Task 18 Execution Packet: Workbench Auth Hardening + Governance Export (Aligned to 2026-01-25 Plan)

This packet replaces the old Task 18 notes. It is aligned to Phase 16 / Task 18 in docs/plans/2026-01-25-end-state.md and the current repo structure.

Use this as the exact execution guide for an agent implementing Task 18.

Objective

Harden Workbench authentication and authorization and deliver real governance export output (signed, content-addressed bundles).

Non-negotiables

Role-aware RBAC enforced server-side and client-side.
OIDC auth (pluggable provider abstraction).
Export output is deterministic and verifiable (content-addressed bundles).
No generated edits.

Step 0 — Ground the current code reality (must confirm before editing)

Verify current auth and policy export locations:

services/workbench-bff/src/api/auth.py
apps/workbench/src/contexts/auth.tsx
services/policy-gateway/src/api/routes.py
Any existing RBAC/roles module or constants
Any existing evidence export adapters

If any of these differ, update this packet before coding.

Step 1 — Implement provider abstraction for auth

Requirements

Define a provider interface: AuthProvider
First implementation: OIDC
Future providers must be pluggable without rewriting auth logic

Server-side (Workbench BFF)

JWT Validation Details

Verify signature against OIDC JWKS (cached with TTL).
Validate exp, iat, nbf and reject expired/invalid tokens with 401.
Validate issuer and audience against configured values.
Token refresh: use OIDC refresh token if available; otherwise force re-auth.

Claims Mapping

Read roles from claim roles by default (configurable via env, e.g., AUTH_ROLE_CLAIM).
Deterministic mapping table (exact-match) maps source values → viewer|operator|admin.
Unknown roles are dropped; missing/malformed roles default to viewer (authenticated but least-privileged).

Session Management

Store access token in httpOnly secure cookie (or explicit secure storage if SPA-only).
Refresh strategy: rotate access token before expiry; configure max session duration.
Session duration and refresh TTL are configurable and documented.

Enforcement

Enforce RBAC in API routes using the mapping rules above.

Client-side (Workbench UI)

Use the new auth context to handle login state
Enforce role-based UI gates (but server remains source of truth)

Step 2 — RBAC requirements

Roles:

viewer
operator
admin

Rules:

Role hierarchy: admin ⇒ operator ⇒ viewer.
Default policy: new endpoints deny all except admin until explicitly added to the matrix.
Unauthorized access blocked at API and UI layers.

RBAC Permission Matrix (minimum)

Capability / Endpoint Group	viewer	operator	admin
Manifest read (`GET /manifests`, `/manifests/{id}`, `/manifests/{id}/versions`, `/manifests/{id}/diff`, `/manifests/{id}/source`)	✅	✅	✅
Provenance read (`GET /provenance/graph`, `/provenance/nodes/{id}`, `/provenance/lineage/{id}`, `/provenance/search`, `/provenance/impact/{id}`, `/provenance/compare`)	✅	✅	✅
Drift read (`GET /drift/context/{context}`, `/drift/report/{node_id}`, `/drift/history`)	✅	✅	✅
Behavior read (`GET /behavior/summaries`, `/behavior/nodes/{id}`, `/behavior/trends`, `/behavior/openobserve-config`)	✅	✅	✅
Ops read (`GET /ops/actions`, `/ops/actions/{id}`, `/ops/runs`, `/ops/runs/{id}`, `/ops/runs/{id}/logs`, `/ops/runs/{id}/summary`)	❌	✅	✅
Ops write (`POST /ops/runs`, `/ops/runs/{id}/cancel`)	❌	✅	✅
Drift analyze (`POST /drift/analyze`)	❌	✅	✅
Behavior scan (`POST /behavior/scan`)	❌	✅	✅
Drift remediation (`POST /drift/remediate`)	❌	❌	✅
Governance export (`POST /governance/export`)	❌	❌	✅
Policy reload (`POST /policy/reload`)	❌	❌	✅
RBAC / auth config changes	❌	❌	✅

Extension rule: adding a new endpoint requires an explicit matrix entry and tests for 401/403 behavior.

Step 3 — Governance export is real (no stubs)

Requirements

Export returns signed, content-addressed bundles that include:
- evidence ledger entries
- referenced objects
- manifest snapshots
- policy bundles
- index with hashes

Policy Gateway changes

services/policy-gateway/src/api/routes.py must export real evidence (no placeholder)

Export Bundle Specification (required)

Cryptography

Signature: Ed25519, detached signature file bundle.sig.
Key storage/rotation: keys stored outside repo; rotation supported via versioned public keys.

Content addressing

Hash: SHA-256, addresses formatted as sha256:<hex>.
Canonical JSON: RFC 8785 for JSON objects; stable array ordering.
Timestamps: excluded or normalized to fixed epoch in deterministic outputs.

Bundle layout

manifest.json
evidence/ledger.jsonl
evidence/objects/<evidence_id>/<artifact_id>
manifests/<manifest_id>.json
policies/opa/...
bundle.sig

manifest.json format

version, hash_alg, files[], root_sha256, generated_at (fixed epoch).
files[] entries map path → sha256 + bytes.
root_sha256 computed from sorted "{sha256} {path}\n" lines.

Verification process (consumer)

Verify bundle.sig using the public Ed25519 key.
Recompute file hashes and compare to manifest.json.
Recompute root_sha256 and compare to manifest.

Step 4 — Tests

Required tests

UI auth gating: apps/workbench/e2e/auth.spec.ts
- viewer/operator/admin role checks
- token refresh + UI↔BFF sync
BFF auth/RBAC: services/workbench-bff/tests/test_auth.py
- 401 for missing/expired/malformed JWT
- missing role claim → viewer only
- per-role allow/deny for matrix entries
Export tests: services/policy-gateway/tests/test_export.py
- bundle structure validation
- signature verification (valid/invalid key)
- hash index integrity
- determinism (byte-identical output)

Run:

pnpm exec nx test workbench -- --testPathPattern=auth
pnpm exec nx test workbench -- --testNamePattern="requires login"
pytest services/workbench-bff/tests/test_auth.py -v
pytest services/policy-gateway/tests/test_export.py -v

(And appropriate backend tests for BFF + policy-gateway.)

Acceptance criteria (from plan)

Unauthorized access blocked at API + UI layers
Evidence export is reproducible and verifiable
just ci passes