@edgeproc/privacy-core 0.2.0

package/dist/rehydrate.d.ts

@@ -0,0 +1,21 @@
+import type { VaultRef } from "./types.js";
+import type { Vault } from "./vault.js";
+/**
+ * Restore real values locally: walk every [TYPE_n] placeholder in the text and
+ * swap in its raw value from the vault. This is the close of the loop — it runs
+ * on-device, after the provider replied, so the real values are restored
+ * without ever having crossed the wire.
+ *
+ * Vault binding is MANDATORY: pass the payload's `vaultRef` so the restore is
+ * bound to the vault the text was actually redacted with. This fails closed in
+ * two ways instead of ever silently substituting a wrong value:
+ *
+ *  - Wrong vault → {@link VaultMismatchError}. Without the binding, an
+ *    overlapping `[NAME_1]`/`[CARD_1]` from a *different* vault would resolve to
+ *    the wrong person's real value.
+ *  - A placeholder the bound vault cannot resolve → {@link
+ *    UnresolvedPlaceholderError}. A model-invented `[CARD_9]`, or text redacted
+ *    with another vault, is an anomaly — stop, don't leave a lookalike token.
+ */
+export declare function rehydrate(redactedText: string, vault: Vault, expectedRef: VaultRef): string;
+//# sourceMappingURL=rehydrate.d.ts.map

package/dist/rehydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../src/rehydrate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAKxC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,QAAQ,GACpB,MAAM,CAkBR"}

package/dist/rehydrate.js

@@ -0,0 +1,36 @@
+import { UnresolvedPlaceholderError, VaultMismatchError } from "./errors.js";
+/** The placeholder grammar `rehydrate` restores (same shape `redact` mints). */
+const PLACEHOLDER = /\[[A-Z]+_\d+\]/g;
+/**
+ * Restore real values locally: walk every [TYPE_n] placeholder in the text and
+ * swap in its raw value from the vault. This is the close of the loop — it runs
+ * on-device, after the provider replied, so the real values are restored
+ * without ever having crossed the wire.
+ *
+ * Vault binding is MANDATORY: pass the payload's `vaultRef` so the restore is
+ * bound to the vault the text was actually redacted with. This fails closed in
+ * two ways instead of ever silently substituting a wrong value:
+ *
+ *  - Wrong vault → {@link VaultMismatchError}. Without the binding, an
+ *    overlapping `[NAME_1]`/`[CARD_1]` from a *different* vault would resolve to
+ *    the wrong person's real value.
+ *  - A placeholder the bound vault cannot resolve → {@link
+ *    UnresolvedPlaceholderError}. A model-invented `[CARD_9]`, or text redacted
+ *    with another vault, is an anomaly — stop, don't leave a lookalike token.
+ */
+export function rehydrate(redactedText, vault, expectedRef) {
+    if (vault.ref.id !== expectedRef.id) {
+        throw new VaultMismatchError(`vault "${vault.ref.id}" does not match the payload's vault ` +
+            `"${expectedRef.id}" — restoring with the wrong vault yields wrong values`);
+    }
+    return redactedText.replace(PLACEHOLDER, (token) => {
+        const value = vault.resolve(token);
+        if (value === undefined) {
+            throw new UnresolvedPlaceholderError(`placeholder ${token} is not in vault "${vault.ref.id}" — under a bound ` +
+                "vault an unresolvable token is an anomaly (a model-invented token, or " +
+                "text redacted with a different vault), so rehydrate fails closed");
+        }
+        return value;
+    });
+}
+//# sourceMappingURL=rehydrate.js.map

