docs(design): SOC 2 / HIPAA compliance plan

[hyperSuperCube]

Summary

Docs-only — no code, API, or client-surface changes. (Client surface checklist removed per template guidance.)

Highlights reviewers may want to weigh in on:

• Treating e2a as a HIPAA business associate (persistent message storage rules out the conduit exception) and targeting the 2025 Security Rule NPRM bar (mandatory encryption + MFA).
• The Gemini AI Studio screening endpoint as the headline HIPAA blocker, with the proposed resolution options (Vertex/BAA-covered provider vs hard-off in a HIPAA profile).
• The proposed audit_events shape and the envelope-encryption migration strategy (dual-read + River re-encryption, no destructive DDL on messages).

Operational risk

None from this PR itself (documentation only). The document does propose future changes with operational weight (field encryption migration, retention sweeps, production sslmode enforcement); each would land as its own PR train with tests and migration review.

Test plan

• scripts/check-repository-text-integrity.sh passes
• scripts/check-no-committed-credentials.sh passes
• Public-repo data boundary reviewed: doc references only in-tree code paths and already-public material, no customer data

[jiashuoz]

This is a useful foundation. Before we adopt it as the execution roadmap, I’d like us to organize the work around one governing principle:

For a HIPAA-enabled account, treat every email and its associated metadata as potentially regulated data and route it through a tightly controlled, fail-closed HIPAA data path.

We should not depend on content classification to decide whether a particular message contains PHI. The account-level capability defines the boundary.

Direction

1. Architecture and PHI-boundary work comes first.

Create a canonical data-flow and storage inventory covering the complete path:

SMTP ingress → intake/queue → workers → Postgres/backups → API/WebSocket/MCP/webhooks → customer systems

It also needs every secondary copy and operational surface: webhook outbox/delivery payloads, River jobs, templates, contacts, lifecycle evidence, idempotency responses, WAL/replicas/backups, logging, monitoring, analytics, support tooling, email providers, and LLM APIs.

For each location, record what data reaches it, why it is necessary, how long it persists, how it is encrypted, how it is deleted, who can access it, and which vendor/service/configuration receives it.

This phase must also make an explicit isolation decision for HIPAA accounts: a dedicated HIPAA cell or a documented logical and cryptographic isolation design. A flag alone is not the isolation boundary.

2. Minimize the PHI boundary.

HIPAA-path logs and telemetry should contain opaque identifiers and operational state, for example message_id, delivery_status, and http_status—never subject, body, attachment data, raw addresses, customer-controlled metadata, URLs containing capability tokens, or unredacted provider errors.

Encryption and retention must cover every PHI-bearing copy, not only the primary messages columns. Hosted encryption should support per-account key separation and a credible crypto-erasure path. Secure deletion needs defined behavior for live rows, queues/outboxes, replicas, backups, logs, exports, and subprocessors.

3. HIPAA mode should enforce invariants.

An account-level capability such as account.hipaa_enabled = true should automatically require:

• TLS-required outbound SMTP with no plaintext downgrade, plus TLS for APIs, webhooks, database/internal connections, and administrative access.
• Approved HIPAA infrastructure and subprocessors only.
• PHI-safe logging, monitoring, analytics, and error handling.
• Least-privilege employee access, RBAC, and MFA.
• Audit trails for sensitive data reads/downloads/exports as well as administrative changes.
• Defined retention, secure deletion, encrypted backups, and tested recovery.
• LLM screening disabled unless the exact provider, service, model/feature, account configuration, and contract are approved for the workload.

4. Compliance evidence follows and validates the architecture.

Before the first BAA customer: complete the formal Security Risk Analysis; execute the required infrastructure/subprocessor BAAs; prepare the e2a customer BAA; adopt security, access-control, incident/breach, backup/recovery, workforce, retention, and vendor-management policies; and train personnel with access to the HIPAA boundary.

Vendor review must verify the exact service and executed agreement, not just that a vendor brand offers some HIPAA-eligible products. Track this evidence privately and review it regularly.

5. Productize after the controls exist.

Expose HIPAA mode, configurable retention, secure deletion, customer-visible security/audit logs, and the relevant administrative controls. A secure-message portal—notification email followed by authenticated portal access—is a valuable later enhancement for customers who need stronger delivery guarantees, but it is not required for the initial HIPAA offering.

SOC 2 is complementary enterprise work and can proceed in parallel or afterward; it is not a prerequisite for signing a BAA or launching the first correctly scoped HIPAA service.

Proposed sequencing

1. PHI inventory, trust boundaries, isolation decision, and vendor/service register.
2. Data-plane hardening: minimization, encryption, PHI-safe observability, access controls/MFA, data-access audit, retention/deletion, backups/DR, TLS enforcement.
3. Formal SRA, policies, incident/breach procedures, training, vendor management, and BAA templates/execution.
4. Enforced HIPAA product mode and, later, secure-message delivery.
5. SOC 2 readiness and attestation on its own commercial timeline.

For positioning, preserve the document’s distinction between compliance-capable software and a hosted HIPAA mode under BAA. Once the hosted controls are operating and BAAs are available, the product line can become: “e2a — HIPAA-compliant email infrastructure for AI agents, available under BAA.”

[hyperSuperCube]

Revised in b143633 — the plan is now organized around the governing principle: for a HIPAA-enabled account, all email + metadata is regulated data on a fail-closed path; the account capability defines the boundary, never content classification (added explicitly to "What we deliberately do not do").

Mapping to your five points:

1. Architecture first — new Phase 0: the canonical data-flow/storage inventory (including the secondary copies you listed — webhook outbox/delivery payloads, River jobs, templates/contacts, lifecycle evidence, idempotency responses, WAL/replicas/backups, logs/telemetry/analytics, support tooling, providers, LLM APIs), a trust-boundary map with an explicit isolation decision (dedicated HIPAA cell vs documented logical + cryptographic isolation — the doc now states a flag alone is not the isolation boundary), and a vendor/service register keyed to exact service + executed agreement.
2. Minimized boundary — Phase 1 now grades encryption/retention/deletion against the full inventory: per-account DEKs with a crypto-erasure path (the backup-deletion story), opaque-identifier-only logging/telemetry on the HIPAA path, per-copy secure-deletion behavior, and audit events for data reads/downloads/exports, not just admin changes.
3. Enforced invariants — Phase 3 is account.hipaa_enabled requiring, at call sites and fail-closed: no-downgrade TLS everywhere (outbound SMTP fails rather than downgrades), approved subprocessors only, LLM screening off unless the exact provider/service/model/config/contract is approved, PHI-safe observability, MFA/RBAC/audit, finite retention + tested encrypted backups.
4. Evidence validates architecture — Phase 2 (SRA over the Phase 0 inventory, policies, IR record, executed BAAs verified at service level, customer BAA template, training) is now sequenced before the first BAA customer rather than as a starting point.
5. Productize last; SOC 2 parallel — secure-message portal noted as a later enhancement, not required for launch; SOC 2 moved to Phase 4 on its own commercial timeline with the doc stating it is not a prerequisite for signing a BAA.

Also kept your end-state positioning: build-out ships "compliance-capable software + hosted HIPAA mode under BAA," and only once controls operate and BAAs are executed does the hosted line become "e2a — HIPAA-compliant email infrastructure for AI agents, available under BAA."

🤖 Generated with Claude Code

https://claude.ai/code/session_01UZ1cdVL4AhDA7MHh8yzQyH