OCR/openspec/changes/migrate-to-external-api-authentication/tasks.md

Implementation Tasks

1. Database Schema Redesign

• 1.1 Backup existing database (for reference)
  • Export current schema and data
  • Document any important data to preserve
• 1.2 Drop old tables
  • Remove existing tables with old naming convention
  • Clear database for fresh start
• 1.3 Create new database schema with tool_ocr_ prefix
  • Create new tool_ocr_users table (email as primary identifier)
  • Create tool_ocr_tasks table with user association
  • Create tool_ocr_task_files table for file tracking
  • Create tool_ocr_sessions table for token storage
  • Add proper indexes for performance
• 1.4 Create SQLAlchemy models
  • User model (mapped to tool_ocr_users)
  • Task model (mapped to tool_ocr_tasks)
  • TaskFile model (mapped to tool_ocr_task_files)
  • Session model (mapped to tool_ocr_sessions)
  • Configure table prefix in base model
• 1.5 Generate Alembic migration
  • Create initial migration for new schema
  • Test migration script with proper table prefixes

2. Configuration Management

• 2.1 Update environment configuration
  • Add EXTERNAL_AUTH_API_URL to .env.local
  • Add EXTERNAL_AUTH_ENDPOINT configuration
  • Add EXTERNAL_AUTH_TIMEOUT setting
  • Add TOKEN_REFRESH_BUFFER setting
  • Add TASK_RETENTION_DAYS for auto-cleanup
  • Add MAX_TASKS_PER_USER for limits
  • Add ENABLE_TASK_HISTORY feature flag
  • Add DATABASE_TABLE_PREFIX = "tool_ocr_"
• 2.2 Update Settings class
  • Add external auth settings to backend/app/core/config.py
  • Add task management settings
  • Add database table prefix configuration
  • Add validation for new configuration values
  • Remove old authentication settings

3. External API Integration Service

• 3.1 Create auth API client
  • Implement backend/app/services/external_auth_service.py
  • Create async HTTP client for API calls
  • Implement request/response models
  • Add proper error handling and logging
• 3.2 Implement authentication methods
  • authenticate_user() - Call external API
  • validate_token() - Verify token validity
  • refresh_token() - Handle token refresh
  • get_user_info() - Fetch user details
• 3.3 Add resilience patterns
  • Implement retry logic with exponential backoff
  • Add circuit breaker pattern
  • Implement timeout handling
  • Add fallback mechanisms

4. Backend Authentication Updates

• 4.1 Modify login endpoint
  • Update backend/app/api/v1/endpoints/auth.py
  • Route to external API based on feature flag
  • Handle both authentication modes during transition
  • Return appropriate token format
• 4.2 Update token validation
  • Modify backend/app/core/security.py
  • Support both local and external tokens
  • Implement token type detection
  • Update JWT validation logic
• 4.3 Update authentication dependencies
  • Modify backend/app/core/auth.py
  • Update get_current_user() dependency
  • Handle external user information
  • Implement proper user context

5. Session and Token Management

• 5.1 Implement token storage
  • Store external tokens securely
  • Implement token encryption at rest
  • Handle multiple token types (access, ID, refresh)
• 5.2 Create token refresh mechanism
  • Background task for token refresh
  • Refresh tokens before expiration
  • Update stored tokens atomically
  • Handle refresh failures gracefully
• 5.3 Session invalidation
  • Clear tokens on logout
  • Handle token revocation
  • Implement session timeout

6. Frontend Updates

• 6.1 Update authentication service
  • Modify frontend/src/services/authService.ts
  • Handle new token format
  • Store user display information
  • Implement token refresh on client side
• 6.2 Update auth store
  • Modify frontend/src/stores/authStore.ts
  • Store external user information
  • Update user display logic
  • Handle token expiration
• 6.3 Update UI components
  • Modify frontend/src/components/Header.tsx
  • Display user name instead of username
  • Show additional user information
  • Update login form if needed
• 6.4 Error handling
  • Handle external API errors
  • Display appropriate error messages
  • Implement retry UI for failures
  • Add loading states

7. Task Management System (NEW)

• 7.1 Create task management backend
  • Implement backend/app/models/task.py
  • Implement backend/app/models/task_file.py
  • Create backend/app/services/task_service.py
  • Add task CRUD operations with user isolation
