@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/healthcare-hipaa-backend/manifest.json

@@ -0,0 +1,138 @@
+{
+  "id": "healthcare-hipaa-backend",
+  "description": "HIPAA-aligned healthcare API framework layer — Drizzle schema (patients, encounters, providers, immutable audit_logs), PHI field-level encryption, PHI-access middleware.",
+  "appliesTo": ["healthcare-hipaa-backend"],
+  "files": [
+    {
+      "source": "files/package.json",
+      "target": "package.json"
+    },
+    {
+      "source": "files/tsconfig.json",
+      "target": "tsconfig.json"
+    },
+    {
+      "source": "files/server.ts",
+      "target": "src/server.ts"
+    },
+    {
+      "source": "files/schema.ts",
+      "target": "src/db/schema.ts"
+    },
+    {
+      "source": "files/db.ts",
+      "target": "src/db/client.ts"
+    },
+    {
+      "source": "files/encryption.ts",
+      "target": "src/encryption.ts"
+    },
+    {
+      "source": "files/phi-access.ts",
+      "target": "src/api/phi-access.ts"
+    },
+    {
+      "source": "files/patients.ts",
+      "target": "src/api/patients.ts"
+    },
+    {
+      "source": "files/encounters.ts",
+      "target": "src/api/encounters.ts"
+    },
+    {
+      "source": "files/drizzle.config.ts",
+      "target": "drizzle.config.ts"
+    },
+    {
+      "source": "files/hipaa.md",
+      "target": "config/hipaa.md"
+    }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "drizzle-orm": "^0.36.0",
+      "postgres": "^3.4.5"
+    },
+    "devDependencies": {
+      "drizzle-kit": "^0.30.0",
+      "typescript": "^5.9.0",
+      "@types/node": "^20.17.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Healthcare products, clinical platforms, patient portals, EHR/EMR integrations, or any service that stores or transmits Protected Health Information (PHI) and requires HIPAA-compliant infrastructure from day one.",
+    "firstSteps": [
+      "Run `pnpm install` then set `DATABASE_URL` (postgres://...) and `PHI_ENCRYPTION_KEY` (64-char hex: `node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"`).",
+      "Run `pnpm db:generate && pnpm db:migrate` to create the patients, encounters, providers, and audit_logs tables.",
+      "Start the server with `pnpm dev` — it listens on port 8100. `GET /health` should return `{\"status\":\"ok\"}`.",
+      "All `/api/*` routes require `X-Actor-Id` and `X-Actor-Role` headers; wire in your real auth layer (better-auth or Clerk slot) before storing real PHI.",
+      "Run `node validate-hipaa.mjs` to verify all required HIPAA controls are present."
+    ],
+    "apiRoutes": [
+      "GET /health",
+      "GET /api/patients/:id (authn + audit-logged PHI read)",
+      "POST /api/patients (authn, PHI encrypted at rest)",
+      "GET /api/encounters/:id",
+      "POST /api/encounters"
+    ],
+    "dataModels": [
+      "Patient (mrn, encryptedName, encryptedDob, encryptedSsn, sex, createdAt)",
+      "Provider (npi, name, specialty, createdAt)",
+      "Encounter (patientId, providerId, encounteredAt, encryptedNotes, cptCode, icd10Codes)",
+      "AuditLog (actorId, action, resourceType, resourceId, occurredAt, reason) — append-only"
+    ],
+    "integrations": [
+      "Drizzle ORM with Postgres",
+      "Node crypto (AES-256-GCM) for field-level PHI encryption",
+      "Append-only audit_logs via trigger / INSERT-only grants"
+    ],
+    "architectureNotes": [
+      "PHI is never stored in plaintext — encrypted columns use AES-256-GCM with per-record IV",
+      "Every PHI read goes through phi-access middleware which writes an AuditLog row BEFORE returning data",
+      "audit_logs is append-only: no UPDATE/DELETE grants in production; enforced by Postgres trigger",
+      "Encryption key comes from PHI_ENCRYPTION_KEY env — in production this lives in a KMS (AWS KMS, GCP KMS, HashiCorp Vault)"
+    ],
+    "gotchas": [
+      "NEVER log PHI to stdout, stderr, files, or APM traces — logging middleware must redact patient.name, patient.dob, encounter.notes. Console.log of a Patient row is a HIPAA breach.",
+      "A BAA (Business Associate Agreement) with every subprocessor (cloud provider, email, analytics, error tracking) is REQUIRED before storing real PHI. Test data only until BAAs are executed.",
+      "audit_logs must be append-only. Do NOT add .update() / .delete() helpers on the AuditLog table — the whole point is tamper-evidence.",
+      "AES-256-GCM requires a UNIQUE IV per encryption. Reusing IV + key on different plaintexts breaks confidentiality. The helper generates a random 12-byte IV per field.",
+      "Don't store the encryption key in the database, source code, or the same secret store as the DB creds. Key compromise + DB compromise = total PHI exposure.",
+      "HIPAA minimum-necessary rule: API responses must filter fields based on the caller's role. A billing user doesn't need to see encounter.notes.",
+      "PHI must be encrypted in transit — TLS 1.2+ only. Disable HTTP. Disable weak ciphers.",
+      "Audit log retention is 6 years minimum under HIPAA. Lifecycle policy on object storage, NOT ad-hoc deletes."
+    ],
+    "placeholders": [
+      {
+        "path": "src/api/phi-access.ts",
+        "description": "resolveActor reads X-Actor-Id / X-Actor-Role headers as a stub. Replace with your real auth layer (Clerk, better-auth, mTLS) before storing real PHI."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm dev",
+      "pnpm typecheck",
+      "pnpm db:generate",
+      "pnpm db:migrate",
+      "pnpm validate"
+    ],
+    "entrypoints": [
+      "src/server.ts",
+      "src/db/schema.ts",
+      "src/encryption.ts",
+      "src/api/phi-access.ts",
+      "config/hipaa.md"
+    ],
+    "preview": {
+      "path": "/health"
+    },
+    "extensionPoints": [
+      "src/db/schema.ts",
+      "src/api/",
+      "src/api/phi-access.ts",
+      "config/hipaa.md"
+    ]
+  }
+}

package/registry/layers/framework/hipaa-compliance-pack/files/AGENTS.md

@@ -0,0 +1,39 @@
+# HIPAA Compliance Pack — Agent Guide
+
+## What this pack provides
+
+Three TypeScript modules implementing the HIPAA Security Rule technical safeguards (45 CFR §164.312):
+
+| File | Purpose |
+|------|---------|
+| `src/encryption.ts` | AES-256-GCM field-level encryption — `encryptPhi`, `decryptPhi`, `generatePhiKey` |
+| `src/phi-access.ts` | `withPhiAccess` audit wrapper + `filterByMinimumNecessary` role filter (§164.502(b)) |
+| `src/audit-log.ts` | Append-only audit log — `AuditStore` interface, `InMemoryAuditStore`, `AuditEntry` type |
+| `docs/HIPAA-controls.md` | §164.312 control-to-file mapping |
+| `docs/BAA-template.md` | Business Associate Agreement template (legal review required before use) |
+| `validate-hipaa-pack.mjs` | Structural validation — run `pnpm validate` → `"hipaa-pack ok"` |
+
+## First steps after `pnpm install`
+
+1. **Run `pnpm validate`** — confirms required files and key exports are present.
+2. **Run `pnpm build`** — `tsc --noEmit` typechecks the full pack; zero errors expected.
+3. **Wire `withPhiAccess`** from `src/phi-access.ts` onto every route that reads or writes PHI — the audit row MUST be emitted BEFORE the response returns.
+4. **Wire `encryptPhi` / `decryptPhi`** from `src/encryption.ts` on every column storing SSN, DOB, MRN, or free-text clinical notes. Supply a 32-byte key from KMS/Vault — never from env vars in production.
+5. **Replace `InMemoryAuditStore`** with a DB-backed append-only store before going to production. The `audit_logs` table must deny UPDATE/DELETE at the DB level (§164.312(c)(2)).
+6. **Extend `DEFAULT_PHI_POLICY`** in `src/phi-access.ts` with the product's actual routes and roles.
+7. **Emit `docs/BAA-template.md`** as a signed document before production PHI lands — gate the production API behind a signed-BAA state flag.
+
+## Key invariants (do not break)
+
+- `withPhiAccess` calls `store.append(...)` BEFORE invoking the handler — a silently dropped audit row is a §164.312(b) violation.
+- Never log PHI values to stdout, JSON logs, or error traces. Pass every logger through a PHI-redaction filter.
+- `filterByMinimumNecessary` must run server-side — returning the full row and letting the client discard fields is a §164.502(b) violation.
+- Audit retention ≥ 6 years per §164.316(b)(2)(i) — do not TTL audit rows.
+- The AES-GCM auth tag detects tampering. If `decryptPhi` throws `PhiEncryptionError`, treat it as a security event, not a normal error.
+
+## Validation
+
+```bash
+pnpm validate   # node validate-hipaa-pack.mjs → "hipaa-pack ok"
+pnpm build      # tsc --noEmit → exit 0
+```

package/registry/layers/framework/hipaa-compliance-pack/files/docs/BAA-template.md

@@ -0,0 +1,60 @@
+# Business Associate Agreement — Template
+
+> **This is a template, not legal advice.** Your legal team MUST review and
+> customize before execution. This document exists so product teams have a
+> starting point — do not ship it as-is.
+
+## Parties
+
+- **Covered Entity**: [Name, address, Tax ID]
+- **Business Associate**: [Name, address, Tax ID]
+- **Effective Date**: [Date]
+
+## 1. Definitions
+
+Terms used but not defined have the meaning assigned in 45 CFR Part 160
+and Part 164 (the HIPAA Rules).
+
+## 2. Permitted uses and disclosures
+
+Business Associate may use or disclose PHI:
+
+- To perform the services described in the underlying Services Agreement.
+- For the proper management and administration of Business Associate's business.
+- To provide data aggregation services relating to the health care operations of the Covered Entity.
+
+All other uses and disclosures are prohibited.
+
+## 3. Business Associate obligations
+
+Business Associate agrees to:
+
+- Not use or disclose PHI other than as permitted by this agreement or as required by law.
+- Use appropriate safeguards, including technical safeguards under §164.312.
+- Report to the Covered Entity any use or disclosure not provided for by this agreement within [5] business days of discovery.
+- Ensure any subcontractors that create, receive, maintain, or transmit PHI on behalf of Business Associate agree to the same restrictions and conditions.
+- Make PHI available to the Covered Entity as required for §164.524 (access), §164.526 (amendment), and §164.528 (accounting of disclosures).
+- At termination, return or destroy all PHI received from the Covered Entity and retain no copies in any form.
+
+## 4. Security incident notification
+
+Business Associate shall notify the Covered Entity of any security incident
+of which it becomes aware within [2] business days. Security incident has
+the meaning set forth in §164.304.
+
+## 5. Breach notification
+
+Following the discovery of a breach of Unsecured PHI, Business Associate
+shall notify the Covered Entity without unreasonable delay and in no case
+later than 60 calendar days after discovery.
+
+## 6. Term and termination
+
+- **Term**: This agreement is effective as of the Effective Date and continues until all PHI is returned or destroyed.
+- **Termination for cause**: The Covered Entity may terminate upon 30 days notice for material breach uncured within that period.
+
+## Signatures
+
+Covered Entity: _____________________ Date: _______
+
+Business Associate: _____________________ Date: _______

package/registry/layers/framework/hipaa-compliance-pack/files/docs/HIPAA-controls.md

@@ -0,0 +1,58 @@
+# HIPAA Security Rule — Control Surface
+
+This pack implements the technical safeguards of the HIPAA Security Rule
+(45 CFR §164.312). Each control below maps to a file in this scaffold.
+Admin + physical safeguards (§164.308, §164.310) are process + infrastructure
+concerns outside the scope of this pack.
+
+## Technical safeguards covered
+
+| Citation | Control | Implementation |
+|---|---|---|
+| §164.312(a)(1) | Access control — unique user identification | `src/phi-access.ts` — audit row carries `actorUserId` + `actorRole` |
+| §164.312(a)(2)(i) | Emergency access procedure | Operational — document your break-glass process |
+| §164.312(a)(2)(iii) | Automatic logoff | Application-layer session timeout (middleware in your framework) |
+| §164.312(a)(2)(iv) | Encryption and decryption | `src/encryption.ts` — AES-256-GCM at column level |
+| §164.312(b) | Audit controls | `src/audit-log.ts` — append-only; `withPhiAccess` emits before response |
+| §164.312(c)(1) | Integrity controls | Audit tag (AES-GCM auth tag) + DB-level append-only constraint on `audit_logs` |
+| §164.312(d) | Person or entity authentication | Use your existing auth layer; pack requires `actorUserId` in every call |
+| §164.312(e)(1) | Transmission security | TLS 1.2+ on the network layer; not enforced at application level |
+| §164.312(e)(2)(i) | Integrity controls (transmission) | TLS + request signing where applicable |
+| §164.312(e)(2)(ii) | Encryption (transmission) | TLS required in production |
+
+## Administrative + physical pointers
+
+These live outside this pack but are required for compliance:
+
+- **§164.316(b)(2)(i)** — Retention: documentation ≥ 6 years. Applies to audit logs + policies. Plan storage accordingly.
+- **§164.316(a)** — Policies and procedures: you need a written Security Management Process. This is PROSE, not code.
+- **§164.308(a)(1)(ii)(A)** — Risk analysis: document + date + sign. Repeat at least annually.
+- **§164.404** — Breach notification: 60-day clock from discovery. Incident-response playbook needed.
+
+## Minimum-necessary policy (§164.502(b))
+
+`src/phi-access.ts` exports `DEFAULT_PHI_POLICY` — a map of `table → role →
+allowed_fields`. Extend per product. The `filterByMinimumNecessary()`
+helper enforces it at the row-shape level so the API never leaks a field
+the caller's role shouldn't see.
+
+## De-identification (§164.514)
+
+Two methods are allowed:
+
+1. **Safe Harbor** — remove all 18 specified identifiers. Pack provides a
+   stub (`safeHarborRedact()`) — extend for free-text fields.
+2. **Expert Determination** — a qualified statistician attests there's
+   "very small" risk of re-identification. Requires a signed letter.
+
+Most products use Safe Harbor. If yours does, the redactor must run on
+every export + analytics path.
+
+## What this pack does NOT do
+
+- **Authentication**: bring your own (better-auth, clerk, custom JWT).
+- **DB-level append-only enforcement**: you must add a trigger or DENY the
+  UPDATE/DELETE privileges on the audit table at the DB user.
+- **TLS termination**: infra concern; use Cloudflare, AWS ALB, or your own.
+- **BAA signature storage**: `docs/BAA-template.md` is the template; store
+  signed copies wherever your legal team mandates.

package/registry/layers/framework/hipaa-compliance-pack/files/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "hipaa-compliance-pack",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc --noEmit",
+    "validate": "node validate-hipaa-pack.mjs"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/registry/layers/framework/hipaa-compliance-pack/files/src/audit-log.ts

@@ -0,0 +1,54 @@
+// Append-only audit log with PHI-redacted field enumeration. Every PHI
+// read/write emits one row. The row references PHI by (subject_table,
+// subject_id) — the audit entry itself contains NO PHI content.
+
+export type AuditAction = 'read' | 'create' | 'update' | 'delete' | 'export' | 'login' | 'logout'
+
+export interface AuditEntry {
+  id?: string
+  actorUserId: string
+  actorRole: string
+  action: AuditAction
+  subjectTable: string
+  subjectId: string
+  /** List of PHI field names accessed — NEVER the values. */
+  subjectFieldsAccessed: string[]
+  requestId?: string
+  clientIp?: string
+  at: string
+}
+
+export interface AuditStore {
+  append(entry: AuditEntry): Promise<void>
+  /** Required by §164.316(b)(2)(i) — retention ≥6 years. Stores must be append-only at the DB level. */
+  list(filter?: {
+    actorUserId?: string
+    subjectId?: string
+    action?: AuditAction
+    since?: string
+    until?: string
+  }): Promise<AuditEntry[]>
+}
+
+/** In-memory audit store for testing. Production stores must be append-only + retained ≥6 years. */
+export class InMemoryAuditStore implements AuditStore {
+  private entries: AuditEntry[] = []
+
+  async append(entry: AuditEntry): Promise<void> {
+    this.entries.push({ ...entry, id: entry.id ?? crypto.randomUUID() })
+  }
+
+  async list(filter?: Parameters<AuditStore['list']>[0]): Promise<AuditEntry[]> {
+    let out = [...this.entries]
+    if (filter?.actorUserId) out = out.filter((e) => e.actorUserId === filter.actorUserId)
+    if (filter?.subjectId) out = out.filter((e) => e.subjectId === filter.subjectId)
+    if (filter?.action) out = out.filter((e) => e.action === filter.action)
+    if (filter?.since) out = out.filter((e) => e.at >= filter.since!)
+    if (filter?.until) out = out.filter((e) => e.at <= filter.until!)
+    return out
+  }
+
+  size(): number {
+    return this.entries.length
+  }
+}

package/registry/layers/framework/hipaa-compliance-pack/files/src/encryption.ts

@@ -0,0 +1,74 @@
+// AES-256-GCM field-level encryption helpers — for PHI at rest in columns
+// like SSN, DOB, MRN, free-text clinical notes. Per-field IV (96-bit)
+// concatenated with the ciphertext so one encrypted value is self-contained.
+// Key management: the application supplies a 256-bit key via KMS / Vault —
+// NEVER from env vars on the filesystem for production workloads.
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+
+const ALGORITHM = 'aes-256-gcm'
+const IV_LENGTH = 12 // 96-bit IV is the AES-GCM standard.
+const TAG_LENGTH = 16 // 128-bit auth tag.
+const KEY_LENGTH = 32 // 256-bit key.
+
+export class PhiEncryptionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PhiEncryptionError'
+  }
+}
+
+function assertKey(key: Buffer): void {
+  if (key.length !== KEY_LENGTH) {
+    throw new PhiEncryptionError(`PHI encryption key must be ${KEY_LENGTH} bytes; got ${key.length}`)
+  }
+}
+
+/**
+ * Encrypt a plaintext string with AES-256-GCM.
+ * Returns base64url( iv || ciphertext || tag ) — self-contained, safe to
+ * store in a single column.
+ */
+export function encryptPhi(plaintext: string, key: Buffer): string {
+  assertKey(key)
+  const iv = randomBytes(IV_LENGTH)
+  const cipher = createCipheriv(ALGORITHM, key, iv)
+  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return Buffer.concat([iv, ciphertext, tag]).toString('base64url')
+}
+
+/**
+ * Decrypt a ciphertext produced by `encryptPhi`. Throws PhiEncryptionError
+ * on tag mismatch (tampering) or malformed input.
+ */
+export function decryptPhi(encoded: string, key: Buffer): string {
+  assertKey(key)
+  const buf = Buffer.from(encoded, 'base64url')
+  if (buf.length < IV_LENGTH + TAG_LENGTH + 1) {
+    throw new PhiEncryptionError('ciphertext shorter than IV + tag; corrupt or wrong encoding')
+  }
+  const iv = buf.subarray(0, IV_LENGTH)
+  const tag = buf.subarray(buf.length - TAG_LENGTH)
+  const ciphertext = buf.subarray(IV_LENGTH, buf.length - TAG_LENGTH)
+  const decipher = createDecipheriv(ALGORITHM, key, iv)
+  decipher.setAuthTag(tag)
+  try {
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()])
+    return plaintext.toString('utf8')
+  } catch (err) {
+    // GCM auth-tag verify fails → throw a class-level PhiEncryptionError so
+    // callers can distinguish from plaintext-level errors.
+    throw new PhiEncryptionError(
+      `PHI decryption failed (auth-tag mismatch — likely tampered or wrong key): ${(err as Error).message}`,
+    )
+  }
+}
+
+/**
+ * Generate a fresh 256-bit key (for key-generation tooling, NOT for per-request use).
+ * Production code must source the key from KMS / Vault and cache it in-memory.
+ */
+export function generatePhiKey(): Buffer {
+  return randomBytes(KEY_LENGTH)
+}

