@fgv/ts-extras 5.1.0-12 → 5.1.0-15

package/dist/packlets/crypto-utils/keystore/keyStore.js

@@ -146,7 +146,6 @@ export class KeyStore {
      * @public
      */
     async unlock(password) {
-        var _a;
         if (this._isNew) {
             return fail('Cannot unlock a new key store - use initialize() instead');
         }
@@ -170,57 +169,37 @@ export class KeyStore {
         if (keyResult.isFailure()) {
             return fail(`Key derivation failed: ${keyResult.message}`);
         }
-        // Decrypt the vault
-        const ivResult = this._cryptoProvider.fromBase64(this._keystoreFile.iv);
-        const authTagResult = this._cryptoProvider.fromBase64(this._keystoreFile.authTag);
-        const encryptedDataResult = this._cryptoProvider.fromBase64(this._keystoreFile.encryptedData);
-        /* c8 ignore next 9 - base64 decode errors tested but coverage intermittently missed */
-        if (ivResult.isFailure()) {
-            return fail(`Invalid IV in key store file: ${ivResult.message}`);
-        }
-        if (authTagResult.isFailure()) {
-            return fail(`Invalid auth tag in key store file: ${authTagResult.message}`);
-        }
-        if (encryptedDataResult.isFailure()) {
-            return fail(`Invalid encrypted data in key store file: ${encryptedDataResult.message}`);
-        }
-        const decryptResult = await this._cryptoProvider.decrypt(encryptedDataResult.value, keyResult.value, ivResult.value, authTagResult.value);
-        if (decryptResult.isFailure()) {
-            return fail('Incorrect password or corrupted key store');
+        return this._decryptVault(keyResult.value);
+    }
+    /**
+     * Unlocks an existing key store with a pre-derived key, bypassing
+     * PBKDF2 key derivation. Use this when the derived key has been
+     * stored externally (e.g., in another key store) and the original
+     * password is no longer available.
+     *
+     * The supplied key must have been derived from the correct password
+     * using the key store file's own PBKDF2 parameters (salt and
+     * iteration count).
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with this instance when unlocked, Failure if key is incorrect
+     * @public
+     */
+    async unlockWithKey(derivedKey) {
+        if (this._isNew) {
+            return fail('Cannot unlock a new key store - use initialize() instead');
         }
-        // Parse the vault contents
-        const parseResult = captureResult(() => JSON.parse(decryptResult.value));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (parseResult.isFailure()) {
-            return fail(`Failed to parse vault contents: ${parseResult.message}`);
+        if (this._state === 'unlocked') {
+            return fail('Key store is already unlocked');
         }
-        const vaultResult = keystoreVaultContents.convert(parseResult.value);
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (vaultResult.isFailure()) {
-            return fail(`Invalid vault format: ${vaultResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${derivedKey.length}`);
         }
-        // Load secrets into memory
-        this._salt = salt;
-        this._secrets = new Map();
-        for (const [name, jsonEntry] of Object.entries(vaultResult.value.secrets)) {
-            const keyBytesResult = this._cryptoProvider.fromBase64(jsonEntry.key);
-            /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-            if (keyBytesResult.isFailure()) {
-                return fail(`Invalid key for secret '${name}': ${keyBytesResult.message}`);
-            }
-            const entry = {
-                name,
-                /* c8 ignore next 1 - backwards compatibility: old vaults may lack type field */
-                type: (_a = jsonEntry.type) !== null && _a !== void 0 ? _a : 'encryption-key',
-                key: keyBytesResult.value,
-                description: jsonEntry.description,
-                createdAt: jsonEntry.createdAt
-            };
-            this._secrets.set(name, entry);
+        /* c8 ignore next 3 - defensive coding: unreachable via public API (open sets file, create sets isNew) */
+        if (!this._keystoreFile) {
+            return fail('No key store file to unlock');
         }
-        this._state = 'unlocked';
-        this._dirty = false;
-        return succeed(this);
+        return this._decryptVault(derivedKey);
     }
     /**
      * Locks the key store, clearing all secrets from memory.
@@ -761,5 +740,75 @@ export class KeyStore {
             cryptoProvider: this._cryptoProvider
         });
     }
+    // ============================================================================
+    // Private: Vault Decryption
+    // ============================================================================
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    async _decryptVault(derivedKey) {
+        var _a;
+        const keystoreFile = this._keystoreFile;
+        if (keystoreFile === undefined) {
+            return fail('No key store file loaded');
+        }
+        const ivResult = this._cryptoProvider.fromBase64(keystoreFile.iv);
+        const authTagResult = this._cryptoProvider.fromBase64(keystoreFile.authTag);
+        const encryptedDataResult = this._cryptoProvider.fromBase64(keystoreFile.encryptedData);
+        /* c8 ignore next 9 - base64 decode errors tested but coverage intermittently missed */
+        if (ivResult.isFailure()) {
+            return fail(`Invalid IV in key store file: ${ivResult.message}`);
+        }
+        if (authTagResult.isFailure()) {
+            return fail(`Invalid auth tag in key store file: ${authTagResult.message}`);
+        }
+        if (encryptedDataResult.isFailure()) {
+            return fail(`Invalid encrypted data in key store file: ${encryptedDataResult.message}`);
+        }
+        const decryptResult = await this._cryptoProvider.decrypt(encryptedDataResult.value, derivedKey, ivResult.value, authTagResult.value);
+        if (decryptResult.isFailure()) {
+            return fail('Incorrect password or corrupted key store');
+        }
+        // Parse the vault contents
+        const parseResult = captureResult(() => JSON.parse(decryptResult.value));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (parseResult.isFailure()) {
+            return fail(`Failed to parse vault contents: ${parseResult.message}`);
+        }
+        const vaultResult = keystoreVaultContents.convert(parseResult.value);
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (vaultResult.isFailure()) {
+            return fail(`Invalid vault format: ${vaultResult.message}`);
+        }
+        // Build secrets into local variables to avoid partial state on failure
+        const saltResult = this._cryptoProvider.fromBase64(keystoreFile.keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return fail(`Invalid salt in key store file: ${saltResult.message}`);
+        }
+        const secrets = new Map();
+        for (const [name, jsonEntry] of Object.entries(vaultResult.value.secrets)) {
+            const keyBytesResult = this._cryptoProvider.fromBase64(jsonEntry.key);
+            /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+            if (keyBytesResult.isFailure()) {
+                return fail(`Invalid key for secret '${name}': ${keyBytesResult.message}`);
+            }
+            const entry = {
+                name,
+                /* c8 ignore next 1 - backwards compatibility: old vaults may lack type field */
+                type: (_a = jsonEntry.type) !== null && _a !== void 0 ? _a : 'encryption-key',
+                key: keyBytesResult.value,
+                description: jsonEntry.description,
+                createdAt: jsonEntry.createdAt
+            };
+            secrets.set(name, entry);
+        }
+        // All validation passed — commit state atomically
+        this._salt = saltResult.value;
+        this._secrets = secrets;
+        this._state = 'unlocked';
+        this._dirty = false;
+        return succeed(this);
+    }
 }
 //# sourceMappingURL=keyStore.js.map

package/dist/packlets/crypto-utils/nodeCryptoProvider.js

@@ -116,6 +116,18 @@ export class NodeCryptoProvider {
             });
         });
     }
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    async sha256(data) {
+        return captureResult(() => {
+            const hash = crypto.createHash('sha256');
+            hash.update(data, 'utf8');
+            return hash.digest('hex');
+        });
+    }
     // ============================================================================
     // Platform Utility Methods
     // ============================================================================

