P0 Implementation Handoff Notes¶
Date: 2024-12-27 From: Analysis Session To: Implementation Session
Context¶
Analysis session completed three audits identifying 46 findings. 14 P0 items require implementation before production. All findings documented with specific file locations and proposed fixes.
Audit Reports (Read These First)¶
| Report | Location | Key Findings |
|---|---|---|
| Security | docs/audits/SECURITY_AUDIT_2024-12-27.md | 16 items (SEC-001 to SEC-016) |
| Compliance | docs/audits/COMPLIANCE_AUDIT_2024-12-27.md | 22 items (COMP-001 to COMP-022) |
| Code | docs/audits/CODE_AUDIT_2024-12-27.md | 8 items (AUDIT-001 to AUDIT-008) |
P0 Master List¶
See docs/backlog.md section "P0 Master Priority List" for full details.
Implementation Order¶
Phase 1: Quick Wins (2.5 hrs) - CAN PARALLELIZE¶
SEC-003: Security Headers - File: src/api/main.py - Add middleware for: X-Frame-Options, X-Content-Type-Options, CSP, HSTS - Reference: FastAPI Middleware documentation
SEC-005: ORDER BY Whitelist
- File: src/repositories/base_repository.py:131
- Current: ORDER BY {order_by} - raw string interpolation
- Fix: Create whitelist of allowed column names, validate before use
SEC-006: CORS Restriction
- File: src/api/main.py:91-98
- Current: allow_methods=["*"], allow_headers=["*"]
- Fix: Restrict to specific methods (GET, POST, PUT, DELETE) and headers
Phase 2: XSS Fixes (3 hrs) - CAN PARALLELIZE¶
SEC-001: Template XSS
- File: src/services/template_service.py:276-301
- Current: re.sub(pattern, value, html) - no escaping
- Fix: import html; html.escape(value) before substitution
- Or: Switch to Jinja2 with autoescape=True
SEC-002: React dangerouslySetInnerHTML
- File: frontend/packages/ui/src/components/tour/TourOverlay.tsx:187-217
- Current: 3 instances of dangerouslySetInnerHTML
- Fix Option A: npm install dompurify and sanitize
- Fix Option B: Refactor to use React components instead of HTML strings
Phase 3: Access Control (5 hrs) - SEQUENTIAL¶
SEC-007: Role Filtering on List Endpoints - File: src/api/routes/clients.py:66-101 - Current: Any authenticated user can list all clients - Fix: Filter by role (staff=all, preparer=assigned, client=own) - Also check: documents.py, returns.py for same pattern
COMP-005: Account Lockout
- Files:
- Database: Add failed_login_attempts, lockout_until to users table
- src/api/middleware/auth.py: Check lockout before auth
- src/workflows/intake/client_authentication.py: Increment on failure
- Design spec: docs/SECURITY_DESIGN.md SEC-005
- 5 failures = 15 min lockout
- 10 cumulative = 1 hour
- 15 cumulative = indefinite (admin unlock)
Phase 4: Audit Logging (5 hrs) - AFTER PHASE 3¶
COMP-003: Auth Event Logging
- File: src/services/audit_service.py has log_auth() method - NEVER CALLED
- Files to modify:
- src/workflows/intake/client_authentication.py
- src/api/routes/client_auth.py
- Events to log: login success/fail, logout, magic link request/verify, lockout
COMP-004: Access Logging
- File: src/services/audit_service.py has log_access() method - NEVER CALLED
- Files to modify:
- src/api/routes/documents.py (all GET endpoints)
- src/api/routes/clients.py (all GET endpoints)
- src/api/routes/returns.py (all GET endpoints)
- Consider: Middleware approach vs explicit calls
Phase 5: Consent System (6 hrs) - SEQUENTIAL¶
COMP-001: AI Processing Consent
- File: src/domain/engagement.py:64-69
- Current: ConsentType enum lacks USE_AI_PROCESSING
- Files to modify:
- src/domain/engagement.py: Add enum value
- src/services/bedrock_service.py:304-392: Add consent check before invoke()
- src/services/anthropic_service.py:477-568: Same pattern
- Must block AI analysis if consent not obtained
COMP-002: E-Filing Consent Check
- File: src/workflows/filing/efiling_workflow.py
- Current: mark_ready_for_filing() has no consent validation
- Fix: Check ConsentType.DISCLOSURE_THIRD_PARTY before allowing filing
- See audit report for code example
Phase 6: New Workflows (16 hrs) - CAN PARALLELIZE¶
COMP-007: Conflict of Interest Checks
- No existing implementation
- Create:
- Database: conflict_check table
- src/domain/conflict.py
- src/repositories/conflict_repository.py
- src/workflows/intake/conflict_check_workflow.py
- src/api/routes/conflicts.py
- Must run before engagement, log all checks
COMP-008: Form 2848 POA Workflow
- Partial: Relationship.POA = "poa" exists in src/domain/client.py:43
- Missing:
- Form 2848 generation
- Signature collection
- IRS authorization validation
- POA-based access control enforcement
Phase 7: Data Protection (8 hrs) - INDEPENDENT¶
COMP-006: Field-Level Encryption - No existing implementation - Design spec: docs/SECURITY_DESIGN.md ENC-004 - Create: src/services/encryption_service.py - Use: pgcrypto with AES-256-GCM - Fields to encrypt: - SSN - Bank account numbers - PTIN - Driver's license numbers - Pattern: Encrypt on write, decrypt on authorized read
Key Dependencies¶
Phase 1 ─┬─> Phase 3 ──> Phase 4
Phase 2 ─┘
Phase 5 (sequential internally)
Phase 6 ─┬─> (parallel COI and POA)
└─>
Phase 7 (independent)
Files Most Frequently Modified¶
| File | Phases |
|---|---|
| src/api/main.py | 1 |
| src/api/routes/clients.py | 3, 4 |
| src/api/routes/documents.py | 4 |
| src/api/middleware/auth.py | 3 |
| src/services/audit_service.py | 4 |
| src/services/bedrock_service.py | 5 |
| src/domain/engagement.py | 5 |
Testing Notes¶
- Run
python -m pytest tests/after each phase - Security fixes (Phases 1-2) need manual verification
- Access control (Phase 3) needs role-based test scenarios
- Audit logging (Phase 4) - check audit_log table for entries
Questions for Don¶
None blocking. All implementation details are specified in audit reports.
Generated by Analysis Session - 2024-12-27