Skip to content

feat: HIPAA-native PHI redaction proxy for AI/LLM interactions#1

Merged
DilawarShafiq merged 11 commits intomainfrom
001-phi-redaction-proxy
Feb 26, 2026
Merged

feat: HIPAA-native PHI redaction proxy for AI/LLM interactions#1
DilawarShafiq merged 11 commits intomainfrom
001-phi-redaction-proxy

Conversation

@DilawarShafiq
Copy link
Copy Markdown
Owner

@DilawarShafiq DilawarShafiq commented Feb 26, 2026

Summary

Complete implementation of phi-redactor — an open-source, HIPAA-native PHI redaction proxy that sits between your application and LLM providers (OpenAI, Anthropic), automatically detecting and masking all 18 Safe Harbor identifiers with clinically coherent synthetic replacements.

What's included

  • PHI Detection Engine — Microsoft Presidio + spaCy NER + 10 custom HIPAA recognizers (MRN, FHIR, HL7v2, etc.)
  • Semantic Masking — Faker-powered synthetic replacements that preserve clinical readability (names → names, dates → shifted dates, SSNs → fake SSNs)
  • Encrypted Vault — Fernet-encrypted SQLite storage for PHI-to-synthetic mappings with session isolation
  • Reverse Proxy — FastAPI proxy with adapters for OpenAI (/openai/v1/chat/completions) and Anthropic (/anthropic/v1/messages)
  • SSE Streaming — Real-time streaming support with buffer-based rehydration
  • Identity Clustering — Groups PHI tokens by proximity/sentence to apply consistent synthetic identities per patient
  • Date/Age Shifting — Session-deterministic temporal de-identification preserving clinical age groups
  • Audit Trail — Tamper-evident SHA-256 hash-chain logging of every redaction event
  • HIPAA Compliance Reports — JSON/Markdown/HTML Safe Harbor attestation reports
  • Plugin System — Extensible recognizer plugins via modules, directories, or entry points
  • Real-time Dashboard — Live monitoring UI at /dashboard/ with auto-refreshing stats
  • CLI — phi-redactor serve|redact|report|sessions|config|plugins commands
  • CI/CD — GitHub Actions with pytest + ruff + mypy across Python 3.11-3.13

Architecture

Client App → phi-redactor proxy → LLM Provider (OpenAI/Anthropic)
                ↓ detect PHI
                ↓ mask with synthetic values  
                ↓ forward sanitized request
                ↓ rehydrate response
            ← return original context

Test Coverage

256 tests passing across unit and integration suites covering detection, masking, vault encryption, session isolation, streaming, proxy round-trips, compliance, clustering, date shifting, plugins, FHIR/HL7, and dashboard.

Test plan

  • 256 pytest tests passing (0 failures)
  • All 18 HIPAA Safe Harbor categories covered
  • Vault FK constraint fix verified
  • Cross-session isolation verified
  • Streaming rehydration verified
  • Plugin system load/validate verified

🤖 Generated with Claude Code

DilawarShafiq and others added 11 commits February 26, 2026 03:51
@DilawarShafiq @claude
feat(spec): create PHI redaction proxy specification
13df84d 
Comprehensive feature specification for phi-redactor — an open-source,
HIPAA-native PHI redaction proxy for AI/LLM interactions. Covers 9 user
stories (P1-P3), 20 functional requirements, 10 success criteria, and
quality validation checklist. Key differentiator: semantic masking with
clinically coherent synthetic replacements vs opaque [REDACTED] tokens.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat(plan): complete architecture design for PHI redaction proxy
bf6862a 
Phase 0 research: Presidio+spaCy detection engine, FastAPI reverse proxy,
LLM API contracts (OpenAI/Anthropic), HIPAA Safe Harbor compliance, Fernet
encryption for vault, streaming re-hydration via sliding window buffer.

Phase 1 design: 7-component architecture (Detection, Masking, Vault, Proxy,
Audit, CLI, Plugins), 8-entity data model, OpenAPI 3.1 contract with 14
endpoints, quickstart guide, 6 key design decisions documented.

Artifacts: plan.md, research.md, data-model.md, quickstart.md,
contracts/openapi.yaml, 4 research PHRs, agent context update.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat(tasks): generate 100 implementation tasks across 12 phases
5140c3b 
Organized by 9 user stories with dependency graph:
- Phase 1-2: Setup + Foundation (26 tasks)
- Phase 3-5: P1 MVP — proxy, detection, masking (31 tasks)
- Phase 6-8: P2 — vault, compliance, multi-provider (18 tasks)
- Phase 9-11: P3 — FHIR, plugins, dashboard (16 tasks)
- Phase 12: Polish (9 tasks)

40+ tasks parallelizable. MVP in 40 tasks. Launch in 57 tasks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat: implement Phase 1 (setup) + Phase 2 (foundation) — T001-T026
e78f882 
Phase 1 - Setup:
- Project structure with all subpackages
- pyproject.toml with dependencies and PyPI metadata
- Dev tooling (ruff, mypy, pytest config)
- Test fixtures and .env.example