package/dist/packlets/yaml/index.js

@@ -20,4 +20,5 @@
  * SOFTWARE.
  */
 export * from './converters';
+export * from './serializers';
 //# sourceMappingURL=index.js.map

package/dist/packlets/yaml/serializers.js

@@ -0,0 +1,48 @@
+/*
+ * 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.
+ */
+import { captureResult, fail } from '@fgv/ts-utils';
+import * as yaml from 'js-yaml';
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+export function yamlStringify(value, options) {
+    if (value === null || value === undefined) {
+        return fail('Cannot serialize null or undefined to YAML');
+    }
+    if (typeof value !== 'object') {
+        return fail('YAML serialization requires an object or array');
+    }
+    return captureResult(() => yaml.dump(value, {
+        indent: options === null || options === void 0 ? void 0 : options.indent,
+        flowLevel: options === null || options === void 0 ? void 0 : options.flowLevel,
+        sortKeys: options === null || options === void 0 ? void 0 : options.sortKeys,
+        lineWidth: options === null || options === void 0 ? void 0 : options.lineWidth,
+        noRefs: options === null || options === void 0 ? void 0 : options.noRefs,
+        noArrayIndent: options === null || options === void 0 ? void 0 : options.noArrayIndent,
+        forceQuotes: options === null || options === void 0 ? void 0 : options.forceQuotes
+    }));
+}
+//# sourceMappingURL=serializers.js.map

