guideai-app 0.4.1 → 0.4.2

package/PII_HASHING_STORIES_SUMMARY.md

@@ -0,0 +1,275 @@
+# PII Hashing - Story Summary
+
+**Epic Goal:** Implement client-side PII hashing to prevent sensitive data from appearing in logs, monitoring tools, and backend systems.
+
+---
+
+## Frontend Stories (Guide AI Package)
+
+### ✅ FE-1: Create PII Hashing Utility
+**Points:** 3 | **Priority:** P0 | **Dependencies:** None
+
+Create `src/utils/pii.ts` with:
+- `hashEmail()` - Hash email using SHA-256
+- `hashPII()` - Generic PII hashing function
+- `isHashed()` - Check if value is already hashed
+- TypeScript types and JSDoc
+- Works with Web Crypto API
+
+**Deliverables:**
+- New file: `src/utils/pii.ts`
+- TypeScript types for hashed data
+- Documentation
+
+---
+
+### ✅ FE-2: Update UserMetadataTracker to Hash Emails  
+**Points:** 5 | **Priority:** P0 | **Dependencies:** FE-1
+
+Update `src/metric/metadata-tracker.tsx`:
+- Hash emails in `updateUserInfo()`
+- Hash emails in `trackLogin()`
+- Hash emails in all `trackVisit*()` methods
+- Hash emails in `trackCustomEvent()`
+- Store hashed emails in localStorage
+- Add migration logic for existing data
+- Graceful error handling
+
+**Deliverables:**
+- Modified: `src/metric/metadata-tracker.tsx`
+- All emails hashed before storage/transmission
+- Backward compatible
+
+---
+
+### ✅ FE-3: Update API Layer for Hashed Identifiers
+**Points:** 3 | **Priority:** P0 | **Dependencies:** FE-1, FE-2
+
+Update API types and validation:
+- Add `emailHash` field to `UserMetadata` type
+- Deprecate `email` field (keep for backward compatibility)
+- Add validation in `sendMetadataUpdates()` (dev mode)
+- Ensure no plain-text emails in API calls
+- Update JSDoc comments
+
+**Deliverables:**
+- Modified: `src/types/metadata.types.ts`
+- Modified: `src/utils/api.ts`
+- API request validation
+
+---
+
+### ✅ FE-4: Add Privacy Configuration Options
+**Points:** 2 | **Priority:** P1 | **Dependencies:** FE-1, FE-2
+
+Add config options to `MetadataConfig`:
+- `enablePIIHashing: boolean` (default: true)
+- `piiFields: string[]` (default: ['email'])
+- `allowPlainTextFallback: boolean` (default: false)
+
+**Deliverables:**
+- Modified: `src/types/metadata.types.ts`
+- Configuration documentation
+- Usage examples
+
+---
+
+### ✅ FE-5: Add Unit & Integration Tests
+**Points:** 5 | **Priority:** P0 | **Dependencies:** FE-1, FE-2, FE-3
+
+Create comprehensive test coverage:
+- Unit tests for `pii.ts` utilities
+- Unit tests for metadata tracker hashing
+- Integration tests for end-to-end flow
+- Test error handling and edge cases
+- Verify no plain-text in API calls
+
+**Deliverables:**
+- New file: `src/utils/pii.test.ts`
+- New file: `src/metric/metadata-tracker.pii.test.ts`
+- 90%+ code coverage
+- All tests passing in CI
+
+---
+
+## Backend Stories (High Level - Other Repo)
+
+### 🔧 BE-1: Update API Endpoints for Hashed Email Handling
+**Points:** 8 | **Priority:** P0
+
+**What:**
+- Update `/initialize-session` endpoint to accept `emailHash`
+- Update `/metadata-updates` endpoint to process `emailHash`
+- Add hash format validation (64 hex chars)
+- Ensure backward compatibility during migration
+- Update API documentation
+
+**Technical Notes:**
+- Accept both `email` and `emailHash` during transition
+- Validate hash format: `/^[a-f0-9]{64}$/i`
+- No plain-text emails in logs
+
+---
+
+### 🔧 BE-2: Create Email Hash Mapping System
+**Points:** 13 | **Priority:** P0
+
+**What:**
+- Create `email_mappings` table
+- Store: `emailHash → encryptedEmail`
+- Implement encryption at rest (AES-256-GCM)
+- Use KMS for key management
+- Add Redis cache for frequently accessed mappings
+- Implement audit logging
+- Create internal API for email lookup
+
+**Database Schema:**
+```sql
+email_mappings (
+  email_hash: VARCHAR(64) PRIMARY KEY,
+  encrypted_email: BYTEA,
+  encryption_key_id: VARCHAR(50),
+  organization_key: VARCHAR(100),
+  first_seen: TIMESTAMP,
+  last_seen: TIMESTAMP
+)
+```
+
+---
+
+### 🔧 BE-3: Update Database Schema
+**Points:** 5 | **Priority:** P0
+
+**What:**
+- Add `email_hash` column to relevant tables
+- Migrate existing plain-text emails to hashes
+- Create indexes on `email_hash`
+- Update all queries to use `email_hash`
+- Keep `email` column temporarily for backward compatibility
+
+**Migration Strategy:**
+1. Add new column
+2. Backfill hashes (incremental)
+3. Create indexes
+4. Update application code
+5. (Future) Drop old email column
+
+---
+
+### 🔧 BE-4: Add Email Retrieval & Notification Logic
+**Points:** 8 | **Priority:** P1
+
+**What:**
+- Create service for secure email retrieval
+- Implement notification service using email lookup
+- Add authentication/authorization
+- Implement audit logging for email access
+- Add rate limiting
+- Monitoring/alerts for suspicious access
+
+**Access Control:**
+- Only notification service can retrieve emails
+- Service-to-service authentication
+- Rate limit: 100 lookups/minute per service
+- IP whitelisting
+
+---
+
+## Story Point Summary
+
+| Team | Total Points | Stories |
+|------|--------------|---------|
+| **Frontend** | **18 points** | 5 stories |
+| **Backend** | **34 points** | 4 stories |
+| **TOTAL** | **52 points** | 9 stories |
+
+---
+
+## Sprint Allocation (Example)
+
+### Sprint 1: Core Implementation
+- FE-1: Create PII Hashing Utility (3 pts)
+- FE-2: Update UserMetadataTracker (5 pts)
+- BE-1: Update API Endpoints (8 pts)
+- **Total: 16 points**
+
+### Sprint 2: Integration & Mapping
+- FE-3: Update API Layer (3 pts)
+- FE-4: Add Privacy Config (2 pts)
+- BE-2: Email Hash Mapping System (13 pts)
+- **Total: 18 points**
+
+### Sprint 3: Testing & Deployment
+- FE-5: Tests (5 pts)
+- BE-3: Database Schema (5 pts)
+- BE-4: Email Retrieval Logic (8 pts)
+- **Total: 18 points**
+
+---
+
+## Critical Path
+
+```
+FE-1 (PII Utils)
+  ↓
+FE-2 (Metadata Tracker) + BE-1 (API Endpoints)
+  ↓
+FE-3 (API Layer) + BE-2 (Email Mapping)
+  ↓
+FE-5 (Tests) + BE-3 (DB Schema) + BE-4 (Email Retrieval)
+  ↓
+Integration Testing
+  ↓
+Production Deployment
+```
+
+---
+
+## Quick Checklist
+
+**Before Starting:**
+- [ ] Product approval for privacy changes
+- [ ] Security review of approach
+- [ ] Backend team capacity confirmed
+- [ ] Database migration plan reviewed
+
+**During Development:**
+- [ ] Daily syncs between FE/BE teams
+- [ ] Test in staging after each story
+- [ ] Security scanning of new code
+- [ ] Performance testing
+
+**Before Production:**
+- [ ] All tests passing
+- [ ] Privacy audit completed
+- [ ] Rollback plan documented
+- [ ] Monitoring configured
+- [ ] Team trained on new system
+
+---
+
+## Key Decisions Needed
+
+1. **Migration Timeline:** How long to support both `email` and `emailHash`?
+2. **Rollout Strategy:** Big bang or gradual rollout?
+3. **Old Data:** Migrate existing emails in DB or only new data?
+4. **Other PII:** Should we hash other fields (userId, customerLicense)?
+5. **Encryption Keys:** Where to store? AWS KMS? Vault?
+
+---
+
+## Success Criteria
+
+✅ No plain-text emails in server logs  
+✅ No plain-text emails in API requests  
+✅ All notifications still work  
+✅ < 50ms latency impact  
+✅ 99.9% uptime during migration  
+✅ Privacy audit passed
+
+---
+
+**Created:** [Date]  
+**Owner:** [Name]  
+**Status:** Ready for Planning
+

