ehoandClaude Opus 5
772c47ea43
BIO-012: roleInterceptor/subjectInterceptor are correctly registered only under isDevMode(), but three hand-written fetch adapters (reveal-bignummer, letter-preview, org-template's proefbrief) bypass HttpClient and set X-Role/X-Subject themselves with no guard. The readers underneath, role.ts and subject.ts, were ungated too: they read ?role=/?subject= and wrote it into sessionStorage on any navigation, in any build -- for ?subject= that value is a BSN, which is exactly what SessionStore's G1 comment promises never happens. Gate both layers: currentRole()/currentSubject() return their safe default immediately outside isDevMode() (no query-param read, no sessionStorage write), and the three adapters additionally wrap their headers in isDevMode() so a production request carries neither header at all, matching what an HttpClient request already does once the interceptors aren't registered. TE-002: reveal-bignummer's response-shape validation was a "Trust boundary" a spec could only reach by stubbing globalThis.fetch. Exported it as parseRevealed(body), matching the other 30 parse* boundaries in the repo. Same treatment for letter-preview's errorMessage and org-template's proefbrief error mapping (extracted from an inline try/catch into a named, exported function first, since it wasn't already separate). BIO-006(a): reveal-bignummer sent X-Step-Up: 'true' unconditionally, so the backend's step-up precondition constrained nothing. reveal() now takes a stepUp flag; BriefStore.revealBigNummer() -- reachable only after the UI's confirm() gesture -- is the one that supplies it, so the literal no longer lives in the transport adapter. BIO-006(b): documented in roles-and-access.md that drafter is also the backend's fallback identity (StubIdentityProvider's catch-all arm), not just the dev switcher's initial choice -- so the least-privilege consequence of it also being the only role that may reveal a BSN is visible. Doc correction, same diff: roles-and-access.md's "wired only under isDevMode()" claim was false for the three hand-written fetch paths; it now says where the gate lives (interceptor registration and the reader functions) so it doesn't go stale the same way again. CLAUDE.md's dev-only claims needed no correction -- they already noted these three calls bypass the interceptor. Every fix has a test confirmed red by temporarily reverting the source change and rerunning the suite before restoring it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
102 lines
6.6 KiB
Markdown
102 lines
6.6 KiB
Markdown
# Roles & access (ABAC) — quick reference
|
|
|
|
A short, practical reference for **which roles exist, how to switch between them, and what each
|
|
unlocks**. For the full design and rationale see
|
|
[PRD-0002 — Attribute-Based Access Control](../project/prd/0002-attribute-based-access-control.md).
|
|
|
|
## Login vs. role — they are separate
|
|
|
|
**Login is faked.** This POC has one hardcoded, stubbed DigiD user (a 9-digit BSN); there is no
|
|
real identity provider and you do **not** pick a role when you log in.
|
|
|
|
The **acting role** is a separate, **dev-only** stand-in for the coarse role a real AD/OIDC identity
|
|
would carry. It is orthogonal to the login user — you log in as the one faked user, then choose an
|
|
acting role to exercise the drafter/approver/admin flows.
|
|
|
|
## The three roles
|
|
|
|
`drafter` (default) · `approver` · `admin` — defined by the `Role` type in
|
|
`src/app/shared/domain/role.ts`.
|
|
|
|
## How to switch role (dev only)
|
|
|
|
Both are wired only under `isDevMode()` — they do not exist in a production build. That
|
|
gate lives in two places: the `roleInterceptor` registration (`app.config.ts`) for every
|
|
`HttpClient` request, **and** inside `role.ts`'s `currentRole()` itself, because three
|
|
hand-written `fetch` calls (`reveal-bignummer.adapter.ts`, `letter-preview.adapter.ts`,
|
|
`org-template.adapter.ts`'s proefbrief) read the role directly and bypass the
|
|
interceptor entirely (RB-11/BIO-012). Before RB-11, `currentRole()` had no such gate, so
|
|
`?role=` kept working through those three calls in a production build even though this
|
|
page said otherwise; the same defect applied to `?subject=` and `subject.ts`, which is
|
|
how a BSN reached `sessionStorage` in any build.
|
|
|
|
- **Dev switcher (easiest):** open the `⚙ state` panel (bottom-right in a dev build) and pick a
|
|
role from the **role** dropdown. The page reloads with the new role.
|
|
- **`?role=` query param:** append `?role=drafter`, `?role=approver`, or `?role=admin` to any URL.
|
|
The value is **sticky for the browser tab** (`sessionStorage`), so it survives navigation that
|
|
drops the query param. An unknown value falls back to `drafter`; open a fresh tab or set
|
|
`?role=drafter` to reset.
|
|
|
|
Mechanism: `src/app/shared/infrastructure/role.ts` reads the role and the HTTP interceptor stamps it
|
|
as an `X-Role` header on role-aware requests; the backend resolves it into a `Principal`.
|
|
|
|
## Actor kinds (backend, WP-62)
|
|
|
|
`X-Role`/`Principal` above is a coarse role that applies to **either** of two actor kinds the
|
|
backend now models (ADR-0002 §3): a **zorgverlener** (the SSP's citizen — has a BSN) or a
|
|
**medewerker** (backoffice employee — no BSN, has `Rollen`). `StubIdentityProvider` picks the
|
|
medewerker kind from a dev header, `X-Medewerker` (+ `X-Rollen`), mirroring `X-Role`/`X-Subject`
|
|
above. The SSP's FE never sends either header — it has no medewerker screens. The
|
|
**behandelportal** does: `apps/behandelportal/src/app/auth/infrastructure/medewerker.interceptor.ts`
|
|
stamps every request as one fixed stand-in medewerker (dev-only, same `isDevMode()` gate as
|
|
`roleInterceptor`), since this app has no real employee-SSO login yet (ADR-0002 §3 — the two
|
|
apps' login flows are expected to diverge, and this stand-in is that flow's placeholder).
|
|
`?rollen=` (sticky per tab, mirroring `?role=`) picks the medewerker's rollen —
|
|
`?rollen=geen` exercises the deny path; the default is `behandelaar`.
|
|
`Authz.CanBeoordelen(caller)` is the first medewerker capability — a rol-based decision flag
|
|
(`MedewerkerRol.Behandelaar`), surfaced on `GET /me` as `aanvraag:beoordelen` (appended
|
|
alongside `RoleCapabilities`'s role-derived set, since that switch is keyed on `Principal` and
|
|
can't see the actor kind) — gates the behandelportal's `/dashboard` werkvoorraad queue (WP-64)
|
|
and its `/aanvraag/:id` beoordeling detail (WP-65).
|
|
|
|
## What each role unlocks
|
|
|
|
Capabilities are resolved server-side (`backend/src/BigRegister.Api/Domain/Authorization/Authz.cs`,
|
|
`RoleCapabilities`) and returned by `GET /me`.
|
|
|
|
| Role | Capabilities (`/me`) | Reaches |
|
|
| ---------- | --------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
| `drafter` | _(none of the admin capabilities)_ | Composes letters; the only role that may reveal a BSN |
|
|
| `approver` | `brief:approve`, `brief:reject`, `brief:send` | Reviews/approves letters (four-eyes: approver ≠ drafter) |
|
|
| `admin` | `orgtemplate:edit`, `stamdata:edit`, `cases:manage` | Huisstijl `/brief/huisstijl`, Stamdata `/beheer/stamdata`, Aanvragen `/beheer/zaken` |
|
|
|
|
The admin pages appear in the header nav and in the dashboard **"Beheer"** section whenever the
|
|
matching capability is present — otherwise they are reachable only by URL (and the route guard
|
|
redirects a user who lacks the capability back to `/dashboard`).
|
|
|
|
**`drafter` is also the backend's fallback identity (BIO-006).** It is not only the dev
|
|
switcher's initial selection — `StubIdentityProvider`'s role switch resolves **any**
|
|
request with no `X-Role` header at all (or an unrecognised one) to `drafter` too. Because
|
|
`drafter` is also the _only_ role that may reveal a BIG-nummer, the least-privilege
|
|
consequence is real: an unauthenticated or misconfigured caller inherits the PII-reveal
|
|
capability by default, rather than the weakest one. This is acceptable only because the
|
|
POC has no real identity or step-up yet (see the pre-production compliance checklist —
|
|
binding the reveal to an app-overlay attribute instead of the coarse role is a named,
|
|
not-yet-built item); it must not survive real identity and step-up.
|
|
|
|
## The one principle
|
|
|
|
Identity (AD/OIDC, faked here) supplies **coarse roles**; the app owns a **fine-grained capability**
|
|
model on top. The **same `Authz` check both emits a capability** (on `GET /me`, consumed by
|
|
`AccessStore` in `src/app/shared/application/access.store.ts`) **and enforces the endpoint** — one
|
|
source of truth, so the two can't drift. **The UI only renders decisions; it never derives access
|
|
from a role.** Anything tied to a specific resource's live state (e.g. may-I-edit _this_ letter,
|
|
reveal _this_ BSN) rides that screen's decision DTO rather than `/me`.
|
|
|
|
## See also
|
|
|
|
- [PRD-0002 — ABAC](../project/prd/0002-attribute-based-access-control.md) — full design.
|
|
- `backend/src/BigRegister.Api/Domain/Authorization/Authz.cs` — role → capability, and the enforce twin.
|
|
- `src/app/shared/infrastructure/role.ts` — the dev `?role=` reader + `X-Role`.
|
|
- `src/app/shared/application/access.store.ts` — how the FE mirrors `/me` capabilities (deny-by-default).
|