# 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).