Security & Architecture Whitepaper

1. Executive Summary

ESUS is a FHIR R4–compliant Backend-as-a-Service for healthcare applications. Patient data is the most sensitive data class regulated in the world, so the platform was designed from day one under a zero-trust, defense-in-depth posture: every request is authenticated, authorized against fine-grained policies, rate-limited, audited, and — whenever Protected Health Information (PHI) is involved — encrypted at the field level with per-tenant keys.

This document describes the security controls that protect our customers’ data, the architecture that enforces them, and our roadmap toward post-quantum cryptography for the critical paths of the system. It is intended to support technical due diligence without exposing implementation details that are not public.

2. Threat Model & Compliance Posture

We design for adversaries that actively attempt to:

• Impersonate legitimate clients — token forgery, algorithm-confusion attacks, replay of captured credentials, session fixation.
• Pivot across tenants — exploit application bugs to read rows that belong to another organization.
• Exfiltrate PHI at rest — steal database dumps, backups, or cold storage; coerce insiders with direct database access.
• Intercept data in transit — MITM against database, cache, or HTTP links; downgrade TLS.
• Exhaust capacity — volumetric DoS, application-layer Slowloris, credential-stuffing.
• Poison logs or evade auditability — tamper with audit records to cover unauthorized access.
• Harvest now, decrypt later — capture ciphertexts today in anticipation of future cryptanalytic capability, including quantum computers.

Each control described in this whitepaper maps to one or more of the threats above. Compliance alignment:

• HIPAA Security Rule — §164.312(a) Access Control, §164.312(b) Audit Controls, §164.312(c) Integrity, §164.312(d) Person Authentication, §164.312(e) Transmission Security.
• GDPR — tenant data segregation, consent tracking via the FHIR Consent resource, retention and right-to-erasure hooks, lawful basis tracking per subject.
• FHIR R4 + SMART-on-FHIR — standards-based identity, scopes, and patient-delegated access.

3. Architecture Overview

ESUS is a modular monolith with three load-bearing design choices. These are architectural commitments, not implementation details, and they are invariant across future technology refreshes:

1. Hexagonal modularity — each of the 60+ FHIR resources is an independent bounded context with its own controller, service, repository, and schema layers. Cross-cutting concerns — authentication, authorization, CORS, rate limiting, auditing — are implemented once at the framework level and applied uniformly, so a developer cannot accidentally ship an endpoint that skips a control.
2. Database-enforced multi-tenancy — isolation between organizations is enforced at the data layer through row-level security policies, not in application code. Every request binds a tenant identifier to the database session before any query runs, and the database filters rows on that identifier. An application bug that forgets to add WHERE organization_id = ? cannot leak data, because the database refuses to return the rows in the first place.
3. Asynchronous critical paths — auditing, anomaly detection, bulk export, and heavy background work run through a durable queue. This protects the patient-facing hot path: a slow or failing audit sink never blocks a clinician from accessing a chart, and a failed audit write is retried with exponential backoff on a durable store.

Persistence combines a relational store as the system of record with a high-performance cache for ephemeral state (sessions, rate-limit counters, OTP codes, cached derivations) and a dedicated durable queue for asynchronous work.

4. Identity and Access Control

4.1 Authentication

Three authentication surfaces, one verification pipeline:

• JWT (HS256) — tokens are signed and verified using standards-based Web Cryptography with a strict verifier that rejects any algorithm other than HS256. This closes the well-known algorithm-confusion family of attacks (alg: none acceptance, HMAC-vs-RSA key confusion) that have affected many JWT libraries. Tokens carry expiration (exp) and are additionally validated against a server-side session store, so revocation is immediate — not “on next expiry.”
• Session store — every successful login creates a server-side session record in the platform’s low-latency session store, holding a TTL, the resolved subject, role bindings, organization, and the device/IP fingerprint. Logging out or triggering revocation deletes the record; any subsequent token referencing that session is rejected regardless of its exp claim. This is defense in depth: the JWT carries cryptographic proof, the session carries authority.
• OAuth 2.0 / SMART-on-FHIR — authorization-code flow for first-party and partner applications, including Google ID token verification for the current IdP. SMART-on-FHIR is supported natively so patients can delegate scoped access to third-party apps following the FHIR standard. The design is provider-agnostic so additional IdPs can be added without changes to the enforcement path.
• API keys — machine-to-machine integrations authenticate with clientId:secret pairs. Secrets are never stored in plaintext; they are hashed with Argon2id at rest, verified in constant time, and carry scoped permissions and explicit expiration. Key rotation is non-disruptive: multiple active keys per client allow overlap during rollover.
• One-Time Passwords — 6-digit codes for email verification and password reset are generated with rejection sampling over cryptographic randomness to eliminate the modulo bias that naive random % 10⁶ implementations leak. Codes are single-use, TTL-bound, and rate-limited per identifier.
• Password policy — aligned with HIPAA §164.312(a)(2)(i): minimum 12 characters, mixed case, digit, special character; breach-list checks on sign-up and password change; lockout with exponential backoff on failed attempts.