package/registry/layers/framework/hipaa-compliance-pack/files/src/phi-access.ts

@@ -0,0 +1,83 @@
+// withPhiAccess — wraps a PHI-returning handler so an audit row is emitted
+// BEFORE the response goes out. Covers §164.312(b) "record and examine
+// activity in information systems that contain or use electronic protected
+// health information."
+//
+// Shape is framework-agnostic. Adapters live in the consuming service
+// (Express, Fastify, Hono, Next.js route handler, etc.).
+
+import { randomUUID } from 'node:crypto'
+import type { AuditAction, AuditStore } from './audit-log.js'
+
+export interface PhiAccessContext {
+  actorUserId: string
+  actorRole: string
+  action: AuditAction
+  subjectTable: string
+  subjectId: string
+  subjectFieldsAccessed: string[]
+  requestId?: string
+  clientIp?: string
+}
+
+/**
+ * Wrap a handler so the audit row is written BEFORE the PHI payload leaves
+ * the process. If the audit-store write fails, the handler MUST reject the
+ * request — a silently-dropped audit row is a §164.312(b) violation.
+ */
+export function withPhiAccess<T>(
+  store: AuditStore,
+  context: PhiAccessContext,
+  handler: () => Promise<T>,
+): Promise<T> {
+  return (async () => {
+    await store.append({
+      actorUserId: context.actorUserId,
+      actorRole: context.actorRole,
+      action: context.action,
+      subjectTable: context.subjectTable,
+      subjectId: context.subjectId,
+      subjectFieldsAccessed: context.subjectFieldsAccessed,
+      requestId: context.requestId ?? randomUUID(),
+      clientIp: context.clientIp,
+      at: new Date().toISOString(),
+    })
+    return handler()
+  })()
+}
+
+/**
+ * Minimum-necessary role filter. Given a table of records, returns only the
+ * fields the actor's role is permitted to see. Required by §164.502(b).
+ */
+export type MinimumNecessaryPolicy = Record<string, Record<string, string[]>>
+
+export function filterByMinimumNecessary<T extends Record<string, unknown>>(
+  row: T,
+  actorRole: string,
+  subjectTable: string,
+  policy: MinimumNecessaryPolicy,
+): Partial<T> {
+  const allowed = policy[subjectTable]?.[actorRole] ?? []
+  const out: Partial<T> = {}
+  for (const field of allowed) {
+    if (field in row) (out as Record<string, unknown>)[field] = row[field as keyof T]
+  }
+  return out
+}
+
+/** Example baseline policy — extend per-product. */
+export const DEFAULT_PHI_POLICY: MinimumNecessaryPolicy = {
+  patients: {
+    attending_physician: ['id', 'name', 'dob', 'mrn', 'insurance_plan', 'allergies', 'current_medications'],
+    nurse: ['id', 'name', 'dob', 'mrn', 'allergies', 'current_medications'],
+    billing: ['id', 'name', 'dob', 'mrn', 'insurance_plan'],
+    scheduler: ['id', 'name', 'dob', 'mrn'],
+  },
+  encounters: {
+    attending_physician: ['id', 'patient_id', 'date', 'chief_complaint', 'diagnosis_codes', 'notes'],
+    nurse: ['id', 'patient_id', 'date', 'chief_complaint', 'vitals'],
+    billing: ['id', 'patient_id', 'date', 'cpt_codes', 'icd10_codes'],
+    scheduler: ['id', 'patient_id', 'date'],
+  },
+}

