RBAC Antlers Surface Audit — Flag Inventory, Gap Report, and Denied-State Remediation

Status: Draft — awaiting operator review
Owner: software-architect
Date: 2026-05-14 UTC
Refs: #1449 (this card), #81 (SDLC epic), #970–#974 (RBAC phase cards), docs/architecture/rbac-design.md, docs/architecture/auth-unification-rbac-reconciliation.md

1. Context

Raxx today has no RBAC enforcement on Antlers (the customer-facing app). Every feature flag that controls a customer-facing Antlers surface is a global binary: ON for all authenticated users, or OFF for all authenticated users. As the platform moves toward a first external customer on 2026-05-23 UTC, three problems must be addressed before or shortly after launch:

1. Global flags cannot express per-role access. The onboarding wizard, route guard, and passkey flows should be gated on authenticated customer role, not a global flag.
2. The "Coming soon" pattern is live in Settings. Two flag-backed surfaces (options_backtest, live_mode_ring) display a visible "Coming soon" badge when the flag is OFF. This violates the locked invariant (2026-05-11 UTC): denied surfaces must be hidden, not grayed, badged, or "upgrade-to-unlock" framed.
3. No permission name exists for any Antlers surface. The role taxonomy in rbac-design.md defines antlers-user, antlers-founders, antlers-pro tiers but no per-feature permission names. RBAC-aware flag resolution is Phase 2; this audit establishes the recommended permission names before Phase 2 implementation.

This document does not ship code. It is a pre-condition for dispatching implementation sub-cards.

2. Invariants (non-negotiable)

The following constraints govern every recommendation in this document:

• No single-user direct access. Permissions flow user → group → role → permission. A check against a bare user ID must not exist.
• Denied Antlers surfaces are hidden, not grayed. A surface the user's role does not grant is simply absent from the UI. No badge, no "Coming soon," no disabled button with a tooltip. (Memory anchor: feedback_hide_dont_gray_unavailable_features, locked 2026-05-11 UTC.)
• Superadmin is break-glass only. No feature access flows through superadmin as a working gate.
• Paper-first gating applies to all live-execution surfaces. Any flag that touches order entry or live-mode state must respect the paper-profitable-for-N-cycles gate.
• No stored credentials. Nothing in this model may store or replay an auth credential.
• GDPR by default. PII fields implied by role metadata follow the same retention and erasure rules as the rest of the platform.

3. Flag Inventory — Antlers Customer-Facing Surfaces

Scope: All flags where surface: antlers in feature_flags.yaml, plus flags on other surfaces (raptor, status-page) where the flag directly gates a customer-visible Antlers UI behavior. Console, Velvet, Queue, and CI flags are out of scope.

Total flags in file: 131 (as of 2026-05-14 UTC)
Flags with surface: antlers: 31
Flags on other surfaces with direct Antlers UI impact: 4 (noted below)
Flags audited: 35

3.1 Auth and Session Surfaces

3.2 App Shell and Navigation Surfaces

3.3 Trading Surfaces

3.4 Backtesting Surfaces

3.5 AI Surfaces

3.6 Onboarding and First-Run Surfaces

3.7 Demo and Marketing Surfaces (pre-auth / public)

3.8 Privacy and Consent Surfaces

3.9 Observability and Auth Backend Flags with Antlers UI Impact

These flags live on surface: raptor or surface: antlers but directly govern what Antlers renders:

3.10 Flags Not Yet in App.js (UI not yet wired)

These flags are defined in feature_flags.yaml with surface: antlers but do not appear in current App.js routing or visible component files:

4. Recommended RBAC Permission Names

Where a flag will eventually need per-role enforcement, the following permission names are proposed following the <app>-<resource>-<level> convention from rbac-design.md:

Phase 2 note: These permission names are for planning purposes. Phase 2 (per-role flag resolution) must confirm B1 enforcement compatibility before any permission-conditional flag resolution ships.

5. Denied-State Audit — Current Gray/Disable Violations

This section inventories surfaces that currently show a grayed, badged, or "Coming soon" affordance when the controlling flag is OFF. Each is a violation of the locked invariant (2026-05-11 UTC) and requires a remediation card before v1 launch.

Gap 1: Settings → Platform Features — "Coming soon" badges (Settings.js, lines 617–638)

Location: frontend/trademaster_ui/src/pages/Settings.js, Settings → Platform Features tab
Current behavior:
- When options_backtest is OFF: "Options Backtesting" row renders with a gray secondary badge reading "Coming soon" and a tooltip explaining the licensing status. - When live_mode_ring is OFF: "Live Mode Ring" row renders with a gray secondary badge reading "Coming soon."

Violation: Both rows are visible to all authenticated users regardless of flag state. The platform is communicating "this exists but you can't have it yet" — exactly the framing the invariant prohibits.

Required remediation: - When options_backtest is OFF: hide the entire "Options Backtesting" row entirely. No badge, no tooltip, no row. - When live_mode_ring is OFF: hide the entire "Live Mode Ring" row, AND hide the "Sentinel ring" nav item in the Settings left nav (line 348, already conditionally rendered — confirm it is gated correctly). - The introductory copy ("Features shown as 'Coming soon' are in active development...") must also be removed or revised once the rows are hidden, since it describes the pattern being eliminated.

