Phase 3: Policy Enforcement

## Overview

Implement configurable attestation policies to enforce minimum security requirements, manage authenticator allowlists/blocklists, and add comprehensive audit logging.

**Parent Issue**: #88 - Add device attestation for enhanced passkey security
**Depends On**: Phase 2 (#90) - FIDO MDS Integration must be completed first

## Scope

This phase adds:
- Admin configuration for attestation requirements
- Minimum security level enforcement (FIDO2 certification, hardware-backed)
- Authenticator allowlist/blocklist by AAGUID
- Backend attestation verification
- Comprehensive audit logging for attestation events
- Policy violation notifications

## Tasks

### Backend - Policy Configuration

- [ ] **Create `backend/attestationPolicy.js` module**
- Define policy schema and validation
- Implement policy evaluation logic
- Support multiple policy types (global, per-account)
- Load policies from configuration file

- [ ] **Create `config/attestation-policy.json`**
- Define default attestation policy
- Configure minimum security requirements
- Define authenticator allowlist/blocklist
- Set enforcement mode (strict, warn, disabled)

- [ ] **Implement policy evaluation functions**
- `evaluateAttestationPolicy(metadata, policy)` - Check if device meets policy
- `isAuthenticatorAllowed(aaguid, policy)` - Check allowlist/blocklist
- `meetsMinimumSecurityLevel(metadata, policy)` - Check certification level
- `isHardwareBackedRequired(metadata, policy)` - Check hardware requirement

- [ ] **Update `POST /api/devices` endpoint**
- Evaluate attestation policy before accepting device
- Return policy violation errors with details
- Log policy evaluation results
- Support policy override for admins (optional)

- [ ] **Create `GET /api/attestation/policy` endpoint**
- Return current attestation policy
- Support per-account policies
- Include policy version and last updated timestamp

- [ ] **Create `PUT /api/attestation/policy` endpoint** (admin only)
- Update attestation policy
- Validate policy schema
- Trigger re-evaluation of existing devices (optional)
- Log policy changes

### Backend - Attestation Verification

- [ ] **Implement server-side attestation verification**
- Move attestation verification from frontend to backend
- Verify attestation signature on server
- Verify certificate chain on server
- Prevent client-side tampering

- [ ] **Update `POST /api/devices` endpoint**
- Accept full attestation object from client
- Perform server-side verification
- Validate against policy
- Return verification result

- [ ] **Add rate limiting for device registration**
- Prevent abuse of attestation verification
- Limit registrations per account per hour
- Log rate limit violations

### Backend - Audit Logging

- [ ] **Create `backend/auditLog.js` module**
- Define audit event types
- Implement structured logging
- Support multiple log outputs (file, database, external service)

- [ ] **Create `audit_logs` table**
- Store attestation-related events
- Include timestamp, account, event type, details
- Support querying and filtering

- [ ] **Log attestation events**
- Device registration success/failure
- Policy violations
- Certificate verification failures
- Blocklisted authenticator attempts
- Policy changes
- MDS refresh events

- [ ] **Create `GET /api/audit/attestation` endpoint** (admin only)
- Query audit logs
- Filter by account, event type, date range
- Support pagination
- Export to CSV/JSON

### Frontend - Policy UI

- [ ] **Create `AttestationPolicySettings.jsx` component** (admin only)
- Display current policy configuration
- Edit minimum security requirements
- Manage authenticator allowlist/blocklist
- Set enforcement mode
- Preview policy impact

- [ ] **Update device registration error handling**
- Display policy violation messages
- Explain why device was rejected
- Suggest alternative authenticators
- Link to policy documentation

- [ ] **Create `PolicyViolationModal.jsx` component**
- Show detailed policy violation information
- Display required vs. actual security properties
- Provide guidance on compliant authenticators
- Contact admin option

- [ ] **Update `DeviceManagement.jsx`**
- Show policy compliance status for each device
- Highlight devices that no longer meet policy
- Warn about upcoming policy changes

### Testing

- [ ] **Unit tests for policy evaluation**
- Test policy schema validation
- Test allowlist/blocklist logic
- Test minimum security level checks
- Test hardware-backed requirement
- Test policy override logic

- [ ] **Integration tests**
- Test device registration with various policies
- Test policy violation scenarios
- Test server-side attestation verification
- Test audit logging
- Test rate limiting

- [ ] **End-to-end tests**
- Test complete registration flow with strict policy
- Test policy update and re-evaluation
- Test admin policy management UI
- Test policy violation user experience

### Documentation

- [ ] **Create `docs/ATTESTATION_POLICY.md`**
- Explain attestation policy system
- Document policy schema and options
- Provide policy configuration examples
- Explain enforcement modes
- Document allowlist/blocklist management

- [ ] **Create `docs/AUDIT_LOGGING.md`**
- Document audit log structure
- Explain audit event types
- Provide query examples
- Document retention policy

- [ ] **Update `README.md`**
- Add section on attestation policies
- Document admin configuration
- Link to policy documentation

## Technical Details

### Policy Schema

```json
// config/attestation-policy.json
{
"version": "1.0",
"enforcementMode": "strict", // "strict", "warn", "disabled"
"requirements": {
"hardwareBacked": true,
"minimumCertificationLevel": "L2", // "L1", "L2", "L3", "L3+", null
"requireFIDO2Certified": true,
"allowedAttestationFormats": ["packed", "fido-u2f"],
"requireUserVerification": true
},
"allowlist": {
"enabled": false,
"aaguids": [
"00000000-0000-0000-0000-000000000000", // Apple Touch ID
"adce0002-35bc-c60a-648b-0b25f1f05503" // Apple Face ID
]
},
"blocklist": {
"enabled": true,
"aaguids": [
"12345678-1234-1234-1234-123456789012" // Known compromised authenticator
],
"reason": "Security vulnerability CVE-2024-XXXXX"
},
"exceptions": {
"allowNoneAttestation": false, // Allow "none" attestation for privacy
"allowLegacyDevices": true // Grandfather existing devices
}
}
```

### Policy Evaluation Logic

```javascript
function evaluateAttestationPolicy(metadata, policy) {
const violations = []

// Check enforcement mode
if (policy.enforcementMode === 'disabled') {
return { allowed: true, violations: [] }
}

// Check blocklist
if (policy.blocklist.enabled && policy.blocklist.aaguids.includes(metadata.aaguid)) {
violations.push({
type: 'BLOCKLISTED',
message: `Authenticator is blocklisted: ${policy.blocklist.reason}`,
severity: 'error'
})
}

// Check allowlist (if enabled)
if (policy.allowlist.enabled && !policy.allowlist.aaguids.includes(metadata.aaguid)) {
violations.push({
type: 'NOT_ALLOWLISTED',
message: 'Authenticator is not in the allowlist',
severity: 'error'
})
}

// Check hardware-backed requirement
if (policy.requirements.hardwareBacked && !metadata.isHardwareBacked) {
violations.push({
type: 'NOT_HARDWARE_BACKED',
message: 'Authenticator must be hardware-backed',
severity: 'error'
})
}

// Check FIDO2 certification
if (policy.requirements.requireFIDO2Certified && !metadata.isFIDO2Certified) {
violations.push({
type: 'NOT_FIDO2_CERTIFIED',
message: 'Authenticator must be FIDO2 certified',
severity: policy.enforcementMode === 'strict' ? 'error' : 'warning'
})
}

// Check certification level
const levelOrder = { 'L1': 1, 'L2': 2, 'L3': 3, 'L3+': 4 }
const requiredLevel = levelOrder[policy.requirements.minimumCertificationLevel] || 0
const actualLevel = levelOrder[metadata.certificationLevel] || 0

if (actualLevel < requiredLevel) {
violations.push({
type: 'INSUFFICIENT_CERTIFICATION_LEVEL',
message: `Minimum certification level ${policy.requirements.minimumCertificationLevel} required, got ${metadata.certificationLevel}`,
severity: 'error'
})
}

// Determine if allowed
const hasErrors = violations.some(v => v.severity === 'error')
const allowed = policy.enforcementMode === 'warn' || !hasErrors

return { allowed, violations }
}
```

### Audit Log Schema

```sql
CREATE TABLE audit_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
timestamp INTEGER NOT NULL,
event_type TEXT NOT NULL, -- 'DEVICE_REGISTERED', 'POLICY_VIOLATION', 'POLICY_UPDATED', etc.
account_address TEXT,
aaguid TEXT,
details TEXT, -- JSON string with event-specific data
severity TEXT, -- 'info', 'warning', 'error'
ip_address TEXT,
user_agent TEXT
);

CREATE INDEX idx_audit_logs_timestamp ON audit_logs(timestamp);
CREATE INDEX idx_audit_logs_account ON audit_logs(account_address);
CREATE INDEX idx_audit_logs_event_type ON audit_logs(event_type);
```

### Audit Event Types

```javascript
const AUDIT_EVENT_TYPES = {
DEVICE_REGISTERED: 'Device successfully registered',
DEVICE_REJECTED: 'Device registration rejected',
POLICY_VIOLATION: 'Attestation policy violation',
CERT_VERIFICATION_FAILED: 'Certificate verification failed',
BLOCKLISTED_ATTEMPT: 'Attempt to register blocklisted authenticator',
POLICY_UPDATED: 'Attestation policy updated',
MDS_REFRESHED: 'FIDO MDS data refreshed',
RATE_LIMIT_EXCEEDED: 'Device registration rate limit exceeded',
}
```

## Success Criteria

- ✅ Attestation policy system implemented and configurable
- ✅ Minimum security requirements enforced
- ✅ Allowlist/blocklist functionality working
- ✅ Server-side attestation verification implemented
- ✅ Audit logging captures all attestation events
- ✅ Admin UI for policy management functional
- ✅ User-friendly policy violation messages
- ✅ Rate limiting prevents abuse
- ✅ Legacy devices grandfathered appropriately
- ✅ Documentation complete

## Dependencies

**No new NPM packages required** - Uses existing dependencies

## Estimated Effort

**5-7 days**
- Policy system implementation: 2 days
- Server-side verification: 1 day
- Audit logging: 1 day
- Admin UI: 1-2 days
- Testing: 1 day
- Documentation: 1 day

## Next Phase

After Phase 3 is complete, proceed to **Phase 4: Advanced Features** (#91) to add:
- Additional attestation format support
- Certificate revocation checking
- Advanced authenticator metadata in UI
- Security reports and analytics

---

**Priority**: Medium
**Complexity**: High
**Labels**: `enhancement`, `security`, `passkey`, `phase-3`