ⓘ
April 2026 Update: Architecture expanded to include production implementation files (zero_trust_auth.py, webhook_handler.py, main.tf), state-specific consent engine, consent revocation flow, Marketplace connection (Folder 07), and cross-folder dependency map. | Total files documented: 9 | Security layers: 7
Flow Step A — Patient Arrives
A1: Portal Entry
Patient visits Moonlitic consent portal. clear-frontend-hook.js generates a PKCE code_verifier using crypto.randomBytes(32).toString('base64url') and computes code_challenge as SHA-256 hash of verifier. clear-frontend-hook.js stores verifier in browser session storage.
OAuth2 + PKCE (RFC 7636)
A2: Authorization URL Construction
clear-backend.js builds the Clear authorization URL with parameters: client_id, redirect_uri, scopes (openid identity), response_type=code, state (CSRF token), code_challenge, code_challenge_method=S256. clear-backend.js stores state parameter in patient's server-side session.
PKCE Code Challenge
A3: Redirect to Clear
clear-frontend-hook.js redirects patient's browser to Clear's authorization endpoint (sandbox: sandbox.clearme.com, production: Clear). Patient is now in Clear's identity proofing flow.
Browser Redirect
Flow Step B — Clear IAL2 Verification
B1: Identity Proofing Flow
Clear Identity Platform presents identity proofing flow to patient. Patient completes NIST IAL2 requirements: government-issued ID scan (driver's license or passport), selfie liveness check, biometric match. Clear Identity Platform verifies all biometric and documentary evidence.
NIST IAL2
B2: Authorization Code Callback
Clear Identity Platform posts authorization code and state parameter to Moonlitic's registered redirect_uri (/auth/clear/callback). Request is sent as HTTP 302 redirect back to patient's browser.
OAuth2 Callback
B3: State Validation & Code Extraction
clear-backend.js receives callback request. clear-backend.js extracts the authorization code and state parameter from query string. clear-backend.js verifies state parameter matches CSRF token stored in patient's session (CSRF protection). If state mismatch, flow is aborted.
CSRF Validation
B4: Token Exchange
clear-backend.js exchanges authorization code for tokens by calling Clear's token endpoint with: code, redirect_uri, client_id, client_secret, code_verifier (PKCE). Clear Identity Platform verifies code_verifier against stored code_challenge. clear-backend.js receives access_token and id_token.
PKCE Verification
B5: UserInfo Endpoint Call
clear-backend.js calls Clear's userInfo endpoint (/api/public/v3/attributes.json) with the access token. Clear Identity Platform returns verified identity attributes: verified name, date of birth, address, email, and ial attribute. ial=2 confirms NIST IAL2 assurance level. clear-backend.js caches these attributes in patient's session.
NIST IAL2 Confirmed
Flow Step C — Age Gate & COPPA Check
C1: Age Calculation & Minor Blocking
clear-backend.js extracts date of birth from Clear userInfo response. clear-backend.js calculates patient age by comparing verified DOB against current date. If patient age < 18: clear-backend.js blocks consent flow and redirects patient to parent/guardian consent pathway (COPPA compliance). Minors cannot consent directly to data sharing under COPPA rules.
COPPA Age Gate
C2: Adult Session Binding
If patient age ≥ 18: clear-backend.js creates Moonlitic session binding with the following attributes: moonliticUserId (internal UUID), ial2Verified=true, verifiedName, verifiedDob, sessionCreatedAt (timestamp). clear-backend.js stores session server-side using express-session with httpOnly, secure, and sameSite=lax cookie flags.
COPPA Compliance
Flow Step D — Consent Category Selection
D1: Category Presentation
texas-health-consent.html presents patient with 12 consent categories organized in a 3x4 grid. Each category tile displays: category name, what data it covers, how it will be used, and the legal framework protecting it. Patient reviews categories and selects those they wish to consent to.
Category Grid
D2: The 12 Consent Categories
Mental Health
ENHANCED — §611
Behavioral / SUD
ENHANCED — 42 CFR Pt2
Reproductive Health
Standard
Genetic Data
ENHANCED — GINA
Wearable / Device
Standard
Financial / Claims
Standard
D3: Enhanced Consent Modal
For Mental Health, Behavioral / SUD, and Genetic Data categories: texas-health-consent.html presents a second confirmation modal that explicitly states the sensitivity of the data, the specific law protecting it (Texas Health & Safety Code §611, 42 CFR Part 2, or GINA), and requires a separate affirmative click to confirm. This enhanced consent step is auditable and compliance-engine uses it to gate any sensitive-category data access or sale.
Enhanced Consent Modal
Decision Branch after Step D: Enhanced Categories Selected?
YES — Patient Selected Enhanced Category
texas-health-consent.html presents separate confirmation modal for each sensitive category (Mental Health, SUD, Genetic Data). Patient must re-confirm selection with explicit click. clear-backend.js sets enhancedConsentFlag=true for each confirmed sensitive category in ACL record.
NO — Only Standard Categories Selected
clear-backend.js proceeds directly to ACL write (Step F). Standard consent ACL entry is written without additional modals. Flow continues normally.
Flow Step E — Data Aggregator Account Linking
E1: Data Aggregator Account Creation
After patient completes category selection (and any enhanced consent modals), clear-backend.js calls Aggregator API to create or link a Data Aggregator account for the patient. clear-backend.js passes the patient's verified identity attributes from IAL2 (verified name, DOB, address) to Data Aggregator. Aggregator API uses these attributes to locate and link patient's EHR records across connected health systems (Epic, Cerner, Athena, etc.).
EHR Linkage
E2: Data Aggregator Token Storage
Aggregator API returns a aggregatorId token that uniquely identifies the patient within Data Aggregator's system. clear-backend.js stores aggregatorId in patient's Moonlitic session alongside ial2Verified flag and session attributes. The aggregatorId is the key that Folder 02's clinical-intelligence-engine uses to pull EHR data in subsequent requests.
EHR Token Stored
Flow Step F — ACL Write
F1: Immutable Consent Record Creation
clear-backend.js calls acl-client.appendToLedger() to write an immutable consent record to Azure Confidential Ledger. The ACL entry contains the following fields: moonliticUserId, sessionId, ial2Verified=true, verifiedName (hashed with SHA-256), consentedCategories (list of all selected categories), enhancedConsentCategories (list of sensitive categories that received separate confirmation), aggregatorId, consentTimestamp (ISO 8601), ipAddressHash (hashed for audit trail).
ACL Write
F2: ACL Transaction ID & Gating Key
acl-client.js writes the record to Azure Confidential Ledger and returns aclTransactionId — a unique, immutable reference for this consent event. clear-backend.js stores aclTransactionId in patient's session. This ID is the gating key that Folder 02 (clinical-intelligence-engine), Folder 03 (compliance-engine), and Folder 04 (claims-orchestrator) use to verify consent before any data access or financial operation occurs.
Zero-Trust Foundation
Flow Step G — Downstream Triggers
G1: Parallel Trigger Fire
After successful ACL write,
clear-backend.js fires two downstream triggers in parallel:
Folder 04 Claims Enrichment: clear-backend.js POSTs to Folder 04 claims-orchestrator endpoint /claims/trigger/enrich-patient with aclTransactionId, moonliticUserId, aggregatorId. Folder 04 immediately pulls the patient's full claims history from their payor's FHIR API so the claims record is pre-populated before the first clinical encounter.
Folder 02 Clinical Intelligence: If billing context is available from intake form, clear-backend.js POSTs to Folder 02 clinical-intelligence-engine to begin the clinical intelligence pipeline asynchronously. Folder 02 uses aggregatorId to pull EHR data and compute care gaps.
G2: Patient Dashboard & Success Response
clear-backend.js returns HTTP 200 success response to patient's browser. Patient is redirected to personalized Moonlitic dashboard showing: consented data categories (checkmarks on selected tiles), Aggregator EHR connection status (green/amber/red indicator), initial care gap findings (populated asynchronously as Folder 02 clinical-intelligence-engine processes EHR data). Consent is now complete and platform is active.
Consent Complete
Security Architecture — 7 Zero-Trust Layers
Every layer below must pass before a single byte of PHI moves. Failure at any layer halts the entire pipeline.
🔒
Layer 1 — Identity Proofing (NIST IAL2)
Clear government ID scan + biometric liveness. No biometric data stored locally. Confirms patient is who they claim to be before any consent is collected. clear-backend.js
🔑
Layer 2 — OAuth2 + PKCE (RFC 7636)
Authorization code flow with SHA-256 code challenge. Code verifier never leaves backend. Prevents interception attacks even on compromised networks. clear-frontend-hook.js
📷
Layer 3 — Device Fingerprinting
JWT tokens bound to device fingerprint (user-agent + locale + IP hash + TLS). Max 5 devices per patient. Stolen tokens cannot be used on different devices. zero_trust_auth.py
🔐
Layer 4 — JWT Token Lifecycle (3-tier)
Enrollment token (1hr, enrollment:write) → Access token (15min, patient:read/write) → Refresh token (30 days). RS256 asymmetric signing via Azure Key Vault. zero_trust_auth.py
🔗
Layer 5 — Mutual TLS (mTLS)
API Gateway ↔ Backend: X.509 certificate verification. Issuer must be "Moonlitic Internal CA", subject must be "api-gateway.moonlitic.com". Prevents rogue internal services. Azure_API_Management Policy.xml
📚
Layer 6 — Cryptographic Consent Anchoring
Hash_Consent = SHA256(PatientID + GranularOptions + Timestamp). Signed with Azure Key Vault key. Written to Azure Confidential Ledger (immutable, tamper-proof). aclTransactionId becomes the gating key for ALL downstream operations. Confidential Ledger
🗃
Layer 7 — Always Encrypted + Row-Level Security
PHI columns encrypted with AEAD_AES_256_CBC_HMAC_SHA_256 using HSM-backed CMK. RLS ensures patients can only access their own records. DBA cannot read PHI — encryption is client-side. Always Encrypted SQL Schema
State-Specific Consent Engine
The consent UI is not one-size-fits-all. The state-specific engine adapts consent categories, enhanced modals, legal citations, and data-sharing rules based on the patient's jurisdiction. Documented in detail in The State Specific Consent Engine.docx.
How It Works
After IAL2 verification (Step B), clear-backend.js extracts the patient's verified address from Clear attributes. The state is resolved from the address and passed to texas-health-consent.html as a configuration parameter. The consent UI dynamically adjusts which categories appear, which require enhanced consent modals, and which legal citations are shown — all driven by the state-specific rule set.
Texas
HB 300 · HSC §611 · 42 CFR Pt2
Most restrictive. Mental health requires separate consent under §611. SUD records under 42 CFR Part 2. Breach notification within 60 days. Current reference implementation.
California
CCPA/CPRA · CMIA · Genetic Info Privacy Act
CMIA requires written authorization for medical data. CCPA adds right-to-delete. Genetic data has its own statute (SB 41). Enhanced modal for genetic + right-to-delete notice.
New York
SHIELD Act · Mental Hygiene Law §33.13
HIV/AIDS data requires specific written consent (PHL §2782). Mental health under §33.13 is stricter than federal HIPAA. Enhanced modals for HIV and mental health categories.
Florida
FIPA · §395.3025 · §394.4615
Mental health under Baker Act has special protections. HIV status requires separate consent. Substance abuse follows 42 CFR Pt2 federal framework. Standard + 2 enhanced modals.
Illinois
BIPA · Mental Health Code (740 ILCS 110)
BIPA governs biometric data (not stored locally via Clear design). Mental health records require separate consent under state code. Genetic data follows GINA.
Federal Baseline
HIPAA · 42 CFR Part 2 · GINA · COPPA
Minimum floor for all states. HIPAA general authorization + 42 CFR Pt2 (SUD) + GINA (genetic) + COPPA (minors). States may only add stricter protections, never weaken.
Flow Step H — Consent Revocation
Consent is not permanent. Patients can revoke all or specific categories at any time. Revocation propagates across all downstream folders within seconds and is itself recorded immutably in the Confidential Ledger.
1
Patient Initiates Revocation
Patient navigates to consent management in their Moonlitic dashboard (Marketplace Portal → My Data tab). Selects categories to revoke or chooses "Revoke All." Moonlitic presents confirmation modal explaining the downstream impact: data queries will be blocked, active clinical trial matches may be affected, pending payouts for revoked categories will still be honored.
2
ACL Revocation Record
clear-backend.js writes a new immutable record to Azure Confidential Ledger with event_type: "consent_revoked", the original aclTransactionId, and the list of revoked categories. A new revocationTransactionId is minted. The original consent record is NOT modified (append-only ledger) — instead, the revocation record references and supersedes it.
3
API Gateway Enforcement
Azure API Management Policy already checks Confidential Ledger on every request (see policy.xml). When the ledger returns a revocation record, the API Gateway returns HTTP 403: "Patient has revoked data access via Moonlitic Sovereignty Control." This blocks all data access in real-time without requiring backend code changes.
4
Downstream Propagation
clear-backend.js fires revocation events to downstream folders:
• Folder 02 (Clinical Intelligence): Marks patient's EHR data as consent-revoked; halts active intelligence pipelines for revoked categories.
• Folder 04 (Claims Engine): Blocks claims processing for revoked categories; existing perfected claims remain (legally required for billing).
• Folder 07 (Marketplace): Entitlement engine removes revoked data categories from all tile company queries. k-Anonymity pools are recomputed excluding the patient's revoked categories.
5
Patient Confirmation
Patient receives confirmation showing: revoked categories, revocationTransactionId (proof of revocation), timestamp, and a notice that revocation is effective immediately for new queries but does not retroactively affect already-delivered data (per HIPAA guidelines — revocation is prospective, not retroactive).
Design Decision: Why Prospective-Only Revocation?
Under HIPAA §164.508(b)(5), a patient's revocation of authorization applies only to future uses and disclosures. Data that was already shared under valid consent before revocation cannot be "unshared." This is consistent with how every major EHR and HIE handles revocation. Moonlitic enforces this by: (a) blocking all new queries for revoked categories at the API Gateway, (b) preserving historical audit records showing the data was accessed under valid consent at the time, and (c) honoring pending financial obligations (payouts, invoices) that were initiated before revocation.
Connection to Folder 07 — Marketplace
Folder 01 consent is the gate that unlocks Marketplace participation. Without a valid aclTransactionId, a patient cannot appear in any tile company's data set, match to clinical trials, or earn payouts.
Consent → Entitlement Engine
When a tile company in the Marketplace runs a query, Folder 07's data-entitlement-engine.js checks the patient's aclTransactionId against the Confidential Ledger. It verifies: (a) consent is not revoked, (b) the queried data category was consented to, (c) enhanced consent flag is present for sensitive categories. Only patients with valid, matching consent appear in query results.
Entitlement Gate
Consent → Clinical Trial Matching
Folder 07's two-way clinical trial matching engine uses consented data categories to match patients to CRO trials. A patient who consented to Oncology data will be matched to oncology trials; a patient who did not consent to that category will never appear — even in aggregate counts. Consent granularity drives trial granularity.
Trial Matching
Consent → Patient Payouts
When tile companies purchase data that includes a patient's consented records, Folder 03's disbursement-engine.js computes the patient's share and routes it through Velo Payments. The payout is linked to the original aclTransactionId — creating an auditable chain from consent to compensation. Patients can see this chain in the Marketplace Portal's Earnings tab.
Payout Chain
Consent → Patient Portal (PATIENT Role)
The PATIENT role in the Marketplace Portal (Folder 07) lets patients view their consented categories, active trial matches, payout history, and query activity — all gated by the consent record established here in Folder 01. The patient welcome panel shows new trial matches and pending payouts that are derived from their consent choices.
Patient Dashboard
Cross-Folder Dependency Map
Folder 01 is the root of the entire Moonlitic trust chain. Every downstream folder depends on the aclTransactionId minted here. This table documents every cross-folder dependency.
| Downstream Folder |
Dependency |
What Folder 01 Provides |
What Happens Without It |
| 02 Clinical Data Intelligence |
Triggered by Step G (async POST) |
aclTransactionId, aggregatorId, consented categories list |
Clinical intelligence pipeline will not start. No EHR data is pulled. |
| 03 Payouts |
Consent validation before any disbursement |
aclTransactionId as proof of consent for payout eligibility |
Disbursement engine refuses to process payout. Compliance engine blocks. |
| 04 Claims Engine |
Triggered by Step G (async POST) |
aclTransactionId, moonliticUserId, aggregatorId |
Claims enrichment does not fire. Patient claims history is not pre-populated. |
| 05 Reconciliation Engine |
Consent chain verification during financial reconciliation |
Original consent hash for audit trail validation |
Reconciliation flags record as "consent not verified" — held for manual review. |
| 07 Marketplace |
Entitlement engine checks on every tile company query |
aclTransactionId, consented categories, enhanced consent flags |
Patient excluded from all query results, trial matching, and payout eligibility. |
Zero-Trust Principle
No downstream folder trusts Folder 01's output blindly. Each folder independently verifies the aclTransactionId against the Confidential Ledger before taking action. This means: even if an attacker compromised a downstream service and fabricated a transaction ID, the Confidential Ledger verification would reject it. Trust is never assumed — it is cryptographically verified at every boundary.
Provider-to-Provider Consent Request Flow
Step 1: External Provider Requests Access
External Provider (provider at different institution) clicks "Request Patient Consent" on a locked data panel in the Clinician Portal. The Moonlitic Entitlement Engine captures: requesting provider NPI, institution name, specialty, and requested data categories (Labs, Imaging, Medications, etc.). Request is timestamped and logged to Azure Confidential Ledger.
Cross-Institutional Request
Step 2: Moonlitic Consent Gateway Validates Provider
Moonlitic Consent Gateway validates the requesting provider's credentials via NPI registry lookup (NPPES database). consent-validation.js verifies: (a) NPI is active and unrevoked, (b) Specialty matches claimed specialty, (c) Institution is recognized. Upon validation, consent-validation.js generates a consent request record with SHA-256 hash of request metadata. This hash is logged to Azure Confidential Ledger for immutable audit trail.
NPI Validation + Ledger
Step 3: Patient Notification via Mobile App
Patient receives push notification via Moonlitic mobile app. Notification displays: (a) Who is requesting: provider name, specialty, institution, (b) What they're requesting: specific data categories, (c) Why: referral context from treating provider (if provided), (d) Estimated duration: how long access will be valid. Patient can tap notification to open consent review screen within 24 hours.
Push Notification
Step 4: Patient Consent Decision
Patient has four options: (a) Approve all requested categories — all requested data becomes accessible, (b) Approve selectively (e.g., Labs yes, Imaging no) — mixed consent state stored separately, (c) Deny with no reason required — provider receives "Access Denied" notification, (d) Defer for later review — request persists for 7 days before auto-expiring. Each decision generates a unique aclTransactionId via uuid4() and is bound to that specific provider-institution pair.
Multi-Decision Pattern
Step 5: Consent Record Logged to Ledger
consent-ledger.js writes consent decision record with: patient ID, requesting provider NPI, requesting institution, approved categories (array), denied categories (array), timestamp (ISO 8601), expiration date (365 days default), SHA-256 hash chain linking to request record (Step 2). All writes are immutable; prior records are never mutated. Azure Confidential Ledger stores this record in /consents/{aclTransactionId}.
ACL Ledger Write
Step 6: Real-Time Portal Update via WebSocket
Upon consent approval, consent-notification.js sends WebSocket message to External Provider's Clinician Portal instance (if active). Portal immediately unlocks relevant data panels and refreshes FHIR bundle views. For approved categories, provider sees live data; for denied categories, panels remain locked with "Access Denied" indicator. If provider is offline, portal polls on next login.
WebSocket Notification
Step 7: Prospective Revocation (HIPAA §164.508(b)(5))
Patient can revoke cross-institutional access at any time via Moonlitic settings > "Manage Cross-Institutional Access". Revocation is logged as new ledger entry. Upon revocation: (a) data access ceases immediately, (b) Clinician Portal receives WebSocket notification and re-locks all panels for that provider-institution pair, (c) prior data already accessed is NOT retroactively hidden (per HIPAA guidance — revocation is prospective-only), (d) audit log shows revocation timestamp and initiator (patient).
Revocation (Prospective)
Cross-Folder Impact — Consent-Gated Rendering
Folder 02: Clinical Data Intelligence
FHIR bundles returned by Folder 02 are filtered per-provider based on the aclTransactionId and consented categories stored in Folder 01. If provider has "Labs: Approved, Imaging: Denied", Folder 02 excludes DiagnosticReport (imaging) resources but includes Observation (labs) resources. Filter applied at FHIR bundle serialization layer.
Folder 04: Claims Engine
Claims data visibility is gated by Diagnoses and Procedures consent categories. If patient consents to Labs but denies Procedures, Folder 04 shows claim line items tied to lab work but hides surgical procedure codes and associated charges. Claim totals are recalculated per-provider per-consent scope.
Folder 07: Marketplace / Clinician Portal
Locked data panels render in real-time based on current consent status from Folder 01. WebSocket connection established on portal load listens for consent state changes. When patient approves/denies/revokes consent, all active portals receive consentStateChanged event and immediately re-render. No page refresh required — panel unlock/lock is animated in-place.
Real-Time Propagation Architecture
When Folder 01 writes a new consent record (Step 5), it publishes a message to Azure Service Bus topic consent-ledger-updates. All downstream folders (02, 04, 07) subscribe to this topic. Subscribers receive consent event with aclTransactionId, triggering immediate data re-fetch or re-render with new consent scope. Mean latency from patient decision to downstream re-render: <500ms.
