# Feature Specification: Enable Endpoint Security Policy Restore (023)

**Feature Branch**: `feat/023-endpoint-security-restore`
**Created**: 2026-01-03
**Status**: Implemented (ready to merge)
**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 **restore-mode enablement** with additional validation/testing and targeted restore hardening, 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