dpdp-kit 0.1.2 → 0.3.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.
- package/CHANGELOG.md +37 -0
- package/README.md +229 -13
- package/dist/access.d.ts +106 -0
- package/dist/audit.d.ts +3 -1
- package/dist/chunk-5TVA2TKG.js +37 -0
- package/dist/chunk-YOEAZX65.js +937 -0
- package/dist/cli.js +48 -10
- package/dist/config.d.ts +79 -0
- package/dist/data-access.d.ts +23 -0
- package/dist/dpdp.d.ts +206 -3
- package/dist/drizzle.d.ts +684 -4
- package/dist/drizzle.js +349 -6
- package/dist/erasure.d.ts +2 -1
- package/dist/errors.d.ts +1 -1
- package/dist/express.d.ts +17 -1
- package/dist/express.js +10 -2
- package/dist/fastify.d.ts +41 -0
- package/dist/fastify.js +25 -0
- package/dist/guard.d.ts +19 -0
- package/dist/hono.d.ts +16 -1
- package/dist/hono.js +11 -2
- package/dist/index.d.ts +11 -5
- package/dist/index.js +482 -51
- package/dist/nestjs.d.ts +65 -0
- package/dist/nestjs.js +41 -0
- package/dist/protect.d.ts +74 -0
- package/dist/protect.js +114 -0
- package/dist/records.d.ts +124 -0
- package/dist/retention.d.ts +47 -0
- package/dist/rights.d.ts +49 -0
- package/dist/run-audit.d.ts +14 -0
- package/dist/safeguards.d.ts +23 -0
- package/dist/schedule.d.ts +37 -0
- package/dist/schedule.js +66 -0
- package/dist/schema-check.d.ts +5 -7
- package/dist/store.d.ts +16 -2
- package/package.json +35 -4
- package/dist/chunk-FGZAH2NF.js +0 -16
- package/dist/chunk-MX5FRZQT.js +0 -455
package/dist/cli.js
CHANGED
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {
|
|
3
3
|
audit,
|
|
4
|
-
checkSchema
|
|
5
|
-
|
|
4
|
+
checkSchema,
|
|
5
|
+
formatSafeguards,
|
|
6
|
+
safeguardsReport
|
|
7
|
+
} from "./chunk-YOEAZX65.js";
|
|
8
|
+
import "./chunk-67Q5GFD6.js";
|
|
6
9
|
|
|
7
10
|
// src/run-audit.ts
|
|
8
11
|
import { existsSync } from "fs";
|
|
9
|
-
import { resolve } from "path";
|
|
12
|
+
import { relative, resolve } from "path";
|
|
10
13
|
import { pathToFileURL } from "url";
|
|
11
14
|
var CONFIG_FILES = ["dpdp.config.ts", "dpdp.config.mts", "dpdp.config.js", "dpdp.config.mjs"];
|
|
12
15
|
function findConfig(cwd, explicit) {
|
|
@@ -39,6 +42,15 @@ function formatIssues(issues) {
|
|
|
39
42
|
lines.push("", `${errors.length} error(s), ${warnings.length} warning(s)`);
|
|
40
43
|
return lines.join("\n");
|
|
41
44
|
}
|
|
45
|
+
var escapeData = (text) => text.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
|
|
46
|
+
var escapeProperty = (text) => escapeData(text).replace(/:/g, "%3A").replace(/,/g, "%2C");
|
|
47
|
+
function formatGithubAnnotations(issues, files, root) {
|
|
48
|
+
return issues.map((issue) => {
|
|
49
|
+
const file = issue.path.startsWith("schema.") && files.schema ? files.schema : files.config;
|
|
50
|
+
const props = [`file=${escapeProperty(relative(root, file))}`, `title=${escapeProperty(`dpdp-kit: ${issue.path}`)}`];
|
|
51
|
+
return `::${issue.level} ${props.join(",")}::${escapeData(issue.message)}`;
|
|
52
|
+
}).join("\n");
|
|
53
|
+
}
|
|
42
54
|
async function loadDrizzleSchema(file) {
|
|
43
55
|
const mod = await loadModule(file);
|
|
44
56
|
let drizzleSchema;
|
|
@@ -57,15 +69,23 @@ var flagValue = (argv, flag) => {
|
|
|
57
69
|
const i = argv.indexOf(flag);
|
|
58
70
|
return i >= 0 ? argv[i + 1] : void 0;
|
|
59
71
|
};
|
|
60
|
-
|
|
72
|
+
function configFile(argv, cwd, log) {
|
|
61
73
|
const explicit = flagValue(argv, "--config");
|
|
74
|
+
const file = findConfig(cwd, explicit);
|
|
75
|
+
if (file && existsSync(file)) return file;
|
|
76
|
+
log(explicit ? `Config file not found: ${explicit}` : `No config found. Create one of: ${CONFIG_FILES.join(", ")}`);
|
|
77
|
+
return void 0;
|
|
78
|
+
}
|
|
79
|
+
async function runAudit(argv, cwd, log) {
|
|
62
80
|
const schemaFlag = flagValue(argv, "--schema");
|
|
63
81
|
const strict = argv.includes("--strict");
|
|
64
|
-
const
|
|
65
|
-
if (
|
|
66
|
-
log(
|
|
82
|
+
const format = flagValue(argv, "--format") ?? "text";
|
|
83
|
+
if (format !== "text" && format !== "github") {
|
|
84
|
+
log(`Unknown --format ${JSON.stringify(format)}. Use "text" or "github".`);
|
|
67
85
|
return 1;
|
|
68
86
|
}
|
|
87
|
+
const file = configFile(argv, cwd, log);
|
|
88
|
+
if (!file) return 1;
|
|
69
89
|
const schemaFile = schemaFlag ? resolve(cwd, schemaFlag) : void 0;
|
|
70
90
|
if (schemaFile && !existsSync(schemaFile)) {
|
|
71
91
|
log(`Schema file not found: ${schemaFlag}`);
|
|
@@ -74,16 +94,28 @@ async function runAudit(argv, cwd, log) {
|
|
|
74
94
|
const config = await loadConfig(file);
|
|
75
95
|
const issues = audit(config);
|
|
76
96
|
if (schemaFile) issues.push(...checkSchema(config, await loadDrizzleSchema(schemaFile)));
|
|
97
|
+
if (format === "github" && issues.length > 0) {
|
|
98
|
+
log(formatGithubAnnotations(issues, { config: file, schema: schemaFile }, process.env.GITHUB_WORKSPACE ?? cwd));
|
|
99
|
+
}
|
|
77
100
|
log(formatIssues(issues));
|
|
78
101
|
const failing = issues.filter((i) => i.level === "error" || strict && i.level === "warning");
|
|
79
102
|
return failing.length > 0 ? 1 : 0;
|
|
80
103
|
}
|
|
104
|
+
async function runSafeguards(argv, cwd, log) {
|
|
105
|
+
const file = configFile(argv, cwd, log);
|
|
106
|
+
if (!file) return 1;
|
|
107
|
+
const report = safeguardsReport(await loadConfig(file));
|
|
108
|
+
log(formatSafeguards(report));
|
|
109
|
+
const gaps = report.some((s) => s.status === "missing" || s.status === "partly");
|
|
110
|
+
return argv.includes("--strict") && gaps ? 1 : 0;
|
|
111
|
+
}
|
|
81
112
|
|
|
82
113
|
// src/cli.ts
|
|
83
114
|
var HELP = `dpdp-kit \u2014 DPDP Act tooling for Node.js
|
|
84
115
|
|
|
85
116
|
Usage:
|
|
86
|
-
dpdp-kit audit [--config <file>] [--schema <file>] [--strict]
|
|
117
|
+
dpdp-kit audit [--config <file>] [--schema <file>] [--strict] [--format text|github]
|
|
118
|
+
dpdp-kit safeguards [--config <file>] [--strict]
|
|
87
119
|
|
|
88
120
|
Checks your data map and purposes. With --schema, also compares the data map with your
|
|
89
121
|
Drizzle schema: personal-looking columns missing from the map, and map entries that no
|
|
@@ -93,10 +125,16 @@ Options:
|
|
|
93
125
|
--config <file> Config file (default: dpdp.config.ts / .mts / .js / .mjs)
|
|
94
126
|
--schema <file> Drizzle schema file (Postgres, MySQL or SQLite), e.g. src/db/schema.ts
|
|
95
127
|
--strict Fail on warnings too
|
|
128
|
+
--format github Also print GitHub Actions annotations, so problems show on the pull request
|
|
129
|
+
|
|
130
|
+
safeguards reports each security safeguard of Rule 6(1), (a) to (g): what your config records
|
|
131
|
+
and what's missing. With --strict, exits 1 when one is missing.
|
|
96
132
|
`;
|
|
97
133
|
var [command, ...rest] = process.argv.slice(2);
|
|
98
|
-
|
|
99
|
-
|
|
134
|
+
var commands = { audit: runAudit, safeguards: runSafeguards };
|
|
135
|
+
var run = command !== void 0 && Object.hasOwn(commands, command) ? commands[command] : void 0;
|
|
136
|
+
if (run) {
|
|
137
|
+
run(rest, process.cwd(), (line) => console.log(line)).then(
|
|
100
138
|
(code) => {
|
|
101
139
|
process.exitCode = code;
|
|
102
140
|
},
|
package/dist/config.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Duration } from "./duration.js";
|
|
2
|
+
import type { RequestType } from "./records.js";
|
|
2
3
|
/**
|
|
3
4
|
* Why you may process data for a purpose.
|
|
4
5
|
* - `"consent"`: the person agreed (Section 6(1)). They can withdraw at any time, as easily as
|
|
@@ -33,12 +34,50 @@ export interface PurposeDef {
|
|
|
33
34
|
}
|
|
34
35
|
/** Kind of personal data. Free text is allowed; these are the common ones. */
|
|
35
36
|
export type Category = "contact" | "identity" | "financial" | "health" | "location" | "device" | "biometric" | "behavioural" | (string & {});
|
|
37
|
+
/**
|
|
38
|
+
* How a field is protected where it's stored. Rule 6(1)(a) of the DPDP Rules lists "encryption,
|
|
39
|
+
* obfuscation, masking or the use of virtual tokens mapped to that personal data" as safeguards.
|
|
40
|
+
* - `"encrypted"`: stored encrypted (e.g. with `createEncryptor` from `dpdp-kit/protect`).
|
|
41
|
+
* - `"tokenised"`: replaced by a token that maps to the value kept elsewhere (a vault).
|
|
42
|
+
* - `"masked"`: only a masked form is stored (e.g. the last four digits of an Aadhaar number).
|
|
43
|
+
* - `"hashed"`: only a keyed hash is stored, for matching (e.g. `createTokenizer`).
|
|
44
|
+
*/
|
|
45
|
+
export type Protection = "encrypted" | "tokenised" | "masked" | "hashed";
|
|
46
|
+
/** A value a field can be set to when it's erased. */
|
|
47
|
+
export type ErasedValue = string | number | boolean | null;
|
|
48
|
+
/** Text written by `erase: "redact"`. */
|
|
49
|
+
export declare const REDACTED = "[erased]";
|
|
50
|
+
/**
|
|
51
|
+
* What a field becomes when it's erased. Default `"null"`.
|
|
52
|
+
* - `"null"`: set to `NULL`. The column must be nullable.
|
|
53
|
+
* - `"redact"`: set to the text `"[erased]"`, for `NOT NULL` text columns.
|
|
54
|
+
* - `{ value }`: a fixed value, or a function of the person and field, for columns with other
|
|
55
|
+
* constraints, e.g. a `NOT NULL UNIQUE` email:
|
|
56
|
+
* `{ value: ({ subjectId }) => \`erased-${subjectId}@invalid\` }`.
|
|
57
|
+
*
|
|
58
|
+
* The replacement must not identify the person: use their internal id, never a hash of their data.
|
|
59
|
+
*/
|
|
60
|
+
export type EraseWith = "null" | "redact" | {
|
|
61
|
+
value: ErasedValue | ((field: {
|
|
62
|
+
subjectId: string;
|
|
63
|
+
table: string;
|
|
64
|
+
field: string;
|
|
65
|
+
}) => ErasedValue);
|
|
66
|
+
};
|
|
36
67
|
export interface PersonalField<P extends string = string> {
|
|
37
68
|
category: Category;
|
|
38
69
|
/** Every purpose this field is held for. When all of them end, the field must go. */
|
|
39
70
|
purposes: readonly P[];
|
|
40
71
|
/** This field can tell you the person is under 18 (e.g. date of birth). Used from v0.3. */
|
|
41
72
|
childSignal?: boolean;
|
|
73
|
+
/**
|
|
74
|
+
* How the field is protected at rest (Rule 6(1)(a)). The audit warns when a high-risk
|
|
75
|
+
* identifier (Aadhaar, PAN, passport, bank account, card number, health or biometric data)
|
|
76
|
+
* has none.
|
|
77
|
+
*/
|
|
78
|
+
protect?: Protection;
|
|
79
|
+
/** What the field becomes when it's erased. Default `"null"`. See `EraseWith`. */
|
|
80
|
+
erase?: EraseWith;
|
|
42
81
|
}
|
|
43
82
|
/**
|
|
44
83
|
* Another law says you must keep these rows (e.g. tax or KYC records). Section 8(7) requires
|
|
@@ -62,6 +101,37 @@ export interface TableDef<P extends string = string> {
|
|
|
62
101
|
export interface ProcessorDef<P extends string = string> {
|
|
63
102
|
purposes: readonly P[];
|
|
64
103
|
description?: string;
|
|
104
|
+
/**
|
|
105
|
+
* Where your contract with this processor requires reasonable security safeguards, e.g.
|
|
106
|
+
* `"DPA signed 2026-03-01, clause 7"`. Rule 6(1)(f) requires such a provision. The audit warns
|
|
107
|
+
* when it's missing.
|
|
108
|
+
*/
|
|
109
|
+
contract?: string;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* The security safeguards of Rule 6(1) that live outside your code, written down as evidence.
|
|
113
|
+
* Describe what you actually do, in a sentence; the audit warns about any you leave out.
|
|
114
|
+
*/
|
|
115
|
+
export interface SecurityConfig {
|
|
116
|
+
/** Rule 6(1)(b): how access to your computer resources is controlled, e.g. `"SSO, least-privilege IAM roles"`. */
|
|
117
|
+
accessControl?: string;
|
|
118
|
+
/** Rule 6(1)(d): how processing continues after a compromise, e.g. `"Daily encrypted backups, restore tested monthly"`. */
|
|
119
|
+
backups?: string;
|
|
120
|
+
/** Rule 6(1)(g): technical and organisational measures, e.g. `"Annual security training, quarterly access reviews"`. */
|
|
121
|
+
measures?: string;
|
|
122
|
+
/**
|
|
123
|
+
* Rule 6(1)(c) and (e): how long the access log (`dpdp.access`) is kept. Default and minimum
|
|
124
|
+
* `"1y"`: the Rule requires a year of logs to detect and investigate unauthorised access.
|
|
125
|
+
*/
|
|
126
|
+
accessLogRetention?: Duration;
|
|
127
|
+
}
|
|
128
|
+
export interface RightsConfig {
|
|
129
|
+
/**
|
|
130
|
+
* How long you give yourself to answer a rights request, from when it's raised. One duration for
|
|
131
|
+
* every type, or one per type. Default `"90d"`. Rule 14(3) of the DPDP Rules caps grievance
|
|
132
|
+
* responses at ninety days; the Rules set no period for the other types, so pick one you can keep.
|
|
133
|
+
*/
|
|
134
|
+
responseWithin?: Duration | Partial<Record<RequestType, Duration>>;
|
|
65
135
|
}
|
|
66
136
|
export interface FiduciaryDef {
|
|
67
137
|
name: string;
|
|
@@ -97,6 +167,9 @@ export interface DpdpConfig<P extends string = string> {
|
|
|
97
167
|
* or `"products.*"` for a whole table. Use database table and column names.
|
|
98
168
|
*/
|
|
99
169
|
notPersonal?: readonly string[];
|
|
170
|
+
rights?: RightsConfig;
|
|
171
|
+
/** Security safeguards under Rule 6(1). See `SecurityConfig`. */
|
|
172
|
+
security?: SecurityConfig;
|
|
100
173
|
}
|
|
101
174
|
/** Purpose names of a config, e.g. `"account" | "marketing_sms"`. */
|
|
102
175
|
export type PurposeOf<C> = C extends DpdpConfig<infer P> ? P : never;
|
|
@@ -106,3 +179,9 @@ export type PurposeOf<C> = C extends DpdpConfig<infer P> ? P : never;
|
|
|
106
179
|
*/
|
|
107
180
|
export declare function defineConfig<const P extends string>(config: DpdpConfig<P>): DpdpConfig<P>;
|
|
108
181
|
export declare function purposeNames<P extends string>(config: DpdpConfig<P>): P[];
|
|
182
|
+
/** The value a field is set to when it's erased, from its `erase` setting. */
|
|
183
|
+
export declare function erasedValue(erase: EraseWith | undefined, field: {
|
|
184
|
+
subjectId: string;
|
|
185
|
+
table: string;
|
|
186
|
+
field: string;
|
|
187
|
+
}): ErasedValue;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { ErasedValue } from "./config.js";
|
|
2
|
+
/**
|
|
3
|
+
* How dpdp-kit reaches the personal data in your own tables: to show a person what you hold
|
|
4
|
+
* (Section 11) and to carry out erasure (Section 8(7)). Names are as written in the data map
|
|
5
|
+
* (`config.data[...].table`, `subject` and field names); an implementation maps them to columns.
|
|
6
|
+
*/
|
|
7
|
+
export interface DataAccess {
|
|
8
|
+
/** The person's rows, with only the listed columns. */
|
|
9
|
+
read(table: string, subjectColumn: string, subjectId: string, columns: readonly string[]): Promise<Record<string, unknown>[]>;
|
|
10
|
+
/**
|
|
11
|
+
* Erase the listed columns in the person's rows: set each to its value in `values`, or to null
|
|
12
|
+
* when it has none (the field's `erase` setting in the config). Returns rows changed.
|
|
13
|
+
*/
|
|
14
|
+
eraseFields(table: string, subjectColumn: string, subjectId: string, columns: readonly string[], values?: Readonly<Record<string, ErasedValue>>): Promise<number>;
|
|
15
|
+
/** Delete the person's rows. Returns rows deleted. */
|
|
16
|
+
deleteRows(table: string, subjectColumn: string, subjectId: string): Promise<number>;
|
|
17
|
+
}
|
|
18
|
+
type Row = Record<string, unknown>;
|
|
19
|
+
/** Data access over plain arrays, for tests and examples. */
|
|
20
|
+
export declare function memoryData(tables: Record<string, Row[]>): DataAccess & {
|
|
21
|
+
readonly tables: Record<string, Row[]>;
|
|
22
|
+
};
|
|
23
|
+
export {};
|
package/dist/dpdp.d.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
|
+
import { type AccessAction, type AccessEntry, type AccessFilter, type AccessReview } from "./access.js";
|
|
1
2
|
import type { DpdpConfig } from "./config.js";
|
|
3
|
+
import type { DataAccess } from "./data-access.js";
|
|
4
|
+
import { type Duration } from "./duration.js";
|
|
2
5
|
import { type ErasurePlan } from "./erasure.js";
|
|
3
6
|
import { type NoticeLanguage } from "./languages.js";
|
|
4
|
-
import type
|
|
7
|
+
import { type ErasureTask, type RequestFilter, type RequestType, type RightsRequest, type TaskFilter } from "./records.js";
|
|
8
|
+
import { type ProcessorHooks, type RunReport } from "./retention.js";
|
|
9
|
+
import { type AccessSummary } from "./rights.js";
|
|
10
|
+
import { type ConsentEvent, type ConsentStore } from "./store.js";
|
|
5
11
|
export interface ConsentMeta {
|
|
6
12
|
noticeVersion?: string;
|
|
7
13
|
language?: NoticeLanguage;
|
|
@@ -17,26 +23,147 @@ export type VerifyResult = {
|
|
|
17
23
|
brokenAt: number;
|
|
18
24
|
reason: "hash-mismatch" | "chain-broken" | "seq-gap";
|
|
19
25
|
};
|
|
26
|
+
export interface AccessInput<P extends string> {
|
|
27
|
+
/** Who is accessing the data: a staff user's id, a service or job name. */
|
|
28
|
+
actor: string;
|
|
29
|
+
/** Whose data. Pass `subjectIds` instead for a list or an export. */
|
|
30
|
+
subjectId?: string;
|
|
31
|
+
subjectIds?: readonly string[];
|
|
32
|
+
/** Why: one of your purposes. */
|
|
33
|
+
purpose: P;
|
|
34
|
+
/** Default `"read"`. */
|
|
35
|
+
action?: AccessAction;
|
|
36
|
+
/**
|
|
37
|
+
* What is accessed, as data map keys: `"users.phone"`, or `"users"` / `"users.*"` for every
|
|
38
|
+
* personal field of a table. Fields not held for `purpose` are recorded as `outOfPurpose`.
|
|
39
|
+
*/
|
|
40
|
+
fields?: readonly string[];
|
|
41
|
+
/** Free text, e.g. a support ticket number. */
|
|
42
|
+
reason?: string;
|
|
43
|
+
/** Details of the request, e.g. IP address, user agent, request id. */
|
|
44
|
+
evidence?: Record<string, string>;
|
|
45
|
+
}
|
|
46
|
+
export interface AccessOptions {
|
|
47
|
+
/**
|
|
48
|
+
* What to do when a log entry reads fields that aren't held for its purpose. `"record"` (default)
|
|
49
|
+
* logs it with `outOfPurpose` for `review()` to report; `"throw"` logs it, then throws
|
|
50
|
+
* `DpdpError("out-of-purpose")` so the caller can refuse.
|
|
51
|
+
*/
|
|
52
|
+
outOfPurpose?: "record" | "throw";
|
|
53
|
+
}
|
|
54
|
+
/** What each event carries. Events fire after the change is saved. */
|
|
55
|
+
export interface DpdpEvents {
|
|
56
|
+
"consent.granted": {
|
|
57
|
+
event: ConsentEvent;
|
|
58
|
+
};
|
|
59
|
+
"consent.withdrawn": {
|
|
60
|
+
event: ConsentEvent;
|
|
61
|
+
erasure: ErasurePlan;
|
|
62
|
+
tasks: ErasureTask[];
|
|
63
|
+
};
|
|
64
|
+
"erasure.scheduled": {
|
|
65
|
+
plan: ErasurePlan;
|
|
66
|
+
tasks: ErasureTask[];
|
|
67
|
+
};
|
|
68
|
+
"retention.ran": {
|
|
69
|
+
report: RunReport;
|
|
70
|
+
};
|
|
71
|
+
"rights.opened": {
|
|
72
|
+
request: RightsRequest;
|
|
73
|
+
};
|
|
74
|
+
"rights.closed": {
|
|
75
|
+
request: RightsRequest;
|
|
76
|
+
};
|
|
77
|
+
"access.logged": {
|
|
78
|
+
entries: AccessEntry[];
|
|
79
|
+
};
|
|
80
|
+
"daily.ran": {
|
|
81
|
+
report: DailyReport;
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
/** What `daily()` did. A part the store can't do (a custom store without the access log) is listed in `skipped`. */
|
|
85
|
+
export interface DailyReport {
|
|
86
|
+
/** When the run started (ISO 8601). */
|
|
87
|
+
at: string;
|
|
88
|
+
/** Erasure tasks carried out by `retention.run()`. */
|
|
89
|
+
retention?: RunReport;
|
|
90
|
+
/** Access log entries older than the retention period, deleted by `access.prune()`. */
|
|
91
|
+
accessPruned?: number;
|
|
92
|
+
/** `access.review()` of the last day. */
|
|
93
|
+
review?: AccessReview;
|
|
94
|
+
/** Open rights requests past their due date. */
|
|
95
|
+
overdueRequests?: RightsRequest[];
|
|
96
|
+
skipped: Array<"retention" | "access" | "rights">;
|
|
97
|
+
/** Steps that failed. The other steps still ran. */
|
|
98
|
+
errors: Array<{
|
|
99
|
+
step: "retention" | "rights" | "access-prune" | "access-review";
|
|
100
|
+
message: string;
|
|
101
|
+
error: unknown;
|
|
102
|
+
}>;
|
|
103
|
+
}
|
|
104
|
+
export type DpdpEventName = keyof DpdpEvents;
|
|
105
|
+
export type DpdpListener<E extends DpdpEventName> = (payload: DpdpEvents[E]) => void | Promise<void>;
|
|
20
106
|
export interface DpdpOptions<P extends string> {
|
|
21
107
|
config: DpdpConfig<P>;
|
|
108
|
+
/** `memoryStore()`, `drizzleStore(db)`, or your own. Rights and retention need a full `DpdpStore`. */
|
|
22
109
|
store: ConsentStore;
|
|
110
|
+
/**
|
|
111
|
+
* How to reach the personal data in your tables, for access summaries and erasure:
|
|
112
|
+
* `drizzleData(db)` from `dpdp-kit/drizzle`, or your own `DataAccess`.
|
|
113
|
+
*/
|
|
114
|
+
data?: DataAccess;
|
|
115
|
+
/** Hooks for each processor in `config.processors`, to stop or erase on their side. */
|
|
116
|
+
processors?: Partial<Record<string, ProcessorHooks>>;
|
|
23
117
|
/** Clock, for tests. */
|
|
24
118
|
now?: () => Date;
|
|
25
119
|
/** Attempts when two writes for the same person race. Default 5. */
|
|
26
120
|
maxRetries?: number;
|
|
121
|
+
/** Access log behaviour. See `AccessOptions`. */
|
|
122
|
+
access?: AccessOptions;
|
|
123
|
+
/**
|
|
124
|
+
* Called when an event listener throws or rejects. Listeners never break the operation that
|
|
125
|
+
* fired them. Default: `console.error`.
|
|
126
|
+
*/
|
|
127
|
+
onListenerError?: (error: unknown, event: DpdpEventName) => void;
|
|
27
128
|
}
|
|
28
129
|
export interface Dpdp<P extends string> {
|
|
29
130
|
readonly config: DpdpConfig<P>;
|
|
131
|
+
/**
|
|
132
|
+
* Listen for an event, e.g. to feed your own audit trail, alerts or analytics. Listeners run after
|
|
133
|
+
* the change is saved, don't delay the call that fired them, and can't make it fail. Returns a
|
|
134
|
+
* function that removes the listener.
|
|
135
|
+
*
|
|
136
|
+
* ```ts
|
|
137
|
+
* dpdp.on("consent.withdrawn", ({ event }) => analytics.forget(event.subjectId, event.purposes));
|
|
138
|
+
* ```
|
|
139
|
+
*/
|
|
140
|
+
on<E extends DpdpEventName>(event: E, listener: DpdpListener<E>): () => void;
|
|
141
|
+
/**
|
|
142
|
+
* The daily upkeep in one call: carry out due erasure (`retention.run()`), prune access logs past
|
|
143
|
+
* their retention (`access.prune()`), review the last day of access (`access.review()`), and list
|
|
144
|
+
* overdue rights requests. Run it once a day: from `startDaily()` in `dpdp-kit/schedule`, node-cron,
|
|
145
|
+
* a BullMQ repeatable job, or your platform's cron. Safe to run from several servers at once.
|
|
146
|
+
*/
|
|
147
|
+
daily(input?: {
|
|
148
|
+
review?: {
|
|
149
|
+
/** Start of the review (ISO 8601). Default: a day before now. Pass the end of the last successful review so no day is missed. */
|
|
150
|
+
from?: string;
|
|
151
|
+
window?: Duration;
|
|
152
|
+
maxSubjects?: number;
|
|
153
|
+
ignoreActors?: readonly string[];
|
|
154
|
+
};
|
|
155
|
+
}): Promise<DailyReport>;
|
|
30
156
|
readonly consent: {
|
|
31
157
|
/** Record that the person agreed to these consent purposes. */
|
|
32
158
|
grant(subjectId: string, purposes: readonly P[], meta?: ConsentMeta): Promise<ConsentEvent>;
|
|
33
159
|
/**
|
|
34
|
-
* Record that the person withdrew consent. Returns
|
|
35
|
-
*
|
|
160
|
+
* Record that the person withdrew consent. Returns the erasure plan and, when the store keeps
|
|
161
|
+
* tasks, schedules it: `retention.run()` carries the tasks out when they're due.
|
|
36
162
|
*/
|
|
37
163
|
withdraw(subjectId: string, purposes: readonly P[], meta?: ConsentMeta): Promise<{
|
|
38
164
|
event: ConsentEvent;
|
|
39
165
|
erasure: ErasurePlan;
|
|
166
|
+
tasks: ErasureTask[];
|
|
40
167
|
}>;
|
|
41
168
|
/**
|
|
42
169
|
* Whether you hold consent, or don't need it, for this purpose. For consent purposes: true when
|
|
@@ -56,6 +183,82 @@ export interface Dpdp<P extends string> {
|
|
|
56
183
|
plan(subjectId: string, input: {
|
|
57
184
|
reason: "account-deletion";
|
|
58
185
|
}): Promise<ErasurePlan>;
|
|
186
|
+
/** Turn a plan into dated tasks for `retention.run()`. */
|
|
187
|
+
schedule(plan: ErasurePlan): Promise<ErasureTask[]>;
|
|
188
|
+
/** Plan and schedule erasure for a deleted account. */
|
|
189
|
+
deleteAccount(subjectId: string): Promise<{
|
|
190
|
+
plan: ErasurePlan;
|
|
191
|
+
tasks: ErasureTask[];
|
|
192
|
+
}>;
|
|
193
|
+
};
|
|
194
|
+
readonly retention: {
|
|
195
|
+
/**
|
|
196
|
+
* Carry out every due erasure task: null out or delete rows through `data`, and call processor
|
|
197
|
+
* hooks. Run it on a schedule (a daily cron is plenty). Safe to run from several processes.
|
|
198
|
+
*/
|
|
199
|
+
run(input?: {
|
|
200
|
+
limit?: number;
|
|
201
|
+
}): Promise<RunReport>;
|
|
202
|
+
tasks(filter?: TaskFilter): Promise<ErasureTask[]>;
|
|
203
|
+
/** Mark a `manual` or `failed` task as handled by a person. */
|
|
204
|
+
markDone(taskId: string, note: string): Promise<ErasureTask>;
|
|
205
|
+
};
|
|
206
|
+
readonly access: {
|
|
207
|
+
/**
|
|
208
|
+
* Record that someone accessed a person's personal data, and why (Rule 6(1)(c)). One entry per
|
|
209
|
+
* person. Needs a store that keeps the access log: `memoryStore()`, `drizzleStore(db)`, or your
|
|
210
|
+
* own `AccessLogStore`.
|
|
211
|
+
*/
|
|
212
|
+
log(input: AccessInput<P>): Promise<AccessEntry[]>;
|
|
213
|
+
/** Entries matching the filter, oldest first: for investigating a person, an actor, or a period. */
|
|
214
|
+
list(filter?: AccessFilter): Promise<AccessEntry[]>;
|
|
215
|
+
/**
|
|
216
|
+
* Look for signs of unauthorised access (Rule 6(1)(c)): fields read for a purpose they aren't
|
|
217
|
+
* held for, consent purposes used without consent at the time, and one actor reaching more
|
|
218
|
+
* than `maxSubjects` people (default 100) within `window` (default `"1h"`). Reviews the last day
|
|
219
|
+
* unless `from` / `to` are given. Run it daily.
|
|
220
|
+
*/
|
|
221
|
+
review(input?: {
|
|
222
|
+
from?: string;
|
|
223
|
+
to?: string;
|
|
224
|
+
window?: Duration;
|
|
225
|
+
maxSubjects?: number;
|
|
226
|
+
/** Actors exempt from bulk-access findings, e.g. a nightly export job that reaches everyone. */
|
|
227
|
+
ignoreActors?: readonly string[];
|
|
228
|
+
}): Promise<AccessReview>;
|
|
229
|
+
/**
|
|
230
|
+
* Delete entries older than `config.security.accessLogRetention` (default and minimum one year,
|
|
231
|
+
* Rule 6(1)(e)). Run it with the retention runner.
|
|
232
|
+
*/
|
|
233
|
+
prune(): Promise<{
|
|
234
|
+
deleted: number;
|
|
235
|
+
before: string;
|
|
236
|
+
}>;
|
|
237
|
+
};
|
|
238
|
+
readonly rights: {
|
|
239
|
+
/** Record a request (Sections 11–14). It's due after `config.rights.responseWithin` (default 90 days). */
|
|
240
|
+
open(subjectId: string, type: RequestType, details?: Record<string, unknown>): Promise<RightsRequest>;
|
|
241
|
+
get(id: string): Promise<RightsRequest | undefined>;
|
|
242
|
+
/** Requests, oldest first. `overdue: true` gives open requests past their due date. */
|
|
243
|
+
list(filter?: RequestFilter & {
|
|
244
|
+
overdue?: boolean;
|
|
245
|
+
}): Promise<RightsRequest[]>;
|
|
246
|
+
resolve(id: string, note?: string): Promise<RightsRequest>;
|
|
247
|
+
reject(id: string, reason: string): Promise<RightsRequest>;
|
|
248
|
+
/** What you hold about the person and who you shared it with (Section 11(1)). Needs `data`. */
|
|
249
|
+
summary(subjectId: string): Promise<AccessSummary>;
|
|
250
|
+
/**
|
|
251
|
+
* Erase on request (Section 12(3)): every purpose ends except those in `keepFor`, which you still
|
|
252
|
+
* need for the specified purpose. Legal holds and `minimumRetention` still apply. Pass the
|
|
253
|
+
* request id to resolve it.
|
|
254
|
+
*/
|
|
255
|
+
erase(subjectId: string, input?: {
|
|
256
|
+
keepFor?: readonly P[];
|
|
257
|
+
requestId?: string;
|
|
258
|
+
}): Promise<{
|
|
259
|
+
plan: ErasurePlan;
|
|
260
|
+
tasks: ErasureTask[];
|
|
261
|
+
}>;
|
|
59
262
|
};
|
|
60
263
|
}
|
|
61
264
|
type HashedFields = Omit<ConsentEvent, "hash">;
|