@vorionsys/security 1.0.0

package/dist/common/di.js

@@ -0,0 +1,219 @@
+/**
+ * Dependency Injection Utilities
+ *
+ * Provides interfaces and factory helpers for dependency injection,
+ * replacing service locator anti-pattern with explicit dependency injection.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// DEPENDENCY CONTAINER
+// =============================================================================
+/**
+ * Dependency container for managing application dependencies.
+ *
+ * This is a simple container that allows registering and retrieving dependencies.
+ * For most use cases, prefer passing dependencies directly to constructors.
+ *
+ * Use this container only when:
+ * - Multiple services need the same dependencies
+ * - You need late binding of dependencies
+ * - You're migrating from service locators incrementally
+ */
+export class DependencyContainer {
+    dependencies = new Map();
+    /**
+     * Register a dependency
+     */
+    register(key, dependency) {
+        this.dependencies.set(key, dependency);
+    }
+    /**
+     * Get a dependency
+     * @throws Error if dependency not found
+     */
+    get(key) {
+        const dep = this.dependencies.get(key);
+        if (dep === undefined) {
+            throw new Error(`Dependency '${key}' not found. Register it before use.`);
+        }
+        return dep;
+    }
+    /**
+     * Get a dependency or undefined if not found
+     */
+    getOptional(key) {
+        return this.dependencies.get(key);
+    }
+    /**
+     * Check if a dependency is registered
+     */
+    has(key) {
+        return this.dependencies.has(key);
+    }
+    /**
+     * Clear all dependencies (useful for testing)
+     */
+    clear() {
+        this.dependencies.clear();
+    }
+    /**
+     * Get all registered dependency keys
+     */
+    keys() {
+        return Array.from(this.dependencies.keys());
+    }
+}
+// =============================================================================
+// DEPENDENCY KEYS
+// =============================================================================
+/**
+ * Well-known dependency keys for type-safe registration
+ */
+export const DependencyKeys = {
+    DATABASE: 'database',
+    REDIS: 'redis',
+    CONFIG: 'config',
+    POOL: 'pool',
+    LOGGER: 'logger',
+};
+// =============================================================================
+// FACTORY HELPERS
+// =============================================================================
+/**
+ * Creates a factory function with pre-bound dependencies.
+ *
+ * This is useful for creating services that need dependencies but also
+ * want to allow overrides for testing.
+ *
+ * @example
+ * ```typescript
+ * const createService = withDependencies(
+ *   (deps: CoreDependencies) => new MyService(deps.database, deps.redis),
+ *   () => getDefaultDependencies()
+ * );
+ *
+ * // Use with defaults
+ * const service = createService();
+ *
+ * // Override for testing
+ * const testService = createService({ redis: mockRedis });
+ * ```
+ */
+export function withDependencies(factory, getDefaults) {
+    return (overrides) => {
+        const defaults = getDefaults();
+        const merged = { ...defaults, ...overrides };
+        return factory(merged);
+    };
+}
+/**
+ * Type guard to check if an object has all required dependencies
+ */
+export function hasRequiredDependencies(deps, required) {
+    return required.every((key) => {
+        const value = deps[key];
+        return value !== undefined && value !== null;
+    });
+}
+// =============================================================================
+// LAZY INITIALIZATION HELPERS
+// =============================================================================
+/**
+ * Creates a lazy-initialized dependency.
+ *
+ * The factory function is called only once on first access.
+ * Subsequent accesses return the cached value.
+ *
+ * @example
+ * ```typescript
+ * const lazyDb = lazy(() => getDatabase());
+ *
+ * // First call initializes
+ * const db1 = lazyDb();
+ *
+ * // Subsequent calls return cached value
+ * const db2 = lazyDb();
+ * ```
+ */
+export function lazy(factory) {
+    let instance;
+    let initialized = false;
+    return () => {
+        if (!initialized) {
+            instance = factory();
+            initialized = true;
+        }
+        return instance;
+    };
+}
+/**
+ * Creates an async lazy-initialized dependency.
+ *
+ * @example
+ * ```typescript
+ * const lazyConnection = lazyAsync(async () => connectToDatabase());
+ *
+ * // First call initializes
+ * const conn1 = await lazyConnection();
+ *
+ * // Subsequent calls return cached promise
+ * const conn2 = await lazyConnection();
+ * ```
+ */
+export function lazyAsync(factory) {
+    let promise;
+    return () => {
+        if (!promise) {
+            promise = factory();
+        }
+        return promise;
+    };
+}
+// =============================================================================
+// TESTING UTILITIES
+// =============================================================================
+/**
+ * Creates a mock dependency container for testing.
+ *
+ * @example
+ * ```typescript
+ * const mocks = createMockDependencies({
+ *   database: mockDatabase,
+ *   redis: mockRedis,
+ * });
+ * ```
+ */
+export function createMockDependencies(overrides = {}) {
+    return {
+        database: overrides.database,
+        redis: overrides.redis,
+        config: overrides.config,
+        pool: overrides.pool ?? null,
+    };
+}
+/**
+ * Verify that all required dependencies are provided.
+ * Throws descriptive error if any are missing.
+ */
+export function validateDependencies(deps, required, serviceName) {
+    const missing = required.filter((key) => {
+        const value = deps[key];
+        return value === undefined || value === null;
+    });
+    if (missing.length > 0) {
+        throw new Error(`${serviceName} is missing required dependencies: ${missing.join(', ')}. ` +
+            `Either inject them via constructor or ensure they are initialized before use.`);
+    }
+}
+// =============================================================================
+// DEFAULT CONTAINER INSTANCE
+// =============================================================================
+/**
+ * Default global container instance.
+ *
+ * IMPORTANT: Prefer explicit dependency injection over using this container.
+ * This is provided for gradual migration from service locators.
+ */
+export const defaultContainer = new DependencyContainer();
+//# sourceMappingURL=di.js.map

