# VS-02: Synchronize Security Master - Vertical Slice Specification

**Slice ID:** VS-02  
**Batch:** 1 (depends on VS-00, which is complete)  
**Status:** 📋 SPECIFICATION  
**Created:** 2026-08-04  

---

## Executive Summary

Establish **Security Master** synchronization system that keeps role permissions and access control rules in sync across the platform.

**User Goal:** Security team can push updated permission rules to all modules without manual intervention or service restart.

**Non-Goal:**
- LDAP/Active Directory integration (Phase 3)
- Real-time webhook notifications (Phase 3)
- Audit trail of permission changes (separate feature)

---

## Acceptance Criteria

### 1. Security Master Data Model ✅

- [ ] **Roles:** Admin, Analyst, Trader, Viewer (from VS-01, immutable)
- [ ] **Permissions:** resource (domain), action (read/write/execute)
- [ ] **Role-Permission Mapping:** Many-to-many assignment
- [ ] **Access Control Rules:** Conditional rules (e.g., "Trader can execute only during market hours")
- [ ] **Temporal Validity:** effective_at, expires_at (time-based activation)

### 2. Synchronization Mechanism ✅

- [ ] **Outbound:** Export permission rules to all modules
- [ ] **Inbound:** Poll for remote updates from security master
- [ ] **Conflict Resolution:** Last-write-wins OR centralized authority
- [ ] **Idempotency:** Multiple sync runs produce same result
- [ ] **Rollback:** Previous good state cached, can revert on error

### 3. Data Integrity ✅

- [ ] **PIT Compliance:** published_at, revision tracking
- [ ] **Immutability:** Security rules never deleted, only versioned
- [ ] **Schema-Qualified:** All queries use security.rules, security.role_permissions
- [ ] **Transactional:** Batch updates atomic (all-or-nothing)

### 4. API Contracts ✅

**Endpoint: POST /api/security/master/sync**
```
Request: { fromVersion: int }
Response: 200 { version: int, rulesCount: int, syncedAt: timestamp }
Errors: 409 (version conflict), 503 (service unavailable)
Idempotency: Yes (version-based)
```

**Endpoint: GET /api/security/master/rules**
```
Response: 200 { rules: [Rule], version: int, lastSyncAt: timestamp }
Errors: 401 (unauthorized), 503 (stale data >5min)
```

### 5. Event Publishing ✅

- [ ] **SecurityMasterSynced Event:** When sync completes
- [ ] **PermissionRuleUpdated Event:** Per-rule change notification
- [ ] **SyncError Event:** When sync fails
- [ ] **Correlation:** CorrelationId traces entire sync operation

---

## Failure Modes & Recovery

### Scenario 1: Network Timeout During Sync

**Trigger:** Remote security master unreachable  
**Expected:** Endpoint returns 503, keeps previous version  
**Recovery:** Auto-retry every 30 seconds (exponential backoff)

### Scenario 2: Conflict (Remote Version Ahead)

**Trigger:** Local version 5, remote version 7  
**Expected:** 409 Conflict { requiredVersion: 7 }  
**Recovery:** Application requests specific version 7

### Scenario 3: Partial Sync (Half Complete)

**Trigger:** Database transaction fails mid-sync  
**Expected:** Rollback all changes, version unchanged  
**Recovery:** Next sync attempt starts fresh

---

## Security Considerations

- ✅ **Authentication:** Only authenticated services can call /sync
- ✅ **Authorization:** Only SecurityAdmin role can trigger sync
- ✅ **Audit:** Every sync logged with timestamp, version, rules changed
- ✅ **Encryption:** Rules transmitted over TLS, stored encrypted
- ✅ **Immutability:** Rules cannot be deleted (only versioned)

---

## Performance SLAs

| Metric | Target |
|--------|--------|
| Sync latency | <5 seconds |
| Rules query latency | <100ms (cached) |
| Rollback latency | <1 second |
| Max rules per sync | 10,000 |

---

## Dependencies

### Inbound (Blocked By)
- ✅ **VS-00:** Platform foundation (complete)
- ✅ **VS-01:** Role definitions (complete)

### Outbound (Unblocks)
- 🔄 **VS-03:** Market data ingestion (uses VS-02's permission model)
- 🔄 **VS-04~08:** All downstream slices depend on consistent permissions

---

## Component Breakdown (7 items)

| Component | Status |
|-----------|--------|
| **GOV** | 📋 This spec |
| **DATA** | ⏳ Next: PIT-compliant schema |
| **DOMAIN** | ⏳ Next: Sync logic tests |
| **BE** | ⏳ REST endpoints |
| **ASYNC** | ⏳ Sync job + events |
| **FE** | ⏳ Rules dashboard |
| **TESTOPS** | ⏳ Integration tests |

**Total Duration:** ~18-22 hours (wall-clock ~3 days)

---

## Sign-Off

| Role | Status | Date |
|------|--------|------|
| Architect | ✅ Draft | 2026-08-04 |
| Security | ⏳ Review | TBD |

---

**Status:** 📋 **READY FOR DATA/DOMAIN/BE COMPONENTS**

Next: VS-02_DATA_CONTRACT.md