Julien Gautier
7992a5ba14
First step of ADR-0009 wiring. Captures the Entra app-registration
env vars in the boot pipeline so subsequent PRs can plug
`@azure/msal-node` straight onto a typed, already-validated config
without re-reading process.env. No MSAL client, no OIDC routes, no
session integration yet — those land in follow-up PRs.
What lands:
- `.env.example` promotes the Entra block from its previous "Future
env vars" comment stub to an active configuration section. Six
keys: `ENTRA_INSTANCE_URL`, `ENTRA_TENANT_ID`, `ENTRA_CLIENT_ID`,
`ENTRA_CLIENT_SECRET`, `ENTRA_REDIRECT_URI`,
`ENTRA_POST_LOGOUT_REDIRECT_URI`. UUID + URL placeholders so the
spec test for the "still-the-placeholder" guard has a real target.
Multi-tenant `ENTRA_ACCEPTED_TENANT_IDS` stays in the future-vars
comment until External ID activation lands.
- `apps/portal-bff/src/config/check-entra-config.ts` — boot
validator mirroring `check-database-url.ts`. Asserts every required
key is present, validates the instance URL is `https://` and ends
with `/`, the tenant + client IDs are UUIDs, none of them are the
literal .env.example placeholder, and the two redirect URIs are
parseable URLs. Returns a typed `EntraConfig` object with a
pre-computed `authority` field (`${instanceUrl}${tenantId}`) so
the MSAL factory in the next PR does not re-derive it.
- `check-entra-config.spec.ts` — covers the happy path plus eight
failure modes (missing keys, non-https instance, missing trailing
slash, non-UUID tenant, placeholder UUID, placeholder secret,
invalid redirect URI, http redirect for local dev).
- `apps/portal-bff/src/auth/auth.module.ts` — `AuthModule` whose
v1 surface is a single provider: the parsed `EntraConfig` keyed by
the `ENTRA_CONFIG` injection token. Factory delegates to
`assertEntraConfig()`. Module is non-global so consumers state
intent by importing it.
- `apps/portal-bff/src/auth/entra-config.token.ts` —
`ENTRA_CONFIG` string token + `EntraConfig` type re-export. The
pattern subsequent modules will use:
`@Inject(ENTRA_CONFIG) private readonly entra: EntraConfig`.
- `auth.module.spec.ts` — verifies the provider resolves the typed
config, and that compilation fails when an env var is missing
(boot-failure behaviour is preserved across the DI boundary).
- `main.ts` calls `assertEntraConfig()` alongside
`assertDatabaseUrl()` so misconfiguration fails fast at boot
rather than mid-request (per ADR-0018 §"BFF env-var loading").
- `AppModule` imports `AuthModule`.
Verification: 29 / 29 specs (was 20; +9 from the new entra-config
spec + auth.module spec), lint clean, webpack build green.
Naming: chose `ENTRA_*` rather than `AZURE_AD_*` to align with ADR
text (Microsoft Entra ID, post-2023 rebrand). The values you copy
from the Entra app-registration UI go into `apps/portal-bff/.env`
(git-ignored).
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.