# Platform Authentication, Authorization, and Secret Persistence

## ADDED Requirements

### Requirement: Platform sessions are durable and bounded
The platform SHALL persist only hashed bearer-session records with user ownership, issued time, expiry time, revocation time, and rotation generation, and SHALL reject missing, expired, revoked, or disabled-user sessions.

#### Scenario: Session survives restart
- **WHEN** a user logs in, the platform store is closed and reopened, and the same bearer token is presented before expiry
- **THEN** the platform restores the session record and authenticates the user without storing the raw token

#### Scenario: Expired or revoked session is rejected
- **WHEN** an expired or revoked bearer token is presented
- **THEN** the API returns 401 and performs no protected read or write

#### Scenario: Session rotation revokes the old generation
- **WHEN** an authenticated user rotates a session
- **THEN** a new token is issued, the previous generation is revoked durably, and the previous token is rejected

#### Scenario: Browser session token is not script-readable
- **WHEN** a user logs in through the strict production router
- **THEN** the platform sets an HttpOnly SameSite session cookie and omits the raw token from the JSON response

### Requirement: Run requests use a trusted bounded channel
Run control, job, log, and artifact channel requests SHALL validate the current endpoint session and, at the HTTP boundary, a timestamped HMAC signature with a five-minute clock-skew limit and single-use nonce.

#### Scenario: Valid signed request
- **WHEN** a request is signed by the current Run session with an accepted timestamp and unused nonce
- **THEN** the request is processed for that endpoint and the nonce is recorded as used

#### Scenario: Invalid, stale, or replayed request
- **WHEN** the signature is invalid, the timestamp is outside the skew window, or the nonce was already used
- **THEN** the request is rejected with a safe authentication error and no state mutation occurs

### Requirement: Sensitive APIs enforce role and resource ownership
Sensitive user, provider, plugin, server, distribution, job, runtime-binding, audit, and channel metadata APIs SHALL enforce platform-admin, server-owner/administrator, or Run-service identity at the API and service boundaries.

#### Scenario: Cross-owner access
- **WHEN** an authenticated non-owner requests another owner's server binding, job, config, artifact, or action
- **THEN** the platform returns 403 and leaves the resource unchanged

#### Scenario: UI bypass
- **WHEN** a caller invokes a sensitive route directly without the required role or session
- **THEN** the platform rejects the call regardless of UI state or request shape

### Requirement: Core auth and secret metadata are durable and redacted
FileStore and MySQLStore SHALL persist auth sessions, Run session state, encrypted component-key metadata, distributions, and controlled secret references through the repository snapshot contract; raw tokens, keys, credentials, paths, sockets, and provider secret values MUST NOT appear in snapshots, logs, DTOs, or browser responses.

#### Scenario: Snapshot reload preserves safe metadata
- **WHEN** the store is reopened after creating a session, Run identity, component key, or secret reference
- **THEN** safe status/generation/presence metadata remains available and raw values remain absent

#### Scenario: Secret presence projection
- **WHEN** a secret reference is configured
- **THEN** API and web responses expose only presence/configured/secret flags and safe fingerprints, never the reference value or storage location

### Requirement: Web clients handle auth failures safely
The platform web client SHALL treat 401 as a session reset/re-login condition and 403 as a capability/ownership denial, without persisting or rendering raw tokens, credentials, paths, sockets, or secret references.

#### Scenario: API session expires in the console
- **WHEN** an API call returns 401
- **THEN** the client clears the bearer token and exposes a safe re-authentication state

#### Scenario: API authorization is denied
- **WHEN** an API call returns 403
- **THEN** the client reports a safe access-denied error without including secret or infrastructure details

## Deferred Requirements

- Production KMS/HSM/vault encryption and secret-value rotation are deferred.
- Durable scheduling, process supervision, logs/artifacts backends, dependency installation, self-update, client-manager lifecycle, and production scaling are outside this change.