4.2 Authorization

Authorization is a two-tier engine that evaluates every request after authentication succeeds:

1. RBAC fast-path — role-to-permission tuples (resource, action) are evaluated in O(1). A user without a permitted role on the target resource is rejected before any attribute computation. This is the common case and it is cheap.
2. ABAC policy evaluation — for resources where coarse RBAC is not enough (most clinical data), a dedicated attribute-based policy engine evaluates structured policies that combine actor attributes (role, organization, specialty), resource attributes (patient id, sensitivity label, consent state), and context attributes (time, IP, purpose-of-use). The platform ships with 10+ policies covering admin operations, clinical data, patient demographics, financial records, medications, consent gating, encounters, documents, scheduling, and structural resources.

The engine operates under deny-overrides, zero-trust semantics: a single applicable deny blocks the request; permits must be positive and explicit. There is no implicit allow. Policies are composed, not flattened, so adding a new policy can only restrict access, never broaden it silently.

ABAC consults the FHIR Consent resource as a first-class input. When a patient revokes or restricts a consent, every downstream request that would touch the affected data is denied by the policy engine — no cache invalidation, no feature flag, no application-code change required.

4.3 Multi-tenancy

• Every JWT and every session carries the organization id; it is non-forgeable because it is part of the signed payload.
• Before any query, the connection binds the authenticated organization into a session-scoped variable, and row-level security policies filter every tenant-scoped table on that variable. A query without tenant context returns zero rows by construction.
• Administrative endpoints — for internal staff operations — require both an admin role and an IP allowlist. Possessing an admin token is not sufficient if the request does not come from an authorized network.

This is a layered isolation model: a bug in application code cannot leak across tenants because RLS will filter the rows. A compromise of application logic cannot escalate to admin surfaces because the network layer blocks the call.

5. Encryption Layer

5.1 At Rest — Field-Level PHI Encryption

Disk encryption alone is not sufficient: it only protects against physical theft of the storage medium. It does not protect against database dumps, logical backups, replica snapshots, or an insider with read access to the database. ESUS therefore encrypts PHI at the application layer, before the data ever reaches the database engine.

• Algorithm — AES-256-GCM with 12-byte random IVs and a 128-bit authentication tag. GCM provides both confidentiality and authenticity: an attacker who tampers with a ciphertext will fail verification and the decryption path returns an error, not corrupted plaintext.
• Key derivation — per-tenant keys are derived via HKDF-SHA256 from a root key, using a salt unique to each organization stored alongside that organization’s metadata. Two tenants encrypting the same plaintext produce completely different ciphertexts, and a key derived for tenant A cannot decrypt data belonging to tenant B — even if every other parameter is identical.
• Encrypted fields — patient identifiers, telecom entries (phone, email), name components (family, given, and text forms), address components (text, line, city, state, postal code), date of birth, and clinical fields across Observation, Condition, MedicationRequest, AllergyIntolerance, DocumentReference and related resources. We encrypt the data that identifies the patient and the data that describes their care.
• Ciphertext envelope — every ciphertext is self-describing: it carries the algorithm identifier, the key id used to encrypt it, the IV, the auth tag, and the ciphertext bytes. This envelope is what enables non-disruptive key rotation.
• Key rotation — the platform maintains a current encryption key and a previous key. Writes always use the current key; reads decrypt with the key identified in the envelope. Rotation is an online operation: promote the new key to current, re-encrypt in the background, retire the old key. No downtime, no flag days, and a partial rotation is always a safe state.

Two additional cryptographic secrets are kept strictly separate from the field-encryption key:

• PHI search HMAC key — for deterministic blind indexes that allow equality lookups over encrypted data without revealing plaintext. Separating this key from the encryption key means that compromising a search index does not compromise the underlying data.
• Audit integrity HMAC key — signs audit records so log tampering becomes cryptographically detectable. An attacker who gains write access to the audit store cannot forge plausible records without also compromising this key.

5.2 In Transit

