NATS Credentials

This directory holds .creds files that are fossil-ignored and must never be committed to the repository. These are sensitive authentication credentials.

Credential Structure

Credentials are organized per repository per user role:

• edgesync-admin.creds — Admin user for the edgesync account
• edgesync-bridge.creds — Bridge user for the edgesync account (restricted publish/subscribe)
• go-libfossil-admin.creds — Admin user for the go-libfossil account
• go-libfossil-bridge.creds — Bridge user for the go-libfossil account (restricted publish/subscribe)
• leaf-*.creds — Leaf node users (added per-hostname as needed)

Full Regeneration Sequence

Run this entire sequence to rebuild the credential tree from scratch:

# 1. Add operator (only if nsc store is empty)
nsc add operator --name fossil-sync
nsc edit operator --account-jwt-server-url tls://localhost:4222

# 2. Add accounts
nsc add account --name edgesync
nsc add account --name go-libfossil

# 3. Add users
nsc add user --account edgesync     --name admin --allow-pub '>' --allow-sub '>'
nsc add user --account go-libfossil --name admin --allow-pub '>' --allow-sub '>'

nsc add user --account edgesync \
  --name bridge \
  --allow-pub  'fossil.edgesync.>' \
  --allow-sub  'fossil.edgesync.>'

nsc add user --account go-libfossil \
  --name bridge \
  --allow-pub  'fossil.go-libfossil.>' \
  --allow-sub  'fossil.go-libfossil.>'

# 4. Generate .creds files into this directory
nsc generate creds --account edgesync     --name bridge > edgesync-bridge.creds
nsc generate creds --account go-libfossil --name bridge > go-libfossil-bridge.creds
nsc generate creds --account edgesync     --name admin  > edgesync-admin.creds
nsc generate creds --account go-libfossil --name admin  > go-libfossil-admin.creds

# 5. Re-extract operator JWT
OPERATOR_JWT=$(nsc generate config --nats-resolver 2>/dev/null \
  | grep '^operator:' | awk '{print $2}')
echo "OPERATOR_JWT=${OPERATOR_JWT}" > /etc/nats/operator.env
chmod 0600 /etc/nats/operator.env

# 6. Push JWTs to running server
nsc push --all --server tls://localhost:4222 --tlsskipverify

Adding a New Leaf Node

To add a new leaf node (e.g., a developer laptop or additional server):

PROJECT=edgesync   # or go-libfossil
HOSTNAME=m4-macbook

nsc add user --account "$PROJECT" \
  --name "leaf-${HOSTNAME}" \
  --allow-pub  "fossil.${PROJECT}.igot,fossil.${PROJECT}.file,fossil.${PROJECT}.delta" \
  --allow-sub  "fossil.${PROJECT}.gimme,fossil.${PROJECT}.file,fossil.${PROJECT}.meta,fossil.${PROJECT}.events"

nsc generate creds --account "$PROJECT" --name "leaf-${HOSTNAME}" > "leaf-${HOSTNAME}.creds"
nsc push --all --server tls://localhost:4222 --tlsskipverify

# Transfer to leaf node over Tailscale
scp "leaf-${HOSTNAME}.creds" "${HOSTNAME}:/path/to/agent/creds/"

Security Notes

• These .creds files are in .fossil-ignore — never commit them
• Store them securely; they grant full access to NATS subjects they're authorized for
• Rotate credentials periodically by regenerating and re-pushing JWTs
• Keep the operator JWT in /etc/nats/operator.env on the server only