package/dist/ts-extras.d.ts

@@ -939,6 +939,12 @@ declare interface ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns Success with hex-encoded hash string, or Failure with error
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
@@ -1445,6 +1451,42 @@ declare interface IVariableRef {
     readonly isSection: boolean;
 }
 
+/**
+ * Options for YAML serialization, mirroring commonly-used `js-yaml` `DumpOptions`.
+ * @public
+ */
+declare interface IYamlSerializeOptions {
+    /**
+     * Indentation width in spaces (default: 2).
+     */
+    readonly indent?: number;
+    /**
+     * Nesting level at which to switch from block to flow style.
+     * -1 means block style everywhere (default: -1).
+     */
+    readonly flowLevel?: number;
+    /**
+     * If true, sort keys when dumping (default: false).
+     */
+    readonly sortKeys?: boolean;
+    /**
+     * Maximum line width (default: 80).
+     */
+    readonly lineWidth?: number;
+    /**
+     * If true, don't convert duplicate objects into references (default: false).
+     */
+    readonly noRefs?: boolean;
+    /**
+     * If true, don't add an indentation level to array elements (default: false).
+     */
+    readonly noArrayIndent?: boolean;
+    /**
+     * If true, all non-key strings will be quoted (default: false).
+     */
+    readonly forceQuotes?: boolean;
+}
+
 /**
  * Simple interface for a file to be added to a zip file.
  * @public
@@ -1594,6 +1636,21 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     unlock(password: string): Promise<Result<KeyStore_2>>;
+    /**
+     * Unlocks an existing key store with a pre-derived key, bypassing
+     * PBKDF2 key derivation. Use this when the derived key has been
+     * stored externally (e.g., in another key store) and the original
+     * password is no longer available.
+     *
+     * The supplied key must have been derived from the correct password
+     * using the key store file's own PBKDF2 parameters (salt and
+     * iteration count).
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with this instance when unlocked, Failure if key is incorrect
+     * @public
+     */
+    unlockWithKey(derivedKey: Uint8Array): Promise<Result<KeyStore_2>>;
     /**
      * Locks the key store, clearing all secrets from memory.
      * @param force - If true, discards unsaved changes
@@ -1759,6 +1816,11 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    private _decryptVault;
 }
 
 /**
@@ -2000,6 +2062,12 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with derived 32-byte key, or `Failure` with an error.
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
@@ -2312,7 +2380,9 @@ declare const uint8ArrayFromBase64: Converter<Uint8Array>;
 
 declare namespace Yaml {
     export {
-        yamlConverter
+        yamlConverter,
+        yamlStringify,
+        IYamlSerializeOptions
     }
 }
 export { Yaml }
@@ -2325,6 +2395,15 @@ export { Yaml }
  */
 declare function yamlConverter<T>(converter: Converter<T>): Converter<T>;
 
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+declare function yamlStringify(value: unknown, options?: IYamlSerializeOptions): Result<string>;
+
 /**
  * Supported compression levels for zip files.
  * @public

package/lib/packlets/crypto-utils/keystore/keyStore.d.ts

@@ -76,6 +76,21 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     unlock(password: string): Promise<Result<KeyStore>>;
+    /**
+     * Unlocks an existing key store with a pre-derived key, bypassing
+     * PBKDF2 key derivation. Use this when the derived key has been
+     * stored externally (e.g., in another key store) and the original
+     * password is no longer available.
+     *
+     * The supplied key must have been derived from the correct password
+     * using the key store file's own PBKDF2 parameters (salt and
+     * iteration count).
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with this instance when unlocked, Failure if key is incorrect
+     * @public
+     */
+    unlockWithKey(derivedKey: Uint8Array): Promise<Result<KeyStore>>;
     /**
      * Locks the key store, clearing all secrets from memory.
      * @param force - If true, discards unsaved changes
@@ -241,5 +256,10 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    private _decryptVault;
 }
 //# sourceMappingURL=keyStore.d.ts.map

package/lib/packlets/crypto-utils/keystore/keyStore.js

@@ -182,7 +182,6 @@ class KeyStore {
      * @public
      */
     async unlock(password) {
-        var _a;
         if (this._isNew) {
             return (0, ts_utils_1.fail)('Cannot unlock a new key store - use initialize() instead');
         }
@@ -206,57 +205,37 @@ class KeyStore {
         if (keyResult.isFailure()) {
             return (0, ts_utils_1.fail)(`Key derivation failed: ${keyResult.message}`);
         }
-        // Decrypt the vault
-        const ivResult = this._cryptoProvider.fromBase64(this._keystoreFile.iv);
-        const authTagResult = this._cryptoProvider.fromBase64(this._keystoreFile.authTag);
-        const encryptedDataResult = this._cryptoProvider.fromBase64(this._keystoreFile.encryptedData);
-        /* c8 ignore next 9 - base64 decode errors tested but coverage intermittently missed */
-        if (ivResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid IV in key store file: ${ivResult.message}`);
-        }
-        if (authTagResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid auth tag in key store file: ${authTagResult.message}`);
-        }
-        if (encryptedDataResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid encrypted data in key store file: ${encryptedDataResult.message}`);
-        }
-        const decryptResult = await this._cryptoProvider.decrypt(encryptedDataResult.value, keyResult.value, ivResult.value, authTagResult.value);
-        if (decryptResult.isFailure()) {
-            return (0, ts_utils_1.fail)('Incorrect password or corrupted key store');
+        return this._decryptVault(keyResult.value);
+    }
+    /**
+     * Unlocks an existing key store with a pre-derived key, bypassing
+     * PBKDF2 key derivation. Use this when the derived key has been
+     * stored externally (e.g., in another key store) and the original
+     * password is no longer available.
+     *
+     * The supplied key must have been derived from the correct password
+     * using the key store file's own PBKDF2 parameters (salt and
+     * iteration count).
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with this instance when unlocked, Failure if key is incorrect
+     * @public
+     */
+    async unlockWithKey(derivedKey) {
+        if (this._isNew) {
+            return (0, ts_utils_1.fail)('Cannot unlock a new key store - use initialize() instead');
         }
-        // Parse the vault contents
-        const parseResult = (0, ts_utils_1.captureResult)(() => JSON.parse(decryptResult.value));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (parseResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Failed to parse vault contents: ${parseResult.message}`);
+        if (this._state === 'unlocked') {
+            return (0, ts_utils_1.fail)('Key store is already unlocked');
         }
-        const vaultResult = converters_1.keystoreVaultContents.convert(parseResult.value);
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (vaultResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid vault format: ${vaultResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return (0, ts_utils_1.fail)(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${derivedKey.length}`);
         }
-        // Load secrets into memory
-        this._salt = salt;
-        this._secrets = new Map();
-        for (const [name, jsonEntry] of Object.entries(vaultResult.value.secrets)) {
-            const keyBytesResult = this._cryptoProvider.fromBase64(jsonEntry.key);
-            /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-            if (keyBytesResult.isFailure()) {
-                return (0, ts_utils_1.fail)(`Invalid key for secret '${name}': ${keyBytesResult.message}`);
-            }
-            const entry = {
-                name,
-                /* c8 ignore next 1 - backwards compatibility: old vaults may lack type field */
-                type: (_a = jsonEntry.type) !== null && _a !== void 0 ? _a : 'encryption-key',
-                key: keyBytesResult.value,
-                description: jsonEntry.description,
-                createdAt: jsonEntry.createdAt
-            };
-            this._secrets.set(name, entry);
+        /* c8 ignore next 3 - defensive coding: unreachable via public API (open sets file, create sets isNew) */
+        if (!this._keystoreFile) {
+            return (0, ts_utils_1.fail)('No key store file to unlock');
         }
-        this._state = 'unlocked';
-        this._dirty = false;
-        return (0, ts_utils_1.succeed)(this);
+        return this._decryptVault(derivedKey);
     }
     /**
      * Locks the key store, clearing all secrets from memory.
@@ -797,6 +776,76 @@ class KeyStore {
             cryptoProvider: this._cryptoProvider
         });
     }
+    // ============================================================================
+    // Private: Vault Decryption
+    // ============================================================================
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    async _decryptVault(derivedKey) {
+        var _a;
+        const keystoreFile = this._keystoreFile;
+        if (keystoreFile === undefined) {
+            return (0, ts_utils_1.fail)('No key store file loaded');
+        }
+        const ivResult = this._cryptoProvider.fromBase64(keystoreFile.iv);
+        const authTagResult = this._cryptoProvider.fromBase64(keystoreFile.authTag);
+        const encryptedDataResult = this._cryptoProvider.fromBase64(keystoreFile.encryptedData);
+        /* c8 ignore next 9 - base64 decode errors tested but coverage intermittently missed */
+        if (ivResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid IV in key store file: ${ivResult.message}`);
+        }
+        if (authTagResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid auth tag in key store file: ${authTagResult.message}`);
+        }
+        if (encryptedDataResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid encrypted data in key store file: ${encryptedDataResult.message}`);
+        }
+        const decryptResult = await this._cryptoProvider.decrypt(encryptedDataResult.value, derivedKey, ivResult.value, authTagResult.value);
+        if (decryptResult.isFailure()) {
+            return (0, ts_utils_1.fail)('Incorrect password or corrupted key store');
+        }
+        // Parse the vault contents
+        const parseResult = (0, ts_utils_1.captureResult)(() => JSON.parse(decryptResult.value));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (parseResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse vault contents: ${parseResult.message}`);
+        }
+        const vaultResult = converters_1.keystoreVaultContents.convert(parseResult.value);
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (vaultResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid vault format: ${vaultResult.message}`);
+        }
+        // Build secrets into local variables to avoid partial state on failure
+        const saltResult = this._cryptoProvider.fromBase64(keystoreFile.keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid salt in key store file: ${saltResult.message}`);
+        }
+        const secrets = new Map();
+        for (const [name, jsonEntry] of Object.entries(vaultResult.value.secrets)) {
+            const keyBytesResult = this._cryptoProvider.fromBase64(jsonEntry.key);
+            /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+            if (keyBytesResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Invalid key for secret '${name}': ${keyBytesResult.message}`);
+            }
+            const entry = {
+                name,
+                /* c8 ignore next 1 - backwards compatibility: old vaults may lack type field */
+                type: (_a = jsonEntry.type) !== null && _a !== void 0 ? _a : 'encryption-key',
+                key: keyBytesResult.value,
+                description: jsonEntry.description,
+                createdAt: jsonEntry.createdAt
+            };
+            secrets.set(name, entry);
+        }
+        // All validation passed — commit state atomically
+        this._salt = saltResult.value;
+        this._secrets = secrets;
+        this._state = 'unlocked';
+        this._dirty = false;
+        return (0, ts_utils_1.succeed)(this);
+    }
 }
 exports.KeyStore = KeyStore;
 //# sourceMappingURL=keyStore.js.map

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

