Refactor/architecture hardening

.env.PRODUCTION.example

@@ -0,0 +1,37 @@
+# ============================================================
+# PRODUCTION DEPLOYMENT - DO NOT COMMIT ACTUAL VALUES
+# ============================================================
+#
+# Copy this file to .env.production (NOT tracked by git)
+# and replace all placeholder values with actual secrets.
+#
+# HIPAA: This file template is safe to commit.
+# Actual .env.production must NEVER be committed.
+# ============================================================
+
+# Build Configuration
+NODE_ENV=production
+ELECTRON_DEV=0
+
+# Database Encryption
+# The encryption key is auto-generated on first run.
+# Override only if migrating from another installation.
+# TRANSTRACK_DB_KEY=<64-char-hex-string>
+
+# EHR Integration (if using bidirectional FHIR sync)
+# EHR_WEBHOOK_SECRET=<generate-with: openssl rand -hex 32>
+# EHR_API_KEY_<integration_id>=<bearer-token-from-ehr-vendor>
+
+# Code Signing (for electron-builder)
+# CSC_LINK=<path-to-certificate.p12>
+# CSC_KEY_PASSWORD=<certificate-password>
+
+# Update Server (if using auto-updates)
+# UPDATE_SERVER_URL=https://releases.yourcompany.com/
+
+# Logging
+# LOG_LEVEL=info
+# LOG_DIR=<custom-log-directory>
+
+# Data Residency
+# DATA_RESIDENCY_REGION=US

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Rebuild native modules for CI Node version
         run: npm rebuild better-sqlite3-multiple-ciphers
 
-      - run: npm audit || true
+      - run: npm audit --omit=dev || true
 
       - run: npm run lint || true
 

.github/workflows/security.yml

@@ -5,22 +5,159 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  schedule:
+    - cron: '0 6 * * 1'
   workflow_dispatch:
 
+permissions:
+  contents: read
+  statuses: write
+
 jobs:
   audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: npm ci --ignore-scripts
+
+      - name: Production dependency audit (fail on moderate+)
+        run: npm audit --omit=dev --audit-level=moderate
+
+      - name: Full dependency audit (informational)
+        run: npm audit || true
+
+      - name: Check for outdated dependencies
+        run: npm outdated || true
+
+  snyk:
+    name: Snyk Vulnerability Scan
+    runs-on: ubuntu-latest
+    if: github.event_name != 'schedule'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: npm ci --ignore-scripts
+
+      - name: Run Snyk to check for vulnerabilities
+        uses: snyk/actions/node@master
+        continue-on-error: true
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          args: --severity-threshold=high
+
+  lint:
+    name: Lint & Static Analysis
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      
+
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
-
-      - run: npm install --ignore-scripts
-
-      - run: npm audit || true
-
-      - run: npm outdated || true
-
-      - run: npm run lint || true
+
+      - run: npm ci --ignore-scripts
+
+      - name: Run ESLint
+        run: npm run lint
+
+  test-security:
+    name: Security Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y python3 make g++
+
+      - run: npm install
+
+      - name: Rebuild native modules
+        run: npm rebuild better-sqlite3-multiple-ciphers
+
+      - name: Run cross-org access tests
+        run: npm run test:security
+
+      - name: Run business logic tests
+        run: npm run test:business
+
+      - name: Run compliance validation tests
+        run: npm run test:compliance
+
+  load-test:
+    name: Performance Load Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y python3 make g++
+
+      - run: npm install
+
+      - name: Rebuild native modules
+        run: npm rebuild better-sqlite3-multiple-ciphers
+
+      - name: Run load tests
+        run: npm run test:load
+
+  lockfile-check:
+    name: Lockfile Integrity
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Verify lockfile is committed
+        run: |
+          if [ ! -f package-lock.json ]; then
+            echo "::warning::package-lock.json is not committed. Dependency pinning is recommended."
+          fi
+
+      - name: Verify clean install matches lockfile
+        run: npm ci --ignore-scripts
+
+  report-audit-status:
+    name: Report audit status
+    runs-on: ubuntu-latest
+    needs: audit
+    if: always()
+    steps:
+      - name: Set audit commit status
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const state = '${{ needs.audit.result }}' === 'success' ? 'success' : 'failure';
+            const sha = context.payload.pull_request
+              ? context.payload.pull_request.head.sha
+              : context.sha;
+            await github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha,
+              state,
+              context: 'audit',
+              description: `Dependency audit ${state}`,
+              target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
+            });

.gitignore

@@ -1,6 +1,7 @@
 # Dependencies
 node_modules/
-package-lock.json
+# Note: package-lock.json SHOULD be committed for reproducible builds.
+# It was previously gitignored. Remove this entry when ready to pin dependencies.
 
 # Build outputs
 dist/
@@ -21,6 +22,7 @@ out/
 # Environment files
 .env
 .env.local
+.env.production
 .env.*.local
 
 # IDE and editor files

SECURITY.md

@@ -1,42 +1,138 @@
-# Security Policy
+# Security Architecture & Implementation
+
+## Reporting a Security Issue
+
+**Email**: Trans_Track@outlook.com
+
+**Please include**: Description, steps to reproduce, potential impact, and suggested fixes.
+
+**Response Timeline**:
+- Acknowledgment: Within 48 hours
+- Initial assessment: Within 1 week
+- Resolution target: Based on severity (Critical: 24h, High: 72h, Medium: 1 week, Low: 30 days)
 
 ## Supported Versions
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.0.x   | Yes                |
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | Yes       |
 
-## Reporting a Security Issue
+---
 
-We take security seriously, especially given the healthcare context of TransTrack.
+## Threat Model
 