package/dist/common/di.js.map

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

package/dist/common/encryption.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Encryption utilities for sensitive data at rest
+ *
+ * Uses AES-256-GCM for authenticated encryption with PBKDF2 key derivation.
+ *
+ * Security notes:
+ * - Key derivation uses PBKDF2-SHA512 with 100,000+ iterations (OWASP recommended)
+ * - NEVER falls back to JWT secret (would cause data loss on rotation)
+ * - Supports versioned key derivation for future algorithm changes
+ */
+/**
+ * Key derivation function versions:
+ * - v1: SHA-256 (legacy, insecure - for migration only)
+ * - v2: PBKDF2-SHA512 (current, secure)
+ */
+export type KdfVersion = 1 | 2;
+/**
+ * Encrypted data envelope containing all components needed for decryption
+ */
+export interface EncryptedEnvelope {
+    /** Encrypted data as base64 */
+    ciphertext: string;
+    /** Initialization vector as base64 */
+    iv: string;
+    /** Authentication tag as base64 */
+    authTag: string;
+    /** Envelope version for future algorithm changes */
+    version: 1;
+    /**
+     * Key derivation version used to encrypt this data
+     * - kdfVersion 1: SHA-256 (legacy)
+     * - kdfVersion 2: PBKDF2-SHA512 (current)
+     * If absent, assumes v1 for backward compatibility
+     */
+    kdfVersion?: KdfVersion;
+}
+/**
+ * Marker interface to identify encrypted fields in JSON
+ */
+export interface EncryptedField {
+    __encrypted: true;
+    envelope: EncryptedEnvelope;
+}
+/**
+ * Encrypt a value using AES-256-GCM with PBKDF2-derived key
+ */
+export declare function encrypt(plaintext: string): EncryptedEnvelope;
+/**
+ * Decrypt a value using AES-256-GCM
+ *
+ * Automatically detects and uses the correct KDF version from the envelope.
+ * This ensures backward compatibility with data encrypted using the legacy SHA-256 method.
+ */
+export declare function decrypt(envelope: EncryptedEnvelope): string;
+/**
+ * Encrypt a JSON object, returning an encrypted field marker
+ */
+export declare function encryptObject(data: Record<string, unknown>): EncryptedField;
+/**
+ * Decrypt an encrypted field marker back to a JSON object
+ */
+export declare function decryptObject(field: EncryptedField): Record<string, unknown>;
+/**
+ * Check if a value is an encrypted field
+ */
+export declare function isEncryptedField(value: unknown): value is EncryptedField;
+/**
+ * Compute SHA-256 hash for tamper detection
+ */
+export declare function computeHash(data: string): string;
+/**
+ * Compute chained hash (includes previous hash for chain integrity)
+ */
+export declare function computeChainedHash(data: string, previousHash: string): string;
+/**
+ * Check if an envelope needs migration to the current KDF version
+ *
+ * @param envelope - The encrypted envelope to check
+ * @returns true if the envelope uses an older KDF version than current config
+ */
+export declare function needsMigration(envelope: EncryptedEnvelope): boolean;
+/**
+ * Migrate an encrypted envelope to the current KDF version
+ *
+ * This decrypts the data using its original KDF and re-encrypts with the current KDF.
+ * Use this during a migration window to upgrade legacy encrypted data.
+ *
+ * @param envelope - The encrypted envelope to migrate
+ * @returns New envelope encrypted with current KDF version
+ * @throws EncryptionError if decryption or re-encryption fails
+ */
+export declare function migrateEnvelope(envelope: EncryptedEnvelope): EncryptedEnvelope;
+/**
+ * Migrate an encrypted field to the current KDF version
+ *
+ * @param field - The encrypted field to migrate
+ * @returns New field with envelope encrypted using current KDF version
+ */
+export declare function migrateEncryptedField(field: EncryptedField): EncryptedField;
+/**
+ * Get the KDF version used in an envelope
+ *
+ * @param envelope - The envelope to check
+ * @returns The KDF version (1 for legacy, 2 for PBKDF2)
+ */
+export declare function getEnvelopeKdfVersion(envelope: EncryptedEnvelope): KdfVersion;
+import type { Config } from './config.js';
+/**
+ * Create an encryptIfEnabled function with injected configuration.
+ *
+ * This factory function removes the service locator anti-pattern by
+ * accepting configuration via parameter rather than calling getConfig().
+ *
+ * NOTE: This version does not include tracing to avoid circular dependencies.
+ * Use the traceEncryptSync wrapper from intent/tracing.js when tracing is needed.
+ *
+ * @param config - Application configuration (for encryption settings)
+ * @returns Function that encrypts data if encryption is enabled in config
+ *
+ * @example
+ * // With dependency injection
+ * const encryptIfEnabled = createEncryptIfEnabled(config);
+ * const encrypted = encryptIfEnabled(sensitiveData);
+ *
+ * @example
+ * // For testing
+ * const mockConfig = { intent: { encryptContext: false } } as Config;
+ * const encryptIfEnabled = createEncryptIfEnabled(mockConfig);
+ */
+export declare function createEncryptIfEnabled(config: Config): (data: Record<string, unknown>) => unknown;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/common/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/common/encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4BH;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,OAAO,EAAE,CAAC,CAAC;IACX;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,IAAI,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAgED;;GAEG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAkB5D;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAsB3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAM3E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAQxE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAK7E;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAInE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,iBAAiB,CAU9E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAS3E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,UAAU,CAE7E;AAMD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GACb,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAO5C"}