package/registry/layers/framework/hipaa-compliance-pack/files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "declaration": true,
+    "lib": ["ES2022"]
+  },
+  "include": ["src"]
+}

package/registry/layers/framework/hipaa-compliance-pack/files/validate-hipaa-pack.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+for (const rel of [
+  'src/encryption.ts',
+  'src/phi-access.ts',
+  'src/audit-log.ts',
+  'docs/HIPAA-controls.md',
+  'docs/BAA-template.md',
+  'tsconfig.json',
+]) {
+  if (!existsSync(join(here, rel))) throw new Error(`missing ${rel}`)
+}
+
+const enc = readFileSync(join(here, 'src/encryption.ts'), 'utf8')
+if (!enc.includes('aes-256-gcm')) throw new Error('encryption.ts does not use aes-256-gcm')
+if (!/IV_LENGTH\s*=\s*12/.test(enc)) throw new Error('encryption.ts IV_LENGTH must be 96-bit (12 bytes)')
+
+const phi = readFileSync(join(here, 'src/phi-access.ts'), 'utf8')
+if (!phi.includes('withPhiAccess')) throw new Error('phi-access.ts missing withPhiAccess export')
+if (!phi.includes('filterByMinimumNecessary')) throw new Error('phi-access.ts missing minimum-necessary filter')
+
+const audit = readFileSync(join(here, 'src/audit-log.ts'), 'utf8')
+if (!audit.includes('append-only')) throw new Error('audit-log.ts should document append-only semantics')
+
+const controls = readFileSync(join(here, 'docs/HIPAA-controls.md'), 'utf8')
+if (!/§164\.312/.test(controls)) throw new Error('HIPAA-controls.md missing §164.312 references')
+
+console.log('hipaa-pack ok')

