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

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

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { ICryptoProvider, IEncryptionResult } from './model';
+import { ICryptoProvider, IEncryptionResult, IWrapBytesOptions, IWrappedBytes, KeyPairAlgorithm } from './model';
 /**
  * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.
  * Uses AES-256-GCM for authenticated encryption.
@@ -59,6 +59,50 @@ export declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * 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.
+     */
+    generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * 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.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * 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.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * 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.
+     */
+    wrapBytes(plaintext: Uint8Array, recipientPublicKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<IWrappedBytes>>;
+    /**
+     * 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.
+     */
+    unwrapBytes(wrapped: IWrappedBytes, recipientPrivateKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<Uint8Array>>;
 }
 /**
  * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.

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

@@ -56,6 +56,7 @@ exports.nodeCryptoProvider = exports.NodeCryptoProvider = void 0;
 const crypto = __importStar(require("crypto"));
 const ts_utils_1 = require("@fgv/ts-utils");
 const Constants = __importStar(require("./constants"));
+const keyPairAlgorithmParams_1 = require("./keyPairAlgorithmParams");
 /**
  * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.
  * Uses AES-256-GCM for authenticated encryption.
@@ -198,8 +199,146 @@ class NodeCryptoProvider {
         }
         return ts_utils_1.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_1.keyPairAlgorithmParams[algorithm];
+        const result = await (0, ts_utils_1.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 (0, ts_utils_1.fail)(`exportPublicKeyJwk requires a public CryptoKey, got '${publicKey.type}'`);
+        }
+        const result = await (0, ts_utils_1.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_1.keyPairAlgorithmParams[algorithm];
+        const result = await (0, ts_utils_1.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 (0, ts_utils_1.fail)(`wrapBytes failed: ${recipientCheck.message}`);
+        }
+        const subtle = crypto.webcrypto.subtle;
+        const result = await (0, ts_utils_1.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 (0, ts_utils_1.fail)(`unwrapBytes failed: ${recipientCheck.message}`);
+        }
+        const nonceResult = this.fromBase64(wrapped.nonce);
+        if (nonceResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`unwrapBytes failed: nonce: ${nonceResult.message}`);
+        }
+        if (nonceResult.value.length !== Constants.GCM_IV_SIZE) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);
+        }
+        if (ciphertextResult.value.length < Constants.GCM_AUTH_TAG_SIZE) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.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}`);
+    }
 }
 exports.NodeCryptoProvider = NodeCryptoProvider;
+/**
+ * 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 (0, ts_utils_1.fail)(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);
+    }
+    const namedCurve = key.algorithm.namedCurve;
+    if (namedCurve !== 'P-256') {
+        return (0, ts_utils_1.fail)(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);
+    }
+    if (key.type !== keyType) {
+        return (0, ts_utils_1.fail)(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);
+    }
+    return (0, ts_utils_1.succeed)(key);
+}
 /**
  * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.
  * @public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-17",
+  "version": "5.1.0-19",
   "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/ts-utils-jest": "5.1.0-17",
-    "@fgv/typedoc-compact-theme": "5.1.0-17",
-    "@fgv/ts-utils": "5.1.0-17",
-    "@fgv/heft-dual-rig": "5.1.0-17"
+    "@fgv/heft-dual-rig": "5.1.0-19",
+    "@fgv/typedoc-compact-theme": "5.1.0-19",
+    "@fgv/ts-utils": "5.1.0-19",
+    "@fgv/ts-utils-jest": "5.1.0-19"
   },
   "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-17"
+    "@fgv/ts-json-base": "5.1.0-19"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-17"
+    "@fgv/ts-utils": "5.1.0-19"
   },
   "repository": {
     "type": "git",