Track B Phase 3 (CR-1) — the chained Ledger view (+ head hash)

2026-06-21

audit-chaingovernance-dashboard

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["GET /auth/governance/audit/ledger"] sdk_methods_updated: ["none — dashboard JWT surface"] mcp_tools_updated: ["none"] ---

What We Built

GET /auth/governance/audit/ledger projects the recent tamper-evident audit rows for the dashboard — per-tenant sequence, outcome, principal, reason, and the truncated event_hash per row — and exposes the current head hash (the newest chained row's event_hash) for cross-plane verification (R20). The dashboard LEDGER card renders it with Denied / Warned / All filters, defaulting to the enforced-denials view so red means a real block, not noise (R14).

Paired with the chain-verify badge (also CR-1), an operator now sees both the _verdict_ ("chain verified ✓") and the _rows themselves_ — the actual hash-linked sequence of allows, denials, and revocations — on one surface.

Why It Matters

The audit chain is the spine of the evidence plane; the Ledger makes it readable. An auditor can scan the recent decisions in sequence order, see each row's hash and tenant_seq (so a gap is visible), and copy the head hash to verify against the apiKey /v1 plane — the same value, by construction. "Tamper-evident" stops being a claim and becomes a table you can read.

How It Works

The route reuses the tenant-scoped completion-audit query (recent-first, optional outcome/since), projects each row, and derives the head from the newest row carrying an event_hash. No new storage — it reads the chain Increments 1–4 already write. The frontend is a thin filtered table over authFetch.

The Numbers

1 new JWT route; rows projected with seq + hash; head-hash exposed. Backend + dashboard build green; 389 dashboard tests + the full backend suite pass; pnpm check green.

Lockstep Checklist

[x] API Routes: GET /auth/governance/audit/ledger.
[x] TS/Python SDK / MCP: none — dashboard JWT surface.
[x] Generated contract: docs/openapi.yaml + static-assets regenerated.

Remaining (Phase 3 + 4)

The evidence spine is now fully legible: CR-7 events + live feed, CR-1 chain badge + ledger, CR-3 would-deny. Still ahead: effective-state badges (CR-2/CR-5) and the scope-check composer (CR-4 refactor). Phase 4 (Plans, CR-9) after.