TenantAtlas/specs/127-rbac-inventory-backup/spec.md

# Feature Specification: Intune RBAC Inventory & Backup v1

**Feature Branch**: `127-rbac-inventory-backup`  
**Created**: 2026-03-09  
**Status**: Draft  
**Input**: User description: "Add Intune RBAC Role Definitions and Role Assignments as Foundation Types with inventory sync and immutable backup/versioning"

## Spec Scope Fields

- **Scope**: tenant
- **Primary Routes**: Existing tenant inventory sync flow, tenant inventory coverage views, tenant backup set detail views, tenant policy version history/detail views for foundation-backed snapshots, restore preview/detail surfaces for foundation-backed items, and provider verification surfaces that explain missing Graph permissions.
- **Data Ownership**: Tenant-owned inventory records, tenant-owned coverage rows, tenant-owned backup items, immutable tenant-owned version snapshots, and tenant/provider verification outcomes bound to a workspace and tenant.
- **RBAC**: Tenant/Admin plane only. Viewing tenant-scoped RBAC inventory, coverage, backups, and versions requires established workspace and tenant membership. Existing canonical capability registry continues to govern inventory sync start, provider verification visibility, backup visibility, and version inspection. Non-members must receive 404 deny-as-not-found behavior; members lacking the required capability must receive 403.

## User Scenarios & Testing

### User Story 1 - Capture Intune RBAC Inventory (Priority: P1)

As an MSP or enterprise admin, I can run the existing tenant inventory flow and have Intune Role Definitions and Intune Role Assignments captured as first-class Foundation Types so I can see the tenant's RBAC model.

**Why this priority**: Inventory visibility is the core product value for v1 and the prerequisite for every later RBAC governance workflow.

**Independent Test**: Can be fully tested by running a tenant inventory sync with mocked RBAC responses and verifying that both RBAC object families are stored, categorized, and surfaced without needing backup or restore behavior.

**Acceptance Scenarios**:

1. **Given** a tenant with readable Intune RBAC data, **When** an inventory sync runs, **Then** Role Definitions are captured as `intuneRoleDefinition` foundation items with readable summaries and tenant-scoped metadata.
2. **Given** a tenant with readable Intune RBAC data, **When** an inventory sync runs, **Then** Role Assignments are captured as `intuneRoleAssignment` foundation items with readable summaries and tenant-scoped metadata.
3. **Given** an inventory coverage view for a tenant, **When** the sync completes, **Then** both RBAC foundation types appear under the RBAC category alongside their support and capture state.

---

### User Story 2 - Review Immutable RBAC History (Priority: P1)

As an auditor or security-conscious admin, I can inspect backup and version history for Intune RBAC objects so I can reconstruct what the tenant's role model looked like at a given point in time.

**Why this priority**: Immutable history closes the governance gap even before compare or restore is introduced.

**Independent Test**: Can be fully tested by capturing a backup/version run after inventory and confirming that RBAC objects appear in backup/version surfaces with immutable, readable snapshot content.

**Acceptance Scenarios**:

1. **Given** a tenant with RBAC inventory data, **When** a backup/version capture runs, **Then** Role Definitions and Role Assignments are stored as immutable foundation-backed snapshots.
2. **Given** a stored Role Definition snapshot, **When** an admin opens its normalized content, **Then** the snapshot clearly shows name, description, built-in versus custom state, and readable permissions structure.
3. **Given** a stored Role Assignment snapshot, **When** an admin opens its normalized content, **Then** the snapshot clearly shows the assigned role, principals or members, scope members, and resource scopes.

---

### User Story 3 - Preserve Safe Read-Only Governance Posture (Priority: P2)

As an operator, I can see that RBAC is covered and historically preserved without being offered an unsafe write or restore path before the product has dedicated RBAC safety gates.

**Why this priority**: Safe product positioning matters for a governance feature touching high-risk access structures.

**Independent Test**: Can be fully tested by validating restore-adjacent surfaces and provider verification behavior without requiring any new RBAC write capability.