• TLS everywhere — database connections require TLS in production, the cache and queue transports require TLS, and the public HTTP surface is behind HTTPS with HSTS max-age=63072000; includeSubDomains; preload in production.
• Modern cipher suites only — legacy protocol versions and weak cipher suites are disabled at the edge.
• Secure cookies — session and OAuth state cookies are Secure, HttpOnly, and SameSite, which neutralizes common CSRF and token-theft-via-XSS patterns.
• No credentials in URLs — API keys are sent in headers; tokens are never included in query strings, so they do not appear in proxy logs, referrer headers, or browser history.

5.3 Secret Management

All cryptographic material — field-encryption keys, HMAC keys, JWT signing keys, OAuth client secrets, database and Redis credentials, SMTP credentials, backup-encryption keys — is managed through a pluggable secret store abstraction with two backends:

• Environment variables — for local development and simple deployments.
• Enterprise secret manager — for production, an enterprise-grade secret manager (HashiCorp Vault is supported today) holds all material. Authentication is via short-lived, role-scoped credentials; secrets live on versioned mounts and are rotated on schedule. The integration is fail-closed: if any required secret is missing at boot, the process refuses to start instead of running with partial configuration. This eliminates a whole class of “ran for six months with a default key” incidents.

Secrets are retrieved at boot and in memory only; they are never written to the filesystem, never committed, and never logged — even at debug level, where structured loggers apply an explicit redaction filter.

6. Defense in Depth

No single control is sufficient, so we apply several independent layers that each have to fail for an attack to succeed.

6.1 Rate Limiting

Multi-tier, backed by the shared cache with an in-memory fallback so a cache outage fails safely rather than removing the control entirely:

• Per-IP — broad baseline cap (500 requests per 60 seconds) that absorbs small-scale abuse without affecting normal users.
• Per-user — plan-scoped caps so a single authenticated user cannot exhaust capacity.
• Per-operation — write operations carry tighter limits than reads, because writes are more expensive and more damaging when abused.

6.2 Anomaly Detection and IP Blocklisting

A scheduled background sweep scores IPs on recent request patterns (failure rate, endpoint spread, time-of-day, geographic drift). IPs that exceed the threshold are moved to a blocklist that rejects at the edge with a hard 429, before the request touches the auth pipeline. Decisions are reviewable and reversible.

6.3 Input Validation

Every route declares a typed schema for its request body, query string, and path parameters. Malformed input is rejected before any handler code runs. FHIR search parameters receive additional hardening: strings are length-capped, and sort columns are validated against an allowlist so a sort parameter can never be coerced into SQL injection or used to exfiltrate order information.

6.4 Security Headers

• Content-Security-Policy: default-src 'none'; frame-ancestors 'none' — a deny-by-default CSP appropriate for an API surface that serves no browser content.
• X-Frame-Options: DENY — no embedding, closes clickjacking.
• X-Content-Type-Options: nosniff — no MIME sniffing.
• Referrer-Policy, Permissions-Policy — minimize metadata leakage.
• HSTS with preload — forces HTTPS even on the first request after a preload rollout.

6.5 CORS

CORS is evaluated dynamically per tenant. Each organization configures its allowed origins explicitly, layered on top of a global allowlist and an internal allowlist for ESUS-operated subdomains. There is no reflective wildcard — an origin that is not on any of the three lists is refused.

6.6 Request Size and Timeouts

• 50 MB ceiling for file-upload endpoints, 1–5 MB defaults for everything else. This prevents memory-exhaustion attacks that dress up as legitimate traffic.
• Explicit server-side timeouts close Slowloris vectors, where an attacker opens many connections and feeds bytes one-at-a-time to hold resources open indefinitely.

6.7 Log Hygiene

Structured logs go through a redaction filter that scrubs MRNs, insurance identifiers, dates of birth, addresses, phone numbers, and free-text fields known to contain PHI before any record leaves the process. Error payloads receive the same treatment. The practical outcome: our operators can debug production without ever seeing patient data, and a compromised logging pipeline does not become a PHI exfiltration channel.

7. Auditability and Compliance

Every access to a PHI resource produces an immutable audit record containing the actor, the action, the target resource, timestamp, source IP, outcome, and organization. These records are:

• Written asynchronously through a durable queue — patient care is never blocked by a slow audit sink. If the audit pipeline is degraded, events are persisted on the queue and drained when the sink recovers. A failed write is retried with exponential backoff; it is never silently dropped.
• Signed with the audit-integrity HMAC key — tampering with records in the audit store is cryptographically detectable. An operator who modifies a record after the fact produces a signature that no longer verifies.
• Append-only by design — the application surface exposes no mutation or deletion endpoints for audit records. Retention is policy-driven and aligned with HIPAA §164.312(b).