Remediation card: See sub-card recommendation in §6 (Gap-1 card).

Gap 2: console_drawer_actions flag — "Re-check disabled + tooltip for roles below ops"

Location: backend_v2/api/feature_flags.yaml line 555, flag console_drawer_actions
Surface: surface: console — this is a console flag, NOT an Antlers customer-facing flag.
Assessment: Out of scope for this audit. The console drawer actions gray pattern is an operator-facing surface. The hide-don't-gray rule applies to customer-facing Antlers surfaces; console surfaces for operators have different UX conventions. No remediation required under this audit.

Gap 3: antlers_demo_mode — referenced in code but absent from feature_flags.yaml

Location: frontend/trademaster_ui/src/context/DemoContext.js line 28
Current behavior: DemoContext.js calls isEnabled('antlers_demo_mode'). This flag name does not exist in feature_flags.yaml. When window.__FLAGS__ does not define it, the flag silently defaults to false — demo mode is globally disabled.
Risk: Undefined flag behavior. If demo mode is intended to be active, it may silently not work. If it is intentionally not in the YAML (because it is set some other way), that should be documented.
Assessment: Not a denied-state violation, but a flag inventory gap. See §7 (open questions).

6. v1 RBAC Gaps — Must-Fix Before 2026-05-23 UTC Launch

These are the items that must be resolved before first external user:

v1 RBAC gap count: 6 (G-1 through G-6)

Note: G-2 through G-5 are operational flips, not code changes, assuming the underlying feature work is complete. G-1 requires a code change in Settings.js. G-6 is an operational flip.

7. Open Questions (require operator decision before sub-cards are claimed)

1. antlers_demo_mode flag registration. DemoContext.js references isEnabled('antlers_demo_mode') but the flag is absent from feature_flags.yaml. Is this flag intentionally managed outside the YAML (e.g., derived from demo_flow_ui), or is it a missing entry? Operator must decide: add a YAML entry or remove the isEnabled call and derive demo-mode state from demo_flow_ui directly.

2. options_backtest row: hide entirely or hide until licensing resolves? The audit recommends hiding the row when the flag is OFF. However, if Kristerpher wants a waitlist-capture affordance for users interested in options backtesting (similar to the Quebec waitlist pattern), the treatment changes. Current recommendation: hide entirely; no waitlist row. Confirm.

3. antlers_obfuscate_mode scope. Currently global ON/OFF. Should it be available to all authenticated users (any tier), or restricted to a specific tier? Recommend: available to all antlers-user-and-above. If restricted to antlers-pro, a denied-state gap would be created (the toggle must be hidden for non-pro users). Operator must lock this before Phase 2 RBAC implementation.

4. advanced_risk_metrics, walk_forward_validation, custom_strategy_sandbox tier assignment. Are these antlers-pro-only or available to all authenticated users at v1? If pro-only, the denied-state treatment for non-pro users is: these options are simply absent from the backtest form. Operator must confirm tier assignment before permission names are finalized.

5. ai_proposer tier. Same question as above. Given the product thesis (AI augments understanding, never autonomous execution), this surface may be appropriate for all authenticated users or only pro. Confirm.

6. B1 compatibility of role-conditional flag resolution. Phase 2 (per-role flag resolution) must confirm that adding role conditions to flag evaluation does not break B1 enforcement (every flag in feature_flags.yaml must have a console_flag_promotions migration row before prod flip). This is a design constraint on Phase 2, not Phase 1.

8. Rollout Compatibility

All flags audited here are currently global ON/OFF. No schema migrations are required to implement the denied-state remediations (G-1 is a React render change only). The RBAC phase is Phase 2 and is not a prerequisite for v1 launch, except where explicitly marked as a blocker above.

The flag reconciler (ADR-0085) is not affected by this audit. Flag values themselves are not changed by this document.

9. Security Considerations

• The route guard (route_guard flag) is the sole client-side access gate for authenticated routes. When OFF, all authenticated routes are publicly accessible. This is acceptable pre-launch in development but must be ON before any customer receives a login link.
• Geographic gates (quebec_geoblock, signup_geoblock_eu) are defense-in-depth only. Server-side enforcement in Raptor is the authoritative gate; client-side is a UX layer.
• No PII is stored or transmitted by any flag in this audit. The antlers_obfuscate_mode flag operates on the render layer only; the backend always sends real values.
• Session state (antlers-user role, onboarding_completed) must be derived from the session token issued by Queue/Raptor after passkey authentication, not from client-only localStorage. The route guard's reliance on localStorage as a fallback (when the session endpoint is not yet live) is a known gap tracked by the auth team.

10. Related Documents

• docs/architecture/rbac-design.md — role taxonomy and data model
• docs/architecture/auth-unification-rbac-reconciliation.md — RBAC V2 phase map
• docs/architecture/auth.md — auth flow design
• docs/architecture/adr/0020-rbac-groups-not-direct-roles.md — centralized identity decision
• docs/architecture/adr/0031-platform-auth-posture.md — WebAuthn-only gate
• docs/architecture/adr/0032-customer-account-recovery-a-plus-b-only.md — recovery path constraint

Awaiting operator review. No code changes will be dispatched from this audit until Kristerpher approves.