@pan-sec/notebooklm-mcp 1.4.0 → 1.7.0

package/docs/COMPLIANCE-SPEC.md

@@ -0,0 +1,1452 @@
+# Enterprise Compliance Specification
+
+**Version**: 1.0.0
+**Date**: 2025-12-16
+**Standards**: GDPR, SOC2 Type II, CSSF (Luxembourg)
+**Status**: Draft
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Phase 1: Core Compliance Infrastructure](#phase-1-core-compliance-infrastructure)
+3. [Phase 2: Data Subject Rights](#phase-2-data-subject-rights-gdpr)
+4. [Phase 3: Security Monitoring & Incident Response](#phase-3-security-monitoring--incident-response)
+5. [Phase 4: Compliance Reporting & Documentation](#phase-4-compliance-reporting--documentation)
+6. [Configuration Reference](#configuration-reference)
+7. [File Structure](#file-structure)
+
+---
+
+## Overview
+
+### Current State
+
+The NotebookLM MCP Server already implements strong security foundations:
+
+| Existing Feature | Implementation |
+|-----------------|----------------|
+| Audit Logging | Hash-chained JSONL with tamper detection |
+| Encryption at Rest | ML-KEM-768 + ChaCha20-Poly1305 (post-quantum) |
+| Encryption in Transit | TLS with certificate pinning |
+| PII Protection | Auto-sanitization in all logs |
+| Access Control | Token-based auth with rate limiting |
+| Session Security | Hard timeout (8h) + inactivity (30m) |
+| Secrets Detection | 50+ patterns, auto-redaction |
+| Memory Security | Secure wiping, auto-expiry credentials |
+| Data Retention | 30-day audit log rotation |
+
+### Compliance Gaps
+
+| Gap | GDPR | SOC2 | CSSF | Priority |
+|-----|------|------|------|----------|
+| Consent Management | Required | - | Required | P1 |
+| Data Subject Rights (DSAR) | Required | - | Required | P1 |
+| Data Export/Portability | Required | - | Required | P1 |
+| Right to Erasure | Required | - | Required | P1 |
+| Data Classification | - | Required | Required | P1 |
+| SIEM Integration | - | Required | Required | P2 |
+| Breach Detection | Required | Required | Required | P2 |
+| Incident Response | - | Required | Required | P2 |
+| Compliance Reporting | - | Required | Required | P3 |
+| Change Management | - | Required | Required | P3 |
+
+---
+
+## Phase 1: Core Compliance Infrastructure
+
+### 1.1 Compliance Logger
+
+**File**: `src/utils/compliance-logger.ts`
+
+**Purpose**: Structured logging specifically for compliance events, separate from operational audit logs.
+
+**Event Categories**:
+
+```typescript
+type ComplianceEventCategory =
+  | "consent"           // Consent granted/revoked
+  | "data_access"       // Data access requests
+  | "data_export"       // Data portability requests
+  | "data_deletion"     // Erasure requests
+  | "data_processing"   // Processing activities
+  | "security_incident" // Security events
+  | "policy_change"     // Configuration changes
+  | "access_control"    // Auth events
+  | "retention"         // Data retention events
+  | "breach";           // Breach notifications
+```
+
+**Event Structure**:
+
+```typescript
+interface ComplianceEvent {
+  // Required fields
+  id: string;                    // UUID v4
+  timestamp: string;             // ISO 8601
+  category: ComplianceEventCategory;
+  event_type: string;            // Specific event (e.g., "consent_granted")
+
+  // Actor information
+  actor: {
+    type: "user" | "system" | "admin";
+    id?: string;                 // User/session ID if applicable
+    ip?: string;                 // Masked IP (last octet zeroed)
+  };
+
+  // Event details
+  resource?: {
+    type: string;                // e.g., "notebook", "session", "audit_log"
+    id?: string;
+  };
+
+  // Compliance metadata
+  legal_basis?: string;          // GDPR legal basis
+  data_categories?: string[];    // Types of data involved
+  retention_days?: number;       // How long to retain this event
+
+  // Outcome
+  outcome: "success" | "failure" | "pending";
+  failure_reason?: string;
+
+  // Integrity
+  hash: string;
+  previous_hash: string;
+}
+```
+
+**Storage**:
+- Location: `<data_dir>/compliance/events-YYYY-MM.jsonl`
+- Retention: Configurable, default 7 years (CSSF requirement)
+- Format: JSONL with hash chain
+- Encryption: Post-quantum encrypted
+
+**Configuration**:
+
+```bash
+NLMCP_COMPLIANCE_ENABLED=true
+NLMCP_COMPLIANCE_DIR=/path/to/compliance
+NLMCP_COMPLIANCE_RETENTION_YEARS=7
+NLMCP_COMPLIANCE_ENCRYPTION=true
+```
+
+---
+
+### 1.2 Data Classification System
+
+**File**: `src/utils/data-classification.ts`
+
+**Purpose**: Tag all data by sensitivity level for appropriate handling.
+
+**Classification Levels**:
+
+```typescript
+enum DataClassification {
+  PUBLIC = "public",           // No restrictions
+  INTERNAL = "internal",       // Internal use only
+  CONFIDENTIAL = "confidential", // Restricted access
+  RESTRICTED = "restricted",   // Highly sensitive (PII, credentials)
+  REGULATED = "regulated"      // Subject to regulatory requirements
+}
+
+interface ClassifiedData {
+  classification: DataClassification;
+  data_categories: DataCategory[];
+  retention_policy: string;
+  encryption_required: boolean;
+  audit_required: boolean;
+  exportable: boolean;
+  erasable: boolean;
+}
+
+type DataCategory =
+  | "personal_data"      // GDPR personal data
+  | "sensitive_data"     // GDPR special categories
+  | "credentials"        // Auth tokens, passwords
+  | "session_data"       // Browser session state
+  | "usage_data"         // Analytics, telemetry
+  | "configuration"      // Settings, preferences
+  | "audit_logs"         // Compliance logs
+  | "notebook_metadata"; // Notebook URLs, descriptions
+```
+
+**Data Inventory**:
+
+| Data Type | Classification | Categories | Retention | Encrypted |
+|-----------|---------------|------------|-----------|-----------|
+| Auth tokens | RESTRICTED | credentials | Session | Yes |
+| Browser cookies | RESTRICTED | session_data, personal_data | 24h | Yes |
+| Notebook library | CONFIDENTIAL | notebook_metadata | Indefinite | Yes |
+| Audit logs | REGULATED | audit_logs | 7 years | Yes |
+| Compliance events | REGULATED | audit_logs | 7 years | Yes |
+| User settings | INTERNAL | configuration | Indefinite | No |
+| Session data | CONFIDENTIAL | session_data | 8h max | Yes |
+| PQ encryption keys | RESTRICTED | credentials | Indefinite | Yes |
+
+---
+
+### 1.3 Consent Manager
+
+**File**: `src/compliance/consent-manager.ts`
+
+**Purpose**: Track and manage user consent for data processing activities.
+
+**Consent Types**:
+
+```typescript
+interface ConsentRecord {
+  id: string;                    // UUID
+  version: string;               // Consent version (e.g., "1.0.0")
+  granted_at: string;            // ISO 8601
+  expires_at?: string;           // Optional expiry
+
+  // What was consented to
+  purposes: ConsentPurpose[];
+  data_categories: DataCategory[];
+
+  // Legal basis (GDPR Article 6)
+  legal_basis: LegalBasis;
+
+  // Consent metadata
+  method: "explicit" | "implicit" | "contractual";
+  evidence?: string;             // How consent was obtained
+
+  // Revocation
+  revoked?: boolean;
+  revoked_at?: string;
+  revocation_reason?: string;
+}
+
+type ConsentPurpose =
+  | "service_provision"    // Core service functionality
+  | "session_management"   // Browser session handling
+  | "security_logging"     // Security audit logging
+  | "error_diagnostics"    // Error logging for debugging
+  | "usage_analytics";     // Optional usage tracking
+
+type LegalBasis =
+  | "consent"              // User explicitly consented
+  | "contract"             // Necessary for contract performance
+  | "legal_obligation"     // Required by law
+  | "vital_interests"      // Protect vital interests
+  | "public_interest"      // Public interest task
+  | "legitimate_interest"; // Legitimate business interest
+```
+
+**Default Legal Bases**:
+
+| Processing Activity | Legal Basis | Requires Explicit Consent |
+|--------------------|-------------|---------------------------|
+| Browser session for NotebookLM access | Contract | No |
+| Security audit logging | Legitimate Interest | No |
+| Credential encryption | Legal Obligation | No |
+| Error logging | Legitimate Interest | No |
+| Compliance logging | Legal Obligation | No |
+
+**Storage**:
+- Location: `<config_dir>/consent.json.pqenc`
+- Encrypted: Yes (post-quantum)
+- Backed up: Yes (with compliance events)
+
+**API**:
+
+```typescript
+class ConsentManager {
+  // Record new consent
+  async grantConsent(purposes: ConsentPurpose[], legalBasis: LegalBasis): Promise<ConsentRecord>;
+
+  // Revoke consent
+  async revokeConsent(consentId: string, reason?: string): Promise<void>;
+
+  // Check if consent exists for purpose
+  hasConsent(purpose: ConsentPurpose): boolean;
+
+  // Get all active consents
+  getActiveConsents(): ConsentRecord[];
+
+  // Get consent history (for DSAR)
+  getConsentHistory(): ConsentRecord[];
+
+  // Check if first run (needs consent prompt)
+  isFirstRun(): boolean;
+
+  // Export consent records (for DSAR)
+  exportConsents(): string; // JSON
+}
+```
+
+---
+
+### 1.4 Privacy Notice Display
+
+**File**: `src/compliance/privacy-notice.ts`
+
+**Purpose**: Display privacy notice on first run and track acceptance.
+
+**Notice Content** (stored in `src/compliance/privacy-notice-text.ts`):
+
+```typescript
+interface PrivacyNotice {
+  version: string;
+  effective_date: string;
+
+  sections: {
+    data_controller: string;
+    data_collected: string[];
+    purposes: string[];
+    legal_basis: string[];
+    retention: string;
+    rights: string[];
+    contact: string;
+  };
+
+  // Short summary for CLI display
+  summary: string;
+}
+```
+
+**Display Behavior**:
+
+1. **First Run**: Display full privacy notice, require acknowledgment
+2. **Notice Updated**: Display changes, require re-acknowledgment
+3. **On Demand**: Available via `get_privacy_notice` MCP tool
+
+**CLI Display Example**:
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║                     PRIVACY NOTICE v1.0.0                         ║
+╠══════════════════════════════════════════════════════════════════╣
+║                                                                   ║
+║  This tool processes the following data locally on your device:  ║
+║                                                                   ║
+║  • Browser session data (cookies, local storage)                 ║
+║  • NotebookLM URLs and metadata                                  ║
+║  • Query history (for session context)                           ║
+║  • Security audit logs                                           ║
+║                                                                   ║
+║  All data is:                                                    ║
+║  ✓ Stored locally only (no cloud sync)                          ║
+║  ✓ Encrypted with post-quantum cryptography                     ║
+║  ✓ Subject to automatic retention policies                      ║
+║                                                                   ║
+║  Your rights: Access, Export, Erasure, Portability              ║
+║                                                                   ║
+║  Full policy: https://github.com/Pantheon-Security/...          ║
+║                                                                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║  By continuing, you acknowledge this privacy notice.             ║
+║                                                                   ║
+║  [Press Enter to continue, or Ctrl+C to exit]                   ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+### 1.5 Enhanced Audit Events
+
+**File**: Update `src/utils/audit-logger.ts`
+
+**New Event Types**:
+
+```typescript
+// Add to existing AuditEventType
+type AuditEventType =
+  | "tool"              // Existing
+  | "auth"              // Existing
+  | "session"           // Existing
+  | "security"          // Existing
+  | "system"            // Existing
+  | "compliance"        // NEW: Compliance events
+  | "data_access"       // NEW: Data access events
+  | "configuration"     // NEW: Config changes
+  | "retention";        // NEW: Data retention events
+
+// New compliance-specific logging methods
+interface AuditLogger {
+  // Existing methods...
+
+  // NEW: Compliance event logging
+  logComplianceEvent(
+    event: string,
+    category: ComplianceEventCategory,
+    details: Record<string, unknown>
+  ): Promise<void>;
+
+  // NEW: Data access logging (for DSAR)
+  logDataAccess(
+    action: "view" | "export" | "delete",
+    dataType: string,
+    details: Record<string, unknown>
+  ): Promise<void>;
+
+  // NEW: Configuration change logging
+  logConfigChange(
+    setting: string,
+    oldValue: unknown,
+    newValue: unknown,
+    changedBy: string
+  ): Promise<void>;
+
+  // NEW: Retention event logging
+  logRetentionEvent(
+    action: "cleanup" | "archive" | "delete",
+    dataType: string,
+    count: number,
+    details: Record<string, unknown>
+  ): Promise<void>;
+}
+```
+
+---
+
+## Phase 2: Data Subject Rights (GDPR)
+
+### 2.1 Data Export Tool
+
+**File**: `src/compliance/data-export.ts`
+
+**Purpose**: Export all user data in machine-readable format (GDPR Article 20).
+
+**Export Format**:
+
+```typescript
+interface DataExport {
+  export_metadata: {
+    version: string;
+    exported_at: string;
+    format: "json";
+    encryption: "none" | "password";
+    checksum: string;
+  };
+
+  data: {
+    // User identity
+    consent_records: ConsentRecord[];
+
+    // Notebooks
+    notebook_library: NotebookEntry[];
+
+    // Settings
+    user_settings: Settings;
+
+    // Session history (if retained)
+    session_history?: SessionSummary[];
+
+    // Audit logs (user's own activity)
+    activity_log: AuditEvent[];
+
+    // Compliance events
+    compliance_events: ComplianceEvent[];
+  };
+
+  data_inventory: {
+    category: string;
+    count: number;
+    date_range: { from: string; to: string };
+  }[];
+}
+```
+
+**Export Options**:
+
+```typescript
+interface ExportOptions {
+  // What to include
+  include_notebooks: boolean;       // Default: true
+  include_settings: boolean;        // Default: true
+  include_sessions: boolean;        // Default: true
+  include_audit_logs: boolean;      // Default: true
+  include_compliance_events: boolean; // Default: true
+
+  // Date range
+  from_date?: string;
+  to_date?: string;
+
+  // Security
+  encrypt_export: boolean;          // Default: false
+  export_password?: string;
+
+  // Format
+  format: "json" | "json_pretty";
+
+  // Delivery
+  output_path?: string;             // Default: stdout
+}
+```
+
+**MCP Tool**:
+
+```typescript
+// New MCP tool: export_user_data
+{
+  name: "export_user_data",
+  description: "Export all user data (GDPR Article 20 - Right to Data Portability)",
+  inputSchema: {
+    type: "object",
+    properties: {
+      include_audit_logs: { type: "boolean", default: true },
+      from_date: { type: "string", format: "date" },
+      to_date: { type: "string", format: "date" },
+      format: { type: "string", enum: ["json", "json_pretty"], default: "json_pretty" }
+    }
+  }
+}
+```
+
+---
+
+### 2.2 Right to Erasure
+
+**File**: `src/compliance/data-erasure.ts`
+
+**Purpose**: Complete deletion of user data (GDPR Article 17).
+
+**Erasure Scope**:
+
+```typescript
+interface ErasureRequest {
+  request_id: string;
+  requested_at: string;
+
+  // What to delete
+  scope: ErasureScope;
+
+  // Verification
+  confirmed: boolean;
+  confirmation_method: "explicit" | "timeout";
+
+  // Execution
+  executed_at?: string;
+  items_deleted: ErasureResult[];
+
+  // Retention (we must keep the erasure record itself)
+  erasure_record_retention_days: number; // Default: 2555 (7 years)
+}
+
+interface ErasureScope {
+  // Data types to delete
+  notebooks: boolean;           // Notebook library
+  settings: boolean;            // User settings
+  browser_data: boolean;        // Browser profiles, cookies
+  audit_logs: boolean;          // User activity logs
+  compliance_events: boolean;   // Keep erasure record only
+  encryption_keys: boolean;     // PQ keys (careful!)
+
+  // Or delete everything
+  complete_erasure: boolean;
+}
+
+interface ErasureResult {
+  data_type: string;
+  path: string;
+  items_deleted: number;
+  size_bytes: number;
+  method: "overwrite" | "delete" | "crypto_shred";
+  verified: boolean;
+}
+```
+
+**Secure Deletion Methods**:
+
+1. **Overwrite**: 3-pass overwrite with random data
+2. **Delete**: Standard file deletion
+3. **Crypto Shred**: Delete encryption keys (data unrecoverable)
+
+**Retention Exceptions** (data that cannot be deleted):
+
+- Erasure request record itself (legal requirement)
+- Security incident logs (if applicable)
+- Data required for legal proceedings
+
+**MCP Tool**:
+
+```typescript
+// New MCP tool: request_data_erasure
+{
+  name: "request_data_erasure",
+  description: "Request deletion of all user data (GDPR Article 17 - Right to Erasure)",
+  inputSchema: {
+    type: "object",
+    properties: {
+      scope: {
+        type: "string",
+        enum: ["complete", "notebooks", "sessions", "audit_logs"],
+        default: "complete"
+      },
+      confirm: {
+        type: "boolean",
+        description: "Explicit confirmation required"
+      }
+    },
+    required: ["confirm"]
+  }
+}
+```
+
+---
+
+### 2.3 Data Access Request Handler
+
+**File**: `src/compliance/dsar-handler.ts`
+
+**Purpose**: Handle Data Subject Access Requests (GDPR Article 15).
+
+**DSAR Response**:
+
+```typescript
+interface DSARResponse {
+  request_id: string;
+  submitted_at: string;
+  completed_at: string;
+
+  // Identity confirmation
+  subject_verified: boolean;
+
+  // Data provided
+  personal_data: {
+    category: string;
+    data: unknown;
+    source: string;
+    retention_period: string;
+  }[];
+
+  // Processing information
+  processing_purposes: string[];
+  legal_bases: string[];
+  data_recipients: string[];  // Empty for local-only
+
+  // Rights information
+  available_rights: string[];
+
+  // Metadata
+  format: "json";
+  encrypted: boolean;
+}
+```
+
+**MCP Tool**:
+
+```typescript
+// New MCP tool: submit_data_access_request
+{
+  name: "submit_data_access_request",
+  description: "Submit a Data Subject Access Request (GDPR Article 15)",
+  inputSchema: {
+    type: "object",
+    properties: {
+      include_processing_info: { type: "boolean", default: true },
+      format: { type: "string", enum: ["json", "summary"], default: "summary" }
+    }
+  }
+}
+```
+
+---
+
+### 2.4 Data Inventory
+
+**File**: `src/compliance/data-inventory.ts`
+
+**Purpose**: Maintain inventory of all personal data stored.
+
+**Inventory Structure**:
+
+```typescript
+interface DataInventoryEntry {
+  id: string;
+
+  // What
+  data_type: string;
+  description: string;
+  classification: DataClassification;
+  data_categories: DataCategory[];
+
+  // Where
+  storage_location: string;
+  encrypted: boolean;
+
+  // How long
+  retention_policy: string;
+  retention_days: number | "indefinite";
+
+  // Legal
+  legal_basis: LegalBasis;
+  processing_purposes: string[];
+
+  // Access
+  who_can_access: string[];
+  exportable: boolean;
+  erasable: boolean;
+
+  // Metadata
+  last_updated: string;
+}
+```
+
+**Auto-Discovery**:
+- Scan data directories on startup
+- Register new data types automatically
+- Track data lifecycle
+
+---
+
+### 2.5 Retention Policy Engine
+
+**File**: `src/compliance/retention-engine.ts`
+
+**Purpose**: Enforce data retention policies automatically.
+
+**Policy Configuration**:
+
+```typescript
+interface RetentionPolicy {
+  id: string;
+  name: string;
+
+  // What it applies to
+  data_types: string[];
+  classifications?: DataClassification[];
+
+  // How long to keep
+  retention_days: number;
+
+  // What to do after expiry
+  action: "delete" | "archive" | "anonymize";
+
+  // When to run
+  schedule: "daily" | "weekly" | "monthly";
+
+  // Exceptions
+  exceptions?: {
+    condition: string;
+    extended_retention_days: number;
+  }[];
+
+  // Compliance
+  regulatory_requirement?: string; // e.g., "CSSF Circular 20/750"
+}
+```
+
+**Default Policies**:
+
+| Data Type | Retention | Action | Regulation |
+|-----------|-----------|--------|------------|
+| Audit logs | 7 years | Archive | CSSF |
+| Compliance events | 7 years | Archive | CSSF |
+| Session data | 24 hours | Delete | - |
+| Browser cache | 7 days | Delete | - |
+| Error logs | 30 days | Delete | - |
+| Consent records | 7 years | Archive | GDPR |
+| Erasure records | 7 years | Archive | GDPR |
+
+---
+
+## Phase 3: Security Monitoring & Incident Response
+
+### 3.1 SIEM Integration
+
+**File**: `src/compliance/siem-exporter.ts`
+
+**Purpose**: Export logs to external Security Information and Event Management systems.
+
+**Supported Formats**:
+
+```typescript
+type SIEMFormat =
+  | "json"           // Raw JSON
+  | "cef"            // Common Event Format (ArcSight)
+  | "leef"           // Log Event Extended Format (IBM QRadar)
+  | "syslog"         // RFC 5424 syslog
+  | "splunk_hec";    // Splunk HTTP Event Collector
+
+interface SIEMConfig {
+  enabled: boolean;
+  format: SIEMFormat;
+
+  // Destination
+  endpoint?: string;          // For HTTP-based (Splunk HEC)
+  syslog_host?: string;       // For syslog
+  syslog_port?: number;
+
+  // Authentication
+  api_key?: string;
+
+  // Filtering
+  min_severity: "info" | "warning" | "error" | "critical";
+  event_types: string[];      // Which events to export
+
+  // Batching
+  batch_size: number;         // Default: 100
+  flush_interval_ms: number;  // Default: 5000
+
+  // Reliability
+  retry_attempts: number;     // Default: 3
+  queue_max_size: number;     // Default: 10000
+}
+```
+
+**CEF Format Example**:
+
+```
+CEF:0|Pantheon Security|NotebookLM MCP|1.5.1|auth_failed|Authentication Failed|7|src=192.168.1.100 suser=unknown outcome=failure reason=invalid_token
+```
+
+**Configuration**:
+
+```bash
+NLMCP_SIEM_ENABLED=true
+NLMCP_SIEM_FORMAT=cef
+NLMCP_SIEM_ENDPOINT=https://siem.example.com/api/events
+NLMCP_SIEM_API_KEY=xxx
+NLMCP_SIEM_MIN_SEVERITY=warning
+```
+
+---
+
+### 3.2 Breach Detection
+
+**File**: `src/compliance/breach-detection.ts`
+
+**Purpose**: Detect potential security breaches and policy violations.
+
+**Detection Rules**:
+
+```typescript
+interface BreachRule {
+  id: string;
+  name: string;
+  description: string;
+  severity: "low" | "medium" | "high" | "critical";
+
+  // Detection
+  event_pattern: string;      // Regex or event type
+  threshold?: number;         // Count threshold
+  window_seconds?: number;    // Time window
+
+  // Response
+  actions: BreachAction[];
+
+  // Regulatory
+  notification_required: boolean;
+  notification_deadline_hours?: number; // e.g., 72 for GDPR
+}
+
+type BreachAction =
+  | "log"                     // Log to compliance events
+  | "alert"                   // Send alert
+  | "block"                   // Block further access
+  | "notify_admin"            // Email/webhook notification
+  | "create_incident";        // Create incident record
+
+```
+
+**Default Rules**:
+
+| Rule | Trigger | Severity | Actions |
+|------|---------|----------|---------|
+| Brute Force | 10 failed auth in 5 min | High | block, alert, log |
+| Secrets Leaked | Secrets detected in output | Critical | alert, log, create_incident |
+| Cert Pinning Violation | TLS cert mismatch | Critical | block, alert, log |
+| Unusual Access Pattern | Access outside normal hours | Medium | alert, log |
+| Mass Data Export | Large export request | Medium | log, notify_admin |
+| Encryption Failure | Encryption operation failed | High | alert, log |
+
+---
+
+### 3.3 Incident Response Log
+
+**File**: `src/compliance/incident-manager.ts`
+
+**Purpose**: Track and manage security incidents.
+
+**Incident Structure**:
+
+```typescript
+interface SecurityIncident {
+  id: string;
+
+  // Classification
+  type: IncidentType;
+  severity: "low" | "medium" | "high" | "critical";
+  status: "open" | "investigating" | "contained" | "resolved" | "closed";
+
+  // Timeline
+  detected_at: string;
+  reported_at?: string;
+  contained_at?: string;
+  resolved_at?: string;
+  closed_at?: string;
+
+  // Details
+  title: string;
+  description: string;
+  affected_data: string[];
+  affected_systems: string[];
+
+  // Response
+  actions_taken: IncidentAction[];
+  root_cause?: string;
+  remediation?: string;
+
+  // Notification
+  notification_required: boolean;
+  notification_sent?: boolean;
+  notification_deadline?: string;
+
+  // Evidence
+  related_events: string[];  // Event IDs from audit log
+}
+
+type IncidentType =
+  | "unauthorized_access"
+  | "data_breach"
+  | "malware"
+  | "dos_attack"
+  | "policy_violation"
+  | "data_loss"
+  | "configuration_error"
+  | "other";
+
+interface IncidentAction {
+  timestamp: string;
+  action: string;
+  performed_by: string;
+  notes?: string;
+}
+```
+
+---
+
+### 3.4 Alert System
+
+**File**: `src/compliance/alert-manager.ts`
+
+**Purpose**: Send alerts for security and compliance events.
+
+**Alert Channels**:
+
+```typescript
+interface AlertConfig {
+  enabled: boolean;
+
+  channels: {
+    // Console (always available)
+    console: boolean;
+
+    // File-based alerts
+    file?: {
+      path: string;
+      format: "json" | "text";
+    };
+
+    // Webhook (Slack, Teams, etc.)
+    webhook?: {
+      url: string;
+      headers?: Record<string, string>;
+      template?: string;
+    };
+
+    // Email (via external service)
+    email?: {
+      smtp_host: string;
+      smtp_port: number;
+      from: string;
+      to: string[];
+      use_tls: boolean;
+    };
+  };
+
+  // Filtering
+  min_severity: "info" | "warning" | "error" | "critical";
+  event_types?: string[];
+
+  // Rate limiting
+  cooldown_seconds: number;  // Don't repeat same alert within
+  max_alerts_per_hour: number;
+}
+```
+
+**Configuration**:
+
+```bash
+NLMCP_ALERTS_ENABLED=true
+NLMCP_ALERTS_WEBHOOK_URL=https://hooks.slack.com/xxx
+NLMCP_ALERTS_MIN_SEVERITY=warning
+NLMCP_ALERTS_COOLDOWN=300
+```
+
+---
+
+### 3.5 Health Monitoring
+
+**File**: `src/compliance/health-monitor.ts`
+
+**Purpose**: Monitor system health and availability (SOC2 requirement).
+
+**Health Metrics**:
+
+```typescript
+interface HealthMetrics {
+  timestamp: string;
+
+  // System health
+  status: "healthy" | "degraded" | "unhealthy";
+  uptime_seconds: number;
+
+  // Component status
+  components: {
+    name: string;
+    status: "up" | "down" | "degraded";
+    last_check: string;
+    response_time_ms?: number;
+    error?: string;
+  }[];
+
+  // Resource usage
+  resources: {
+    memory_used_mb: number;
+    memory_limit_mb: number;
+    disk_used_mb: number;
+    disk_available_mb: number;
+  };
+
+  // Security status
+  security: {
+    encryption_enabled: boolean;
+    auth_enabled: boolean;
+    cert_pinning_enabled: boolean;
+    last_security_scan?: string;
+    open_incidents: number;
+  };
+
+  // Compliance status
+  compliance: {
+    consent_valid: boolean;
+    retention_policies_active: number;
+    pending_erasure_requests: number;
+    last_compliance_check: string;
+  };
+}
+```
+
+**MCP Tool Enhancement**:
+
+```typescript
+// Enhance existing get_health tool
+{
+  name: "get_health",
+  description: "Get server health including compliance status",
+  // Add compliance metrics to response
+}
+```
+
+---
+
+## Phase 4: Compliance Reporting & Documentation
+
+### 4.1 Compliance Dashboard
+
+**File**: `src/compliance/dashboard.ts`
+
+**Purpose**: Generate compliance status overview.
+
+**Dashboard Output**:
+
+```typescript
+interface ComplianceDashboard {
+  generated_at: string;
+
+  // Overall status
+  overall_status: "compliant" | "non_compliant" | "needs_attention";
+
+  // By regulation
+  regulations: {
+    name: "GDPR" | "SOC2" | "CSSF";
+    status: "compliant" | "non_compliant" | "partial";
+    requirements_met: number;
+    requirements_total: number;
+    issues: ComplianceIssue[];
+  }[];
+
+  // Key metrics
+  metrics: {
+    active_consents: number;
+    pending_dsars: number;
+    pending_erasures: number;
+    open_incidents: number;
+    audit_log_integrity: "verified" | "issues_found";
+    encryption_status: "enabled" | "disabled" | "partial";
+    retention_compliance: number; // Percentage
+  };
+
+  // Recent events
+  recent_compliance_events: ComplianceEvent[];
+
+  // Upcoming deadlines
+  deadlines: {
+    type: string;
+    deadline: string;
+    days_remaining: number;
+  }[];
+}
+
+interface ComplianceIssue {
+  severity: "critical" | "high" | "medium" | "low";
+  regulation: string;
+  requirement: string;
+  description: string;
+  remediation: string;
+}
+```
+
+**MCP Tool**:
+
+```typescript
+// New MCP tool: get_compliance_status
+{
+  name: "get_compliance_status",
+  description: "Get compliance dashboard showing status across GDPR, SOC2, CSSF",
+  inputSchema: {
+    type: "object",
+    properties: {
+      regulations: {
+        type: "array",
+        items: { type: "string", enum: ["GDPR", "SOC2", "CSSF"] },
+        default: ["GDPR", "SOC2", "CSSF"]
+      },
+      include_events: { type: "boolean", default: true }
+    }
+  }
+}
+```
+
+---
+
+### 4.2 Audit Report Generator
+
+**File**: `src/compliance/report-generator.ts`
+
+**Purpose**: Generate compliance audit reports.
+
+**Report Types**:
+
+```typescript
+type ReportType =
+  | "compliance_summary"     // High-level compliance status
+  | "audit_trail"            // Detailed audit log report
+  | "access_report"          // Who accessed what
+  | "retention_report"       // Data retention status
+  | "incident_report"        // Security incident summary
+  | "dsar_report"            // Data subject request summary
+  | "consent_report";        // Consent status report
+
+interface ReportConfig {
+  type: ReportType;
+
+  // Time range
+  from_date: string;
+  to_date: string;
+
+  // Format
+  format: "json" | "html" | "pdf" | "csv";
+
+  // Filters
+  regulations?: string[];
+  severity_min?: string;
+
+  // Output
+  output_path?: string;
+  include_evidence?: boolean;
+}
+```
+
+---
+
+### 4.3 Policy Documentation
+
+**File**: `src/compliance/policy-docs.ts`
+
+**Purpose**: Machine-readable policy documentation.
+
+**Policies**:
+
+```typescript
+interface PolicyDocument {
+  id: string;
+  type: PolicyType;
+  version: string;
+  effective_date: string;
+
+  // Content
+  title: string;
+  description: string;
+  full_text: string;
+
+  // Applicability
+  regulations: string[];
+  data_types: string[];
+
+  // Enforcement
+  enforced: boolean;
+  enforcement_method: "automatic" | "manual" | "audit";
+
+  // Review
+  last_reviewed: string;
+  next_review: string;
+  approved_by: string;
+}
+
+type PolicyType =
+  | "privacy_policy"
+  | "data_retention"
+  | "access_control"
+  | "encryption"
+  | "incident_response"
+  | "acceptable_use";
+```
+
+---
+
+### 4.4 Change Log
+
+**File**: `src/compliance/change-log.ts`
+
+**Purpose**: Track all configuration changes (SOC2 requirement).
+
+**Change Record**:
+
+```typescript
+interface ChangeRecord {
+  id: string;
+  timestamp: string;
+
+  // What changed
+  component: string;
+  setting: string;
+  old_value: unknown;
+  new_value: unknown;
+
+  // Who/how
+  changed_by: "user" | "system" | "admin";
+  method: "cli" | "env" | "api" | "config_file";
+
+  // Approval (for sensitive changes)
+  requires_approval: boolean;
+  approved_by?: string;
+  approved_at?: string;
+
+  // Impact
+  impact: "low" | "medium" | "high";
+  affected_compliance: string[];
+}
+```
+
+---
+
+### 4.5 Evidence Collection
+
+**File**: `src/compliance/evidence-collector.ts`
+
+**Purpose**: Automated collection of compliance evidence for audits.
+
+**Evidence Types**:
+
+```typescript
+interface EvidencePackage {
+  id: string;
+  generated_at: string;
+
+  // What it's for
+  audit_type: "SOC2" | "GDPR" | "CSSF" | "internal";
+  period: { from: string; to: string };
+
+  // Contents
+  items: EvidenceItem[];
+
+  // Integrity
+  checksum: string;
+  signed_by?: string;
+}
+
+interface EvidenceItem {
+  id: string;
+  type: EvidenceType;
+  description: string;
+
+  // Content
+  content: string | object;
+  format: "json" | "text" | "screenshot" | "log";
+
+  // Metadata
+  collected_at: string;
+  source: string;
+
+  // Compliance mapping
+  controls: string[];  // e.g., ["SOC2-CC6.1", "GDPR-Art32"]
+}
+
+type EvidenceType =
+  | "policy_document"
+  | "configuration"
+  | "audit_log_sample"
+  | "access_review"
+  | "encryption_status"
+  | "retention_proof"
+  | "consent_records"
+  | "incident_response";
+```
+
+---
+
+## Configuration Reference
+
+### All New Environment Variables
+
+```bash
+# ============================================
+# COMPLIANCE CONFIGURATION
+# ============================================
+
+# Core Compliance
+NLMCP_COMPLIANCE_ENABLED=true              # Enable compliance features
+NLMCP_COMPLIANCE_MODE=full                 # full | minimal | audit_only
+NLMCP_COMPLIANCE_REGULATIONS=GDPR,SOC2,CSSF  # Which regulations to enforce
+
+# Compliance Logging
+NLMCP_COMPLIANCE_DIR=/path/to/compliance   # Compliance event directory
+NLMCP_COMPLIANCE_RETENTION_YEARS=7         # Retention for compliance events
+NLMCP_COMPLIANCE_ENCRYPTION=true           # Encrypt compliance logs
+
+# Consent Management
+NLMCP_CONSENT_REQUIRED=true                # Require consent on first run
+NLMCP_CONSENT_VERSION=1.0.0                # Current consent version
+NLMCP_PRIVACY_NOTICE_URL=https://...       # Link to full privacy policy
+
+# Data Subject Rights
+NLMCP_DSAR_ENABLED=true                    # Enable DSAR handling
+NLMCP_ERASURE_ENABLED=true                 # Enable right to erasure
+NLMCP_EXPORT_ENABLED=true                  # Enable data export
+NLMCP_EXPORT_ENCRYPT=false                 # Encrypt exports by default
+
+# Retention Policies
+NLMCP_RETENTION_AUDIT_DAYS=2555            # 7 years for audit logs
+NLMCP_RETENTION_SESSION_HOURS=24           # Session data retention
+NLMCP_RETENTION_BROWSER_DAYS=7             # Browser cache retention
+NLMCP_RETENTION_CHECK_SCHEDULE=daily       # When to run retention cleanup
+
+# SIEM Integration
+NLMCP_SIEM_ENABLED=false                   # Enable SIEM export
+NLMCP_SIEM_FORMAT=cef                      # cef | leef | syslog | json | splunk_hec
+NLMCP_SIEM_ENDPOINT=https://...            # SIEM endpoint URL
+NLMCP_SIEM_API_KEY=xxx                     # SIEM API key
+NLMCP_SIEM_BATCH_SIZE=100                  # Events per batch
+NLMCP_SIEM_FLUSH_INTERVAL_MS=5000          # Flush interval
+
+# Breach Detection
+NLMCP_BREACH_DETECTION=true                # Enable breach detection
+NLMCP_BREACH_NOTIFICATION=true             # Auto-notify on breach
+NLMCP_BREACH_WEBHOOK=https://...           # Breach notification webhook
+
+# Incident Response
+NLMCP_INCIDENT_TRACKING=true               # Enable incident tracking
+NLMCP_INCIDENT_AUTO_CREATE=true            # Auto-create incidents on breach
+
+# Alerts
+NLMCP_ALERTS_ENABLED=true                  # Enable alerts
+NLMCP_ALERTS_WEBHOOK_URL=https://...       # Slack/Teams webhook
+NLMCP_ALERTS_EMAIL_TO=security@example.com # Alert email recipients
+NLMCP_ALERTS_MIN_SEVERITY=warning          # Minimum alert severity
+NLMCP_ALERTS_COOLDOWN=300                  # Seconds between repeated alerts
+
+# Health Monitoring
+NLMCP_HEALTH_MONITORING=true               # Enable health monitoring
+NLMCP_HEALTH_CHECK_INTERVAL=60             # Seconds between health checks
+
+# Reporting
+NLMCP_REPORTS_DIR=/path/to/reports         # Report output directory
+NLMCP_REPORTS_AUTO_GENERATE=false          # Auto-generate periodic reports
+NLMCP_REPORTS_SCHEDULE=monthly             # Report generation schedule
+```
+
+---
+
+## File Structure
+
+```
+src/
+├── compliance/
+│   ├── index.ts                    # Module exports
+│   ├── compliance-logger.ts        # Phase 1.1
+│   ├── data-classification.ts      # Phase 1.2
+│   ├── consent-manager.ts          # Phase 1.3
+│   ├── privacy-notice.ts           # Phase 1.4
+│   ├── privacy-notice-text.ts      # Privacy notice content
+│   ├── data-export.ts              # Phase 2.1
+│   ├── data-erasure.ts             # Phase 2.2
+│   ├── dsar-handler.ts             # Phase 2.3
+│   ├── data-inventory.ts           # Phase 2.4
+│   ├── retention-engine.ts         # Phase 2.5
+│   ├── siem-exporter.ts            # Phase 3.1
+│   ├── breach-detection.ts         # Phase 3.2
+│   ├── incident-manager.ts         # Phase 3.3
+│   ├── alert-manager.ts            # Phase 3.4
+│   ├── health-monitor.ts           # Phase 3.5
+│   ├── dashboard.ts                # Phase 4.1
+│   ├── report-generator.ts         # Phase 4.2
+│   ├── policy-docs.ts              # Phase 4.3
+│   ├── change-log.ts               # Phase 4.4
+│   ├── evidence-collector.ts       # Phase 4.5
+│   └── types.ts                    # Shared types
+├── utils/
+│   └── audit-logger.ts             # Enhanced (Phase 1.5)
+└── tools/
+    └── compliance-tools.ts         # New MCP tools
+```
+
+---
+
+## Implementation Order
+
+### Phase 1 (Foundation) - Implement First
+1. `types.ts` - Shared types
+2. `compliance-logger.ts` - Core logging
+3. `data-classification.ts` - Classification system
+4. `consent-manager.ts` - Consent tracking
+5. `privacy-notice.ts` + `privacy-notice-text.ts` - Privacy display
+6. Update `audit-logger.ts` - Enhanced events
+
+### Phase 2 (GDPR Rights) - Implement Second
+1. `data-inventory.ts` - Data catalog
+2. `retention-engine.ts` - Retention enforcement
+3. `data-export.ts` - Export functionality
+4. `data-erasure.ts` - Erasure functionality
+5. `dsar-handler.ts` - DSAR handling
+
+### Phase 3 (Monitoring) - Implement Third
+1. `alert-manager.ts` - Alert system
+2. `breach-detection.ts` - Breach detection
+3. `incident-manager.ts` - Incident tracking
+4. `siem-exporter.ts` - SIEM integration
+5. `health-monitor.ts` - Health monitoring
+
+### Phase 4 (Reporting) - Implement Last
+1. `change-log.ts` - Change tracking
+2. `policy-docs.ts` - Policy documentation
+3. `dashboard.ts` - Compliance dashboard
+4. `report-generator.ts` - Report generation
+5. `evidence-collector.ts` - Evidence collection
+6. `compliance-tools.ts` - MCP tools
+
+---
+
+## Approval
+
+- [ ] Phase 1 Specification Approved
+- [ ] Phase 2 Specification Approved
+- [ ] Phase 3 Specification Approved
+- [ ] Phase 4 Specification Approved
+
+**Approved By**: ___________________
+**Date**: ___________________