@@ -145,6 +145,12 @@ export interface ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns Success with hex-encoded hash string, or Failure with error
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate

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

@@ -35,6 +35,12 @@ export declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with derived 32-byte key, or `Failure` with an error.
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate

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

@@ -152,6 +152,18 @@ class NodeCryptoProvider {
             });
         });
     }
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    async sha256(data) {
+        return (0, ts_utils_1.captureResult)(() => {
+            const hash = crypto.createHash('sha256');
+            hash.update(data, 'utf8');
+            return hash.digest('hex');
+        });
+    }
     // ============================================================================
     // Platform Utility Methods
     // ============================================================================

package/lib/packlets/yaml/index.d.ts

@@ -1,2 +1,3 @@
 export * from './converters';
+export * from './serializers';
 //# sourceMappingURL=index.d.ts.map

package/lib/packlets/yaml/index.js

@@ -36,4 +36,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./converters"), exports);
+__exportStar(require("./serializers"), exports);
 //# sourceMappingURL=index.js.map

package/lib/packlets/yaml/serializers.d.ts

@@ -0,0 +1,45 @@
+import { Result } from '@fgv/ts-utils';
+/**
+ * Options for YAML serialization, mirroring commonly-used `js-yaml` `DumpOptions`.
+ * @public
+ */
+export interface IYamlSerializeOptions {
+    /**
+     * Indentation width in spaces (default: 2).
+     */
+    readonly indent?: number;
+    /**
+     * Nesting level at which to switch from block to flow style.
+     * -1 means block style everywhere (default: -1).
+     */
+    readonly flowLevel?: number;
+    /**
+     * If true, sort keys when dumping (default: false).
+     */
+    readonly sortKeys?: boolean;
+    /**
+     * Maximum line width (default: 80).
+     */
+    readonly lineWidth?: number;
+    /**
+     * If true, don't convert duplicate objects into references (default: false).
+     */
+    readonly noRefs?: boolean;
+    /**
+     * If true, don't add an indentation level to array elements (default: false).
+     */
+    readonly noArrayIndent?: boolean;
+    /**
+     * If true, all non-key strings will be quoted (default: false).
+     */
+    readonly forceQuotes?: boolean;
+}
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+export declare function yamlStringify(value: unknown, options?: IYamlSerializeOptions): Result<string>;
+//# sourceMappingURL=serializers.d.ts.map

