Sarah is 34. She goes for her usual Saturday morning run in Central Park. Two miles in, she collapses.

A bystander calls 911. The paramedic arrives in four minutes. Sarah is unconscious. Her iPhone is locked — Face ID won't work on an unconscious face. Her emergency contact isn't picking up.

The paramedic needs to know two things right now:

1. Is she allergic to anything?
2. What medications is she on?

She has no way to know that Sarah has a severe sulfa drug allergy and takes warfarin — a blood thinner that makes certain emergency interventions life-threatening. She makes a judgement call based on zero information.

She gets lucky. Sarah survives.

Millions of people aren't that lucky.

The instinctive answer is "just put it in your phone's Medical ID." But Medical ID only works if:

• The paramedic knows to look for it
• The right information was entered and kept up to date
• The doctor treating you is in the same country, speaks the same language, and has time to scroll through a phone

The deeper answer is that the medical records system was never designed for emergencies. It was designed for scheduled appointments between a patient who is awake, coherent, and cooperative — and a doctor who has time to look things up.

The moment that design assumption breaks down — car accident, stroke, allergic reaction, cardiac arrest — the entire system fails simultaneously.

Consider what happens when that emergency occurs:

• Your records are locked inside hospital portals that don't talk to each other
• The ER doctor treating you has never seen you before and has no access to your history
• If you're travelling internationally, the language barrier makes everything worse
• Every minute spent tracking down your records is a minute not spent treating you

This is not a rare edge case. It is the default state of emergency medicine. Doctors make critical treatment decisions with incomplete information every single day — not because the information doesn't exist, but because there is no reliable way to get it to them in time.

Here is what we noticed that others missed:

The problem is not storing medical records. That has been solved. The problem is delivering the right records to the right doctor in the right language in the first 60 seconds of an emergency — without requiring the patient to do anything.

Every existing solution fails this test:

None of these work when the patient is unconscious. None of them work across language barriers. And critically — none of them can prove that the document the doctor sees is the same document that was originally created, not a selectively edited screenshot.

MedVault solves all three.

MedVault is a zero-knowledge, end-to-end encrypted health record platform with one core design principle:

Medical information should reach the doctor who needs it, in the language they speak, in under 10 seconds — regardless of whether the patient can help.

Here is how it works:

┌─────────────────────────────────────────────────────────────────┐
│  PATIENT (at home, healthy, five minutes of setup)              │
│                                                                 │
│  Uploads lab results, prescriptions, vaccine cards              │
│         ↓                                                       │
│  AES-256-GCM encryption happens in the browser                  │
│  Server receives only ciphertext — we cannot read your files    │
│         ↓                                                       │
│  Prints a wallet card: name + QR code. Nothing else.            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
                        [ EMERGENCY ]
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  PARAMEDIC (no account, no app, just a phone camera)            │
│                                                                 │
│  Scans the QR code on the wallet card                           │
│         ↓                                                       │
│  Browser decrypts the original documents — not summaries,       │
│  not screenshots, the actual original encrypted files           │
│         ↓                                                       │
│  AI generates a clinical summary in the doctor's language       │
│  Blood type · Allergies · Medications · Conditions              │
│         ↓                                                       │
│  Access expires automatically. Every scan permanently logged.   │
└─────────────────────────────────────────────────────────────────┘

Scan. Eight seconds. In her language:

PATIENT: Sarah Chen, 34, Female
BLOOD TYPE: A+

⚠ CRITICAL ALERTS
• Severe sulfa drug allergy — do NOT administer sulfonamides
• Currently on warfarin — elevated bleeding risk, check INR before procedures

ACTIVE CONDITIONS
• Atrial fibrillation (diagnosed 2023)

CURRENT MEDICATIONS
• Warfarin 5mg daily · Metoprolol 25mg twice daily

EMERGENCY CONTACT
• James Chen (Husband) · +1 (212) 555-0147

No app. No account. No phone unlock. No language barrier. No guesswork.

Every document is encrypted in your browser using AES-256-GCM before it ever touches our servers. We store only encrypted ciphertext. This is not a privacy policy — it is a cryptographic guarantee. Even a complete breach of our servers exposes nothing readable.

