@nodii/dsar 0.19.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/dist/bind-pattern-a.d.ts +139 -2
  2. package/dist/bind-pattern-a.d.ts.map +1 -1
  3. package/dist/bind-pattern-a.js +571 -32
  4. package/dist/bind-pattern-a.js.map +1 -1
  5. package/dist/bind-pattern-b.d.ts.map +1 -1
  6. package/dist/bind-pattern-b.js +58 -3
  7. package/dist/bind-pattern-b.js.map +1 -1
  8. package/dist/grpc/dsar-service.d.ts +29 -0
  9. package/dist/grpc/dsar-service.d.ts.map +1 -1
  10. package/dist/grpc/dsar-service.js +34 -0
  11. package/dist/grpc/dsar-service.js.map +1 -1
  12. package/dist/grpc/proto-path.d.ts +33 -0
  13. package/dist/grpc/proto-path.d.ts.map +1 -0
  14. package/dist/grpc/proto-path.js +87 -0
  15. package/dist/grpc/proto-path.js.map +1 -0
  16. package/dist/hold-failure-mode.d.ts +24 -0
  17. package/dist/hold-failure-mode.d.ts.map +1 -1
  18. package/dist/hold-failure-mode.js +24 -0
  19. package/dist/hold-failure-mode.js.map +1 -1
  20. package/dist/hold-gate-probe.d.ts +61 -0
  21. package/dist/hold-gate-probe.d.ts.map +1 -0
  22. package/dist/hold-gate-probe.js +146 -0
  23. package/dist/hold-gate-probe.js.map +1 -0
  24. package/dist/holds.d.ts +60 -1
  25. package/dist/holds.d.ts.map +1 -1
  26. package/dist/holds.js +60 -3
  27. package/dist/holds.js.map +1 -1
  28. package/dist/index.d.ts +16 -6
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +28 -5
  31. package/dist/index.js.map +1 -1
  32. package/dist/migrations/index.d.ts.map +1 -1
  33. package/dist/migrations/index.js +10 -0
  34. package/dist/migrations/index.js.map +1 -1
  35. package/dist/orchestrator.d.ts +48 -0
  36. package/dist/orchestrator.d.ts.map +1 -1
  37. package/dist/orchestrator.js +297 -20
  38. package/dist/orchestrator.js.map +1 -1
  39. package/dist/register.d.ts +35 -1
  40. package/dist/register.d.ts.map +1 -1
  41. package/dist/register.js +26 -0
  42. package/dist/register.js.map +1 -1
  43. package/dist/retention-sweeper.d.ts +252 -0
  44. package/dist/retention-sweeper.d.ts.map +1 -0
  45. package/dist/retention-sweeper.js +356 -0
  46. package/dist/retention-sweeper.js.map +1 -0
  47. package/dist/retention.d.ts +109 -1
  48. package/dist/retention.d.ts.map +1 -1
  49. package/dist/retention.js +216 -3
  50. package/dist/retention.js.map +1 -1
  51. package/dist/subject-kinds.d.ts +74 -0
  52. package/dist/subject-kinds.d.ts.map +1 -0
  53. package/dist/subject-kinds.js +141 -0
  54. package/dist/subject-kinds.js.map +1 -0
  55. package/dist/types.d.ts +423 -7
  56. package/dist/types.d.ts.map +1 -1
  57. package/dist/types.js +164 -0
  58. package/dist/types.js.map +1 -1
  59. package/package.json +7 -4
  60. package/proto/nodii/dsar/v1/dsar.proto +202 -0
  61. package/src/migrations/001-lifecycle-requests.sql +422 -0
@@ -12,10 +12,53 @@
12
12
  // enforce it.
13
13
  import { actionName } from "./audit-actions.js";
14
14
  import { holdKindFromProto, subjectKindFromProto, } from "./grpc/dsar-service.js";
15
- import { brandHoldGateRefusal, carryHoldGateRefusalBrand, HOLD_CONSULT_FAILED_REASON, holdGateRefusalAuditPayload, resolveFailClosedHolds, } from "./hold-failure-mode.js";
15
+ import { UNKNOWN_SUBJECT_KIND_REASON, isSubjectKind, unknownSubjectKindRefusal, } from "./subject-kinds.js";
16
+ import { brandHoldGateRefusal, carryHoldGateRefusalBrand, HOLD_CONSULT_FAILED_REASON, HOLD_GATE_NO_SQL_CLIENT_DETAIL, holdGateRefusalAuditPayload, resolveFailClosedHolds, } from "./hold-failure-mode.js";
17
+ import { HOLD_GATE_PROBE_TIMEOUT_MS, HoldGateUnreachableError, probeHoldGate, } from "./hold-gate-probe.js";
16
18
  import { isHeld, listActiveHolds } from "./holds.js";
17
19
  import { PostgresLifecycleRequestsStore, withLifecycleIdempotency, } from "./state-store/postgres-lifecycle.js";
