TenantAtlas/specs/076-permissions-enterprise-ui/research.md

Research — Spec 076 (Permissions Enterprise UI)

Decisions

1) Build a dedicated tenant-scoped Filament Page

• Decision: Implement a new Filament Page under the tenant panel route (/admin/t/{tenant}/...) for the “Required permissions” enterprise remediation UX.
• Rationale:
  • The existing TenantResource infolist entry is a raw list; Spec 076 requires a two-layer remediation layout (overview + matrix) and feature grouping.
  • A dedicated Page can provide operator-first UX without bloating the tenant detail resource.
• Alternatives considered:
  • Extending the existing TenantResource view: rejected because it couples a complex remediation UI to a general-purpose resource view and makes verification deep-linking/clustering harder.

2) Use stored + config-based data only at render time (DB-only render)

• Decision: The page loads required permissions from config('intune_permissions.permissions') and granted/missing statuses from the tenant_permissions table via TenantPermissionService::compare($tenant, persist: false, liveCheck: false, useConfiguredStub: false).
• Rationale:
  • Satisfies FR-076-008 (no external network calls during page view).
  • Reuses existing data normalization and status modeling.
• Alternatives considered:
  • Calling Graph on page view (liveCheck: true): rejected (explicitly out of scope and violates DB-only render).

3) Authorization semantics: non-member 404, member missing capability 403

• Decision:
  • Non-member tenant access remains deny-as-not-found (404) via the Admin panel middleware (DenyNonMemberTenantAccess).
  • Page access is capability-gated via Page::canAccess() using Capabilities::TENANT_VIEW.
• Rationale:
  • Matches Constitution RBAC-UX-002 and RBAC-UX-003.
  • Ensures correct semantics for both initial request and Livewire requests.
• Alternatives considered:
  • Enforcing capability only in mount() with custom abort(...): rejected because canAccess() is the consistent Filament entry-point gate and keeps nav hiding in sync.

4) Badge semantics: use centralized domains only

• Decision:
  • Per-permission badges: BadgeDomain::TenantPermissionStatus.
  • Overall status badge: BadgeDomain::VerificationReportOverall with values from VerificationReportOverall.
• Rationale:
  • Constitution BADGE-001 requires centralized semantic mapping.

5) Filters/search implementation: server-side Livewire state, in-memory filtering

• Decision: Represent filter/search state as Livewire properties on the Page and filter the already-loaded permission array in-memory.
• Rationale:
  • Dataset size is small (config-defined permissions), so in-memory filtering is fast and stable.
  • Enables programmatic tests for filtering/copy payload generation without relying on browser JS.
• Alternatives considered:
  • Filament Tables with query-backed filters: rejected as unnecessary complexity for a config-driven list.
  • Pure client-side Alpine filtering: rejected due to weaker automated testability.

6) Copy-to-clipboard: “copy payload modal” + robust clipboard fallback

• Decision: Implement copy actions that open a modal (or inline panel) containing the exact newline-separated payload; a “Copy” button uses the existing robust Alpine clipboard fallback pattern.
• Rationale:
  • Clipboard APIs are browser-only; Livewire actions cannot write directly to clipboard.
  • Reuses proven fallback approach in resources/views/filament/partials/json-viewer.blade.php.
  • Makes copy output auditable/visible before copying (enterprise-friendly).
• Alternatives considered:
  • Attempting server-side copy: not possible.

7) Verify-step clustering: emit clustered checks in verification_report

• Decision:
  • Extend the queued verification job (ProviderConnectionHealthCheckJob) to write a verification report that includes the existing connection check plus 5–6 permission cluster checks.
  • Update the onboarding wizard Verify step to render OperationRun.context.verification_report (via VerificationReportViewer) and show checks issues-first.
• Rationale:
  • The project already has a report schema (VerificationReportSchema) and writer (VerificationReportWriter).
  • Clustering in the report keeps the experience consistent across the wizard and operation-run detail views.
• Alternatives considered:
  • Cluster in Blade only: rejected because it does not affect summary/overall and can drift between views.

8) Enterprise correctness: refresh Observed permissions during the verification run

• Decision:
  • The queued verification run (Operation Run) attempts a live Graph refresh for Observed permissions and persists it to tenant_permissions.
  • Viewer surfaces (Required Permissions page, onboarding Verify step, operation run viewer) remain DB-only at render time.
  • If the refresh fails (429/network), permission clusters degrade to warnings with retry guidance and MUST NOT assert “missing permissions” based on stale/empty inventory.
• Rationale:
  • Prevents false “missing” findings when the stored inventory is empty/stale.
  • Keeps all external calls in the queued run, maintaining the DB-only render rule.

Open questions resolved (NEEDS CLARIFICATION → decision)

“Enabled features” for impact summary

• Decision: In Spec 076 scope, treat “enabled features” as the feature tags present in config('intune_permissions.permissions').
• Rationale: There is no current per-tenant feature-enable registry in the codebase; feature tags already exist and are deterministic.
• Future upgrade path: If/when tenant-specific enablement exists, compute relevance by intersecting enabled features with permission feature tags.

Check cluster proposal (stable keys)

Target: 5–7 checks; issues-first.

• provider.connection.check (existing)
• permissions.admin_consent (overall admin consent / application permissions missing)
• permissions.directory_groups
• permissions.intune_configuration
• permissions.intune_apps
• permissions.intune_rbac_assignments
• permissions.scripts_remediations (optional / skip when irrelevant)

Each permission-derived check:

• Pass: no missing permissions in its mapped set
• Fail/Blocked: any missing required permission in its set
• Skip: cluster mapped permissions set is empty (or feature not relevant)
• Next step: “Open required permissions” deep link to the new page (optionally pre-filtered by Feature).