@nodii/dsar 0.3.3 → 0.4.1

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.
@@ -1,5 +1,33 @@
1
1
  import { S3Client } from "@aws-sdk/client-s3";
2
2
  import type { AuditEmitter, SubjectKindStr } from "./types";
3
+ /**
4
+ * Serializer hook output. A serializer turns the payload into the bytes to
5
+ * upload + the object metadata (content-type + key suffix). The library ships
6
+ * a default JSON serializer; consumers pass an XLSX / CSV serializer for the
7
+ * billing-spec formats.
8
+ */
9
+ export interface SerializedArtifact {
10
+ body: Uint8Array;
11
+ contentType: string;
12
+ /** Key suffix incl. extension, e.g. `.json`, `.xlsx.gz`, `.csv.gz`. */
13
+ keySuffix: string;
14
+ }
15
+ /**
16
+ * Format/serializer hook. Given the payload, returns the serialized bytes +
17
+ * metadata. Library-default formats are provided (`jsonSerializer`,
18
+ * `gzipJsonSerializer`); consumers register their own for XLSX/CSV.
19
+ */
20
+ export type ArtifactSerializer = (payload: Record<string, unknown>) => SerializedArtifact | Promise<SerializedArtifact>;
21
+ /** Default serializer — canonical JSON, `application/json`, `.json`. */
22
+ export declare const jsonSerializer: ArtifactSerializer;
23
+ /** Gzipped canonical JSON — `application/json` + gzip, `.json.gz`. */
24
+ export declare const gzipJsonSerializer: ArtifactSerializer;
25
+ export interface ObjectLockOpts {
26
+ /** Object Lock mode. Spec uses GOVERNANCE. */
27
+ mode: "GOVERNANCE" | "COMPLIANCE";
28
+ /** Retention window in seconds (spec: 24h staging retention). */
29
+ retainSeconds: number;
30
+ }
3
31
  export interface CreateArtifactOpts {
4
32
  s3Client: S3Client;
5
33
  tenantId: string;
@@ -8,12 +36,55 @@ export interface CreateArtifactOpts {
8
36
  kind: "access" | "portability";
9
37
  payload: Record<string, unknown>;
10
38
  region: string;
39
+ /**
40
+ * v0.4.0 — request id, used in the staging key
41
+ * `{tenant_id}/{request_id}/{filename}` per billing spec. Falls back to a
42
+ * random UUID when omitted (back-compat with the old subject-keyed layout).
43
+ */
44
+ requestId?: string;
45
+ /**
46
+ * v0.4.0 — explicit object key (overrides the computed key). Use for the
47
+ * billing-spec key `{tenant_id}/{request_id}/billing-export.xlsx.gz`.
48
+ */
49
+ key?: string;
50
+ /**
51
+ * v0.4.0 — base filename for the object (the serializer's keySuffix is
52
+ * appended). Defaults to the random-UUID legacy layout when omitted.
53
+ * e.g. `billing-export` → `billing-export.xlsx.gz`.
54
+ */
55
+ filename?: string;
56
+ /**
57
+ * v0.4.0 — format/serializer hook. Defaults to `jsonSerializer`. Pass
58
+ * `gzipJsonSerializer` or a custom XLSX/CSV serializer.
59
+ */
60
+ serializer?: ArtifactSerializer;
11
61
  /** SSE-KMS key id (production); omit for minio dev/test. */
12
62
  kmsKeyId?: string;
13
- /** Optional bucket-name override (production: `nodii-dsar-artifacts-<region>`). */
63
+ /**
64
+ * Bucket-name override (production final: `nodii-dsar-artifacts-<region>`;
65
+ * staging: `nodii-dsar-staging-<region>`).
66
+ */
14
67
  bucketName?: string;
68
+ /**
69
+ * v0.4.0 — write to the per-region STAGING bucket
70
+ * `nodii-dsar-staging-<region>` instead of the final artifacts bucket.
71
+ * Per billing spec [6]. Ignored when `bucketName` is set.
72
+ */
73
+ staging?: boolean;
74
+ /**
75
+ * v0.4.0 — Object Lock retention. Production-only; skipped against minio
76
+ * (which doesn't support it). Spec: GOVERNANCE 24h on the staging bucket.
77
+ */
78
+ objectLock?: ObjectLockOpts;
15
79
  /** 7-day expiry default per spec § 5.7. */
16
80
  expirySeconds?: number;
81
+ /**
82
+ * v0.4.0 — when `true` (default), the returned `presignedUrl` is a
83
+ * GetObject (download) presign — the object is already uploaded (gap 5).
84
+ * Set `false` to skip presigning entirely (the billing spec returns a KEY,
85
+ * not a URL — see `result_artifact_uri=<staging-bucket-key>`).
86
+ */
87
+ presignDownload?: boolean;
17
88
  /** Service name for audit auto-naming. */
18
89
  serviceName?: string;
19
90
  /** Audit emitter — captures bucket+key+size+expiresAt, never the URL. */
@@ -24,19 +95,26 @@ export interface CreateArtifactResult {
24
95
  key: string;
25
96
  size: number;
26
97
  expiresAt: string;
27
- presignedUrl: string;
98
+ /** Presigned GetObject URL — present only when `presignDownload !== false`. */
99
+ presignedUrl?: string;
28
100
  }
29
101
  /**
30
- * Build the canonical bucket name for a region. Spec § 5.7.
102
+ * Build the canonical FINAL bucket name for a region. Spec § 5.7.
31
103
  */
32
104
  export declare function bucketNameForRegion(region: string): string;
105
+ /**
106
+ * v0.4.0 — build the canonical STAGING bucket name for a region per billing
107
+ * spec 505b8c66 [6].
108
+ */
109
+ export declare function stagingBucketNameForRegion(region: string): string;
33
110
  /**
34
111
  * Ensure the bucket exists. In production, infra/Terraform owns this; in
35
112
  * dev/test we create it on-demand against minio.
36
113
  */
37
114
  export declare function ensureBucket(client: S3Client, bucket: string): Promise<void>;
38
115
  /**
39
- * Create an S3 artifact for DSAR access/portability per spec § 5.7.
116
+ * Create an S3 artifact for DSAR access/portability per spec § 5.7 + billing
117
+ * spec 505b8c66 [6].
40
118
  */
41
119
  export declare function createArtifact(opts: CreateArtifactOpts): Promise<CreateArtifactResult>;
42
120
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"s3-artifact.d.ts","sourceRoot":"","sources":["../src/s3-artifact.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,cAAc,CAAC;IAC5B,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,oBAAoB,CAAC,CAwD/B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,QAAQ,CAeX"}
1
+ {"version":3,"file":"s3-artifact.d.ts","sourceRoot":"","sources":["../src/s3-artifact.ts"],"names":[],"mappings":"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"}
@@ -1,26 +1,57 @@
1
- // S3 artifact-lifecycle helper per spec § 5.7 / § 5.10.
1
+ // S3 artifact-lifecycle helper per spec § 5.7 / § 5.10 + locked billing spec
2
+ // 505b8c66 § AccessData [6].
2
3
  //
3
- // `createArtifact(...)` uploads the DSAR access/portability payload to a
4
- // per-region S3 bucket `nodii-dsar-artifacts-<region>` and returns a
5
- // pre-signed URL.
4
+ // `createArtifact(...)` serializes the DSAR access/portability payload and
5
+ // uploads it to a per-region S3 bucket, returning the bucket/key + an
6
+ // optional presigned download URL.
6
7
  //
7
- // In production: SSE-KMS via per-tenant CMK (via @nodii/pii). In dev/test:
8
- // against minio (:9001) which doesn't support SSE-KMS — we skip the SSE-KMS
9
- // param when `kmsKeyId` is undefined.
8
+ // v0.4.0 (request `bc646e4e`):
9
+ // - gap 2 — pluggable format/serializer hook + staging-bucket/key +
10
+ // Object Lock options. The old helper hard-coded JSON / application/json /
11
+ // `.json` to the FINAL bucket with no Object Lock; the billing spec needs
12
+ // XLSX (Access) / CSV + JSON-manifest (Export), gzipped, to the STAGING
13
+ // bucket `nodii-dsar-staging-{region}` key
14
+ // `{tenant_id}/{request_id}/billing-export.xlsx.gz`, per-tenant CMK,
15
+ // Object Lock GOVERNANCE 24h.
16
+ // - gap 5 — presign a GetObject (download) command, not a PutObject
17
+ // (upload), since the object is already uploaded when we presign.
18
+ //
19
+ // In production: SSE-KMS via per-tenant CMK. In dev/test against minio
20
+ // (:9001) which doesn't support SSE-KMS / Object Lock — we skip those params
21
+ // when their key/flag is undefined.
10
22
  //
11
23
  // Audit emission captures `bucket + key + size + expiresAt`; the presigned
12
- // URL is NEVER logged. Audit emitter is optional — callers pass it via
13
- // `auditEmitter`.
24
+ // URL is NEVER logged. Audit emitter is optional.
25
+ import { gzipSync } from "node:zlib";
14
26
  import { randomUUID } from "node:crypto";
15
- import { CreateBucketCommand, HeadBucketCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
27
+ import { CreateBucketCommand, GetObjectCommand, HeadBucketCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
16
28
  import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
17
29
  import { canonicalJson } from "./canonical";
30
+ /** Default serializer — canonical JSON, `application/json`, `.json`. */
31
+ export const jsonSerializer = (payload) => ({
32
+ body: new TextEncoder().encode(canonicalJson(payload)),
33
+ contentType: "application/json",
34
+ keySuffix: ".json",
35
+ });
36
+ /** Gzipped canonical JSON — `application/json` + gzip, `.json.gz`. */
37
+ export const gzipJsonSerializer = (payload) => ({
38
+ body: new Uint8Array(gzipSync(Buffer.from(canonicalJson(payload)))),
39
+ contentType: "application/json",
40
+ keySuffix: ".json.gz",
41
+ });
18
42
  /**
19
- * Build the canonical bucket name for a region. Spec § 5.7.
43
+ * Build the canonical FINAL bucket name for a region. Spec § 5.7.
20
44
  */
21
45
  export function bucketNameForRegion(region) {
22
46
  return `nodii-dsar-artifacts-${region}`;
23
47
  }
48
+ /**
49
+ * v0.4.0 — build the canonical STAGING bucket name for a region per billing
50
+ * spec 505b8c66 [6].
51
+ */
52
+ export function stagingBucketNameForRegion(region) {
53
+ return `nodii-dsar-staging-${region}`;
54
+ }
24
55
  /**
25
56
  * Ensure the bucket exists. In production, infra/Terraform owns this; in
26
57
  * dev/test we create it on-demand against minio.
@@ -44,30 +75,66 @@ export async function ensureBucket(client, bucket) {
44
75
  }
45
76
  }
46
77
  /**
47
- * Create an S3 artifact for DSAR access/portability per spec § 5.7.
78
+ * Create an S3 artifact for DSAR access/portability per spec § 5.7 + billing
79
+ * spec 505b8c66 [6].
48
80
  */
49
81
  export async function createArtifact(opts) {
50
- const bucket = opts.bucketName ?? bucketNameForRegion(opts.region);
82
+ const bucket = opts.bucketName ??
83
+ (opts.staging
84
+ ? stagingBucketNameForRegion(opts.region)
85
+ : bucketNameForRegion(opts.region));
51
86
  const expirySeconds = opts.expirySeconds ?? 7 * 24 * 3600;
52
- const key = `${opts.tenantId}/${opts.subjectId}/${randomUUID()}.json`;
53
- const body = new TextEncoder().encode(canonicalJson(opts.payload));
87
+ const serializer = opts.serializer ?? jsonSerializer;
88
+ const serialized = await serializer(opts.payload);
89
+ // Key resolution (gap 2 — staging key
90
+ // `{tenant_id}/{request_id}/{filename}{suffix}`):
91
+ // 1. explicit `key` wins.
92
+ // 2. `{tenant}/{requestId}/{filename}{suffix}` when requestId+filename set.
93
+ // 3. legacy `{tenant}/{subject}/{uuid}{suffix}` fallback.
94
+ let key;
95
+ if (opts.key) {
96
+ key = opts.key;
97
+ }
98
+ else if (opts.requestId && opts.filename) {
99
+ key = `${opts.tenantId}/${opts.requestId}/${opts.filename}${serialized.keySuffix}`;
100
+ }
101
+ else if (opts.requestId) {
102
+ key = `${opts.tenantId}/${opts.requestId}/${randomUUID()}${serialized.keySuffix}`;
103
+ }
104
+ else {
105
+ key = `${opts.tenantId}/${opts.subjectId}/${randomUUID()}${serialized.keySuffix}`;
106
+ }
107
+ const body = serialized.body;
54
108
  await ensureBucket(opts.s3Client, bucket);
55
109
  const putParams = {
56
110
  Bucket: bucket,
57
111
  Key: key,
58
112
  Body: body,
59
- ContentType: "application/json",
113
+ ContentType: serialized.contentType,
60
114
  };
61
115
  if (opts.kmsKeyId) {
62
116
  putParams.ServerSideEncryption = "aws:kms";
63
117
  putParams.SSEKMSKeyId = opts.kmsKeyId;
64
118
  }
119
+ if (opts.objectLock) {
120
+ // Object Lock requires a versioned bucket with Object Lock enabled
121
+ // (Terraform-owned in production). Skipped against minio dev/test which
122
+ // doesn't support it — set objectLock only in production.
123
+ putParams.ObjectLockMode = opts.objectLock.mode;
124
+ putParams.ObjectLockRetainUntilDate = new Date(Date.now() + opts.objectLock.retainSeconds * 1000);
125
+ }
65
126
  await opts.s3Client.send(new PutObjectCommand(putParams));
66
- // `getSignedUrl` types live in @aws-sdk/s3-request-presigner whose smithy
67
- // pins occasionally diverge from @aws-sdk/client-s3's smithy pins (4.14.1
68
- // vs 4.14.2). Cast at the boundary keeps the call site clean.
69
- // biome-ignore lint/suspicious/noExplicitAny: smithy-type drift between aws-sdk subpackages
70
- const presignedUrl = await getSignedUrl(opts.s3Client, new PutObjectCommand({ Bucket: bucket, Key: key }), { expiresIn: expirySeconds });
127
+ let presignedUrl;
128
+ if (opts.presignDownload !== false) {
129
+ // gap 5 — presign a GetObject (download) URL for the already-uploaded
130
+ // object, NOT a PutObject (upload) presign as the old code did.
131
+ //
132
+ // `getSignedUrl` types live in @aws-sdk/s3-request-presigner whose smithy
133
+ // pins occasionally diverge from @aws-sdk/client-s3's smithy pins. Cast at
134
+ // the boundary keeps the call site clean.
135
+ // biome-ignore lint/suspicious/noExplicitAny: smithy-type drift between aws-sdk subpackages
136
+ presignedUrl = await getSignedUrl(opts.s3Client, new GetObjectCommand({ Bucket: bucket, Key: key }), { expiresIn: expirySeconds });
137
+ }
71
138
  const expiresAt = new Date(Date.now() + expirySeconds * 1000).toISOString();
72
139
  if (opts.auditEmitter && opts.serviceName) {
73
140
  await opts.auditEmitter.emit({
@@ -90,7 +157,7 @@ export async function createArtifact(opts) {
90
157
  key,
91
158
  size: body.byteLength,
92
159
  expiresAt,
93
- presignedUrl,
160
+ ...(presignedUrl !== undefined ? { presignedUrl } : {}),
94
161
  };
95
162
  }
96
163
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"s3-artifact.js","sourceRoot":"","sources":["../src/s3-artifact.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"s3-artifact.js","sourceRoot":"","sources":["../src/s3-artifact.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6BAA6B;AAC7B,EAAE;AACF,2EAA2E;AAC3E,sEAAsE;AACtE,mCAAmC;AACnC,EAAE;AACF,+BAA+B;AAC/B,sEAAsE;AACtE,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,+CAA+C;AAC/C,yEAAyE;AACzE,kCAAkC;AAClC,sEAAsE;AACtE,sEAAsE;AACtE,EAAE;AACF,uEAAuE;AACvE,6EAA6E;AAC7E,oCAAoC;AACpC,EAAE;AACF,2EAA2E;AAC3E,kDAAkD;AAElD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,GACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyB5C,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAAuB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACtD,WAAW,EAAE,kBAAkB;IAC/B,SAAS,EAAE,OAAO;CACnB,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAuB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClE,IAAI,EAAE,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,WAAW,EAAE,kBAAkB;IAC/B,SAAS,EAAE,UAAU;CACtB,CAAC,CAAC;AAiFH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,wBAAwB,MAAM,EAAE,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,OAAO,sBAAsB,MAAM,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAgB,EAChB,MAAc;IAEd,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7D,OAAO;IACT,CAAC;IAAC,MAAM,CAAC;QACP,oBAAoB;IACtB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uCAAuC;QACvC,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,IAAI,CAAC,6CAA6C,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAwB;IAExB,MAAM,MAAM,GACV,IAAI,CAAC,UAAU;QACf,CAAC,IAAI,CAAC,OAAO;YACX,CAAC,CAAC,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC;YACzC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IAE1D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,cAAc,CAAC;IACrD,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAElD,sCAAsC;IACtC,kDAAkD;IAClD,4BAA4B;IAC5B,8EAA8E;IAC9E,4DAA4D;IAC5D,IAAI,GAAW,CAAC;IAChB,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACjB,CAAC;SAAM,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC3C,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;IACrF,CAAC;SAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAC1B,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,UAAU,EAAE,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;IACpF,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,UAAU,EAAE,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;IACpF,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;IAE7B,MAAM,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE1C,MAAM,SAAS,GAAsD;QACnE,MAAM,EAAE,MAAM;QACd,GAAG,EAAE,GAAG;QACR,IAAI,EAAE,IAAI;QACV,WAAW,EAAE,UAAU,CAAC,WAAW;KACpC,CAAC;IACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,SAAS,CAAC,oBAAoB,GAAG,SAAS,CAAC;QAC3C,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC;IACxC,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,mEAAmE;QACnE,wEAAwE;QACxE,0DAA0D;QAC1D,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAChD,SAAS,CAAC,yBAAyB,GAAG,IAAI,IAAI,CAC5C,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,IAAI,CAClD,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC;IAE1D,IAAI,YAAgC,CAAC;IACrC,IAAI,IAAI,CAAC,eAAe,KAAK,KAAK,EAAE,CAAC;QACnC,sEAAsE;QACtE,gEAAgE;QAChE,EAAE;QACF,0EAA0E;QAC1E,2EAA2E;QAC3E,0CAA0C;QAC1C,4FAA4F;QAC5F,YAAY,GAAG,MAAO,YAAoB,CACxC,IAAI,CAAC,QAAQ,EACb,IAAI,gBAAgB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAClD,EAAE,SAAS,EAAE,aAAa,EAAE,CAC7B,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IAE5E,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1C,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;YAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,wBAAwB;YACnD,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,IAAI,CAAC,QAAQ;YACxB,mCAAmC;YACnC,OAAO,EAAE;gBACP,MAAM;gBACN,GAAG;gBACH,IAAI,EAAE,IAAI,CAAC,UAAU;gBACrB,UAAU,EAAE,SAAS;gBACrB,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,MAAM;QACN,GAAG;QACH,IAAI,EAAE,IAAI,CAAC,UAAU;QACrB,SAAS;QACT,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAM5B;IACC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnC,MAAM,GAAG,GAA8C;QACrD,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,WAAW;KACnC,CAAC;IACF,IAAI,IAAI,CAAC,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChD,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS;QACnC,GAAG,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;IAC3C,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;QAC7C,GAAG,CAAC,WAAW,GAAG;YAChB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}
@@ -0,0 +1,65 @@
1
+ import { PostgresLifecycleRequestsStore } from "./postgres-lifecycle";
2
+ type SqlClient = {
3
+ unsafe: (sql: string, args?: unknown[]) => Promise<any>;
4
+ };
5
+ /** Canonical reaper job name per the lib feature_doc metrics family. */
6
+ export declare const LIFECYCLE_REQUESTS_REAPER_JOB_NAME = "dsar.lifecycle_requests_reaper";
7
+ /** Default reaper interval — 24h per doctrine § 5 / lib feature_doc § 5.3. */
8
+ export declare const LIFECYCLE_REQUESTS_REAPER_INTERVAL_MS: number;
9
+ export interface ReaperRunResult {
10
+ /** Rows deleted this run. */
11
+ deleted: number;
12
+ /** ISO-8601 timestamp the run completed. */
13
+ ranAt: string;
14
+ }
15
+ /**
16
+ * A framework-agnostic, schedulable job definition. Hand `name` + `intervalMs`
17
+ * to the consumer's scheduler (BullMQ repeatable, node-cron, etc.) and call
18
+ * `handler()` on each tick.
19
+ */
20
+ export interface ReaperJobDefinition {
21
+ name: string;
22
+ intervalMs: number;
23
+ /**
24
+ * Pool the handler must run under. The DELETE is owner-granted (BYPASSRLS),
25
+ * so the store MUST be owner-pool-backed. Typed reminder for the consumer.
26
+ */
27
+ pool: "owner";
28
+ /** Run one reaper sweep. Returns the delete count + timestamp. */
29
+ handler: () => Promise<ReaperRunResult>;
30
+ }
31
+ export interface MakeReaperJobOpts {
32
+ /**
33
+ * OWNER-pool-backed SQL client (the DELETE is granted only to nodii_owner).
34
+ * Mutually exclusive with `store`.
35
+ */
36
+ sql?: SqlClient;
37
+ /** Pre-built owner-pool store. Mutually exclusive with `sql`. */
38
+ store?: PostgresLifecycleRequestsStore;
39
+ /** Defaults to `lifecycle_requests`. Ignored when `store` is supplied. */
40
+ tableName?: string;
41
+ /** Override the default 24h interval. */
42
+ intervalMs?: number;
43
+ /** Optional hook invoked after each sweep (e.g. metric emission). */
44
+ onRun?: (result: ReaperRunResult) => void | Promise<void>;
45
+ }
46
+ /**
47
+ * Build the schedulable reaper job definition. The consumer registers
48
+ * `{ name, intervalMs }` with its scheduler and calls `handler()` per tick.
49
+ */
50
+ export declare function makeLifecycleRequestsReaperJob(opts: MakeReaperJobOpts): ReaperJobDefinition;
51
+ /** Handle to a running reaper loop. */
52
+ export interface ReaperLoopHandle {
53
+ /** Stop the loop. Idempotent. */
54
+ stop: () => void;
55
+ }
56
+ /**
57
+ * Zero-dependency self-scheduling loop for consumers without a scheduler.
58
+ * Runs `job.handler()` immediately, then every `job.intervalMs`. Errors in a
59
+ * sweep are reported via `onError` (default: swallow + continue) so one bad
60
+ * sweep doesn't kill the loop (lib feature_doc: "reaper job logs error +
61
+ * continues"). Returns a handle to stop it.
62
+ */
63
+ export declare function runReaperLoop(job: ReaperJobDefinition, onError?: (err: unknown) => void): ReaperLoopHandle;
64
+ export {};
65
+ //# sourceMappingURL=reaper-job.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reaper-job.d.ts","sourceRoot":"","sources":["../../src/state-store/reaper-job.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAEtE,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACzD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,kCAAkC,mCACb,CAAC;AAEnC,8EAA8E;AAC9E,eAAO,MAAM,qCAAqC,QAAsB,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,8BAA8B,CAAC;IACvC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,iBAAiB,GACtB,mBAAmB,CA8BrB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,mBAAmB,EACxB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC/B,gBAAgB,CAgClB"}
@@ -0,0 +1,98 @@
1
+ // Runnable reaper job definition — request `626c342a` gap 4.
2
+ //
3
+ // `PostgresLifecycleRequestsStore.runReaperOnce()` deletes lifecycle_requests
4
+ // rows whose `cleanup_after < now()`, but the library shipped only the method
5
+ // — no schedulable job. The lib feature_doc (§ 5.3 + § 5.11.6) promises
6
+ // "Library ships the job definition; consumer wires it into its existing
7
+ // scheduler." This module ships that job definition.
8
+ //
9
+ // The definition is framework-agnostic: it carries the canonical job `name`,
10
+ // the default `intervalMs` (24h per doctrine), and an async `handler`. A
11
+ // consumer registers it with whatever scheduler it runs (BullMQ repeatable
12
+ // job, node-cron, a setInterval loop, k8s CronJob calling a one-shot, etc.).
13
+ // `runReaperLoop` is a zero-dependency self-scheduling loop for consumers
14
+ // without a scheduler.
15
+ //
16
+ // OWNER-pool note: the DELETE on lifecycle_requests is granted only to
17
+ // nodii_owner (BYPASSRLS) per the RLS doctrine — the SqlClient passed here
18
+ // MUST be backed by the owner pool, not the per-tenant services pool. The
19
+ // job carries `pool: "owner"` as a typed reminder + the consumer is
20
+ // responsible for supplying an owner-pool-backed store.
21
+ import { PostgresLifecycleRequestsStore } from "./postgres-lifecycle";
22
+ /** Canonical reaper job name per the lib feature_doc metrics family. */
23
+ export const LIFECYCLE_REQUESTS_REAPER_JOB_NAME = "dsar.lifecycle_requests_reaper";
24
+ /** Default reaper interval — 24h per doctrine § 5 / lib feature_doc § 5.3. */
25
+ export const LIFECYCLE_REQUESTS_REAPER_INTERVAL_MS = 24 * 60 * 60 * 1000;
26
+ /**
27
+ * Build the schedulable reaper job definition. The consumer registers
28
+ * `{ name, intervalMs }` with its scheduler and calls `handler()` per tick.
29
+ */
30
+ export function makeLifecycleRequestsReaperJob(opts) {
31
+ if (!opts.sql && !opts.store) {
32
+ throw new Error("makeLifecycleRequestsReaperJob requires `sql` (owner pool) or `store`.");
33
+ }
34
+ const store = opts.store ??
35
+ new PostgresLifecycleRequestsStore({
36
+ // biome-ignore lint/style/noNonNullAssertion: guarded above
37
+ sql: opts.sql,
38
+ ...(opts.tableName !== undefined ? { tableName: opts.tableName } : {}),
39
+ });
40
+ const handler = async () => {
41
+ const deleted = await store.runReaperOnce();
42
+ const result = {
43
+ deleted,
44
+ ranAt: new Date().toISOString(),
45
+ };
46
+ if (opts.onRun)
47
+ await opts.onRun(result);
48
+ return result;
49
+ };
50
+ return {
51
+ name: LIFECYCLE_REQUESTS_REAPER_JOB_NAME,
52
+ intervalMs: opts.intervalMs ?? LIFECYCLE_REQUESTS_REAPER_INTERVAL_MS,
53
+ pool: "owner",
54
+ handler,
55
+ };
56
+ }
57
+ /**
58
+ * Zero-dependency self-scheduling loop for consumers without a scheduler.
59
+ * Runs `job.handler()` immediately, then every `job.intervalMs`. Errors in a
60
+ * sweep are reported via `onError` (default: swallow + continue) so one bad
61
+ * sweep doesn't kill the loop (lib feature_doc: "reaper job logs error +
62
+ * continues"). Returns a handle to stop it.
63
+ */
64
+ export function runReaperLoop(job, onError) {
65
+ let stopped = false;
66
+ let timer = null;
67
+ const tick = async () => {
68
+ if (stopped)
69
+ return;
70
+ try {
71
+ await job.handler();
72
+ }
73
+ catch (err) {
74
+ if (onError)
75
+ onError(err);
76
+ }
77
+ if (stopped)
78
+ return;
79
+ timer = setTimeout(() => {
80
+ void tick();
81
+ }, job.intervalMs);
82
+ // Don't keep the event loop alive solely for the reaper.
83
+ if (typeof timer === "object" && timer && "unref" in timer) {
84
+ timer.unref();
85
+ }
86
+ };
87
+ void tick();
88
+ return {
89
+ stop: () => {
90
+ stopped = true;
91
+ if (timer) {
92
+ clearTimeout(timer);
93
+ timer = null;
94
+ }
95
+ },
96
+ };
97
+ }
98
+ //# sourceMappingURL=reaper-job.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reaper-job.js","sourceRoot":"","sources":["../../src/state-store/reaper-job.ts"],"names":[],"mappings":"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"}
package/dist/types.d.ts CHANGED
@@ -179,6 +179,13 @@ export interface LifecycleResponse {
179
179
  result_artifact_uri?: string;
180
180
  expires_at?: string;
181
181
  statute_citation?: string;
182
+ /**
183
+ * v0.4.0 — RectifyData: number of corrections applied to the subject's live
184
+ * PII (Art. 16). Per locked billing spec 505b8c66 § RectifyData [4]
185
+ * (`corrections_applied=count`); surfaced to the wire so the orchestrator
186
+ * can record it. Absent for non-rectify RPCs.
187
+ */
188
+ corrections_applied?: number;
182
189
  }
183
190
  /** Five subject kinds matching the proto SubjectKind enum (excluding UNSPECIFIED). */
184
191
  export type SubjectKindStr = "user" | "employee" | "customer" | "platform_admin" | "tenant";
@@ -191,11 +198,29 @@ export interface PatternAEnvelope {
191
198
  reason: string;
192
199
  requested_by: string;
193
200
  }
194
- /** Pattern A handler set — five GDPR-right callbacks per spec § 5.1. */
201
+ /**
202
+ * Pattern A handler set — five GDPR-right callbacks per spec § 5.1.
203
+ *
204
+ * v0.4.0 (request `bc646e4e`):
205
+ * - `access` + `portability` return `result_artifact_uri?` so the
206
+ * staging-bucket key reaches `LifecycleResponse.result_artifact_uri`
207
+ * (locked billing spec 505b8c66 § AccessData [7]). The old shape had no
208
+ * channel — the binding discarded the return + hard-coded
209
+ * `{status:COMPLETED, reason:''}`, silently dropping the export locator.
210
+ * - `access` receives `region` (resolved from tenant residency by the
211
+ * orchestrator / consumer) so the per-region staging bucket can be
212
+ * selected — billing spec mandates a per-region staging bucket for BOTH
213
+ * Access and Portability.
214
+ * - `rectify` returns `corrections_applied?` (count) + may report
215
+ * `status:'partial'` so the PARTIAL wire path surfaces.
216
+ */
195
217
  export interface PatternAHandlers {
196
- access(env: PatternAEnvelope): Promise<{
218
+ access(env: PatternAEnvelope & {
219
+ region: string;
220
+ }): Promise<{
197
221
  status: string;
198
222
  payload?: Record<string, unknown>;
223
+ result_artifact_uri?: string;
199
224
  }>;
200
225
  erase(env: PatternAEnvelope & {
201
226
  scope: "subject" | "tenant";
@@ -208,12 +233,14 @@ export interface PatternAHandlers {
208
233
  }): Promise<{
209
234
  status: string;
210
235
  artifactId?: string;
236
+ corrections_applied?: number;
211
237
  }>;
212
238
  portability(env: PatternAEnvelope & {
213
239
  region: string;
214
240
  }): Promise<{
215
241
  status: string;
216
242
  payload?: Record<string, unknown>;
243
+ result_artifact_uri?: string;
217
244
  }>;
218
245
  restrict(env: PatternAEnvelope & {
219
246
  restriction_kind: string;
@@ -231,6 +258,12 @@ export interface RetentionHoldHandlers {
231
258
  statute_citation: string;
232
259
  expires_at?: string;
233
260
  requested_by: string;
261
+ /** v0.4.0 — statutory hold kind (defaults to `erase` gate when absent). */
262
+ hold_kind?: HoldKind;
263
+ /** v0.4.0 — data-class the hold scopes to. */
264
+ data_class?: string;
265
+ /** v0.4.0 — dedupe key for idempotent auto-holds. */
266
+ hold_request_id?: string;
234
267
  }): Promise<{
235
268
  status: string;
236
269
  }>;
@@ -245,11 +278,51 @@ export interface RetentionHoldHandlers {
245
278
  status: string;
246
279
  }>;
247
280
  }
281
+ /**
282
+ * Canonical retention `hold_kind` set.
283
+ *
284
+ * The original `@nodii/dsar` modelled `hold_kind` as the gate-*action* axis
285
+ * (`erase` | `restrict`). The locked billing DSAR spec (feature_doc
286
+ * `505b8c66` § "Holds block EraseData") models it as the statutory-*reason*
287
+ * axis (`legal` | `compliance` | `business` | `aml_regulatory`). A
288
+ * `hold_kind='aml_regulatory'` row was NEVER matched by the old
289
+ * `erase`-only gate → silent statutory-retention bypass (request `626c342a`
290
+ * gap 1).
291
+ *
292
+ * v0.4.0 widens the union to carry BOTH axes so the gate matches every
293
+ * blocking kind. Back-compat: `erase`/`restrict` keep their original
294
+ * semantics (`erase` = blocks the erase path, `restrict` = blocks the
295
+ * restrict path); the four statutory kinds default to blocking erase per the
296
+ * billing spec CHECK.
297
+ */
298
+ export type HoldKind = "erase" | "restrict" | "legal" | "compliance" | "business" | "aml_regulatory";
299
+ /**
300
+ * The hold kinds that block an `EraseData` request by default.
301
+ *
302
+ * Everything except the legacy `restrict` gate-action (which blocks the
303
+ * RESTRICT path, not erase). A `data_residency_holds` row with any of these
304
+ * kinds, unlifted + unexpired + (data_class-matching when filtered), blocks
305
+ * erase. Per request `626c342a` gap 1 + locked billing spec 505b8c66.
306
+ */
307
+ export declare const DEFAULT_ERASE_BLOCKING_HOLD_KINDS: readonly HoldKind[];
308
+ /** The four statutory hold kinds per the billing-spec `hold_kind_valid` CHECK. */
309
+ export declare const STATUTORY_HOLD_KINDS: readonly HoldKind[];
310
+ /**
311
+ * Hold kinds for which a `statute_citation` is mandatory per the billing-spec
312
+ * `legal_basis_required_for_statutory_holds` CHECK
313
+ * (`hold_kind NOT IN ('legal','aml_regulatory') OR statute_citation IS NOT NULL`).
314
+ */
315
+ export declare const CITATION_REQUIRED_HOLD_KINDS: readonly HoldKind[];
248
316
  /**
249
317
  * Hold consult result returned by `isHeld`. Spec § 5.8.
318
+ *
319
+ * v0.4.0 adds `hold_kind` so callers can surface which statutory kind blocked
320
+ * the erase (the billing spec returns `hold_kind` + `held_until` +
321
+ * `legal_basis_citation` in the `held` reason).
250
322
  */
251
323
  export interface HoldConsultResult {
252
324
  held: boolean;
325
+ hold_kind?: HoldKind;
253
326
  statute_citation?: string;
254
327
  expires_at?: string;
255
328
  }
@@ -264,7 +337,12 @@ export interface ActiveHold {
264
337
  tenant_id: string;
265
338
  /** null when this is a tenant-level hold (no subject filter). */
266
339
  subject_id: string | null;
267
- hold_kind: "erase" | "restrict";
340
+ hold_kind: HoldKind;
341
+ /**
342
+ * v0.4.0 — data-class the hold scopes to (e.g. `billing_invoice_pii`).
343
+ * null for legacy rows / kind-only holds. Per billing spec 505b8c66.
344
+ */
345
+ data_class: string | null;
268
346
  statute_citation: string;
269
347
  placed_by: string;
270
348
  /** ISO-8601 UTC, microsecond precision. */
@@ -291,7 +369,7 @@ export interface ListActiveHoldsRequest {
291
369
  /** Optional narrowing filter; absence = "any subject". */
292
370
  subject_id?: string;
293
371
  /** Optional narrowing filter; absence = "any hold kind". */
294
- hold_kind?: "erase" | "restrict";
372
+ hold_kind?: HoldKind;
295
373
  requested_by: string;
296
374
  }
297
375
  /**