Generate a time-limited QR code. Any doctor scans it with any phone camera — no app download, no account creation, no waiting room paperwork. Configurable expiry: 15 minutes, 30 minutes, or 1 hour. Access ends automatically.

Gemini AI reads your decrypted documents and generates a structured clinical summary in the doctor's chosen language — 15 languages, including Yoruba, Hausa, and Igbo alongside English, French, Spanish, Arabic, and 8 others. The language barrier between patient and doctor disappears.

A credit-card sized card (ISO 85.6×54mm) you keep in your wallet behind your driver's licence. Front: your name and a QR code. After scanning: blood type and allergies — the two pieces of information that can cause immediate death if unknown. Exportable as a print-ready PNG. No PIN, no barrier — modelled on the MedicAlert bracelet. Works when you are unconscious.

AI extracts numeric biomarkers from every lab result you upload — HbA1c, cholesterol, haemoglobin, kidney function, thyroid levels, and 20+ others — and plots them over time. Watch your health trajectory across months and years. Results are cached so Gemini analyses each document exactly once.

Every time a doctor scans your QR, it is logged permanently — timestamp, language used, whether it was a first or repeated access. You can see exactly who has viewed your records and when. This is the transparency that paper records, USB drives, and most health apps have never provided.

Your encryption key is derived from your password using PBKDF2-SHA256 (100,000 iterations) and exists only in your browser's memory for the duration of your session. It is never transmitted to our servers. A complete compromise of our infrastructure exposes nothing but encrypted bytes.

When a doctor uses the emergency QR, their browser decrypts the original file — the exact bytes you uploaded. You had no opportunity to modify it after upload. The document the doctor sees is cryptographically identical to the original. This is the chain of custody that no other patient-facing health tool provides.

1. Create your vault — sign up, complete your medical profile (blood type, allergies, medications, conditions, emergency contacts)
2. Upload your documents — lab results, prescriptions, vaccine records, imaging reports — encrypted automatically in your browser
3. Print your wallet card — one click from the Dashboard generates a print-ready PNG with your name and QR code
4. You're done — carry the card. Update your documents when you get new results.

1. Paramedic or ER doctor finds the card in your wallet
2. Scans the QR with any phone camera — opens instantly in a browser, no app required
3. Selects their language from 15 options
4. Clicks Generate Summary — AI produces a structured clinical summary in under 10 seconds
5. For full documents — generate a time-limited QR from the Emergency Share screen; doctor decrypts your original files in their browser
6. Access expires automatically — no manual revocation needed; you see every access in your audit trail

1. Open the Emergency Share screen
2. Select which documents to share and for how long
3. Show the QR to your doctor — they scan it, see your records in their preferred language, and the access token expires when the appointment ends

The following invariants are enforced by the architecture — not by policy:

