Stratum Platform — API Security & Architecture Report

src/middleware/tenant.ts:16 The entire API is authenticated by a single header value: X-User-Id. Any caller who obtains or guesses a valid UUID can impersonate that user. This is acknowledged in the codebase as "Phase 1 auth" pending Auth0/Clerk, but it is critical to flag explicitly because the platform is designed to hold PHI-adjacent clinical data and is nearing multi-tenant production readiness.

The risk is compounded by several adjacent issues: (a) there is no token expiry, (b) there is no device binding, (c) there is no MFA surface, and (d) there is no IP-based gating. An attacker who intercepts or reads a single logged user ID has full authenticated access. This needs to be the first thing replaced before real tenants are onboarded.

What to do: Complete Phase 2 (Auth0 or Clerk). In the interim, add an API key layer as a bridge — even a static per-tenant bearer token checked against the database is vastly better than a bare UUID header. Consider gating all non-demo traffic behind VPN or IP allowlist until real auth ships.

src/server.ts:15-18 The CORS config reads process.env.CORS_ORIGIN || '*'. If CORS_ORIGIN is not set — in staging, CI, or any deployment that forgets the env var — the API is open to cross-origin requests from any domain. The CloudFormation template correctly sets a production origin (https://platform.stratumcollective.co) but nothing enforces that this env var is set in non-production deployments.

On a healthcare platform, a wildcard CORS policy means a malicious page hosted anywhere can make credentialed requests (using the credentials: true setting that is currently combined with the wildcard) on behalf of authenticated users. Note: browsers actually block credentials: true with wildcard — but the intent is wrong and the wildcard is still overly permissive for public APIs hitting a sensitive data store.

What to do: Default CORS origin to https://platform.stratumcollective.co in the code. Only allow localhost variants when NODE_ENV === 'development'. Never allow * for a credentialed API. Fail the server startup if CORS_ORIGIN is missing in production.

src/routes/precedents.ts:43 src/routes/marketplace.ts:124 Error handlers log raw error objects via console.error('Create precedent error:', err). If a database error, Zod parse error, or upstream exception happens to contain user-supplied text (which in this system can include clinical language), that data ends up in whatever logging sink is consuming stdout.

More directly: if someone submits a request containing PHI that slips past the regex guards (e.g., a name-only or context-dependent identifier), it will be logged to console. HIPAA's 2025 proposed updates eliminate the "addressable vs. required" distinction, making log sanitation a hard requirement rather than an addressable one.

What to do: Replace bare console.error with a structured logger (Winston or Pino) configured with a PHI sanitizer transform. Log error codes and stack traces, never request bodies. Apply this to the entire codebase.

src/db/connection.ts:16 The production SSL config uses ssl: { rejectUnauthorized: false }. This disables certificate chain validation, making the database connection vulnerable to man-in-the-middle attacks. Any adversary who can intercept traffic between the Node.js process and the RDS instance could present a forged certificate and read all database traffic, including clinical precedent data.

AWS App Runner connects to RDS via a VPC connector, so in the specific CloudFormation deployment the attack surface is reduced — but the policy is wrong and will cause problems if the database is ever accessed from outside that VPC boundary (e.g., admin scripts, data pipelines, disaster recovery procedures).

What to do: Set rejectUnauthorized: true and provide the RDS CA bundle (downloadable from AWS) as the ca property. AWS publishes regional RDS CA certificates specifically for this purpose.

src/middleware/audit.ts src/routes/precedents.ts:229-241 The export audit log call is wrapped in try/catch { /* non-critical */ }. The audit middleware itself has no retry logic, no dead-letter queue, and no alerting. If the audit table write fails for any reason (DB connection blip, constraint violation, disk pressure), the event is silently swallowed.

HIPAA audit log requirements (45 CFR §164.312(b)) are not optional — you must be able to prove who accessed what and when. A silently failing audit log is worse than no audit log because it creates a false sense of compliance. The 7-year retention schema exists, but retention of records that were never written is zero.

What to do: Audit writes should fail loudly via structured logging (never silently catch). For the export endpoint specifically, consider moving audit logging before the response is sent (with a circuit breaker pattern) rather than fire-and-forget after.

src/server.ts:22-27 The rate limiter is applied globally at 500 requests per 15-minute window. For a healthcare API that serves a small number of known tenants, 500 req/15 min is extremely generous — it provides negligible protection against abusive tenants (who can exhaust quota before hitting the limit) or against an attacker who has obtained a valid user ID.

There is also no differentiation between the paid marketplace routes (which burn credits) and the free registry routes. A caller could hammer /api/registries/payers 499 times without any rate limiting consequence.

What to do: Implement tiered rate limiting: stricter limits on write endpoints (50/15min per tenant), moderate on reads (200/15min), and lenient on public registry endpoints (1000/15min with no auth). Use keyGenerator in express-rate-limit to key by tenant_id (from the auth context) rather than IP address.

src/middleware/phi-validation.ts:6-16 The PHI guard covers 10 patterns. HIPAA Safe Harbor (45 CFR §164.514(b)(2)) defines 18 identifier types. Missing coverage includes: geographic data smaller than state (zip codes), dates other than year (birth dates, admission dates), ages over 89, vehicle and device identifiers, biometric identifiers (finger/voice prints), and full-face photographs. A field containing a zip code or date of birth would pass through undetected.

The existing patterns also have some fragility: the Phone pattern would match many non-PHI numeric sequences, and the "Date" pattern for MM/DD/YYYY would block date ranges that appear in clinical policy references (e.g., "see §4.2 dated 01/15/2024").

src/server.ts:14 helmet() is applied with no configuration. This installs Helmet's defaults including a Content Security Policy, but Helmet 8's default CSP is lenient enough to allow inline scripts and data URIs. For a pure JSON API (no HTML responses), Helmet should be configured explicitly: disable features irrelevant to an API (crossOriginEmbedderPolicy, etc.) and set a minimal CSP (default-src 'none'). Additionally, hsts should be explicitly configured with a long max-age and includeSubDomains.

src/registries/index.ts:61-64 Registry files are loaded with readFileSync inside the loadRegistry function, which is called lazily. If the sibling stratum-corpus-data repo is missing in a deployment, the first request to /api/registries/* will throw an unhandled exception that propagates through the route handler. The public registry routes have no specific error handling for this case — they'd return a 500 with the generic error handler's generic message. A startup check would give a clearer operational signal.

src/routes/precedents.ts:244 The bulk export endpoint is registered as POST /precedents/export which comes after DELETE /precedents/:id in the route file. In Express, since the POST verb differs from DELETE/GET, this is safe — but the inline comment "// IMPORTANT: This route must come AFTER..." in marketplace.ts shows this pattern has already caused a real confusion. The same anti-pattern appears in the precedents router: mixing static path segments (/export) with dynamic ones (/:id) in the same router without an explicit route ordering convention is fragile as the codebase grows.

Additionally, POST /export is a non-REST pattern for what is effectively a filtered GET. Consider GET /export with query params, or a dedicated export endpoint namespace.

src/routes/precedents.ts:152-159 GET /precedents/:id/versions returns a raw array. All other list endpoints in this codebase return { data: [...], total, limit, offset }. This inconsistency means API consumers need different logic to handle this endpoint. For a highly-versioned precedent object that goes through many changes, this endpoint could also return an unbounded number of rows with no pagination.

src/routes/precedents.ts:163-171 POST /precedents/:id/apply returns only { success: true } after incrementing reuse_count. The caller must make a second GET request to see the updated state. In the test suite, this is exactly what happens (lines 373-388). REST convention is to return the mutated resource. This is a minor but consistent DX friction point.

The API has no versioning prefix (/v1/). For an early-stage product this is understandable, but the absence of versioning means any breaking schema or route change will require coordinated deploys with all API consumers. Given that the CLAUDE.md notes "Phase 2 will use Auth0/Clerk" — a breaking auth change — the migration will be easier if there's a /api/v1/ prefix already in place. The health check is at /health (un-versioned), which is correct convention.

src/routes/registries.ts The public registry routes use manual query param destructuring rather than Zod schemas. Typos (?famly=Anthem instead of ?family=Anthem) return unfiltered full results silently. This is not a security issue (data is public and read-only) but is a developer experience problem — callers get no indication that their filter was ignored.

src/pipeline/runner.ts:119-125 The full pipeline runner uses a sequential for...of loop over all clusters. Each iteration calls processCluster() which issues multiple DB queries and transactions. At scale (hundreds of clusters), this will run for many minutes inside a synchronous HTTP request triggered by POST /marketplace/pipeline/trigger. The HTTP response will either time out (App Runner has a 120s default) or hang the thread.

The admin/allocate-monthly endpoint has the same problem: it runs one await query() per tenant in a serial loop with no batching, no transaction wrapping the whole operation, and no idempotency guard against running twice.

src/routes/precedents.ts:253 The bulk export endpoint overrides the limit to 1000 and loads all rows into memory before streaming the CSV. For a platform accumulating precedents across many tenants, 1000 rows of JSONB-heavy records (each with full evidence kits, narrative templates, and traceability ledgers) will create significant memory pressure. The 1mb JSON body limit compounds this — if a tenant's 1000-record export is large, this will OOM.

src/routes/marketplace.ts:80 src/middleware/marketplace-access.ts:34 The getBalance() function issues a SUM(amount) aggregate query. In the /profiles/:payer endpoint, balance is checked once pre-deduction and the ledger INSERT happens in a separate transaction. This is a read-before-write without a locking mechanism — a highly concurrent tenant could theoretically burn more credits than they have if two requests race to the balance check before either commits. The cluster detail flow in marketplace-access.ts does use a transaction for the deduct-then-read pattern, which is correct. The profile endpoint does not.

src/models/precedent.ts:266-279 The search function runs a COUNT query followed by a paginated SELECT. These could be combined using a window function (COUNT(*) OVER ()) into a single round-trip, reducing query latency by ~50% for list operations. Minor at current data volumes but worth noting as the corpus grows.

src/routes/precedents.ts:238 The logAuditExport function uses require('../middleware/audit') at runtime instead of a static import. This bypasses TypeScript module resolution, removes type checking on the imported function, and could fail silently if the path changes. It appears to have been done to avoid a circular dependency, but a static import would work fine here — the audit middleware doesn't import from the routes.

src/middleware/marketplace-access.ts:11 The Express Request augmentation declares marketplaceData?: any. This means the cluster detail route at marketplace.ts:60 spreads untyped data directly into the response. Should be typed as MarketplaceCluster | null.

src/db/startup.ts:34 startup.ts calls await pool.end() in the finally block. If startup.ts is ever integrated into the main server boot sequence (which the CLAUDE.md description implies it might be), ending the shared pool would break all subsequent database queries. Currently it appears to be run as a separate script, not imported by server.ts, so this is not an active bug — but it's a trap waiting to be triggered.

src/db/seed.ts:14 The admin user is seeded with patrick@stratumcollective.co as the email, and the seed script prints the user ID to console. While seed data is not production data, this pattern will be replicated if anyone uses this as a template for a production seed, and the console output leaks a real email address into CI logs.

There is no OpenAPI/Swagger spec, no Postman collection, and no route-level JSDoc. The CLAUDE.md describes the routes at a high level, but a new developer (or a Development Partnership client building against this API) has no machine-readable contract. This becomes significant when the frontend (web/) evolves separately from the API — type drift is hard to catch without a shared contract. Given the platform already has comprehensive Zod schemas, generating an OpenAPI spec from them (e.g., via zod-to-openapi or @asteasolutions/zod-to-openapi) is low-effort and high-value.

src/server.ts:30-32 The health check returns { status: 'ok', timestamp: '...' } but performs no actual health assertion. If the database connection pool is exhausted or the DB is unreachable, the health check still returns 200. Load balancers and App Runner health checks use this endpoint to decide whether to route traffic — a false positive here means a dead instance continues to receive requests. The check should perform a SELECT 1 against the database and report the result.