From a5ac1fb7298237a417c6cd417c1812cbc591761b Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Thu, 23 Jul 2026 13:03:05 +0200 Subject: [PATCH] docs: roles & ABAC quick reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add docs/reference/roles-and-access.md — a short, scannable reference for the three dev roles (drafter/approver/admin), that login is faked and role is a separate dev-only stand-in, how to switch (dev switcher / ?role=), a per-role capability table, and the one ABAC principle (server emits + enforces; UI renders). Points to PRD-0002 + the code. Adds a pointer from CLAUDE.md. Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 2 + docs/reference/roles-and-access.md | 64 ++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 docs/reference/roles-and-access.md diff --git a/CLAUDE.md b/CLAUDE.md index 362bdfb..0b29d07 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,6 +184,8 @@ atomic layer it is (a context organism doesn't get its own `Organisms/` bucket). components keep referencing tokens). System-font stack (licensed RO/Rijks fonts not shipped). See ADR-0003. - Scenario toggle (**dev-only**, not wired in prod builds): `?scenario=slow|loading|empty|error` on data pages (`scenario.interceptor.ts`) to see every async state. +- Dev role stand-in (**dev-only**): `?role=drafter|approver|admin` (or the `⚙ state` dev panel). + Roles, how to switch, and what each unlocks: `docs/reference/roles-and-access.md`. - Prettier; `.editorconfig`. tsconfig: `noImplicitReturns`, `noPropertyAccessFromIndexSignature`, `noFallthroughCasesInSwitch`, `isolatedModules`. - **Enforced, not just hoped-for:** `npm run lint` (`eslint.config.mjs`) fails the build diff --git a/docs/reference/roles-and-access.md b/docs/reference/roles-and-access.md new file mode 100644 index 0000000..e8c3fc2 --- /dev/null +++ b/docs/reference/roles-and-access.md @@ -0,0 +1,64 @@ +# 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. + +- **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`. + +## 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`). + +## 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).