Console Blueprint RBAC V2 Cutover Design

Status: Design locked 2026-06-18 Owner: software-architect Refs: #1473 (parent card), #1464 (RBAC V2 design PR), issues #971/#972/#973 (resolution-DAG) Related docs: rbac-design.md, auth-unification-rbac-reconciliation.md Related ADR: 0129-rbac-blueprint-cutover-rollout.md

1. Context

The Console has 141 legacy @require_role(...) decorator call sites across the 17 blueprints listed below. Each call invokes admin.has_role(...) against the flat admin_roles table (superadmin / ops / support / readonly). The RBAC V2 tables (rbac_roles, rbac_user_groups, rbac_group_roles, rbac_role_permissions) were provisioned in migration 0012. Fine-grained decorators (@require_rbac_role, @require_rbac_permission, and the billing-specific @require_permission) already exist in console/app/middleware/rbac.py and are used by ~54 call sites that were already ported (billing, api_billing, api_billing_dashboard, api_rbac_grants).

This design governs the remaining 141-site cutover, grouped into 17 blueprints. The correctness artifact is the per-route permission mapping in §3. A wrong cell can lock out a legitimate operator or over-expose a privileged surface before launch.

2. Invariants

These constraints take precedence over every design choice below.

3. Per-Blueprint, Per-Route Permission Mapping

How to read this table

• Legacy gate — the current @require_role(...) argument set.
• V2 decorator — the @require_rbac_role("<role>") replacement.
• V2 role exists? — whether the named V2 role was seeded in migration 0012 or a subsequent migration.
• AMBIGUOUS — operator decision required before implementation.

Role names follow <app>-<resource>-<level> per rbac-design.md §3.1.

Legend of roles cited

From migration 0012 (_ROLES) and subsequent migrations:

CRITICAL GAP (pre-cutover blocker): Several legacy gates use ops or superadmin combinations that map naturally to console-ops or console-manager, but those roles have no explicit group assignment for ops-equivalent operators in the current seed data. Migration 0012 assigns console-ops to no group. This must be resolved before sub-cards are implemented. See Open Question #5 in §10.

Blueprint 1: admins_online.py — 2 routes, 2 legacy sites

Rationale: Viewing and revoking other operators' sessions is admin management of identities — semantically aligned with console-invite-admin (which grants console:admins:invite and console:groups:write). The legacy superadmin gate maps to the highest-trust working group; console-invite-admin is the closest V2 equivalent for user management actions.

AMBIGUOUS-1 (operator decision required): Should session revocation require a dedicated console:admins:revoke-session permission (not yet seeded) rather than reusing console-invite-admin? Options: (A) reuse console-invite-admin as proposed above, (B) add a new permission console:admins:revoke-session and role console-session-admin in a pre-cutover migration. This must be decided before sub-card S1 is claimed.

Blueprint 2: alerts.py — 4 routes, 4 legacy sites

All 4 routes (/api/_internal/alerts/unread-count, /_alerts/drawer, /_alerts/dismiss/<id>, /_alerts/dismiss-all) use:

Rationale: Any authenticated Console operator should see alerts. console-user is the broadest role held by all three groups. This preserves the "all roles" intent exactly.

Blueprint 3: api_billing.py — 3 routes, 0 legacy sites

Already fully ported. No action required.

Blueprint 4: api_billing_dashboard.py — 7 routes, 0 legacy sites

Already fully ported. No action required.

Blueprint 5: api_rbac_grants.py — 4 routes, 0 legacy sites

Already fully ported. No action required.

Blueprint 6: api_status.py — 4 routes, 4 legacy sites

Rationale for /builds: support can read builds but not readonly. console-audit-user is held by raxx-platform-admins, raxx-support-team, raxx-devops-team — matching the support-and-above intent. readonly is the only tier excluded, which matches the legacy gate.

