​

Implementation Plan — Prism Administrative Console

​

0. How to read this plan

• §1 — the load-bearing decision that gates everything else.
• §2 — work breakdown by lane, every item concrete.
• §3 — sequencing + critical path + the integration handoffs.
• §4 — acceptance: what “done” means, per function.
• §5 — risk register.
• §6 — what gets filed (Plan + SPEC) and what stays deferred.

​

1. Gate-zero decision — the two seams (must land first)

1. Auth / identity seam — IdentityProvider interface. The console and every verb ask the seam “who is this + what is their scope + what role” — never the provider directly. Two bindings, WorkOS is the one we exercise now:
   • WorkOS binding (primary, exercised from Wave 1). WorkOS AuthKit session
     • WorkOS Organization Roles drive the real three-tier owner/admin/member gating. This is the binding Frank exercises the full console access mechanism with — the bootstrap-key path is single-superuser and has no RBAC to test.
   • Bootstrap-key binding (kept, not the test path). Local/LAN bootstrap-admin-key + localhost access. Still exists for pure-local use; it simply isn’t where the access mechanism gets exercised.
2. Tenant-bootstrap seam — “a tenant exists with an owner” is produced by a bootstrapper. Local/LAN = bootstrap_personal_install() (exists). Cloud = prism_tenant_create. Downstream code consumes the result identically.

​

GATE-ZERO RESULT — BLESSED 2026-05-14 (Texi, note 2146983a)

1. Name the seam ConsoleIdentityProvider returning a ConsoleAuthContext — distinct from the existing OAuthProvider.
2. ConsoleAuthContext carries: normalized user, tenant scope, tenant_role (owner/admin/member/none), capabilities, and provider_context (audit only).
3. The WorkOS raw role claim is never read for authorization. It maps through backend validation to memberships.role / capabilities; authorization reads the Prism-normalized role, not the raw provider claim. (This is ADR-53 made concrete.)
4. Provider Organization maps to Prism Tenant only — never Prism org/dept authority.
5. Unknown / missing role fails closed — except the bootstrap-key local single-superuser path.
6. The tenant-bootstrap seam returns the same postcondition for Local/LAN/Cloud: tenant + owner + default org/dept + console entry scope, idempotently.

​

2. Work breakdown by lane

​

Lane A — Backend verbs + middleware (owner: Donna)

​

Lane B — Console UI (owner: Porsche)

​

Lane C — Install / invite (owner: Lafonda)

​

Lane D — Reviews (owners: Texi architecture, Andora security)

​

3. Sequencing + critical path

STEP 0  ──  D1 Texi blesses the two seams ──┐
                                            │
        ┌───────────────────────────────────┼───────────────────────────┐
        │ Lane A (backend)                  │ Lane B (UI)                │ Lane C (install)
        │                                   │                           │
WAVE 1  │ A1 seams ── A1w WorkOS binding     │ B1 shell ── B2 scope       │ C1 verify Local
        │ A1k bootstrap-key binding          │   render                  │ C4 dist-invite
        │ A2 role-gating (needs A1w)         │ B7 update-notif            │
        │ A3 org_create  A4 dept_create      │                           │
        │                                   │                           │
WAVE 2  │ A5 team_preseed                    │ B3 role UI (needs A2/A1w)  │ C2 verify LAN
        │ A6 tenant_backup                   │ B4 hierarchy tree          │ C3 LAN invite
        │                                   │   (needs A3,A4)            │   (needs A2)
        │                                   │                           │
WAVE 3  │ A7 archive  A9 tenant_create       │ B5 preseed UI (needs A5)   │ C5 install↔console
        │ A8 restore (test-gated)            │ B6 backup UI (needs A6,A7) │   handoff
        │                                   │                           │
INTEGRATE ── clean Local install smoke ── WorkOS-authed access-control exercise ── all 6 functions

• B1 console shell + B2 scope rendering + B7 update-notification — pure UI, no backend contract needed.
• C1 verify Local install, C4 distribution-invite helper.

• A3/A4 verbs → B4 tree: backend publishes the org/dept verb contracts; UI wires.
• A2 middleware → B3 + C3: role-gating contract is shared by UI and the LAN invite.
• A5 → B5, A6/A7 → B6: verb-ready signal triggers UI wiring.
• A1 seam stubs → everyone: the seam interface is the shared contract; it must be published (even as a stub) before A2/B3/C3 start.

​

4. Acceptance — what “done” means

​

5. Risk register

​

6. What gets filed + what’s deferred

• Texi — step zero: bless the two seam interfaces (§1), WorkOS as a first-class binding. Everything waits on this 30-min call.
• Donna — Lane A backend verbs + middleware; A1w WorkOS binding on the critical path.
• Lafonda — Lane C install / invite.
• Andora — Lane D security, incl. the WorkOS role-claim trust boundary.
• Porsche — Lane B Console UI shell immediately + drives all four lanes.
• Frank — operator prerequisites §6a before A1w closes.
• File a formal Plan (prism_plan) + SPEC (“SPEC-1xx — Administrative Console”) as the SOR, cross-ref SPEC-089 / SPEC-114 / SPEC-115 / ADR-53/54/55.

• WorkOS binding on the auth seam (A1w) + the WorkOS-authed access-control exercise. WorkOS is now the primary exercised binding — it is how the full three-tier console access mechanism gets tested. On the critical path.

• Full Cloud multi-tenant exercise across many tenants — the WorkOS binding and role-gating are built + exercised today against one Organization; scaling to the full multi-tenant Cloud topology is the later additive step.
• Distribution-invite automation (manual gh repo-collaborator add works today).
• prism_tenant_create Cloud path may trail same-day — it’s not on the role-gating critical path.

​

6a. Operator prerequisites — Frank’s WorkOS setup (blocks A1w)

1. WorkOS Organization — confirm the Organization that the console exercises against (the SPEC-089 cutover used one; confirm WORKOS_ORGANIZATION_ID).
2. WorkOS Roles defined — the three roles owner / admin / member must exist in the WorkOS dashboard for that Organization, so the session carries a readable role claim. Without them A2 role-gating has nothing to read.
3. WORKOS_* env on the target backend — WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_ORGANIZATION_ID, WORKOS_ISSUER present on whichever backend the console is exercised against (cloud prism-server has these per SPEC-089 §6.1; a local backend would need them added).
4. At least two test humans in WorkOS with different roles, so the three-tier gating is exercised with real role differences — not just owner.

​

7. Open items for the reviews (not plan blockers)

• GitHub-handle storage location (users vs memberships vs user_external_identities) — Texi call during D2.
• Backup destination seam: confirm local-disk default path + the S3 binding shape — Donna + Andora during A6/D3.
• Update-notification cadence + where the GitHub-release check runs — Porsche + Donna during B7.