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

Why

The Cloud Console currently asks every operator to paste a long-lived, pre-shared bearer token. That is awkward for routine access and provides no per-user password lifecycle, role assignment, session revocation, or reliable attribution when several people operate the control plane.

What Changes

• Add a persistent Cloud user directory with unique usernames, display names, password hashes, active/disabled state, fixed roles (viewer, operator, and admin), and security timestamps.
• Add username/password sign-in, sign-out, current-user, and password-change endpoints backed by revocable, expiring server-side sessions delivered through secure HttpOnly cookies.
• Map user roles to the Cloud API's existing operation scopes so browser users and configured bearer-token principals pass through the same authorization checks.
• Add admin-only user management endpoints and Console views for listing users, creating accounts, changing roles/status, resetting passwords, and revoking sessions.
• Add an interactive administration CLI for securely creating the first administrator and recovering access without embedding a bootstrap password in an image, Compose file, or shell argument.
• Replace the Console's default token-entry gate with a username/password login screen and authenticated account menu; retain an explicit bearer-token option for existing operators and break-glass access.
• Add login throttling, generic authentication failures, password/session invalidation rules, CSRF protection for cookie-authenticated writes, and audit events that never record passwords, session secrets, or bearer tokens.
• Preserve configured bearer-token authentication for CloudClient, Host Agents, enrollment, automation, and backward compatibility.
• Explicitly out of scope: public self-registration, email delivery or forgot-password links, OIDC/SAML/LDAP, multi-factor authentication, organization/multi-tenant membership, and customizable role definitions.

Capabilities

New Capabilities

• cloud-user-authentication: Persistent users, password verification, role-to-scope authorization, secure session lifecycle, administrator account management, bootstrap/recovery tooling, throttling, and security audit behavior.

Modified Capabilities

• platform-sdk: Add versioned user-authentication and user-administration routes, and allow a valid browser session principal alongside the existing bearer-token principals without weakening operation-specific scope checks.
• cloud-console-ui: Make username/password login the primary operator flow, add account/session handling and an admin-only user-management view, while keeping the existing token flow as an explicit compatibility option. The base capability remains in the active cloud-console change, so this follow-up supplies additive delta requirements until that change is archived.

Impact

• Database: a new Alembic revision adds user, session, login-attempt/audit state with equivalent SQLite and PostgreSQL behavior; rollback invalidates browser sessions and removes user records only when the explicit downgrade is run.
• Backend: cloud/auth.py, repository/database models, SQLAlchemy repository code, Cloud API composition, /v1/auth/* and /v1/users/* models/routes, and production configuration gain user-session support while retaining current bearer providers.
• Frontend: cloud-console/ replaces its default token screen with account login, sends credentialed requests plus CSRF protection, exposes logout/password change, and adds admin user management.
• Dependencies: add a maintained Argon2id password-hashing dependency; continue storing only digests for bearer/session credentials.
• Operations/docs: document HTTPS and secure-cookie requirements, initial-admin creation via docker compose exec, role semantics, user recovery, session revocation, and migration/rollback procedures.