browser/openspec/changes/fix-platform-auth-session-api/specs/platform-auth-session/spec.md

ADDED Requirements

Requirement: Platform authentication sessions are implemented

The platform SHALL expose login, registration, logout, and current-user routes backed by platform-owned user records and in-memory session tokens.

Scenario: Active user logs in

• WHEN a client posts a valid account and password to POST /api/v1/auth/login
• THEN the platform MUST return 200 with an authenticated AuthSessionResponse and a session token

Scenario: Pending user cannot log in

• WHEN a pending user submits valid credentials
• THEN the platform MUST reject the login with 403 and MUST NOT issue a session token

Scenario: Current user is requested

• WHEN a client sends GET /api/v1/users/current with a valid bearer session token
• THEN the platform MUST return the bounded current user DTO without password material

Scenario: Session logs out

• WHEN a client posts to POST /api/v1/auth/logout with a valid bearer token
• THEN the platform MUST invalidate that session token

Requirement: Registration is low privilege by default

Public registration SHALL create pending users with server scope and SHALL NOT grant platform administrator privileges.

Scenario: Visitor registers

• WHEN a visitor submits display name, email, and password to POST /api/v1/auth/register
• THEN the platform MUST create a pending user with a non-platform-admin role and return status=pending

Requirement: User management updates are supported

The platform SHALL support controlled user updates through PUT /api/v1/users/{id} using named DTOs and service validation.

Scenario: User status is updated

• WHEN a platform client sends a valid status update for an existing user
• THEN the platform MUST persist and return the updated user DTO

Requirement: Current user preferences are supported

The platform SHALL allow an authenticated current user to update bounded profile and theme preference fields.

Scenario: Current user profile is updated

• WHEN a client sends PUT /api/v1/users/current/profile with a valid bearer session token
• THEN the platform MUST persist the bounded profile fields and return the updated current user DTO

Scenario: Current user theme is updated

• WHEN a client sends PUT /api/v1/users/current/theme with a valid bearer session token
• THEN the platform MUST persist the theme preference and return a UserThemePreferenceResponse

Requirement: Frontend fallback cannot silently grant platform admin

The frontend SHALL NOT persist a local platform administrator user as a fallback authentication path.

Scenario: Auth API is unavailable

• WHEN the auth API is unavailable and local fallback is not explicitly enabled
• THEN the frontend MUST keep the user on the authentication screen and MUST NOT enter the console as platform administrator

Scenario: Development fallback is enabled

• WHEN local fallback is explicitly enabled
• THEN the fallback user MUST have server-scoped access only and MUST NOT expose platform administrator navigation