@nodii/dsar 0.20.0 → 0.23.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 +127 -13
  2. package/dist/bind-pattern-a.d.ts.map +1 -1
  3. package/dist/bind-pattern-a.js +553 -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
@@ -1,4 +1,5 @@
1
1
  import { type DsarServiceImpl } from "./grpc/dsar-service.js";
2
+ import type { DataClassRegistration } from "./register.js";
2
3
  import type { AuditEmitter, DsarComplianceEvent, HoldKind, OutboxEmitter, PatternAHandlers, PiiAdapter, RetentionHoldHandlers, SqlTransaction } from "./types.js";
3
4
  type SqlClient = {
4
5
  unsafe: (sql: string, args?: unknown[]) => Promise<any>;
@@ -11,25 +12,36 @@ type SqlClient = {
11
12
  };
12
13
  /**
13
14
  * Map a `LifecycleResponse.status` to the D239 compliance status.
14
- * COMPLETED / PARTIAL → 'completed'
15
- * HELD → 'held'
16
- * everything else (FAILED / ACCEPTED / NO_DATA / UNSPECIFIED / …) → 'failed'
15
+ * COMPLETED / PARTIAL / NO_DATA → 'completed'
16
+ * HELD → 'held'
17
+ * everything else (FAILED / ACCEPTED / UNSPECIFIED / …) → 'failed'
17
18
  *
18
19
  * Hoisted to module scope (it was a `bindPatternA` closure) so the mapping is a
19
20
  * DIRECTLY TESTABLE pure function. Before the hoist the only way to observe it
20
21
  * was to boot a Pattern A service against a real Postgres and read the emitted
21
22
  * outbox row back, which meant 3 of the 7 `LifecycleResponse["status"]` members
22
23
  * (COMPLETED / FAILED / HELD) were pinned and the other 4 were unobservable in
23
- * any CI job without the stack. No behaviour change — byte-identical logic.
24
+ * any CI job without the stack.
24
25
  *
25
- * KNOWN DEFECT (issue #713): `NO_DATA` — a first-class SUCCESS state meaning "I
26
- * hold nothing for this subject" (see D399, which made the orchestrator stop
27
- * coercing an all-NO_DATA aggregate to COMPLETED) — lands in the `else` arm and
28
- * is therefore recorded as a compliance FAILURE, with a fabricated
29
- * `failureReason`, plus a `<svc>.dsar.<verb>_failed` row on the tamper-evident
30
- * audit chain. Fixing it is a D239 semantic change that has to land in all
31
- * three languages at once (python `_compliance_status`, go `complianceStatus`),
32
- * so it is NOT made here. This test-visible seam is the prerequisite.
26
+ * `NO_DATA` IS A SUCCESS (issue #713, fixed). "I hold nothing for this subject"
27
+ * discharges the obligation exactly as a completed erase/export does — the
28
+ * participant was asked, it answered truthfully, and there was nothing to act
29
+ * on. It used to land in the `else` arm, which recorded it as a compliance
30
+ * FAILURE carrying a fabricated `failureReason` ("unspecified_failure", since a
31
+ * NO_DATA response has no `reason`) AND wrote a `<svc>.dsar.<verb>_failed` row
32
+ * to the tamper-evident audit chain — a regulator-facing chain asserting a
33
+ * failure that never happened. The three-value compliance vocabulary
34
+ * (`completed` | `failed` | `held`) has no `no_data` member, so `completed` is
35
+ * the only truthful arm.
36
+ *
37
+ * This does NOT contradict D399. D399 governs the ORCHESTRATOR's aggregate
38
+ * (`toAggregatorStatus` / § 6.2), where an all-NO_DATA fan-out must not be
39
+ * coerced to COMPLETED and the wire `LifecycleResponse.status` stays NO_DATA
40
+ * verbatim. Neither is changed here; this is the participant-side collapse into
41
+ * the narrower D239 event vocabulary, which cannot represent NO_DATA at all.
42
+ *
43
+ * Twins: python `nodii_dsar.bind_patterns.compliance_status_for`, go
44
+ * `dsar.ComplianceStatusFor`. All three moved in the same commit.
33
45
  */
34
46
  export declare function complianceStatusFor(status: string): DsarComplianceEvent["status"];
35
47
  export interface BindPatternAOpts {
@@ -50,7 +62,20 @@ export interface BindPatternAOpts {
50
62
  handlers: PatternAHandlers;
51
63
  /** Retention-hold handlers. Required for full Pattern A coverage. */
52
64
  retentionHoldHandlers?: RetentionHoldHandlers;
53
- /** Postgres SQL client for lifecycle_requests + holds. */
65
+ /**
66
+ * Postgres SQL client for lifecycle_requests + holds.
67
+ *
68
+ * **REQUIRED.** A Pattern A participant always binds `erase` + `restrict`
69
+ * (both are mandatory members of {@link PatternAHandlers}), and both are gated
70
+ * on the `data_residency_holds` consult. With no client the gate can never
71
+ * run, and the gate is UNCONDITIONALLY fail-closed — so every erase / restrict
72
+ * would be refused. Omitting it throws
73
+ * {@link MissingSqlClientForHoldGateError} at BOOT. There is no opt-out.
74
+ *
75
+ * Still typed OPTIONAL so a JS caller (or a stale build) that omits it reaches
76
+ * the bind-time throw with its own error rather than a `TypeError`, and so the
77
+ * runtime refusal below stays reachable as defence in depth.
78
+ */
54
79
  sqlClient?: SqlClient;
55
80
  /** Audit emitter for the 28-action family. */
56
81
  auditEmitter?: AuditEmitter;
@@ -83,6 +108,12 @@ export interface BindPatternAOpts {
83
108
  * fail-open to opt into.
84
109
  */
85
110
  failClosedHolds?: boolean;
111
+ /**
112
+ * Budget for the bind-time hold-gate reachability probe, in ms. Defaults to
113
+ * {@link HOLD_GATE_PROBE_TIMEOUT_MS} (3s). ONE round-trip, ONE attempt — see
114
+ * `hold-gate-probe.ts` for why it does not retry.
115
+ */
116
+ holdGateProbeTimeoutMs?: number;
86
117
  /**
87
118
  * v0.4.0 (request `626c342a` gap 1) — the hold kinds that block an erase.
88
119
  * Defaults to `DEFAULT_ERASE_BLOCKING_HOLD_KINDS` (every blocking kind incl.
@@ -90,10 +121,93 @@ export interface BindPatternAOpts {
90
121
  * Override to a narrower allow-list if a service needs different semantics.
91
122
  */
92
123
  eraseBlockingHoldKinds?: readonly HoldKind[];
124
+ /**
125
+ * D720 — the three-bucket retention declaration. Supply it and the erase leg
126
+ * stops being all-or-nothing:
127
+ *
128
+ * - `operational` + `free_text` classes are crypto-shredded as before;
129
+ * - `statutory` classes are RETAINED and the subject enters the RESTRICTED
130
+ * state (`<svc>_data_subjects.restricted_at` stamped in the SAME tx as
131
+ * the lifecycle row);
132
+ * - the response becomes `PARTIAL` with `retained_classes[]` enumerating
133
+ * what survived, under which statute, until when — a reasoned partial
134
+ * refusal rather than a silent one.
135
+ *
136
+ * Omit it entirely and NOTHING changes: every class is `operational` by
137
+ * default, so a participant that has no statutory data keeps its current
138
+ * total-erase behaviour byte for byte.
139
+ */
140
+ retention?: RetentionBucketDeclaration;
141
+ }
142
+ /**
143
+ * D720 — a Pattern A participant's retention-bucket declaration.
144
+ */
145
+ export interface RetentionBucketDeclaration {
146
+ /**
147
+ * The service's data classes + their buckets. This is the SAME array handed
148
+ * to `registerWithOrchestrator`, deliberately: the buckets the orchestrator
149
+ * knows about and the buckets the erase leg partitions on cannot then drift.
150
+ */
151
+ dataClasses: readonly DataClassRegistration[];
152
+ /**
153
+ * The `<svc>_data_subjects` table where `restricted_at` is stamped.
154
+ * REQUIRED when any declared class is `statutory` — the marker is the durable
155
+ * record that the subject was erased as far as the law allows, and a
156
+ * statutory retention with no marker is indistinguishable from a failed
157
+ * erase on the next audit.
158
+ */
159
+ dataSubjectsTableName?: string;
160
+ /**
161
+ * Optional per-class schedule lookup, resolving the statute + expiry that
162
+ * ride `retained_classes[]`. Called once per retained class.
163
+ *
164
+ * Return `null` when nothing resolves — the class is STILL reported as
165
+ * retained (omitting it would understate what survived); it simply carries no
166
+ * `retained_until`.
167
+ */
168
+ schedule?: RetentionScheduleLookup;
93
169
  }
170
+ /** D720 — resolves the statute + expiry for one retained statutory class. */
171
+ export type RetentionScheduleLookup = (args: {
172
+ tenantId: string;
173
+ subjectId: string;
174
+ subjectKind: string;
175
+ dataClass: string;
176
+ }) => Promise<{
177
+ statute_citation?: string;
178
+ retained_until?: string;
179
+ } | null>;
94
180
  /**
95
181
  * Bind a Pattern A service implementation.
96
182
  */
97
183
  export declare function bindPatternA(opts: BindPatternAOpts): DsarServiceImpl;
184
+ /**
185
+ * {@link bindPatternA} with the hold-gate probe AWAITED — the hard boot gate.
186
+ *
187
+ * Identical to `bindPatternA` except that it does not resolve until the probe
188
+ * has succeeded, and REJECTS with {@link HoldGateUnreachableError} when it has
189
+ * not. Use it at boot when a participant that cannot consult holds should fail
190
+ * the deploy rather than serve refusals:
191
+ *
192
+ * ```ts
193
+ * const dsar = await bindPatternAAndVerify({ … }); // throws if holds unreachable
194
+ * ```
195
+ *
196
+ * The synchronous `bindPatternA` remains for callers whose boot path cannot
197
+ * await; they get the same guarantee one step later by awaiting
198
+ * `impl.holdGateReady`, and the same refusal at request time if they do neither.
199
+ */
200
+ export declare function bindPatternAAndVerify(opts: BindPatternAOpts): Promise<DsarServiceImpl>;
201
+ /**
202
+ * The hold-gate probe promise attached to a `bindPatternA` impl.
203
+ *
204
+ * Exposed as a function rather than a typed field because `DsarServiceImpl` is
205
+ * the WIRE descriptor — the 9 RPCs and nothing else — and widening it would
206
+ * declare a 10th method on a shape consumers hand to `server.addService`.
207
+ * Returns an already-resolved promise for impls that carry no probe (Pattern B /
208
+ * Pattern C, which have no hold gate to verify), so a caller can await it
209
+ * unconditionally.
210
+ */
211
+ export declare function holdGateReadyOf(impl: DsarServiceImpl): Promise<void>;
98
212
  export {};
99
213
  //# sourceMappingURL=bind-pattern-a.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"bind-pattern-a.d.ts","sourceRoot":"","sources":["../src/bind-pattern-a.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAahC,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EAIR,aAAa,EAEb,gBAAgB,EAChB,UAAU,EACV,qBAAqB,EACrB,cAAc,EAEf,MAAM,YAAY,CAAC;AAOpB,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACxD;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACnE,CAAC;AAKF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GACb,mBAAmB,CAAC,QAAQ,CAAC,CAI/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,qEAAqE;IACrE,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,0DAA0D;IAC1D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,aAAa,CAAC;IAC7B,iEAAiE;IACjE,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,wCAAwC;IACxC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC9C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CA25BpE"}
1
+ {"version":3,"file":"bind-pattern-a.d.ts","sourceRoot":"","sources":["../src/bind-pattern-a.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAwBhC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EAIR,aAAa,EAEb,gBAAgB,EAChB,UAAU,EAIV,qBAAqB,EACrB,cAAc,EAEf,MAAM,YAAY,CAAC;AA8BpB,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACxD;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACnE,CAAC;AAKF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GACb,mBAAmB,CAAC,QAAQ,CAAC,CAM/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,qEAAqE;IACrE,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,aAAa,CAAC;IAC7B,iEAAiE;IACjE,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,wCAAwC;IACxC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC7C;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,0BAA0B,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC;AAED,6EAA6E;AAC7E,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,KAAK,OAAO,CAAC;IACZ,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,IAAI,CAAC,CAAC;AAEV;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CA68CpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,eAAe,CAAC,CAI1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE"}