TenantAtlas/specs/104-provider-permission-posture/spec.md

# Feature Specification: Provider Permission Posture

**Feature Branch**: `104-provider-permission-posture`
**Created**: 2026-02-26
**Status**: Draft
**Input**: User description: "Provider Permission Posture - StoredReports foundation, Permission Posture Findings generation, and Alerts integration for measured app permissions"

## Spec Scope Fields *(mandatory)*

- **Scope**: tenant (per-tenant posture assessment) + workspace (stored reports and alerts extend workspace-level infrastructure)
- **Primary Routes**:
  - No new Filament pages in this spec; findings and stored reports are backend data consumed by existing Findings/Alerts UI
  - Existing: Monitoring > Findings (extended with `finding_type=permission_posture`)
  - Existing: Monitoring > Alerts (extended with new `EVENT_PERMISSION_MISSING` event type)
- **Data Ownership**:
  - `stored_reports` -- workspace-owned, generic report storage (new table)
  - `findings` -- tenant-owned, extended with `finding_type=permission_posture` (existing table)
  - `tenant_permissions` -- tenant-owned, source of truth for measured permission state (existing table)
  - `alert_rules` -- workspace-owned, extended with `EVENT_PERMISSION_MISSING` trigger (existing table)
- **RBAC**:
  - Workspace membership is required for any access (non-members receive 404)
  - Viewing posture findings uses existing `FINDINGS_VIEW` capability
  - Acknowledging posture findings uses existing `FINDINGS_MANAGE` capability
  - Alert rules for permission events use existing `ALERTS_VIEW` / `ALERTS_MANAGE` capabilities
  - No new RBAC capabilities are introduced

## Assumptions and Dependencies

- **TenantPermissionService** already performs live permission checks via Microsoft Graph and persists results to `tenant_permissions`. That flow is unchanged; this spec reads its output.
- **DriftFindingGenerator** establishes the fingerprint-based idempotent upsert pattern for findings. The new `PermissionPostureFindingGenerator` follows the same pattern.
- **Alerts v1** (Spec 099) provides the generic `AlertDispatchService` and `EvaluateAlertsJob` framework. This spec adds a new event type; no structural changes to alerting.
- **`config/intune_permissions.php`** is the single registry of required permissions (14 entries, all `type: application`). The posture generator reads this registry to know what to expect.
- **`findings.source`** column was added in a recent migration but is not currently populated. This spec uses it to tag posture findings (`source=permission_check`).

## User Scenarios and Testing *(mandatory)*

### User Story 1 - Generate permission posture findings (Priority: P1)

As a workspace operator, after my tenant's permissions have been checked, I want the system to automatically generate findings for any missing or degraded permissions so that I can see permission gaps alongside drift findings.

**Why this priority**: This is the core value. Without posture findings, nothing downstream (alerts, reports) has data to work with.

**Independent Test**: Run the posture finding generator for a tenant with 2 missing permissions; confirm 2 findings of type `permission_posture` exist with severity, fingerprint, and evidence populated.

**Acceptance Scenarios**:

1. **Given** a tenant has 14 required permissions and 12 are granted, **When** the posture finding generator runs, **Then** 2 findings are created with `finding_type=permission_posture`, `status=new`, and `severity` based on the number of features blocked.
2. **Given** a tenant had a missing permission that is now granted, **When** the posture finding generator runs again, **Then** the previously-created finding for that permission is auto-resolved (status changes from `new` to `resolved`).
3. **Given** a tenant has all required permissions granted, **When** the posture finding generator runs, **Then** no new findings are created; any previously open posture findings are auto-resolved.
4. **Given** the posture generator runs twice for the same permission state, **When** the same missing permissions persist, **Then** no duplicate findings are created (fingerprint-based idempotency).

---

### User Story 2 - Persist posture snapshot as a stored report (Priority: P2)

As a workspace operator, I want each permission check to produce a durable posture snapshot (stored report) so that I can track permission health over time and answer "what was the posture at time T?"

**Why this priority**: Stored reports provide temporal context and form the foundation for future dashboards and trend analysis.

