Julien Gautier
77b2f73172
Third step of ADR-0009 wiring. Adds the first OIDC route:
`GET /api/auth/login` 302s to Entra's authorize endpoint with a
freshly-generated state + PKCE challenge, and stashes the matching
`{state, codeVerifier}` payload in a short-lived signed cookie so
the next-PR callback can verify the round-trip.
What lands:
- `cookie-parser` + `@types/express` added as deps. main.ts mounts
the cookie parser middleware with the `SESSION_SECRET` signing
key — signed cookies become available via `req.signedCookies` for
the upcoming callback.
- `.env.example` promotes `SESSION_SECRET` from a future-vars
comment into an active variable, with a one-liner showing how to
generate a 32-byte base64url value.
- `apps/portal-bff/src/config/check-session-secret.ts` — same family
of boot-time guard as `check-database-url.ts` /
`check-entra-config.ts`: refuses to start if `SESSION_SECRET` is
unset, still the .env.example placeholder, or decodes below 32
bytes of entropy.
- `apps/portal-bff/src/auth/auth.service.ts` —
`AuthService.beginAuthCodeFlow()` uses MSAL Node's `CryptoProvider`
for canonical PKCE verifier / challenge generation and state
nonce (fresh GUID per call), calls `msal.getAuthCodeUrl()` with
the configured redirect URI + OIDC scopes
(`openid profile email` — no `offline_access`; sessions are
short-lived and re-auth via Entra rather than refresh-token
shenanigans, per ADR-0010), and returns the URL + pre-auth
payload to the controller.
- `apps/portal-bff/src/auth/auth.cookie.ts` — pre-auth cookie name
(`portal_pre_auth`), 5-minute TTL, and shared `CookieOptions`:
`signed: true`, `httpOnly: true`, `sameSite: 'lax'` (allows
Entra's cross-site top-level redirect back), `secure` toggled by
`NODE_ENV`. The `__Host-` prefix waits for the prod TLS hardening
ADR.
- `apps/portal-bff/src/auth/auth.controller.ts` —
`@Controller('auth') GET login`: writes the cookie via Express
`res.cookie()` (using `@Res()`) then 302s to the auth URL. Thin
shell around `AuthService`.
- `AuthModule` registers the controller + service alongside the
existing `ENTRA_CONFIG` and `MSAL_CLIENT` providers.
Verification:
- `nx run-many -t lint test build --projects=portal-bff` — green.
- 39/39 specs (was 30; +9 across the new validator spec, service
spec, and controller spec).
- The service spec mocks MSAL's `getAuthCodeUrl` and asserts the
redirect URI / scopes / S256 method, the state-verifier identity
between the cookie payload and what's sent to Entra, and the
fresh-per-call replay protection.
- The controller spec asserts the cookie name + options + payload
serialization and the 302 redirect.
What this PR explicitly does NOT do:
- The callback. `GET /auth/callback` reads the cookie, exchanges
the code for tokens via `acquireTokenByCode`, validates the ID
token, and (next PR after) creates a session. If you click
`/auth/login` today, you'll round-trip through Entra and land on
a 404 — by design until the callback ships.
- Session persistence (waits on ADR-0010 Redis wiring).
- Logout, CSRF protection, route guards.
Documentation index
This is the entry point to all project documentation. It is maintained automatically: any addition, rename, or removal of a .md file under docs/ must be reflected here in the same change.
Conventions
- Documentation is written in English.
- One topic per file. Group related files into a folder when there are three or more.
- Cross-reference with relative links so they keep working in GitHub, IDEs, and exported sites.
- For architectural decisions, do not add them here — they belong in decisions/ as MADR 4.0.0 ADRs.
Sections
Daily development
- development.md — repo layout, prerequisites, initial setup, daily commands, observability dev-loop (Jaeger UI, log ↔ trace correlation), dependency updates (Renovate), conventional commit cycle. Day-to-day reference for working on the project.
Architecture
- architecture.md — cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline. Single-decision diagrams (auth sequence, ERD, etc.) live inline in their ADR.
Onboarding & environment
Setup guides for new contributors:
- setup/01-wsl-terminal-setup.md — modern WSL terminal (Zsh + Powerlevel10k + CLI tools)
- setup/02-dev-web-stack.md — Node via nvm, pnpm via corepack, Docker
- setup/03-angular-nx-monorepo.md — Angular + Nx monorepo bootstrap
Operations & runbooks
Empty — to be populated when we deploy.
Security, performance, accessibility
Empty — placeholders to be filled with rationale docs alongside their corresponding ADRs.