package/dist/common/encryption.js

@@ -0,0 +1,255 @@
+/**
+ * Encryption utilities for sensitive data at rest
+ *
+ * Uses AES-256-GCM for authenticated encryption with PBKDF2 key derivation.
+ *
+ * Security notes:
+ * - Key derivation uses PBKDF2-SHA512 with 100,000+ iterations (OWASP recommended)
+ * - NEVER falls back to JWT secret (would cause data loss on rotation)
+ * - Supports versioned key derivation for future algorithm changes
+ */
+import { createCipheriv, createDecipheriv, randomBytes, createHash, pbkdf2Sync } from 'node:crypto';
+import { getConfig } from './config.js';
+import { EncryptionError } from './errors.js';
+import { createLogger } from './logger.js';
+import { devOnlyDefault } from './security-mode.js';
+const logger = createLogger({ component: 'encryption' });
+/**
+ * Track whether we've already logged the SHA-256 deprecation warning
+ * to avoid spamming logs on every decrypt operation
+ */
+let sha256DeprecationWarningLogged = false;
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32; // 256 bits for AES-256
+/**
+ * Development-only fallback values
+ * These are only used when devOnlyDefault() permits (non-production modes)
+ */
+const DEV_FALLBACK_SALT = 'vorion-dev-salt-do-not-use-in-production';
+const DEV_FALLBACK_KEY = 'vorion-dev-key-32-chars-minimum!!';
+/**
+ * Derive a 256-bit key using the specified KDF version
+ *
+ * @param kdfVersion - Which key derivation function to use (1=SHA-256 legacy, 2=PBKDF2)
+ * @returns Derived 32-byte key suitable for AES-256
+ * @throws Error if encryption key is not configured (no fallback to JWT secret)
+ */
+function deriveKey(kdfVersion = 2) {
+    const config = getConfig();
+    // Get encryption key - use devOnlyDefault for secure fallback handling
+    let encryptionKey = config.encryption?.key;
+    if (!encryptionKey) {
+        // devOnlyDefault throws in production, returns fallback in development
+        encryptionKey = devOnlyDefault('VORION_ENCRYPTION_KEY', DEV_FALLBACK_KEY);
+    }
+    if (kdfVersion === 1) {
+        // Legacy SHA-256 derivation (insecure, for migration only)
+        // WARNING: This should only be used to decrypt old data during migration
+        if (!sha256DeprecationWarningLogged) {
+            sha256DeprecationWarningLogged = true;
+            logger.warn({
+                kdfVersion: 1,
+                recommendation: 'Migrate to KDF version 2 (PBKDF2-SHA512)',
+                migrationGuide: 'Use migrateEnvelope() or migrateEncryptedField() to upgrade encrypted data',
+            }, 'SECURITY DEPRECATION: Using legacy SHA-256 key derivation (KDF v1). ' +
+                'This method is cryptographically weak and should only be used for decrypting legacy data. ' +
+                'Please migrate all encrypted data to KDF v2 (PBKDF2-SHA512) using the migration utilities.');
+        }
+        return createHash('sha256').update(encryptionKey).digest();
+    }
+    // Version 2: PBKDF2-SHA512 (secure, current)
+    let salt = config.encryption?.salt;
+    if (!salt) {
+        // devOnlyDefault throws in production, returns fallback in development
+        salt = devOnlyDefault('VORION_ENCRYPTION_SALT', DEV_FALLBACK_SALT);
+    }
+    const iterations = config.encryption?.pbkdf2Iterations ?? 100000;
+    return pbkdf2Sync(encryptionKey, salt, iterations, KEY_LENGTH, 'sha512');
+}
+/**
+ * Get the current KDF version from config
+ */
+function getCurrentKdfVersion() {
+    const config = getConfig();
+    return (config.encryption?.kdfVersion ?? 2);
+}
+/**
+ * Encrypt a value using AES-256-GCM with PBKDF2-derived key
+ */
+export function encrypt(plaintext) {
+    const kdfVersion = getCurrentKdfVersion();
+    const key = deriveKey(kdfVersion);
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const encrypted = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    return {
+        ciphertext: encrypted.toString('base64'),
+        iv: iv.toString('base64'),
+        authTag: cipher.getAuthTag().toString('base64'),
+        version: 1,
+        kdfVersion,
+    };
+}
+/**
+ * Decrypt a value using AES-256-GCM
+ *
+ * Automatically detects and uses the correct KDF version from the envelope.
+ * This ensures backward compatibility with data encrypted using the legacy SHA-256 method.
+ */
+export function decrypt(envelope) {
+    if (envelope.version !== 1) {
+        throw new EncryptionError(`Unsupported encryption version: ${envelope.version}`, { version: envelope.version });
+    }
+    // Use the KDF version from the envelope, defaulting to v1 for backward compatibility
+    // with data encrypted before kdfVersion was added to envelopes
+    const kdfVersion = envelope.kdfVersion ?? 1;
+    const key = deriveKey(kdfVersion);
+    const iv = Buffer.from(envelope.iv, 'base64');
+    const authTag = Buffer.from(envelope.authTag, 'base64');
+    const ciphertext = Buffer.from(envelope.ciphertext, 'base64');
+    const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return decrypted.toString('utf8');
+}
+/**
+ * Encrypt a JSON object, returning an encrypted field marker
+ */
+export function encryptObject(data) {
+    const plaintext = JSON.stringify(data);
+    return {
+        __encrypted: true,
+        envelope: encrypt(plaintext),
+    };
+}
+/**
+ * Decrypt an encrypted field marker back to a JSON object
+ */
+export function decryptObject(field) {
+    if (!field.__encrypted || !field.envelope) {
+        throw new EncryptionError('Invalid encrypted field format', { hasEncryptedFlag: !!field.__encrypted, hasEnvelope: !!field.envelope });
+    }
+    const plaintext = decrypt(field.envelope);
+    return JSON.parse(plaintext);
+}
+/**
+ * Check if a value is an encrypted field
+ */
+export function isEncryptedField(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__encrypted' in value &&
+        value.__encrypted === true &&
+        'envelope' in value);
+}
+/**
+ * Compute SHA-256 hash for tamper detection
+ */
+export function computeHash(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/**
+ * Compute chained hash (includes previous hash for chain integrity)
+ */
+export function computeChainedHash(data, previousHash) {
+    return createHash('sha256')
+        .update(previousHash)
+        .update(data)
+        .digest('hex');
+}
+// ============================================================================
+// Migration Utilities
+// ============================================================================
+/**
+ * Check if an envelope needs migration to the current KDF version
+ *
+ * @param envelope - The encrypted envelope to check
+ * @returns true if the envelope uses an older KDF version than current config
+ */
+export function needsMigration(envelope) {
+    const currentVersion = getCurrentKdfVersion();
+    const envelopeVersion = envelope.kdfVersion ?? 1;
+    return envelopeVersion < currentVersion;
+}
+/**
+ * Migrate an encrypted envelope to the current KDF version
+ *
+ * This decrypts the data using its original KDF and re-encrypts with the current KDF.
+ * Use this during a migration window to upgrade legacy encrypted data.
+ *
+ * @param envelope - The encrypted envelope to migrate
+ * @returns New envelope encrypted with current KDF version
+ * @throws EncryptionError if decryption or re-encryption fails
+ */
+export function migrateEnvelope(envelope) {
+    if (!needsMigration(envelope)) {
+        return envelope; // Already at current version
+    }
+    // Decrypt with original KDF version (handled automatically by decrypt)
+    const plaintext = decrypt(envelope);
+    // Re-encrypt with current KDF version
+    return encrypt(plaintext);
+}
+/**
+ * Migrate an encrypted field to the current KDF version
+ *
+ * @param field - The encrypted field to migrate
+ * @returns New field with envelope encrypted using current KDF version
+ */
+export function migrateEncryptedField(field) {
+    if (!needsMigration(field.envelope)) {
+        return field;
+    }
+    return {
+        __encrypted: true,
+        envelope: migrateEnvelope(field.envelope),
+    };
+}
+/**
+ * Get the KDF version used in an envelope
+ *
+ * @param envelope - The envelope to check
+ * @returns The KDF version (1 for legacy, 2 for PBKDF2)
+ */
+export function getEnvelopeKdfVersion(envelope) {
+    return envelope.kdfVersion ?? 1;
+}
+/**
+ * Create an encryptIfEnabled function with injected configuration.
+ *
+ * This factory function removes the service locator anti-pattern by
+ * accepting configuration via parameter rather than calling getConfig().
+ *
+ * NOTE: This version does not include tracing to avoid circular dependencies.
+ * Use the traceEncryptSync wrapper from intent/tracing.js when tracing is needed.
+ *
+ * @param config - Application configuration (for encryption settings)
+ * @returns Function that encrypts data if encryption is enabled in config
+ *
+ * @example
+ * // With dependency injection
+ * const encryptIfEnabled = createEncryptIfEnabled(config);
+ * const encrypted = encryptIfEnabled(sensitiveData);
+ *
+ * @example
+ * // For testing
+ * const mockConfig = { intent: { encryptContext: false } } as Config;
+ * const encryptIfEnabled = createEncryptIfEnabled(mockConfig);
+ */
+export function createEncryptIfEnabled(config) {
+    return (data) => {
+        if (config.intent.encryptContext) {
+            return encryptObject(data);
+        }
+        return data;
+    };
+}
+//# sourceMappingURL=encryption.js.map

package/dist/common/encryption.js.map

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