guideai-app 0.4.1 → 0.4.2-1

package/PII_HASHING_EPIC.md

@@ -0,0 +1,886 @@
+# 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
+