# Authentication

## Cognito bearer tokens

Production and seahaven-dev expect a Bearer Cognito token verified against the
user pool JWKS and issuer.

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.
Prefer a Cognito **ID token**, which carries email/name by default. An access
token is accepted only when it includes an `email` claim (for example via a
pre-token-generation enrichment).

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.