@abhishekvardanbotta/mask 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,7 @@
 Keep personal data out of LLM prompts, tool calls, memory and logs, and still get it back where it is allowed.
 
 `mask` finds personal data in structured and unstructured values. It replaces each value with a reversible
-token such as `[EMAIL_1]`, keeps the original encrypted in a vault, and restores it only for principals
+token such as `ss1_njpskmng`, keeps the original encrypted in a vault, and restores it only for principals
 granted that kind of data. It has zero runtime dependencies and uses only `node:crypto` and `node:net`.
 
 It is the engine behind `privacy: { enabled: true }` in [kiln](https://www.npmjs.com/package/@abhishekvardanbotta/kiln), and works on its own with any LLM stack.
@@ -19,7 +19,7 @@ const privacy = createPrivacy({ key: process.env.KILN_PRIVACY_KEY });   // 32-by
 const session = privacy.session("conversation-123");
 
 const prompt = session.protectSync("I'm Priya Sharma, priya@example.com, card 4111 1111 1111 1111, cvv 123");
-// "I'm [PERSON_1], [EMAIL_1], card [CREDIT_CARD_1], cvv [BLOCKED:CARD_SECURITY_CODE]"
+// "I'm ss1_ubjboike, ss1_njpskmng, card ss1_efecfvfz, cvv [BLOCKED:CARD_SECURITY_CODE]"   (letters vary with the key)
 
 const reply = await callYourModel(prompt);              // the model only ever sees placeholders
 session.restore(reply, { allow: ["PII"] });             // email and name restored; the card stays [REDACTED:CREDIT_CARD]
@@ -80,11 +80,11 @@ createPrivacy({ detectors: [{ name: "ner", detect: async (text) => (await ner(te
 
 ## Tokens, the vault and keys
 
-- **Tokens** are `[TYPE_<id>]`. The same value always gets the same token within a scope (looked up by an HMAC-SHA256 fingerprint, RFC 2104), so a model can still tell "the same customer wrote twice". `tokenStyle` picks the id:
-  - `"sequential"` (default): `[EMAIL_1]`, `[EMAIL_2]`, numbered per type within the scope. Small models copy these more reliably. The number reveals nothing about the value, but ids are guessable within a scope.
-  - `"opaque"`: `[EMAIL_3f9a1c0b7e]`, 40 bits of the keyed HMAC. Unguessable, and the same value gives different tokens in different scopes or under different keys.
-- **Vault records** are encrypted with AES-256-GCM (NIST SP 800-38D). Each record has a random 96-bit IV and is bound to its scope and token via AAD, so records cannot be swapped. A `VaultStore` (in-memory by default, or your Redis or SQL implementation) only ever holds ciphertext and keyed fingerprints.
-- **Keys**: one 256-bit master key, split with HKDF-SHA256 (RFC 5869) into an encryption key and a token key. Generate one with `generateKey()`. Without a key, a random per-process key is used, which is right for an in-memory vault.
+- **Tokens.** The same value always gets the same token within a scope (looked up by an HMAC-SHA256 fingerprint, RFC 2104), so a model can still tell "the same customer wrote twice" and analytics on masked data still join and group correctly. Different scopes, or different keys, give unrelated tokens. `tokenStyle` picks the format:
+  - `"random"` (default): `ss1_njpskmng`, 8 letters from the keyed HMAC. Reveals nothing, not even what kind of value it replaced, and can't be guessed.
+  - `"sequential"`: `[EMAIL_1]`, `[PERSON_2]`, numbered per type within the scope. The type is visible and ids are guessable within a scope, but small models copy these most reliably.
+  - `"opaque"`: `[EMAIL_3f9a1c0b7e]`, the type plus 40 bits of the keyed HMAC.
+- **Numbers** in JSON stay numbers (amounts, salaries, ages, counts), so aggregates are unchanged. A number is masked only when it is an identifier: in a classified field such as `ssn`, or a long integer that validates as a card or phone number. It restores as a number.
 - **Retention**: `destroy(scope)` deletes a scope; its tokens, wherever they were logged, become permanently opaque. Records also carry `expiresAt` (`retentionMs`, default one hour).
 
 ```ts

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { Recognizer } from "./detectors/recognizers.js";
 export { aadhaarValid, cardBrand, emailValid, ibanValid, luhnValid, shannonEntropy, ssnValid, verhoeffValid } from "./detectors/validators.js";
 export { inferFieldType } from "./fields.js";
 export { generateKey } from "./crypto.js";
+export { renderToken, TOKEN_REFERENCE } from "./tokens.js";
+export type { TokenStyle } from "./tokens.js";
 export { InMemoryVaultStore } from "./vault.js";
 export type { VaultRecord, VaultStore } from "./vault.js";
 export { PrivacyError } from "./types.js";

package/dist/index.js

@@ -4,5 +4,6 @@ export { BUILT_IN_RECOGNIZERS } from "./detectors/recognizers.js";
 export { aadhaarValid, cardBrand, emailValid, ibanValid, luhnValid, shannonEntropy, ssnValid, verhoeffValid } from "./detectors/validators.js";
 export { inferFieldType } from "./fields.js";
 export { generateKey } from "./crypto.js";
+export { renderToken, TOKEN_REFERENCE } from "./tokens.js";
 export { InMemoryVaultStore } from "./vault.js";
 export { PrivacyError } from "./types.js";

package/dist/policy.js

@@ -1,6 +1,7 @@
 import { BUILT_IN_RECOGNIZERS } from "./detectors/recognizers.js";
 import { compileFieldRules, isClassification } from "./fields.js";
 import { PrivacyError } from "./types.js";
+import { renderToken } from "./tokens.js";
 /**
  * Default handling per entity type, following NIST SP 800-122's confidentiality-impact guidance, GDPR Art. 9
  * special categories, and PCI DSS v4.0:
@@ -109,7 +110,7 @@ export function maskValue(type, value) {
 }
 export function deniedReplacement(mode, type, value, token) {
     if (mode === "token")
-        return `[${token}]`;
+        return renderToken(token);
     if (mode === "mask")
         return maskValue(type, value);
     return `[REDACTED:${type}]`;

package/dist/privacy.d.ts

@@ -1,6 +1,7 @@
 import { type CompiledPolicy } from "./policy.js";
 import { type AuditEvent, type Detection, type EntityType, type PolicyConfig, type PrivacySummary, type ProtectOptions, type RestoreOptions } from "./types.js";
 import { type VaultStore } from "./vault.js";
+import { type TokenStyle } from "./tokens.js";
 export interface PrivacyOptions extends PolicyConfig {
     /**
      * 256-bit master key (32 bytes, or base64 of 32 bytes). Omitted, a random key is generated per process: tokens then
@@ -13,13 +14,14 @@ export interface PrivacyOptions extends PolicyConfig {
     /** How long an idle scope stays restorable, in ms. Default one hour. Records get a matching `expiresAt`. */
     retentionMs?: number;
     /**
-     * How token ids look.
-     * - `"sequential"` (default): `[EMAIL_1]`, `[PERSON_2]` — numbered per type within the scope. Small models copy
-     *   these reliably; with random ids they were measured to splice one token's id onto another's type. The number says
-     *   nothing about the value, and scopes stay unlinkable, but ids are guessable within a scope.
-     * - `"opaque"`: `[EMAIL_3f9a1c0b7e]` — 40 bits of the keyed HMAC, so a model can only reference tokens it was shown.
+     * How tokens look.
+     * - `"random"` (default): `ss1_kqfmzxat` — 8 letters from the keyed HMAC. Reveals nothing, not even what kind of value
+     *   it replaced, and is unguessable. The same value still gets the same token within a scope.
+     * - `"sequential"`: `[EMAIL_1]`, `[PERSON_2]` — type plus a per-scope counter. Small models copy these most reliably,
+     *   but the type is visible and ids are guessable within a scope.
+     * - `"opaque"`: `[EMAIL_3f9a1c0b7e]` — type plus 40 bits of the keyed HMAC.
      */
-    tokenStyle?: "sequential" | "opaque";
+    tokenStyle?: TokenStyle;
 }
 interface Entry {
     token: string;

package/dist/privacy.js

@@ -4,11 +4,9 @@ import { asNode, inferFieldType, itemSchema, matchFieldRule, nodeAnnotation, pro
 import { compilePolicy, deniedReplacement, isGranted, mergePolicyConfig } from "./policy.js";
 import { PrivacyError, } from "./types.js";
 import { InMemoryVaultStore } from "./vault.js";
-/** The token marker the model sees: `[EMAIL_1]` (sequential) or `[EMAIL_3f9a1c0b7e]` (opaque). */
+import { randomToken, renderToken, TOKEN_MARKER, TOKEN_REFERENCE } from "./tokens.js";
 const TOKEN_ID_LENGTH = 10;
-const TOKEN_MARKER = /\[(?:[A-Z][A-Z0-9_]*_(?:[0-9a-f]{10}|[1-9]\d{0,5})|BLOCKED:[A-Z][A-Z0-9_]*|REDACTED:[A-Z][A-Z0-9_]*)\]/g;
 /** Strict `[TYPE_id]` plus a bare `TYPE_id` (models sometimes drop the brackets); only tokens in this scope's vault are ever resolved. */
-const TOKEN_REFERENCE = /(?<![A-Za-z0-9_])\[?([A-Z][A-Z0-9_]*_(?:[0-9a-f]{10}|[1-9]\d{0,5}))\]?(?![A-Za-z0-9_])/g;
 const MAX_AUDIT_EVENTS = 5000;
 const MAX_MEMO_ENTRIES = 2000;
 /** Everything one scope knows: shared by every policy view of that scope. */
@@ -105,9 +103,9 @@ export class Privacy {
         this.keys = deriveKeys(normalizeMasterKey(key));
         this.store = store ?? new InMemoryVaultStore();
         this.retentionMs = retentionMs ?? 60 * 60 * 1000;
-        if (tokenStyle !== undefined && tokenStyle !== "sequential" && tokenStyle !== "opaque")
-            throw new PrivacyError(`mask: tokenStyle must be "sequential" or "opaque".`, "config");
-        this.tokenStyle = tokenStyle ?? "sequential";
+        if (tokenStyle !== undefined && tokenStyle !== "random" && tokenStyle !== "sequential" && tokenStyle !== "opaque")
+            throw new PrivacyError(`mask: tokenStyle must be "random", "sequential" or "opaque".`, "config");
+        this.tokenStyle = tokenStyle ?? "random";
         this.baseConfig = policy;
         this.basePolicy = compilePolicy(policy);
     }
@@ -169,7 +167,13 @@ export class Privacy {
             return existing;
         }
         let token;
-        if (this.tokenStyle === "sequential") {
+        if (this.tokenStyle === "random") {
+            let attempt = 0;
+            token = randomToken(fp, attempt);
+            while (state.byToken.has(token))
+                token = randomToken(fp, ++attempt);
+        }
+        else if (this.tokenStyle === "sequential") {
             let n = state.sequence.get(type) ?? 0;
             do {
                 n += 1;
@@ -462,7 +466,7 @@ export class PrivacySession {
             return kind === "number" ? Number(value) : value;
         if (fieldClass.classification === "BLOCK")
             return this.block(type);
-        return `[${this.engine.tokenFor(this.state, type, value, fieldClass.classification, kind)}]`;
+        return renderToken(this.engine.tokenFor(this.state, type, value, fieldClass.classification, kind));
     }
     block(type) {
         if (this.policy.onBlock === "throw")
@@ -486,10 +490,10 @@ export class PrivacySession {
             output += text.slice(cursor, d.start);
             const original = text.slice(d.start, d.end);
             if (d.token)
-                output += `[${d.token}]`;
+                output += renderToken(d.token);
             else {
                 const classification = this.policy.classify(d.type);
-                output += classification === "BLOCK" ? this.block(d.type) : `[${this.engine.tokenFor(this.state, d.type, original, classification, "string")}]`;
+                output += classification === "BLOCK" ? this.block(d.type) : renderToken(this.engine.tokenFor(this.state, d.type, original, classification, "string"));
             }
             cursor = d.end;
         }

package/dist/tokens.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How tokens look, in one place. Three styles:
+ *   random     (default)  ss1_kqfmzxat         — keyed-HMAC letters, no type shown; written bare
+ *   sequential            [EMAIL_1]             — type plus a per-scope counter; written in brackets
+ *   opaque                [EMAIL_3f9a1c0b7e]    — type plus keyed-HMAC hex; written in brackets
+ */
+export type TokenStyle = "random" | "sequential" | "opaque";
+export declare const RANDOM_PREFIX = "ss1_";
+export declare const RANDOM_ID_LENGTH = 8;
+/** Anything already masked: a token in any style, or a BLOCKED/REDACTED marker. Detection never touches these spans. */
+export declare const TOKEN_MARKER: RegExp;
+/**
+ * A token reference to restore. Brackets are optional on both forms, since models add or drop them; capture group 1 is
+ * the bare token. Only tokens present in the scope's vault are ever resolved, so look-alikes stay untouched.
+ */
+export declare const TOKEN_REFERENCE: RegExp;
+/** How a token is written into text: random tokens bare, typed tokens in brackets. */
+export declare function renderToken(token: string): string;
+/** `ss1_` + 8 letters derived from a hex fingerprint; `attempt` shifts the window to resolve the (rare) collision. */
+export declare function randomToken(fingerprintHex: string, attempt: number): string;

package/dist/tokens.js

@@ -0,0 +1,25 @@
+export const RANDOM_PREFIX = "ss1_";
+export const RANDOM_ID_LENGTH = 8;
+const RANDOM_ALPHABET = "abcdefghijklmnopqrstuvwxyz";
+const TYPED = String.raw `[A-Z][A-Z0-9_]*_(?:[0-9a-f]{10}|[1-9]\d{0,5})`;
+const RANDOM = String.raw `ss1_[a-z]{8}`;
+/** Anything already masked: a token in any style, or a BLOCKED/REDACTED marker. Detection never touches these spans. */
+export const TOKEN_MARKER = new RegExp(String.raw `\[(?:${TYPED}|BLOCKED:[A-Z][A-Z0-9_]*|REDACTED:[A-Z][A-Z0-9_]*)\]|(?<![A-Za-z0-9_])\[?${RANDOM}\]?(?![A-Za-z0-9_])`, "g");
+/**
+ * A token reference to restore. Brackets are optional on both forms, since models add or drop them; capture group 1 is
+ * the bare token. Only tokens present in the scope's vault are ever resolved, so look-alikes stay untouched.
+ */
+export const TOKEN_REFERENCE = new RegExp(String.raw `(?<![A-Za-z0-9_])\[?(${TYPED}|${RANDOM})\]?(?![A-Za-z0-9_])`, "g");
+/** How a token is written into text: random tokens bare, typed tokens in brackets. */
+export function renderToken(token) {
+    return token.startsWith(RANDOM_PREFIX) ? token : `[${token}]`;
+}
+/** `ss1_` + 8 letters derived from a hex fingerprint; `attempt` shifts the window to resolve the (rare) collision. */
+export function randomToken(fingerprintHex, attempt) {
+    let id = "";
+    for (let i = 0; i < RANDOM_ID_LENGTH; i++) {
+        const at = (attempt * 2 + i * 2) % (fingerprintHex.length - 1);
+        id += RANDOM_ALPHABET[parseInt(fingerprintHex.slice(at, at + 2), 16) % RANDOM_ALPHABET.length];
+    }
+    return RANDOM_PREFIX + id;
+}

package/package.json

@@ -1,52 +1,52 @@
-{
-  "name": "@abhishekvardanbotta/mask",
-  "version": "0.1.0",
-  "description": "Schema-aware PII classification, validated detection, reversible vault tokenization and authorization-checked restoration for LLM applications. Zero runtime dependencies.",
-  "type": "module",
-  "license": "MIT",
-  "author": "Abhishek Vardan Botta",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "pii",
-    "privacy",
-    "tokenization",
-    "pseudonymization",
-    "redaction",
-    "llm",
-    "ai",
-    "agents",
-    "kiln",
-    "gdpr",
-    "pci"
-  ],
-  "engines": {
-    "node": ">=20.3"
-  },
-  "scripts": {
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "test": "tsx --test tests/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.5",
-    "tsx": "^4.19.3",
-    "typescript": "^5.7.3"
-  }
-}
+{
+  "name": "@abhishekvardanbotta/mask",
+  "version": "0.2.0",
+  "description": "Schema-aware PII classification, validated detection, reversible vault tokenization and authorization-checked restoration for LLM applications. Zero runtime dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abhishek Vardan Botta",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pii",
+    "privacy",
+    "tokenization",
+    "pseudonymization",
+    "redaction",
+    "llm",
+    "ai",
+    "agents",
+    "kiln",
+    "gdpr",
+    "pci"
+  ],
+  "engines": {
+    "node": ">=20.3"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  }
+}