Cardano Healthcare Vault - Backend

Decentralized Electronic Health Record (EHR) system with encrypted medical file storage on IPFS, immutable verification on Cardano blockchain, and multi-layer permission control.

🏗️ Architecture

Core Components

• Encryption Service: AES-256-GCM authenticated encryption
• IPFS Storage: Pinata-backed decentralized file storage
• 4-Layer Permission System:
  1. Hydra Layer-2 (5-15ms) - Off-chain state channels, 100-400x faster
  2. Aiken Layer-1 (~2s) - Plutus V3 smart contracts
  3. Midnight ZK (800-1200ms) - Zero-knowledge proofs
  4. Blockfrost L1 (500-2000ms) - Public blockchain fallback
• Audit Logging: Winston-based 90-day retention, HIPAA/GDPR compliant
• Key Management: In-memory CEK store with RSA-OAEP wrapping

🚀 Quick Start (demo mode — no real API keys needed)

Prerequisites

• Node.js 18+
• MongoDB running locally (or update DB_URI to a remote instance)
• Redis is optional — DISABLE_REDIS=true uses an in-memory CEK cache instead

Installation

npm install
cd mock-hydra && npm install && cd ..

Configuration

cp .env.example .env

The defaults in .env.example run the whole system in DEMO_MODE: encryption and Hydra L2 are genuinely live, everything else (IPFS, Midnight, Blockfrost, wallet signatures) runs against mocked/local scaffolding so the full pipeline works without any real credentials. See the comments in .env.example for where to plug in real Blockfrost/Pinata/Midnight keys later — flip DEMO_MODE=false once you do.

Generate actor keys (once)

node scripts/genActorKeys.js

This generates RSA key pairs for 4 actors:

• 01 - Patient
• 02 - Doctor
• 03 - Hospital
• 04 - Insurance

Run

# Optional: Terminal 1 — mock Hydra L2 node
cd mock-hydra && npm start

# Terminal 2 — main server
npm start        # or: npm run dev (nodemon)

You can skip the mock Hydra node. If no Hydra node answers, the server runs a simulated Hydra head in-process (this is what the hosted Vercel demo uses). The simulated head fills itself with made-up patients (PT-xxxx, tagged synthetic) so the L2 layer looks alive. Its timing is simulated too, but every snapshot is still signed by all four parties with real Ed25519 keys, and the signatures are checked again each time the head is read. Set HYDRA_MODE=simulated to always use it, or HYDRA_MODE=remote to turn the fallback off.

Four actor portals

Each actor has its own portal and its own sign-in:

Portal	URL	What it shows
Patient	/portal/patient	Upload & encrypt, my records (grant and revoke), access history, Hydra L2 network
Doctor	/portal/doctor	Records shared with me, request access, my activity
Hospital	/portal/hospital	Records shared with me, request access, my activity
Insurance	/portal/insurance	Records shared with me, request access, my activity

A portal opens only for a browser signed in as that actor and is locked to it: every API call carries an X-Acting-As header, and the server refuses a call from a portal whose actor is not signed in, or that tries to act as another actor. Requesting actors only ever see the records shared with them, never who else has access (the same property the Midnight ZK layer protects), and only their own audit entries. Signing out of one portal leaves the others signed in, so several portals can be open side by side.

Guided demo

Run the guided demo on the landing page (or open /present) loads the four portals side by side and runs every feature end to end, explaining the idea behind each step and checking the result on the server:

1. Each actor signs in to its own portal; the server refuses a cross-portal upload
2. The patient encrypts and uploads a synthetic lab report for the Doctor and Hospital
3. The access list is published as a signed Hydra L2 snapshot
4. The Doctor sees the shared record, without the access list
5. The Doctor's request passes the four-layer cascade
6. The Doctor decrypts the report
7. The Hospital is granted with its own key
8. Insurance looks the patient up and is refused
9. The patient revokes the Hospital: key rotation
10. The Hospital is locked out
11. The audit trail: the patient sees everything, the Doctor only its own activity

The 24 checks are listed as the demo runs, so it doubles as an end-to-end test. Space pauses, → skips the wait, Esc stops. /present?autostart=1 starts it straight away. It needs DEMO_MODE=true for one-click sign-in; otherwise sign in to each portal at /login first.

Sign-in works on a fresh deploy without extra setup: the actors' password hashes ship in config/actor-credentials.json, and on Vercel the session key is derived from server-only settings. Setting ACTOR_CREDENTIALS and SESSION_SECRET (from node scripts/setActorPasswords.js) overrides both.

Then open http://localhost:4000 for the landing page and http://localhost:4000/login to sign in to a portal.

Wallets: with an Eternl extension installed, "Connect Wallet" uses it and signs every action with CIP-8. Without one, and only while the server runs with DEMO_MODE=true, the portals fall back to a demo wallet so the full pipeline can still be shown in any browser.

flowchart LR
    P[Patient uploads file] --> E[Encrypt with AES-256-GCM]
    E --> I[Store on IPFS]
    E --> W[Wrap key for each chosen actor]
    W --> H[Share via Hydra L2]
    D[Doctor asks for access] --> C{Permission check<br/>Hydra, Aiken, Midnight, Blockfrost}
    C -->|allowed| U[Doctor unwraps key and reads file]
    C -->|denied| X[Access denied + audit log]
    R[Patient revokes access] --> K[New key, file re-encrypted]

📡 API Endpoints

Upload & Encrypt

POST /api/encrypt/upload
Content-Type: multipart/form-data

Body:
- file: medical file
- ownerAddr: wallet address
- actorIds: comma-separated (e.g., "01,02,03")

This is the beginning of the README. Read the rest at the original. Read the full README ↗