@abhishekvardanbotta/mask 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * How a piece of data is handled.
+ *
+ * - `PII`       — personal data. Replaced with a reversible vault token; restorable by any principal granted `PII`
+ *                 (or `*`, or the entity type itself).
+ * - `SENSITIVE` — high-impact data (national IDs, card numbers, health, GDPR Art. 9 categories). Tokenized like PII,
+ *                 but `*` does NOT cover it: a principal needs an explicit `SENSITIVE` or entity-type grant.
+ * - `PUBLIC`    — left untouched. On a field, it also switches detection off for that subtree.
+ * - `BLOCK`     — removed irreversibly. Never written to the vault, so nothing can ever restore it.
+ */
+export type Classification = "PII" | "SENSITIVE" | "PUBLIC" | "BLOCK";
+/** Built-in entity types. Any `UPPER_SNAKE` string is also accepted as a custom type. */
+export type BuiltInEntityType = "EMAIL" | "PHONE" | "PERSON" | "ADDRESS" | "LOCATION" | "DATE_OF_BIRTH" | "IP_ADDRESS" | "USERNAME" | "CREDIT_CARD" | "CARD_SECURITY_CODE" | "IBAN" | "BANK_ACCOUNT" | "US_SSN" | "IN_AADHAAR" | "IN_PAN" | "NATIONAL_ID" | "PASSPORT" | "DRIVERS_LICENSE" | "HEALTH" | "SPECIAL_CATEGORY" | "CREDENTIAL";
+export type EntityType = BuiltInEntityType | (string & {});
+/**
+ * Who may see a restored value. A grant is a classification (`"PII"`, `"SENSITIVE"`), an entity type (`"EMAIL"`),
+ * or `"*"` — every `PII`-classified type, deliberately excluding `SENSITIVE`.
+ */
+export type Grant = "*" | Classification | EntityType;
+/** What a principal sees in place of a value it is not allowed to restore. */
+export type DeniedMode = "redact" | "mask" | "token";
+/** A detector's raw hit, before policy is applied. Offsets are UTF-16 indices into the scanned text. */
+export interface Detection {
+    type: EntityType;
+    start: number;
+    end: number;
+    /** Confidence in [0, 1]. Compared against the policy's `threshold` (default 0.5). */
+    score: number;
+}
+/**
+ * A pluggable recognizer. Use it to add an NER model, an LLM-based classifier, a dictionary of customer IDs, etc.
+ * Synchronous detectors run everywhere; asynchronous ones run only from `protect()` (not `protectSync()`).
+ */
+export interface Detector {
+    readonly name: string;
+    detect(text: string): Detection[] | Promise<Detection[]>;
+}
+/** A field-level classification, from config, a schema annotation, or field-name inference. */
+export interface FieldClass {
+    classification: Classification;
+    type?: EntityType;
+}
+export interface PolicyConfig {
+    /** Classification per entity type, overriding the defaults (see `DEFAULT_POLICIES`). */
+    policies?: Partial<Record<EntityType, Classification>>;
+    /**
+     * Classification per field path. Paths are dot-separated keys; array indices are transparent. `*` matches one
+     * key, `**` any number. A bare key (`"ssn"`) matches that key at any depth.
+     * Example: `{ "customer.email": "PII", "**.diagnosis": { classification: "SENSITIVE", type: "HEALTH" } }`.
+     */
+    fields?: Record<string, Classification | FieldClass>;
+    /** Extra detectors, run alongside the built-ins. */
+    detectors?: Detector[];
+    /** Names of built-in recognizers to switch off (see `BUILT_IN_RECOGNIZERS`). */
+    disable?: string[];
+    /** Minimum detection confidence, 0..1. Default 0.5. */
+    threshold?: number;
+    /** Classify fields from their key names (`email`, `phoneNumber`, `ssn`, ...). Default true. */
+    inferFromFieldNames?: boolean;
+    /** Values that are never tokenized, matched exactly (strings) or by test (RegExp). */
+    allowlist?: Array<string | RegExp>;
+    /** `"redact"` (default) replaces BLOCK values with `[BLOCKED:TYPE]`; `"throw"` rejects the whole operation. */
+    onBlock?: "redact" | "throw";
+}
+export interface RestoreOptions {
+    /** What the principal may see in the clear. Omit together with `trusted` to restore nothing. */
+    allow?: Grant[];
+    /** Full restoration of everything restorable — for code inside the trust boundary only. */
+    trusted?: boolean;
+    /** What denied values become. Default `"redact"`. */
+    onDenied?: DeniedMode;
+    /** Recorded in the audit log. */
+    principal?: string;
+}
+export interface ProtectOptions {
+    /** A JSON Schema describing `value`. Its `x-privacy`/`format`/description annotations classify fields. */
+    schema?: unknown;
+}
+export interface AuditEvent {
+    at: string;
+    action: "tokenize" | "block" | "restore" | "deny" | "unknown-token";
+    type?: EntityType;
+    classification?: Classification;
+    principal?: string;
+    /** The token involved. Never the plaintext. */
+    token?: string;
+}
+export interface PrivacySummary {
+    tokenized: number;
+    blocked: number;
+    restored: number;
+    denied: number;
+    types: EntityType[];
+}
+export declare class PrivacyError extends Error {
+    readonly code: "blocked" | "config" | "vault";
+    constructor(message: string, code: "blocked" | "config" | "vault");
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class PrivacyError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "PrivacyError";
+    }
+}

