docs(security): document audience scoping rollout rules

2026-03-30 09:59:33 +02:00
parent 3a30fecc13
commit 8495b83b3e
1 changed files with 49 additions and 0 deletions
@@ -47,6 +47,55 @@

 - all current routes are `controller-finance`

+### `packages/api/src/router/role.ts`
+
+- `resolveByIdentifier`: `authenticated-safe-lookup`
+- `list`, `getByIdentifier`, `getById`: `planning-read`
+- create, update, delete: `manager-write`
+
+Reasoning:
+
+- `resolveByIdentifier` returns a narrow lookup shape without planning counts
+- `list`, `getByIdentifier`, and `getById` attach planning-linked usage counts, so they must not remain broad `protectedProcedure` reads
+
+### `packages/api/src/router/scenario.ts`
+
+- `getProjectBaseline`: `planning-read` plus explicit `viewCosts`
+
+Reasoning:
+
+- the route combines staffing baseline data with commercial totals, so both planning and cost audiences are required
+
+### `packages/api/src/router/estimate.ts`
+
+- `list`: `controller-finance`
+- drafting, versioning, export generation, and approval writes: `manager-write`
+
+### `packages/api/src/router/system-role-config.ts`
+
+- all reads and writes: `admin-only`
+
+Reasoning:
+
+- system role defaults define the effective permission model and therefore belong to the smallest operational audience
+
+## Assistant Parity Rule
+
+- assistant tool visibility must never widen the audience of the backing router
+- router audience is the source of truth; assistant gating mirrors it
+- when a route becomes narrower, update assistant visibility in the same hardening slice
+- if `assistant-tools.ts` already has unrelated local edits, prefer updating `packages/api/src/router/assistant.ts` and parity tests first instead of mixing concerns into the tool implementation file
+
+## Rollout Discipline
+
+For audience-scoping changes, use this order:
+
+1. narrow the backing router procedure first
+2. add or tighten authorization tests on the router
+3. align assistant visibility in `packages/api/src/router/assistant.ts`
+4. update assistant parity tests
+5. ship in small isolated commits so regressions can be reverted without undoing unrelated hardening
+
 ## Immediate Follow-Ups

 - monitor whether `viewPlanning` should later split into narrower project-read vs allocation-read audiences