package/dist/rehydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.js","sourceRoot":"","sources":["../src/rehydrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAI7E,gFAAgF;AAChF,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,YAAoB,EACpB,KAAY,EACZ,WAAqB;IAErB,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,WAAW,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,kBAAkB,CAC1B,UAAU,KAAK,CAAC,GAAG,CAAC,EAAE,uCAAuC;YAC3D,IAAI,WAAW,CAAC,EAAE,wDAAwD,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE;QACjD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,0BAA0B,CAClC,eAAe,KAAK,qBAAqB,KAAK,CAAC,GAAG,CAAC,EAAE,oBAAoB;gBACvE,wEAAwE;gBACxE,kEAAkE,CACrE,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test-only fixtures, exposed via the `@edgeproc/privacy-core/testing` subpath.
+ * These are NOT part of the production barrel — keep synthetic data out of the
+ * front door so consumers never ship a fixture by accident.
+ */
+/**
+ * SYNTHETIC, INVENTED bank statement. Contains NO real PII.
+ * - Card 4242…4242 is the canonical Stripe test card (Luhn-valid, not issued).
+ * - IBAN GB82 WEST… is the public mod-97 IBAN example from Wikipedia.
+ * - SSN 123-45-6789 is a textbook placeholder.
+ * - Routing 021000021 is a published ABA test routing number (JPMorgan Chase).
+ */
+export declare const SYNTHETIC_STATEMENT = "MONTHLY STATEMENT \u2014 FIRST INVENTED BANK\n\nAccount holder: Ada Lovelace\nEmail: ada.lovelace@example.com\nPhone: (415) 555-0132\nSSN on file: 123-45-6789\n\nAccount number: 000123456789\nRouting number: 021000021\nLinked IBAN: GB82 WEST 1234 5698 7654 32\nCard on file: 4242 4242 4242 4242\n\nTransactions:\n  01/05/2026  Whole Foods            $1,482.10\n  01/09/2026  Starbucks                 $7.45\n  01/14/2026  Amazon                  $329.00\n\nPlease review the charge to Whole Foods.";
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,sfAiBS,CAAC"}

package/dist/testing.js