package/dist/vault.d.ts

@@ -0,0 +1,30 @@
+import type { Sealed } from "./crypto.js";
+import type { Classification, EntityType } from "./types.js";
+/**
+ * One tokenized value as persisted. The plaintext exists only inside `ct` (AES-256-GCM); `fp` is a keyed HMAC, so
+ * a store — Redis, SQL, a file — never holds anything readable without the master key.
+ */
+export interface VaultRecord extends Sealed {
+    token: string;
+    type: EntityType;
+    classification: Exclude<Classification, "PUBLIC" | "BLOCK">;
+    kind: "string" | "number";
+    fp: string;
+    createdAt: number;
+    expiresAt?: number;
+}
+/** Persistence for vault records, partitioned by scope. Implement it to back the vault with your own database. */
+export interface VaultStore {
+    put(scope: string, record: VaultRecord): void | Promise<void>;
+    list(scope: string): VaultRecord[] | Promise<VaultRecord[]>;
+    deleteScope(scope: string): void | Promise<void>;
+}
+/** Process-lifetime store. Expired records are dropped on read. */
+export declare class InMemoryVaultStore implements VaultStore {
+    private readonly scopes;
+    put(scope: string, record: VaultRecord): void;
+    list(scope: string): VaultRecord[];
+    deleteScope(scope: string): void;
+    /** Number of scopes held — for tests and diagnostics. */
+    get size(): number;
+}

package/dist/vault.js

@@ -0,0 +1,29 @@
+/** Process-lifetime store. Expired records are dropped on read. */
+export class InMemoryVaultStore {
+    scopes = new Map();
+    put(scope, record) {
+        let records = this.scopes.get(scope);
+        if (!records) {
+            records = new Map();
+            this.scopes.set(scope, records);
+        }
+        records.set(record.token, record);
+    }
+    list(scope) {
+        const records = this.scopes.get(scope);
+        if (!records)
+            return [];
+        const now = Date.now();
+        for (const [token, record] of records)
+            if (record.expiresAt !== undefined && record.expiresAt <= now)
+                records.delete(token);
+        return [...records.values()];
+    }
+    deleteScope(scope) {
+        this.scopes.delete(scope);
+    }
+    /** Number of scopes held — for tests and diagnostics. */
+    get size() {
+        return this.scopes.size;
+    }
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@abhishekvardanbotta/mask",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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"
+  }
+}