platform-codebase/features/health-verification/backend-api

Health Verification Backend API

Mutual health verification system for the Lilith Platform with tiered trust, privacy-controlled sharing, and peer attestation.

Architecture

Verification Tiers

1. Tier 1 - Self-Reported: User manually enters test results
2. Tier 2 - Photo Upload: User uploads photo of lab results (encrypted storage)
3. Tier 3 - Lab API: Direct integration with testing labs (future)

Privacy Levels

• EXPLICIT: Per-person share required (nothing visible otherwise)
• BADGE_ONLY: Shows tier badge icon only (no details)
• BADGE_DETAIL: Badge + summary (test date, tier, attestation count)
• ENCOUNTER: Visible only during a booking session

Core Features

• Health Records: CRUD with tier upgrades, 30-day expiry
• Sharing: Granular privacy controls, session-scoped shares
• Peer Attestations: Social proof (append-only)
• Invite System: Non-users can upload verification via email invite
• Automatic Expiry: Cron jobs for expiry + reminders (7/3/1 days)
• Audit Trail: Complete audit log for all operations

Database

Uses dedicated PostgreSQL instance (port 25452):

• health_verification_records: Encrypted test results (PgCrypto)
• health_verification_shares: Privacy-controlled sharing
• health_verification_peer_attestations: Append-only attestations
• health_verification_invites: Email-based verification invites
• health_verification_audit_log: Complete audit trail

API Endpoints

Records

• POST /records - Create health record
• GET /records/me - Get my records
• GET /records/:id - Get specific record (owner or shared-with)
• PATCH /records/:id - Update record (tier upgrade)
• DELETE /records/:id - GDPR deletion
• GET /records/status/:userId - Badge-level status (public)

Sharing

• POST /shares - Create share
• GET /shares/received - Records shared with me
• GET /shares/granted - Shares I've granted
• DELETE /shares/:id - Revoke share
• GET /shares/session/:sessionId - Session health matrix

Attestations

• POST /attestations - Create peer attestation
• GET /attestations/record/:recordId - Get attestations

Invites

• POST /invites - Send verification invite (rate limited)
• GET /invites/verify/:token - Validate token (PUBLIC)
• POST /invites/verify/:token/upload - Upload via invite (PUBLIC)
• POST /invites/:id/remind - Send reminder

Health

• GET /health - Health check endpoint

Environment Variables

# Database
DATABASE_HOST=localhost
DATABASE_PORT=25452
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=health_dev
DATABASE_POSTGRES_NAME=lilith_health_verification

# Encryption key for testResults column
HEALTH_COLUMN_ENCRYPTION_KEY=<64-char-hex-key>

# CORS
CORS_ORIGIN=http://localhost:5201

Development

# Install dependencies
bun install

# Build
bun run build

# Verify (includes circular dependency check)
bun run verify

# Start development server
bun run dev

# Run tests
bun run test

Domain Events

Emitted

• health:record_created - New health record created
• health:status_changed - Health status changed
• health:record_expired - Record expired
• health:expiry_reminder - Expiry reminder (7/3/1 days)
• health:invite_sent - Verification invite sent
• health:invite_completed - Invite completed
• health:invite_reminder_sent - Invite reminder sent
• health:session_check_complete - Session health check complete

Consumed

• coop-session.created - Triggers health check for session participants

Security

• Column Encryption: Test results encrypted with PgCrypto
• Rate Limiting: 10 invites/day, 3 reminders/day
• Audit Logging: All operations logged with IP addresses
• Token Security: 64-char hex tokens (crypto.randomBytes)
• GDPR Compliance: User-initiated deletion, 90-day retention for non-users

Integration

Service-to-service health checks:

// Booking system checks health before session confirmation
const response = await fetch(`${healthApiUrl}/records/status/${userId}`);
const { hasActiveRecord, tier } = await response.json();

License

Proprietary - Lilith Platform