agentic-mobile-control/openspec/changes/cloud-console-user-authentication/specs/cloud-user-authentication/spec.md

ADDED Requirements

Requirement: Persistent user accounts protect password material

The system SHALL persist uniquely identifiable human user accounts with a case-insensitive unique username, display name, fixed role, enabled state, forced-password-change state, and security timestamps, and SHALL store passwords only as salted Argon2id hashes that are never returned or logged.

Scenario: Administrator creates a user

• WHEN an authorized administrator creates a user with a username, display name, role, and valid initial password
• THEN the system stores the normalized unique identity and password hash, returns only non-secret account fields, and marks the account to change its initial password

Scenario: Username differs only by case

• WHEN an administrator attempts to create a username that differs from an existing username only by normalization or letter case
• THEN the system rejects the duplicate without changing either account

Scenario: Stored password needs stronger parameters

• WHEN a user successfully signs in and the password hasher reports that the stored Argon2id parameters are outdated
• THEN the system replaces the stored hash using current parameters without retaining or logging the submitted password

Requirement: Fixed roles map to operation scopes

The system SHALL map viewer, operator, and admin users to the existing Cloud API scopes so resource handlers authorize user sessions and bearer principals through the same Principal scope checks.

Scenario: Viewer accesses read dashboards

• WHEN a logged-in viewer calls task-read, pool-read, or plugin-read operations
• THEN the request is authorized, while task submission, plugin administration, and user administration remain forbidden

Scenario: Operator submits a task

• WHEN a logged-in operator submits a task
• THEN the request is authorized in addition to all viewer read operations, while plugin and user administration remain forbidden

Scenario: Administrator manages users

• WHEN a logged-in admin invokes an operation requiring users:admin or another Cloud API scope
• THEN the request is authorized subject to the operation's normal validation

Requirement: Password login creates a revocable server-side session

The system SHALL authenticate enabled users with username and password, SHALL create an opaque expiring session whose secret is stored only as a digest, and SHALL deliver the session secret in an HttpOnly, SameSite cookie that is Secure in production.

Scenario: Valid credentials create a session

• WHEN an enabled user submits a correct username and password within throttle limits
• THEN the system records a revocable session, returns the non-secret current-user representation, and sets the session and CSRF cookies with their required security attributes

Scenario: Credentials are not valid

• WHEN the username is unknown, disabled, temporarily throttled, or paired with a wrong password
• THEN the system returns the same generic authentication failure without revealing which condition occurred and without setting a session cookie

Scenario: Session is expired or revoked

• WHEN a request presents a session whose idle or absolute expiry has passed, whose row is revoked, or whose authentication version no longer matches the user
• THEN authentication fails and the system clears the browser session cookies

Requirement: User session lifecycle is controllable

The system SHALL let a logged-in user inspect the current account, sign out, and change their own password, and SHALL revoke sessions when a password, role, enabled state, or authentication version changes.

Scenario: User signs out

• WHEN a logged-in user signs out with valid CSRF proof
• THEN the current session is revoked server-side and both browser cookies are cleared

Scenario: User changes password

• WHEN a logged-in user proves the current password and supplies a valid new password
• THEN the password hash and authentication version are updated, other sessions are revoked, and the user must continue only with a newly established valid session

Scenario: Temporary password requires replacement

• WHEN a user signs in while must_change_password is set
• THEN the session may call current-user, password-change, and logout operations but cannot access other Cloud API resources until the password is changed

Requirement: Cookie-authenticated writes require CSRF proof

The system SHALL require a session-bound CSRF value on unsafe HTTP methods authenticated by a user cookie, while requests authenticated by an explicit bearer header SHALL remain exempt from cookie CSRF validation.

Scenario: Valid cookie session submits a write

• WHEN a cookie-authenticated request uses an unsafe method and its X-CSRF-Token header matches the CSRF cookie and session-bound digest
• THEN the request proceeds to normal scope and payload validation

Scenario: Cookie request omits CSRF proof

• WHEN a cookie-authenticated request uses an unsafe method without matching CSRF proof
• THEN the system rejects it before executing the operation

Scenario: Bearer client submits a write

• WHEN an authorized client sends an unsafe request with an Authorization: Bearer credential and no session cookie is used for authentication
• THEN the request is evaluated by existing bearer scope checks without requiring a CSRF header

Requirement: Failed login attempts are throttled without permanent lockout

The system SHALL enforce a bounded failed-login window and temporary block by normalized username and trusted client-address bucket, SHALL use generic client responses, and SHALL clear applicable failure state after successful authentication.

Scenario: Repeated failures exceed the limit

• WHEN repeated failed logins for the same username and client bucket exceed the configured limit within the failure window
• THEN further attempts are temporarily blocked, audited, and answered with the generic authentication failure

Scenario: Temporary block expires

• WHEN the configured block duration passes
• THEN the account can attempt authentication again without administrator intervention

Scenario: Unknown username is submitted

• WHEN a login names no stored user
• THEN the system performs timing-resistant dummy password verification and applies the same throttle and response behavior as a wrong password

Requirement: Administrators control user lifecycle

The system SHALL expose users:admin-protected operations to list and create users, change display name/role/enabled state, reset passwords, and revoke sessions, and SHALL prevent API actions that remove the last enabled administrator.

Scenario: Administrator disables an operator

• WHEN an administrator disables an enabled operator
• THEN the account can no longer authenticate and all of its active sessions are revoked

Scenario: Administrator resets a password

• WHEN an administrator assigns a valid temporary password to another user
• THEN existing sessions are revoked and the account is required to change that password after its next login

Scenario: Non-admin attempts user management

• WHEN a viewer, operator, anonymous caller, or Host principal calls a user-administration operation
• THEN the system rejects the request without exposing password or session state

Scenario: Last administrator would be removed

• WHEN an API request would disable or demote the only enabled administrator
• THEN the system rejects the request and preserves an enabled administrator

Requirement: Deployment administrators can bootstrap and recover accounts safely

The system SHALL provide an administration CLI that checks the current database schema, reads new passwords interactively without echo, and can create, reset, enable, or revoke sessions for user accounts without accepting passwords in command arguments.

Scenario: First administrator is created in Compose

• WHEN a deployment administrator runs the user-create command inside the Cloud API container and enters a valid password twice at the interactive prompts
• THEN an enabled administrator account is created without placing the password in process arguments, Compose configuration, or command output

Scenario: Interactive password confirmation differs

• WHEN the two interactive password entries do not match
• THEN the CLI exits unsuccessfully without changing the account

Scenario: Database schema is not current

• WHEN a user administration CLI command runs against a database missing the required migration
• THEN it fails with a migration diagnostic rather than creating partial schema state

Requirement: Authentication security events are auditable without secrets

The system SHALL record durable structured audit events for authentication and user-administration outcomes with actor, target, action, timestamp, outcome, and correlation context, and SHALL exclude submitted passwords, hashes, raw cookies, CSRF values, and bearer credentials.

Scenario: Login fails

• WHEN a login attempt fails or is throttled
• THEN the system records a safe failure category and correlation context without recording the submitted password or confirming whether the username exists

Scenario: Administrator changes a role

• WHEN an administrator changes a user's role
• THEN the system records the actor, target user id, old/new role metadata, outcome, and associated session revocation without any credential material