**Acceptance Scenarios**:

1. **Given** an RBAC backup item, **When** an admin reviews restore options, **Then** both RBAC foundation types are shown as preview-only and no executable restore action is presented.
2. **Given** a tenant whose provider lacks `DeviceManagementRBAC.Read.All`, **When** sync or verification runs, **Then** the system records a clear warning or reason for RBAC coverage without crashing the run pipeline.
3. **Given** a user outside the current workspace or tenant scope, **When** they attempt to access RBAC inventory or version data, **Then** the system responds as not found and does not leak RBAC object existence.

### Edge Cases

- Built-in role definitions with minimal custom fields must still normalize into a readable, diff-safe summary.
- Role assignments that reference deleted or unresolved principals, scope tags, or resource scopes must preserve stable fallback identifiers rather than dropping the reference.
- Missing `DeviceManagementRBAC.Read.All` must mark RBAC coverage as unavailable or warning-state without aborting unrelated inventory families.
- If role definitions are readable but role assignments fail for a recoverable reason, the run must preserve partial RBAC visibility with a clear reason instead of silently reporting full success.
- Existing coverage, backup, and version surfaces must remain tenant-scoped so RBAC metadata cannot appear in workspace-only or cross-tenant contexts.

## Requirements

**Constitution alignment (required):** This feature extends Microsoft Graph-backed tenant inventory and snapshot flows. Contract registry updates are required for both RBAC object families, restore safety remains preview-only, tenant isolation remains mandatory, and the existing inventory and backup `OperationRun` flows continue to provide run observability and auditability. No new RBAC write path is introduced.

**Constitution alignment (OPS-UX):** This feature reuses existing inventory sync and backup/version `OperationRun` flows. The implementation must preserve the three-surface feedback contract: queued-only toasts, progress only in the active-ops widget and run detail surfaces, and initiator-only terminal DB notifications. `OperationRun.status` and `OperationRun.outcome` remain service-owned through `OperationRunService`, summary counts remain numeric and limited to canonical keys, and scheduled or system-run behavior remains unchanged. Regression coverage must confirm these reused flows remain compliant after RBAC types are added.

**Constitution alignment (RBAC-UX):** The feature affects the Tenant/Admin plane only. Tenant-context access under `/admin/t/{tenant}/...` and tenant-aware canonical monitoring or coverage views must preserve deny-as-not-found semantics for non-members and 403 semantics for members missing the required capability. All visibility and operation-start checks remain server-side via existing gates or policies and the canonical capability registry. No raw capability strings or role-string checks may be introduced. Existing global search safety rules remain unchanged because no dedicated RBAC resource is added in v1.

**Constitution alignment (BADGE-001):** Any new or reused risk, restore-mode, support-state, or availability badges for RBAC types must use centralized badge semantics. If RBAC introduces new badge values, the badge mapper and regression tests must be updated in the same change.

**Constitution alignment (Filament Action Surfaces / UX-001):** No new Filament resource, relation manager, or standalone RBAC screen is introduced. Existing inventory coverage and backup/version detail surfaces are only extended with additional RBAC rows, summaries, and preview-only labeling. Existing action surfaces, layouts, empty states, and inspection affordances must remain intact; the UI Action Matrix below documents the affected surfaces and confirms that no new destructive action is introduced.

**Constitution alignment (UI-STD-001):** This feature modifies existing list and detail surfaces, so review must follow `docs/product/standards/list-surface-review-checklist.md` for the inventory coverage, backup set detail, and policy version history/detail surfaces touched by this change.

### Functional Requirements

