From e5ad9b6cf8f8c05487fe37d5b256c008e8c732d9 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Wed, 28 Jan 2026 23:10:49 +0100 Subject: [PATCH] spec: 066 rbac ui enforcement helper v1 --- .../checklists/requirements.md | 34 ++++ specs/066-rbac-ui-enforcement-helper/spec.md | 153 ++++++++++++++++++ 2 files changed, 187 insertions(+) create mode 100644 specs/066-rbac-ui-enforcement-helper/checklists/requirements.md create mode 100644 specs/066-rbac-ui-enforcement-helper/spec.md diff --git a/specs/066-rbac-ui-enforcement-helper/checklists/requirements.md b/specs/066-rbac-ui-enforcement-helper/checklists/requirements.md new file mode 100644 index 0000000..91ef52d --- /dev/null +++ b/specs/066-rbac-ui-enforcement-helper/checklists/requirements.md @@ -0,0 +1,34 @@ +# Specification Quality Checklist: RBAC UI Enforcement Helper v1 + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-01-28 +**Feature**: [specs/066-rbac-ui-enforcement-helper/spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- No blockers found in this iteration. diff --git a/specs/066-rbac-ui-enforcement-helper/spec.md b/specs/066-rbac-ui-enforcement-helper/spec.md new file mode 100644 index 0000000..0015978 --- /dev/null +++ b/specs/066-rbac-ui-enforcement-helper/spec.md @@ -0,0 +1,153 @@ +# 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.