Phase 2 - Foundation:
- models.py: 4 enums (18 HIPAA categories), 4 Pydantic models
- config.py: PhiRedactorConfig with env/file/defaults, PHI-safe logging
- detection/: PhiDetectionEngine wrapping Presidio + spaCy, HIPAA registry
- masking/: SemanticMasker with Faker-based synthetic replacements
- vault/: PhiVault with Fernet encryption, SQLite, session token maps
- audit/: AuditTrail with hash-chain JSONL, integrity verification
- 62 unit tests across detection, masking, vault, and audit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat(proxy,cli): implement PHI redaction proxy server and CLI — T029-…
bc79fd9 
…T039

Phase 3 (US1 MVP):
- proxy/app.py: FastAPI factory with lifespan, CORS, all routers
- proxy/session.py: SessionManager with idle/max timeout cleanup
- proxy/adapters/: BaseProviderAdapter ABC + OpenAIAdapter (SSE parsing)
- proxy/routes/openai.py: /openai/v1/chat/completions + /embeddings
- proxy/routes/management.py: /health, /stats, /sessions, /audit
- proxy/routes/library.py: /redact and /rehydrate direct API
- proxy/streaming.py: StreamRehydrator with sliding window buffer
- cli/main.py: Click group with lazy-loading subcommands
- cli/serve.py: phi-redactor serve with startup banner
- cli/redact.py: phi-redactor redact for batch file processing

Fail-safe: detection errors block requests (503) rather than leaking PHI.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat: complete PHI redactor with all 18 HIPAA identifiers, multi-prov…
175358e 
…ider proxy, and compliance reports

Critical fixes:
- Fix vault-masker integration: SemanticMasker now correctly calls
  lookup_by_original(), store_mapping(), and new get_reverse_map() on PhiVault
- Remove silent try/except that masked the broken vault calls
- Fix FastAPI response_model=None for union return types in proxy routes
- Replace example SSN 123-45-6789 with valid pattern 456-78-9012 in all tests

New features:
- 8 custom HIPAA recognizers (MRN, health plan, account, license, vehicle,
  device, biometric, fax) covering all 18 Safe Harbor identifier categories
- Anthropic (Claude) provider adapter and proxy routes at /anthropic/v1/messages
- HIPAA Safe Harbor compliance report generator with category coverage analysis,
  confidence distribution, hash-chain integrity verification, and compliance checks
- CLI report command: phi-redactor report [--full] [--output file.json]
- Compliance API endpoints: GET /api/v1/compliance/report and /compliance/summary
- Vault helper methods: get_reverse_map, get_session_mappings, get_session_count

Tests (156 passing):
- Integration tests for OpenAI proxy round-trip with mocked upstream
- Integration tests for multi-turn session consistency and rehydration
- Unit tests for SSE streaming rehydrator buffering and token splitting
- Unit tests for all 8 custom HIPAA recognizers
- Detection benchmark covering all 18 HIPAA categories

Project essentials:
- README.md with architecture, quickstart, API reference, and badges
- Apache-2.0 LICENSE file
- GitHub Actions CI workflow (pytest + ruff + mypy across Python 3.11-3.13)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
test: add 7 test files covering clustering, date shifting, vault encr…
fa2ea57 
…yption, isolation, masking quality, compliance, and Anthropic proxy

Adds unit tests for IdentityClusterer and DateShifter, vault encryption at-rest
tests, and integration tests for vault session isolation, masking pipeline quality,
compliance report generation, and the Anthropic proxy route with mocked upstream.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat(vault,cli,audit,proxy): add session mgmt CLI, vault stats, Safe …
bed0f9f 
…Harbor report rendering

- New cli/sessions.py: list/inspect/close/cleanup session commands backed by PhiVault
- New cli/config.py: config show/providers commands for runtime config inspection
- vault/store.py: add export_anonymized, purge_session, get_vault_stats methods
- audit/reports.py: add generate_safe_harbor method + render_markdown/render_html functions
- cli/report.py: add --format (json/md/html) and --safe-harbor options
- proxy/routes/management.py: POST /api/v1/reports/safe-harbor endpoint
- cli/main.py: register sessions and config in lazy_commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat(dashboard,polish): add real-time monitoring dashboard and PEP 56…
b79f0c9 
…1 marker — Phase 11-12

Phase 11 (Dashboard):
- Add FastAPI dashboard router with live-stats API endpoint
- Create self-contained HTML dashboard UI with auto-refresh
- Mount dashboard routes in the proxy application factory

Phase 12 (Polish):
- Add PEP 561 py.typed marker for type checker support
- Add SECURITY.md with vulnerability reporting policy and architecture docs
- Add unit tests for dashboard module

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
feat(detection,plugins): add FHIR/HL7 recognizers and plugin system —…
d36a201 
… Phase 9-10

Phase 9: FHIR resource reference recognizer (Patient/12345, FHIR URLs,
OIDs) and HL7v2 segment recognizer (PID, NK1, GT1, IN1 segments) with
entity mapping to OTHER_UNIQUE_ID category.

Phase 10: Extensible plugin system with PluginLoader supporting module
imports, directory scanning, and setuptools entry points. Includes
example plugin, CLI plugin management commands, and full test coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq @claude
fix(vault): auto-create session on store_mapping to prevent FK constr…
97f0c6e 
…aint errors

Adds ensure_session() to PhiVault that creates a session row if one
doesn't exist, called automatically by store_mapping(). Also adds
identity clustering, date shifting, and synthetic identity factory
modules (Phase 5). Fixes proximity clustering test boundary detection.

256 tests passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DilawarShafiq DilawarShafiq merged commit 224a50f into main Feb 26, 2026
0 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DilawarShafiq