@@ -0,0 +1,31 @@
+/**
+ * Test-only fixtures, exposed via the `@edgeproc/privacy-core/testing` subpath.
+ * These are NOT part of the production barrel — keep synthetic data out of the
+ * front door so consumers never ship a fixture by accident.
+ */
+/**
+ * SYNTHETIC, INVENTED bank statement. Contains NO real PII.
+ * - Card 4242…4242 is the canonical Stripe test card (Luhn-valid, not issued).
+ * - IBAN GB82 WEST… is the public mod-97 IBAN example from Wikipedia.
+ * - SSN 123-45-6789 is a textbook placeholder.
+ * - Routing 021000021 is a published ABA test routing number (JPMorgan Chase).
+ */
+export const SYNTHETIC_STATEMENT = `MONTHLY STATEMENT — FIRST INVENTED BANK
+
+Account holder: Ada Lovelace
+Email: ada.lovelace@example.com
+Phone: (415) 555-0132
+SSN on file: 123-45-6789
+
+Account number: 000123456789
+Routing number: 021000021
+Linked IBAN: GB82 WEST 1234 5698 7654 32
+Card on file: 4242 4242 4242 4242
+
+Transactions:
+  01/05/2026  Whole Foods            $1,482.10
+  01/09/2026  Starbucks                 $7.45
+  01/14/2026  Amazon                  $329.00
+
+Please review the charge to Whole Foods.`;
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;yCAiBM,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/** The PII categories the Tier-1 deterministic detector recognizes. */
+export type EntityType = "CARD" | "IBAN" | "SSN" | "EMAIL" | "PHONE" | "ACCOUNT" | "ROUTING" | "AMOUNT" | "DATE" | "NAME" | "MERCHANT";
+/** A detected PII span in the source text. */
+export interface Span {
+    readonly type: EntityType;
+    readonly value: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** Opaque handle to a vault holding token -> raw-value mappings. */
+export interface VaultRef {
+    readonly id: string;
+}
+/** An audit record — metadata only, never raw PII (except the explicit bypass case). */
+export interface AuditEntry {
+    readonly kind: "redact" | "approve" | "unsafe-bypass";
+    readonly at: number;
+    readonly placeholders?: readonly string[];
+    readonly reason?: string;
+}
+/** A sink the caller supplies to receive append-only audit entries. */
+export type AuditSink = (entry: AuditEntry) => void;
+/** A provider's reply, still in placeholder form until rehydrated locally. */
+export interface RedactedResponse {
+    readonly redactedText: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,MAAM,GACN,KAAK,GACL,OAAO,GACP,OAAO,GACP,SAAS,GACT,SAAS,GACT,QAAQ,GACR,MAAM,GACN,MAAM,GACN,UAAU,CAAC;AAEf,8CAA8C;AAC9C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,oEAAoE;AACpE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,eAAe,CAAC;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAEpD,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/vault.d.ts

@@ -0,0 +1,21 @@
+import type { EntityType, VaultRef } from "./types.js";
+/**
+ * In-memory reversible token<->value map (v0 scope).
+ *
+ * Stable placeholders: the same raw value always maps to the same token, and
+ * each entity type gets its own counter ([CARD_1], [NAME_2], ...). The encrypted
+ * IndexedDB vault (AES-GCM + passphrase KDF) is deferred — see Roadmap. This v0
+ * vault is in-memory and clears on reload, by design.
+ */
+export declare class Vault {
+    readonly ref: VaultRef;
+    private readonly tokenForValue;
+    private readonly valueForToken;
+    private readonly counters;
+    constructor();
+    /** Return the stable placeholder for a (type, value), minting one on first sight. */
+    tokenize(type: EntityType, value: string): string;
+    /** Resolve a placeholder back to its raw value, or undefined if unknown. */
+    resolve(token: string): string | undefined;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIvD;;;;;;;GAOG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAE1D,cAIC;IAED,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhD;IAED,4EAA4E;IAC5E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzC;CACF"}

package/dist/vault.js

@@ -0,0 +1,38 @@
+let nextVaultId = 1;
+/**
+ * In-memory reversible token<->value map (v0 scope).
+ *
+ * Stable placeholders: the same raw value always maps to the same token, and
+ * each entity type gets its own counter ([CARD_1], [NAME_2], ...). The encrypted
+ * IndexedDB vault (AES-GCM + passphrase KDF) is deferred — see Roadmap. This v0
+ * vault is in-memory and clears on reload, by design.
+ */
+export class Vault {
+    ref;
+    tokenForValue = new Map();
+    valueForToken = new Map();
+    counters = new Map();
+    constructor() {
+        // Frozen: `payload.vaultRef` aliases this object, so the rehydrate binding
+        // (VaultMismatchError) cannot be defeated by rewriting the id after the fact.
+        this.ref = Object.freeze({ id: `vault-${nextVaultId++}` });
+    }
+    /** Return the stable placeholder for a (type, value), minting one on first sight. */
+    tokenize(type, value) {
+        const key = `${type}::${value}`;
+        const existing = this.tokenForValue.get(key);
+        if (existing)
+            return existing;
+        const n = (this.counters.get(type) ?? 0) + 1;
+        this.counters.set(type, n);
+        const token = `[${type}_${n}]`;
+        this.tokenForValue.set(key, token);
+        this.valueForToken.set(token, value);
+        return token;
+    }
+    /** Resolve a placeholder back to its raw value, or undefined if unknown. */
+    resolve(token) {
+        return this.valueForToken.get(token);
+    }
+}
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAEA,IAAI,WAAW,GAAG,CAAC,CAAC;AAEpB;;;;;;;GAOG;AACH,MAAM,OAAO,KAAK;IACP,GAAG,CAAW;IACN,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE1D;QACE,2EAA2E;QAC3E,8EAA8E;QAC9E,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,SAAS,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,qFAAqF;IACrF,QAAQ,CAAC,IAAgB,EAAE,KAAa;QACtC,MAAM,GAAG,GAAG,GAAG,IAAI,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4EAA4E;IAC5E,OAAO,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@edgeproc/privacy-core",
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "A browser-side privacy boundary for LLM calls: redact on-device, send only placeholders, rehydrate locally — enforced by a type-checked Egress Guard.",
+  "license": "MIT",
+  "author": "Harish Seshadri",
+  "packageManager": "pnpm@11.5.0",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@edgeproc/avow": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p examples/demo/tsconfig.json --noEmit",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "demo": "pnpm --filter @edgeproc/privacy-core-demo dev",
+    "gate": "pnpm lint && pnpm typecheck && pnpm test && pnpm test:e2e && pnpm build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.7",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.7"
+  }
+}