ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
e5ad9b6cf8
TenantAtlas/specs/066-rbac-ui-enforcement-helper/spec.md
Ahmed Darrazi e5ad9b6cf8 spec: 066 rbac ui enforcement helper v1
2026-01-28 23:10:49 +01:00

9.6 KiB
Raw Blame History

Feature Specification: RBAC UI Enforcement Helper v1

Feature Branch: 066-rbac-ui-enforcement-helper
Created: 2026-01-28
Status: Draft
Input: Provide a suite-wide, consistent way to enforce tenant RBAC for admin UI actions (buttons/actions in lists, records, and bulk actions) without copy/paste authorization logic.

User Scenarios & Testing (mandatory)

User Story 1 - Tenant member sees consistent disabled UX (Priority: P1)

As a tenant member, I can clearly see which actions exist, and when I lack permission the action is visible but disabled with an explanatory tooltip.

Why this priority: Prevents confusion and reduces support load while keeping the UI predictable for members.

Independent Test: Can be tested by visiting a tenant-scoped admin page as a member with insufficient permissions and verifying the action is disabled, shows the standard tooltip, and cannot be executed.

Acceptance Scenarios:

  1. Given a tenant member without the required capability, When they view an action on a tenant-scoped page, Then the action is visible but disabled and shows the standard “insufficient permission” tooltip.
  2. Given a tenant member without the required capability, When they attempt to execute the action (including direct invocation, bypassing the UI), Then the server rejects with 403.

User Story 2 - Non-members cannot infer tenant resources (Priority: P2)

As a non-member of a tenant, I cannot discover tenant-scoped resources or actions; the system responds as “not found”.

Why this priority: Prevents tenant enumeration and cross-tenant information leakage.

Independent Test: Can be tested by attempting to access tenant-scoped pages/actions as a user without membership and verifying 404 behavior.

Acceptance Scenarios:

  1. Given a user who is not entitled to the tenant scope, When they attempt any tenant-scoped page or action, Then the system responds as 404 (deny-as-not-found).

User Story 3 - Maintainers add actions safely by default (Priority: P3)

As a maintainer, I can add new tenant-scoped actions using one standard pattern, and regression guards prevent introducing ad-hoc authorization logic.

Why this priority: Reduces RBAC regressions as the app grows and makes reviews easier.

Independent Test: Can be tested by introducing a sample ad-hoc authorization pattern and confirming automated checks/tests flag it.

Acceptance Scenarios:

  1. Given a maintainer adds a new tenant-scoped action, When they use the central enforcement helper, Then member/non-member semantics and tooltip behavior match the standard without additional per-page customization.
  2. Given a maintainer introduces a new ad-hoc authorization mapping in tenant-scoped admin UI code, When automated checks run, Then the change is flagged to prevent drift.

[Add more user stories as needed, each with an assigned priority]

Edge Cases

  • Membership is revoked while the user has the page open (execution must still enforce 404 semantics).
  • Capability changes mid-session (UI may be stale; server enforcement remains correct).
  • Bulk actions with mixed-permission records (the safe default behavior is enforced consistently).
  • Target record is deleted/archived between render and execution (no information leakage in errors).

Requirements (mandatory)

Constitution alignment (required): If this feature introduces any Microsoft Graph calls, any write/change behavior, or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates (preview/confirmation/audit), tenant isolation, run observability (OperationRun type/identity/visibility), and tests. If security-relevant DB-only actions intentionally skip OperationRun, the spec MUST describe AuditLog entries.

Constitution alignment (RBAC-UX): This feature defines a default pattern for tenant-plane admin actions. The implementation MUST:

  • enforce membership as an isolation boundary (non-member / not entitled → 404 deny-as-not-found),
  • enforce capability denials as 403 (after membership is established),
  • keep actions visible-but-disabled with a standard tooltip for members lacking capability (except allowed sensitive exceptions),
  • enforce authorization server-side for every mutation/operation-start/credential change,
  • use the canonical capability registry (no raw capability string literals),
  • ensure destructive-like actions require confirmation,
  • ship regression tests and a guard against new ad-hoc authorization patterns.

Constitution alignment (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP (e.g., token exchange) on /auth/* endpoints without an OperationRun. This MUST NOT be used for Monitoring/Operations pages.

Constitution alignment (BADGE-001): If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean), the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values.

Functional Requirements

  • FR-001: The system MUST provide a single, centrally maintained enforcement mechanism that can be applied to tenant-scoped admin actions (including header actions, record actions, and bulk actions).
  • FR-002: For tenant-scoped actions, the system MUST enforce membership as deny-as-not-found: users not entitled to the tenant scope MUST receive 404 semantics for action execution.
  • FR-003: For tenant members, the system MUST enforce capability denial as 403 when executing an action without permission.
  • FR-004: For tenant members lacking capability, the UI MUST render actions as visible-but-disabled and MUST show a standard tooltip explaining the missing permission.
  • FR-005: The enforcement mechanism MUST also enforce the same rules server-side (UI state is never sufficient).
  • FR-006: The enforcement mechanism MUST be capability-first and MUST reference capabilities only via the canonical capability registry (no ad-hoc string literals).
  • FR-007: The enforcement mechanism MUST provide a standard confirmation behavior for destructive-like actions, including a clear warning message.
  • FR-008: The system MUST provide standardized, non-leaky error and tooltip messages:
    • 404 semantics for non-members without hints.
    • 403 responses for insufficient capability without object details.
  • FR-009: v1 MUST include limited adoption by migrating 3–6 exemplar action surfaces to the new pattern to prove the approach.
  • FR-010: v1 MUST include regression tests that cover: non-member → 404, member without capability → disabled UI + 403 on execution, member with capability → allowed.
  • FR-011: v1 SHOULD include an automated guard that flags new ad-hoc authorization patterns in tenant-scoped admin UI code.
  • FR-012: The enforcement mechanism MUST avoid introducing avoidable performance regressions (no per-record membership lookups during render).
  • FR-013: The enforcement mechanism MUST NOT trigger outbound HTTP calls during render; it is DB-only.

Key Entities (include if feature involves data)

  • Tenant: The isolation boundary for all tenant-scoped UI and actions.
  • User: The authenticated actor attempting to view or execute actions.
  • Membership: Whether a user is entitled to a tenant scope.
  • Capability: A named permission from the canonical capability registry.
  • Action: A discrete operation exposed in the tenant-scoped admin interface.

Assumptions

  • Default tooltip language is English (i18n may be added later).
  • Non-destructive bulk actions are in scope for v1; destructive bulk actions may be supported but are not required for v1 completion.
  • Global search tenant scoping is out of scope for this spec (covered by separate work), but this feature must not introduce new leaks.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: For all migrated tenant-scoped action surfaces, 100% of non-member execution attempts are denied with 404 semantics (verified by automated tests).
  • SC-002: For all migrated tenant-scoped action surfaces, 100% of member-but-unauthorized execution attempts are denied with 403 (verified by automated tests).
  • SC-003: For all migrated tenant-scoped action surfaces, members lacking capability see the action visible-but-disabled with the standard tooltip (verified by automated tests and/or UI assertions).
  • SC-004: At least one automated guard exists that flags newly introduced ad-hoc authorization patterns in tenant-scoped admin UI code.
  • SC-005: v1 demonstrates adoption by migrating 3–6 exemplar action surfaces, reducing duplicate authorization wiring in those areas.