health-records-vault

name

health-records-vault

description

Encrypted personal health document storage system. Use when you need to upload, browse, download, or share encrypted health documents, generate share links, export a backup archive, or understand the AES-256-GCM security model. Triggers include "upload health record", "encrypt document", "share medical file", "vault backup", "download record", "health record storage", or any task involving personal medical documents.

health-records-vault

Store and manage personal health documents with AES-256-GCM encryption at rest. A master password never touches the database - it is used only to derive a 256-bit key in memory via PBKDF2.

When to use

• Uploading PDFs, DICOM files, or images to the encrypted vault
• Browsing records by category (Lab Results, Imaging, Prescriptions, Insurance, General)
• Downloading a decrypted file for viewing or sharing
• Generating a time-limited, single-use share link for a provider
• Exporting an encrypted archive backup of all records
• Understanding the encryption and key derivation model

Base URL

http://localhost:4900   (default)

Configure with PORT env var.

Unlocking the vault

Before any authenticated request, you must unlock the vault:

curl -X POST http://localhost:4900/api/auth/unlock \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"password": "your-master-password"}'

The derived AES key is stored in server memory for the session duration. Rate limited to 5 attempts per 15 minutes.

Lock the vault:

curl -X POST http://localhost:4900/api/auth/lock -b cookies.txt

Upload a document

curl -X POST http://localhost:4900/api/records/upload \
  -b cookies.txt \
  -F "file=@/path/to/lab_results.pdf" \
  -F "category=Lab Results" \
  -F "description=Q1 2026 blood panel from Generic Lab" \
  -F "provider=Generic Lab" \
  -F "dateOfRecord=2026-01-15" \
  -F "tags=[\"CBC\",\"lipid\"]"

The file is encrypted with AES-256-GCM on the server before being written to disk. The original file is never written to disk in plaintext.

List all records

curl http://localhost:4900/api/records -b cookies.txt

Filter by category:

curl "http://localhost:4900/api/records?category=Lab%20Results" -b cookies.txt

Search:

curl "http://localhost:4900/api/records?search=blood+panel" -b cookies.txt

Download a record

curl -O -J http://localhost:4900/api/records/<id>/download -b cookies.txt

The file is decrypted in memory on the server and streamed to the client. No plaintext is ever written to disk.

Delete a record

curl -X DELETE http://localhost:4900/api/records/<id> -b cookies.txt

This removes the SQLite row and the .enc file from STORAGE_DIR.

Generate a share link

curl -X POST http://localhost:4900/api/records/<id>/share \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"expiresIn": 1440}'

expiresIn is in minutes. Response includes the token URL. Save this URL immediately - the token is not stored and cannot be retrieved again.

Consume a share link (no auth required)

curl -O -J -X POST http://localhost:4900/api/share/<token>/download

The link is marked as used after the first download. Subsequent attempts return 410 Gone.

Export backup archive

curl -O -J http://localhost:4900/api/backup -b cookies.txt

Downloads a .zip archive containing all encrypted .enc files and a vault-metadata.json file. The master password is NOT included - you must retain it separately to restore.

API reference

Method	Path	Auth	Description
POST	/api/auth/unlock	none	Derive key from password
POST	/api/auth/lock	session	Clear session and key
POST	/api/records/upload	session	Encrypt and store a file
GET	/api/records	session	List records (filter by category/search)
GET	/api/records/:id/download	session	Decrypt and stream a file
DELETE	/api/records/:id	session	Delete record and .enc file
POST	/api/records/:id/share	session	Generate single-use share token
POST	/api/share/:token/download	none	Consume token and stream file
GET	/api/backup	session	Export encrypted archive

Security model

master password
      |
      v
PBKDF2(password, salt, 100000 iterations, SHA-256)
      |
      v
256-bit AES key (RAM only, never persisted)
      |
      v
AES-256-GCM encrypt with unique 12-byte IV per file
      |
      v
<uuid>.enc stored in STORAGE_DIR

• SQLite stores only metadata (filename, category, tags, IV, salt) - never file contents
• Share tokens are stored as SHA-256 hashes - original token is returned once and never stored
• Session cookie: httpOnly, secure in production, sameSite=strict

Categories

Category	Description
Lab Results	Blood panels, urinalysis, metabolic tests
Imaging	X-rays, MRIs, CT scans, DICOM files
Prescriptions	Medication prescriptions and refill history
Insurance	Insurance cards, EOBs, coverage documents
General	Checkup notes, referrals, miscellaneous

Environment variables

Variable	Default	Description
PORT	4900	HTTP server port
DB_PATH	./data/vault.db	SQLite database file
STORAGE_DIR	./data/storage	Encrypted .enc file directory
SESSION_SECRET	(required)	express-session signing secret
MAX_FILE_SIZE_MB	50	Upload size limit
NODE_ENV	development	Set to production for secure cookies

Supported file types

• PDF (.pdf)
• DICOM (.dcm)
• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)

Maximum file size: 50 MB (configurable via MAX_FILE_SIZE_MB).

Running with Docker

docker compose up

Data is persisted in a Docker volume. Set SESSION_SECRET in your environment before starting.

Sample data notice

All built-in sample data uses clearly fictional names: "Sample Patient", "Generic Lab", "Dr. Sample", "Anytown Clinic", "Fictional Drug A". Never use real medication names or real medical values in demonstrations.