• The server never holds a plaintext document. Encryption happens in the browser before the upload request is initiated.
• The server never holds an encryption key. Keys are derived from passwords client-side and stored only in browser memory.
• Emergency share keys never touch the server. The ephemeral share key is embedded in the URL fragment (#key=...). URL fragments are never sent in HTTP requests by specification.
• The audit trail is append-only. scan_logs rows are inserted, never updated or deleted. Every access is permanently and immutably recorded.

Password + UserID  →  PBKDF2-SHA256 (100k iterations)  →  Master Key
                                                               │
                                              ┌────────────────┘
                                              │
                                    Per-document AES-256-GCM key
                                              │
                              ┌───────────────┴────────────────┐
                              │                                │
                    Wrapped with master key              Encrypts document
                              │                                │
                    Stored in document_keys          IV + ciphertext uploaded
                              │                         to Supabase Storage
                              │
                    (useless without master key)

Emergency share:

New ephemeral AES-256-GCM key generated
              │
All selected documents re-encrypted with share key
              │
Share key  →  base64  →  embedded in URL fragment: /doctor/:token#key=<base64>
              │
              └─ Fragment is never sent to server (HTTP specification)
              └─ Doctor's browser extracts key → decrypts documents locally
              └─ Share expires at configured time → key becomes unreachable

profiles          -- Patient identity and medical profile
documents         -- Document metadata (no plaintext content)
document_keys     -- AES-GCM keys wrapped with master key (useless without password)
qr_tokens         -- Time-limited emergency share tokens
scan_logs         -- Immutable access audit trail
health_metrics    -- Biomarker cache (Gemini runs once per document)

Full annotated DDL is in /docs/schema.sql.

• Node.js v18+
• Supabase account (free tier sufficient for demo)
• Google Gemini API key (free tier sufficient)

# Clone and install
git clone https://github.com/your-username/medvault.git
cd medvault
npm install

# Configure environment
cp .env.example .env
# Add your VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_GEMINI_API_KEY

# Start development server
npm run dev

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key
VITE_GEMINI_API_KEY=your_gemini_key

Run in your Supabase SQL Editor:

-- Wallet card token
ALTER TABLE public.profiles
  ADD COLUMN IF NOT EXISTS wallet_token uuid DEFAULT gen_random_uuid();

-- Scan history
ALTER TABLE public.scan_logs
  ADD COLUMN IF NOT EXISTS scanned_at    timestamptz DEFAULT now(),
  ADD COLUMN IF NOT EXISTS language_used text;

-- Pre-signed share URLs
ALTER TABLE public.qr_tokens
  ADD COLUMN IF NOT EXISTS share_signed_urls jsonb DEFAULT '{}';

-- Biomarker cache
CREATE TABLE IF NOT EXISTS public.health_metrics (
  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  patient_id   uuid REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  document_id  uuid REFERENCES public.documents(id) ON DELETE CASCADE NOT NULL,
  test_date    date NOT NULL,
  biomarkers   jsonb NOT NULL DEFAULT '[]',
  doc_title    text,
  created_at   timestamptz DEFAULT now(),
  UNIQUE (document_id)
);

ALTER TABLE public.health_metrics ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users manage own metrics"
  ON public.health_metrics FOR ALL
  USING  (patient_id = auth.uid())
  WITH CHECK (patient_id = auth.uid());

src/
├── pages/
│   ├── Landing.tsx           # Public landing page
│   ├── Auth.tsx              # Sign in / Sign up
│   ├── Onboarding.tsx        # 5-step medical profile setup
│   ├── Dashboard.tsx         # App home — real-time data, activity feed
│   ├── Vault.tsx             # Encrypted document store
│   ├── Emergency.tsx         # Time-limited QR generation + audit trail
│   ├── Health.tsx            # AI biomarker trend charts
│   ├── Profile.tsx           # Inline-editable medical profile
│   ├── DoctorView.tsx        # Public emergency view — multilingual AI summary
│   └── MedicalIDCard.tsx     # Permanent wallet card scan page
│
├── components/
│   ├── WalletCardButton.tsx  # Canvas 2D PNG export — front + back
│   ├── ShareExpiryBanner.tsx # Sticky warning when active QR is expiring
│   └── DocExpiryWarnings.tsx # Stale document alerts by category
│
├── hooks/
│   ├── useAuth.ts            # Auth state — onAuthStateChange only, no race conditions
│   ├── useHealthMetrics.ts   # Biomarker extraction + caching
│   ├── useScanHistory.ts     # Grouped audit trail with first/repeat detection
│   └── useActiveShares.ts    # Active QR polling + expiry warnings
│
└── lib/
    └── cryptoUtils.ts        # AES-GCM, PBKDF2, key wrap/unwrap — Web Crypto API only

• Documents uploaded before the document_keys table existed cannot be decrypted — re-upload required
• The permanent wallet card shows blood type and allergies without authentication by design (MedicAlert model) — patients who want a higher security threshold should use the time-limited QR instead
• Biomarker extraction depends on Gemini's ability to parse the specific lab format — non-standard layouts may miss some values
• Supabase storage signed URLs have a 1-hour ceiling that may be shorter than some configured QR expiry windows

• FHIR R4 import — pull records directly from hospital EHR systems
• NFC wristband — write permanent card URL to NFC sticker, tap to open
• Offline vault — service worker caches encrypted documents for no-internet access
• Next-of-kin delegation — trusted person can generate emergency QR on patient's behalf
• Custom AI prompts — treating physicians can ask specific questions about the patient's history
• Biometric vault unlock — WebAuthn as alternative to password entry

MIT — see LICENSE