TenantAtlas/specs/048-backup-restore-ui-graph-safety/spec.md

Feature Specification: Backup/Restore UI Graph-Safety (Phase 1)

Feature Branch: feat/048-backup-restore-ui-graph-safety
Created: 2026-01-10
Status: Draft

Purpose

Ensure Backup/Restore UI follows the same guardrails as Inventory:

• UI renders DB-only (no Microsoft Graph calls during render/mount/options/typeahead)
• UI still remains usable with safe fallbacks for unresolved external identifiers
• Add programmatic guard tests that fail if Graph is touched while rendering

This phase is intentionally minimal-change and high-safety.

Clarifications

Session 2026-01-10

• Q: Which pages must the fail-hard GraphClientInterface guard tests render? → A: Backup Sets index + Restore wizard.
• Q: How should <masked-id> be formatted in fallback labels? → A: …<last8>

Session 2026-01-11

• Q: How should the fail-hard Graph guard tests be structured? → A: Feature tests that actingAs(...) then GET the Filament pages’ routes.
• Q: For the feature tests, should we assert only HTTP 200, or also a stable UI marker? → A: Assert HTTP 200 + a stable page marker string.

Users

• Tenant Admin
• MSP Operator (within authorized tenant scope)

User Stories

US1 (P1): Backup Sets Index is Graph-safe

As a tenant admin, I can open the Backup Sets index page and it renders DB-only (no Graph calls during request/render/mount/options/typeahead).

Maps to: Scenario 1

US2 (P1): Restore Wizard is Graph-safe incl. Group Mapping UI

As a tenant admin, I can open the Restore wizard page and the group mapping UI remains usable without any Graph calls (including typeahead/search/label resolution).

Maps to: Scenario 2 + Scenario 3

User Scenarios & Testing

Scenario 1: Open Backup pages without Graph access

• Given a user is authenticated and has access to a tenant
• When they open the Backup Sets index page
• Then the page renders successfully (HTTP 200) without any Graph calls

Scenario 2: Open Restore Wizard without Graph access

• Given a user is authenticated and has access to a tenant
• When they open the Restore Run wizard page
• Then the wizard renders successfully (HTTP 200) without any Graph calls

Scenario 3: Group mapping shows safe fallback labels

• Given the UI displays group IDs (e.g., in mapping fields)
• When the UI cannot resolve group names without Graph
• Then it shows safe fallback labels like:
  • Unresolved (…<last8>)
  • Group (external): …<last8>

Stable Page Marker Rules (for Guard Tests)

Guard tests MUST assert a stable, static marker string in addition to HTTP 200.

Marker selection rules:

• MUST be static UI text that is not tenant data (avoid names, IDs, timestamps, counts)
• SHOULD be a column label, section heading, or primary action label rendered by Filament
• MUST be present on the initial GET without requiring any Livewire interaction
• MUST NOT depend on Microsoft Graph availability

Markers MUST be recorded in quickstart.md once chosen.

Functional Requirements

• FR-001: Backup/Restore UI MUST NOT call Microsoft Graph during render/mount/options/typeahead.
• FR-002: The Restore Wizard group mapping controls MUST NOT call Graph for search results or label resolution.

Group Mapping UX (DB-only)

When group mapping is required, the UI MUST remain Graph-free and MUST provide a DB-only safe input.

• For each unresolved source group, the UI shows a mapping row with:

  • Source label: <displayName or "Security group"> (…<last8>)
  • Target input:
    • Allowed values:
      • SKIP (skip assignment)
      • A manually entered Entra ID group objectId (GUID/UUID string)

• Validation rules:

  • If not SKIP, the value MUST be a syntactically valid UUID
  • No network lookup/verification is performed in Phase 1 (Graph-free). Existence is validated later during preview/restore execution paths.

• Helper text MUST explain:

  • “Paste the target Entra ID group Object ID (GUID). Names are not resolved in this phase.”
  • “Use SKIP to omit the assignment.”

• FR-003: When names cannot be resolved DB-only, the UI MUST show safe fallback labels using masked identifiers.

  • <masked-id> format: …<last8> (last 8 characters of the external identifier, prefixed with an ellipsis)

• FR-004: Add fail-hard Pest feature tests binding GraphClientInterface to throw on any invocation and verify:

  • Backup Sets index renders OK (HTTP 200 + stable page marker)
  • Restore wizard renders OK (HTTP 200 + stable page marker)

Non-Functional Requirements

• NFR-001: No new Graph calls are introduced in UI code paths.
• NFR-002: No new tables are added in this phase.
• NFR-003: Changes should be low-risk and minimal surface area.

Out of Scope

• Moving action handlers (snapshot capture, backup create, restore rerun, restore dry-run) to jobs.
• Creating new cache/inventory tables to support group search.

Success Criteria

• SC-001: Guard tests reliably fail if any Backup/Restore UI render path touches Graph.
• SC-002: Backup and Restore wizard pages render successfully with Graph disabled.
• SC-003: Group mapping UI remains usable with DB-only fallback labels.

Related Specs

• Follow-up (Phase 2): Backup/Restore job orchestration (TBD)