@fgv/ts-extras 5.1.0-17 → 5.1.0-19

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

@@ -17,6 +17,9 @@
 // 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.
+// Re-export so consumers can continue to access the algorithm enum via the
+// CryptoUtils.KeyStore namespace alongside the rest of the keystore types.
+export { allKeyPairAlgorithms } from '../model';
 /**
  * Current format version constant.
  * @public
@@ -33,11 +36,29 @@ export const DEFAULT_KEYSTORE_ITERATIONS = 600000;
  * @public
  */
 export const MIN_SALT_LENGTH = 16;
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+export const allKeyStoreSymmetricSecretTypes = [
+    'encryption-key',
+    'api-key'
+];
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+export const allKeyStoreAsymmetricSecretTypes = [
+    'asymmetric-keypair'
+];
 /**
  * All valid key store secret types.
  * @public
  */
-export const allKeyStoreSecretTypes = ['encryption-key', 'api-key'];
+export const allKeyStoreSecretTypes = [
+    ...allKeyStoreAsymmetricSecretTypes,
+    ...allKeyStoreSymmetricSecretTypes
+];
 /**
  * Default PBKDF2 iterations for secret-level key derivation.
  * Lower than keystore encryption since these are used more frequently.

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

@@ -0,0 +1,21 @@
+// 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.
+export {};
+//# sourceMappingURL=privateKeyStorage.js.map

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

@@ -19,6 +19,11 @@
 // SOFTWARE.
 import * as Constants from './constants';
 export { Constants };
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+export const allKeyPairAlgorithms = ['ecdsa-p256', 'rsa-oaep-2048'];
 // ============================================================================
 // Detection Helper
 // ============================================================================

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

@@ -18,8 +18,9 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 import * as crypto from 'crypto';
-import { captureResult, fail, Failure, succeed, Success } from '@fgv/ts-utils';
+import { captureAsyncResult, captureResult, fail, Failure, succeed, Success } from '@fgv/ts-utils';
 import * as Constants from './constants';
+import { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 /**
  * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.
  * Uses AES-256-GCM for authenticated encryption.
@@ -162,6 +163,144 @@ export class NodeCryptoProvider {
         }
         return Success.with(new Uint8Array(Buffer.from(base64, 'base64')));
     }
+    // ============================================================================
+    // Asymmetric Key Operations
+    // ============================================================================
+    /**
+     * Generates a new asymmetric keypair using Node's WebCrypto.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.
+     * @param extractable - Whether the resulting keys may be exported.
+     * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.
+     */
+    async generateKeyPair(algorithm, extractable) {
+        const params = keyPairAlgorithmParams[algorithm];
+        const result = await captureAsyncResult(() => crypto.webcrypto.subtle.generateKey(params.generateKey, extractable, params.keyPairUsages));
+        return result.withErrorFormat((e) => `Failed to generate ${algorithm} keypair: ${e}`);
+    }
+    /**
+     * Exports a public `CryptoKey` as a JSON Web Key.
+     * @remarks
+     * Rejects non-public keys at runtime. WebCrypto's `exportKey('jwk', ...)`
+     * does not enforce public-vs-private; without this guard a caller that
+     * passed an extractable private key would receive its private fields
+     * (`d`, `p`, `q`, ...) as JWK, defeating the method's name.
+     * @param publicKey - Extractable public key to export.
+     * @returns `Success` with the JWK, or `Failure` if not a public key or if export fails.
+     */
+    async exportPublicKeyJwk(publicKey) {
+        if (publicKey.type !== 'public') {
+            return fail(`exportPublicKeyJwk requires a public CryptoKey, got '${publicKey.type}'`);
+        }
+        const result = await captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('jwk', publicKey));
+        return result.withErrorFormat((e) => `Failed to export public key as JWK: ${e}`);
+    }
+    /**
+     * Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+     * @param jwk - The JSON Web Key produced by a prior export.
+     * @param algorithm - The algorithm the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with an error.
+     */
+    async importPublicKeyJwk(jwk, algorithm) {
+        const params = keyPairAlgorithmParams[algorithm];
+        const result = await captureAsyncResult(() => crypto.webcrypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, params.publicKeyUsages));
+        return result.withErrorFormat((e) => `Failed to import ${algorithm} public key from JWK: ${e}`);
+    }
+    /**
+     * Wraps `plaintext` for the holder of `recipientPublicKey` using
+     * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See
+     * {@link CryptoUtils.ICryptoProvider.wrapBytes | ICryptoProvider.wrapBytes}.
+     * @param plaintext - The bytes to wrap.
+     * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.
+     * @param options - HKDF salt and info; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.
+     * @returns `Success` with the wrapped payload, or `Failure` with an error.
+     */
+    async wrapBytes(plaintext, recipientPublicKey, options) {
+        const recipientCheck = checkEcdhP256(recipientPublicKey, 'public', 'recipient public key');
+        if (recipientCheck.isFailure()) {
+            return fail(`wrapBytes failed: ${recipientCheck.message}`);
+        }
+        const subtle = crypto.webcrypto.subtle;
+        const result = await captureAsyncResult(async () => {
+            const ephemeral = (await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+                'deriveKey'
+            ]));
+            const hkdfBase = await subtle.deriveKey({ name: 'ECDH', public: recipientPublicKey }, ephemeral.privateKey, { name: 'HKDF' }, false, ['deriveKey']);
+            const wrapKey = await subtle.deriveKey({ name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' }, hkdfBase, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+            const nonce = crypto.randomBytes(Constants.GCM_IV_SIZE);
+            const ctBuf = await subtle.encrypt({ name: 'AES-GCM', iv: nonce }, wrapKey, plaintext);
+            const ephemeralPublicKey = await subtle.exportKey('jwk', ephemeral.publicKey);
+            return {
+                ephemeralPublicKey,
+                nonce: this.toBase64(nonce),
+                ciphertext: this.toBase64(new Uint8Array(ctBuf))
+            };
+        });
+        return result.withErrorFormat((e) => `wrapBytes failed: ${e}`);
+    }
+    /**
+     * Unwraps a payload produced by `wrapBytes` using the recipient's private
+     * key. See {@link CryptoUtils.ICryptoProvider.unwrapBytes | ICryptoProvider.unwrapBytes}.
+     * @param wrapped - The wrapped payload.
+     * @param recipientPrivateKey - The recipient's ECDH P-256 private `CryptoKey`.
+     * @param options - HKDF salt and info matching the wrap call.
+     * @returns `Success` with the original `plaintext`, or `Failure` with an error.
+     */
+    async unwrapBytes(wrapped, recipientPrivateKey, options) {
+        const recipientCheck = checkEcdhP256(recipientPrivateKey, 'private', 'recipient private key');
+        if (recipientCheck.isFailure()) {
+            return fail(`unwrapBytes failed: ${recipientCheck.message}`);
+        }
+        const nonceResult = this.fromBase64(wrapped.nonce);
+        if (nonceResult.isFailure()) {
+            return fail(`unwrapBytes failed: nonce: ${nonceResult.message}`);
+        }
+        if (nonceResult.value.length !== Constants.GCM_IV_SIZE) {
+            return fail(`unwrapBytes failed: nonce must be ${Constants.GCM_IV_SIZE} bytes (got ${nonceResult.value.length})`);
+        }
+        const ciphertextResult = this.fromBase64(wrapped.ciphertext);
+        if (ciphertextResult.isFailure()) {
+            return fail(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);
+        }
+        if (ciphertextResult.value.length < Constants.GCM_AUTH_TAG_SIZE) {
+            return fail(`unwrapBytes failed: ciphertext must be at least ${Constants.GCM_AUTH_TAG_SIZE} bytes (got ${ciphertextResult.value.length})`);
+        }
+        const subtle = crypto.webcrypto.subtle;
+        const result = await captureAsyncResult(async () => {
+            const ephemeralPub = await subtle.importKey('jwk', wrapped.ephemeralPublicKey, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+            const hkdfBase = await subtle.deriveKey({ name: 'ECDH', public: ephemeralPub }, recipientPrivateKey, { name: 'HKDF' }, false, ['deriveKey']);
+            const wrapKey = await subtle.deriveKey({ name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' }, hkdfBase, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+            const ptBuf = await subtle.decrypt({ name: 'AES-GCM', iv: nonceResult.value }, wrapKey, ciphertextResult.value);
+            return new Uint8Array(ptBuf);
+        });
+        return result.withErrorFormat((e) => `unwrapBytes failed: ${e}`);
+    }
+}
+/**
+ * Verifies that `key` is an ECDH P-256 `CryptoKey` of the expected `keyType`
+ * (public or private). Used by the wrap/unwrap methods to surface a clean
+ * `Failure` instead of letting the WebCrypto deriveKey call throw a less
+ * informative error later in the pipeline. Key usages are intentionally not
+ * checked here: WebCrypto already produces a specific error if `deriveKey` is
+ * not in `usages`, and `deriveBits` is an equally valid alternative usage that
+ * an explicit check would have to track.
+ * @param key - The CryptoKey to validate.
+ * @param keyType - The required `key.type` ('public' for wrap, 'private' for unwrap).
+ * @param label - Human-readable role label included in the failure message.
+ * @returns `Success` with the key (unchanged) when the algorithm, curve, and
+ * type all match; otherwise `Failure` with `<label> must be ECDH P-256 (...)`.
+ */
+function checkEcdhP256(key, keyType, label) {
+    if (key.algorithm.name !== 'ECDH') {
+        return fail(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);
+    }
+    const namedCurve = key.algorithm.namedCurve;
+    if (namedCurve !== 'P-256') {
+        return fail(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);
+    }
+    if (key.type !== keyType) {
+        return fail(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);
+    }
+    return succeed(key);
 }
 /**
  * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.

package/dist/test/unit/crypto/keystore/inMemoryPrivateKeyStorage.js

@@ -0,0 +1,78 @@
+// 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.
+import { fail, succeed } from '@fgv/ts-utils';
+/**
+ * In-memory implementation of `IPrivateKeyStorage` for keystore tests.
+ *
+ * Not exported from `@fgv/ts-extras`. Lives in the test tree as a reference
+ * implementation downstream packages may copy if useful, but the public API
+ * delegates concrete backends to platform-specific packages
+ * (browser/IDB in `@fgv/ts-web-extras`, encrypted-file in `@fgv/ts-chocolate`).
+ *
+ * Holds `CryptoKey` objects directly in a `Map`, so it advertises
+ * `supportsNonExtractable: true` by default. The constructor accepts overrides
+ * useful for negative tests:
+ *   - `supportsNonExtractable: false` exercises the extractable=true codepath.
+ *   - `failOn: { store?, load?, delete?, list? }` makes the named operations
+ *     return Failure with a stable message so tests can assert downstream
+ *     warning/error propagation without resorting to mocks.
+ */
+export class InMemoryPrivateKeyStorage {
+    constructor(options) {
+        var _a, _b;
+        this.supportsNonExtractable = (_a = options === null || options === void 0 ? void 0 : options.supportsNonExtractable) !== null && _a !== void 0 ? _a : true;
+        this.entries = new Map();
+        this._failOn = (_b = options === null || options === void 0 ? void 0 : options.failOn) !== null && _b !== void 0 ? _b : {};
+    }
+    async store(id, key) {
+        if (this._failOn.store) {
+            return fail(this._failOn.store);
+        }
+        this.entries.set(id, key);
+        return succeed(id);
+    }
+    async load(id) {
+        if (this._failOn.load) {
+            return fail(this._failOn.load);
+        }
+        const key = this.entries.get(id);
+        if (!key) {
+            return fail(`No private key for id '${id}'`);
+        }
+        return succeed(key);
+    }
+    async delete(id) {
+        if (this._failOn.delete) {
+            return fail(this._failOn.delete);
+        }
+        if (!this.entries.has(id)) {
+            return fail(`No private key for id '${id}'`);
+        }
+        this.entries.delete(id);
+        return succeed(id);
+    }
+    async list() {
+        if (this._failOn.list) {
+            return fail(this._failOn.list);
+        }
+        return succeed(Array.from(this.entries.keys()));
+    }
+}
+//# sourceMappingURL=inMemoryPrivateKeyStorage.js.map