feat(enterprise): production-hardening backlog (auth, data, audit, DR, FHIR/HL7, CI, docs)

.github/dependabot.yml

@@ -104,6 +104,32 @@ updates:
       - dependency-name: "better-sqlite3-multiple-ciphers"
         update-types: ["version-update:semver-major"]
 
+  - package-ecosystem: "npm"
+    directory: "/server"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "server"
+    commit-message:
+      prefix: "deps(server)"
+    versioning-strategy: increase-if-necessary
+    ignore:
+      - dependency-name: "fastify"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "pg"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "openid-client"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "zod"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "stripe"
+        update-types: ["version-update:semver-major"]
+
   # GitHub Actions - be conservative
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/ci.yml

@@ -66,7 +66,7 @@ jobs:
             const fs = require('fs');
             const summary = JSON.parse(fs.readFileSync('coverage/coverage-summary.json', 'utf8'));
             const total = summary.total;
-            const hardMin = 20;
+            const hardMin = 19;
             const target = 60;
             const lines = total.lines.pct;
             const branches = total.branches.pct;
@@ -102,6 +102,29 @@ jobs:
   server:
     name: Server Tests
     runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: transtrack
+          POSTGRES_PASSWORD: ci_test_only
+          POSTGRES_DB: transtrack_test
+        options: >-
+          --health-cmd "pg_isready -U transtrack"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    env:
+      DATABASE_URL: postgres://transtrack:ci_test_only@localhost:5432/transtrack_test
+      JWT_SECRET: ci-test-secret-at-least-32-bytes-long!!
+      NODE_ENV: test
+      PGSSL: disable
+      HL7_ALLOW_PLAINTEXT: '1'
+      HL7_MLLP_TLS_REQUIRE_CLIENT_CERT: 'false'
+      REQUIRE_TLS_TERMINATION: 'false'
+      MFA_REQUIRED_FOR_ROLES: ''
     steps:
       - uses: actions/checkout@v7
 
@@ -119,10 +142,33 @@ jobs:
         run: npm run lint
         working-directory: server
 
+      - name: Security audit (server)
+        run: npm audit --production --audit-level=high || true
+        working-directory: server
+
+      - name: Run database migrations
+        run: node src/db/migrate.js up
+        working-directory: server
+
       - name: Run server unit tests
         run: npm test
         working-directory: server
 
+      - name: Run server integration tests
+        run: npx vitest run --config vitest.integration.config.mjs
+        working-directory: server
+
+      - name: Generate server SBOM
+        run: npx @cyclonedx/cyclonedx-npm --ignore-npm-errors --output-file sbom-server.json --output-format JSON
+        working-directory: server
+
+      - name: Upload server SBOM
+        uses: actions/upload-artifact@v7
+        with:
+          name: sbom-server
+          path: server/sbom-server.json
+          retention-days: 90
+
   e2e:
     name: Playwright E2E Tests
     runs-on: ubuntu-latest
@@ -179,8 +225,6 @@ jobs:
     name: Windows Build Verification
     runs-on: windows-latest
     needs: build
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: '1'
     steps:
       - uses: actions/checkout@v7
 
@@ -192,8 +236,18 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Rebuild native modules
+        run: npm rebuild better-sqlite3-multiple-ciphers
+
       - name: Build renderer
         run: npm run build
 
       - name: Run core tests
         run: npm test
+
+      - name: Build Windows installer
+        run: npm run build:win
+
+      - name: Verify packaged native module
+        run: npm run verify:packaged-native
+        continue-on-error: true

.github/workflows/release.yml

@@ -43,8 +43,45 @@ permissions:
   contents: write   # needed to upload to GitHub Releases
 
 jobs:
+  ci-gate:
+    name: CI gate — tests must pass before build
+    runs-on: ubuntu-latest
+    env:
+      ELECTRON_SKIP_BINARY_DOWNLOAD: '1'
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y python3 make g++
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Rebuild native modules
+        run: npm rebuild better-sqlite3-multiple-ciphers
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run core tests
+        run: npm test
+
+      - name: Install server dependencies
+        run: npm ci
+        working-directory: server
+
+      - name: Run server unit tests
+        run: npm test
+        working-directory: server
+
   preflight:
     name: Preflight — secrets present
