seahaven-ap/packages/api/docs/auth.md

Authentication

Cookie session (live path)

The API is a same-origin BFF. Cognito hosted UI issues tokens. The API stores them in host-only cookies:

• __Host-ap_at access token (HttpOnly)
• __Host-ap_it ID token (HttpOnly)
• __Host-ap_rt refresh token (HttpOnly, path / when host-prefixed)
• __Host-ap_sess session hint (not HttpOnly; display name and email)
• __Host-ap_oauth PKCE state during login

Local NODE_ENV development or test drops the __Host- prefix and the Secure flag so http://127.0.0.1:8787 works (ap_at, ap_it, ap_rt).

Routes:

• GET /api/auth/login
• GET /api/auth/callback
• POST /api/auth/refresh
• POST /api/auth/logout
• GET /api/me reads the ID cookie, verifies it, and upserts users by sub

CloudFront sends X-Origin-Verify on /api/*. GET /api/health skips that check so the ALB probe succeeds. Mutating /api/* requests also require a matching Origin.

Cognito tokens

Audience check:

• ID tokens (token_use=id): aud must equal COGNITO_AUDIENCE (app client id).
• Access tokens (token_use=access): client_id must equal COGNITO_AUDIENCE.

Identity claims (sub, email, and name or cognito:username) are required. GET /api/me uses the ID cookie.

Optional role claim mapping:

• custom:role or role → role (admin, ap_processor, approver, viewer)
• Missing role defaults to viewer

Users are upserted by sub only. An email already linked to a different sub returns HTTP 409 and does not rebind the account.

Local DEV_AUTH_BYPASS

For local development only, set DEV_AUTH_BYPASS=true. The middleware uses DEV_AUTH_SUB, DEV_AUTH_EMAIL, DEV_AUTH_NAME, and DEV_AUTH_ROLE and skips JWT verification.

Align DEV_AUTH_SUB with the seeded Cognito subject (default seed-sub-admin) so local auth updates the seed user instead of conflicting on email.

DEV_AUTH_BYPASS is allowed only when NODE_ENV is development or test. Any other value (including production, staging, and preview) rejects startup.