@fgv/ts-extras 5.0.2 → 5.1.0-0

package/lib/packlets/crypto-utils/converters.js

@@ -0,0 +1,192 @@
+"use strict";
+// Copyright (c) 2024 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptedFile = exports.namedSecret = exports.uint8ArrayFromBase64 = exports.base64String = exports.keyDerivationParams = exports.keyDerivationFunction = exports.encryptedFileErrorMode = exports.encryptedFileFormat = exports.encryptionAlgorithm = void 0;
+exports.createEncryptedFileConverter = createEncryptedFileConverter;
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const ts_utils_1 = require("@fgv/ts-utils");
+const Constants = __importStar(require("./constants"));
+// ============================================================================
+// Base Converters
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.EncryptionAlgorithm | encryption algorithm} values.
+ * @public
+ */
+exports.encryptionAlgorithm = ts_utils_1.Converters.enumeratedValue([Constants.DEFAULT_ALGORITHM]);
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileFormat | encrypted file format} version.
+ * @public
+ */
+exports.encryptedFileFormat = ts_utils_1.Converters.enumeratedValue([
+    Constants.ENCRYPTED_FILE_FORMAT
+]);
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileErrorMode | encrypted file error mode}.
+ * @public
+ */
+exports.encryptedFileErrorMode = ts_utils_1.Converters.enumeratedValue(['fail', 'skip', 'warn']);
+/**
+ * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
+ * @public
+ */
+exports.keyDerivationFunction = ts_utils_1.Converters.enumeratedValue(['pbkdf2']);
+/**
+ * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * @public
+ */
+exports.keyDerivationParams = ts_utils_1.Converters.object({
+    kdf: exports.keyDerivationFunction,
+    salt: ts_utils_1.Converters.string,
+    iterations: ts_utils_1.Converters.number
+});
+/**
+ * Converter for base64 strings (validates format).
+ * @public
+ */
+exports.base64String = ts_utils_1.Converters.string.withConstraint((value) => {
+    // Basic base64 validation - check for valid characters and padding
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    if (!base64Regex.test(value)) {
+        return (0, ts_utils_1.fail)('Invalid base64 encoding');
+    }
+    return (0, ts_utils_1.succeed)(value);
+});
+// ============================================================================
+// Uint8Array Converter
+// ============================================================================
+/**
+ * Converter which converts a base64 string to a Uint8Array.
+ * @public
+ */
+exports.uint8ArrayFromBase64 = ts_utils_1.Converters.string.map((base64) => {
+    try {
+        // Use Buffer in Node.js environment, atob in browser
+        if (typeof Buffer !== 'undefined') {
+            return (0, ts_utils_1.succeed)(Uint8Array.from(Buffer.from(base64, 'base64')));
+        }
+        /* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+        const binaryString = atob(base64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+        return (0, ts_utils_1.succeed)(bytes);
+    }
+    catch (e) {
+        // This catch is for browser's atob() which throws on invalid base64
+        // Node's Buffer.from() doesn't throw, it ignores invalid characters
+        const message = e instanceof Error ? e.message : String(e);
+        return (0, ts_utils_1.fail)(`Invalid base64: ${message}`);
+    }
+    /* c8 ignore stop */
+});
+// ============================================================================
+// Named Secret Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.INamedSecret | named secret} from JSON representation.
+ * Expects key as base64 string in JSON, converts to Uint8Array.
+ * @public
+ */
+exports.namedSecret = ts_utils_1.Converters.object({
+    name: ts_utils_1.Converters.string,
+    key: exports.uint8ArrayFromBase64
+});
+/**
+ * Base converter for encrypted file structure (without typed metadata).
+ */
+const baseEncryptedFileConverter = ts_utils_1.Converters.object({
+    format: exports.encryptedFileFormat,
+    secretName: ts_utils_1.Converters.string,
+    algorithm: exports.encryptionAlgorithm,
+    iv: exports.base64String,
+    authTag: exports.base64String,
+    encryptedData: exports.base64String,
+    keyDerivation: exports.keyDerivationParams,
+    metadata: ts_json_base_1.Converters.jsonValue
+}, { optionalFields: ['keyDerivation', 'metadata'] });
+/**
+ * Creates a converter for {@link CryptoUtils.IEncryptedFile | encrypted files} with optional typed metadata.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param metadataConverter - Optional converter for validating metadata field
+ * @returns A converter that validates and converts encrypted file structures
+ * @public
+ */
+function createEncryptedFileConverter(metadataConverter) {
+    return ts_utils_1.Converters.generic((from) => {
+        // First validate base structure
+        const baseResult = baseEncryptedFileConverter.convert(from);
+        if (baseResult.isFailure()) {
+            return (0, ts_utils_1.fail)(baseResult.message);
+        }
+        const base = baseResult.value;
+        // Validate metadata with specific converter if provided and metadata exists
+        if (metadataConverter !== undefined && base.metadata !== undefined) {
+            const metaResult = metadataConverter.convert(base.metadata);
+            if (metaResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Invalid metadata: ${metaResult.message}`);
+            }
+            return (0, ts_utils_1.succeed)(Object.assign(Object.assign({}, base), { metadata: metaResult.value }));
+        }
+        // Return as-is (metadata is either undefined or untyped JsonValue)
+        return (0, ts_utils_1.succeed)(base);
+    });
+}
+/**
+ * Default converter for encrypted files without typed metadata.
+ * @public
+ */
+exports.encryptedFile = createEncryptedFileConverter();
+//# sourceMappingURL=converters.js.map

package/lib/packlets/crypto-utils/directEncryptionProvider.d.ts

@@ -0,0 +1,69 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+import { ICryptoProvider, IEncryptedFile, IEncryptionProvider } from './model';
+/**
+ * Parameters for creating a {@link DirectEncryptionProvider}.
+ * @public
+ */
+export interface IDirectEncryptionProviderParams {
+    /**
+     * The crypto provider to use for encryption operations.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * The encryption key (32 bytes for AES-256).
+     */
+    readonly key: Uint8Array;
+    /**
+     * Optional bound secret name.
+     * When set, `encryptByName` will fail if called with a different name.
+     * When unset, any secret name is accepted.
+     */
+    readonly boundSecretName?: string;
+}
+/**
+ * An {@link IEncryptionProvider} that uses a pre-supplied key and crypto provider.
+ *
+ * This is useful when you have the raw encryption key from an external source
+ * (e.g. a `SecretProvider` callback, password derivation, or a one-shot
+ * operation) and don't want to open a full KeyStore.
+ *
+ * Optionally bound to a specific secret name for safety: if a `boundSecretName`
+ * is provided, calls to `encryptByName` with a different name will fail.
+ *
+ * @example
+ * ```typescript
+ * const provider = DirectEncryptionProvider.create({
+ *   cryptoProvider: nodeCryptoProvider,
+ *   key: myKey,
+ *   boundSecretName: 'my-collection'
+ * }).orThrow();
+ *
+ * const encrypted = await provider.encryptByName('my-collection', jsonContent);
+ * ```
+ *
+ * @public
+ */
+export declare class DirectEncryptionProvider implements IEncryptionProvider {
+    private readonly _cryptoProvider;
+    private readonly _key;
+    private readonly _boundSecretName;
+    private constructor();
+    /**
+     * Creates a new DirectEncryptionProvider.
+     * @param params - Provider configuration
+     * @returns Success with provider, or Failure if parameters are invalid
+     * @public
+     */
+    static create(params: IDirectEncryptionProviderParams): Result<DirectEncryptionProvider>;
+    /**
+     * The secret name this provider is bound to, if any.
+     * @public
+     */
+    get boundSecretName(): string | undefined;
+    /**
+     * {@inheritDoc IEncryptionProvider.encryptByName}
+     */
+    encryptByName<TMetadata = JsonValue>(secretName: string, content: JsonValue, metadata?: TMetadata): Promise<Result<IEncryptedFile<TMetadata>>>;
+}
+//# sourceMappingURL=directEncryptionProvider.d.ts.map

package/lib/packlets/crypto-utils/directEncryptionProvider.js

@@ -0,0 +1,90 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectEncryptionProvider = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const encryptedFile_1 = require("./encryptedFile");
+/**
+ * An {@link IEncryptionProvider} that uses a pre-supplied key and crypto provider.
+ *
+ * This is useful when you have the raw encryption key from an external source
+ * (e.g. a `SecretProvider` callback, password derivation, or a one-shot
+ * operation) and don't want to open a full KeyStore.
+ *
+ * Optionally bound to a specific secret name for safety: if a `boundSecretName`
+ * is provided, calls to `encryptByName` with a different name will fail.
+ *
+ * @example
+ * ```typescript
+ * const provider = DirectEncryptionProvider.create({
+ *   cryptoProvider: nodeCryptoProvider,
+ *   key: myKey,
+ *   boundSecretName: 'my-collection'
+ * }).orThrow();
+ *
+ * const encrypted = await provider.encryptByName('my-collection', jsonContent);
+ * ```
+ *
+ * @public
+ */
+class DirectEncryptionProvider {
+    constructor(params) {
+        this._cryptoProvider = params.cryptoProvider;
+        this._key = params.key;
+        this._boundSecretName = params.boundSecretName;
+    }
+    /**
+     * Creates a new DirectEncryptionProvider.
+     * @param params - Provider configuration
+     * @returns Success with provider, or Failure if parameters are invalid
+     * @public
+     */
+    static create(params) {
+        if (params.key.length === 0) {
+            return (0, ts_utils_1.fail)('Encryption key cannot be empty');
+        }
+        return (0, ts_utils_1.succeed)(new DirectEncryptionProvider(params));
+    }
+    /**
+     * The secret name this provider is bound to, if any.
+     * @public
+     */
+    get boundSecretName() {
+        return this._boundSecretName;
+    }
+    /**
+     * {@inheritDoc IEncryptionProvider.encryptByName}
+     */
+    async encryptByName(secretName, content, metadata) {
+        if (this._boundSecretName !== undefined && secretName !== this._boundSecretName) {
+            return (0, ts_utils_1.fail)(`Secret name mismatch: requested '${secretName}' but provider is bound to '${this._boundSecretName}'`);
+        }
+        return (0, encryptedFile_1.createEncryptedFile)({
+            content,
+            secretName,
+            key: this._key,
+            cryptoProvider: this._cryptoProvider,
+            metadata
+        });
+    }
+}
+exports.DirectEncryptionProvider = DirectEncryptionProvider;
+//# sourceMappingURL=directEncryptionProvider.js.map

package/lib/packlets/crypto-utils/encryptedFile.d.ts

@@ -0,0 +1,88 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Converter, Result } from '@fgv/ts-utils';
+import { ICryptoProvider, IEncryptedFile, IKeyDerivationParams } from './model';
+/**
+ * Encodes a `Uint8Array` to a base64 string.
+ * @param bytes - Bytes to encode
+ * @returns Base64 string
+ * @public
+ */
+export declare function toBase64(bytes: Uint8Array): string;
+/**
+ * Decodes a base64 string to a `Uint8Array`.
+ * @param base64 - Base64 string to decode
+ * @returns Decoded bytes
+ * @public
+ */
+export declare function fromBase64(base64: string): Uint8Array;
+/**
+ * Parameters for creating an {@link CryptoUtils.IEncryptedFile | encrypted file}.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @public
+ */
+export interface ICreateEncryptedFileParams<TMetadata = JsonValue> {
+    /**
+     * The JSON content to encrypt.
+     */
+    readonly content: JsonValue;
+    /**
+     * Name of the secret used for encryption.
+     */
+    readonly secretName: string;
+    /**
+     * The encryption key (32 bytes for AES-256).
+     */
+    readonly key: Uint8Array;
+    /**
+     * {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for encryption.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Optional metadata to include unencrypted.
+     */
+    readonly metadata?: TMetadata;
+    /**
+     * Optional converter to validate metadata before including.
+     * If provided, metadata will be validated before encryption.
+     */
+    readonly metadataConverter?: Converter<TMetadata>;
+    /**
+     * Optional {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+     * If provided, stores the salt and iterations used to derive the key from a password.
+     * This allows decryption using only a password (the salt/iterations are read from the file).
+     */
+    readonly keyDerivation?: IKeyDerivationParams;
+}
+/**
+ * Creates an {@link CryptoUtils.IEncryptedFile | encrypted file} from JSON content.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param params - Encryption parameters
+ * @returns `Success` with encrypted file structure, or `Failure` with an error.
+ * @public
+ */
+export declare function createEncryptedFile<TMetadata = JsonValue>(params: ICreateEncryptedFileParams<TMetadata>): Promise<Result<IEncryptedFile<TMetadata>>>;
+/**
+ * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @param file - The encrypted file structure
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @returns `Success` with decrypted content, or `Failure` with an error.
+ * @public
+ */
+export declare function decryptFile<TPayload extends JsonValue = JsonValue>(file: IEncryptedFile<unknown>, key: Uint8Array, cryptoProvider: ICryptoProvider, payloadConverter?: Converter<TPayload>): Promise<Result<TPayload>>;
+/**
+ * Attempts to parse and decrypt a JSON object as an {@link CryptoUtils.IEncryptedFile | encrypted file}.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param json - JSON object that may be an encrypted file
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @param metadataConverter - Optional converter to validate metadata before decryption
+ * @returns `Success` with decrypted content, or `Failure` with an error (including if not encrypted)
+ * @public
+ */
+export declare function tryDecryptFile<TPayload extends JsonValue = JsonValue, TMetadata = JsonValue>(json: JsonValue, key: Uint8Array, cryptoProvider: ICryptoProvider, payloadConverter?: Converter<TPayload>, metadataConverter?: Converter<TMetadata>): Promise<Result<TPayload>>;
+//# sourceMappingURL=encryptedFile.d.ts.map

package/lib/packlets/crypto-utils/encryptedFile.js

@@ -0,0 +1,201 @@
+"use strict";
+// Copyright (c) 2024 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBase64 = toBase64;
+exports.fromBase64 = fromBase64;
+exports.createEncryptedFile = createEncryptedFile;
+exports.decryptFile = decryptFile;
+exports.tryDecryptFile = tryDecryptFile;
+const ts_utils_1 = require("@fgv/ts-utils");
+const Constants = __importStar(require("./constants"));
+const converters_1 = require("./converters");
+const model_1 = require("./model");
+// ============================================================================
+// Base64 Utilities
+// ============================================================================
+/**
+ * Encodes a `Uint8Array` to a base64 string.
+ * @param bytes - Bytes to encode
+ * @returns Base64 string
+ * @public
+ */
+/* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+function toBase64(bytes) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    // Browser fallback
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/* c8 ignore stop */
+/**
+ * Decodes a base64 string to a `Uint8Array`.
+ * @param base64 - Base64 string to decode
+ * @returns Decoded bytes
+ * @public
+ */
+/* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+function fromBase64(base64) {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // Browser fallback
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// ============================================================================
+// Encryption Functions
+// ============================================================================
+/**
+ * Creates an {@link CryptoUtils.IEncryptedFile | encrypted file} from JSON content.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param params - Encryption parameters
+ * @returns `Success` with encrypted file structure, or `Failure` with an error.
+ * @public
+ */
+async function createEncryptedFile(params) {
+    const { content, secretName, key, metadata, metadataConverter, keyDerivation, cryptoProvider } = params;
+    // Validate metadata if converter provided
+    /* c8 ignore next 6 - metadata validation path exercised via higher-level tests */
+    if (metadata !== undefined && metadataConverter !== undefined) {
+        const metadataResult = metadataConverter.convert(metadata);
+        if (metadataResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid metadata: ${metadataResult.message}`);
+        }
+    }
+    // Serialize content to JSON string
+    const jsonResult = (0, ts_utils_1.captureResult)(() => JSON.stringify(content));
+    if (jsonResult.isFailure()) {
+        return (0, ts_utils_1.fail)(`Failed to serialize content: ${jsonResult.message}`);
+    }
+    // Encrypt the JSON string
+    const encryptResult = await cryptoProvider.encrypt(jsonResult.value, key);
+    if (encryptResult.isFailure()) {
+        return (0, ts_utils_1.fail)(`Encryption failed: ${encryptResult.message}`);
+    }
+    const { iv, authTag, encryptedData } = encryptResult.value;
+    // Build the encrypted file structure
+    const encryptedFile = Object.assign(Object.assign({ format: Constants.ENCRYPTED_FILE_FORMAT, secretName, algorithm: Constants.DEFAULT_ALGORITHM, iv: toBase64(iv), authTag: toBase64(authTag), encryptedData: toBase64(encryptedData) }, (metadata !== undefined ? { metadata } : {})), (keyDerivation !== undefined ? { keyDerivation } : {}));
+    return (0, ts_utils_1.succeed)(encryptedFile);
+}
+// ============================================================================
+// Decryption Functions
+// ============================================================================
+/**
+ * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @param file - The encrypted file structure
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @returns `Success` with decrypted content, or `Failure` with an error.
+ * @public
+ */
+async function decryptFile(file, key, cryptoProvider, payloadConverter) {
+    // Decode base64 values
+    const iv = fromBase64(file.iv);
+    const authTag = fromBase64(file.authTag);
+    const encryptedData = fromBase64(file.encryptedData);
+    // Decrypt
+    const decryptResult = await cryptoProvider.decrypt(encryptedData, key, iv, authTag);
+    if (decryptResult.isFailure()) {
+        return (0, ts_utils_1.fail)(decryptResult.message);
+    }
+    // Parse JSON
+    const parseResult = (0, ts_utils_1.captureResult)(() => JSON.parse(decryptResult.value)).withErrorFormat((e) => `Failed to parse decrypted content as JSON: ${e}`);
+    /* c8 ignore next 3 - JSON parse failure only occurs with corrupted encrypted data */
+    if (parseResult.isFailure()) {
+        return parseResult;
+    }
+    // Validate with converter if provided
+    /* c8 ignore next 3 - payload converter path exercised via higher-level tests */
+    if (payloadConverter !== undefined) {
+        return payloadConverter.convert(parseResult.value);
+    }
+    return parseResult;
+}
+/**
+ * Attempts to parse and decrypt a JSON object as an {@link CryptoUtils.IEncryptedFile | encrypted file}.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param json - JSON object that may be an encrypted file
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @param metadataConverter - Optional converter to validate metadata before decryption
+ * @returns `Success` with decrypted content, or `Failure` with an error (including if not encrypted)
+ * @public
+ */
+async function tryDecryptFile(json, key, cryptoProvider, payloadConverter, metadataConverter) {
+    // Check if it's an encrypted file
+    if (!(0, model_1.isEncryptedFile)(json)) {
+        return (0, ts_utils_1.fail)('Not an encrypted file');
+    }
+    // Validate and convert to typed encrypted file
+    const fileConverter = (0, converters_1.createEncryptedFileConverter)(metadataConverter);
+    const fileResult = fileConverter.convert(json);
+    if (fileResult.isFailure()) {
+        return (0, ts_utils_1.fail)(`Invalid encrypted file format: ${fileResult.message}`);
+    }
+    return decryptFile(fileResult.value, key, cryptoProvider, payloadConverter);
+}
+//# sourceMappingURL=encryptedFile.js.map

package/lib/packlets/crypto-utils/index.browser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Crypto utilities for encrypted file handling and key management (browser version).
+ * Note: For browser crypto provider, use \@fgv/ts-web-extras.
+ * @packageDocumentation
+ */
+export * from './model';
+export { AES_256_KEY_SIZE, DEFAULT_ALGORITHM, ENCRYPTED_FILE_FORMAT, GCM_AUTH_TAG_SIZE, GCM_IV_SIZE } from './constants';
+import * as KeyStore from './keystore';
+export { KeyStore };
+import * as Converters from './converters';
+export { Converters };
+export { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';
+export { createEncryptedFile, decryptFile, fromBase64, ICreateEncryptedFileParams, toBase64, tryDecryptFile } from './encryptedFile';
+//# sourceMappingURL=index.browser.d.ts.map