specs/023-endpoint-security-restore/checklists/requirements.md

@@ -0,0 +1,14 @@
+# Requirements Checklist (023)
+
+**Created**: 2026-01-03
+**Feature**: [spec.md](../spec.md)
+
+- [ ] `endpointSecurityPolicy.restore` is changed to `enabled` in `config/tenantpilot.php`.
+- [ ] Restore preview validates template existence and reports missing/ambiguous templates.
+- [ ] Restore execution blocks on missing/ambiguous templates with a clear, actionable error message.
+- [ ] Settings instances are validated against resolved template definitions before execution.
+- [ ] Template mapping strategy is defined for cross-tenant differences (if required) and is tested.
+- [ ] Restore create + update paths for Endpoint Security policies are covered by automated tests.
+- [ ] Assignments mapping/application for Endpoint Security policies are covered by automated tests.
+- [ ] Audit log entries exist for restore execution attempts (success and failure).
+

specs/023-endpoint-security-restore/plan.md

@@ -0,0 +1,32 @@
+# Plan: Endpoint Security Policy Restore (023)
+
+**Branch**: `feat/023-endpoint-security-restore`
+**Date**: 2026-01-03
+**Input**: [spec.md](./spec.md)
+
+## Goal
+Enable full restore execution for Endpoint Security Policies (`endpointSecurityPolicy`) instead of preview-only, with defensive validation around templates and settings payloads.
+
+## Approach
+1. Enable restore execution in `config/tenantpilot.php` by switching `endpointSecurityPolicy.restore` from `preview-only` to `enabled`.
+2. Add template existence validation during restore preview:
+	- Resolve the snapshot’s `templateReference` (family/id/display name where available).
+	- Confirm the referenced template is resolvable in the target tenant before execution.
+	- Surface warnings in preview and fail execution with a clear error when missing.
+3. Add settings instance validation prior to execution:
+	- Resolve template definitions for the target tenant.
+	- Validate that settings instances are structurally compatible with the resolved template.
+	- Treat validation failures as preview warnings, and block execution when the payload cannot be made safe.
+4. Ensure restore uses the existing generic configuration policy create/update flow:
+	- Create when no match exists; update when matched (per existing restore matching rules).
+	- Apply assignments using existing mapping logic.
+5. Add targeted tests covering:
+	- Create + update restore execution for `endpointSecurityPolicy`.
+	- Preview warnings and execution failure when template is missing.
+	- Settings validation failure paths.
+	- Assignment application expectations.
+
+## Decisions / Notes
+- Assume template identifiers may differ across tenants; prefer mapping by `templateFamily` with display-name fallback when required.
+- Safety-first: if template resolution is ambiguous, treat as missing and block execution.
+

specs/023-endpoint-security-restore/spec.md

