31 lines
2.7 KiB
Markdown
31 lines
2.7 KiB
Markdown
# 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.
|