• 7.2 Implement task APIs
  • Create backend/app/api/v1/endpoints/tasks.py
  • GET /tasks (list user's tasks with pagination)
  • GET /tasks/{id} (get specific task)
  • DELETE /tasks/{id} (delete task)
  • POST /tasks/{id}/retry (retry failed task)
• 7.3 Create task history endpoints
  • Create backend/app/api/v1/endpoints/task_history.py
  • GET /history (query with filters)
  • GET /history/stats (user statistics)
  • POST /history/export (export history)
• 7.4 Implement file access control
  • Create backend/app/services/file_access_service.py
  • Validate user ownership before file access
  • Restrict download to user's own files
  • Add audit logging for file access
• 7.5 Update OCR service integration
  • Link OCR tasks to user accounts
  • Save task records in database
  • Update task status during processing
  • Store result file paths

8. Frontend Task Management UI (NEW)

• 8.1 Create task history page
  • Implement frontend/src/pages/TaskHistory.tsx
  • Display task list with status indicators
  • Add pagination controls
  • Show task details modal
• 8.2 Build task list component
  • Implement frontend/src/components/TaskList.tsx
  • Display task table with columns
  • Add sorting capabilities
  • Implement action buttons
• 8.3 Create filter components
  • Implement frontend/src/components/TaskFilters.tsx
  • Date range picker
  • Status filter dropdown
  • Search by filename
  • Clear filters button
• 8.4 Add task management store
  • Implement frontend/src/stores/taskStore.ts
  • Manage task list state
  • Handle filter state
  • Cache task data
• 8.5 Create task service client
  • Implement frontend/src/services/taskService.ts
  • API methods for task operations
  • Handle pagination
  • Implement retry logic
• 8.6 Update navigation
  • Add "Task History" menu item
  • Update router configuration
  • Add task count badge
  • Implement user menu with stats

9. User Isolation and Security

• 9.1 Implement user context middleware
  • Create middleware to inject user context
  • Validate user in all requests
  • Add user_id to logging context
• 9.2 Database query isolation
  • Add user_id filter to all task queries
  • Prevent cross-user data access
  • Implement row-level security
• 9.3 File system isolation
  • Organize files by user directory
  • Validate file paths before access
  • Implement cleanup for deleted users
• 9.4 API authorization
  • Add @require_user decorator
  • Validate ownership in endpoints
  • Return 403 for unauthorized access

10. Testing

• 10.1 Unit tests
  • Test external auth service
  • Test token validation
  • Test task isolation logic
  • Test file access control
• 10.2 Integration tests
  • Test full authentication flow
  • Test task management flow
  • Test user isolation between accounts
  • Test file download restrictions
• 10.3 Load testing
  • Test external API response times
  • Test system with many concurrent users
  • Test large task history queries
  • Measure database query performance
• 10.4 Security testing
  • Test token security
  • Verify user isolation
  • Test unauthorized access attempts
  • Validate SQL injection prevention

11. Migration Execution (Simplified)

• 11.1 Pre-migration preparation
  • Backup existing database (reference only)
  • Prepare deployment package
  • Set up monitoring
• 11.2 Execute migration
  • Drop old database tables
  • Create new schema
  • Deploy new code
  • Verify system startup
• 11.3 Post-migration validation
  • Test authentication with real users
  • Verify task isolation works
  • Check task history functionality
  • Validate file access controls

12. Documentation

• 12.1 Technical documentation
  • Update API documentation with new endpoints
  • Document authentication flow
  • Document task management APIs
  • Create troubleshooting guide
• 12.2 User documentation
  • Update login instructions
  • Document task history features
  • Explain user isolation
  • Create user guide for new UI
• 12.3 Developer documentation
  • Document database schema
  • Explain security model
  • Provide integration examples

13. Monitoring and Observability

• 13.1 Add monitoring metrics
  • Authentication success/failure rates
  • Task creation/completion rates
  • User activity metrics
  • File storage usage
• 13.2 Implement logging
  • Log all authentication attempts
  • Log task operations
  • Log file access attempts
  • Structured logging for analysis
• 13.3 Create alerts
  • Alert on authentication failures
  • Alert on high error rates
  • Alert on storage issues
  • Alert on performance degradation

14. Performance Optimization (Post-Launch)

• 14.1 Database optimization
  • Analyze query patterns
  • Add missing indexes
  • Optimize slow queries
• 14.2 Caching implementation
  • Cache user information
  • Cache task lists
  • Implement Redis if needed
• 14.3 File management
  • Implement automatic cleanup
  • Optimize storage structure
  • Add compression if needed