18
- import { DEFAULT_ERASE_BLOCKING_HOLD_KINDS, MissingOutboxEmitterError, RPC_TO_COMPLIANCE_VERB, } from "./types.js";
20
+ import { DEFAULT_ERASE_BLOCKING_HOLD_KINDS, DEFAULT_PII_BUCKET, MissingOutboxEmitterError, MissingSqlClientForHoldGateError, RPC_TO_COMPLIANCE_VERB, RestrictedMarkerNotWritten, STATUTORY_ALREADY_TENANT_SHREDDED_REASON, STATUTORY_NOT_RETENTION_KEYED_REASON, STATUTORY_RETENTION_PARTIAL_REASON, StatutoryBucketNotRetentionKeyed, isPiiBucket, } from "./types.js";
21
+ /**
22
+ * Map a `LifecycleResponse.status` to the D239 compliance status.
23
+ * COMPLETED / PARTIAL / NO_DATA → 'completed'
24
+ * HELD → 'held'
25
+ * everything else (FAILED / ACCEPTED / UNSPECIFIED / …) → 'failed'
26
+ *
27
+ * Hoisted to module scope (it was a `bindPatternA` closure) so the mapping is a
28
+ * DIRECTLY TESTABLE pure function. Before the hoist the only way to observe it
29
+ * was to boot a Pattern A service against a real Postgres and read the emitted
30
+ * outbox row back, which meant 3 of the 7 `LifecycleResponse["status"]` members
31
+ * (COMPLETED / FAILED / HELD) were pinned and the other 4 were unobservable in
32
+ * any CI job without the stack.
33
+ *
34
+ * `NO_DATA` IS A SUCCESS (issue #713, fixed). "I hold nothing for this subject"
35
+ * discharges the obligation exactly as a completed erase/export does — the
36
+ * participant was asked, it answered truthfully, and there was nothing to act
37
+ * on. It used to land in the `else` arm, which recorded it as a compliance
38
+ * FAILURE carrying a fabricated `failureReason` ("unspecified_failure", since a
39
+ * NO_DATA response has no `reason`) AND wrote a `<svc>.dsar.<verb>_failed` row
40
+ * to the tamper-evident audit chain — a regulator-facing chain asserting a
41
+ * failure that never happened. The three-value compliance vocabulary
42
+ * (`completed` | `failed` | `held`) has no `no_data` member, so `completed` is
43
+ * the only truthful arm.
44
+ *
45
+ * This does NOT contradict D399. D399 governs the ORCHESTRATOR's aggregate
46
+ * (`toAggregatorStatus` / § 6.2), where an all-NO_DATA fan-out must not be
47
+ * coerced to COMPLETED and the wire `LifecycleResponse.status` stays NO_DATA
48
+ * verbatim. Neither is changed here; this is the participant-side collapse into
49
+ * the narrower D239 event vocabulary, which cannot represent NO_DATA at all.
50
+ *
51
+ * Twins: python `nodii_dsar.bind_patterns.compliance_status_for`, go
52
+ * `dsar.ComplianceStatusFor`. All three moved in the same commit.
53
+ */
54
+ export function complianceStatusFor(status) {
55
+ if (status === "COMPLETED" || status === "PARTIAL" || status === "NO_DATA") {
56
+ return "completed";
57
+ }
58
+ if (status === "HELD")
59
+ return "held";
60
+ return "failed";
61
+ }
19
62
  /**
20
63
  * Bind a Pattern A service implementation.
21
64
  */
@@ -36,6 +79,63 @@ export function bindPatternA(opts) {
36
79
  throw new MissingOutboxEmitterError(serviceName);
37
80
  }
38
81
  const outboxEmitter = opts.outboxEmitter;
82
+ // THE HOLD GATE MUST BE ABLE TO RUN (libs#612 → bind time).
83
+ //
84
+ // `handlers.erase` + `handlers.restrict` are REQUIRED members of
85
+ // PatternAHandlers, so binding Pattern A always binds the two hold-gated RPCs.
86
+ // With no `sqlClient` there is no holds table to consult; the gate is
87
+ // unconditionally fail-closed (operator ruling 2026-07-30), so both RPCs would
88
+ // refuse every request for the life of the process. That is a boot
89
+ // misconfiguration, and it now fails at BOOT — loudly, once — instead of
90
+ // surfacing as a `hold_consult_failed_fail_closed` on the first production
91
+ // erase. Same position + shape as the D239 outbox check directly above; the
92
+ // outbox check stays FIRST so a boot missing both still names the outbox gap.
93
+ if (opts.sqlClient == null || typeof opts.sqlClient.unsafe !== "function") {
94
+ throw new MissingSqlClientForHoldGateError(serviceName);
95
+ }
96
+ const sqlClient = opts.sqlClient;
97
+ // …AND IT MUST BE ABLE TO REACH THE HOLDS TABLE.
98
+ //
99
+ // The check above is STRUCTURAL — it proves an object with an `unsafe` method
100
+ // was passed. A pool aimed at a down host, at the WRONG database, or at one
101
+ // that never had `applyDsarMigrations` run satisfies it completely. The probe
102
+ // is the behavioural half: one bounded round-trip asserting the connection
103
+ // works AND `data_residency_holds` exists.
104
+ //
105
+ // `bindPatternA` is synchronous, so this CANNOT throw from here (see
106
+ // `hold-gate-probe.ts`). The promise is exposed as `impl.holdGateReady`, and
107
+ // `bindPatternAAndVerify` awaits it for callers who want the gate in one call.
108
+ //
109
+ // THE PROBE IS A DEPLOY GATE, NOT A RUNTIME LATCH — deliberately. An earlier
110
+ // draft had `checkHold` await it and convert a failure into a refusal, which
111
+ // is wrong twice over: a service that booted during a five-second DB blip
112
+ // would refuse every erase FOREVER (until redeployed), and the operator ruling
113
+ // the whole fail-closed posture rests on says the opposite —
114
+ // "it's just a matter of a retry when holds is accessible". A latched boot
115
+ // verdict is precisely the un-retryable refusal that D650's non-memoization
116
+ // rule exists to prevent, moved from the row cache into process memory.
117
+ //
118
+ // Nothing is lost by not latching: every condition the probe detects
119
+ // (unreachable pool, wrong database, unmigrated schema) ALSO makes the
120
+ // per-request `isHeld` consult raise, and that already produces the branded,
121
+ // audited, non-memoizable refusal. The runtime floor was never the probe's
122
+ // job. Its unique contribution is telling a DEPLOY, once, instead of telling
123
+ // the first production erase.
124
+ const holdGateProbe = probeHoldGate({
125
+ sql: sqlClient,
126
+ holdsTableName: opts.holdsTableName ?? "data_residency_holds",
127
+ timeoutMs: opts.holdGateProbeTimeoutMs ?? HOLD_GATE_PROBE_TIMEOUT_MS,
128
+ }).then((result) => {
129
+ if (!result.ok) {
130
+ throw new HoldGateUnreachableError(serviceName, result.detail, result.cause);
131
+ }
132
+ });
133
+ // An unawaited rejected promise is an unhandled rejection, which on modern
134
+ // Node CRASHES the process — turning a diagnostic into an outage for services
135
+ // that never opted into (1) or (2). Attach a terminal no-op handler NOW; the
136
+ // rejection is still delivered to everyone who awaits `holdGateProbe` itself,
137
+ // because attaching a handler to a promise does not consume it.
138
+ void holdGateProbe.catch(() => { });
39
139
  // Hold gate is UNCONDITIONALLY fail-closed (operator ruling 2026-07-30 —
