mirror of
https://github.com/Sea-Haven-Industries/seahaven-ap.git
synced 2026-10-01 20:13:22 +00:00
Adam Moussa
bbfa6e4a3c
Replace Bearer as the documented session path with Cognito hosted UI plus __Host-ap_* cookies so the SPA can call /api with credentials include.
58 lines
2 KiB
Markdown
58 lines
2 KiB
Markdown
# 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.
|