dpdp-kit 0.1.1 → 0.2.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/README.md +138 -11
- package/dist/audit.d.ts +2 -2
- package/dist/chunk-KVTUMHXO.js +491 -0
- package/dist/cli.js +61 -9
- package/dist/config.d.ts +15 -0
- package/dist/data-access.d.ts +19 -0
- package/dist/dpdp.d.ts +60 -3
- package/dist/drizzle.d.ts +505 -4
- package/dist/drizzle.js +268 -3
- package/dist/erasure.d.ts +2 -1
- package/dist/errors.d.ts +1 -1
- package/dist/index.d.ts +8 -2
- package/dist/index.js +375 -24
- package/dist/personal.d.ts +17 -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 +12 -0
- package/dist/schema-check.d.ts +22 -0
- package/dist/store.d.ts +9 -2
- package/package.json +1 -1
- package/dist/chunk-HRKHRKV4.js +0 -185
package/README.md
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
- **Declare why you hold each piece of personal data**, in one typed config file. A misspelt purpose is a type error.
|
|
8
8
|
- **Keep consent records that show tampering.** Each person's grants and withdrawals form a hash chain, with the notice version and language they saw.
|
|
9
9
|
- **Know what to erase.** When consent is withdrawn or an account is deleted, get a plan: which fields go, which stay (and why), which tables are under a legal hold, which third parties to tell.
|
|
10
|
-
- **Check it in CI.** `dpdp-kit audit` fails the build when the data map is inconsistent.
|
|
10
|
+
- **Check it in CI.** `dpdp-kit audit` fails the build when the data map is inconsistent, and the GitHub Action puts each problem on the pull request.
|
|
11
|
+
- **Catch drift.** `dpdp-kit audit --schema` reads your Drizzle schema and fails the build when someone adds a `phone`, `email` or `aadhaar_number` column without saying what it's for, or when the data map points at columns that no longer exist. Compliance that can't quietly fall out of date.
|
|
11
12
|
|
|
12
13
|
## Node-native
|
|
13
14
|
|
|
@@ -92,14 +93,80 @@ npx dpdp-kit audit --strict # also fail on warnings
|
|
|
92
93
|
|
|
93
94
|
The same checks run when the app starts: `createDpdp` throws if the config has errors.
|
|
94
95
|
|
|
96
|
+
### Catch schema drift
|
|
97
|
+
|
|
98
|
+
A data map is only useful while it matches the database. Point the audit at your Drizzle schema (Postgres, MySQL or SQLite):
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npx dpdp-kit audit --schema src/db/schema.ts
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
✖ error schema.users.aadhaar_number
|
|
106
|
+
Looks like personal data (identity, matched "aadhaar") but isn't in the data map. Add it under `data`
|
|
107
|
+
with the purposes it's held for, or add "users.aadhaar_number" to `notPersonal`.
|
|
108
|
+
✖ error data.users.fields.interests
|
|
109
|
+
Column "interests" isn't in table "users". Fix the name, or remove it if the column was dropped.
|
|
110
|
+
⚠ warning schema.users.gender
|
|
111
|
+
Looks like personal data (identity, matched "gender") but isn't in the data map. ...
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
It checks both directions:
|
|
115
|
+
|
|
116
|
+
- **New personal columns nobody mapped.** Columns are recognised by name: phone and email, Aadhaar, PAN, passport and voter ID, date of birth, names, addresses and PIN codes, UPI, IFSC and bank details, IP addresses and device IDs, health, biometric and location data. Clear cases are errors. Columns that are personal only sometimes, like `name`, `gender` or `city`, or anything named for a company or branch, are warnings.
|
|
117
|
+
- **A data map that points at nothing.** Tables or columns that were renamed or dropped.
|
|
118
|
+
|
|
119
|
+
Columns that describe data rather than hold it, such as `email_verified_at`, `phone_confirmed` and `address_type`, are not flagged. For anything that only looks personal, list it in the config:
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
notPersonal: ["products.name", "branches.*"], // database table and column names
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
From code, `checkSchema(config, drizzleSchema(schema))` returns the same issues. `drizzleSchema` comes from `dpdp-kit/drizzle`. Matching is by column name, so it can't see personal data hidden inside a JSON column or a vaguely named field. Review those by hand.
|
|
126
|
+
|
|
127
|
+
### In GitHub Actions
|
|
128
|
+
|
|
129
|
+
Add the audit to any workflow. Problems show up as annotations on the pull request, plus a summary on the run page:
|
|
130
|
+
|
|
131
|
+
```yaml
|
|
132
|
+
# .github/workflows/dpdp.yml
|
|
133
|
+
name: DPDP
|
|
134
|
+
on: [pull_request]
|
|
135
|
+
jobs:
|
|
136
|
+
audit:
|
|
137
|
+
runs-on: ubuntu-latest
|
|
138
|
+
steps:
|
|
139
|
+
- uses: actions/checkout@v4
|
|
140
|
+
- uses: actions/setup-node@v4
|
|
141
|
+
with:
|
|
142
|
+
node-version: 22
|
|
143
|
+
- run: npm ci # so your config can import dpdp-kit
|
|
144
|
+
- uses: yogesh2902/dpdp-kit@main
|
|
145
|
+
with:
|
|
146
|
+
schema: src/db/schema.ts # optional: also check for drift
|
|
147
|
+
# config: dpdp.config.ts # default: found automatically
|
|
148
|
+
# strict: true # fail on warnings too
|
|
149
|
+
# working-directory: apps/api # for monorepos
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The Action runs the dpdp-kit your project installed, falling back to `npx dpdp-kit@latest`. It sets `errors` and `warnings` outputs. Annotations need dpdp-kit 0.2.0 or later; with 0.1.x the check still runs and fails the build, without annotations. Outside GitHub, `npx dpdp-kit audit --format github` prints the same annotation lines.
|
|
153
|
+
|
|
95
154
|
## 3. Record consent
|
|
96
155
|
|
|
97
156
|
```ts
|
|
98
157
|
import { createDpdp } from "dpdp-kit";
|
|
99
|
-
import { drizzleStore } from "dpdp-kit/drizzle";
|
|
158
|
+
import { drizzleData, drizzleStore } from "dpdp-kit/drizzle";
|
|
159
|
+
import * as schema from "./db/schema";
|
|
100
160
|
import config from "./dpdp.config";
|
|
101
161
|
|
|
102
|
-
export const dpdp = createDpdp({
|
|
162
|
+
export const dpdp = createDpdp({
|
|
163
|
+
config,
|
|
164
|
+
store: drizzleStore(db), // consent records, rights requests, erasure tasks
|
|
165
|
+
data: drizzleData(db, { schema }), // reads and erases personal data in your own tables
|
|
166
|
+
processors: { // optional: tell third parties to stop or erase
|
|
167
|
+
msg91: { stop: ({ subjectId }) => msg91.optOut(subjectId), erase: ({ subjectId }) => msg91.deleteContact(subjectId) },
|
|
168
|
+
},
|
|
169
|
+
});
|
|
103
170
|
|
|
104
171
|
await dpdp.consent.grant(userId, ["marketing_sms", "analytics"], {
|
|
105
172
|
noticeVersion: "2026-11",
|
|
@@ -141,9 +208,63 @@ await dpdp.erasure.plan(userId, { reason: "account-deletion" });
|
|
|
141
208
|
|
|
142
209
|
**"Erase" is not "delete this second".** Every plan carries `minimumRetention` from your config. Under Rule 8(3), stop using the data now, keep a restricted copy only for the Seventh Schedule purposes, and delete it once a year has passed since its last processing. The Rule's own example is an e-book platform that keeps order details and logs for a year "even if X deletes her account".
|
|
143
210
|
|
|
144
|
-
|
|
211
|
+
### Carrying it out
|
|
145
212
|
|
|
146
|
-
|
|
213
|
+
`withdraw()` schedules the plan as dated tasks, and `erasure.deleteAccount(userId)` plans and schedules an account deletion. Then run the retention runner on a schedule; once a day is plenty:
|
|
214
|
+
|
|
215
|
+
```ts
|
|
216
|
+
const report = await dpdp.retention.run(); // { done, failed, manual }
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
| Task | When it runs | What it does |
|
|
220
|
+
|---|---|---|
|
|
221
|
+
| `processor-stop` | straight away | calls the processor's `stop` hook (Section 6(6)) |
|
|
222
|
+
| `erase-fields` | after `minimumRetention` (and `afterWithdrawal`) | sets the fields to `NULL` in the person's rows |
|
|
223
|
+
| `delete-rows` | after `minimumRetention` | deletes the person's rows (account deletion) |
|
|
224
|
+
| held table | after the legal hold (`keep`) | then anonymises (`NULL`s) or deletes, as `then` says |
|
|
225
|
+
| `processor-erase` | after `minimumRetention` | calls the processor's `erase` hook (Section 8(7)(b)) |
|
|
226
|
+
|
|
227
|
+
- **Safe to run from several servers.** Each task is claimed atomically, so it runs once.
|
|
228
|
+
- **Failures are retried**, up to 5 times. `lastError` keeps the database's message for developers, for example when a column is `NOT NULL`.
|
|
229
|
+
- **A processor with no hook** gives a `manual` task. Handle it yourself (email their support), then `retention.markDone(taskId, "ticket 4411")`.
|
|
230
|
+
- **Consent records are never erased.** Section 6(10) makes you prove consent, and Rule 8(3) requires keeping records of processing.
|
|
231
|
+
- **Erasure sets columns to `NULL`**, so erasable columns must be nullable. Data access currently covers Postgres.
|
|
232
|
+
|
|
233
|
+
## 5. Rights requests
|
|
234
|
+
|
|
235
|
+
People can ask to see their data (Section 11), correct or erase it (Section 12), raise a grievance (Section 13) or name a nominee (Section 14). Each request is recorded with a due date:
|
|
236
|
+
|
|
237
|
+
```ts
|
|
238
|
+
const request = await dpdp.rights.open(userId, "grievance", { text: "I keep getting promo SMS" });
|
|
239
|
+
// request.dueAt is 90 days out: Rule 14(3) caps grievance responses at ninety days
|
|
240
|
+
|
|
241
|
+
await dpdp.rights.list({ overdue: true }); // your inbox of late answers
|
|
242
|
+
await dpdp.rights.resolve(request.id, "Promo SMS turned off");
|
|
243
|
+
await dpdp.rights.reject(otherId, "Duplicate of an earlier grievance");
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
**Access (Section 11):** `summary()` reads the person's personal fields from your tables, with the purposes each is held for, their consents, and the processors their data goes to:
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
const summary = await dpdp.rights.summary(userId);
|
|
250
|
+
// { data: [{ table: "users", fields: [...], rows: [{ phone: "98…", name: "Asha" }] }],
|
|
251
|
+
// consents: ["order_updates"], legitimateUses: ["account"],
|
|
252
|
+
// sharedWith: [{ name: "msg91", purposes: ["order_updates"] }] }
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
**Erasure (Section 12(3)):** every purpose ends except those you still need for the specified purpose. Legal holds and `minimumRetention` still apply:
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
await dpdp.rights.erase(userId, { keepFor: ["account"], requestId: request.id }); // schedules, resolves the request
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Corrections and nominations are recorded with the request (`details`); your app applies them, then calls `resolve()`. Set your own answer times in the config. The Rules set ninety days for grievances only, and the audit fails above that:
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
rights: { responseWithin: { grievance: "30d", access: "30d" } },
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## 6. Guard routes
|
|
147
268
|
|
|
148
269
|
```ts
|
|
149
270
|
// Express
|
|
@@ -161,18 +282,22 @@ Without consent, the middleware responds `403 { error: "consent_required", purpo
|
|
|
161
282
|
|
|
162
283
|
### Drizzle (Postgres)
|
|
163
284
|
|
|
164
|
-
Add the
|
|
285
|
+
Add the tables to your schema so drizzle-kit creates them:
|
|
165
286
|
|
|
166
287
|
```ts
|
|
167
288
|
// schema.ts
|
|
168
|
-
export { consentEvents } from "dpdp-kit/drizzle";
|
|
289
|
+
export { consentEvents, erasureTasks, rightsRequests } from "dpdp-kit/drizzle";
|
|
169
290
|
```
|
|
170
291
|
|
|
171
|
-
If you don't use drizzle-kit, run `
|
|
292
|
+
If you don't use drizzle-kit, run `DPDP_DDL` (exported from `dpdp-kit/drizzle`). This works with any Drizzle Postgres driver: node-postgres, postgres.js, Neon, PGlite.
|
|
293
|
+
|
|
294
|
+
> **Upgrading from 0.1.x?** Add `rightsRequests` and `erasureTasks` to your schema and generate a migration, or run `RECORDS_DDL`. `withdraw()` now schedules erasure tasks, so it needs the `dpdp_erasure_tasks` table.
|
|
295
|
+
|
|
296
|
+
`drizzleData(db, { schema })` reaches your own tables. Pass your schema module when the data map uses Drizzle property names (`userId`) rather than column names (`user_id`).
|
|
172
297
|
|
|
173
298
|
### Anything else
|
|
174
299
|
|
|
175
|
-
Implement `
|
|
300
|
+
Implement `DpdpStore`: consent events (`lastEvent`, `insert`, `events`), requests and tasks (see `RequestStore` and `TaskStore`). `insert` must throw `SeqConflictError` on a duplicate `(subjectId, seq)`, and `claimTask` must be atomic. A store with only the three consent methods still works for consent; rights and retention then throw `store-unsupported`. Implement `DataAccess` (`read`, `eraseFields`, `deleteRows`) for another database. `memoryStore()` and `memoryData()` are included for tests.
|
|
176
301
|
|
|
177
302
|
## How the consent record works
|
|
178
303
|
|
|
@@ -187,8 +312,10 @@ Section 6(10) puts the burden on you: if consent is questioned in a proceeding,
|
|
|
187
312
|
|
|
188
313
|
| Version | Adds |
|
|
189
314
|
|---|---|
|
|
190
|
-
| **v0.1**
|
|
191
|
-
| v0.2 |
|
|
315
|
+
| **v0.1** | Config and types, `audit` + CLI, consent records, erasure plans, Drizzle store, Express/Hono guards |
|
|
316
|
+
| **v0.1.2** | Schema drift check: `audit --schema`, `checkSchema`, `drizzleSchema`, `notPersonal` |
|
|
317
|
+
| **v0.2.0** | Rights requests (Sections 11–14, Rule 14), retention runner that carries out erasure (Section 8(7), Rule 8(3), legal holds), processor hooks, `drizzleData`, GitHub Action with pull request annotations |
|
|
318
|
+
| later | Recording objections to a Section 7(a) use, React notice that meets Rule 3 + privacy centre, MySQL and SQLite data access |
|
|
192
319
|
| v0.3 | Breach records with deadlines (Section 8(6), Rule 7: people and the Board without delay, detailed report to the Board within 72 hours), children and guardian consent (Section 9, Rule 10), inactivity erasure with 48 hours' warning for large e-commerce, gaming and social media platforms (Rule 8(1)–(2), Third Schedule), Consent Manager interop (Sections 6(7)–6(9), Rule 4), Prisma store |
|
|
193
320
|
|
|
194
321
|
## When the Rules apply
|
package/dist/audit.d.ts
CHANGED
|
@@ -2,8 +2,8 @@ import type { DpdpConfig } from "./config.js";
|
|
|
2
2
|
export type IssueLevel = "error" | "warning";
|
|
3
3
|
export interface Issue {
|
|
4
4
|
level: IssueLevel;
|
|
5
|
-
code: "no-purposes" | "invalid-basis" | "invalid-retention" | "invalid-duration" | "unknown-purpose" | "field-without-purpose" | "table-without-fields" | "missing-subject-column" | "unused-purpose" | "minimum-retention-missing" | "minimum-retention-too-short" | "grievance-missing" | "fiduciary-missing";
|
|
6
|
-
/** Where in the config
|
|
5
|
+
code: "no-purposes" | "invalid-basis" | "invalid-retention" | "invalid-duration" | "unknown-purpose" | "field-without-purpose" | "table-without-fields" | "missing-subject-column" | "unused-purpose" | "minimum-retention-missing" | "minimum-retention-too-short" | "grievance-missing" | "fiduciary-missing" | "invalid-not-personal" | "unknown-table" | "unknown-column" | "unmapped-personal-column" | "stale-not-personal" | "grievance-response-too-long" | "invalid-request-type";
|
|
6
|
+
/** Where in the config (`data.users.fields.phone`), or in the schema (`schema.users.phone`). */
|
|
7
7
|
path: string;
|
|
8
8
|
message: string;
|
|
9
9
|
}
|