The Consent FHIR resource is a first-class participant in the authorization pipeline (§4.2). This means that patient-delegated access, consent revocations, and GDPR data-subject rights are enforced by the same policy engine that evaluates all other authorization decisions — not by ad-hoc checks scattered across handlers.

8. FHIR R4 Resource Surface

ESUS implements 60+ FHIR R4 resources — a broad subset covering the clinical, administrative, medication, diagnostic, care-coordination, financial, document, compliance, and workflow domains that real healthcare applications need. Every resource below inherits the identity, authorization, encryption, audit, and rate-limiting controls described above. Security is enforced at the framework level, not opt-in per endpoint.

People and administrative: Patient, Practitioner, PractitionerRole, RelatedPerson, Person, Organization, Location, HealthcareService, Device, Group.

Clinical: Encounter, EpisodeOfCare, Observation, Condition, Procedure, AllergyIntolerance, DiagnosticReport, ClinicalImpression, DetectedIssue, RiskAssessment, Specimen, FamilyMemberHistory, Flag, Goal, Immunization, ImmunizationEvaluation, ImmunizationRecommendation.

Care coordination: CarePlan, CareTeam, ServiceRequest, Task, Communication, NutritionOrder.

Medications: Medication, MedicationKnowledge, MedicationRequest, MedicationDispense, MedicationAdministration, MedicationStatement.

Scheduling: Schedule, Slot, Appointment, AppointmentResponse.

Financial: Coverage, Claim, ClaimResponse, ExplanationOfBenefit, Account, Invoice, VisionPrescription.

Documents and media: DocumentReference, Composition, Media.

Terminology and knowledge: CodeSystem, ValueSet, Questionnaire, QuestionnaireResponse, ActivityDefinition, PlanDefinition, Measure, MeasureReport.

Compliance primitives: Consent, AuditEvent, Provenance, Subscription, and retention policies.

Platform services: Bulk Export (async exports in ndjson for analytics and migrations), SMART-on-FHIR OAuth (patient-delegated scoped access), FHIR batch and transaction bundles, $validate operations, metadata endpoints, anomaly detection, and IP blocklisting.

The list above is representative of what ESUS supports today; we continue to add resources as customer use cases require them. What is invariant is that every new resource ships behind the same security envelope as the rest.

9. Roadmap: Post-Quantum Cryptography

“Harvest now, decrypt later” is a real threat for healthcare data that must remain confidential for decades. A ciphertext captured in 2026 might face a quantum-capable adversary in 2040; the decryption timeline is longer than the data’s confidentiality timeline. ESUS plans a hybrid classical + NIST post-quantum migration that targets the layers with the longest confidentiality horizon first, on a deliberately conservative rollout.

9.1 Priority layers

1. Backup-encryption keys — the highest-longevity data surface. Stored backups may remain archived for years and are the most likely “capture now” target. These keys move first to hybrid KEM so that backups written today remain confidential even if one of the classical or PQC primitives is broken.
2. Envelope encryption (KDF/KEM boundary) — the envelope that protects per-field PHI keys migrates to ML-KEM (CRYSTALS-Kyber, FIPS 203) combined with the current HKDF-SHA256 path. Ciphertext envelopes remain backward-compatible through the key-id mechanism described in §5.1, so existing data stays readable during and after migration.
3. Audit and provenance signatures — ML-DSA (CRYSTALS-Dilithium, FIPS 204) is adopted for audit integrity signing. During transition, records are signed with both the current HMAC and ML-DSA so verifiers can validate either, enabling a staged rollout without breaking historical verification.

9.2 Hybrid by construction

The migration is hybrid, not replacement. Classical and PQC primitives are composed so that a cryptanalytic break in either layer does not break the system. Concretely, a shared secret is derived from both a classical key-agreement and an ML-KEM encapsulation, and the derived key feeds a KDF that mixes both inputs; an attacker must break both primitives simultaneously to recover plaintext. This approach follows current NIST and IETF guidance for PQC transitions.

9.3 Operational discipline

• Parameter sets — we will publish the specific ML-KEM and ML-DSA parameter sets (e.g., ML-KEM-768, ML-DSA-65) as each phase lands, along with the rationale.
• Testing — each primitive is rolled out in shadow mode first, where the new algorithm runs alongside the old and outputs are compared, before production cutover.
• Reversibility — because every envelope carries an algorithm and key id, we can revert a primitive decision without data loss if a published cryptanalytic finding requires it.
• Compliance mapping — the migration will align with NIST SP 800-208 / 800-227 and FIPS 203/204 as they are updated.

Timelines, parameter sets, and operational runbooks will be published publicly as each phase lands.

10. Contact

For security questions, coordinated disclosure, or to request additional technical depth under NDA for due diligence:

security@esus.health