@@ -0,0 +1,93 @@
+# Feature Specification: Enable Endpoint Security Policy Restore (023)
+
+**Feature Branch**: `feat/023-endpoint-security-restore`
+**Created**: 2026-01-03
+**Status**: Draft
+**Priority**: P1 (Quick Win)
+
+## Context
+Endpoint Security Policies are already in the `tenantpilot.php` config as `endpointSecurityPolicy` with `restore => 'preview-only'`. Based on Microsoft's recommendation to use the unified `deviceManagement/configurationPolicies` endpoint (over the deprecated `intents` API for new creations), we should enable full restore for this type.
+
+This is a **configuration-only change** with additional validation/testing, not a new policy type implementation.
+
+## User Scenarios & Testing
+
+### User Story 1 — Restore Endpoint Security Policies (Priority: P1)
+As an admin, I want to restore Endpoint Security Policies (Firewall, Defender, ASR, BitLocker, etc.) from backup, so I can recover from configuration errors or replicate security baselines across tenants.
+
+**Why this priority**: These are high-impact security policies; restore is a core safety feature.
+
+**Independent Test**: Restore an Endpoint Security Policy snapshot; verify settings and assignments are applied correctly.
+
+**Acceptance Scenarios**
+1. Given an Endpoint Security Policy snapshot (e.g., Firewall), when I restore to a tenant without that policy, then a new policy is created with matching settings.
+2. Given an Endpoint Security Policy snapshot, when I restore to a tenant with an existing policy (name match), then the policy is updated.
+3. Given such a policy has assignments, when I restore, then assignments are mapped and applied.
+
+### User Story 2 — Template Validation (Priority: P1)
+As an admin, I want clear warnings if an Endpoint Security template is not available in the target tenant, so I understand restore limitations.
+
+**Why this priority**: Templates are version-dependent; missing templates must be surfaced.
+
+**Independent Test**: Attempt to restore a policy referencing a template not present in target; verify preview shows a warning.
+
+**Acceptance Scenarios**
+1. Given a policy snapshot references a template ID, when I restore to a tenant without that template, then preview warns about missing template.
+2. Given such a scenario, when I execute restore, then the operation fails gracefully with a clear error message.
+
+### User Story 3 — Settings Instance Consistency (Priority: P2)
+As an admin, I want settings instances to be validated against template definitions, so restored policies are valid.
+
+**Why this priority**: Settings must match template structure; invalid settings break policies.
+
+**Independent Test**: Restore a policy with settings; verify Graph API accepts the settings payload.
+
+**Acceptance Scenarios**
+1. Given a policy snapshot with settings, when I restore, then settings are validated before submission to Graph API.
+2. Given settings validation detects structural issues, when running preview, then warnings indicate which settings may be problematic.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Change `restore` value from `'preview-only'` to `'enabled'` for `endpointSecurityPolicy` in config
+- **FR-002**: Add template existence validation in restore preview
+- **FR-003**: Ensure settings instance validation against template structure
+- **FR-004**: Update Graph contract for `endpointSecurityPolicy` if needed (may already exist)
+- **FR-005**: Add template ID mapping (if templates have different IDs across tenants)
+- **FR-006**: Add comprehensive restore tests for common Endpoint Security policy types:
+  - Antivirus (Defender)
+  - Firewall
+  - Disk Encryption (BitLocker)
+  - Attack Surface Reduction (ASR)
+  - Account Protection
+
+### Non-Functional Requirements
+- **NFR-001**: Restore preview must complete within 5 seconds for typical policy
+- **NFR-002**: Template validation must not significantly slow down preview
+- **NFR-003**: All common Endpoint Security policy types must be covered by tests
+
+### Graph API Details
+- **Endpoint**: `https://graph.microsoft.com/beta/deviceManagement/configurationPolicies`
+- **Filter** (if needed): `templateReference/templateFamily eq 'endpointSecurity...'`
+- **Template Families**: 
+  - `endpointSecurityAntivirus`
+  - `endpointSecurityFirewall`
+  - `endpointSecurityDiskEncryption`
+  - `endpointSecurityAttackSurfaceReduction`
+  - `endpointSecurityAccountProtection`
+  - etc.
+- **Required Permissions**: `DeviceManagementConfiguration.ReadWrite.All`
+
+### Known Considerations
+- **Template Versioning**: Templates can evolve; settings structure may change
+- **Platform Differences**: Some templates are Windows 10 only, others support Windows 11+
+- **Settings Validation**: Graph API will reject invalid settings; catch this in preview
+
+## Success Criteria
+- **SC-001**: Config change applied: `endpointSecurityPolicy` has `restore => 'enabled'`
+- **SC-002**: Restore preview shows accurate change summary for Endpoint Security policies
+- **SC-003**: Restore executes successfully for common policy types (Firewall, Antivirus, BitLocker)
+- **SC-004**: Template existence validation catches missing templates before execution
+- **SC-005**: Settings instance validation prevents invalid payloads
+- **SC-006**: No regressions in sync or backup for this policy type
+- **SC-007**: Feature tests cover restore success and failure scenarios

specs/023-endpoint-security-restore/tasks.md

@@ -0,0 +1,32 @@
+# Tasks: Endpoint Security Policy Restore (023)
+
+**Branch**: `feat/023-endpoint-security-restore`
+**Date**: 2026-01-03
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Inventory & Design
+- [ ] T002 Confirm current restore mode + code paths for `endpointSecurityPolicy` (`config/tenantpilot.php`, restore services).
+- [ ] T003 Decide template resolution strategy (ID vs family/display name) and required Graph calls.
+- [ ] T004 Define settings instance validation rules (warning vs block) for restore preview/execution.
+
+## Phase 3: Tests (TDD)
+- [ ] T005 Add feature tests for restore execution create/update for `endpointSecurityPolicy`.
+- [ ] T006 Add feature tests for preview warnings when template is missing.
+- [ ] T007 Add feature tests asserting restore execution fails gracefully when template is missing.
+- [ ] T008 Add tests for settings validation failure paths (invalid/unknown settings instances).
+- [ ] T009 Add feature tests asserting assignments are applied for endpoint security policies.
+
+## Phase 4: Implementation
+- [ ] T010 Enable restore for `endpointSecurityPolicy` in `config/tenantpilot.php`.
+- [ ] T011 Implement template existence validation in restore preview and execution gating.
+- [ ] T012 Implement settings instance validation against resolved template definitions.
+- [ ] T013 Implement template mapping (if required) and ensure restore payload uses mapped template reference.
+- [ ] T014 Ensure restore applies assignments for endpoint security policies using existing mapping logic.
+
+## Phase 5: Verification
+- [ ] T015 Run targeted tests.
+- [ ] T016 Run Pint (`./vendor/bin/pint --dirty`).
+