mask-privacy 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+/** Interface every vault backend must implement. */
+declare abstract class BaseVault {
+    /** Persist a token → plaintext mapping with a TTL. Optionally save a reverse lookup hash. */
+    abstract store(token: string, plaintext: string, ttlSeconds: number, ptHash?: string | null): Promise<void> | void;
+    /** Return the existing unexpired token for a given plaintext hash, or null. */
+    abstract getTokenByPlaintextHash(ptHash: string): Promise<string | null> | string | null;
+    /** Return the plaintext for token, or null if missing/expired. */
+    abstract retrieve(token: string): Promise<string | null> | string | null;
+    /** Delete a token and its reverse mapping. */
+    abstract delete(token: string): Promise<void> | void;
+}
+declare function getVault(): BaseVault;
+/**
+ * Tokenise rawText, encrypt it, store in vault, return the FPE token.
+ */
+declare function encode(rawText: string, options?: {
+    ttl?: number;
+}): Promise<string>;
+/** Async wrapper for encode (parity with Python aencode). */
+declare const aencode: typeof encode;
+/**
+ * Detokenise token via vault lookup and decrypt it.
+ */
+declare function decode(token: string): Promise<string>;
+/** Async wrapper for decode (parity with Python adecode). */
+declare const adecode: typeof decode;
+/**
+ * Find all Mask tokens within text and replace them with their original plaintext.
+ */
+declare function detokenizeText(text: string): Promise<string>;
+/** Async wrapper for detokenizeText (parity with Python adetokenize_text). */
+declare const adetokenizeText: typeof detokenizeText;
+
+/**
+ * Format-Preserving Encryption (FPE) token generation.
+ *
+ * Generates structurally valid, **deterministic** tokens that preserve the
+ * format of the original data type so downstream tools, schemas, and
+ * validators continue to work without modification.
+ *
+ * Determinism is achieved via HMAC-SHA256 keyed with a master key, ensuring
+ * the same plaintext always produces the same token. This preserves entity
+ * relationships for LLMs (e.g. "John" is always [TKN-abc]) without leaking
+ * the identity.
+ *
+ * Supported formats:
+ *   - Email  →  tkn-<hex>@email.com
+ *   - Phone  →  +1-555-<7 digits>
+ *   - SSN    →  000-00-<4 digits>
+ *   - CC     →  4000-0000-0000-<4 digits>
+ *   - Routing→  000000<3 digits>
+ *   - Default→  [TKN-<hex>]
+ */
+/** Clear the cached master key. Useful in tests. */
+declare function resetMasterKey(): void;
+/**
+ * Return a **deterministic**, format-preserving token for rawText.
+ *
+ * The token is structurally compatible with the original data type
+ * so that downstream schema validators, regex checks, and database
+ * constraints continue to pass.
+ */
+declare function generateFPEToken(rawText: string): string;
+/**
+ * Heuristic: return true if value appears to be a Mask token.
+ */
+declare function looksLikeToken(value: string): boolean;
+
+declare class PresidioScanner {
+    protected _supportedEntities: string[];
+    constructor();
+    setSupportedEntities(entities: string[]): void;
+    /** Validate a credit card number using the Luhn algorithm. */
+    protected static _luhnChecksum(ccNumber: string): boolean;
+    /** Validate a US ABA routing number using the checksum algorithm. */
+    protected static _abaChecksum(routingNumber: string): boolean;
+    protected _tier1Regex(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
+    protected _tier2Nlp(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
+    protected _resolveBoost(context?: string | null): Set<string>;
+    scanAndTokenize(text: string, options?: {
+        encodeFn?: (val: string) => Promise<string>;
+        pipeline?: string[];
+        confidenceThreshold?: number;
+        context?: string | null;
+        aggressive?: boolean;
+    }): Promise<string>;
+    scanAndReturnEntities(text: string, options?: {
+        encodeFn?: (val: string) => Promise<string>;
+        pipeline?: string[];
+        confidenceThreshold?: number;
+        context?: string | null;
+        aggressive?: boolean;
+    }): Promise<any[]>;
+}
+/**
+ * Scanner that calls a remote Presidio Analyzer endpoint.
+ */
+declare class RemotePresidioScanner extends PresidioScanner {
+    private endpointUrl;
+    constructor(endpointUrl: string);
+    protected _tier2Nlp(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
+}
+declare function getScanner(): PresidioScanner;
+
+/**
+ * Custom exception hierarchy for the Mask SDK.
+ *
+ * Provides specific exceptions so callers can implement targeted
+ * retry/fallback logic instead of catching generic Error.
+ */
+declare class MaskError extends Error {
+    constructor(message: string);
+}
+/** Raised when a vault backend (Redis, DynamoDB) is unreachable. */
+declare class MaskVaultConnectionError extends MaskError {
+}
+/** Raised when CryptoEngine.decrypt() fails (bad key, corrupt data). */
+declare class MaskDecryptionError extends MaskError {
+}
+/** Raised when spaCy / Presidio analysis exceeds the time budget. */
+declare class MaskNLPTimeout extends MaskError {
+}
+
+/**
+ * Core cryptography engine for Mask SDK.
+ *
+ * Provides a CryptoEngine singleton that handles Envelope Encryption,
+ * ensuring that plaintext PII is encrypted locally before being
+ * transmitted and stored in distributed vaults (Redis/Memcached/DynamoDB).
+ *
+ * Requires MASK_ENCRYPTION_KEY to be set in the environment.
+ */
+declare class CryptoEngine {
+    private static _instance;
+    private _fernet;
+    private constructor();
+    static getInstance(): CryptoEngine;
+    /** Clear the singleton instance to force re-initialization (useful for key rotation). */
+    static reset(): void;
+    private _init;
+    encrypt(plaintext: string): string;
+    decrypt(ciphertext: string): string;
+}
+
+/**
+ * Asynchronous audit logger for Mask Privacy SDK.
+ *
+ * Logs every tokenisation / detokenisation event *without* recording the
+ * plaintext PII. Events are batched and flushed to:
+ *   - stdout / Console (default)
+ *   - Customer SIEM via structured JSON log lines
+ *
+ * NOTE: This SDK is LOCAL-FIRST. Audits are stored in a local
+ * SQLite file (.mask_audit.db) and are NOT sent anywhere externally.
+ */
+declare class AuditLogger {
+    private static _instance;
+    private _dbPath;
+    private _flushInterval;
+    private _running;
+    private _timer;
+    private _buffer;
+    private _dbDisabled;
+    private _db;
+    private constructor();
+    static getInstance(): AuditLogger;
+    log(action: string, token: string, dataType?: string, agent?: string, tool?: string, extra?: Record<string, any>): void;
+    start(): void;
+    stop(): void;
+    private _flush;
+}
+
+/**
+ * Explicit Client initialization for the Mask SDK.
+ *
+ * Provides MaskClient — a unified, explicitly-configured client that
+ * bundles vault, crypto, scanner, and audit logger into a single object.
+ */
+
+declare class MaskClient {
+    vault: BaseVault;
+    crypto: CryptoEngine;
+    scanner: PresidioScanner;
+    auditLogger: AuditLogger;
+    /** backward compat alias */
+    logger: AuditLogger;
+    ttl: number;
+    /**
+     * Initialise the client with specific component instances.
+     *
+     * If an instance is not provided, the client will fall back to
+     * the standard environment-configured singleton for that component.
+     */
+    constructor(options?: {
+        vault?: BaseVault;
+        crypto?: CryptoEngine;
+        scanner?: PresidioScanner;
+        auditLogger?: AuditLogger;
+        ttl?: number;
+    });
+    /**
+     * Tokenise rawText, encrypt it, and store it in the vault.
+     *
+     * Includes deduplication: if the same plaintext has been encoded
+     * before and the token is still active, the existing token is returned.
+     */
+    encode(rawText: string): Promise<string>;
+    /** Retrieve token from vault and decrypt it. */
+    decode(token: string): Promise<string>;
+    /** Scan text using the Waterfall pipeline and replace PII with FPE tokens. */
+    scanAndTokenize(text: string): Promise<string>;
+    /** Async wrapper for encode (parity with Python aencode). */
+    aencode(rawText: string): Promise<string>;
+    /** Async wrapper for decode (parity with Python adecode). */
+    adecode(token: string): Promise<string>;
+    /** Async wrapper for scanAndTokenize (parity with Python ascan_and_tokenize). */
+    ascanAndTokenize(text: string): Promise<string>;
+    /** Find and replace all tokens within text with their plaintext. */
+    detokenizeText(text: string): Promise<string>;
+    /** Async wrapper for detokenizeText (parity with Python adetokenize_text). */
+    adetokenizeText(text: string): Promise<string>;
+}
+
+/**
+ * Mask Privacy SDK
+ * Just-In-Time Privacy Middleware for AI Agents.
+ *
+ * Provides format-preserving encryption, local/distributed vaulting,
+ * and framework-agnostic tool interception hooks.
+ */
+declare const VERSION = "1.0.0";
+
+/**
+ * Detect PII entities in text and return a list of objects with metadata.
+ */
+declare function detectEntitiesWithConfidence(text: string, options?: {
+    pipeline?: string[];
+    confidenceThreshold?: number;
+    context?: string | null;
+    aggressive?: boolean;
+}): Promise<any[]>;
+/**
+ * Async variant of getScanner().scanAndTokenize().
+ */
+declare function ascanAndTokenize(text: string, options?: {
+    pipeline?: string[];
+    confidenceThreshold?: number;
+    context?: string | null;
+    aggressive?: boolean;
+}): Promise<string>;
+
+/**
+ * Drop-in decorator for LangChain tools with automatic PII protection.
+ */
+declare function secureTool(...args: any[]): any;
+
+export { MaskClient, MaskDecryptionError, MaskError, MaskNLPTimeout, MaskVaultConnectionError, RemotePresidioScanner, VERSION, adecode, adetokenizeText, aencode, ascanAndTokenize, decode, detectEntitiesWithConfidence, detokenizeText, encode, generateFPEToken, getScanner, getVault, looksLikeToken, resetMasterKey, secureTool };