A cryptographic trust layer for FHIR-based health data consent.
When a patient revokes consent in a current EHR system, a database flag changes. Whether that change propagates depends entirely on the implementing vendor. The patient has no cryptographic proof of what was shared, when, or with whom.
IHE's Privacy Consent on FHIR (PCF) defines a consent authorization architecture. It deliberately leaves the trust model to implementers. In practice, that means the EHR vendor is the root of trust — enforced by policy, not by math.
This protocol closes that gap.
Patient-controlled DID identity. Each patient holds a W3C Decentralized Identifier derived from an Ed25519 keypair. The private key stays on the patient's device.
Signed FHIR R4 Consent resources. Every consent grant is a valid FHIR R4 Consent resource carrying the patient's Ed25519 signature. Any post-hoc modification invalidates the signature. Revocation is itself a signed artifact.
Hash-chained audit log. All consent lifecycle events write to an append-only SHA-256 hash-chained log. Any modification to any entry — including deletion or reordering — breaks the chain. Maps to IHE BALP-compatible FHIR AuditEvent resources, satisfying 45 CFR §164.312(b).
Consent API server. A FastAPI middleware layer that sits between any EHR and any downstream application. Developers call this API to issue, verify, and revoke consent — the cryptographic enforcement happens server-side.
openconsent/
├── sdk/ TypeScript SDK — DID identity, signed FHIR Consent, audit log
└── server/ Python consent API server — FastAPI middleware
cd sdk && npm installimport { generatePatientIdentity, issueConsent, verifyConsent, AuditLogger } from "@openconsent/sdk";
const patient = await generatePatientIdentity();
// patient.did → "did:health:86tgCygCYCJn2chupLs..."
const grant = await issueConsent(patient, {
providerDID: "did:health:HolyNameMedicalCenter",
providerName: "Holy Name Medical Center",
scopes: ["lab_results", "imaging_reports"],
durationDays: 90,
});
// grant.fhirConsent → valid FHIR R4 Consent resource
const check = await verifyConsent(grant, patient.publicKey);
// → { valid: true }cd server
pip install -r requirements.txt
uvicorn main:app --reloadAPI docs available at http://localhost:8000/docs
Register a patient identity:
POST /identity/register
{ "consent_id": "...", "did": "did:health:...", "public_key_hex": "...", "did_document": {...} }Issue a signed consent grant:
POST /consent/issue
{ "consent_id": "...", "patient_did": "...", "provider_did": "...", "scopes": ["lab_results"], ... }Verify consent before accessing data:
POST /consent/verify
{ "consent_id": "...", "provider_did": "...", "requested_scope": "lab_results" }
→ { "valid": true, "access_token": "...", "token_expires_at": "..." }Revoke consent:
POST /consent/revoke
{ "consent_id": "...", "patient_did": "...", "revocation_signature": "..." }Retrieve and verify audit log:
GET /audit/{patient_did}
POST /audit/verify/{patient_did}
→ { "valid": true, "entry_count": 7, "head_hash": "..." }SDK stress test: 21/21 passed
API integration test: 13/13 passed
Security properties verified:
✓ Tampered consent payload rejected
✓ Invalid signature rejected (422)
✓ Wrong provider DID rejected
✓ Out-of-scope access denied
✓ Post-revocation access denied
✓ Audit chain tamper detection
✓ Concurrent independent grants
Cryptographic primitives: Ed25519 · SHA-256 · W3C DID
This protocol does not replace FHIR, SMART on FHIR, or IHE PCF. It supplies the cryptographic trust layer they leave unspecified.
| Standard | Provides | Leaves open |
|---|---|---|
| FHIR R4 Consent | Resource structure and semantics | Trust model |
| IHE PCF | Consent authorization architecture | Cryptographic enforcement |
| SMART on FHIR | OAuth-based access delegation | Patient-key-anchored signing |
| OpenConsent | Cryptographic trust model | Compatible with all above |
v0.1.0 (current) — SDK + API server, DID identity, signed FHIR R4 Consent, cryptographic revocation, hash-chained audit log
v0.2.0 — ZK-SNARK selective disclosure, break-glass emergency access, multi-sig key recovery
v0.3.0 — HL7 Implementation Guide draft, ONC certification pathway documentation
This repository is the reference implementation for a protocol specification paper in preparation. Target venues: JAMIA, npj Digital Medicine, NEJM Catalyst.
Working title: OpenConsent: A Patient-Anchored Cryptographic Trust Protocol for FHIR Consent Enforcement
If you work in FHIR security, SSI/DID health identity, or patient-controlled health records and want to collaborate on the specification or manuscript, open an issue.
MIT licensed and intentionally open. The goal is HL7 Implementation Guide adoption, not a proprietary standard.
MIT — see LICENSE
OpenConsent Protocol v0.1.0 · W3C DID Core · FHIR R4 · Ed25519 · SHA-256 · IHE BALP