browser/platform/protocol/auth-contracts.md

Authentication and Service Identity Contracts

Platform bearer sessions

• Login and first-user registration issue a random bearer token with an eight-hour expiry.
• Strict production HTTP routes deliver the session through an HttpOnly, SameSite=Strict cookie and omit it from JSON. X-Auth-Token-Response: bearer is an explicit CLI compatibility mode.
• Durable stores keep only AuthSessionRecord.tokenHash, owner, generation, status, and lifecycle timestamps.
• Logout and rotation set status=revoked and revokedAt; rotation issues a distinct generation.
• Missing, unknown, expired, revoked, or disabled-user sessions return a safe 401 unauthorized error.

Authorization roles

• platform-admin: user/provider/plugin installation and state, Run endpoint administration, platform metrics, and global internal resource creation.
• server owner: server membership, runtime binding changes, destructive/archive operations, and all visible server actions.
• server administrator: non-owner operational access to assigned server resources, but no owner-only membership or secret/key rotation.
• Run service: control/job/log/artifact channels for its current endpoint session; it cannot use browser bearer authority.

Job, log, artifact, runtime-binding, distribution, and plugin-bridge services resolve the target server and repeat ownership checks independently from the HTTP router.

Run signed envelope

Component-authenticated Run hello responses advertise signed-envelope.v1.required. Subsequent HTTP channel calls carry X-Run-Endpoint, X-Run-Timestamp (Unix seconds), X-Run-Nonce, and X-Run-Signature (hex HMAC-SHA256).

The canonical payload is METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(BODY). The current Run session token is the HMAC key. The platform rejects endpoint mismatch, invalid signatures, timestamps outside a five-minute window, expired/revoked sessions, and replayed nonces. Legacy non-component local test sessions remain an explicit compatibility path and advertise the envelope as optional.

Secret boundary

Platform snapshots may contain password verifiers, bearer/Run token hashes, encrypted component-key ciphertext, fingerprints, generations, and scoped secret:///vault:// references. They never contain raw bearer tokens, raw component keys, provider key values, host paths, or direct sockets. Browser DTOs expose secret presence/configured flags only.

Component-key ciphertext uses an injectable AES-GCM envelope derived from PLATFORM_SECRET_ENVELOPE_KEY; the built-in key is a disposable-development fallback only. This boundary is not a production KMS/vault. External key wrapping, KMS/HSM integration, multi-node replay coordination, envelope-key migration, and secret-value rotation remain deferred risks.