chore(readiness): assert query-hash HMAC guard is active (PIA-2)

docs/privacy-impact-assessment.md

@@ -42,15 +42,15 @@ material.
 
 **Top gaps (full register in §10):**
 
-| ID | Risk | One-line |
-| ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| PIA-1 | High | Cross-border disclosure to OpenAI (US) has no code-visible DPA/ZDR and no user-facing notice/consent (APP 8, APP 5). |
-| PIA-2 | High | Query-hash HMAC downgrades to **unsalted, dictionary-reversible SHA-256** if `RAG_QUERY_HASH_SECRET` is unset — nothing enforces it in production.  |
-| PIA-3 | Resolved | Generated answer text is no longer persisted to `rag_queries` by default; answer-text persistence is gated behind `RAG_PERSIST_ANSWER_TEXT` (default off, blocked in production readiness). |
-| PIA-4 | Medium | `rag_query_misses` has **no retention/purge job** (only `rag_queries` and `rag_retrieval_logs` do). |
-| PIA-5 | Medium | No privacy policy / collection notice / data-handling documentation shipped (APP 1, APP 5). |
-| PIA-6 | Low-Med | OpenAI **prompt-cache retention is forced to 24h** for gpt-5.5 regardless of config — query + retrieved excerpts persist ≤24h at OpenAI. |
-| PIA-7 | Low | `RAG_PERSIST_RAW_QUERY_TEXT=true` would store raw PHI query text with no secondary safeguard beyond the 30-day purge. |
+| ID | Risk | One-line |
+| ----- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PIA-1 | High | Cross-border disclosure to OpenAI (US) has no code-visible DPA/ZDR and no user-facing notice/consent (APP 8, APP 5). |
+| PIA-2 | High | Query-hash HMAC would downgrade to **unsalted, dictionary-reversible SHA-256** without `RAG_QUERY_HASH_SECRET` — now **enforced**: production fails closed at boot; operator must place the secret. |
+| PIA-3 | Resolved | Generated answer text is no longer persisted to `rag_queries` by default; answer-text persistence is gated behind `RAG_PERSIST_ANSWER_TEXT` (default off, blocked in production readiness). |
+| PIA-4 | Medium | `rag_query_misses` has **no retention/purge job** (only `rag_queries` and `rag_retrieval_logs` do). |
+| PIA-5 | Medium | No privacy policy / collection notice / data-handling documentation shipped (APP 1, APP 5). |
+| PIA-6 | Low-Med | OpenAI **prompt-cache retention is forced to 24h** for gpt-5.5 regardless of config — query + retrieved excerpts persist ≤24h at OpenAI. |
+| PIA-7 | Low | `RAG_PERSIST_RAW_QUERY_TEXT=true` would store raw PHI query text with no secondary safeguard beyond the 30-day purge. |
 
 ---
 
@@ -185,7 +185,7 @@ service-role for writes). Redaction is applied centrally at every write site.
 | `rag_retrieval_logs` | No (hash placeholder) | same helpers; write at [search/route.ts:556-559](src/app/api/search/route.ts) | retrieval telemetry only | owner-read, [schema.sql:3938](supabase/schema.sql) |
 | `audit_logs` | N/A (no query text) | action/resource metadata only; error strings pass through `redactLogValue` ([privacy.ts:5-31](src/lib/privacy.ts)) | `owner_id`, `action`, `resource_id` | service-role-only, [schema.sql:3959](supabase/schema.sql) |
 
-### 5.1 M15 HMAC query-hash fix — verified present, conditionally active
+### 5.1 M15 HMAC query-hash fix — verified present, enforced in production
 
 The audit's **M15** remediation is in the code
 ([src/lib/query-privacy.ts:17-23](src/lib/query-privacy.ts)):