Machine-token compatibility note (Open Question #6): @machine_auth_or_session is applied before @require_role on /sites and /builds. Machine tokens have no rbac_user_groups rows and will 403 under V2 unless enrolled in a group. Feature-developer must verify or add machine-token enrollment before S5 ships.

Blueprint 7: audit_ingest.py — 1 route, 0 legacy sites

Uses Bearer token auth. Not session-based. Excluded per Invariant I-7.

Blueprint 8: audit_viewer.py — 1 route, 1 legacy site

Rationale: console-audit-user grants console:audit:read — exact permission match.

Blueprint 9: beta.py — 12 routes, 15 legacy sites

All 12 routes use @require_role("superadmin").

Rationale: console-manager is assigned to raxx-platform-admins and break-glass — the V2 equivalent of superadmin. Beta management is operator-only and PII-touching (invites, deletes, resends).

AMBIGUOUS-2 (operator decision required): Should beta management use a dedicated console-beta-admin role rather than console-manager? Options: (A) console-manager as proposed, (B) new console-beta-admin role requiring a pre-cutover migration. Recommend option A for v1 given single-operator team size; revisit when a second operator is added.

Blueprint 10: billing.py — 3 routes, 0 legacy sites

Already fully ported. No action required.

Blueprint 11: console_versions.py — 1 route, 1 legacy site

TOTP elevation preserved. The V2 decorator replaces only the session/role gate.

Blueprint 12: console_versions_ui.py — 1 route, 1 legacy site

Blueprint 13: customers.py — 16 routes, 16 legacy sites

AMBIGUOUS-3 (operator decision required): The customer session-revoke route (POST /console/customers/<id>/<session_id>/revoke) is a write action currently gated at ops-level. Mapping it to console-audit-user (a read role) would be a security regression — audit-user was not intended to authorize mutations. Options: (A) console-manager (narrowest, matches destructive intent), (B) console-invite-admin (user management semantic), (C) new console-customers-write role (cleanest but requires migration). This must be decided before sub-card S3 is claimed.

Blueprint 14: dashboard.py — 9 routes, 10 legacy sites

Note on _force_poll: This is a mutation (force-triggers polling). console-flag-admin is the V2 role for operational write actions on Console infrastructure.

Blueprint 15: deploy_freeze.py — 2 routes, 2 legacy sites

/api/internal/deploy-freeze/state uses service-token auth — excluded per Invariant I-7.

Rationale: Reading the freeze page is informational (manager-level). Toggling the freeze is a production write action — console-prod-services-write was seeded in 0097 precisely for production mutation gates.

Blueprint 16: deploys.py — 4 routes, 4 legacy sites

/api/internal/deploys/<id>/status (callback) and /api/internal/deploys/<id>/xenv use Bearer/service-token auth — excluded per Invariant I-7.

AMBIGUOUS-4 (operator decision required): The POST /api/internal/deploys route applies a single @require_role("ops", "superadmin") but then performs an inline TOTP check for prod targets (determined from request body). Under V2, prod vs staging deploys ideally map to different roles (console-prod-services-write vs console-staging-services-write). Options: (A) Gate the whole POST on console-prod-services-write (conservative; ops group already holds both staging and prod roles per 0097 seed), (B) Outer gate on console-staging-services-write; inline check for console-prod-services-write on prod-targeted requests (mirrors existing inline TOTP pattern), (C) Split the route into /deploys/staging and /deploys/prod. Option B is the recommended approach. Must be confirmed before sub-card S4 is claimed.

Blueprint 17: flags.py — 14 routes, 22 legacy sites

The flags.py blueprint contains an inner _flag_gated_rbac_perm helper that wraps require_rbac_permission conditionally on FLAG_FLAG_PROMOTION_QUEUE_RBAC. This inner guard must be preserved independently of the outer @require_role swap.

Blueprint 18: internal.py — 5 routes, 5 legacy sites

Blueprint 19: ops.py — 3 routes, 3 legacy sites

Blueprint 20: rbac_grants_audit_ui.py — 1 route, 1 legacy site

The docstring already states the intended gate is raptor-audit-admin. The legacy @require_role("ops", "superadmin") is a placeholder; this cutover corrects the under-specification.

Blueprint 21: rbac_shadow_report.py — 2 routes, 2 legacy sites

These routes are deleted (not migrated) as part of this card. The dual-mode drift reporter removal (#1473 AC) eliminates the shadow comparison report entirely.

Sub-card S1 includes the route deletion.

Blueprint 22: replay.py — 4 routes, 4 legacy sites

Blueprint 23: secrets.py — 14 routes, 19 legacy sites

Rationale for /sop: All roles can view the SOP docs (runbook links, not secret values). console-secrets-user is inherited by console-secrets-admin and can be assigned to support/devops groups. See OQ-5 in reconciliation doc.

Blueprint 24: security.py — 2 routes, 2 legacy sites

Blueprint 25: status_page.py — 2 routes, 2 legacy sites

Blueprint 26: waitlist.py — 2 routes, 2 legacy sites

4. Ambiguous Mappings — Operator Decisions Required

These items BLOCK the sub-cards they are labeled against. Feature-developer must not claim the relevant sub-card until the operator has recorded a decision on #1473.

5. Flag-Gated Rollout Strategy

Current dual-mode behaviour

@require_role calls _run_shadow_check() which lazily imports app.middleware.rbac_dual_mode.shadow_check. That shadow check runs both paths when FLAG_RBAC_V2 is on, logs drift, but never alters the authoritative decision. The legacy path is always authoritative.

The shadow check is removed in this card. After cutover, each blueprint is either on the legacy decorator or the V2 decorator — not both. There is no dual-evaluation shim.

Flag as deployment gate, not runtime gate

Flask evaluates decorators at import time (startup), not at request time. A module-level flag check is frozen at process start. Therefore FLAG_RBAC_V2 controls which deployment is live, not which decorator fires per request.

Implementation pattern: Feature-developer replaces decorators directly. The FLAG_RBAC_V2 flag serves as a deployment signal: - Staging: deploy V2-decorated code, set FLAG_RBAC_V2=1 in staging config. - Prod: promote only after staging soak; FLAG_RBAC_V2=1 signals the promoted build. - Rollback: redeploy the legacy-baseline SHA (see §8).

Per-blueprint granularity: Each sub-card targets one cluster of blueprints (see §6). Sub-cards are promoted independently to staging, allowing per-blueprint soak before the cluster is promoted to prod.

6. Phased Sub-Card Breakdown

S1 — Shadow report deletion + low-risk read-only clusters

Blueprints: rbac_shadow_report.py (delete), alerts.py, status_page.py, waitlist.py, console_versions_ui.py Approx. legacy sites: 11 Blocked on: AMBIGUOUS-1 is NOT blocking S1 (admins_online is a separate sub-card) Why first: Removes dead code. Read-only blueprints map uniformly to console-user. Lowest blast radius.

S2 — Audit, security, replay, ops

Blueprints: audit_viewer.py, security.py, replay.py, ops.py Approx. legacy sites: 10 Why second: All map to console-manager or console-audit-user with no ambiguity. No TOTP chains. Straightforward mechanical swap.

S3 — Beta + customers

Blueprints: beta.py, customers.py Approx. legacy sites: 31 Blocked on: AMBIGUOUS-2, AMBIGUOUS-3

S4 — Deploys + deploy_freeze + internal + console_versions

Blueprints: deploys.py, deploy_freeze.py, internal.py, console_versions.py Approx. legacy sites: 14 Blocked on: AMBIGUOUS-4 (deploys POST pattern) Special: deploys.py has inline TOTP logic that must not be moved.

S5 — Dashboard + api_status

Blueprints: dashboard.py, api_status.py Approx. legacy sites: 14 Special: Machine-token compatibility verification required before merging (Open Question #6).

S6 — Flags

Blueprint: flags.py Approx. legacy sites: 22 Why last of the main cluster: Largest single blueprint. 5 routes with TOTP elevation. Inner _flag_gated_rbac_perm helper must be preserved independent of outer role swap.

S7 — Admins online

Blueprint: admins_online.py Approx. legacy sites: 2 Blocked on: AMBIGUOUS-1

S8 — Secrets (last)

Blueprint: secrets.py Approx. legacy sites: 19 Why last: Highest privilege surface. 5 routes with TOTP elevation. Ship only after S1–S7 have soaked in staging for at least 24 hours.

S9 — RBAC grants audit UI

Blueprint: rbac_grants_audit_ui.py Approx. legacy sites: 1 Why separate: Small blast radius; can be picked up between any two other sub-cards.

S10 — CI lint gate (RV-14)

Add grep -r '@require_role' console/app/blueprints/ to CI as a zero-match enforcement gate. Ship as a co-requirement with or immediately after S8.

7. Test Strategy

Pre-cutover smoke test (required before first sub-card ships)

console/tests/test_rbac_cutover_smoke.py: asserts that every V2 role name cited in the mapping tables above exists in the rbac_roles seed data. Prevents "role name typo" class of bugs before any PR is merged.

Per-sub-card table-driven tests

Each sub-card PR adds console/tests/test_rbac_cutover_<cluster>.py with:

For each route in the cluster:
  assert: unauthenticated request -> 302 to /auth/login
  assert: session with V2 role -> 200
  assert: session without any V2 role -> 403
  assert: 403 response writes access_denied audit row

Test fixture creates admin with exactly the proposed V2 role via rbac_user_groups/ rbac_group_roles tables (not via legacy admin_roles).

Golden test per cluster

One test that runs the full route list for the cluster with a single authorized admin and asserts 200 on all. Catches "missed a route" class of bugs.

No double-evaluation in test

Tests run with FLAG_RBAC_V2 forced on for V2 tests and forced off for legacy tests via the existing conftest fixture. Shadow dual-mode is removed in S1.

8. Rollback

Rollback after a sub-card's PR is merged and deployed requires redeploying the previous SHA.

Pre-cutover action (required): Before any sub-card is promoted to prod, tag the last all-legacy SHA:

git tag rbac-legacy-baseline <sha>
git push origin rbac-legacy-baseline

Rollback command (prod emergency):

git push heroku rbac-legacy-baseline:main

FLAG_RBAC_V2 alone is not sufficient as a live rollback once decorators are replaced (evaluated at startup). The flag remains meaningful as a staging deployment gate.

Low-tech per-file rollback: Feature-developer keeps the legacy @require_role on a commented line directly above the new @require_rbac_role for all TOTP-elevation routes. A two-line change re-activates legacy without a full redeploy.

9. Security Considerations

• PII: No PII is collected or exposed. Decorators read admin_id from session (UUID).
• Retention: Audit rows from _write_access_denied are unchanged in schema and retention.
• Deletion on DSR: No new tables introduced.
• Audit trail: Every 403 continues to write an access_denied audit row. V2 and legacy decorators both call _write_access_denied. Audit coverage is not reduced.
• Stored credentials: None. V2 resolution reads live from rbac_* tables per request.
• Breach notification: No change to existing breach path.
• Kill-switch: FLAG_RBAC_V2=0 + redeploy previous SHA (see §8).
• Over-exposure risk: Primary risk is mapping a superadmin-only gate to a V2 role held by a broader group. Every console-manager mapping in this document is held only by raxx-platform-admins and break-glass, which is the correct superadmin-equivalent scope. The AMBIGUOUS items in §4 are the only sites where over-exposure is not yet ruled out — they must be resolved before the affected sub-cards are claimed.

10. Open Questions

These must be resolved on issue #1473 before implementation of the blocked sub-cards.

1. AMBIGUOUS-1: Should session revocation (/admins/online/<id>/revoke) live under console-invite-admin or a new console-session-admin role? (Blocks S1, S7)
2. AMBIGUOUS-2: Should beta management use console-manager or a new console-beta-admin role? (Blocks S3)
3. AMBIGUOUS-3: What role governs customer session revocation (POST /console/customers/<id>/<session_id>/revoke) — console-manager, console-invite-admin, or a new console-customers-write? (Blocks S3)
4. AMBIGUOUS-4: How is the POST /api/internal/deploys prod-vs-staging split implemented — single broadest role, inline check, or route split? (Blocks S4)
5. console-ops group assignment: Migration 0012 defines console-ops but assigns it to no group. Is this intentional? If raxx-devops-team or raxx-platform-admins needs ops-tier access via a composition role rather than individual role grants, a new group assignment migration may be required before cutover. (Pre-cutover verification)
6. Machine-token compatibility: Routes decorated with @machine_auth_or_session set g.admin from a machine token. Machine tokens have no rbac_user_groups rows. Will they pass _admin_has_rbac_role()? If not, machine tokens must be enrolled in an RBAC group before S5 ships. (Blocks S5)