package/registry/layers/framework/hipaa-compliance-pack/manifest.json

@@ -0,0 +1,56 @@
+{
+  "id": "hipaa-compliance-pack",
+  "description": "HIPAA compliance overlay — PHI audit trail, field-level AES-256-GCM helpers, role-based minimum-necessary middleware, BAA acknowledgment surface. Composes onto fullstack-ts / api-service / healthcare-hipaa-backend.",
+  "appliesTo": ["hipaa-compliance-pack"],
+  "files": [
+    { "source": "files/package.json", "target": "package.json" },
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/AGENTS.md", "target": "AGENTS.md" },
+    { "source": "files/src/encryption.ts", "target": "src/encryption.ts" },
+    { "source": "files/src/phi-access.ts", "target": "src/phi-access.ts" },
+    { "source": "files/src/audit-log.ts", "target": "src/audit-log.ts" },
+    { "source": "files/docs/HIPAA-controls.md", "target": "docs/HIPAA-controls.md" },
+    { "source": "files/docs/BAA-template.md", "target": "docs/BAA-template.md" },
+    { "source": "files/validate-hipaa-pack.mjs", "target": "validate-hipaa-pack.mjs" }
+  ],
+  "packageDeps": {
+    "devDependencies": {
+      "@types/node": "^22.0.0",
+      "typescript": "^5.9.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Bolt HIPAA primitives (audit trail, field encryption, minimum-necessary middleware) onto an existing healthcare backend. Not a standalone application.",
+    "firstSteps": [
+      "Run `pnpm validate` — confirms required files and key exports are present.",
+      "Run `pnpm build` — `tsc --noEmit` typechecks the full pack; zero errors expected.",
+      "Read `docs/HIPAA-controls.md` — each §164.312 control maps to one file in this pack.",
+      "Wire `withPhiAccess` from `src/phi-access.ts` onto every route that reads or writes PHI. The middleware MUST log BEFORE returning.",
+      "Wire `src/encryption.ts` helpers on every column storing SSN, DOB, MRN, or free-text clinical notes. AES-256-GCM with per-field IV; key must come from KMS/Vault, not env vars.",
+      "Replace `InMemoryAuditStore` with a DB-backed append-only store; add a TRIGGER or DENY UPDATE/DELETE on the audit table at the DB level (§164.312(c)(2)).",
+      "Emit `docs/BAA-template.md` as a signed doc before production PHI lands — gate the production API behind a signed-BAA state flag."
+    ],
+    "gotchas": [
+      "Do NOT log PHI to stdout, structured JSON logs, or error traces. Every logger must run through a PHI-redaction filter — one slip violates §164.312(b).",
+      "Audit retention is ≥6 years per §164.316(b)(2)(i). Design the storage tier for it — don't plan to TTL old audit rows.",
+      "De-identification per §164.514 is NOT anonymization. Safe Harbor requires 18 specific identifier classes removed; Expert Determination needs a signed statistician's attestation.",
+      "Encryption at rest is 'addressable' not 'required' in §164.312 — but skipping it is almost always an audit failure. Always encrypt.",
+      "Minimum-necessary rule (§164.502(b)) means APIs must filter, not just the UI. A /patients endpoint that returns the full row and lets the caller discard fields is a violation."
+    ],
+    "architectureNotes": [
+      "Pair with `healthcare-hipaa-backend` family for a full starter, or compose onto `fullstack-ts` / `api-service` / `python-api` for incremental adoption.",
+      "Audit table schema: id, actor_user_id, actor_role, action (enum), subject_table, subject_id, subject_fields_accessed[], at (timestamp), request_id, client_ip. Never include the PHI itself in the audit row — reference it by ID only.",
+      "TS source files are supplied by the family (src/encryption.ts, src/phi-access.ts, src/audit-log.ts, docs/, validate-hipaa-pack.mjs). This layer contributes package.json with a real name, tsconfig.json, and AGENTS.md."
+    ],
+    "placeholders": [
+      { "path": "src/phi-access.ts", "description": "Reference middleware. Replace the stubbed route matchers with the product's real routes; keep the audit-before-return order." },
+      { "path": "docs/BAA-template.md", "description": "BAA template. Legal MUST review + customize before use — it is not legal advice." }
+    ]
+  },
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm build", "pnpm validate"],
+    "entrypoints": ["src/encryption.ts", "src/phi-access.ts", "src/audit-log.ts"],
+    "preview": null,
+    "extensionPoints": ["src/phi-access.ts", "docs/HIPAA-controls.md"]
+  }
+}