@elanlanguages/bridge-anonymization 0.1.0

package/README.md

@@ -0,0 +1,382 @@
+# Bridge Anonymization
+
+On-device PII anonymization module for high-privacy translation workflows. Detects and replaces Personally Identifiable Information (PII) with placeholder tags while maintaining an encrypted mapping for later rehydration.
+
+## Features
+
+- **Structured PII Detection**: Regex-based detection for emails, phones, IBANs, credit cards, IPs, URLs
+- **Soft PII Detection**: ONNX-powered NER model for names, organizations, locations (auto-downloads on first use)
+- **Secure PII Mapping**: AES-256-GCM encrypted storage of original PII values
+- **Configurable Policies**: Customizable detection rules, thresholds, and allowlists
+- **Validation & Leak Scanning**: Built-in validation and optional leak detection
+
+## Installation
+
+```bash
+npm install bridge-anonymization
+```
+
+> **Bun users**: Install `onnxruntime-web` additionally: `bun add bridge-anonymization onnxruntime-web`
+
+## Quick Start
+
+### Regex-Only Mode (No Downloads Required)
+
+For structured PII like emails, phones, IBANs, credit cards:
+
+```typescript
+import { anonymizeRegexOnly } from 'bridge-anonymization';
+
+const result = await anonymizeRegexOnly(
+  'Contact john@example.com or call +49 30 123456. IBAN: DE89370400440532013000'
+);
+
+console.log(result.anonymizedText);
+// "Contact <PII type="EMAIL" id="1"/> or call <PII type="PHONE" id="2"/>. IBAN: <PII type="IBAN" id="3"/>"
+```
+
+### Full Mode with NER (Detects Names, Organizations, Locations)
+
+The NER model is automatically downloaded on first use (~280 MB for quantized):
+
+```typescript
+import { createAnonymizer } from 'bridge-anonymization';
+
+const anonymizer = createAnonymizer({
+  ner: { 
+    mode: 'quantized',  // or 'standard' for full model (~1.1 GB)
+    onStatus: (status) => console.log(status),  // Optional progress
+  }
+});
+
+await anonymizer.initialize();  // Downloads model if needed
+
+const result = await anonymizer.anonymize(
+  'Hello John Smith from Acme Corp in Berlin!'
+);
+
+console.log(result.anonymizedText);
+// "Hello <PII type="PERSON" id="1"/> from <PII type="ORG" id="2"/> in <PII type="LOCATION" id="3"/>!"
+```
+
+### One-liner with NER
+
+```typescript
+import { anonymizeWithNER } from 'bridge-anonymization';
+
+const result = await anonymizeWithNER(
+  'Contact John Smith at john@example.com',
+  { mode: 'quantized', onStatus: console.log }
+);
+```
+
+## API Reference
+
+### Configuration Options
+
+```typescript
+import { createAnonymizer, InMemoryKeyProvider } from 'bridge-anonymization';
+
+const anonymizer = createAnonymizer({
+  // NER configuration
+  ner: {
+    mode: 'quantized',     // 'standard' | 'quantized' | 'disabled' | 'custom'
+    autoDownload: true,    // Auto-download model if not present
+    onStatus: (s) => {},   // Status messages callback
+    onDownloadProgress: (p) => {},  // Download progress callback
+    
+    // For 'custom' mode only:
+    modelPath: './my-model.onnx',
+    vocabPath: './vocab.txt',
+  },
+  
+  // Encryption key provider
+  keyProvider: new InMemoryKeyProvider(),
+  
+  // Custom policy
+  defaultPolicy: { /* ... */ },
+});
+
+await anonymizer.initialize();
+```
+
+### NER Modes
+
+| Mode | Description | Size | Auto-Download |
+|------|-------------|------|---------------|
+| `'disabled'` | No NER, regex only | 0 | N/A |
+| `'quantized'` | Smaller model, ~95% accuracy | ~280 MB | Yes |
+| `'standard'` | Full model, best accuracy | ~1.1 GB | Yes |
+| `'custom'` | Your own ONNX model | Varies | No |
+
+### Main Functions
+
+#### `createAnonymizer(config?)`
+
+Creates an anonymizer instance:
+
+```typescript
+const anonymizer = createAnonymizer({
+  ner: { mode: 'quantized' }
+});
+
+await anonymizer.initialize();
+const result = await anonymizer.anonymize('text');
+await anonymizer.dispose();
+```
+
+#### `anonymize(text, locale?, policy?)`
+
+One-off anonymization (regex-only by default):
+
+```typescript
+const result = await anonymize('Contact test@example.com');
+```
+
+#### `anonymizeWithNER(text, nerConfig, policy?)`
+
+One-off anonymization with NER:
+
+```typescript
+const result = await anonymizeWithNER(
+  'Hello John Smith',
+  { mode: 'quantized' }
+);
+```
+
+#### `anonymizeRegexOnly(text, policy?)`
+
+Fast regex-only anonymization:
+
+```typescript
+const result = await anonymizeRegexOnly('Card: 4111111111111111');
+```
+
+### Result Structure
+
+```typescript
+interface AnonymizationResult {
+  // Text with PII replaced by placeholder tags
+  anonymizedText: string;
+  
+  // Detected entities (without original text for safety)
+  entities: Array<{
+    type: PIIType;
+    id: number;
+    start: number;
+    end: number;
+    confidence: number;
+    source: 'REGEX' | 'NER';
+  }>;
+  
+  // Encrypted PII mapping (for later rehydration)
+  piiMap: {
+    ciphertext: string;  // Base64
+    iv: string;          // Base64
+    authTag: string;     // Base64
+  };
+  
+  // Processing statistics
+  stats: {
+    countsByType: Record<PIIType, number>;
+    totalEntities: number;
+    processingTimeMs: number;
+    modelVersion: string;
+    leakScanPassed?: boolean;
+  };
+}
+```
+
+## Supported PII Types
+
+| Type | Description | Detection Method |
+|------|-------------|------------------|
+| `EMAIL` | Email addresses | Regex |
+| `PHONE` | Phone numbers (international) | Regex |
+| `IBAN` | International Bank Account Numbers | Regex + Checksum |
+| `BIC_SWIFT` | Bank Identifier Codes | Regex |
+| `CREDIT_CARD` | Credit card numbers | Regex + Luhn |
+| `IP_ADDRESS` | IPv4 and IPv6 addresses | Regex |
+| `URL` | Web URLs | Regex |
+| `CASE_ID` | Case/ticket numbers | Regex (configurable) |
+| `CUSTOMER_ID` | Customer identifiers | Regex (configurable) |
+| `PERSON` | Person names | NER |
+| `ORG` | Organization names | NER |
+| `LOCATION` | Location/place names | NER |
+| `ADDRESS` | Physical addresses | NER |
+| `DATE_OF_BIRTH` | Dates of birth | NER |
+
+## Configuration
+
+### Anonymization Policy
+
+```typescript
+import { createAnonymizer, PIIType } from 'bridge-anonymization';
+
+const anonymizer = createAnonymizer({
+  ner: { mode: 'quantized' },
+  defaultPolicy: {
+    // Which PII types to detect
+    enabledTypes: new Set([PIIType.EMAIL, PIIType.PHONE, PIIType.PERSON]),
+    
+    // Confidence thresholds per type (0.0 - 1.0)
+    confidenceThresholds: new Map([
+      [PIIType.PERSON, 0.8],
+      [PIIType.EMAIL, 0.5],
+    ]),
+    
+    // Terms to never treat as PII
+    allowlistTerms: new Set(['Customer Service', 'Help Desk']),
+    
+    // Enable leak scanning on output
+    enableLeakScan: true,
+  },
+});
+```
+
+### Custom Recognizers
+
+Add domain-specific patterns:
+
+```typescript
+import { createCustomIdRecognizer, PIIType, createAnonymizer } from 'bridge-anonymization';
+
+const customRecognizer = createCustomIdRecognizer([
+  {
+    name: 'Order Number',
+    pattern: /\bORD-[A-Z0-9]{8}\b/g,
+    type: PIIType.CASE_ID,
+  },
+]);
+
+const anonymizer = createAnonymizer();
+anonymizer.getRegistry().register(customRecognizer);
+```
+
+## Model Management
+
+Models are hosted on [Hugging Face Hub](https://huggingface.co/Xenova/xlm-roberta-base-ner-hrl) and automatically downloaded on first use.
+
+**Cache locations:**
+- **macOS**: `~/Library/Caches/bridge-anonymization/models/`
+- **Linux**: `~/.cache/bridge-anonymization/models/`
+- **Windows**: `%LOCALAPPDATA%/bridge-anonymization/models/`
+
+### Manual Model Management
+
+```typescript
+import { 
+  isModelDownloaded, 
+  downloadModel, 
+  clearModelCache,
+  listDownloadedModels,
+  getModelCacheDir 
+} from 'bridge-anonymization';
+
+// Check if model is downloaded
+const hasModel = await isModelDownloaded('quantized');
+
+// Manually download
+await downloadModel('quantized', (progress) => {
+  console.log(`${progress.file}: ${progress.percent}%`);
+});
+
+// List downloaded models
+const models = await listDownloadedModels();
+
+// Clear cache
+await clearModelCache('quantized');  // or clearModelCache() for all
+```
+
+## Encryption & Security
+
+The PII map is encrypted using AES-256-GCM:
+
+```typescript
+import { createAnonymizer, KeyProvider, generateKey } from 'bridge-anonymization';
+
+class SecureKeyProvider implements KeyProvider {
+  async getKey(): Promise<Buffer> {
+    // Retrieve from OS keychain, HSM, or secure storage
+    return await getKeyFromSecureStorage();
+  }
+}
+
+const anonymizer = createAnonymizer({
+  keyProvider: new SecureKeyProvider(),
+  ner: { mode: 'quantized' },
+});
+```
+
+### Security Best Practices
+
+- **Never log the raw PII map** - Always use encrypted storage
+- **Rotate keys** - Implement key rotation for long-running applications
+- **Use platform keystores** - iOS Keychain, Android Keystore, or OS credential managers
+- **Enable leak scanning** - Catch any missed PII in output
+
+## Bun Support
+
+This library works with [Bun](https://bun.sh). Since `onnxruntime-node` is a native Node.js addon, Bun users need `onnxruntime-web`:
+
+```bash
+bun add bridge-anonymization onnxruntime-web
+```
+
+Usage is identical - the library auto-detects the runtime:
+
+```typescript
+import { createAnonymizer } from 'bridge-anonymization';
+
+const anonymizer = createAnonymizer({
+  ner: { mode: 'quantized' }
+});
+
+await anonymizer.initialize();
+const result = await anonymizer.anonymize('Hello John Smith');
+```
+
+## Performance
+
+| Component | Time (2K chars) | Notes |
+|-----------|-----------------|-------|
+| Regex pass | ~5 ms | All regex recognizers |
+| NER inference | ~100-150 ms | Quantized model |
+| Total pipeline | ~150-200 ms | Full anonymization |
+
+| Model | Size | First-Use Download |
+|-------|------|-------------------|
+| Quantized | ~280 MB | ~30s on fast connection |
+| Standard | ~1.1 GB | ~2min on fast connection |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+### Building Custom Models
+
+For development or custom models, you can use the setup script:
+
+```bash
+# Requires Python 3.8+
+npm run setup:ner              # Standard model
+npm run setup:ner:quantized    # Quantized model
+```
+
+## Requirements
+
+- Node.js >= 18.0.0 (ONNX runtime included automatically)
+- Bun >= 1.0.0 (requires `onnxruntime-web`)
+
+## License
+
+MIT

package/dist/crypto/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Crypto Module
+ * Exports encryption utilities for PII map
+ */
+export * from './pii-map-crypto.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/crypto/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,qBAAqB,CAAC"}

package/dist/crypto/index.js

@@ -0,0 +1,6 @@
+/**
+ * Crypto Module
+ * Exports encryption utilities for PII map
+ */
+export * from './pii-map-crypto.js';
+//# sourceMappingURL=index.js.map

package/dist/crypto/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,qBAAqB,CAAC"}

package/dist/crypto/pii-map-crypto.d.ts

@@ -0,0 +1,100 @@
+/**
+ * PII Map Encryption
+ * AES-256-GCM encryption for the PII mapping
+ */
+import { EncryptedPIIMap } from '../types/index.js';
+import type { RawPIIMap } from '../pipeline/tagger.js';
+/**
+ * Encryption configuration
+ */
+export interface EncryptionConfig {
+    /** Algorithm (default: aes-256-gcm) */
+    algorithm: string;
+    /** IV length in bytes (default: 12 for GCM) */
+    ivLength: number;
+    /** Auth tag length in bytes (default: 16) */
+    authTagLength: number;
+}
+/**
+ * Default encryption configuration
+ */
+export declare const DEFAULT_ENCRYPTION_CONFIG: EncryptionConfig;
+/**
+ * Key generation options
+ */
+export interface KeyGenOptions {
+    /** Key length in bytes (default: 32 for AES-256) */
+    length: number;
+}
+/**
+ * Generates a random encryption key
+ * @returns Buffer containing the key
+ */
+export declare function generateKey(options?: Partial<KeyGenOptions>): Buffer;
+/**
+ * Derives a key from a password using PBKDF2
+ * @param password - Password string
+ * @param salt - Salt buffer (should be randomly generated and stored)
+ * @param iterations - Number of iterations (default: 100000)
+ * @returns Buffer containing the derived key
+ */
+export declare function deriveKey(password: string, salt: Buffer, iterations?: number): Buffer;
+/**
+ * Generates a random salt for key derivation
+ * @param length - Salt length in bytes (default: 16)
+ * @returns Buffer containing the salt
+ */
+export declare function generateSalt(length?: number): Buffer;
+/**
+ * Encrypts a PII map using AES-256-GCM
+ * @param piiMap - Raw PII map to encrypt
+ * @param key - 32-byte encryption key
+ * @param config - Encryption configuration
+ * @returns Encrypted PII map
+ */
+export declare function encryptPIIMap(piiMap: RawPIIMap, key: Buffer, config?: Partial<EncryptionConfig>): EncryptedPIIMap;
+/**
+ * Decrypts an encrypted PII map
+ * @param encrypted - Encrypted PII map
+ * @param key - 32-byte encryption key
+ * @param config - Encryption configuration
+ * @returns Decrypted PII map
+ */
+export declare function decryptPIIMap(encrypted: EncryptedPIIMap, key: Buffer, config?: Partial<EncryptionConfig>): RawPIIMap;
+/**
+ * Key provider interface for external key management
+ */
+export interface KeyProvider {
+    /** Gets the current encryption key */
+    getKey(): Promise<Buffer>;
+    /** Rotates to a new key (optional) */
+    rotateKey?(): Promise<Buffer>;
+}
+/**
+ * Simple in-memory key provider (for testing/development)
+ * WARNING: Not secure for production use
+ */
+export declare class InMemoryKeyProvider implements KeyProvider {
+    private key;
+    constructor(key?: Buffer);
+    getKey(): Promise<Buffer>;
+    rotateKey(): Promise<Buffer>;
+}
+/**
+ * Environment variable key provider
+ * Reads key from environment variable (base64 encoded)
+ */
+export declare class EnvKeyProvider implements KeyProvider {
+    private envVarName;
+    constructor(envVarName?: string);
+    getKey(): Promise<Buffer>;
+}
+/**
+ * Validates that a key is suitable for AES-256
+ */
+export declare function validateKey(key: Buffer): boolean;
+/**
+ * Securely compares two buffers (timing-safe)
+ */
+export declare function secureCompare(a: Buffer, b: Buffer): boolean;
+//# sourceMappingURL=pii-map-crypto.d.ts.map

package/dist/crypto/pii-map-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii-map-crypto.d.ts","sourceRoot":"","sources":["../../src/crypto/pii-map-crypto.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,MAAM,CAGxE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAe,GAC1B,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACrC,eAAe,CAwCjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,eAAe,EAC1B,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACrC,SAAS,CAuCX;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,sCAAsC;IACtC,SAAS,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,GAAG,CAAS;gBAER,GAAG,CAAC,EAAE,MAAM;IAIlB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAIzB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;CAInC;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,UAAU,CAAS;gBAEf,UAAU,GAAE,MAA6B;IAI/C,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAahC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK3D"}

package/dist/crypto/pii-map-crypto.js

@@ -0,0 +1,163 @@
+/**
+ * PII Map Encryption
+ * AES-256-GCM encryption for the PII mapping
+ */
+import * as crypto from 'crypto';
+/**
+ * Default encryption configuration
+ */
+export const DEFAULT_ENCRYPTION_CONFIG = {
+    algorithm: 'aes-256-gcm',
+    ivLength: 12,
+    authTagLength: 16,
+};
+/**
+ * Generates a random encryption key
+ * @returns Buffer containing the key
+ */
+export function generateKey(options = {}) {
+    const length = options.length ?? 32;
+    return crypto.randomBytes(length);
+}
+/**
+ * Derives a key from a password using PBKDF2
+ * @param password - Password string
+ * @param salt - Salt buffer (should be randomly generated and stored)
+ * @param iterations - Number of iterations (default: 100000)
+ * @returns Buffer containing the derived key
+ */
+export function deriveKey(password, salt, iterations = 100000) {
+    return crypto.pbkdf2Sync(password, salt, iterations, 32, 'sha256');
+}
+/**
+ * Generates a random salt for key derivation
+ * @param length - Salt length in bytes (default: 16)
+ * @returns Buffer containing the salt
+ */
+export function generateSalt(length = 16) {
+    return crypto.randomBytes(length);
+}
+/**
+ * Encrypts a PII map using AES-256-GCM
+ * @param piiMap - Raw PII map to encrypt
+ * @param key - 32-byte encryption key
+ * @param config - Encryption configuration
+ * @returns Encrypted PII map
+ */
+export function encryptPIIMap(piiMap, key, config = {}) {
+    const encConfig = { ...DEFAULT_ENCRYPTION_CONFIG, ...config };
+    // Validate key length
+    if (key.length !== 32) {
+        throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+    }
+    // Convert map to JSON
+    const mapObject = {};
+    for (const [k, v] of piiMap) {
+        mapObject[k] = v;
+    }
+    const plaintext = JSON.stringify(mapObject);
+    // Generate random IV
+    const iv = crypto.randomBytes(encConfig.ivLength);
+    // Create cipher
+    const cipher = crypto.createCipheriv(encConfig.algorithm, key, iv, { authTagLength: encConfig.authTagLength });
+    // Encrypt
+    const encrypted = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    // Get auth tag
+    const authTag = cipher.getAuthTag();
+    return {
+        ciphertext: encrypted.toString('base64'),
+        iv: iv.toString('base64'),
+        authTag: authTag.toString('base64'),
+    };
+}
+/**
+ * Decrypts an encrypted PII map
+ * @param encrypted - Encrypted PII map
+ * @param key - 32-byte encryption key
+ * @param config - Encryption configuration
+ * @returns Decrypted PII map
+ */
+export function decryptPIIMap(encrypted, key, config = {}) {
+    const encConfig = { ...DEFAULT_ENCRYPTION_CONFIG, ...config };
+    // Validate key length
+    if (key.length !== 32) {
+        throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+    }
+    // Decode base64
+    const ciphertext = Buffer.from(encrypted.ciphertext, 'base64');
+    const iv = Buffer.from(encrypted.iv, 'base64');
+    const authTag = Buffer.from(encrypted.authTag, 'base64');
+    // Create decipher
+    const decipher = crypto.createDecipheriv(encConfig.algorithm, key, iv, { authTagLength: encConfig.authTagLength });
+    // Set auth tag
+    decipher.setAuthTag(authTag);
+    // Decrypt
+    const decrypted = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    // Parse JSON back to map
+    const mapObject = JSON.parse(decrypted.toString('utf8'));
+    const piiMap = new Map();
+    for (const [k, v] of Object.entries(mapObject)) {
+        piiMap.set(k, v);
+    }
+    return piiMap;
+}
+/**
+ * Simple in-memory key provider (for testing/development)
+ * WARNING: Not secure for production use
+ */
+export class InMemoryKeyProvider {
+    key;
+    constructor(key) {
+        this.key = key ?? generateKey();
+    }
+    async getKey() {
+        return this.key;
+    }
+    async rotateKey() {
+        this.key = generateKey();
+        return this.key;
+    }
+}
+/**
+ * Environment variable key provider
+ * Reads key from environment variable (base64 encoded)
+ */
+export class EnvKeyProvider {
+    envVarName;
+    constructor(envVarName = 'PII_ENCRYPTION_KEY') {
+        this.envVarName = envVarName;
+    }
+    async getKey() {
+        const keyBase64 = process.env[this.envVarName];
+        if (keyBase64 === undefined || keyBase64.length === 0) {
+            throw new Error(`Encryption key not found in environment variable: ${this.envVarName}`);
+        }
+        const key = Buffer.from(keyBase64, 'base64');
+        if (key.length !== 32) {
+            throw new Error(`Invalid key length from ${this.envVarName}: expected 32 bytes`);
+        }
+        return key;
+    }
+}
+/**
+ * Validates that a key is suitable for AES-256
+ */
+export function validateKey(key) {
+    return key.length === 32;
+}
+/**
+ * Securely compares two buffers (timing-safe)
+ */
+export function secureCompare(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(a, b);
+}
+//# sourceMappingURL=pii-map-crypto.js.map

package/dist/crypto/pii-map-crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii-map-crypto.js","sourceRoot":"","sources":["../../src/crypto/pii-map-crypto.ts"],"names":[],"mappings":"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"}