- **FR-001**: The system must register `intuneRoleDefinition` and `intuneRoleAssignment` as separate Foundation Types with labels, platform metadata, risk level, restore mode, and inventory/backup participation metadata consistent with existing Foundation Types.
- **FR-002**: The system must expose RBAC as a dedicated semantic category so both RBAC Foundation Types appear under RBAC in coverage and related presentation rather than being folded into a generic foundations label.
- **FR-003**: The system must define inventory-grade Graph contract entries for Intune Role Definitions and Intune Role Assignments that are suitable for full snapshot fidelity rather than minimal health checks.
- **FR-004**: The Role Definition contract must support retrieving the stable fields needed for immutable history and readable display, including identifier, display name, description, built-in versus custom state, and permissions data.
- **FR-005**: The Role Assignment contract must support retrieving the stable fields needed for immutable history and readable display, including identifier, display name, description when present, linked role definition reference, principals or members, scope members, resource scopes, and stable type metadata for referenced principals and scopes.
- **FR-006**: Existing legacy or health-check-oriented RBAC contract keys must remain backward compatible. If separate inventory-grade keys are required, they must coexist without silently changing the meaning of existing health-check flows.
- **FR-007**: All RBAC Graph reads introduced by this feature must continue to flow through `GraphClientInterface` and the contract registry; feature code must not hardcode RBAC endpoints outside the registry.
- **FR-008**: The existing tenant inventory sync flow must capture both RBAC Foundation Types without creating a new standalone RBAC workflow.
- **FR-009**: Inventory sync must persist tenant-scoped inventory results for both RBAC Foundation Types using the existing provider, contract, and normalization model.
- **FR-010**: Backup and version capture must create immutable RBAC snapshots for both Foundation Types using the existing foundation-backed snapshot model, including backup items and tenant-scoped version history entries.
- **FR-011**: Backup sets must include both RBAC Foundation Types as foundation-backed items using the same backup item semantics applied to other supported foundation objects.
- **FR-012**: Coverage must track `coverage.foundation_types.intuneRoleDefinition` and `coverage.foundation_types.intuneRoleAssignment` and present them under the RBAC category.
- **FR-013**: Role Definition normalization must produce human-readable output that includes the role name, description, built-in versus custom indicator, and a stable normalized permissions structure suitable for audit review and future diffs.
- **FR-014**: Role Assignment normalization must produce human-readable output that includes assignment name, assigned role, principals or members, scope members, and resource scopes.
- **FR-015**: Reference-aware RBAC normalization must prefer readable related-object names when practical, but must fall back to stable identifiers when Microsoft Graph does not provide a readable expansion so snapshots stay understandable and diff-safe.
- **FR-016**: Both RBAC Foundation Types must be visible through existing inventory, coverage, backup set detail, and policy version history/detail surfaces without introducing a dedicated RBAC CRUD resource in v1.
- **FR-017**: Both RBAC Foundation Types must be configured as `preview-only` for restore and must not expose any executable restore path in v1.
- **FR-018**: If `DeviceManagementRBAC.Read.All` is missing, provider verification and sync outcomes must record a clear warning or reason for RBAC coverage rather than failing with an opaque system error.
- **FR-019**: RBAC inventory, backup, coverage, and version data must remain strictly bound to existing workspace and tenant isolation rules, with no cross-tenant leakage in storage or presentation.
- **FR-020**: Adding RBAC Foundation Types must not degrade existing inventory, coverage, backup, or version behavior for currently supported types.
- **FR-021**: The feature must not introduce any Intune RBAC write, restore-execution, drift, compare, or cross-tenant comparison path in v1.
- **FR-022**: Any authorization checks touched by RBAC visibility or operation-start surfaces must continue to enforce canonical capability registry usage, 404 semantics for non-members, and 403 semantics for in-scope members missing required capability.
- **FR-023**: Reused inventory sync and backup/version operations must remain observable through existing `OperationRun` behavior, including canonical summary-count keys, service-owned lifecycle transitions, and initiator-only terminal notifications.

### Non-Goals

- No restore execution for Role Definitions or Role Assignments.
- No RBAC baseline compare, drift detection, findings, or alerts.
- No dedicated Filament CRUD resource or separate RBAC operational workflow.
- No Entra RBAC or Entra role backup scope.
- No expansion of Scope Tag functionality beyond referencing existing data already supported elsewhere.

