# Audit log (authz / PII-reveal trail) — how it's built & extended

A persisted, **data-minimised** trail of authorization decisions and sensitive reveals.
By construction it **never** records a name, BSN, or the revealed value — only _that_ a
decision happened, on what kind of resource, and its outcome. Built in WP-41 (persisted
backend) and surfaced by WP-42 (privacy/security showcase); it backs
[PRD-0002 — ABAC](../project/prd/0002-attribute-based-access-control.md) §8.

## The one rule: one producer hub, not scattered logging

Every audited event flows through a **single** helper — `AuditAuthz(…)` in `Program.cs`.
It writes the log line _and_ persists the row. Endpoints don't hand-roll audit records;
they call the hub. That's what keeps the "never log PII" guarantee enforceable in one place
instead of trusting every call site.

## Layered pipeline

Backend:

- `Data/AuthzAuditStore.cs` — `AuthzAuditEntry (At, Action, Resource, Decision, Role,
CorrelationId)` + `Record(…)` / `List()` (newest-first). No PII column — a reflection
  test asserts the schema stays that way.
- `Data/AppDbContext.cs` — `AuthzAudit` DbSet + migration (persists to SQLite, WP-22).
- `Program.cs`: `AuditAuthz(…)` (the hub, ~line 590) is called on every authz denial and on
  the BIG-nummer reveal/step-up; `GET /admin/audit` (read) is gated by `CasesAdmin`.

Frontend (`src/app/beheer/`):

- `domain/audit-entry.ts` → `infrastructure/audit.adapter.ts` (`list()` + `parseAuditEntries`
  boundary) → `application/audit.store.ts` (root singleton, `RemoteData`, **read-only**) →
  `ui/audit.page.ts` (read-only table, gated on `cases:manage`, loads via a guarded `effect`
  once the capability resolves).

## How to audit a new action

You do **not** touch the frontend. In the backend, at the decision point, call the hub:

```csharp
AuditAuthz(ctx, action: "flags:manage", resource: key, decision: "deny");
```

Use a short stable `action` slug and a **non-PII** `resource` identifier (an id or table
name, never a name/BSN). The admin table picks it up automatically.

## Coupling

Deep-linked on the **producer** side by design, self-contained on the consumer side:

- **Consumer coupling: near zero.** The audit store is read by exactly one page; no other
  component depends on it.
- **Producer coupling: centralized, not scattered.** Many endpoints call `AuditAuthz`
  (stamdata/cases/flags denials, org-template edits, reveal-bignummer) — but all through
  the one hub, so it's a spoke-and-hub, not logic sprinkled across the codebase. Extend by
  calling the hub; never inline a new audit write.

## Wire-up gotchas (both bit WP-41)

- Add the read endpoint to the `role.interceptor` **ROLE_AWARE** list
  (`/api/v1/admin/audit`) or it 403s silently with no `X-Role` header.
- The admin nav entry lives in `ADMIN_LINKS`, gated on `cases:manage`.

## See also

- [PRD-0002 — ABAC](../project/prd/0002-attribute-based-access-control.md) §8 — the audit requirement.
- [WP-41](../project/backlog/WP-41-persisted-authz-audit.md) (persistence), [WP-42](../project/backlog/WP-42-privacy-security-showcase.md) (showcase).
- `backend/src/BigRegister.Api/Data/AuthzAuditStore.cs` — the no-PII schema.
- `src/app/beheer/ui/audit.page.ts` — the read-only view.
- [Roles & access](roles-and-access.md) — `cases:manage` + admin gating.