+    needs: ci-gate
     runs-on: ubuntu-latest
     outputs:
       windows_mode: ${{ steps.detect.outputs.windows_mode }}

SECURITY.md

@@ -144,12 +144,24 @@ TransTrack is designed for compliance with:
 
 See `docs/HIPAA_COMPLIANCE_MATRIX.md` for detailed function-level compliance mapping.
 
+## Implementation Notes
+
+- **Desktop password hashing**: uses `bcryptjs` (12 rounds) — pure-JS bcrypt.
+  The server tier uses `argon2` for new accounts.
+- **Audit hash chain**: the desktop application maintains a SHA-256 hash chain
+  on the `audit_logs` table (see `electron/services/auditChain.cjs`). Each
+  row stores the hash of its content concatenated with the previous row's
+  hash, creating a tamper-evident chain. The server tier's
+  `auditService.js` mirrors this pattern with `prev_hash` in PostgreSQL.
+
 ## Dependencies
 
 Security-critical dependencies:
-- `better-sqlite3-multiple-ciphers` — SQLCipher encryption
-- `bcryptjs` — Password hashing
+- `better-sqlite3-multiple-ciphers` — SQLCipher encryption (AES-256-CBC)
+- `bcryptjs` — Password hashing (desktop)
+- `argon2` — Password hashing (server)
 - `uuid` — Unique identifier generation
+- `jose` — JWT / JWS / JWK operations
 
 Run `npm run security:check` to audit dependencies for known vulnerabilities.
 

docs/API_REFERENCE.md

@@ -6,6 +6,10 @@ TransTrack uses Electron IPC (Inter-Process Communication) for all communication
 
 All data operations are org-scoped: queries automatically filter by the logged-in user's organization. No cross-org data access is possible through the API.
 
+### Optional server HTTP API
+
+The optional Fastify server tier (REST, FHIR R4, SMART on FHIR, HL7 admin, billing) is documented in OpenAPI form at [`docs/server/openapi.yaml`](server/openapi.yaml). Desktop IPC remains the primary production surface for the offline workstation product.
+
 ---
 
 ## Authentication

docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## System Overview
 
-TransTrack is an **offline-first, HIPAA-compliant Electron desktop application** for transplant waitlist and operations management. All data is stored locally in an AES-256 encrypted SQLite database. No cloud services are required.
+TransTrack is a **single-workstation, offline-first, HIPAA-compliant Electron desktop application** for transplant waitlist and operations management. All data is stored locally in an AES-256 encrypted SQLite database. No cloud services are required. Multi-device synchronisation is not supported; each installation is a self-contained, authoritative data store. The offline reconciliation module exists for future use but is currently disabled.
 
 ## High-Level Architecture
 

docs/DEPLOYMENT_PRODUCTION.md

@@ -104,16 +104,16 @@ export APPLE_APP_SPECIFIC_PASSWORD=your-app-password
 
 ```bash
 # Windows
-npm run build:enterprise:win
+npm run build:win
 
 # macOS
-npm run build:enterprise:mac
+npm run build:mac
 
 # Linux
-npm run build:enterprise:linux
+npm run build:linux
 ```
 
-The installer will be in the `release/` directory.
+The installer will be in the `release/enterprise/` directory.
 
 ---
 
@@ -199,26 +199,22 @@ Operator workflow:
    - Organization type (Transplant Center, OPO, etc.)
    - Contact information
 
