@fgv/ts-extras 5.1.0-27 → 5.1.0-29

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

@@ -1,7 +1,7 @@
 import { JsonValue } from '@fgv/ts-json-base';
 import { Result } from '@fgv/ts-utils';
-import { ICryptoProvider, IEncryptedFile, IEncryptionConfig, IEncryptionProvider, IKeyDerivationParams, SecretProvider } from '../model';
-import { IAddKeyPairOptions, IAddKeyPairResult, IAddSecretFromPasswordOptions, IAddSecretFromPasswordResult, IAddSecretOptions, IAddSecretResult, IImportKeyOptions, IImportSecretOptions, IKeyStoreCreateParams, IKeyStoreEntry, IKeyStoreFile, IKeyStoreOpenParams, IRemoveSecretResult, KeyStoreLockState, KeyStoreSecretType } from './model';
+import { ICryptoProvider, IEncryptedFile, IEncryptionConfig, IEncryptionProvider, IArgon2idKeyDerivationParams, IArgon2idProvider, IKeyDerivationParams, SecretProvider } from '../model';
+import { IAddKeyPairOptions, IAddKeyPairResult, IAddSecretFromPasswordArgon2idOptions, IAddSecretFromPasswordOptions, IAddSecretFromPasswordResult, IAddSecretOptions, IAddSecretResult, IImportKeyOptions, IImportSecretOptions, IKeyStoreCreateParams, IKeyStoreEntry, IKeyStoreFile, IKeyStoreOpenParams, IRemoveSecretResult, KeyStoreLockState, KeyStoreSecretType } from './model';
 /**
  * Password-protected key store for managing encryption secrets.
  *
@@ -231,6 +231,36 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     verifySecretFromPassword(name: string, password: string, keyDerivation: IKeyDerivationParams): Promise<Result<boolean>>;
+    /**
+     * Adds a secret derived from a password using Argon2id (RFC 9106).
+     *
+     * The Argon2id provider must be supplied explicitly; the KeyStore does not
+     * hold one by default (consumers opt in by depending on the argon2 package).
+     *
+     * Returns the key derivation parameters so callers can store them alongside
+     * encrypted artifacts, enabling future re-derivation and verification.
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password or passphrase
+     * @param argon2idProvider - Argon2id provider (Node or Browser implementation)
+     * @param options - Optional: Argon2id params (defaults to ARGON2ID_OWASP_MIN), description, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
+     */
+    addSecretFromPasswordArgon2id(name: string, password: string, argon2idProvider: IArgon2idProvider, options?: IAddSecretFromPasswordArgon2idOptions): Promise<Result<IAddSecretFromPasswordResult>>;
+    /**
+     * Verifies a candidate password against an Argon2id-derived entry using the
+     * supplied key derivation parameters. Constant-time comparison.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param argon2idProvider - Argon2id provider (must produce bit-identical output for identical inputs)
+     * @param keyDerivation - The Argon2id key derivation parameters returned by `addSecretFromPasswordArgon2id`
+     * @returns Success(true) if candidate matches stored key, Success(false) if not,
+     * Failure if locked, secret missing, wrong type, or derivation fails
+     * @public
+     */
+    verifySecretFromPasswordArgon2id(name: string, password: string, argon2idProvider: IArgon2idProvider, keyDerivation: IArgon2idKeyDerivationParams): Promise<Result<boolean>>;
     /**
      * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
      * before any storage cleanup runs. For asymmetric-keypair entries, best-effort

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

@@ -1 +1 @@
-{"version":3,"file":"keyStore.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/keyStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keyStore.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/keyStore.ts"],"names":[],"mappings":"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"}

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

@@ -56,7 +56,8 @@ exports.KeyStore = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const Constants = __importStar(require("../constants"));
 const encryptedFile_1 = require("../encryptedFile");
-const model_1 = require("./model");
+const model_1 = require("../model");
+const model_2 = require("./model");
 const converters_1 = require("./converters");
 /**
  * Gets the current ISO timestamp.
@@ -120,7 +121,7 @@ class KeyStore {
      */
     static create(params) {
         var _a;
-        const iterations = (_a = params.iterations) !== null && _a !== void 0 ? _a : model_1.DEFAULT_KEYSTORE_ITERATIONS;
+        const iterations = (_a = params.iterations) !== null && _a !== void 0 ? _a : model_2.DEFAULT_KEYSTORE_ITERATIONS;
         if (iterations < 1) {
             return (0, ts_utils_1.fail)('Iterations must be at least 1');
         }
@@ -164,7 +165,7 @@ class KeyStore {
             return (0, ts_utils_1.fail)('Password cannot be empty');
         }
         // Generate salt for this key store using crypto provider
-        const saltResult = this._cryptoProvider.generateRandomBytes(model_1.MIN_SALT_LENGTH);
+        const saltResult = this._cryptoProvider.generateRandomBytes(model_2.MIN_SALT_LENGTH);
         /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
         if (saltResult.isFailure()) {
             return (0, ts_utils_1.fail)(`Failed to generate salt: ${saltResult.message}`);
@@ -471,9 +472,9 @@ class KeyStore {
         if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
             return (0, ts_utils_1.fail)(`Secret '${name}' already exists - use replace=true to overwrite`);
         }
-        const iterations = (_a = options === null || options === void 0 ? void 0 : options.iterations) !== null && _a !== void 0 ? _a : model_1.DEFAULT_SECRET_ITERATIONS;
+        const iterations = (_a = options === null || options === void 0 ? void 0 : options.iterations) !== null && _a !== void 0 ? _a : model_2.DEFAULT_SECRET_ITERATIONS;
         // Generate a random salt for this secret's key derivation
-        const saltResult = this._cryptoProvider.generateRandomBytes(model_1.MIN_SALT_LENGTH);
+        const saltResult = this._cryptoProvider.generateRandomBytes(model_2.MIN_SALT_LENGTH);
         /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
         if (saltResult.isFailure()) {
             return (0, ts_utils_1.fail)(`Failed to generate salt: ${saltResult.message}`);
@@ -567,6 +568,111 @@ class KeyStore {
         }
         return (0, ts_utils_1.succeed)(KeyStore._timingSafeEqual(derivedResult.value, entry.key));
     }
+    /**
+     * Adds a secret derived from a password using Argon2id (RFC 9106).
+     *
+     * The Argon2id provider must be supplied explicitly; the KeyStore does not
+     * hold one by default (consumers opt in by depending on the argon2 package).
+     *
+     * Returns the key derivation parameters so callers can store them alongside
+     * encrypted artifacts, enabling future re-derivation and verification.
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password or passphrase
+     * @param argon2idProvider - Argon2id provider (Node or Browser implementation)
+     * @param options - Optional: Argon2id params (defaults to ARGON2ID_OWASP_MIN), description, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
+     */
+    async addSecretFromPasswordArgon2id(name, password, argon2idProvider, options) {
+        var _a;
+        if (!this._secrets) {
+            return (0, ts_utils_1.fail)('Key store is locked');
+        }
+        if (!name || name.length === 0) {
+            return (0, ts_utils_1.fail)('Secret name cannot be empty');
+        }
+        if (!password || password.length === 0) {
+            return (0, ts_utils_1.fail)('Password cannot be empty');
+        }
+        const existing = this._secrets.get(name);
+        if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
+            return (0, ts_utils_1.fail)(`Secret '${name}' already exists - use replace=true to overwrite`);
+        }
+        const params = (_a = options === null || options === void 0 ? void 0 : options.params) !== null && _a !== void 0 ? _a : model_1.ARGON2ID_OWASP_MIN;
+        const saltResult = this._cryptoProvider.generateRandomBytes(model_2.MIN_SALT_LENGTH);
+        /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
+        if (saltResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to generate salt: ${saltResult.message}`);
+        }
+        const keyResult = await argon2idProvider.argon2id(password, saltResult.value, params);
+        if (keyResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Argon2id key derivation failed: ${keyResult.message}`);
+        }
+        if (keyResult.value.length !== Constants.AES_256_KEY_SIZE) {
+            return (0, ts_utils_1.fail)(`Argon2id outputBytes must be ${Constants.AES_256_KEY_SIZE} for KeyStore secrets, got ${keyResult.value.length}`);
+        }
+        const entry = {
+            name,
+            type: 'encryption-key',
+            key: keyResult.value,
+            description: options === null || options === void 0 ? void 0 : options.description,
+            createdAt: getCurrentTimestamp()
+        };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
+        this._secrets.set(name, entry);
+        this._dirty = true;
+        const keyDerivation = {
+            kdf: 'argon2id',
+            salt: this._cryptoProvider.toBase64(saltResult.value),
+            memoryKiB: params.memoryKiB,
+            iterations: params.iterations,
+            parallelism: params.parallelism
+        };
+        return (0, ts_utils_1.succeed)({ entry, replaced: existing !== undefined, warning, keyDerivation });
+    }
+    /**
+     * Verifies a candidate password against an Argon2id-derived entry using the
+     * supplied key derivation parameters. Constant-time comparison.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param argon2idProvider - Argon2id provider (must produce bit-identical output for identical inputs)
+     * @param keyDerivation - The Argon2id key derivation parameters returned by `addSecretFromPasswordArgon2id`
+     * @returns Success(true) if candidate matches stored key, Success(false) if not,
+     * Failure if locked, secret missing, wrong type, or derivation fails
+     * @public
+     */
+    async verifySecretFromPasswordArgon2id(name, password, argon2idProvider, keyDerivation) {
+        if (!this._secrets) {
+            return (0, ts_utils_1.fail)('Key store is locked');
+        }
+        if (!password || password.length === 0) {
+            return (0, ts_utils_1.fail)('Password cannot be empty');
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return (0, ts_utils_1.fail)(`Secret '${name}' not found`);
+        }
+        if (entry.type !== 'encryption-key') {
+            return (0, ts_utils_1.fail)(`Secret '${name}' is not a password-verifiable encryption key (type: ${entry.type})`);
+        }
+        const saltResult = this._cryptoProvider.fromBase64(keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid salt: ${saltResult.message}`);
+        }
+        const params = {
+            memoryKiB: keyDerivation.memoryKiB,
+            iterations: keyDerivation.iterations,
+            parallelism: keyDerivation.parallelism,
+            outputBytes: entry.key.length
+        };
+        const derivedResult = await argon2idProvider.argon2id(password, saltResult.value, params);
+        if (derivedResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Argon2id key derivation failed: ${derivedResult.message}`);
+        }
+        return (0, ts_utils_1.succeed)(KeyStore._timingSafeEqual(derivedResult.value, entry.key));
+    }
     /**
      * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
      * before any storage cleanup runs. For asymmetric-keypair entries, best-effort
@@ -897,7 +1003,7 @@ class KeyStore {
             }
         }
         // Generate new salt for the new password using crypto provider
-        const saltResult = this._cryptoProvider.generateRandomBytes(model_1.MIN_SALT_LENGTH);
+        const saltResult = this._cryptoProvider.generateRandomBytes(model_2.MIN_SALT_LENGTH);
         /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
         if (saltResult.isFailure()) {
             return (0, ts_utils_1.fail)(`Failed to generate salt: ${saltResult.message}`);
@@ -1009,7 +1115,7 @@ class KeyStore {
             }
         }
         const vaultContents = {
-            version: model_1.KEYSTORE_FORMAT,
+            version: model_2.KEYSTORE_FORMAT,
             secrets: secretEntries
         };
         // Serialize and encrypt
@@ -1025,7 +1131,7 @@ class KeyStore {
         }
         const { iv, authTag, encryptedData } = encryptResult.value;
         const keystoreFileData = {
-            format: model_1.KEYSTORE_FORMAT,
+            format: model_2.KEYSTORE_FORMAT,
             algorithm: Constants.DEFAULT_ALGORITHM,
             iv: this._cryptoProvider.toBase64(iv),
             authTag: this._cryptoProvider.toBase64(authTag),
@@ -1047,7 +1153,7 @@ class KeyStore {
      */
     async _decryptVault(derivedKey) {
         const keystoreFile = this._keystoreFile;
-        /* c8 ignore next 3 - defensive coding: keystoreFile cannot be undefined at call sites */
+        /* c8 ignore next 3 - defensive: _decryptVault is only called after a successful open() or create() */
         if (keystoreFile === undefined) {
             return (0, ts_utils_1.fail)('No key store file loaded');
         }
@@ -1155,8 +1261,7 @@ class KeyStore {
      * the position of the first differing byte.
      */
     static _timingSafeEqual(a, b) {
-        /* c8 ignore next 4 - defensive: callers in this class only compare
-           PBKDF2-derived 32-byte keys against encryption-key entries (also 32 bytes) */
+        /* c8 ignore next 3 - defensive: callers compare equal-length 32-byte PBKDF2 keys */
         if (a.length !== b.length) {
             return false;
         }