package/SESSION_ID_VERIFICATION.md

@@ -0,0 +1,122 @@
+# Session ID Implementation Verification Guide
+
+## Overview
+This guide helps you verify that the session ID tracking implementation is working correctly.
+
+## What Was Implemented
+
+### 1. Session Utility (`src/utils/session.ts`)
+- ✅ `getSessionId()` - Gets or creates session ID
+- ✅ `clearSessionId()` - Clears session ID (for testing)
+- ✅ `peekSessionId()` - Views session ID without creating one
+- ✅ Standard UUID v4 format
+- ✅ Stored in `sessionStorage['guideai_session_id']`
+
+### 2. UserMetadataTracker Updates
+- ✅ Session ID initialized in `init()` method
+- ✅ Session ID stored in metadata object
+- ✅ Session ID included in all metadata updates
+
+### 3. Exports
+- ✅ Session utility functions exported from main index
+- ✅ Available for external debugging and testing
+
+## Manual Verification Steps
+
+### Step 1: Check Session Storage
+1. Open your test site in a browser
+2. Open DevTools → Application → Session Storage
+3. Look for `guideai_session_id`
+4. Verify it contains a UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`)
+
+### Step 2: Verify Persistence
+1. Navigate between different pages on your site
+2. Check that `guideai_session_id` remains the same
+3. Refresh the page - session ID should persist
+
+### Step 3: Verify New Session Creation
+1. Open a new tab to the same site
+2. Check Session Storage - should have a different `guideai_session_id`
+3. Close and reopen a tab - should generate a new `guideai_session_id`
+
+### Step 4: Verify Metadata Tracking
+Open the browser console and check logs:
+
+```javascript
+// UserMetadataTracker should log:
+// "Session ID initialized" with { sessionId: "..." }
+
+// metadata object should include sessionId
+```
+
+### Step 6: Programmatic Testing
+You can test session functions directly in the console:
+
+```javascript
+// Get current session ID
+const { getSessionId, peekSessionId, clearSessionId } = window.GuideAI || {};
+
+// View current session ID (if GuideAI exports are available)
+console.log('Current session:', peekSessionId());
+
+// Or directly from sessionStorage
+console.log('Session ID:', sessionStorage.getItem('guideai_session_id'));
+```
+
+## Expected Behavior
+
+### Session Lifecycle
+- **New Tab**: New session ID generated
+- **Page Navigation**: Session ID persists
+- **Page Refresh**: Session ID persists
+- **Tab Close**: Session ID cleared automatically
+- **Browser Restart**: New session IDs for all tabs
+
+### Data Inclusion
+- **UserMetadataTracker**: Metadata should include `sessionId` field
+- **API Calls**: Session ID should be sent to backend with metadata updates
+
+## Testing in Your Application
+
+Add this code to your test application to verify session tracking:
+
+```typescript
+import GuideAI, { getSessionId } from 'guideai-package';
+
+// In your component
+useEffect(() => {
+  // Log session ID on mount
+  console.log('Current GuideAI Session:', getSessionId());
+  
+  // Check sessionStorage directly
+  console.log('Session Storage:', sessionStorage.getItem('guideai_session_id'));
+}, []);
+```
+
+## Common Issues & Solutions
+
+### Issue: Session ID not appearing
+**Solution**: Ensure GuideAI component has mounted and initialized
+
+### Issue: Session ID changes on page refresh
+**Solution**: Verify you're using `sessionStorage` not `localStorage`
+
+### Issue: Same session ID across tabs
+**Solution**: This is expected behavior - each tab should have its own session ID
+
+## Phase 2 Features (Not Yet Implemented)
+
+These features are planned for future releases:
+- ❌ `session_start` metadata event
+- ❌ `session_end` metadata event  
+- ❌ Session duration tracking
+- ❌ Session-level analytics
+
+## Notes
+
+- Session ID uses browser's `crypto.randomUUID()` when available
+- Fallback UUID generation for older browsers
+- Global session key (not per-organization)
+- `conversationStartTime` remains for backward compatibility
+- Session utility handles SSR/non-browser environments gracefully
+