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 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({ config, store: drizzleStore(db) });
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
- **In v0.1 the plan only describes what to do; nothing is deleted for you.** Applying it (with your own `onErase` hooks for third parties) arrives in v0.2.
211
+ ### Carrying it out
145
212
 
146
- ## 5. Guard routes
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 table to your schema so drizzle-kit creates it:
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 `CONSENT_EVENTS_DDL` (exported from `dpdp-kit/drizzle`). This works with any Drizzle Postgres driver: node-postgres, postgres.js, Neon, PGlite.
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 `ConsentStore`: three methods (`lastEvent`, `insert`, `events`). `insert` must throw `SeqConflictError` on a duplicate `(subjectId, seq)`; a primary key on those columns does that. `memoryStore()` is included for tests.
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** (this) | Config and types, `audit` + CLI, consent records, erasure plans, Drizzle store, Express/Hono guards |
191
- | v0.2 | User rights requests (Sections 11–14, Rule 14; grievances answered within 90 days, Rule 14(3)), recording objections to a Section 7(a) use, applying erasure plans, processor hooks, React notice that meets Rule 3 + privacy centre |
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, e.g. `data.users.fields.phone`. */
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
  }