client/specs/features/002-authentication.md

Spec 002: Authentication (Forest-Server Frontend)

Status: Phase 2 Complete (20 tests passing)

Overview

Forage is a server-side rendered frontend for forest-server. All user management (register, login, sessions, tokens) is handled by forest-server's UsersService via gRPC. Forage stores access/refresh tokens in HTTP-only cookies and proxies auth operations to the forest-server backend.

Architecture

Browser <--HTML/cookies--> forage-server (axum) <--gRPC--> forest-server (UsersService)

• No local user database in forage
• forest-server owns all auth state (users, sessions, passwords)
• forage-server stores access_token + refresh_token in HTTP-only cookies
• forage-server has a gRPC client to forest-server's UsersService

Behavioral Contract

gRPC Client (forage-core)

A typed client wrapping forest-server's UsersService:

• register(username, email, password) -> Result<AuthTokens>
• login(identifier, password) -> Result<AuthTokens>
• refresh_token(refresh_token) -> Result<AuthTokens>
• logout(refresh_token) -> Result<()>
• get_user(access_token) -> Result<User>
• list_personal_access_tokens(access_token, user_id) -> Result<Vec<Token>>
• create_personal_access_token(access_token, user_id, name, scopes, expires) -> Result<(Token, raw_key)>
• delete_personal_access_token(access_token, token_id) -> Result<()>

Cookie Management

• forage_access cookie: access_token, HttpOnly, Secure, SameSite=Lax, Path=/
• forage_refresh cookie: refresh_token, HttpOnly, Secure, SameSite=Lax, Path=/
• On every authenticated request: extract access_token from cookie
• If access_token expired but refresh_token valid: auto-refresh, set new cookies
• If both expired: redirect to /login

Routes

Public Pages

• GET /signup -> signup form (200), redirect to /dashboard if authenticated
• POST /signup -> call Register RPC, set cookies, redirect to /dashboard (302)
• GET /login -> login form (200), redirect to /dashboard if authenticated
• POST /login -> call Login RPC, set cookies, redirect to /dashboard (302)
• POST /logout -> call Logout RPC, clear cookies, redirect to / (302)

Authenticated Pages

• GET /dashboard -> home page showing user info + orgs (200), or redirect to /login
• GET /settings/tokens -> list PATs (200)
• POST /settings/tokens -> create PAT, show raw key once (200)
• POST /settings/tokens/:id/delete -> delete PAT, redirect to /settings/tokens (302)

Error Handling

• gRPC errors mapped to user-friendly messages in form re-renders
• Invalid credentials: "Invalid username/email or password" (no enumeration)
• Duplicate email/username on register: "Already registered"
• Network error to forest-server: 502 Bad Gateway page

Edge Cases

• Forest-server unreachable: show error page, don't crash
• Expired access token with valid refresh: auto-refresh transparently
• Both tokens expired: redirect to login, clear cookies
• Malformed cookie values: treat as unauthenticated
• Concurrent requests during token refresh: only refresh once

Purity Boundary

Pure Core (forage-core)

• ForestClient trait (mockable for tests)
• Token cookie helpers (build Set-Cookie headers, parse cookies)
• Form validation (email format, password length)

Effectful Shell (forage-server)

• Actual gRPC calls to forest-server
• HTTP cookie read/write
• Route handlers and template rendering
• Auth middleware (extractor)

Test Strategy

Unit Tests (forage-core)

• Cookie header building: correct flags, encoding
• Form validation: email format, password length
• Token expiry detection

Integration Tests (forage-server)

• All routes render correct templates (using mock ForestClient)
• POST /signup calls register, sets cookies on success
• POST /login calls login, sets cookies on success
• GET /dashboard without cookies -> redirect to /login
• GET /dashboard with valid token -> 200 with user content
• POST /logout clears cookies
• Error paths: bad credentials, server down

The mock ForestClient allows testing all UI flows without a running forest-server.