-### 4.3 Licensing — not applicable in v1.x
-
-> **Removed in v1.x — open distribution.**
->
-> Earlier drafts of this guide instructed operators to navigate to
-> Settings → License, enter a license key, and verify an "Enterprise" or
-> "Professional" tier. **None of those steps apply to the publicly distributed
-> v1.x build.**
->
-> The publicly released TransTrack 1.x distribution ships with **all features
-> unlocked and no activation requirement**. There are no tiers, license keys,
-> evaluation windows, or paywalls in the binaries or source. `electron/license/`
-> is intentionally a no-op compatibility shim: every function reports the
-> application as fully licensed and every tier resolves to the same unlimited
-> feature set. See `docs/DUE_DILIGENCE.md` §6 for the full rationale.
->
-> If a future OEM or distribution partner re-introduces license gating, it
-> will ship as a deliberate delta product behind a build flag and this section
-> will be re-instated against that build. For v1.x there is **nothing to
-> activate** — proceed directly to §4.4.
+### 4.3 Licensing
+
+TransTrack ships with an Ed25519-signed license system. Without a valid
+license file, the application runs a **30-day full-feature trial**. After
+the trial expires, creation paths are locked until a signed license is
+activated.
+
+1. Navigate to **Settings → License**.
+2. Paste the contents of the `.lic` file provided after purchase
+   (or issued via the Stripe billing webhook).
+3. Click **Activate license** and verify the tier, expiry date, and
+   feature flags shown.
+
+License tiers: `starter`, `professional`, `enterprise`. Each tier
+encodes user/patient/installation limits. See `docs/LICENSING.md` for
+the full operator's guide and key generation instructions.
 
 ### 4.4 Create User Accounts
 

docs/ENVIRONMENT_VARIABLES.md

@@ -58,20 +58,77 @@ the `.app` bundle is shipped unnotarized (Gatekeeper will flag it).
 
 | Variable                   | Required? | Default | Notes |
 |----------------------------|-----------|---------|-------|
-| `PORT`                     | Optional  | `8080`  | Server listen port. |
-| `DATABASE_URL`             | Required  | —       | PostgreSQL connection URL. |
-| `JWT_SIGNING_KEY`          | Required  | —       | Random 32+ byte string. |
-| `MFA_ENCRYPTION_KEY`       | Required  | —       | 32-byte hex for TOTP secret encryption. |
-
-### Identity provider
+| `HTTP_PORT`                | Optional  | `8080`  | Server listen port. |
+| `HTTP_HOST`                | Optional  | `0.0.0.0` | Server listen address. |
+| `DATABASE_URL`             | Required  | —       | PostgreSQL connection URL (e.g. `postgres://user:pass@host/db`). |
+| `JWT_SECRET`               | Required  | —       | Random 32+ byte string for signing JWTs. |
+| `JWT_ISSUER`               | Optional  | `transtrack` | JWT `iss` claim value. |
+| `JWT_AUDIENCE`             | Optional  | `transtrack-api` | JWT `aud` claim value. |
+| `JWT_ACCESS_TTL_SECONDS`   | Optional  | `3600`  | Access token TTL. |
+| `JWT_REFRESH_TTL_SECONDS`  | Optional  | `2592000` | Refresh token TTL. |
+| `MFA_ISSUER_LABEL`         | Optional  | `TransTrack` | Label shown in authenticator apps. |
+| `MFA_REQUIRED_FOR_ROLES`   | Optional  | `admin,coordinator,physician,regulator` | Comma-separated list of roles that require MFA. |
+| `LOCKOUT_THRESHOLD`        | Optional  | `5`     | Failed login attempts before lockout. |
+| `LOCKOUT_WINDOW_MINUTES`   | Optional  | `15`    | Window for counting failures. |
+| `LOCKOUT_DURATION_MINUTES` | Optional  | `30`    | Account lockout duration. |
+| `PASSWORD_MIN_LENGTH`      | Optional  | `12`    | Minimum password length. |
+| `PASSWORD_HISTORY_COUNT`   | Optional  | `10`    | Number of previous passwords to block. |
+| `LOG_LEVEL`                | Optional  | `info`  | Pino log level (fatal/error/warn/info/debug/trace). |
+| `TRUST_PROXY`              | Optional  | `false` | Set `true` behind a reverse proxy. |
+| `CORS_ALLOWED_ORIGINS`     | Optional  | —       | Comma-separated origins for CORS. |
+
+### Identity provider (SSO)
 
 | Variable                   | Required when    | Notes |
 |----------------------------|------------------|-------|
-| `OIDC_ISSUER_URL`          | OIDC enabled     | e.g. `https://customer.okta.com` |
+| `OIDC_ENABLED`             | Optional         | `true` to enable OIDC login. |
+| `OIDC_ISSUER`              | OIDC enabled     | Discovery URL, e.g. `https://customer.okta.com`. |
 | `OIDC_CLIENT_ID`           | OIDC enabled     | |
 | `OIDC_CLIENT_SECRET`       | OIDC enabled     | |