40
140
  // fail CLOSED, all twins). This call survives only to reject the deprecated
41
141
  // `failClosedHolds: false` loudly here (boot), where it is visible, rather
@@ -47,19 +147,8 @@ export function bindPatternA(opts) {
47
147
  tableName: opts.lifecycleTableName,
48
148
  })
49
149
  : null;
50
- /**
51
- * Map a `LifecycleResponse.status` to the D239 compliance status.
52
- * COMPLETED / PARTIAL → 'completed'
53
- * HELD → 'held'
54
- * everything else (FAILED / ACCEPTED / …) → 'failed'
55
- */
56
- const complianceStatus = (status) => {
57
- if (status === "COMPLETED" || status === "PARTIAL")
58
- return "completed";
59
- if (status === "HELD")
60
- return "held";
61
- return "failed";
62
- };
150
+ /** See {@link complianceStatusFor} (hoisted to module scope to be testable). */
151
+ const complianceStatus = complianceStatusFor;
63
152
  /**
64
153
  * D239 — build the canonical compliance event from the resolved
65
154
  * LifecycleResponse + the lib-known request context, then derive the topic
@@ -87,6 +176,15 @@ export function bindPatternA(opts) {
87
176
  if (status === "held") {
88
177
  event.statuteHoldCitation = response.statute_citation ?? "";
89
178
  }
179
+ // D720 — the retained statutory classes ride the compliance event, because
180
+ // the wire `LifecycleResponse` has no field for them yet (adding a 7th
181
+ // proto field is a separate cross-repo change). Without this the orchestrator
182
+ // aggregating a fan-out would record "erase completed" with no trace that
183
+ // anything was lawfully kept.
184
+ if (response.retained_classes !== undefined &&
185
+ response.retained_classes.length > 0) {
186
+ event.retainedClasses = response.retained_classes;
187
+ }
90
188
  return event;
91
189
  };
92
190
  /**
@@ -109,6 +207,15 @@ export function bindPatternA(opts) {
109
207
  * treat the `tx`-carrying call as the durable terminal row.
110
208
  */
