guideai-app 0.4.3-1 → 0.4.3-2

package/PII_HASHING_EPIC.md

@@ -1,886 +0,0 @@
-# Epic: Implement PII Hashing for Enhanced Privacy & Security
-
-## Overview
-Implement client-side hashing of Personally Identifiable Information (PII) before sending to backend APIs to improve privacy, security, and GDPR/CCPA compliance. This will prevent PII from appearing in logs, monitoring tools, and third-party services.
-
-**Impact:** 
-- ✅ Reduces PII exposure in server logs, APM tools, and monitoring systems
-- ✅ Improves GDPR/CCPA compliance through pseudonymization
-- ✅ Maintains user tracking capabilities across sessions
-- ✅ Reduces attack surface (leaked logs don't expose emails)
-
-**Estimated Timeline:** 2 weeks (1 week FE, 1 week BE + Testing)
-
----
-
-## Story Map
-
-```
-Epic: PII Hashing
-├── Frontend Stories (Guide AI Package)
-│   ├── FE-1: Create PII Hashing Utility
-│   ├── FE-2: Update UserMetadataTracker to Hash Emails
-│   ├── FE-3: Update API Layer for Hashed Identifiers
-│   ├── FE-4: Add Privacy Configuration Options
-│   └── FE-5: Add Unit & Integration Tests
-│
-└── Backend Stories (BE Repo - High Level)
-    ├── BE-1: Update API Endpoints for Hashed Email Handling
-    ├── BE-2: Create Email Hash Mapping System
-    ├── BE-3: Update Database Schema
-    └── BE-4: Add Email Retrieval & Notification Logic
-```
-
----
-
-# Frontend Stories (Detailed)
-
-## FE-1: Create PII Hashing Utility
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 3  
-**Owner:** Frontend Team
-
-### User Story
-As a developer, I need a reusable utility function to hash PII data so that sensitive information is never sent in plain text to the backend.
-
-### Acceptance Criteria
-- [ ] Create `src/utils/pii.ts` with hashing utilities
-- [ ] Implement `hashEmail()` function using SHA-256
-- [ ] Implement generic `hashPII()` function for other PII fields
-- [ ] Functions return consistent hashes (same input = same output)
-- [ ] Functions are async and use Web Crypto API
-- [ ] Include JSDoc documentation
-- [ ] Add TypeScript types for hashed data
-- [ ] Works in browser environments (no Node.js dependencies)
-
-### Technical Details
-
-**New File:** `src/utils/pii.ts`
-
-```typescript
-/**
- * PII Hashing Utilities
- * 
- * Provides client-side hashing of Personally Identifiable Information (PII)
- * using SHA-256 before sending to backend. This prevents PII exposure in logs,
- * monitoring tools, and third-party services.
- */
-
-/**
- * Hash an email address using SHA-256
- * @param email - The email address to hash
- * @returns Promise resolving to hex-encoded hash
- */
-export async function hashEmail(email: string): Promise<string> {
-  if (!email || typeof email !== 'string') {
-    throw new Error('Invalid email: must be a non-empty string');
-  }
-  
-  // Normalize email (lowercase, trim) for consistent hashing
-  const normalizedEmail = email.toLowerCase().trim();
-  return hashPII(normalizedEmail);
-}
-
-/**
- * Generic PII hashing function using SHA-256
- * @param data - The PII string to hash
- * @returns Promise resolving to hex-encoded hash
- */
-export async function hashPII(data: string): Promise<string> {
-  if (!data || typeof data !== 'string') {
-    throw new Error('Invalid data: must be a non-empty string');
-  }
-  
-  try {
-    // Use Web Crypto API (supported in all modern browsers)
-    const encoder = new TextEncoder();
-    const dataBuffer = encoder.encode(data);
-    const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer);
-    
-    // Convert to hex string
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    const hashHex = hashArray
-      .map(byte => byte.toString(16).padStart(2, '0'))
-      .join('');
-    
-    return hashHex;
-  } catch (error) {
-    console.error('PII hashing failed:', error);
-    throw new Error('Failed to hash PII data');
-  }
-}
-
-/**
- * Check if a value is already hashed (64-char hex string = SHA-256)
- * @param value - The value to check
- * @returns True if value appears to be a SHA-256 hash
- */
-export function isHashed(value: string): boolean {
-  if (!value || typeof value !== 'string') return false;
-  // SHA-256 produces 64 hex characters
-  return /^[a-f0-9]{64}$/i.test(value);
-}
-```
-
-**Testing Strategy:**
-- Unit tests for each function
-- Test edge cases (empty string, null, undefined, non-string)
-- Test hash consistency (same email → same hash)
-- Test normalization (Email@test.com === email@test.com)
-
-**Dependencies:** None (uses built-in Web Crypto API)
-
----
-
-## FE-2: Update UserMetadataTracker to Hash Emails
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 5  
-**Owner:** Frontend Team  
-**Depends On:** FE-1
-
-### User Story
-As a developer, I need the metadata tracker to automatically hash email addresses before storing them locally and sending to the backend, so that PII is never exposed in plain text.
-
-### Acceptance Criteria
-- [ ] Import hashing utilities in `metadata-tracker.tsx`
-- [ ] Hash email in `updateUserInfo()` method before storing
-- [ ] Hash email in `trackLogin()` method before creating updates
-- [ ] Hash email in all `trackVisit*()` methods before creating updates
-- [ ] Hash email in `trackCustomEvent()` method if present
-- [ ] Store hashed email in localStorage (not plain text)
-- [ ] Update pending updates to include hashed email
-- [ ] Maintain backward compatibility with existing stored data
-- [ ] Add logging for hashing operations (development mode only)
-- [ ] Handle hashing errors gracefully (don't break tracking)
-
-### Technical Details
-
-**Files to Modify:**
-- `src/metric/metadata-tracker.tsx`
-
-**Changes Required:**
-
-1. **Import hashing utility** (top of file):
-```typescript
-import { hashEmail, isHashed } from '../utils/pii';
-```
-
-2. **Update `updateUserInfo()` method** (lines 121-159):
-```typescript
-public async updateUserInfo(userInfo: Partial<UserMetadata>): Promise<void> {
-  const timestamp = Date.now();
-  
-  // Extract email from user object if present
-  const rawEmail = userInfo.user?.email || userInfo.email;
-  
-  // Hash email if provided
-  let hashedEmail: string | undefined;
-  if (rawEmail) {
-    try {
-      // Only hash if not already hashed
-      hashedEmail = isHashed(rawEmail) ? rawEmail : await hashEmail(rawEmail);
-      Logger.metadata('Email hashed for user info update', { hashedEmail });
-    } catch (error) {
-      Logger.error('Metadata', 'Failed to hash email', error);
-      // Continue without email rather than exposing plain text
-    }
-  }
-  
-  // Create updated info with hashed email
-  const updatedInfo = {
-    ...userInfo,
-    ...(hashedEmail && { emailHash: hashedEmail }),
-    email: undefined // Remove plain text email
-  };
-  
-  // ... rest of method
-}
-```
-
-3. **Update `trackLogin()` method** (lines 161-195):
-```typescript
-public async trackLogin(additionalInfo?: Partial<UserMetadata>): Promise<void> {
-  if (!this.config.trackLogins) return;
-
-  const timestamp = Date.now();
-  
-  // ... duplicate check logic ...
-  
-  // Hash email if present
-  let hashedEmail: string | undefined;
-  if (this.metadata.emailHash) {
-    hashedEmail = this.metadata.emailHash;
-  }
-  
-  this.metadata = {
-    ...this.metadata,
-    ...additionalInfo,
-    loginCount: (this.metadata.loginCount || 0) + 1,
-    lastLogin: timestamp,
-    lastVisit: timestamp
-  };
-
-  this.addPendingUpdate({
-    type: 'login',
-    timestamp,
-    data: {
-      sessionId: this.metadata.sessionId,
-      ...(hashedEmail && { emailHash: hashedEmail }),
-      loginCount: this.metadata.loginCount,
-      lastLogin: timestamp,
-      ...additionalInfo
-    }
-  });
-
-  // ... rest of method
-}
-```
-
-4. **Similar updates for:**
-- `trackVisitIfNewSession()` (lines 197-253)
-- `trackVisitManually()` (lines 270-303)
-- `trackCustomEvent()` (lines 305-336)
-
-**Migration Strategy:**
-- Existing plain-text emails in localStorage will be hashed on next update
-- Add migration helper in `loadMetadata()` to detect and hash old emails
-- Keep system working during transition period
-
-**Error Handling:**
-- Wrap hashing calls in try-catch
-- Log errors but don't fail the tracking operation
-- If hashing fails, omit email rather than sending plain text
-
----
-
-## FE-3: Update API Layer for Hashed Identifiers
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 3  
-**Owner:** Frontend Team  
-**Depends On:** FE-1, FE-2
-
-### User Story
-As a developer, I need the API layer to send hashed email identifiers instead of plain text, so that backend logs and monitoring systems never see PII.
-
-### Acceptance Criteria
-- [ ] Update `MetadataUpdate` type to use `emailHash` instead of `email`
-- [ ] Update `sendMetadataUpdates()` to validate hashed format
-- [ ] Ensure no plain-text email is ever sent in API requests
-- [ ] Add logging to verify hashed data in requests (dev mode)
-- [ ] Update request body structure in API calls
-- [ ] Add JSDoc comments explaining hashed fields
-
-### Technical Details
-
-**Files to Modify:**
-1. `src/types/metadata.types.ts`
-2. `src/utils/api.ts`
-
-**Changes in `metadata.types.ts`:**
-```typescript
-export interface UserMetadata {
-  // Core user identification
-  userId?: string;
-  
-  // DEPRECATED: Use emailHash instead (for backward compatibility only)
-  email?: string;
-  
-  // Hashed email identifier (SHA-256)
-  // Use this for user identification instead of plain email
-  emailHash?: string;
-  
-  userType?: 'agent' | 'admin' | 'manager' | 'customer' | 'guest' | string;
-  
-  // ... rest of interface
-}
-```
-
-**Changes in `api.ts`:**
-```typescript
-// Add validation before sending
-export const sendMetadataUpdates = async (
-  updates: MetadataUpdate[],
-  organizationKey: string,
-  onError: (error: Error, context: string) => void
-): Promise<boolean> => {
-  if (updates.length === 0) return true;
-
-  try {
-    // Validate that no plain-text emails are being sent
-    if (process.env.NODE_ENV === 'development') {
-      updates.forEach(update => {
-        if (update.data.email && !update.data.emailHash) {
-          console.warn('⚠️ Plain-text email detected in metadata update!', update);
-        }
-      });
-    }
-
-    const requestData = {
-      organizationKey,
-      updates,
-      batchTimestamp: Date.now(),
-      updateCount: updates.length
-    };
-    
-    Logger.apiCall('POST', '/metadata-updates', requestData);
-    
-    // ... rest of method
-  }
-  // ... error handling
-};
-```
-
-**Validation Rules:**
-- Warn if `email` field exists without corresponding `emailHash`
-- Verify `emailHash` matches SHA-256 format (64 hex chars)
-- Only in development mode to avoid performance overhead
-
----
-
-## FE-4: Add Privacy Configuration Options
-
-**Priority:** P1 (High)  
-**Story Points:** 2  
-**Owner:** Frontend Team  
-**Depends On:** FE-1, FE-2
-
-### User Story
-As a developer integrating GuideAI, I want configuration options to control PII hashing behavior, so I can customize privacy settings based on my application's requirements.
-
-### Acceptance Criteria
-- [ ] Add `enablePIIHashing` config option (default: true)
-- [ ] Add `piiFields` config option to specify which fields to hash
-- [ ] Add `allowPlainTextFallback` option for backward compatibility
-- [ ] Update `MetadataConfig` type with new options
-- [ ] Document new configuration options
-- [ ] Respect config in metadata tracker
-
-### Technical Details
-
-**Files to Modify:**
-- `src/types/metadata.types.ts`
-
-**New Configuration:**
-```typescript
-export interface MetadataConfig {
-  // ... existing options ...
-  
-  // Privacy & PII Settings
-  
-  /**
-   * Enable automatic PII hashing before storage/transmission
-   * @default true
-   */
-  enablePIIHashing?: boolean;
-  
-  /**
-   * List of PII fields to hash (if enablePIIHashing is true)
-   * @default ['email']
-   */
-  piiFields?: Array<'email' | 'userId' | 'customerId' | string>;
-  
-  /**
-   * Allow plain-text fallback if hashing fails
-   * WARNING: Only enable for backward compatibility during migration
-   * @default false
-   */
-  allowPlainTextFallback?: boolean;
-}
-```
-
-**Usage Example:**
-```typescript
-const tracker = new UserMetadataTracker('org-key', {
-  enablePIIHashing: true, // Hash PII before sending
-  piiFields: ['email', 'customerId'], // Which fields to hash
-  allowPlainTextFallback: false, // Never send plain text
-});
-```
-
----
-
-## FE-5: Add Unit & Integration Tests
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 5  
-**Owner:** Frontend Team  
-**Depends On:** FE-1, FE-2, FE-3
-
-### User Story
-As a developer, I need comprehensive tests for PII hashing functionality to ensure it works correctly and doesn't break existing features.
-
-### Acceptance Criteria
-- [ ] Unit tests for `pii.ts` utility functions (90%+ coverage)
-- [ ] Unit tests for metadata tracker hashing logic (90%+ coverage)
-- [ ] Integration tests for end-to-end hashing flow
-- [ ] Tests for error handling and edge cases
-- [ ] Tests for backward compatibility with existing data
-- [ ] Tests verify no plain-text emails in API calls
-- [ ] Mock Web Crypto API for tests
-- [ ] All tests pass in CI/CD pipeline
-
-### Technical Details
-
-**New Test Files:**
-1. `src/utils/pii.test.ts` (unit tests)
-2. `src/metric/metadata-tracker.pii.test.ts` (integration tests)
-
-**Test Cases:**
-
-**Unit Tests (`pii.test.ts`):**
-```typescript
-describe('PII Hashing Utils', () => {
-  describe('hashEmail', () => {
-    it('should hash email to 64-char hex string', async () => {
-      const hash = await hashEmail('user@example.com');
-      expect(hash).toMatch(/^[a-f0-9]{64}$/);
-    });
-
-    it('should produce consistent hashes', async () => {
-      const hash1 = await hashEmail('user@example.com');
-      const hash2 = await hashEmail('user@example.com');
-      expect(hash1).toBe(hash2);
-    });
-
-    it('should normalize emails (case-insensitive)', async () => {
-      const hash1 = await hashEmail('User@Example.com');
-      const hash2 = await hashEmail('user@example.com');
-      expect(hash1).toBe(hash2);
-    });
-
-    it('should throw error for invalid input', async () => {
-      await expect(hashEmail('')).rejects.toThrow();
-      await expect(hashEmail(null as any)).rejects.toThrow();
-    });
-  });
-
-  describe('isHashed', () => {
-    it('should identify valid hashes', () => {
-      const validHash = 'a'.repeat(64);
-      expect(isHashed(validHash)).toBe(true);
-    });
-
-    it('should reject invalid hashes', () => {
-      expect(isHashed('short')).toBe(false);
-      expect(isHashed('user@example.com')).toBe(false);
-      expect(isHashed('')).toBe(false);
-    });
-  });
-});
-```
-
-**Integration Tests (`metadata-tracker.pii.test.ts`):**
-```typescript
-describe('MetadataTracker PII Hashing', () => {
-  it('should hash email in updateUserInfo', async () => {
-    const tracker = new UserMetadataTracker('test-org');
-    tracker.init();
-    
-    await tracker.updateUserInfo({ email: 'user@test.com' });
-    
-    const metadata = tracker.getMetadata();
-    expect(metadata.email).toBeUndefined();
-    expect(metadata.emailHash).toMatch(/^[a-f0-9]{64}$/);
-  });
-
-  it('should not send plain-text email to API', async () => {
-    const mockSendMetadata = jest.fn();
-    // ... mock API call
-    
-    await tracker.updateUserInfo({ email: 'user@test.com' });
-    await tracker.emitPendingUpdates();
-    
-    const apiCall = mockSendMetadata.mock.calls[0][0];
-    const hasPlainEmail = JSON.stringify(apiCall).includes('user@test.com');
-    expect(hasPlainEmail).toBe(false);
-  });
-
-  it('should handle hashing errors gracefully', async () => {
-    // Mock crypto.subtle.digest to fail
-    jest.spyOn(crypto.subtle, 'digest').mockRejectedValue(new Error('Crypto failed'));
-    
-    const tracker = new UserMetadataTracker('test-org');
-    
-    // Should not throw
-    await expect(
-      tracker.updateUserInfo({ email: 'user@test.com' })
-    ).resolves.not.toThrow();
-    
-    // Email should be omitted (not sent in plain text)
-    const updates = tracker.getPendingUpdates();
-    expect(updates[0].data.email).toBeUndefined();
-    expect(updates[0].data.emailHash).toBeUndefined();
-  });
-});
-```
-
-**Run Tests:**
-```bash
-npm test -- --coverage
-```
-
----
-
-# Backend Stories (High Level)
-
-## BE-1: Update API Endpoints for Hashed Email Handling
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 8  
-**Owner:** Backend Team
-
-### User Story
-As a backend developer, I need to update API endpoints to receive and process hashed emails instead of plain-text emails, so that our logs and monitoring systems never contain PII.
-
-### Acceptance Criteria
-- [ ] Update `/initialize-session` endpoint to accept `emailHash` instead of `email`
-- [ ] Update `/metadata-updates` endpoint to process `emailHash` field
-- [ ] Update `/conversations/:id/messages` endpoint if it handles user data
-- [ ] Validate that `emailHash` matches SHA-256 format (64 hex chars)
-- [ ] Add backward compatibility for transition period
-- [ ] Update API documentation/OpenAPI spec
-- [ ] Log hashed emails only, never plain text
-- [ ] Deploy to staging environment for testing
-
-### Technical Notes
-- Accept both `email` and `emailHash` during migration (deprecate `email` later)
-- Validate hash format: `/^[a-f0-9]{64}$/i`
-- Update request validation schemas
-- Ensure no plain-text emails in application logs
-- Update error messages to not expose PII
-
-### Backend Framework Considerations
-- If using Express/Node: Update request validators
-- If using Django/Python: Update serializers/validators
-- If using Spring/Java: Update DTOs and validation annotations
-
----
-
-## BE-2: Create Email Hash Mapping System
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 13  
-**Owner:** Backend Team  
-**Depends On:** BE-1
-
-### User Story
-As a backend developer, I need a secure system to store and retrieve the mapping between hashed emails and actual email addresses, so we can send notifications while keeping hashes in logs.
-
-### Acceptance Criteria
-- [ ] Create `email_mappings` table/collection
-- [ ] Store mapping: `emailHash → encryptedEmail`
-- [ ] Encrypt actual emails at rest in database
-- [ ] Implement secure key management for encryption
-- [ ] Create API for email lookup by hash
-- [ ] Add strict access controls (only specific services can decrypt)
-- [ ] Implement audit logging for email decryption
-- [ ] Add cache layer for frequently accessed mappings (Redis)
-- [ ] Handle hash collisions (extremely unlikely but possible)
-- [ ] Add data retention policies
-
-### Technical Notes
-
-**Database Schema (Example):**
-```sql
-CREATE TABLE email_mappings (
-  email_hash VARCHAR(64) PRIMARY KEY,
-  encrypted_email BYTEA NOT NULL,
-  encryption_key_id VARCHAR(50) NOT NULL,
-  organization_key VARCHAR(100) NOT NULL,
-  first_seen TIMESTAMP DEFAULT NOW(),
-  last_seen TIMESTAMP DEFAULT NOW(),
-  access_count INTEGER DEFAULT 0,
-  INDEX idx_org_key (organization_key)
-);
-```
-
-**Key Points:**
-- Use AES-256-GCM for email encryption
-- Store encryption key in KMS (AWS KMS, HashiCorp Vault, etc.)
-- Rotate encryption keys periodically
-- Log all email decryption operations
-- Implement rate limiting on lookups
-- Cache mappings in Redis with TTL
-
-**API Design:**
-```
-POST /internal/email-mappings
-- Register new hash → email mapping
-- Returns: success status
-
-GET /internal/email-mappings/{hash}
-- Retrieve actual email for notification
-- Requires internal service authentication
-- Returns: decrypted email
-```
-
----
-
-## BE-3: Update Database Schema
-
-**Priority:** P0 (Blocker)  
-**Story Points:** 5  
-**Owner:** Backend Team  
-**Depends On:** BE-2
-
-### User Story
-As a backend developer, I need to update database schemas to use `emailHash` instead of `email` for user identification in metadata/analytics tables.
-
-### Acceptance Criteria
-- [ ] Add `email_hash` column to relevant tables
-- [ ] Create migration script for existing data
-- [ ] Hash existing plain-text emails in database
-- [ ] Add index on `email_hash` for performance
-- [ ] Update all queries to use `email_hash`
-- [ ] Keep `email` column temporarily for backward compatibility
-- [ ] Plan deprecation of `email` column (after migration complete)
-- [ ] Test migration on staging database first
-- [ ] Verify no performance degradation after migration
-
-### Technical Notes
-
-**Tables to Update:**
-- `user_metadata`
-- `user_sessions`
-- `user_visits`
-- `conversation_logs`
-- Any other tables storing user identifiers
-
-**Migration Strategy:**
-```sql
--- Step 1: Add new column
-ALTER TABLE user_metadata 
-ADD COLUMN email_hash VARCHAR(64);
-
--- Step 2: Backfill hashes (run incrementally)
--- Use same SHA-256 algorithm as frontend
-
--- Step 3: Create index
-CREATE INDEX idx_email_hash ON user_metadata(email_hash);
-
--- Step 4: Update application code to use email_hash
-
--- Step 5: (Future) Drop email column after verification period
--- ALTER TABLE user_metadata DROP COLUMN email;
-```
-
-**Data Migration:**
-- Hash existing emails using same algorithm (SHA-256)
-- Normalize emails before hashing (lowercase, trim)
-- Store hashes in email_mappings table
-- Run migration in batches to avoid locking tables
-- Verify hash consistency between FE and BE
-
----
-
-## BE-4: Add Email Retrieval & Notification Logic
-
-**Priority:** P1 (High)  
-**Story Points:** 8  
-**Owner:** Backend Team  
-**Depends On:** BE-2, BE-3
-
-### User Story
-As a backend developer, I need to implement secure email retrieval logic for sending notifications, so that we can contact users while keeping hashed identifiers in all other systems.
-
-### Acceptance Criteria
-- [ ] Create service layer for email retrieval
-- [ ] Implement notification service that looks up emails by hash
-- [ ] Add authentication/authorization for email access
-- [ ] Log all email access attempts (audit trail)
-- [ ] Implement rate limiting on email lookups
-- [ ] Add monitoring/alerts for suspicious access patterns
-- [ ] Test email notifications work end-to-end
-- [ ] Document email retrieval API for internal services
-
-### Technical Notes
-
-**Service Design:**
-```python
-# Example (Python/Django)
-class EmailRetrievalService:
-    def get_email_by_hash(self, email_hash: str, requesting_service: str) -> str:
-        """
-        Retrieve actual email from hash for notification purposes.
-        
-        Args:
-            email_hash: SHA-256 hash of email
-            requesting_service: Name of service requesting email
-            
-        Returns:
-            Decrypted email address
-            
-        Raises:
-            UnauthorizedException: If service not allowed
-            NotFoundException: If hash not found
-        """
-        # Check service authorization
-        if not self.is_authorized(requesting_service):
-            audit_log.warning(f"Unauthorized email access attempt by {requesting_service}")
-            raise UnauthorizedException()
-        
-        # Retrieve mapping
-        mapping = EmailMapping.objects.get(email_hash=email_hash)
-        
-        # Decrypt email
-        email = self.decrypt_email(mapping.encrypted_email, mapping.encryption_key_id)
-        
-        # Audit log
-        audit_log.info(f"Email retrieved for notification by {requesting_service}", {
-            "email_hash": email_hash,
-            "service": requesting_service
-        })
-        
-        return email
-```
-
-**Access Control:**
-- Only notification service can retrieve emails
-- Use service-to-service authentication (API keys, OAuth)
-- Implement IP whitelisting if services on private network
-- Rate limit: max 100 lookups per minute per service
-
-**Monitoring:**
-- Alert on unusual access patterns
-- Track email retrieval frequency
-- Monitor for brute force attempts
-- Dashboard for email access audit logs
-
----
-
-# Definition of Done
-
-## Frontend
-- [ ] All FE stories completed and tested
-- [ ] Unit tests pass with 90%+ coverage
-- [ ] Integration tests pass
-- [ ] No plain-text emails in localStorage
-- [ ] No plain-text emails in API requests (verified in network tab)
-- [ ] Backward compatible with existing installations
-- [ ] Documentation updated
-- [ ] Code reviewed and approved
-- [ ] Deployed to staging
-- [ ] QA tested
-
-## Backend  
-- [ ] All BE stories completed and tested
-- [ ] Database migration completed successfully
-- [ ] Email mappings working correctly
-- [ ] Notifications still function properly
-- [ ] No plain-text emails in application logs
-- [ ] Audit logging in place
-- [ ] API documentation updated
-- [ ] Load testing completed
-- [ ] Security review completed
-- [ ] Deployed to staging
-- [ ] QA tested
-
-## System-Wide
-- [ ] End-to-end testing completed (FE → BE → DB)
-- [ ] Privacy audit passed
-- [ ] Performance benchmarks met
-- [ ] Rollback plan documented
-- [ ] Production deployment plan approved
-- [ ] Monitoring/alerts configured
-- [ ] Team training completed
-
----
-
-# Risks & Mitigations
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| Breaking existing installations | High | Maintain backward compatibility; gradual migration |
-| Hashing errors in browser | Medium | Graceful fallback; comprehensive error handling |
-| Performance impact of hashing | Low | SHA-256 is fast; test with load testing |
-| Database migration failure | High | Test on staging first; incremental migration; rollback plan |
-| Email mapping not found | Medium | Handle missing mappings gracefully; alert on failures |
-| Encryption key compromise | Critical | Use KMS; rotate keys regularly; audit access |
-
----
-
-# Testing Strategy
-
-## Phase 1: Unit Testing
-- Test all new utilities in isolation
-- Mock external dependencies
-- Cover edge cases and error scenarios
-
-## Phase 2: Integration Testing
-- Test FE → BE data flow
-- Verify hashed data in API calls
-- Test email retrieval for notifications
-
-## Phase 3: Migration Testing
-- Test backward compatibility with existing data
-- Verify data migration scripts
-- Test rollback procedures
-
-## Phase 4: Security Testing
-- Verify no PII in logs (grep for email patterns)
-- Test encryption/decryption
-- Audit access controls
-
-## Phase 5: Performance Testing
-- Load test hashing operations
-- Database query performance with new indexes
-- Cache hit rates for email mappings
-
----
-
-# Rollout Plan
-
-## Week 1: Frontend Development
-- Days 1-2: FE-1 (PII utility)
-- Days 3-4: FE-2 (Metadata tracker updates)
-- Day 5: FE-3 (API layer updates)
-
-## Week 2: Backend Development + Testing
-- Days 1-2: BE-1 (API endpoints)
-- Days 3-4: BE-2 (Email mapping system)
-- Day 5: BE-3 (Database schema updates)
-
-## Week 3: Integration & Testing
-- Days 1-2: FE-5 (Tests) + BE-4 (Email retrieval)
-- Days 3-4: Integration testing + QA
-- Day 5: Staging deployment + validation
-
-## Week 4: Production Rollout
-- Day 1: Production deployment (FE first)
-- Day 2: Monitor for issues
-- Day 3: BE deployment (staged rollout)
-- Day 4: Full system verification
-- Day 5: Retrospective + documentation
-
----
-
-# Success Metrics
-
-- [ ] 0 plain-text emails in server logs (verified by log analysis)
-- [ ] 100% of new sessions use hashed emails
-- [ ] < 50ms latency impact from hashing operations
-- [ ] 0 notification delivery failures due to mapping issues
-- [ ] 99.9% uptime during migration
-- [ ] Privacy audit score improvement by 20%+
-
----
-
-# Questions & Decisions
-
-| Question | Decision | Date | Owner |
-|----------|----------|------|-------|
-| Which PII fields to hash? | Start with email only, expand later | TBD | Product |
-| Backward compatibility period? | 3 months | TBD | Engineering |
-| Encryption key rotation schedule? | Quarterly | TBD | Security |
-| What to do with existing logs? | Redact after migration | TBD | DevOps |
-
----
-
-**Epic Created:** [Date]  
-**Last Updated:** [Date]  
-**Epic Owner:** [Name]  
-**Status:** Planning
-