package/lib/packlets/yaml/serializers.js

@@ -0,0 +1,84 @@
+"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.yamlStringify = yamlStringify;
+const ts_utils_1 = require("@fgv/ts-utils");
+const yaml = __importStar(require("js-yaml"));
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+function yamlStringify(value, options) {
+    if (value === null || value === undefined) {
+        return (0, ts_utils_1.fail)('Cannot serialize null or undefined to YAML');
+    }
+    if (typeof value !== 'object') {
+        return (0, ts_utils_1.fail)('YAML serialization requires an object or array');
+    }
+    return (0, ts_utils_1.captureResult)(() => yaml.dump(value, {
+        indent: options === null || options === void 0 ? void 0 : options.indent,
+        flowLevel: options === null || options === void 0 ? void 0 : options.flowLevel,
+        sortKeys: options === null || options === void 0 ? void 0 : options.sortKeys,
+        lineWidth: options === null || options === void 0 ? void 0 : options.lineWidth,
+        noRefs: options === null || options === void 0 ? void 0 : options.noRefs,
+        noArrayIndent: options === null || options === void 0 ? void 0 : options.noArrayIndent,
+        forceQuotes: options === null || options === void 0 ? void 0 : options.forceQuotes
+    }));
+}
+//# sourceMappingURL=serializers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-12",
+  "version": "5.1.0-15",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -86,10 +86,10 @@
     "@types/js-yaml": "~4.0.9",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/heft-dual-rig": "5.1.0-12",
-    "@fgv/ts-utils-jest": "5.1.0-12",
-    "@fgv/ts-utils": "5.1.0-12",
-    "@fgv/typedoc-compact-theme": "5.1.0-12"
+    "@fgv/heft-dual-rig": "5.1.0-15",
+    "@fgv/typedoc-compact-theme": "5.1.0-15",
+    "@fgv/ts-utils-jest": "5.1.0-15",
+    "@fgv/ts-utils": "5.1.0-15"
   },
   "dependencies": {
     "luxon": "^3.7.2",
@@ -97,10 +97,10 @@
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2",
     "js-yaml": "~4.1.1",
-    "@fgv/ts-json-base": "5.1.0-12"
+    "@fgv/ts-json-base": "5.1.0-15"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-12"
+    "@fgv/ts-utils": "5.1.0-15"
   },
   "repository": {
     "type": "git",