@fgv/ts-extras 5.1.0-16 → 5.1.0-18

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

@@ -1,4 +1,6 @@
-import { EncryptionAlgorithm, ICryptoProvider, IKeyDerivationParams } from '../model';
+import { EncryptionAlgorithm, ICryptoProvider, IKeyDerivationParams, KeyPairAlgorithm } from '../model';
+import { IPrivateKeyStorage } from './privateKeyStorage';
+export { allKeyPairAlgorithms, KeyPairAlgorithm } from '../model';
 /**
  * Format version for key store files.
  * @public
@@ -21,31 +23,55 @@ export declare const DEFAULT_KEYSTORE_ITERATIONS: number;
  */
 export declare const MIN_SALT_LENGTH: number;
 /**
- * Discriminator for secret types stored in the vault.
+ * Discriminator for symmetric secret types stored in the vault.
  * - `'encryption-key'`: A 32-byte AES-256 encryption key.
  * - `'api-key'`: An arbitrary-length API key string (UTF-8 encoded).
  * @public
  */
-export type KeyStoreSecretType = 'encryption-key' | 'api-key';
+export type KeyStoreSymmetricSecretType = 'encryption-key' | 'api-key';
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+export declare const allKeyStoreSymmetricSecretTypes: ReadonlyArray<KeyStoreSymmetricSecretType>;
+/**
+ * Discriminator for asymmetric secret types stored in the vault.
+ * - `'asymmetric-keypair'`: A public/private key pair. The public key is held in
+ *   the vault as a JWK; the private key lives in the supplied
+ *   {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider.
+ * @public
+ */
+export type KeyStoreAsymmetricSecretType = 'asymmetric-keypair';
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+export declare const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType>;
+/**
+ * Discriminator for any secret type stored in the vault.
+ * @public
+ */
+export type KeyStoreSecretType = KeyStoreSymmetricSecretType | KeyStoreAsymmetricSecretType;
 /**
  * All valid key store secret types.
  * @public
  */
 export declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
 /**
- * A secret entry stored in the vault (in-memory representation).
+ * A symmetric secret entry stored in the vault (in-memory representation).
+ * Holds the raw key material directly — for `'encryption-key'` it is a 32-byte
+ * AES-256 key; for `'api-key'` it is the UTF-8 encoded API key string.
  * @public
  */