**Independent Test**: Run the posture check for a tenant; confirm a stored report record exists with the correct report type, payload schema, and associated tenant.

**Acceptance Scenarios**:

1. **Given** a tenant permission check completes, **When** the stored report is created, **Then** it contains the full posture payload (required permissions, granted statuses, computed score, timestamp) and is associated with the tenant and workspace.
2. **Given** multiple posture checks run over time, **When** I query stored reports for a tenant, **Then** I can see the history of snapshots ordered by creation date.
3. **Given** the stored reports table has a polymorphic type field, **When** other spec domains later produce reports, **Then** they can use the same table without schema changes.

---

### User Story 3 - Alert on missing permissions (Priority: P3)

As a workspace manager, I want to be notified via existing alert channels (Teams/email) when a tenant is missing critical permissions, so I can take corrective action before operations fail.

**Why this priority**: Alerts close the feedback loop. Operators learn about permission gaps without polling the UI.

**Independent Test**: Create an alert rule for `EVENT_PERMISSION_MISSING`, run the posture generator for a tenant with a missing high-impact permission, and confirm a delivery is queued for the matching rule.

**Acceptance Scenarios**:

1. **Given** an alert rule exists for `EVENT_PERMISSION_MISSING` with minimum severity = high, **When** a posture finding of severity high is created, **Then** the alert dispatch service queues a delivery for each enabled destination on that rule.
2. **Given** an alert rule exists for `EVENT_PERMISSION_MISSING` with minimum severity = critical, **When** a posture finding of severity high (not critical) is created, **Then** no delivery is queued for that rule.
3. **Given** the same permission is still missing across two posture runs, **When** the alert is evaluated, **Then** cooldown/dedupe logic from Alerts v1 prevents duplicate notifications (fingerprint-based suppression).

---

### User Story 4 - Posture score calculation (Priority: P2)

As a workspace operator, I want a normalized posture score (0-100) for each tenant that summarizes how many required permissions are granted versus missing, so I can quickly compare tenant health at a glance.

**Why this priority**: A single numeric score enables sorting, filtering, and future dashboard widgets.

**Independent Test**: Check a tenant with 12/14 permissions granted; confirm score = 86 (round(12/14 * 100)). Check a tenant with 14/14; confirm score = 100.

**Acceptance Scenarios**:

1. **Given** a tenant has N of M required permissions granted, **When** the posture score is calculated, **Then** the score equals `round(N / M * 100)`.
2. **Given** the registry has 0 required permissions (edge case), **When** the score is calculated, **Then** the score is 100 (no requirements = fully compliant).
3. **Given** the posture score is stored in the report payload, **When** users query stored reports, **Then** they can sort/filter tenants by posture score.

---

### Edge Cases