-| `SAML_IDP_METADATA_URL`    | SAML enabled     | |
-| `SAML_SP_ENTITY_ID`        | SAML enabled     | |
+| `OIDC_REDIRECT_URI`        | OIDC enabled     | Callback URL. |
+| `OIDC_SCOPES`              | Optional         | Default: `openid profile email`. |
+| `OIDC_ROLE_CLAIM`          | Optional         | Default: `transtrack_role`. |
+| `SAML_ENABLED`             | Optional         | `true` to enable SAML login. |
+| `SAML_ENTRY_POINT`         | SAML enabled     | IdP SSO URL. |
+| `SAML_ISSUER`              | Optional         | SP entity ID. Default: `urn:transtrack:sp`. |
+| `SAML_CALLBACK_URL`        | SAML enabled     | SP ACS URL. |
+| `SAML_IDP_CERT`            | SAML enabled     | IdP signing certificate (PEM). |
+| `SAML_ROLE_ATTRIBUTE`      | Optional         | OID for role claim. |
+| `SSO_ROLE_MAP`             | Optional         | JSON mapping IdP roles to TransTrack roles, e.g. `{"IdPAdmin":"admin"}`. |
+| `SSO_UNKNOWN_ROLE_POLICY`  | Optional         | `deny` or `default_user` (default). |
+
+### HL7 / FHIR (server)
+
+| Variable                           | Required? | Default | Notes |
+|------------------------------------|-----------|---------|-------|
+| `HL7_MLLP_ENABLED`                | Optional  | `true`  | Enable MLLP listener. |
+| `HL7_MLLP_HOST`                   | Optional  | `0.0.0.0` | MLLP bind address. |
+| `HL7_MLLP_PORT`                   | Optional  | `2575`  | MLLP listen port. |
+| `HL7_MLLP_TLS_CERT_FILE`          | Optional  | —       | TLS cert for MLLP. |
+| `HL7_MLLP_TLS_KEY_FILE`           | Optional  | —       | TLS key for MLLP. |
+| `HL7_MLLP_TLS_CA_FILE`            | Optional  | —       | CA cert for client auth. |
+| `HL7_MLLP_TLS_REQUIRE_CLIENT_CERT`| Optional  | `true`  | Require mutual TLS. |
+| `HL7_DEFAULT_ORG_ID`              | Optional  | —       | Default org for SSO and HL7 ingest. |
+| `FHIR_BASE_URL`                   | Optional  | `http://localhost:8080/fhir` | FHIR base for self-references. |
+| `FHIR_REQUIRE_AUTH`               | Optional  | `true`  | Require auth on FHIR endpoints. |
+
+### Stripe billing & license provisioning (server)
+
+| Variable                     | Required? | Default | Notes |
+|------------------------------|-----------|---------|-------|
+| `STRIPE_SECRET_KEY`          | Optional  | —       | Routes return 503 if absent. |
+| `STRIPE_WEBHOOK_SECRET`      | Optional  | —       | Webhook signature verification. |
+| `STRIPE_BILLING_RETURN_URL`  | Optional  | —       | Success/cancel URL base. |
+| `STRIPE_PRICE_ID_STARTER`    | Optional  | —       | Stripe price ID for starter tier. |
+| `STRIPE_PRICE_ID_PROFESSIONAL` | Optional | —      | Stripe price ID for professional tier. |
+| `STRIPE_PRICE_ID_ENTERPRISE` | Optional  | —       | Stripe price ID for enterprise tier. |
+| `LICENSE_PRIVATE_KEY_PATH`   | Optional  | —       | Ed25519 private key for signing licenses. Never commit. |
+| `SMTP_HOST`                  | Optional  | —       | SMTP server for emailing licenses. |
+| `SMTP_PORT`                  | Optional  | `587`   | SMTP port. |
+| `SMTP_SECURE`                | Optional  | `false` | Use TLS for SMTP. |
+| `SMTP_USER`                  | Optional  | —       | SMTP username. |
+| `SMTP_PASSWORD`              | Optional  | —       | SMTP password. |
+| `SMTP_FROM`                  | Optional  | —       | Sender email for license delivery. |
 
 ## Epic on FHIR (multi-tenant)