browser/openspec/changes/harden-platform-auth-and-secret-persistence/proposal.md

Harden Platform Authentication, Authorization, and Secret Persistence

Why

Platform account sessions and Run control sessions currently live only in process memory, so a restart invalidates valid clients and leaves revocation/expiry state implicit. Several management routes also rely on the caller reaching a UI path rather than enforcing an authenticated role or resource-ownership boundary at the API/service boundary. Existing component-key and distribution metadata is not included in the durable file/MySQL snapshot, while secret-bearing values must remain platform-owned and redacted.

What Changes

• Persist hashed platform sessions and Run control session state with explicit issued/expiry/revoked timestamps and safe rotation.
• Require authenticated sessions for sensitive management APIs and enforce platform-admin, server-owner/administrator, and Run-service boundaries in handlers and services.
• Add a signed, timestamped Run request envelope for control/job/log/artifact channel requests where the HTTP boundary can validate a trusted Run session and reject stale/replayed messages.
• Persist existing encrypted component-key and distribution metadata in FileStore/MySQLStore snapshots, plus controlled secret metadata references and presence/fingerprint projections.
• Ensure auth failures are stable 401/403 API errors and the web client clears invalid sessions without rendering token, key, path, socket, or secret literals.
• Add regression coverage for login/reload, expiry/revocation/rotation, signed Run requests, cross-owner/role rejection, replay/clock failures, snapshot recovery, and non-disclosure.

Goals / Non-Goals

Goals:

• Make session and authorization decisions durable and independently enforceable from the UI.
• Keep raw credentials, host paths, direct sockets, and provider keys out of DTOs, logs, snapshots, and browser state.
• Preserve the independent run repository boundary and channel priorities.

Non-Goals:

• A production KMS/vault, encrypted secret-value storage, durable scheduling, process supervision, logs/artifacts backends, dependency installation, self-update, client-manager lifecycle, or production scaling.
• Re-adding Run source code to this repository or claiming the later roadmap is complete.

Impact

• platform/: auth/session domain, repositories, snapshots, signed Run request validation, route authorization, safe secret metadata.
• platform_web/: API error/session handling and safe auth capability projections.
• plugins/: no raw credential or direct channel access; manifest/SDK contracts remain unchanged except for regression fixtures if needed.