-export interface IKeyStoreSecretEntry {
+export interface IKeyStoreSymmetricEntry {
     /**
      * Unique name for this secret (used as lookup key).
      */
     readonly name: string;
     /**
-     * Secret type discriminator.
-     * Defaults to `'encryption-key'` for backwards compatibility.
+     * Symmetric secret type discriminator.
      */
-    readonly type: KeyStoreSecretType;
+    readonly type: KeyStoreSymmetricSecretType;
     /**
      * The secret data.
      * - For `'encryption-key'`: 32-byte AES-256 key.
@@ -62,19 +88,83 @@ export interface IKeyStoreSecretEntry {
     readonly createdAt: string;
 }
 /**
- * JSON-serializable version of secret entry (for storage).
+ * An asymmetric keypair entry stored in the vault (in-memory representation).
+ * Holds only the public key (as a JWK) and a stable handle (`id`) the
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider uses to fetch the private key.
+ * @public
+ */
+export interface IKeyStoreAsymmetricEntry {
+    /**
+     * Unique name for this entry (used as vault lookup key, renameable).
+     */
+    readonly name: string;
+    /**
+     * Asymmetric secret type discriminator.
+     */
+    readonly type: KeyStoreAsymmetricSecretType;
+    /**
+     * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the
+     * private key. Independent of `name`; survives renames.
+     */
+    readonly id: string;
+    /**
+     * Algorithm used to generate this keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * The public key as a JSON Web Key.
+     */
+    readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional description for this entry.
+     */
+    readonly description?: string;
+    /**
+     * When this entry was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+/**
+ * Any vault entry, discriminated by `type`.
+ * @public
+ */
+export type IKeyStoreEntry = IKeyStoreSymmetricEntry | IKeyStoreAsymmetricEntry;
+/**
+ * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry}.
+ * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry} for symmetric
+ * entries or {@link CryptoUtils.KeyStore.IKeyStoreEntry} for the discriminated union.
+ * @public
+ */
+export type IKeyStoreSecretEntry = IKeyStoreSymmetricEntry;
+/**
+ * JSON-serializable representation of a symmetric secret entry.
+ *
+ * @remarks
+ * Describes the *normalized* shape after parsing. `type` is required here
+ * because the converter (see
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson})
+ * injects the default `'encryption-key'` when reading vaults written before
+ * asymmetric-keypair support added the discriminator. Raw on-wire bytes from
+ * a legacy vault may therefore omit `type`; downstream code only ever sees
+ * the post-conversion shape declared here.
+ *
  * @public
  */
-export interface IKeyStoreSecretEntryJson {
+export interface IKeyStoreSymmetricEntryJson {
     /**
      * Unique name for this secret.
      */
     readonly name: string;
     /**
-     * Secret type discriminator.
-     * Optional for backwards compatibility — missing means `'encryption-key'`.
+     * Symmetric secret type discriminator.
+     *
+     * Required on this normalized model type. Vaults written prior to the
+     * asymmetric-keypair support may omit this field on the wire; the
+     * converter injects `'encryption-key'` when missing for backwards
+     * compatibility, so by the time a value of this type is observed the
+     * discriminator is always present.
      */
-    readonly type?: KeyStoreSecretType;
+    readonly type: KeyStoreSymmetricSecretType;
     /**
      * Base64-encoded secret data.
      */
@@ -89,7 +179,57 @@ export interface IKeyStoreSecretEntryJson {
     readonly createdAt: string;
 }
 /**
- * The decrypted vault contents - a versioned map of secrets.
+ * JSON-serializable representation of an asymmetric keypair entry.
+ * The private key is not present here — it lives in the
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider, addressed by `id`.
+ * @public
+ */
+export interface IKeyStoreAsymmetricEntryJson {
+    /**
+     * Unique name for this entry.
+     */
+    readonly name: string;
+    /**
+     * Asymmetric secret type discriminator.
+     */
+    readonly type: KeyStoreAsymmetricSecretType;
+    /**
+     * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the
+     * private key.
+     */
+    readonly id: string;
+    /**
+     * Algorithm used to generate this keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * The public key as a JSON Web Key.
+     */
+    readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional description.
+     */
+    readonly description?: string;
+    /**
+     * When this entry was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+/**
+ * Any JSON vault entry, discriminated by `type`.
+ * @public
+ */
+export type IKeyStoreEntryJson = IKeyStoreSymmetricEntryJson | IKeyStoreAsymmetricEntryJson;
+/**
+ * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}.
+ * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson} for
+ * symmetric entries or {@link CryptoUtils.KeyStore.IKeyStoreEntryJson} for the
+ * discriminated union.
+ * @public
+ */
+export type IKeyStoreSecretEntryJson = IKeyStoreSymmetricEntryJson;
+/**
+ * The decrypted vault contents - a versioned map of entries.
  * @public
  */
 export interface IKeyStoreVaultContents {
@@ -98,9 +238,9 @@ export interface IKeyStoreVaultContents {
      */
     readonly version: KeyStoreFormat;
     /**
-     * Map of secret name to secret entry.
+     * Map of entry name to entry (symmetric or asymmetric).
      */
-    readonly secrets: Record<string, IKeyStoreSecretEntryJson>;
+    readonly secrets: Record<string, IKeyStoreEntryJson>;
 }
 /**
  * The encrypted key store file format.
@@ -150,6 +290,12 @@ export interface IKeyStoreCreateParams {
      * PBKDF2 iterations (defaults to DEFAULT_KEYSTORE_ITERATIONS).
      */
     readonly iterations?: number;
+    /**
+     * Optional private-key storage backend. Required to use `addKeyPair` /
+     * `getKeyPair`; absent backends still permit opening, listing, and reading
+     * public-key metadata for asymmetric entries.
+     */
+    readonly privateKeyStorage?: IPrivateKeyStorage;
 }
 /**
  * Parameters for opening an existing key store.
@@ -164,6 +310,12 @@ export interface IKeyStoreOpenParams {
      * The encrypted key store file content.
      */
     readonly keystoreFile: IKeyStoreFile;
+    /**
+     * Optional private-key storage backend. Required to use `addKeyPair` /
+     * `getKeyPair`; absent backends still permit opening, listing, and reading
+     * public-key metadata for asymmetric entries.
+     */
+    readonly privateKeyStorage?: IPrivateKeyStorage;
 }
 /**
  * Result of adding a secret to the key store.
@@ -173,11 +325,19 @@ export interface IAddSecretResult {
     /**
      * The secret entry that was added.
      */
-    readonly entry: IKeyStoreSecretEntry;
+    readonly entry: IKeyStoreSymmetricEntry;
     /**
      * Whether this replaced an existing secret.
      */
     readonly replaced: boolean;
+    /**
+     * Best-effort warning from displaced-resource cleanup. Set when this call
+     * replaced an asymmetric-keypair entry but the corresponding
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new
+     * entry is still committed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
 }
 /**
  * Options for adding a secret.
@@ -206,10 +366,10 @@ export interface IImportSecretOptions extends IAddSecretOptions {
  */
 export interface IImportKeyOptions extends IImportSecretOptions {
     /**
-     * Secret type classification for the imported key material.
+     * Symmetric secret type classification for the imported key material.
      * @defaultValue 'encryption-key'
      */
-    readonly type?: KeyStoreSecretType;
+    readonly type?: KeyStoreSymmetricSecretType;
 }
 /**
  * Options for adding a secret derived from a password.
@@ -246,6 +406,65 @@ export interface IAddSecretFromPasswordResult extends IAddSecretResult {
      */
     readonly keyDerivation: IKeyDerivationParams;
 }
+/**
+ * Options for adding an asymmetric keypair to the key store.
+ * @public
+ */
+export interface IAddKeyPairOptions {
+    /**
+     * Algorithm to use for the new keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * Optional description for the entry.
+     */
+    readonly description?: string;
+    /**
+     * Whether to replace an existing entry with the same name.
+     * Replacement mints a fresh storage `id` and best-effort deletes the
+     * displaced storage blob; see the keystore design doc for details.
+     */
+    readonly replace?: boolean;
+}
+/**
+ * Result of adding an asymmetric keypair to the key store.
+ * @public
+ */
+export interface IAddKeyPairResult {
+    /**
+     * The asymmetric entry that was added.
+     */
+    readonly entry: IKeyStoreAsymmetricEntry;
+    /**
+     * Whether this replaced an existing entry.
+     */
+    readonly replaced: boolean;
+    /**
+     * Best-effort warning from displaced-resource cleanup. Set when this call
+     * replaced a prior entry but the corresponding
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new
+     * keypair is still committed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
+}
+/**
+ * Result of removing a secret from the key store.
+ * @public
+ */
+export interface IRemoveSecretResult {
+    /**
+     * The secret entry that was removed from the vault.
+     */
+    readonly entry: IKeyStoreEntry;
+    /**
+     * Best-effort warning from {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete
+     * for asymmetric entries when the storage call failed. The vault entry is
+     * still considered removed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
+}
 /**
  * Checks if a JSON object appears to be a key store file.
  * Uses the format field as a discriminator.

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

@@ -19,8 +19,12 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = void 0;
+exports.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.allKeyStoreAsymmetricSecretTypes = exports.allKeyStoreSymmetricSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = exports.allKeyPairAlgorithms = void 0;
 exports.isKeyStoreFile = isKeyStoreFile;
+// Re-export so consumers can continue to access the algorithm enum via the
+// CryptoUtils.KeyStore namespace alongside the rest of the keystore types.
+var model_1 = require("../model");
+Object.defineProperty(exports, "allKeyPairAlgorithms", { enumerable: true, get: function () { return model_1.allKeyPairAlgorithms; } });
 /**
  * Current format version constant.
  * @public
@@ -37,11 +41,29 @@ exports.DEFAULT_KEYSTORE_ITERATIONS = 600000;
  * @public
  */
 exports.MIN_SALT_LENGTH = 16;
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+exports.allKeyStoreSymmetricSecretTypes = [
+    'encryption-key',
+    'api-key'
+];
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+exports.allKeyStoreAsymmetricSecretTypes = [
+    'asymmetric-keypair'
+];
 /**
  * All valid key store secret types.
  * @public
  */
-exports.allKeyStoreSecretTypes = ['encryption-key', 'api-key'];
+exports.allKeyStoreSecretTypes = [
+    ...exports.allKeyStoreAsymmetricSecretTypes,
+    ...exports.allKeyStoreSymmetricSecretTypes
+];
 /**
  * Default PBKDF2 iterations for secret-level key derivation.
  * Lower than keystore encryption since these are used more frequently.

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

@@ -0,0 +1,50 @@
+import { Result } from '@fgv/ts-utils';
+/**
+ * Pluggable backend that persists raw asymmetric private keys outside of the
+ * encrypted keystore vault. Concrete implementations live in platform-specific
+ * packages (e.g. an IndexedDB-backed implementation in `@fgv/ts-web-extras` or
+ * an encrypted-file implementation in `@fgv/ts-chocolate`).
+ *
+ * The keystore writes storage-first: a private key is always stored here
+ * before the corresponding public-key vault entry is committed. Conversely,
+ * deletes hit the vault first and then this storage best-effort. As a result,
+ * crashes or skipped saves can leave orphaned blobs here; callers are expected
+ * to reconcile via {@link CryptoUtils.KeyStore.IPrivateKeyStorage.list} cross-referenced
+ * against the keystore's asymmetric entries.
+ *
+ * @public
+ */
+export interface IPrivateKeyStorage {
+    /**
+     * Whether keys generated for this backend may be marked
+     * `extractable: false`. `true` on backends that store `CryptoKey`
+     * objects directly (e.g. IndexedDB). `false` on backends that must
+     * round-trip via JWK (e.g. encrypted-file backends).
+     */
+    readonly supportsNonExtractable: boolean;
+    /**
+     * Stores `key` under `id`. Returns the stored `id` on success so the
+     * call can compose into a Result chain.
+     * @param id - Storage handle to write under.
+     * @param key - The private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key previously stored under `id`.
+     * @param id - Storage handle to look up.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Returns the deleted `id` on
+     * success so the call can compose into a Result chain.
+     * @param id - Storage handle to remove.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every `id` currently held by the backend. Used by consumers to
+     * garbage-collect orphans left by crashes or aborted sessions; the
+     * keystore itself does not invoke this automatically.
+     */
+    list(): Promise<Result<readonly string[]>>;
+}
+//# sourceMappingURL=privateKeyStorage.d.ts.map

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

@@ -0,0 +1,22 @@
+"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 });
+//# sourceMappingURL=privateKeyStorage.js.map

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

@@ -44,6 +44,18 @@ export interface IEncryptionResult {
      */
     readonly encryptedData: Uint8Array;
 }
+/**
+ * Asymmetric keypair algorithms supported by the crypto provider.
+ * - `'ecdsa-p256'`: ECDSA over the P-256 curve, for signing.
+ * - `'rsa-oaep-2048'`: RSA-OAEP, 2048-bit modulus with SHA-256, for encryption.
+ * @public
+ */
+export type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048';
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+export declare const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm>;
 /**
  * Supported key derivation functions.
  * @public
@@ -169,6 +181,32 @@ export interface ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * Generates a new asymmetric keypair for the requested algorithm.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.
+     * @param extractable - Whether the resulting `CryptoKey` objects may be exported.
+     * Set `false` on backends that store `CryptoKey` references directly (e.g.
+     * IndexedDB). Set `true` when the private key must round-trip through JWK or
+     * PKCS#8 (e.g. encrypted-file backends).
+     * @returns Success with the generated `CryptoKeyPair`, or Failure with error context.
+     */
+    generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Exports the public half of a keypair as a JSON Web Key.
+     * @param publicKey - The public `CryptoKey` to export. Must be an `extractable`
+     * key generated for an asymmetric algorithm.
+     * @returns Success with the JWK, or Failure with error context.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * Re-imports a public-key JWK as a `CryptoKey` usable for verification or
+     * encryption (depending on algorithm).
+     * @param jwk - The JSON Web Key produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeyJwk | exportPublicKeyJwk}.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the
+     * key was generated for. Determines the import parameters and key usages.
+     * @returns Success with the imported public `CryptoKey`, or Failure with error context.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
 }
 /**
  * High-level interface for encrypting JSON content by secret name.

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

@@ -52,10 +52,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Constants = void 0;
+exports.allKeyPairAlgorithms = exports.Constants = void 0;
 exports.isEncryptedFile = isEncryptedFile;
 const Constants = __importStar(require("./constants"));
 exports.Constants = Constants;
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+exports.allKeyPairAlgorithms = ['ecdsa-p256', 'rsa-oaep-2048'];
 // ============================================================================
 // Detection Helper
 // ============================================================================

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, 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,31 @@ 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>>;
 }
 /**
  * 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,6 +199,48 @@ 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}`);
+    }
 }
 exports.NodeCryptoProvider = NodeCryptoProvider;
 /**

package/lib/packlets/zip-file-tree/zipFileTreeAccessors.d.ts

@@ -132,8 +132,8 @@ export declare class ZipFileTreeAccessors<TCT extends string = string> implement
     private constructor();
     /**
      * Default function to infer the content type of a file.
-     * @param filePath - The path of the file.
-     * @param provided - Optional supplied content type.
+     * @param __filePath - The path of the file.
+     * @param __provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.

package/lib/packlets/zip-file-tree/zipFileTreeAccessors.js

@@ -149,8 +149,8 @@ class ZipFileTreeAccessors {
     }
     /**
      * Default function to infer the content type of a file.
-     * @param filePath - The path of the file.
-     * @param provided - Optional supplied content type.
+     * @param __filePath - The path of the file.
+     * @param __provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.