-**To report a security issue:**
+### Assets Protected
+1. **Patient PHI** — Names, MRNs, diagnoses, blood types, medical scores, contact info
+2. **Donor Information** — Organ details, HLA typing, compatibility data
+3. **Match Results** — Donor-patient matching scores and rankings
+4. **Audit Logs** — Immutable record of all system activity
+5. **Encryption Keys** — Database encryption key material
 
-Email: Trans_Track@outlook.com
+### Threats Addressed
 
-**Please include:**
-- Description of the issue
-- Steps to reproduce
-- Potential impact
-- Any suggested fixes
+| # | Threat | Mitigation | Status |
+|---|--------|------------|--------|
+| T1 | **Unauthorized Data Access** | AES-256-CBC local encryption (SQLCipher), role-based access control | ✅ |
+| T2 | **Data Exfiltration** | Offline-first architecture, no cloud PHI transmission, data residency controls | ✅ |
+| T3 | **SQL Injection** | Parameterized queries, column whitelisting (shared.cjs) | ✅ |
+| T4 | **Cross-Site Scripting (XSS)** | CSP headers, patient name sanitization in notifications and FHIR exports | ✅ |
+| T5 | **Session Hijacking** | Server-side session management with expiration, context isolation | ✅ |
+| T6 | **Privilege Escalation** | Organization isolation at query layer, role enforcement in all handlers | ✅ |
+| T7 | **Brute Force Login** | Account lockout after 5 failed attempts, bcrypt password hashing (12 rounds) | ✅ |
+| T8 | **Cross-Organization Access** | Hard org_id scoping on all queries, tested via cross-org access tests | ✅ |
+| T9 | **Audit Log Tampering** | SQLite triggers prevent UPDATE/DELETE on audit_logs table | ✅ |
+| T10 | **DevTools Exploitation** | DevTools disabled in production, blocked via event listener | ✅ |
+| T11 | **License Bypass** | Fail-closed license checking, clock-skew protection | ✅ |
+| T12 | **Medical Score Manipulation** | Input validation against UNOS/OPTN ranges (MELD 6-40, LAS 0-100, etc.) | ✅ |
+| T13 | **Race Conditions** | Patient freshness re-check before match creation | ✅ |
 
-**Response Timeline:**
-- Acknowledgment: Within 48 hours
-- Initial assessment: Within 1 week
-- Resolution target: Based on severity
+### Threats NOT Addressed (Out of Scope)
+
+| Threat | Reason | Recommendation |
+|--------|--------|---------------|
+| Physical device theft | Desktop app responsibility of deploying org | Use full-disk encryption (BitLocker/FileVault) |
+| OS-level keyloggers | Outside application boundary | Endpoint detection and response (EDR) |
+| Memory dump attacks | Electron limitation | Use hardware security modules for key storage |
+| Network-level MITM | Only relevant for EHR integration | Use TLS 1.3 for all EHR endpoints |
 
-## Security Features
+## Security Architecture
 
-TransTrack includes:
-- AES-256 encrypted local database
-- Role-based access control
-- Immutable audit logging
-- Session management
-- No external network transmission of PHI
+### Defense in Depth Layers
+
+```
+┌─────────────────────────────────────┐
+│  Layer 1: Electron Security          │
+│  - Context isolation                 │
+│  - CSP headers                       │
+│  - No nodeIntegration                │
+│  - Navigation blocking               │
+│  - DevTools disabled in production   │
+├─────────────────────────────────────┤
+│  Layer 2: Authentication             │
+│  - bcrypt password hashing           │
+│  - Session management                │
+│  - Account lockout                   │
+│  - Password strength requirements    │
+├─────────────────────────────────────┤
+│  Layer 3: Authorization              │
+│  - Role-based access control         │
+│  - Organization isolation            │
+│  - License enforcement               │
+│  - Feature gating                    │
+├─────────────────────────────────────┤
+│  Layer 4: Data Protection            │
+│  - AES-256-CBC encryption at rest    │
+│  - Input validation                  │
+│  - Output sanitization               │
+│  - Parameterized SQL queries         │
+├─────────────────────────────────────┤
+│  Layer 5: Audit & Monitoring         │
+│  - Immutable audit logs              │
+│  - Structured error logging          │
+│  - Request ID tracking               │
+│  - Compliance report generation      │
+└─────────────────────────────────────┘
+```
+
+### IPC Security Model
+
+All renderer-to-main communication uses Electron's IPC:
+- **contextBridge** exposes a minimal, typed API to the renderer
+- All IPC handlers validate session, check organization scope, and enforce license limits
+- Entity operations are scoped by `org_id` at the query level
+- Rate limiting prevents abuse (configurable per handler)
+
+### Password Policy
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum length | 12 characters |
+| Uppercase required | Yes |
+| Lowercase required | Yes |
+| Number required | Yes |
+| Special character required | Yes |
+| Hash algorithm | bcrypt |
+| Hash rounds | 12 |
+| Account lockout threshold | 5 failed attempts |
 
 ## Compliance
 
-TransTrack is designed for:
-- HIPAA Technical Safeguards
-- FDA 21 CFR Part 11
-- AATB Standards
+TransTrack is designed for compliance with:
+- **HIPAA** — Health Insurance Portability and Accountability Act
+- **FDA 21 CFR Part 11** — Electronic Records and Signatures
+- **AATB Standards** — American Association of Tissue Banks
+
+See `docs/HIPAA_COMPLIANCE_MATRIX.md` for detailed function-level compliance mapping.
+
+## Dependencies
+
+Security-critical dependencies:
+- `better-sqlite3-multiple-ciphers` — SQLCipher encryption
+- `bcryptjs` — Password hashing
+- `uuid` — Unique identifier generation
+
+Run `npm run security:check` to audit dependencies for known vulnerabilities.
+
+---
+
+*Last updated: 2026-03-21*