111
209
  const makeInTxHook = (rpcMethod, env, dataClasses) => async (tx, response) => {
210
+ // D720 — the RESTRICTED marker joins the SAME tx as the lifecycle row,
211
+ // the compliance event and the terminal audit. A retained-statutory erase
212
+ // whose marker was lost to a partial commit reads, on the next audit, as
213
+ // a subject that was never erased at all.
214
+ if (rpcMethod === "EraseData" &&
215
+ response.retained_classes !== undefined &&
216
+ response.retained_classes.length > 0) {
217
+ await markRestricted(tx, env);
218
+ }
112
219
  const event = buildComplianceEvent(rpcMethod, env, response, dataClasses);
113
220
  await outboxEmitter(tx, event);
114
221
  await emitTerminalAudit(tx, rpcMethod, env, response);
@@ -129,9 +236,10 @@ export function bindPatternA(opts) {
129
236
  /**
130
237
  * D239 — the TERMINAL audit row, emitted INSIDE the lifecycle tx alongside
131
238
  * the compliance event so it commits/rolls-back atomically with both.
132
- * Mapped from the resolved response status: COMPLETED/PARTIAL → completed,
133
- * HELD/FAILED → failed. The `tx` is passed to `auditEmitter.emit` as the
134
- * second arg (additive, optional) so a tx-aware emitter writes in-tx.
239
+ * The phase is derived from {@link complianceStatusFor}: COMPLETED / PARTIAL
240
+ * / NO_DATA → `completed`; HELD / FAILED / everything else → `failed`. The
241
+ * `tx` is passed to `auditEmitter.emit` as the second arg (additive,
242
+ * optional) so a tx-aware emitter writes in-tx.
135
243
  */
136
244
  const emitTerminalAudit = async (tx, rpcMethod, env, response) => {
137
245
  if (!opts.auditEmitter)
@@ -166,14 +274,213 @@ export function bindPatternA(opts) {
166
274
  }, handler, inTx);
167
275
  };
168
276
  const eraseBlockingKinds = opts.eraseBlockingHoldKinds ?? DEFAULT_ERASE_BLOCKING_HOLD_KINDS;
277
+ // -------------------------------------------------------------------------
278
+ // D720 — the three-bucket erase declaration.
279
+ // -------------------------------------------------------------------------
280
+ /** data_class → bucket, boot-validated. Absent ⇒ operational (pre-D720). */
281
+ const bucketOfClass = new Map();
282
+ /** data_class → the statute the service registered for it. */
283
+ const citationOfClass = new Map();
284
+ for (const dc of opts.retention?.dataClasses ?? []) {
285
+ const bucket = dc.bucket ?? DEFAULT_PII_BUCKET;
286
+ if (!isPiiBucket(bucket)) {
287
+ // Boot-loud, same position + reason as the D719 kind check: this
288
+ // declaration decides whether an erase destroys a class or keeps it, and
289
+ // a silently-defaulted typo picks "destroy".
290
+ throw new Error(`bindPatternA({ serviceName: ${JSON.stringify(serviceName)} }): data class ${JSON.stringify(dc.dataClass)} declares unknown retention bucket ${JSON.stringify(bucket)} — expected statutory | operational | free_text (D720).`);
291
+ }
292
+ bucketOfClass.set(dc.dataClass, bucket);
293
+ if (dc.statuteCitation)
294
+ citationOfClass.set(dc.dataClass, dc.statuteCitation);
295
+ }
296
+ const declaredStatutoryClasses = [...bucketOfClass.entries()]
297
+ .filter(([, b]) => b === "statutory")
298
+ .map(([c]) => c);
299
+ // A statutory class with nowhere to stamp `restricted_at` is a half-built
300
+ // declaration: the erase would retain the data and leave no durable record
301
+ // that it did, which on the next audit is indistinguishable from an erase
302
+ // that silently failed. Boot-loud, not request-loud.
303
+ if (declaredStatutoryClasses.length > 0 &&
304
+ !opts.retention?.dataSubjectsTableName) {
305
+ throw new Error(`bindPatternA({ serviceName: ${JSON.stringify(serviceName)} }): retention.dataClasses declares statutory class(es) [${declaredStatutoryClasses.join(", ")}] but no \`retention.dataSubjectsTableName\`. D720 requires the RESTRICTED marker (\`restricted_at\`) to be stamped on <svc>_data_subjects in the same tx as the erase — a statutory retention with no marker leaves no durable record that the subject was erased as far as the law allows.`);
306
+ }
307
+ const dataSubjectsTableName = opts.retention?.dataSubjectsTableName;
308
+ if (dataSubjectsTableName !== undefined &&
309
+ !/^[a-z_][a-z0-9_]*$/.test(dataSubjectsTableName)) {
310
+ throw new Error(`bindPatternA({ serviceName: ${JSON.stringify(serviceName)} }): retention.dataSubjectsTableName ${JSON.stringify(dataSubjectsTableName)} is not a bare SQL identifier (/^[a-z_][a-z0-9_]*$/).`);
311
+ }
312
+ /**
313
+ * D720 — partition the erase scope into (destroyed, retained).
314
+ *
315
+ * `requested` is the request's `data_classes[]`. Empty means "everything the
316
+ * service holds", so the partition falls back to the full declared set —
317
+ * otherwise a class-agnostic erase would silently skip the statutory check
318
+ * and shred through it, which is the exact hole this closes.
319
+ */
320
+ const partitionByBucket = (requested) => {
321
+ const scope = requested.length > 0 ? requested : [...bucketOfClass.keys()];
322
+ const destroyed = [];
323
+ const retained = [];
324
+ for (const dc of scope) {
325
+ // Undeclared classes default to operational — the pre-D720 behaviour.
326
+ if ((bucketOfClass.get(dc) ?? DEFAULT_PII_BUCKET) === "statutory") {
327
+ retained.push(dc);
328
+ }
329
+ else {
330
+ destroyed.push(dc);
331
+ }
332
+ }
333
+ return { destroyed, retained };
334
+ };
335
+ /**
336
+ * D720 — build `retained_classes[]` for the statutory classes an erase kept.
337
+ * The schedule lookup is best-effort per class: a class with no resolvable
338
+ * schedule is STILL reported (omitting it would understate what survived),
339
+ * carrying whatever citation the registration declared.
340
+ */
341
+ const buildRetainedClasses = async (env, classes) => {
342
+ const out = [];
343
+ for (const dataClass of classes) {
344
+ let resolved = null;
345
+ if (opts.retention?.schedule) {
346
+ try {
347
+ resolved = await opts.retention.schedule({
348
+ tenantId: env.tenant_id,
349
+ subjectId: env.subject_id,
350
+ subjectKind: String(env.subject_kind),
351
+ dataClass,
352
+ });
353
+ }
354
+ catch {
355
+ // A schedule lookup failure must not turn a lawful retention into a
356
+ // failed erase. Report the class with the registered citation.
357
+ resolved = null;
358
+ }
359
+ }
360
+ const citation = resolved?.statute_citation ?? citationOfClass.get(dataClass);
361
+ out.push({
362
+ data_class: dataClass,
363
+ ...(citation ? { statute_citation: citation } : {}),
364
+ ...(resolved?.retained_until
365
+ ? { retained_until: resolved.retained_until }
366
+ : {}),
367
+ });
368
+ }
369
+ return out;
370
+ };
371
+ /**
372
+ * D720 — the anti-silent-shred probe. Before an erase whose scope includes a
373
+ * statutory class, PROVE that class is keyed to the tenant retention DEK.
374
+ *
375
+ * A `false` (or a missing probe) means the statutory data is under the
376
+ * per-subject DEK that `erasePerSubject` is about to NULL — so proceeding
377
+ * would destroy a record the law requires the tenant to keep, and would
378
+ * report COMPLETED while doing it. Returns a FAILED refusal instead.
379
+ */
380
+ const checkStatutoryKeying = async (env, retained) => {
381
+ if (retained.length === 0)
382
+ return { kind: "retain" };
383
+ const refuse = (detail) => ({
384
+ kind: "refuse",
385
+ response: {
386
+ request_id: env.request_id,
387
+ status: "FAILED",
388
+ reason: STATUTORY_NOT_RETENTION_KEYED_REASON,
389
+ retention_gate_error: detail,
390
+ },
391
+ });
392
+ const probe = opts.pii?.retentionDekState;
393
+ if (typeof probe !== "function") {
394
+ return refuse(new StatutoryBucketNotRetentionKeyed(serviceName, env.tenant_id, retained, "adapter_missing_probe").message);
395
+ }
396
+ let state;
397
+ try {
398
+ state = await probe.call(opts.pii, env.tenant_id);
399
+ }
400
+ catch (err) {
401
+ // Fail-CLOSED, for the same reason the hold gate does: we cannot show the
402
+ // statutory data is safe, and the operation is irreversible.
403
+ return refuse(err instanceof Error ? err.message : String(err));
404
+ }
405
+ if (state === "present")
406
+ return { kind: "retain" };
407
+ if (state === "erased") {
408
+ // The D105 tenant shred already destroyed the statutory ciphertext. There
409
+ // is nothing left to protect, so the erase PROCEEDS. Refusing here would
410
+ // permanently block every Art. 17 request for a closed tenant AND blame a
411
+ // misconfiguration that does not exist.
412
+ return { kind: "already_erased" };
413
+ }
414
+ // state === "absent" — the real misconfiguration.
415
+ return refuse(new StatutoryBucketNotRetentionKeyed(serviceName, env.tenant_id, retained, "no_retention_dek").message);
416
+ };
417
+ /**
418
+ * D720 — stamp the RESTRICTED marker on `<svc>_data_subjects`.
419
+ *
420
+ * Runs on `tx` (the lifecycle transaction) so the marker, the lifecycle row,
421
+ * the compliance event and the terminal audit all commit or all roll back:
422
+ * a subject whose statutory data was retained but whose marker was lost is a
423
+ * subject the next audit reads as never-erased.
424
+ *
425
+ * Idempotent (`restricted_at = COALESCE(restricted_at, now())`) — a replayed
426
+ * request must not move the timestamp.
427
+ */
428
+ const markRestricted = async (tx, env) => {
429
+ if (!dataSubjectsTableName)
430
+ return;
431
+ // UPSERT, not UPDATE. A STATUTORY-ONLY subject has no `data_subjects` row
432
+ // at all — `encryptStatutory` keys to the tenant retention DEK and never
433
+ // mints a per-subject DEK, so nothing ever inserted one. A plain UPDATE
434
+ // silently matched zero rows there, and the response went out claiming a
435
+ // marker that did not exist. The INSERT arm records exactly what is true:
436
+ // this subject exists in this service, holds NO subject DEK, and is
437
+ // RESTRICTED.
438
+ //
439
+ // `dek_kms_key_id` / `dek_kms_key_version` are NOT NULL in the canonical
440
+ // § 8 schema but describe a key this subject never had; the empty string is
441
+ // the sentinel for "no per-subject key was ever minted", paired with
442
+ // `dek_ciphertext IS NULL` which is what every reader actually checks.
443
+ //
444
+ // `erased_at` is deliberately NOT set here. It is `@nodii/pii`'s column,
445
+ // stamped by `executeErasePerSubject` when a crypto-shred really happens;
446
+ // a statutory-only subject has nothing to shred, and a second writer with
447
+ // different semantics would make the column unreadable. `erased_at IS NULL`
448
+ // + `restricted_at IS NOT NULL` is the honest record of that case.
449
+ //
450
+ // COALESCE on the update arm keeps a replayed request from moving the
451
+ // timestamp.
452
+ const rows = (await tx.unsafe(`INSERT INTO ${dataSubjectsTableName}
453
+ (tenant_id, subject_id, subject_kind,
454
+ dek_ciphertext, dek_kms_key_id, dek_kms_key_version, restricted_at)
455
+ VALUES ($1, $2, $3, NULL, '', '', now())
456
+ ON CONFLICT (tenant_id, subject_id, subject_kind)
457
+ DO UPDATE SET restricted_at =
458
+ COALESCE(${dataSubjectsTableName}.restricted_at, now())
459
+ RETURNING 1 AS marked`, [env.tenant_id, env.subject_id, String(env.subject_kind).toUpperCase()]));
460
+ // Rows-affected is checked, not assumed. Without it the whole marker is
461
+ // advisory: a missing table, a missing `restricted_at` column, or a missing
462
+ // UNIQUE constraint all fail SILENTLY and the response still promises
463
+ // retention.
464
+ if (!Array.isArray(rows) || rows.length !== 1) {
465
+ throw new RestrictedMarkerNotWritten(serviceName, dataSubjectsTableName, Array.isArray(rows) ? rows.length : 0);
466
+ }
467
+ };
169
468
  /**
170
469
  * Consult the hold table before an erase/restrict path. Returns a non-null
171
470
  * `LifecycleResponse` when the operation must NOT proceed:
172
471
  * - `HELD` — an active hold matched.
173
- * - `FAILED` — the consult threw. UNCONDITIONAL (there is no mode to
174
- * select and no flag to unset — operator ruling 2026-07-30; gap 3).
472
+ * - `FAILED` — the consult threw, OR no `sqlClient` is configured at all
473
+ * (libs#612). UNCONDITIONAL: there is no mode to select, no flag to
474
+ * unset, and no configuration that skips the gate — operator ruling
475
+ * 2026-07-30; gap 3; D650.
175
476
  * Returns `null` when the operation may proceed.
176
477
  *
478
+ * The no-`sqlClient` leg is now UNREACHABLE from a successful `bindPatternA`
479
+ * (the bind throws {@link MissingSqlClientForHoldGateError} first) and is KEPT
480
+ * as defence in depth: it is the last line that turns a missing pool into a
481
+ * refusal rather than a skipped gate, and removing it would restore the
482
+ * original defect the moment anyone relaxes the bind-time check.
483
+ *
177
484
  * For erase, consults the SET of blocking kinds (gap 1) + optional
178
485
  * data_class (gap 2). For restrict, consults the legacy `restrict` gate.
179
486
  *
@@ -183,10 +490,18 @@ export function bindPatternA(opts) {
183
490
  * a matter of a retry when holds is accessible".
184
491
  */
185
492
  const checkHold = async (tenantId, subjectId, gate, dataClass) => {
186
- if (!opts.sqlClient)
187
- return null;
188
493
  const holdKind = gate === "erase" ? eraseBlockingKinds : "restrict";
189
494
  try {
495
+ // libs#612 — NO SQL CLIENT is a hold-consult failure, not a reason to skip
496
+ // the gate. This used to `return null` (proceed), which made the
497
+ // "UNCONDITIONALLY fail-closed" docstring above literally false whenever
498
+ // the pool was absent: the fail-open opt-out D650 removed at FLAG level
499
+ // survived at CONFIG level. Raising here routes it through the exact same
500
+ // branded, audited, non-memoizable refusal path as an unreadable holds
501
+ // table — which is what "if holds is inaccessible - we deny the write"
502
+ // means when the inaccessibility is that we never had a connection.
503
+ if (!opts.sqlClient)
504
+ throw new Error(HOLD_GATE_NO_SQL_CLIENT_DETAIL);
190
505
  const result = await isHeld({
191
506
  sql: opts.sqlClient,
192
507
  tenantId,
@@ -344,18 +659,108 @@ export function bindPatternA(opts) {
344
659
  request_id: env.request_id,
345
660
  });
346
661
  }
662
+ // D720 — partition the erase scope by retention bucket BEFORE anything
663
+ // irreversible runs. `retained` is the statutory set: it must survive
664
+ // this erase, and if it cannot be shown to be keyed to the tenant
665
+ // retention DEK, nothing is shredded at all.
666
+ const { destroyed, retained } = partitionByBucket(dataClasses);
667
+ // Scope matters. A per-SUBJECT erase must not destroy statutory data,
668
+ // so it is gated. A TENANT-scope erase is the D105 whole-tenant close —
669
+ // there statutory destruction is the intended outcome (the CMK shred
670
+ // takes the retention DEK with everything else), so gating it would
671
+ // block the one erase that is supposed to reach the statutory bucket.
672
+ const verdict = scope === "subject"
673
+ ? await checkStatutoryKeying(env, retained)
674
+ : { kind: "retain" };
675
+ if (verdict.kind === "refuse") {
676
+ await emitAudit("EraseData", "failed", env.tenant_id, env.subject_id, {
677
+ error: verdict.response.retention_gate_error,
678
+ statutory_classes: retained,
679
+ });
680
+ return verdict.response;
681
+ }
682
+ // The tenant key is already shredded (D105): the statutory ciphertext
683
+ // is dead, so nothing is RETAINED — but the rows are still not this
684
+ // erase's to row-delete.
685
+ const alreadyErased = verdict.kind === "already_erased";
347
686
  await emitAudit("EraseData", "started", env.tenant_id, env.subject_id);
348
687
  try {
349
688
  if (opts.pii) {
350
689
  if (scope === "tenant") {
690
+ // The tenant-wide erase IS the D105 shred — it reaches the
691
+ // retention DEK too, by design (the tenant is closing).
351
692
  await opts.pii.erasePerTenant(env.tenant_id);
352
693
  }
353
694
  else {
695
+ // Per-subject crypto-shred. This destroys the operational +
696
+ // free_text buckets ONLY: statutory columns are under the tenant
697
+ // retention DEK, which no per-subject path touches (D720).
354
698
  await opts.pii.erasePerSubject(env.tenant_id, env.subject_id, env.subject_kind);
355
699
  }
356
700
  }
357
- const result = await handlers.erase({ ...env, scope });
358
- await emitAudit("EraseData", "completed", env.tenant_id, env.subject_id, { scope, artifactId: result.artifactId });
701
+ // D720 — CARRY THE PARTITION INTO THE HANDLER. The crypto-shred kills
702
+ // the operational + free_text buckets, but it cannot stop a handler
703
+ // from row-deleting a statutory record, and a handler told to erase
704
+ // "everything for this subject" destroys exactly the rows the
705
+ // response is about to report as retained. So the handler is told
706
+ // what to destroy AND what to spare.
707
+ //
708
+ // A tenant close spares nothing: the D105 shred is meant to reach the
709
+ // statutory bucket, so the full scope goes to `data_classes`.
710
+ const handlerRetained = scope === "subject" && retained.length > 0
711
+ ? await buildRetainedClasses(env, retained)
712
+ : [];
713
+ const handlerDestroy = scope === "tenant" ? [...destroyed, ...retained] : destroyed;
714
+ const classSelection = dataClasses.length > 0 ? "explicit" : "all";
715
+ const result = await handlers.erase({
716
+ ...env,
717
+ scope,
718
+ data_classes: handlerDestroy,
719
+ retained_classes: handlerRetained,
720
+ class_selection: classSelection,
721
+ });
722
+ // What the SUBJECT is told. Diverges from what the HANDLER is told in
723
+ // the already-shredded case: the handler must still not delete those
724
+ // rows, but promising the subject they "survive under statute" when
725
+ // their key is gone would be false.
726
+ const retainedClasses = alreadyErased ? [] : handlerRetained;
727
+ const alreadyErasedClasses = alreadyErased && scope === "subject" ? [...retained] : [];
728
+ await emitAudit("EraseData", "completed", env.tenant_id, env.subject_id, {
729
+ scope,
730
+ artifactId: result.artifactId,
731
+ destroyed_classes: handlerDestroy,
732
+ ...(retainedClasses.length > 0
733
+ ? { retained_classes: retainedClasses }
734
+ : {}),
735
+ ...(alreadyErasedClasses.length > 0
736
+ ? { statutory_already_erased: alreadyErasedClasses }
737
+ : {}),
738
+ });
739
+ if (retainedClasses.length > 0) {
740
+ // A reasoned PARTIAL refusal: the operational + free_text buckets
741
+ // are gone, the statutory ones survive under statute. PARTIAL still
742
+ // classifies as `completed` in the D239 compliance vocabulary
743
+ // (complianceStatusFor) — the participant discharged the obligation
744
+ // as far as the law permits, which is what it is obliged to do.
745
+ return {
746
+ request_id: env.request_id,
747
+ status: "PARTIAL",
748
+ reason: STATUTORY_RETENTION_PARTIAL_REASON,
749
+ retained_classes: retainedClasses,
750
+ };
751
+ }
752
+ if (alreadyErasedClasses.length > 0) {
753
+ // Nothing survived, so nothing is retained and the erase is TOTAL.
754
+ // The note says what was already gone when the request arrived —
755
+ // neither a retention promise nor a misconfiguration report, both
756
+ // of which would be false here.
757
+ return {
758
+ request_id: env.request_id,
759
+ status: "COMPLETED",
760
+ reason: STATUTORY_ALREADY_TENANT_SHREDDED_REASON,
761
+ statutory_already_erased: alreadyErasedClasses,
762
+ };
763
+ }
359
764
  return {
360
765
  request_id: env.request_id,
361
766
  status: "COMPLETED",
@@ -590,6 +995,18 @@ export function bindPatternA(opts) {
590
995
  };
591
996
  }
592
997
  const retentionHoldHandlers = opts.retentionHoldHandlers;
998
+ // SCOPE PASSTHROUGH (drift `f65c3930`). The lift handler used to receive
999
+ // only `{request_id, tenant_id, subject_kind, subject_id, justification,
1000
+ // requested_by}` — every narrowing dimension the REQUEST carried
1001
+ // (`hold_kind`, `data_class`, `hold_request_id`) was DROPPED on the floor,
1002
+ // and `subject_id` arrived pre-flattened to `""` for a tenant-level lift by
1003
+ // the scalar bind rule (`String(x ?? "")`). So a handler could not tell
1004
+ // "lift the tenant's legal hold" from "lift subject ''"'s holds", and could
1005
+ // not narrow to the kind/class/dedupe-key the caller asked for — it had to
1006
+ // lift with whatever defaults it invented, which is precisely the
1007
+ // over-broad `liftHold` call drift 4a72cce1 is about. `place` (directly
1008
+ // above) has passed all three through since v0.4.0; `lift` never did.
1009
+ const subjectScoped = request.subject_id != null && String(request.subject_id) !== "";
593
1010
  // D239 — same-tx lifecycle row +
594
1011
  // <svc>.compliance.retention_hold_lifted.completed.v1 outbox event.
595
1012
  return runWithIdempotency("LiftRetentionHold", request, async () => {
@@ -601,6 +1018,22 @@ export function bindPatternA(opts) {
601
1018
  subject_id: env.subject_id,
602
1019
  justification: String(request.justification ?? ""),
603
1020
  requested_by: env.requested_by,
1021
+ // ALWAYS present (a derived boolean, never nullish) so the handler
1022
+ // branches without a nullish dance — this is the bit `subject_id:
1023
+ // ""` could not carry.
1024
+ tenant_level: !subjectScoped,
1025
+ // Nullish OMITS the key, exactly as `place` does (see the nullish
1026
+ // rule on placeHoldHandler): an explicit `null` must not reach the
1027
+ // handler as the literal 4-char string "null".
1028
+ ...(request.hold_kind != null
1029
+ ? { hold_kind: holdKindFromProto(request.hold_kind) }
1030
+ : {}),
1031
+ ...(request.data_class != null
1032
+ ? { data_class: String(request.data_class) }
1033
+ : {}),
1034
+ ...(request.hold_request_id != null
1035
+ ? { hold_request_id: String(request.hold_request_id) }
1036
+ : {}),
604
1037
  });
605
1038
  await emitAudit("LiftRetentionHold", "completed", env.tenant_id, env.subject_id);
606
1039
  return {
@@ -708,16 +1141,122 @@ export function bindPatternA(opts) {
708
1141
  };
709
1142
  }
710
1143
  };
711
- return {
712
- AccessData: accessHandler,
713
- EraseData: eraseHandler,
714
- RectifyData: rectifyHandler,
715
- ExportPortableData: portabilityHandler,
716
- RestrictProcessing: restrictHandler,
717
- PlaceRetentionHold: placeHoldHandler,
718
- LiftRetentionHold: liftHoldHandler,
1144
+ /**
1145
+ * D719 — the DECODE BOUNDARY guard, applied to every RPC in one place.
1146
+ *
1147
+ * `subjectKindFromProto` is a lenient decoder: it hands back whatever string
1148
+ * the wire carried when it does not recognise the shape. Every call site then
1149
+ * unchecked-cast that result into `SubjectKindStr` and carried on, so a
1150
+ * retired kind (`platform_admin`), a typo, or an internal DEK key SCOPE flowed
1151
+ * straight into `lifecycle_requests.subject_kind`, into the envelope handed to
1152
+ * consumer handlers, and into the hold rows — none of which any fan-out can
1153
+ * ever reach again (routing is subject_kind-ONLY, D486).
1154
+ *
1155
+ * Wrapping the returned impl map is deliberate: a per-handler check is a
1156
+ * checklist that a tenth RPC will silently skip. This runs before ANY handler
1157
+ * body, before `envelope()`, and before `withLifecycleIdempotency` touches the
1158
+ * store — so a refused request persists nothing and dispatches nothing.
1159
+ */
1160
+ const guardSubjectKind = (rpcMethod, handler) => {
1161
+ return async (request) => {
1162
+ const decoded = subjectKindFromProto(request.subject_kind);
1163
+ if (isSubjectKind(decoded))
1164
+ return handler(request);
1165
+ const requestId = String(request.request_id ?? "");
1166
+ await emitRefusalAudit(rpcMethod, request, decoded);
1167
+ return unknownSubjectKindRefusal(requestId);
1168
+ };
1169
+ };
1170
+ /**
1171
+ * Best-effort audit of a decode-boundary refusal. This is the ONLY place the
1172
+ * offending value is recorded in full, since the wire response carries just
1173
+ * the stable token — without it, an operator reading the orchestrator's
1174
+ * `per_sibling_state` would know a sibling refused but not what it refused.
1175
+ *
1176
+ * Never allowed to convert a refusal into a crash: if the consumer's audit
1177
+ * emitter is broken, the refusal still returns. Refusing loudly is the
1178
+ * guarantee; auditing the refusal is the diagnostic on top of it.
1179
+ */
1180
+ const emitRefusalAudit = async (rpcMethod, request, decoded) => {
1181
+ if (!opts.auditEmitter)
1182
+ return;
1183
+ try {
1184
+ await opts.auditEmitter.emit({
1185
+ action: actionName(opts.serviceName, rpcMethod, "failed"),
1186
+ target_kind: "data_subject",
1187
+ target_id: String(request.subject_id ?? ""),
1188
+ tenant_id: String(request.tenant_id ?? ""),
1189
+ payload: {
1190
+ refusal_reason: UNKNOWN_SUBJECT_KIND_REASON,
1191
+ rejected_subject_kind: decoded,
1192
+ },
1193
+ });
1194
+ }
1195
+ catch {
1196
+ // Swallowed by design — see the doc comment above.
1197
+ }
1198
+ };
1199
+ const impl = {
1200
+ AccessData: guardSubjectKind("AccessData", accessHandler),
1201
+ EraseData: guardSubjectKind("EraseData", eraseHandler),
1202
+ RectifyData: guardSubjectKind("RectifyData", rectifyHandler),
1203
+ ExportPortableData: guardSubjectKind("ExportPortableData", portabilityHandler),
1204
+ RestrictProcessing: guardSubjectKind("RestrictProcessing", restrictHandler),
1205
+ PlaceRetentionHold: guardSubjectKind("PlaceRetentionHold", placeHoldHandler),
1206
+ LiftRetentionHold: guardSubjectKind("LiftRetentionHold", liftHoldHandler),
1207
+ // GetLifecycleRequestStatus + ListActiveHolds are READ paths keyed on
1208
+ // request_id / tenant_id; `subject_kind` is an optional narrowing filter
1209
+ // there, not a routing or persistence key, so they are intentionally not
1210
+ // guarded — refusing a read because a filter is unrecognised would hide
1211
+ // exactly the rows an operator is trying to find while cleaning up.
719
1212
  GetLifecycleRequestStatus: statusHandler,
720
1213
  ListActiveHolds: listActiveHoldsHandler,
721
1214
  };
1215
+ // NON-ENUMERABLE so the impl still presents EXACTLY the 9 RPC keys to
1216
+ // `Object.keys` / spread / `server.addService` — a 10th enumerable key would
1217
+ // reach every consumer that iterates the descriptor to mount handlers, and
1218
+ // would be registered as an RPC that does not exist on the wire.
1219
+ Object.defineProperty(impl, "holdGateReady", {
1220
+ value: holdGateProbe,
1221
+ enumerable: false,
1222
+ writable: false,
1223
+ configurable: false,
1224
+ });
1225
+ return impl;
1226
+ }
1227
+ /**
1228
+ * {@link bindPatternA} with the hold-gate probe AWAITED — the hard boot gate.
1229
+ *
1230
+ * Identical to `bindPatternA` except that it does not resolve until the probe
1231
+ * has succeeded, and REJECTS with {@link HoldGateUnreachableError} when it has
1232
+ * not. Use it at boot when a participant that cannot consult holds should fail
1233
+ * the deploy rather than serve refusals:
1234
+ *
1235
+ * ```ts
1236
+ * const dsar = await bindPatternAAndVerify({ … }); // throws if holds unreachable
1237
+ * ```
1238
+ *
1239
+ * The synchronous `bindPatternA` remains for callers whose boot path cannot
1240
+ * await; they get the same guarantee one step later by awaiting
1241
+ * `impl.holdGateReady`, and the same refusal at request time if they do neither.
1242
+ */
1243
+ export async function bindPatternAAndVerify(opts) {
1244
+ const impl = bindPatternA(opts);
1245
+ await holdGateReadyOf(impl);
1246
+ return impl;
1247
+ }
1248
+ /**
1249
+ * The hold-gate probe promise attached to a `bindPatternA` impl.
1250
+ *
1251
+ * Exposed as a function rather than a typed field because `DsarServiceImpl` is
1252
+ * the WIRE descriptor — the 9 RPCs and nothing else — and widening it would
1253
+ * declare a 10th method on a shape consumers hand to `server.addService`.
1254
+ * Returns an already-resolved promise for impls that carry no probe (Pattern B /
1255
+ * Pattern C, which have no hold gate to verify), so a caller can await it
1256
+ * unconditionally.
1257
+ */
1258
+ export function holdGateReadyOf(impl) {
1259
+ const ready = impl.holdGateReady;
1260
+ return ready ?? Promise.resolve();
722
1261
  }
723
1262
  //# sourceMappingURL=bind-pattern-a.js.map