reactbin/specs/004-jwt-bearer-auth/data-model.md

Data Model: JWT Bearer Token Authentication

Feature: 004-jwt-bearer-auth | Date: 2026-05-03

---

Database Changes

None. JWTs are stateless bearer tokens. The API validates them by cryptographic signature and embedded expiry claim on each request. No token storage, session table, or blocklist is introduced in Phase 2.

---

Configuration Schema (new env vars)

Four new environment variables are added to api/app/config.py and .env.example.

Variable	Type	Required	Default	Description
JWT_SECRET_KEY	str	Yes	—	HMAC-SHA256 signing secret. Must be a long random string; no default (startup fails if absent).
JWT_EXPIRY_SECONDS	int	No	86400	Token lifetime in seconds (24 h).
OWNER_USERNAME	str	Yes	—	Login username for the single owner account.
OWNER_PASSWORD	str	Yes	—	Login password for the single owner account.

These values are loaded via pydantic-settings (BaseSettings) alongside the existing database and S3 settings. JWT_SECRET_KEY, OWNER_USERNAME, and OWNER_PASSWORD have no defaults and will raise a validation error at startup if absent, providing a clear "misconfigured" failure rather than a silent security hole.

---

Token Structure

A JWT issued by the login endpoint carries the following claims.

Claim	Type	Value
sub	string	"owner" — fixed identifier for the single owner
iat	integer	Unix epoch seconds at time of issuance
exp	integer	iat + JWT_EXPIRY_SECONDS

Algorithm: HS256 (HMAC-SHA256). Secret: JWT_SECRET_KEY setting.

The token is opaque to the client. The Angular SPA stores it in sessionStorage and transmits it as Authorization: Bearer <token> on every request.

---

Module and Interface Changes

api/app/auth/provider.py — updated interface

The get_identity() method gains an authorization parameter — the raw value of the Authorization HTTP header (or None if the header is absent).

AuthProvider (abstract)
  get_identity(authorization: str | None) -> Identity

Identity (dataclass)
  id: str
  anonymous: bool = True

api/app/auth/noop.py — no behavioural change

NoOpAuthProvider.get_identity() continues to return the static anonymous identity regardless of the authorization argument. The signature is updated to match the new interface.

api/app/auth/jwt_provider.py — new module

JWTAuthProvider (AuthProvider)
  __init__(secret_key: str, expiry_seconds: int, owner_username: str, owner_password: str)
  
  get_identity(authorization: str | None) -> Identity
    - Parses "Bearer <token>" from authorization header
    - Decodes and validates the JWT (signature + exp)
    - Returns Identity(id="owner", anonymous=False) on success
    - Raises HTTPException 401 with code "unauthorized" on any failure

  create_token() -> str
    - Mints a new HS256 JWT with sub="owner", iat=now, exp=now+expiry_seconds
    - Returns the encoded token string
  
  verify_credentials(username: str, password: str) -> bool
    - Compares username and password against OWNER_USERNAME / OWNER_PASSWORD
    - Uses secrets.compare_digest to prevent timing attacks
    - Returns True on match, False otherwise

api/app/dependencies.py — new require_auth dependency

require_auth(
  authorization: str | None = Header(None, alias="Authorization"),
  auth: AuthProvider = Depends(get_auth)
) -> Identity
  - Calls auth.get_identity(authorization)
  - Raises HTTPException 401 if identity.anonymous is True
  - Returns the Identity on success

Protected routes inject identity: Identity = Depends(require_auth) and do not need to perform any additional auth checks — the dependency raises before the route body executes if authentication fails.

api/app/routers/auth.py — new router

POST /api/v1/auth/token
  Request body: LoginRequest { username: str, password: str }
  Success (200): TokenResponse { access_token: str, token_type: "bearer", expires_in: int }
  Failure (401): { detail: "Invalid credentials", code: "invalid_credentials" }

---

Angular Module Changes

ui/src/app/auth/auth.service.ts — new service

AuthService
  TOKEN_KEY = 'auth_token'            (sessionStorage key)

  login(username: string, password: string): Observable<void>
    - POST /api/v1/auth/token
    - On success: stores access_token in sessionStorage, emits completion
    - On 401: propagates error for the component to handle

  logout(): void
    - Removes token from sessionStorage

  getToken(): string | null
    - Returns stored token or null

  isAuthenticated(): boolean
    - Returns true if getToken() is non-null

ui/src/app/auth/auth.interceptor.ts — new functional interceptor

Attaches Authorization: Bearer <token> to every outbound HttpRequest if AuthService.getToken() returns a non-null value. Requests without a token are passed through unmodified.

ui/src/app/auth/auth.guard.ts — new route guard

Functional CanActivateFn. If AuthService.isAuthenticated() is false, redirects to /login?returnUrl=<current-url>. Otherwise allows navigation.

ui/src/app/login/login.component.ts — new component

Route: /login

LoginComponent
  Fields: username (required), password (required)
  On submit:
    - Calls AuthService.login()
    - On success: navigates to returnUrl query param, or '/' if absent
    - On 401: displays inline error "Invalid username or password"
    - On other error: displays generic error message
  Shows loading state while request is in flight

ui/src/app/detail/detail.component.ts — updated

Injects AuthService. Hides tag-edit input and delete button when auth.isAuthenticated() is false. Shows them when authenticated. Read-only view (image display, tag chips) is always visible.

ui/src/app/app.routes.ts — updated

/upload route gains canActivate: [authGuard]. /login route is added (unguarded). All other routes are unchanged.

ui/src/app/app.config.ts — updated

provideHttpClient() becomes provideHttpClient(withInterceptors([authInterceptor])).