@@ -208,10 +208,17 @@ export function hashQueryText(query: string) {
  and match rows, and can correlate the same query across rows. This defeats the redaction it is
  meant to provide.
 
-**Nothing in the codebase forces the secret to be present in production.** `RAG_QUERY_HASH_SECRET`
-is `z.string().min(16).optional()` ([src/lib/env.ts:104](src/lib/env.ts)) with no production guard.
-This is gap **PIA-2** — the fix is real but its safety depends on an operator setting that is not
-enforced.
+**Status (PIA-2 — enforcement landed):** production now **fails closed** when the secret is absent.
+`requireQueryHashSecret()` ([src/lib/env.ts](src/lib/env.ts)) throws at server startup
+([src/instrumentation.ts](src/instrumentation.ts)) when `NODE_ENV=production` and
+`RAG_QUERY_HASH_SECRET` is unset, so a misconfigured clinical server refuses to boot rather than
+degrade to the unsalted digest. `npm run check:production-readiness` additionally asserts the boot
+guard is wired into the startup path and that the secret is present, and
+[tests/instrumentation.test.ts](tests/instrumentation.test.ts) /
+[tests/env-query-hash-secret.test.ts](tests/env-query-hash-secret.test.ts) cover the fail-closed
+behaviour. The schema stays `z.string().min(16).optional()` so dev/CI keep the legacy digest for
+stored-row joins. **Remaining operator action:** place the secret in the deploy host's secret store —
+the guard and assertion enforce its presence but cannot supply it.
 
 ### 5.2 Redaction helper coverage
 
@@ -341,15 +348,20 @@ compliance-posture and PHI-minimisation gaps.
  offers **Australia data residency** (storage) — an option that postdates this PIA. The remaining step
  (execute DPA / apply ZDR / counsel sign-off) is operator/legal, not code.
 
-### PIA-2 — Query-hash HMAC silently downgrades without the secret **(High)**
+### PIA-2 — Query-hash HMAC silently downgrades without the secret **(High — enforcement landed)**
 
 - **Risk:** If `RAG_QUERY_HASH_SECRET` is unset in prod, stored query hashes are unsalted SHA-256 →
  dictionary-reversible and cross-row correlatable, defeating the redaction (undoes M15).
-- **Evidence:** [query-privacy.ts:17-23](src/lib/query-privacy.ts); optional with no prod guard
- ([env.ts:104](src/lib/env.ts)).
-- **Fix:** Make `RAG_QUERY_HASH_SECRET` **mandatory in production** — fail closed at startup (mirror the
- `requireServerEnv` pattern) when `NODE_ENV=production` and the secret is missing. Set it on the live
- project now.
+- **Evidence:** [query-privacy.ts:17-23](src/lib/query-privacy.ts); the secret is
+ `z.string().min(16).optional()` in [env.ts](src/lib/env.ts).
+- **Fix (landed):** `requireQueryHashSecret()` now makes the secret **mandatory in production** — it
+ fails closed at startup ([instrumentation.ts](src/instrumentation.ts)) when `NODE_ENV=production` and
+ the secret is missing, mirroring the `requireServerEnv` pattern. `check:production-readiness` asserts
+ the boot guard is wired in and the secret is present; covered by
+ [instrumentation.test.ts](tests/instrumentation.test.ts) and
+ [env-query-hash-secret.test.ts](tests/env-query-hash-secret.test.ts).
+- **Remaining (operator):** place `RAG_QUERY_HASH_SECRET` in the deploy host's secret store on the live
+ project (the code enforces its presence but cannot supply the value).
 
 ### PIA-3 — Generated answers stored un-redacted in `rag_queries` **(Resolved)**
 
@@ -403,7 +415,8 @@ compliance-posture and PHI-minimisation gaps.
 ## 11. Recommendation
 
 Before the app is used with real patients in a WA clinical setting, close **PIA-1** and **PIA-2** as
-launch-blockers (cross-border contractual basis + user notice; mandatory HMAC secret). **PIA-3** is
+launch-blockers (cross-border contractual basis + user notice; the mandatory HMAC secret is now
+enforced in code — the remaining step is placing it in the deploy host's secret store). **PIA-3** is
 closed (answer text is no longer persisted by default; gated behind `RAG_PERSIST_ANSWER_TEXT`); **PIA-4**
 remains as a fast follow-up (purge `rag_query_misses`), and ship the **PIA-5** privacy documentation. The data-at-rest security posture (Sydney residency, RLS, private storage,
 query hashing, automated purge) is already strong and should be highlighted in the privacy policy as

scripts/production-readiness.ts

@@ -136,13 +136,44 @@ async function checkFileForServiceRoleExposure() {
  }
 }
 
+// PIA-2: the query-hash HMAC guard only redacts logged clinical queries if it is
+// actually invoked at boot. Assert the fail-closed call is still wired into the
+// startup path (src/instrumentation.ts) so a refactor can't silently drop it and let
+// production start writing unsalted, dictionary-reversible SHA-256 hashes. The
+// behavioural proof lives in tests/instrumentation.test.ts; this is a check-time
+// signal that the guard is active in every environment, including CI where the
+// secret-presence check below is intentionally quiet. The regex matches the call
+// form (`requireQueryHashSecret(`), not the bare import destructuring.
+async function checkQueryHashGuardWiring() {
+ const instrumentationPath = path.join(process.cwd(), "src", "instrumentation.ts");
+ let source: string;
+ try {
+ source = await readFile(instrumentationPath, "utf8");
+ } catch {
+ result.failures.push(
+ "Cannot read src/instrumentation.ts to verify the RAG_QUERY_HASH_SECRET boot guard is active.",
+ );
+ return;
+ }
+ if (/\brequireQueryHashSecret\s*\(/.test(source)) {
+ result.passes.push(
+ "Boot guard invokes requireQueryHashSecret(); the query-hash HMAC fails closed in production (PIA-2).",
+ );
+ } else {
+ result.failures.push(
+ "src/instrumentation.ts no longer invokes requireQueryHashSecret(); the query-hash HMAC boot guard (PIA-2) is not active.",
+ );
+ }
+}
+
 async function main() {
  checkNodeRuntime();
  recordNoAuthProductionCheck();
  recordDemoModeProductionCheck();
  recordRawQueryPersistenceProductionCheck();
  recordAnswerPersistenceProductionCheck();
  await checkFileForServiceRoleExposure();
+ await checkQueryHashGuardWiring();
 
  if (!(await checkRequiredFile(path.join(process.cwd(), "package-lock.json"), "package-lock.json is required"))) {
  // keep going so we can show all diagnostics
@@ -198,9 +229,21 @@ async function main() {
  }
  }
 
- const productionLike = process.env.NODE_ENV === "production" || process.env.VERCEL_ENV === "production";
- if (productionLike && !envModule.env.RAG_QUERY_HASH_SECRET) {
- result.failures.push("RAG_QUERY_HASH_SECRET is required in a production-like environment.");
+ // Exercise the real boot guard so this check tracks its behaviour instead of
+ // re-encoding the env rule (mirrors requireServerEnv/requireOpenAIEnv above). A
+ // present secret passes in any environment; a missing one fails closed only in a
+ // production-like environment (dev/CI keep the legacy digest for stored-row joins).
+ try {
+ envModule.requireQueryHashSecret();
+ result.passes.push(
+ "RAG_QUERY_HASH_SECRET is set; logged clinical-query hashes are keyed HMAC pseudonyms (PIA-2).",
+ );
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ const productionLike = process.env.NODE_ENV === "production" || process.env.VERCEL_ENV === "production";
+ if (productionLike) {
+ result.failures.push(`Query-hash secret issue: ${message}`);
+ }
  }
 
  if (placeholderLooksLikeExample(envModule.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY ?? "")) {