Admin role tiers: file-rooted superadmins + runtime-managed roster (P2B)

[MartinMontero]

What does this PR do?

Extends the landed Phase-2 admin auth (worker/admin/*) with the P2B two-tier role model: the committed allowlist (worker/admin/allowlist.ts) is the file-rooted tier (PR-governed, immutable at runtime); a new D1 admin_roster in the existing DB holds runtime-managed admins, mutable only by file superadmins via three new superadmin-only /api/admin/admins* endpoints, with every mutation written to an insert-only admin_audit. One resolver (worker/admin/roles.ts) re-derives the role from the current effective set (file ∪ roster) on every authenticated request — cookie path included — so removal is effective on the principal's next request. Four commits, one phase each: migration → resolver/rewiring → management API → invariant tests.

Phase 0 stale-brief corrections (on the record)

• The per-request cookie re-check the brief flagged as missing had already landed on main via PR fix(admin): per-request allowlist enforcement on the cookie path (revocation takes effect next request) #49 (resolveAllowlistedAdmin); this PR generalizes it to role re-derivation (resolveRoledAdmin) and extends it to logout, which was still resolving sessions without a membership re-check — that gap is closed here (a valid session id reaching logout is now always destroyed; membership failure changes the status code, never leaves the record alive).
• The allowlist does not ship empty: the owner identities were constituted via PR Admin constitution — genesis role schema + the two owner identities (superadmin) #50. All fails-closed proofs remain fixture-based (injected empty allowlist), so they hold regardless of the committed set.
• No prior "input-normalization fix" exists anywhere in the tree or history; normalizeSubject introduced here (allowlist.ts) is therefore THE single shared Cf-stripping normalizer, per the one-implementation ruling.

The four rulings (applied)

1. File role: 'admin' entries are honored as recorded — they log in like admins, hold no roster-mutation rights, and are immutable via the API (add → 409, remove → 403). The file is a complete governance surface: a fork may run its entire admin set through PRs with the roster empty forever.
2. Allowlist exports additive only — normalizeSubject (Unicode trim + strip all Cf format chars + lowercase hex; DIDs exact after strip) and isValidSubject (the same HEX_PUBKEY/DID rules the matchers enforce). Existing exports byte-untouched. npub input is accepted on the management API via the in-tree nostr-tools/nip19 and the hex is echoed back. Validation errors surface only after successful superadmin auth — no pre-auth format oracle.
3. Actor/audit format provider:subject.
4. Remove of a non-member roster entry → 404.

D1 availability asymmetry (deliberate)

On the auth path a missing/unreachable DB treats the roster as empty: file principals keep working (a D1 outage can't lock the operator out), roster admins are denied — fails closed, never degraded-open. The management routes do the opposite: DB unavailability is an explicit 503 (roster unavailable), and a file-only list is never rendered as if complete.

Migration sequencing note

Between merge (code deploys) and the remote migration apply, the management routes return 503 and existing auth is unaffected — fails closed by design. Remote apply is a hard stop reserved to the owner (see below).

What the owner does post-merge

1. Apply the migration remotely (hard stop — exact command, run only on your explicit go):
   npx wrangler d1 migrations apply wcjbt-auth --remote
2. Positive round-trip with a throwaway public identifier only (an npub/hex pubkey or DID — never any secret): POST /api/admin/admins/add with {"provider":"nostr","subject":"<throwaway npub or hex>","note":"round-trip test"} (cookie + x-admin-csrf, or per-request NIP-98), confirm it appears in GET /api/admin/admins as source: roster, then POST /api/admin/admins/remove for the same principal.
3. Quote the two audit rows:
   npx wrangler d1 execute wcjbt-auth --remote --command "SELECT at, actor, action, provider, subject, method, note FROM admin_audit ORDER BY at;" — expect one admin.add and one admin.remove for the throwaway subject, actor provider:subject of the acting superadmin.

Type of change

• New catalog entry
• Fix/update to an existing entry
• New or updated recipe
• Build flow / docs
• Enforcement engine / tooling
• Other

Required checks

The enforcement engine is blocking. CI runs all of this on your PR, but please
confirm you ran it locally too.

• npm run check passes (schema validation)
• npm run enforce passes (three-layer exclusion policy + recipe contract)
• npm test passes (315/315 — 291 baseline + 24 new invariant tests, each P2B invariant pinned by name)
• npm run build succeeds (npm run verify:all exit 0)

Dependency delta: zero (package.json/lockfile untouched; nip19 comes from the already-in-tree nostr-tools). Migration applies cleanly on a fresh local D1 (0001 → 0002 verified from empty state). No workflow files touched; operational_advisory untouched.

For catalog entries

Not applicable — no catalog entries in this PR.

For recipes

Not applicable — no recipes in this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U8EGtxYhdvUcvhCZLBrXFc

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	wecanjustbuildthings	9c23253	Jul 05 2026, 05:27 PM