adam/seahaven-ap
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/seahaven-ap.git synced 2026-09-30 10:23:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
seahaven-ap/packages/api/docs/auth.md
Adam Moussa 864531b51e
feat(api): portal contract, cookie auth, and domain stubs (AP-51) (#64) 
* feat(api): serve portal-shaped health and error envelope

Move liveness to GET /api/health { stage, sha } with a Node 24 image on 8080 so ALB probes and deploy verify do not need auth or a database ping.

* feat(api): switch live auth to host cookie BFF

Replace Bearer as the documented session path with Cognito hosted UI plus __Host-ap_* cookies so the SPA can call /api with credentials include.

* feat(web): add unused cookie SPA API client

Land a credentials-include fetch helper and hand-synced health/me types without wiring pages or domain hooks, so mocks stay the default data path.

* feat(api): add master-data OpenAPI and Hono stubs

* feat(api): add invoice, line, and document stubs

* feat(api): add approval policy, inbox, and activity stubs

* test(web): fix SPA client fetch mock types

* test(web): cast fetch mock call args for tsc

* fix(api): do not default DEV_AUTH_BYPASS outside local migrate

* fix(api): replace invoice lines in a single transaction

* fix(api): create invoices and lines in one transaction

* fix(api): inline GIT_SHA from the image build arg

* fix(api): stop PATCH from skipping the approval workflow

* fix(api): address review feedback

* fix(ci): format upsert-user test

* fix(api): document only the auth statuses the routes return

* fix(api): drop health 400 responses the routes never return
2026-09-25 22:43:44 +00:00

2 KiB
Raw Blame History

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.