### Assumptions

- Existing tenant inventory sync and backup/version workflows already provide the operational entry points needed to add new Foundation Types.
- Existing canonical capabilities already cover tenant inventory sync, provider verification, backup visibility, and version inspection for the affected surfaces.
- Microsoft Graph returns enough stable RBAC read data to preserve immutable snapshots even when some related objects can only be represented by identifiers.
- Scope Tags remain managed by existing functionality and are only referenced as related governance context by RBAC assignments in this v1.

### Dependencies

- Existing provider and contract registry architecture.
- Existing tenant inventory sync pipeline.
- Existing immutable backup and version capture model.
- Existing coverage aggregation for foundation types.
- Existing preview-only restore semantics and restore-surface gating.

## UI Action Matrix

This spec modifies existing list surfaces and therefore uses `docs/product/standards/list-surface-review-checklist.md` as the review checklist for inventory coverage, backup set detail, and policy version history/detail changes.

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Inventory Coverage | Existing tenant inventory coverage screen | No new actions introduced | Existing coverage inspection pattern remains unchanged | No new row actions introduced | None introduced | Existing sync/run CTA remains the single empty-state CTA | N/A | N/A | Existing inventory sync `OperationRun` and audit trail remain in force | Change is limited to RBAC category rows, labels, and support state presentation; Action Surface Contract remains satisfied by the existing surface. |
| Backup Set Detail and Policy Version Detail | Existing tenant backup set detail and policy version detail screens | No new actions introduced | Existing item preview/detail affordance remains unchanged | Existing preview or view behavior only; no execute restore action for RBAC items | None introduced | Existing backup or capture CTA remains unchanged | Existing preview/view actions only | N/A | Existing backup/version `OperationRun` and audit trail remain in force | Change is limited to additional RBAC items, readable normalized content, and visible preview-only restore labeling. |
| Provider Verification / Support Detail | Existing provider or verification detail surfaces | No new actions introduced | Existing provider detail inspection remains unchanged | No new row actions introduced | None introduced | Existing verification CTA remains unchanged | Existing detail affordances unchanged | N/A | Existing verification logging remains in force | Surface adds a readable warning or reason for missing `DeviceManagementRBAC.Read.All` without adding new action patterns. |

## Key Entities

- **Intune Role Definition Inventory Item**: The tenant-scoped representation of a built-in or custom Intune role definition, including stable identity, descriptive metadata, built-in versus custom state, and readable permission structure.
- **Intune Role Assignment Inventory Item**: The tenant-scoped representation of an Intune role assignment, including stable identity, linked role definition, principals or members, scope members, resource scopes, and stable fallback references.
- **RBAC Snapshot Version**: An immutable historical record of a Role Definition or Role Assignment captured through the existing foundation-backed snapshot model for audit and version history.
- **RBAC Coverage Entry**: The tenant-scoped support and capture status for each RBAC Foundation Type within `coverage.foundation_types`.

## Success Criteria

### Measurable Outcomes

- **SC-001**: In a tenant with RBAC read access, one normal inventory sync cycle is sufficient for admins to see both Role Definitions and Role Assignments represented in coverage and tenant-scoped inventory views without using a separate RBAC workflow.
- **SC-002**: 100% of stored Role Definition snapshots produced by the feature show a readable built-in versus custom indicator and a readable permissions summary.
- **SC-003**: 100% of stored Role Assignment snapshots produced by the feature show the assigned role and assignment scope details, using stable fallback identifiers whenever readable expansions are unavailable.
- **SC-004**: For tenants lacking `DeviceManagementRBAC.Read.All`, verification or sync surfaces show an explicit RBAC warning or reason and complete without an unhandled failure or cross-tenant data leak.
- **SC-005**: RBAC backup items never present an executable restore action in v1; they remain clearly labeled as preview-only across affected restore-adjacent surfaces.