Security: Secrets (admin view)

For the secrets inventory, see Security: Secrets. This page is the admin's perspective: how to manage, rotate, and audit secrets today, and what the target UI would offer.

Today's tooling

There is no admin UI for secret management. Operators:

• Hand-edit host.json for auth.sessionSecret, auth.providers.google.*.
• Use auth.hostLink.credentials.refresh for per-Device JWT rotation (this is automated; admins rarely intervene).
• Hand-edit <host-home>/state/auth-state.json for principal NATS account changes (very rare; risky).

Target Secrets dashboard

A secrets dashboard would surface:

• Health: which secrets are set, which need rotation by policy.
• Metadata: when each secret was last rotated, who rotated it.
• Actions: rotate (with confirmation), reveal (with audit), retire (rare).
• Per-secret access policy: who can view, who can rotate.
• Integration: secret-store backend (HashiCorp Vault, AWS KMS, etc. — target).

Categories of secrets to manage

Platform secrets

• Session HMAC secret.
• Google OIDC client secret.
• Future: GitHub OIDC, enterprise SSO secrets.
• NATS operator key.
• TLS certs (managed by Caddy today, not the platform).

Per-principal secrets

• Principal NATS account seed (one per principal).
• Inference credentials (Factotum-managed, never on the platform).
• Future: API tokens for service principals.

Per-Device secrets

• Heartbeat tokens (rotated automatically with credential refresh).
• NATS user JWTs (24h TTL, refresh daily).
• Local install identity (not really a secret, but identity-bearing).

Rotation cadence guidance

Secret	Recommended cadence
Session HMAC	quarterly (manually accept all-users-relogin)
Google OIDC client secret	when Google rotates, or yearly
Principal NATS account seed	only on suspected compromise
Device user JWT	daily (automatic)
Heartbeat token	per credential refresh (automatic)

Rotation procedure: session HMAC

# 1. Generate
NEW_SECRET=$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')

# 2. Update host.json (CARE: invalidates ALL sessions)
sudo jq ".auth.sessionSecret = \"$NEW_SECRET\"" \
  <host-home>/host.json > /tmp/host.json.new
sudo mv /tmp/host.json.new <host-home>/host.json

# 3. Restart
hivecast stop && hivecast start

# 4. Communicate to users that re-login is required.

Rotation procedure: principal NATS account

# Today this is direct state mutation. CARE.
# 1. Capture state snapshot.
sudo cp <host-home>/state/auth-state.json /tmp/auth-state-pre-rotate.json

# 2. Identify the principal's account credential entry.
sudo jq '.credentials | map(select(.principalId == "p_xxx" and .credentialType == "nats-account"))' \
  <host-home>/state/auth-state.json

# 3. Generate new account seed (using nats-auth helpers).
# 4. Replace credentials[].value with the new seed.
# 5. Trigger re-pair for every Device under this principal.

This is operationally painful. Target state: a system.factotum-coordinated rotation op.

Audit of secret access

Today: actorLog logs the fact that a credential op happened, not the secret value. Fine in principle; the gap is the lack of structured audit (per Security: Audit trails).

Backup considerations

Secrets are in:

• host.json (HMAC secret, OIDC client secret).
• auth-state.json credentials[] (NATS account seeds).
• <host-home>/credentials/ (Device-side material).

Backups must be encrypted at rest. A clear-text auth-state.json backup containing principal NATS account seeds is a direct compromise vector. Use gpg, age, or a secret-managed encryption key.

Target: Vault integration

A target secret-store integration would:

• Store secrets out-of-process (HashiCorp Vault, AWS KMS, etc.).
• Retrieve at startup; never persist locally.
• Audit retrieval at the secret-store layer.
• Support automatic rotation with secret-store hooks.

The current implementation hard-couples secret storage to the JSON state files.

See also

• Security: Secrets — full inventory.
• Security: Authorization — who can manage secrets.
• Operations: Resolve incident — emergency rotation.

Source: projects/matrix-3/packages/system-factotum/ for the credentials authority pattern. projects/matrix-3/packages/system-auth/src/host-auth.ts for HostCredentialStore.