dpdp-erasure-cli 1.1.0 → 1.1.2

package/README.md

@@ -1,10 +1,10 @@
 # dpdp-erasure-cli
 
-[![npm version](https://badge.fury.io/js/dpdp-erasure-cli.svg)](https://badge.fury.io/js/dpdp-erasure-cli)
+[![npm version](https://img.shields.io/npm/v/dpdp-erasure-cli?color=14b8a6&style=flat-square)](https://www.npmjs.com/package/dpdp-erasure-cli)
 
 **The DPDP Erasure Engine CLI** is an automated, AI-assisted privacy toolkit that helps you securely discover, map, and cryptographically shred PII (Personally Identifiable Information) in your database. 
 
-It acts as the control plane for the [DPDP Erasure Engine](https://github.com/devxdh/dpdp-erasure-engine), allowing Data Protection Officers (DPOs) and Software Engineers to effortlessly comply with global privacy laws (DPDP, GDPR, CCPA) without writing manual SQL deletion scripts.
+It acts as the control plane for the [DPDP Erasure Engine](https://github.com/devxdh/dpdp-erasure-engine). We are an open-source DPDP-aligned data erasure engine that helps developers comply with India's Digital Personal Data Protection Act (DPDPA), 2023. Data erasure is one of the biggest hurdles under the law due to the complex conflict between data retention policies, Data Principal rights, and Data Fiduciary obligations—this engine helps you solve that without writing manual SQL deletion scripts.
 
 ---
 
@@ -20,11 +20,24 @@ Manually deleting a user across dozens of microservice tables is dangerous and p
 
 ---
 
+## ⚠️ Introspector Limitations (100% Transparency)
+
+While our Introspector is incredibly powerful at analyzing metadata, foreign keys, and block-sampling text to find common identifiers (like Emails, Phone Numbers, Aadhaar, PAN, SSN, Credit Cards), it is fundamentally a regex and heuristic engine—not a sentient AI. 
+
+**What we CANNOT do:**
+1. **Generic Column Names:** If your production database has a column named `info` or `data` and it happens to contain a user's *First Name* or *Last Name* embedded inside a generic string, our engine cannot confidently flag it as PII. We can only guess "Name" PII if the column is named descriptively (e.g., `full_name`, `first_name`, `last_name`).
+2. **Passwords, Tokens, and Secrets:** We cannot differentiate a random SHA-256 password hash or an API token from an ordinary ID string unless the column has a clear name like `password`, `secret`, `token`, or `api_key`.
+3. **Roles and Permissions:** Similarly, we cannot guess if an integer or string denotes an administrative permission unless the column gives us a hint (like `role_id` or `access_level`).
+
+**The Solution:** The Introspector is designed to do 95% of the heavy lifting. **The remaining 5% requires a human DPO or Developer.** You must always review the generated `compliance.worker.yml` and manually add any deeply hidden sensitive columns before deploying.
+
+---
+
 ## 🚀 Installation
 
 This CLI relies on [Bun](https://bun.sh/) for native cryptographic bindings and high-performance execution.
 
-```bash
+```text
 npm install -g dpdp-erasure-cli
 ```
 
@@ -34,7 +47,7 @@ npm install -g dpdp-erasure-cli
 
 Don't want to memorize commands? Just run the CLI with no arguments to launch the interactive wizard:
 
-```bash
+```text
 dpdp-cli
 ```
 
@@ -47,7 +60,7 @@ Setting up your database for privacy compliance follows this simple 5-step workf
 ### 1. Introspect Your Database
 Safely analyze your schema to discover PII and draft the deletion manifest. The AI will even find logical links if you don't use strict Foreign Keys!
 
-```bash
+```text
 dpdp-cli introspect \
   --url "postgres://user:pass@localhost:5432/app_db" \
   --root public.users \
@@ -60,19 +73,19 @@ Open the generated `compliance.worker.yml`. Review the `targets` and `join` cond
 
 ### 3. Generate Security Keys
 Create a private/public keypair to securely sign your manifest for production environments.
-```bash
+```text
 dpdp-cli keygen
 ```
 
 ### 4. Cryptographically Sign the Manifest
 Lock down the rules to prevent unauthorized changes in your CI/CD pipeline.
-```bash
+```text
 dpdp-cli sign --config ./compliance.worker.yml --key ./worker.pkcs8.key
 ```
 
 ### 5. Simulate an Erasure (Dry-Run)
 Test the erasure on a specific user. This command runs entirely within an isolated transaction that is automatically rolled back, so it is 100% safe.
-```bash
+```text
 dpdp-cli dry-run --id "user_12345" --url "postgres://user:pass@localhost:5432/app_db" --config ./compliance.worker.yml
 ```
 
@@ -82,7 +95,7 @@ dpdp-cli dry-run --id "user_12345" --url "postgres://user:pass@localhost:5432/ap
 
 You can use the CLI in your GitHub Actions or GitLab CI to fail builds if a developer modifies the database schema without updating the signed compliance manifest:
 
-```bash
+```text
 dpdp-cli check-integrity --url "postgres://..." --config ./compliance.worker.yml
 ```
 

package/compliance.worker.yml

@@ -1,6 +1,6 @@
 # AUTO-GENERATED BY INTROSPECTOR
 # REVIEW REQUIRED: DPO must validate every table, join condition, and PII column before production use.
-# Generated At: 2026-06-12T05:19:07.235Z
+# Generated At: 2026-06-12T08:15:53.497Z
 
 legal_attestation:
   dpo_identifier: PENDING_REVIEW
@@ -13,6 +13,20 @@ legal_attestation:
 legal_disclaimer:
   text: "Auto-generated by Compliance Worker. The DPO/Developer is responsible for verifying all logical links and PII mappings."
 
+# ===================================================================================
+# HOW TO READ THIS MANIFEST:
+# - 'targets': The list of tables the worker will delete/redact from.
+# - 'parent': The table that owns this data. The worker deletes parent-first or child-first depending on the DB constraints.
+# - 'join': The SQL condition used to link the child table to the parent table.
+# - 'pii_columns': Columns identified as containing Personal Identifiable Information.
+# - 'action': 'redact' (anonymizes the row but keeps it) or implicitly 'delete' (removes the row entirely).
+#
+# IMPORTANT:
+# 1. Review all 'join' conditions. If the Introspector guessed a join for an orphaned table, verify it.
+# 2. Review all 'pii_columns' to ensure no sensitive columns were missed.
+# 3. Replace 'PENDING_REVIEW' in legal_attestation once verified.
+# ===================================================================================
+
 rules:
   - id: dpdp_standard
     root_table: public.users
@@ -98,14 +112,14 @@ rules:
           message_body: HMAC
       - table: public.abandoned_carts
         parent: public.users
-        join: "LOGICAL_LINK (customer_id)"
-        parent_columns: [customer_id]
+        join: "public.users.id = public.abandoned_carts.customer_id"
+        parent_columns: [id]
         child_columns: [customer_id]
         pii_columns: []
       - table: public.audit_logs
         parent: public.users
-        join: "LOGICAL_LINK (actor_id)"
-        parent_columns: [actor_id]
+        join: "public.users.id = public.audit_logs.actor_id"
+        parent_columns: [id]
         child_columns: [actor_id]
         # Introspector Confidence: 0.820 (ipv4)
         pii_columns: [ip_address]
@@ -115,8 +129,8 @@ rules:
           ip_address: HMAC
       - table: public.legacy_crm_notes
         parent: public.users
-        join: "LOGICAL_LINK (client_id)"
-        parent_columns: [client_id]
+        join: "public.users.id = public.legacy_crm_notes.client_id"
+        parent_columns: [id]
         child_columns: [client_id]
         # Introspector Confidence: 0.950 (email, indian_mobile)
         pii_columns: [agent_notes]
@@ -126,8 +140,8 @@ rules:
           agent_notes: HMAC
       - table: public.marketing_campaign_clicks
         parent: public.users
-        join: "LOGICAL_LINK (target_email)"
-        parent_columns: [target_email]
+        join: "public.users.email = public.marketing_campaign_clicks.target_email"
+        parent_columns: [email]
         child_columns: [target_email]
         # Introspector Confidence: 0.950 (email)
         pii_columns: [target_email]
@@ -137,8 +151,8 @@ rules:
           target_email: HMAC
       - table: public.third_party_telemetry
         parent: public.users
-        join: "LOGICAL_LINK (user_uuid)"
-        parent_columns: [user_uuid]
+        join: "public.users.id = public.third_party_telemetry.user_uuid"
+        parent_columns: [id]
         child_columns: [user_uuid]
         pii_columns: []
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dpdp-erasure-cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "license": "Apache-2.0",
   "keywords": [
     "dpdp",
@@ -54,4 +54,4 @@
     "postgres": "^3.4.9",
     "zod": "^4.4.2"
   }
-}
+}

package/report.json

@@ -1,7 +1,7 @@
 {
   "summary": {
     "rootTable": "public.users",
-    "generatedAt": "2026-06-12T05:19:07.235Z",
+    "generatedAt": "2026-06-12T08:15:53.497Z",
     "schemaHash": "ea9e816d30fcee6bd4f322f1fb769e853c2e7ee5b19263aaa54f5ef80189212c",
     "targetCount": 15,
     "tablesWithPii": 8,

package/report.md

@@ -3,7 +3,7 @@
 ## Summary
 
 - Root table: `public.users`
-- Generated at: `2026-06-12T05:19:07.235Z`
+- Generated at: `2026-06-12T08:15:53.497Z`
 - Schema hash: `ea9e816d30fcee6bd4f322f1fb769e853c2e7ee5b19263aaa54f5ef80189212c`
 - DAG targets: 15
 - Tables with PII: 8

package/src/modules/cli/ui.ts

@@ -10,18 +10,18 @@ import boxen from "boxen";
 export const UI = {
   header: (title: string) => {
     console.log(
-      boxen(pc.bold(pc.blue(`COMPLIANCE WORKER — ${title.toUpperCase()}`)), {
+      boxen(pc.bold(pc.cyan(`COMPLIANCE WORKER — ${title.toUpperCase()}`)), {
         padding: { top: 0, bottom: 0, left: 2, right: 2 },
         margin: { top: 1, bottom: 1 },
         borderStyle: "round",
-        borderColor: "blue",
+        borderColor: "cyan",
       })
     );
   },
 
   divider: () => console.log(pc.gray("─".repeat(process.stdout.columns || 60))),
 
-  spinner: (text: string): Ora => ora({ text, color: "blue" }).start(),
+  spinner: (text: string): Ora => ora({ text, color: "cyan" }).start(),
 
   success: (msg: string) => console.log(`\n${pc.green("✔")} ${pc.bold(msg)}`),
   error: (msg: string) => console.error(`\n${pc.red("✖")} ${pc.bold(msg)}`),

package/src/modules/introspector/classifier.ts

@@ -121,6 +121,10 @@ const CONTENT_SIGNATURES: ContentSignature[] = [
 ];
 
 const METADATA_PATTERNS: Array<{ pattern: RegExp; score: number }> = [
+  { pattern: /(^|_)(full_name|first_name|last_name|middle_name|surname|given_name|display_name)($|_)/i, score: STRONG_METADATA_SCORE },
+  { pattern: /(^|_)name($|_)/i, score: MEDIUM_METADATA_SCORE },
+  { pattern: /(^|_)(password|passwd|pwd|secret|token|api_key|access_token|refresh_token|auth_token|hash|salt)($|_)/i, score: STRONG_METADATA_SCORE },
+  { pattern: /(^|_)(role|roles|permission|permissions|group|groups|acl|access_level)($|_)/i, score: WEAK_METADATA_SCORE },
   { pattern: /(^|_)(email|e_mail|email_address|mail_address|contact_email)($|_)/i, score: STRONG_METADATA_SCORE },
   { pattern: /(^|_)(phone|mobile|msisdn|telephone|contact_number|whatsapp)(_number|_no)?($|_)/i, score: STRONG_METADATA_SCORE },
   { pattern: /(^|_)(aadhaar|aadhar|uidai)(_number|_no|_id)?($|_)/i, score: STRONG_METADATA_SCORE },

package/tests/introspector-classifier.test.ts

@@ -53,10 +53,10 @@ describe("Introspector PII classifier", () => {
     expect(classifyLeaf("560001", "postal_code")).toContain("indian_pin_code");
   });
 
-  it("does not infer personal names without a dedicated NER model", () => {
-    expect(metadataScore("full_name")).toBe(0);
-    expect(metadataScore("first_name")).toBe(0);
-    expect(metadataScore("customer_name")).toBe(0);
+  it("infers personal names based on standard developer metadata patterns", () => {
+    expect(metadataScore("full_name")).toBe(0.92);
+    expect(metadataScore("first_name")).toBe(0.92);
+    expect(metadataScore("customer_name")).toBe(0.82);
     expect(classifyLeaf("Priya Sharma")).toEqual([]);
   });
 });

package/tests/introspector.test.ts

@@ -201,6 +201,7 @@ describe("Offline Introspector", () => {
     expect(users?.piiColumns.map((column) => column.column).sort()).toEqual([
       "card_number",
       "email",
+      "full_name",
       "gstin",
       "phone",
       "upi_id",
@@ -215,7 +216,6 @@ describe("Offline Introspector", () => {
     expect(yaml).toContain(`root_table: ${schema}.users`);
     expect(yaml).toContain(`table: ${schema}.profiles`);
     expect(yaml).toContain("pii_columns: [pan, aadhaar_payload, nested_payload]");
-    expect(yaml).not.toContain("full_name");
     expect(yaml).toContain("schema_hash:");
     expect(yaml).toContain("generated_by: compliance-introspector-v1");
     expect(yaml).toContain("legal_disclaimer:");