- **Graph API unreachable during posture check**: If TenantPermissionService returns an error state for a permission, the posture generator records the permission as `status=error` in evidence but does NOT create a missing-permission finding for that key. It generates a separate `permission_check_error` finding instead.
- **Registry changes (permissions added/removed)**: If a new permission is added to `config/intune_permissions.php`, the next posture run automatically detects it as missing (for tenants that don't have it). If a permission is removed from the registry, existing findings for that key are auto-resolved on the next run.
- **Tenant with no provider connection**: The posture generator skips tenants without a configured provider connection; no findings or reports are created.
- **Concurrent posture runs**: Fingerprint-based upsert ensures idempotency. Two concurrent runs for the same tenant produce the same set of findings without duplicates.
- **Large workspace with many tenants**: The posture check is dispatched per-tenant as a queued job, not as a blocking batch operation.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces long-running/queued work (posture generator job).
- **Contract registry**: No new Graph contracts; uses existing TenantPermissionService read path.
- **Safety gates**: Posture generation is a read-only analysis; no write operations to Intune. No confirmation needed.
- **Tenant isolation**: Findings and stored reports are always scoped to a specific tenant (via `tenant_id` FK). Workspace-level queries filter by tenant entitlement.
- **Run observability**: The posture generator runs as a queued job. Its execution is tracked by the existing `OperationRun` mechanism with `type=permission_posture_check`. Status, outcome, started_at, completed_at are recorded.
- **Tests**: Unit tests for finding generation logic, score calculation, auto-resolve, and alert event production.

**Constitution alignment (RBAC-UX):** This feature does not introduce new authorization behavior.
- **Authorization planes**: Tenant-context (`/admin/t/{tenant}/...`) for viewing tenant posture findings; workspace-context for alerts.
- **404 vs 403**: Non-member / not entitled to workspace or tenant scope results in 404. Member missing `FINDINGS_VIEW` results in 403.
- **Server-side enforcement**: Existing FindingPolicy and AlertRule policies apply. No new policies needed.
- **Capability registry**: Uses `FINDINGS_VIEW`, `FINDINGS_MANAGE`, `ALERTS_VIEW`, `ALERTS_MANAGE` -- all existing.
- **Global search**: No new globally searchable resources.
- **Destructive actions**: None. Posture findings are system-generated, not user-deletable.
- **Authorization tests**: Positive test: user with FINDINGS_VIEW can see posture findings. Negative test: user without tenant entitlement receives 404.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable -- no OIDC/SAML login flows involved.

**Constitution alignment (BADGE-001):** This feature introduces new badge values:
- `finding_type=permission_posture` -- new finding type value. Badge rendering uses the centralized finding-type badge map; the new type is added there with icon and color.
- `severity` values: Uses existing `low`, `medium`, `high`, `critical` -- no new severity values.
- `status` values: Uses existing `new`, `acknowledged` + new `resolved` status for auto-closed findings. The `resolved` status is added to the centralized badge map.
- Tests cover rendering of `permission_posture` type badge and `resolved` status badge.

**Constitution alignment (Filament Action Surfaces):** No new Filament Resources/Pages/RelationManagers are introduced. Posture findings appear in the existing Findings list with the new `finding_type` filter value. **Exemption**: No UI Action Matrix needed -- no new action surfaces.

**Constitution alignment (UX-001 -- Layout and Information Architecture):** No new Filament screens. Posture findings use the existing Findings UI which already complies with UX-001. **Exemption**: No layout changes to audit.

### Functional Requirements

- **FR-001 (Stored Reports Table)**: The system MUST provide a generic `stored_reports` table with a polymorphic `report_type` field, a JSONB `payload` column, and foreign keys to `tenant_id` and `workspace_id`. This table is reusable by future spec domains.
- **FR-002 (Posture Payload Schema)**: Each stored posture report MUST contain: `report_type=permission_posture`, a payload with `required_permissions` (from registry), `granted_statuses` (per-key status at check time), `posture_score` (integer 0-100), and `checked_at` timestamp.
- **FR-003 (Posture Score Calculation)**: The system MUST calculate posture score as `round(granted_count / required_count * 100)`. If `required_count` is 0, score MUST be 100.
- **FR-004 (Posture Finding Generation)**: For each permission that is `status=missing` after a tenant permission check, the system MUST create or update a finding with `finding_type=permission_posture`, a deterministic fingerprint based on `tenant_id + permission_key`, and severity derived from the number of features that depend on that permission.
- **FR-005 (Severity Derivation)**: Finding severity MUST be derived from feature impact:
  - Permission blocks 3+ features results in `critical`
  - Permission blocks 2 features results in `high`
  - Permission blocks 1 feature results in `medium`
  - Permission blocks 0 features results in `low`
- **FR-006 (Finding Evidence)**: Each posture finding MUST store evidence in `evidence_jsonb` containing at minimum: `permission_key`, `permission_type`, `expected_status`, `actual_status`, `blocked_features` (list), and `checked_at`.
- **FR-007 (Finding Source Tag)**: Posture findings MUST set `source=permission_check` on the `findings` table to distinguish them from drift findings.
- **FR-008 (Auto-Resolve)**: When a previously-missing permission is now granted, the system MUST auto-resolve the corresponding finding by changing its status to `resolved` and recording `resolved_at` and `resolved_reason=permission_granted`.
- **FR-009 (Idempotent Upsert)**: The posture generator MUST use fingerprint-based upsert (`firstOrNew` on `tenant_id + fingerprint`) to prevent duplicate findings for the same permission on the same tenant.
- **FR-010 (Alert Event)**: When posture findings are created or updated, the system MUST produce `EVENT_PERMISSION_MISSING` events for the alert dispatch pipeline. Events MUST include tenant_id, permission_key, severity, and a deterministic fingerprint for cooldown/dedupe.
- **FR-011 (Alert Rule Integration)**: The `EVENT_PERMISSION_MISSING` event type MUST be available as an option when creating/editing alert rules in the existing Alerts UI. No new alert pages are needed.
- **FR-012 (Queued Execution)**: Posture generation MUST execute as a queued job (per-tenant) to avoid blocking user-facing requests.
- **FR-013 (Operation Run Tracking)**: Each posture generation execution MUST be tracked as an `OperationRun` with `type=permission_posture_check`, recording start, completion, outcome (success/failure), and error details.
- **FR-014 (Tenant Isolation)**: Findings, stored reports, and operation runs MUST be scoped to a specific tenant via `tenant_id`. Cross-tenant data access MUST be impossible at the query level.
- **FR-015 (Error Handling)**: If the permission check returns an error state for a specific permission key, the system MUST NOT create a `missing` finding for that key. Instead, it MUST create a separate finding with evidence indicating the check failed.
- **FR-016 (Skip Unconnected Tenants)**: The posture generator MUST skip tenants that have no configured provider connection. No findings or reports are created for unconnected tenants.
- **FR-017 (Registry as Source)**: The set of required permissions MUST be read from `config/intune_permissions.php` at runtime. No hardcoded permission lists in the generator.
- **FR-018 (Retention)**: Stored reports MUST support configurable retention. Default: 90 days.

## UI Action Matrix *(mandatory when Filament is changed)*

**Exemption**: This spec does NOT add or modify any Filament Resource, RelationManager, or Page.

Posture findings are rendered via the existing Findings Resource with a new `finding_type` filter value (`permission_posture`). The `EVENT_PERMISSION_MISSING` option is added to the existing Alert Rules form event type dropdown. No new surfaces, actions, or pages are created.

### Key Entities *(include if feature involves data)*

- **StoredReport**: A generic, workspace-scoped report record. Polymorphic `report_type` distinguishes domain (e.g., `permission_posture`). JSONB `payload` holds the full report data. Associated with a `tenant_id` and `workspace_id`. Supports temporal queries (ordered by `created_at`).
- **Finding (extended)**: Existing model extended with `finding_type=permission_posture` and `source=permission_check`. Each posture finding has a deterministic fingerprint (`tenant_id + permission_key`), severity derived from feature impact, and structured evidence in `evidence_jsonb`. Supports `resolved` status for auto-closed findings.
- **AlertRule (extended)**: Existing model gains `EVENT_PERMISSION_MISSING` as a valid `event_type` constant. No schema change; the constant is added to the model and the UI dropdown.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001 (Posture coverage)**: For any tenant with a configured provider connection, 100% of required permissions from the registry are evaluated and their status reflected in the posture report and findings.
- **SC-002 (Finding accuracy)**: The number of open `permission_posture` findings for a tenant exactly matches the number of `missing` permissions reported by the tenant permission check (no duplicates, no omissions).
- **SC-003 (Auto-resolve latency)**: When a previously-missing permission is granted, the corresponding finding is auto-resolved within the next posture check cycle (no manual intervention needed).
- **SC-004 (Score reliability)**: Posture score for a tenant with N of M permissions granted equals `round(N / M * 100)`. Deterministic and reproducible.
- **SC-005 (Alert delivery)**: When a posture finding of qualifying severity is created and an active alert rule matches, a delivery is queued within the standard alert processing time (under 2 minutes per Alerts v1 SLA).
- **SC-006 (Temporal audit)**: An operator can query stored reports to see a tenant's posture at any point in the last 90 days.
- **SC-007 (No duplicates)**: Repeated posture checks for the same permission state on the same tenant produce no duplicate findings (fingerprint idempotency verified).