Secrets

This page enumerates the secrets the platform manages, where each one lives, and the constraints that govern them. Per CLAUDE.md Rule 4, inference credentials never leave the local Device. Per CONSTRAINTS.md C7, there is no shared transport credential.

Server-side secrets (HiveCast platform Host)

Session HMAC secret

• File: <host-home>/host.json field auth.sessionSecret.
• Lifetime: long-lived.
• Rotation: edit + restart Host (invalidates all sessions).
• Audience: signs every mx_session and Bus token.
• Constraint: must be ≥ 32 characters.

Google OIDC client secret

• File: host.json field auth.providers.google.clientSecret, or env GOOGLE_CLIENT_SECRET.
• Lifetime: long-lived; rotate from Google Cloud console.
• Audience: required for the OAuth code exchange.
• Constraint: never logged, never sent to the browser.

Principal NATS account seed

• File: <host-home>/state/auth-state.json (under each principal's credentials).
• Lifetime: per-principal; durable.
• Audience: signs every Device's NATS user JWT for that principal.
• Constraint: NEVER leaves the server. Per HIVECAST-DEVICE-ENROLLMENT-SPEC.md and the live proofs.

NATS operator key

• File: NATS server config (outside the Host home).
• Audience: signs the account JWTs.
• Constraint: extreme care required; rotation invalidates every account.

Device-side secrets (user's laptop / workstation / VM)

Device-scoped NATS user JWT + seed

• File: <host-home>/credentials/hivecast-link.json and adjacent nats-creds files.
• Lifetime: 24 hours; rotated by auth.hostLink.credentials.refresh.
• Audience: NATS connection auth from this Device.
• Constraint: device-scoped; revoking this Device does not affect other Devices.

Heartbeat token

• File: <host-home>/credentials/hivecast-link.json field heartbeatToken.
• Lifetime: rotates per credential refresh.
• Audience: bearer token for /_auth/host-link/heartbeat.
• Constraint: HMAC at rest on the platform; plaintext only on the Device.

Inference credentials (OAuth tokens, API keys)

• File: managed by system.factotum.
• Lifetime: per provider.
• Audience: outbound calls to OpenAI, Anthropic, Codex, Ollama, etc.
• Constraint: NEVER leaves the local Device. Per CLAUDE.md Rule 4 and CONSTRAINTS.md C11.

The Factotum-only rule is critical. HiveCast cannot make inference calls on a user's behalf because the user's API tokens are not on HiveCast — they are on the user's Device. The bus routes the request from the user's browser to the user's Device, which makes the call locally.

Local install identity

• File: <host-home>/credentials/hivecast-install.json field installId.
• Lifetime: durable per install.
• Audience: identity correlation; per the spec, durable across reinstalls and rsync.
• Constraint: not a secret — but it is identity-bearing and should not be shared casually.

Environment-borne secrets

Env var	What	Where read
MATRIX_AUTH_SESSION_SECRET	Override host.json session secret	system-auth/src/index.ts:1255
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google OIDC creds	system-auth/src/index.ts:1369-1372
MATRIX_AUTHORITY_ROOT	Override authority root	system-auth/src/index.ts:1258
EXTERNAL_URL	Platform's public URL	system-auth/src/index.ts:1271

The deploy-cloud setup pins these in environment files, not in committed code. Per the auto-memory ledger, deploy-cloud/.env has historically contained the Google OAuth secret + NATS token; this needs to move out of the file checked next to deploy code.

What is NEVER persisted

• The user's Google ID token (used at exchange, then discarded).
• The plaintext Bus token (memory-only on the browser).
• The OAuth code and code_verifier past the exchange (the verifier is in HostAuthStateStore.googleOauthStates[] until take() by the callback, then deleted).
• Inference responses (these are the user's data, not the platform's).

What is logged

The auth ops log via actorLog (per Rule 9 — no console.log). Log lines do not include token values; they include token ids (jti) and outcome (ok/error).

A live log review on the platform Host should never reveal:

• Plaintext session JWTs.
• Plaintext bus tokens.
• Plaintext heartbeat tokens.
• NATS account seeds.

If any of these appear, that is a security bug; file an incident.

Secret rotation guidance

Secret	Trigger	Procedure
Session HMAC	suspected compromise; periodic	edit host.json, restart
Google client secret	provider rotation	edit env, restart
Principal NATS account	suspected per-principal compromise	rotate account JWT, every Device must re-pair
Device user JWT	daily	automatic via mx refresh-credentials
Heartbeat token	with each refresh	automatic

See also

• Authentication — issuance flows.
• Capability tokens — token semantics.
• Audit logs — what is recorded.
• Edge / Device Management / Health — Device-side refresh.

Source: WORKSTREAMS/product-launch/CONSTRAINTS.md (C4-C8, C11, C16). CLAUDE.md (Rule 4). projects/matrix-3/packages/system-auth/src/host-auth.ts for storage layout.