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

package/dist/ts-extras.d.ts

@@ -193,12 +193,30 @@ declare const aiToolEnablement: Converter<IAiToolEnablement>;
  */
 declare const aiWebSearchToolConfig: Converter<IAiWebSearchToolConfig>;
 
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+declare const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm>;
+
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+declare const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType>;
+
 /**
  * All valid key store secret types.
  * @public
  */
 declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
 
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+declare const allKeyStoreSymmetricSecretTypes: ReadonlyArray<KeyStoreSymmetricSecretType>;
+
 /**
  * All valid {@link ModelSpecKey} values.
  * @public
@@ -388,6 +406,12 @@ declare namespace Converters_2 {
     export {
         keystoreFormat,
         keystoreSecretType,
+        keystoreSymmetricSecretType,
+        keystoreAsymmetricSecretType,
+        keyPairAlgorithm,
+        jsonWebKeyShape,
+        keystoreSymmetricEntryJson,
+        keystoreAsymmetricEntryJson,
         keystoreSecretEntryJson,
         keystoreVaultContents,
         keystoreFile
@@ -440,6 +464,8 @@ declare namespace CryptoUtils {
         Converters_3 as Converters,
         DirectEncryptionProvider,
         IDirectEncryptionProviderParams,
+        IKeyPairAlgorithmParams,
+        keyPairAlgorithmParams,
         NodeCryptoProvider,
         nodeCryptoProvider,
         createEncryptedFile,
@@ -453,6 +479,8 @@ declare namespace CryptoUtils {
         EncryptedFileFormat,
         INamedSecret,
         IEncryptionResult,
+        KeyPairAlgorithm,
+        allKeyPairAlgorithms,
         KeyDerivationFunction,
         IKeyDerivationParams,
         IEncryptedFile,
@@ -829,6 +857,50 @@ declare namespace Hash {
 }
 export { Hash }
 
+/**
+ * Options for adding an asymmetric keypair to the key store.
+ * @public
+ */
+declare 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
+ */
+declare 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;
+}
+
 /**
  * Options for adding a secret derived from a password.
  * @public
@@ -879,11 +951,19 @@ declare 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;
 }
 
 /**
@@ -1389,6 +1469,32 @@ declare 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>>;
 }
 
 /**
@@ -1534,10 +1640,10 @@ declare interface IEncryptionResult {
  */
 declare 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;
 }
 
 /**
@@ -1571,6 +1677,111 @@ declare interface IKeyDerivationParams {
     readonly iterations: number;
 }
 
+/**
+ * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.
+ * Implementations of {@link CryptoUtils.ICryptoProvider} use this table to
+ * translate the small public algorithm enum into the WebCrypto algorithm
+ * objects and key-usage arrays expected by `crypto.subtle`.
+ * @public
+ */
+declare interface IKeyPairAlgorithmParams {
+    /**
+     * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric
+     * variant — these algorithms produce a `CryptoKeyPair`, not a single key.
+     */
+    readonly generateKey: RsaHashedKeyGenParams | EcKeyGenParams;
+    /**
+     * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when
+     * importing the public half of a keypair.
+     */
+    readonly importPublicKey: RsaHashedImportParams | EcKeyImportParams;
+    /**
+     * Default key usages for the generated `CryptoKeyPair`. Both halves receive
+     * the usages WebCrypto considers valid for their role; the platform filters.
+     */
+    readonly keyPairUsages: ReadonlyArray<KeyUsage>;
+    /**
+     * Key usages applied when re-importing only the public key.
+     */
+    readonly publicKeyUsages: ReadonlyArray<KeyUsage>;
+}
+
+/**
+ * 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
+ */
+declare 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;
+}
+
+/**
+ * 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
+ */
+declare 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;
+}
+
 /**
  * Parameters for creating a new key store.
  * @public
@@ -1584,8 +1795,26 @@ declare 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;
 }
 
+/**
+ * Any vault entry, discriminated by `type`.
+ * @public
+ */
+declare type IKeyStoreEntry = IKeyStoreSymmetricEntry | IKeyStoreAsymmetricEntry;
+
+/**
+ * Any JSON vault entry, discriminated by `type`.
+ * @public
+ */
+declare type IKeyStoreEntryJson = IKeyStoreSymmetricEntryJson | IKeyStoreAsymmetricEntryJson;
+
 /**
  * The encrypted key store file format.
  * @public
@@ -1630,22 +1859,46 @@ declare 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;
 }
 
 /**
- * A secret entry stored in the vault (in-memory representation).
+ * 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
+ */
+declare type IKeyStoreSecretEntry = IKeyStoreSymmetricEntry;
+
+/**
+ * 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
  */
-declare interface IKeyStoreSecretEntry {
+declare type IKeyStoreSecretEntryJson = IKeyStoreSymmetricEntryJson;
+
+/**
+ * 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
+ */
+declare 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.
@@ -1663,19 +1916,34 @@ declare interface IKeyStoreSecretEntry {
 }
 
 /**
- * JSON-serializable version of secret entry (for storage).
+ * 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
  */
-declare interface IKeyStoreSecretEntryJson {
+declare 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.
      */
@@ -1691,7 +1959,7 @@ declare interface IKeyStoreSecretEntryJson {
 }
 
 /**
- * The decrypted vault contents - a versioned map of secrets.
+ * The decrypted vault contents - a versioned map of entries.
  * @public
  */
 declare interface IKeyStoreVaultContents {
@@ -1700,9 +1968,9 @@ declare 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>;
 }
 
 /**
@@ -1785,6 +2053,55 @@ declare interface INamedSecret {
     readonly key: Uint8Array;
 }
 
+/**
+ * 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
+ */
+declare 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[]>>;
+}
+
 /**
  * Parameters for a provider completion request.
  * @public
@@ -1884,6 +2201,24 @@ declare interface IProviderListModelsParams {
     readonly signal?: AbortSignal;
 }
 
+/**
+ * Result of removing a secret from the key store.
+ * @public
+ */
+declare 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;
+}
+
 /**
  * Required version of options with all fields populated.
  * @internal
@@ -2015,6 +2350,24 @@ declare interface JarRecordParserOptions {
     readonly fixedContinuationSize?: number;
 }
 
+/**
+ * In-place shape check for a JSON Web Key. Asserts only that the input is a
+ * non-array object whose `kty` discriminator is a string; every other JWK
+ * field passes through untouched. This is intentionally **not** a true JWK
+ * validator — per-algorithm correctness (RSA `n`/`e`, EC `crv`/`x`/`y`,
+ * key-size constraints, etc.) is delegated to `crypto.subtle.importKey` at
+ * first use, which is the authoritative checker. The "shape" suffix in the
+ * name is the warning sign for readers expecting full validation.
+ * @remarks
+ * Built with `Validators.object` (in-place, non-strict) so unknown JWK fields
+ * survive the round-trip; the cast to `FieldValidators<JsonWebKey>` is required
+ * only because TypeScript's mapped type demands an entry for every key in
+ * `JsonWebKey`. At runtime the `ObjectValidator` only inspects keys present in
+ * the field-validators map.
+ * @public
+ */
+declare const jsonWebKeyShape: Validator<JsonWebKey>;
+
 /**
  * Supported key derivation functions.
  * @public
@@ -2033,18 +2386,54 @@ declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
  */
 declare const keyDerivationParams: Converter<IKeyDerivationParams>;
 
+/**
+ * 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
+ */
+declare type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048';
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+declare const keyPairAlgorithm: Converter<KeyPairAlgorithm>;
+
+/**
+ * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto
+ * parameters needed to drive `crypto.subtle`. Shared between every
+ * {@link CryptoUtils.ICryptoProvider} implementation since both Node and
+ * browser providers speak the same WebCrypto API. Exposed for downstream
+ * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).
+ * @public
+ */
+declare const keyPairAlgorithmParams: Readonly<Record<KeyPairAlgorithm, IKeyPairAlgorithmParams>>;
+
 declare namespace KeyStore {
     export {
         Converters_2 as Converters,
         KeyStore_2 as KeyStore,
         isKeyStoreFile,
+        allKeyPairAlgorithms,
+        KeyPairAlgorithm,
         KeyStoreFormat,
         KEYSTORE_FORMAT,
         DEFAULT_KEYSTORE_ITERATIONS,
         MIN_SALT_LENGTH,
+        KeyStoreSymmetricSecretType,
+        allKeyStoreSymmetricSecretTypes,
+        KeyStoreAsymmetricSecretType,
+        allKeyStoreAsymmetricSecretTypes,
         KeyStoreSecretType,
         allKeyStoreSecretTypes,
+        IKeyStoreSymmetricEntry,
+        IKeyStoreAsymmetricEntry,
+        IKeyStoreEntry,
         IKeyStoreSecretEntry,
+        IKeyStoreSymmetricEntryJson,
+        IKeyStoreAsymmetricEntryJson,
+        IKeyStoreEntryJson,
         IKeyStoreSecretEntryJson,
         IKeyStoreVaultContents,
         IKeyStoreFile,
@@ -2057,7 +2446,11 @@ declare namespace KeyStore {
         IImportKeyOptions,
         IAddSecretFromPasswordOptions,
         DEFAULT_SECRET_ITERATIONS,
-        IAddSecretFromPasswordResult
+        IAddSecretFromPasswordResult,
+        IAddKeyPairOptions,
+        IAddKeyPairResult,
+        IRemoveSecretResult,
+        IPrivateKeyStorage
     }
 }
 
@@ -2094,6 +2487,7 @@ declare namespace KeyStore {
  */
 declare class KeyStore_2 implements IEncryptionProvider {
     private readonly _cryptoProvider;
+    private readonly _privateKeyStorage;
     private readonly _iterations;
     private _keystoreFile;
     private _salt;
@@ -2192,12 +2586,23 @@ declare class KeyStore_2 implements IEncryptionProvider {
      */
     listSecrets(): Result<readonly string[]>;
     /**
-     * Gets a secret by name.
+     * Gets a secret by name. Returns the {@link CryptoUtils.KeyStore.IKeyStoreEntry | discriminated union}
+     * — callers must check `entry.type` before accessing `key`/`id` since asymmetric
+     * entries carry no raw key material.
      * @param name - Name of the secret
      * @returns Success with secret entry, Failure if not found or locked
      * @public
      */
-    getSecret(name: string): Result<IKeyStoreSecretEntry>;
+    getSecret(name: string): Result<IKeyStoreEntry>;
+    /**
+     * Returns the public-key JWK for an asymmetric-keypair entry.
+     * Available without {@link CryptoUtils.KeyStore.IPrivateKeyStorage} since the
+     * public key lives in the vault metadata directly.
+     * @param name - Name of the entry
+     * @returns Success with the JWK, Failure if not found, locked, or wrong type
+     * @public
+     */
+    getPublicKeyJwk(name: string): Result<JsonWebKey>;
     /**
      * Checks if a secret exists.
      * @param name - Name of the secret
@@ -2227,7 +2632,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns Success with entry, Failure if locked, key invalid, or exists and !replace
      * @public
      */
-    importSecret(name: string, key: Uint8Array, options?: IImportKeyOptions): Result<IAddSecretResult>;
+    importSecret(name: string, key: Uint8Array, options?: IImportKeyOptions): Promise<Result<IAddSecretResult>>;
     /**
      * Adds a secret derived from a password using PBKDF2.
      *
@@ -2244,12 +2649,16 @@ declare class KeyStore_2 implements IEncryptionProvider {
      */
     addSecretFromPassword(name: string, password: string, options?: IAddSecretFromPasswordOptions): Promise<Result<IAddSecretFromPasswordResult>>;
     /**
-     * Removes a secret by name.
+     * 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
+     * calls {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete on the entry's
+     * `id`; a failure is reported via `warning` on the result but does not roll
+     * back the vault removal.
      * @param name - Name of the secret to remove
-     * @returns Success with removed entry, Failure if not found or locked
+     * @returns Success with removed entry (and optional warning), Failure if not found or locked
      * @public
      */
-    removeSecret(name: string): Result<IKeyStoreSecretEntry>;
+    removeSecret(name: string): Promise<Result<IRemoveSecretResult>>;
     /**
      * Imports an API key string into the vault.
      * The string is UTF-8 encoded and stored with type `'api-key'`.
@@ -2259,7 +2668,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns Success with entry, Failure if locked, empty, or exists and !replace
      * @public
      */
-    importApiKey(name: string, apiKey: string, options?: IImportSecretOptions): Result<IAddSecretResult>;
+    importApiKey(name: string, apiKey: string, options?: IImportSecretOptions): Promise<Result<IAddSecretResult>>;
     /**
      * Retrieves an API key string by name.
      * Only works for secrets with type `'api-key'`.
@@ -2268,6 +2677,41 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     getApiKey(name: string): Result<string>;
+    /**
+     * Adds a new asymmetric keypair to the vault. Storage-first: the private key
+     * is stored under a freshly-minted `id` before the public-key vault entry is
+     * committed. If the storage call fails, no vault entry is written and the
+     * operation returns Failure.
+     *
+     * When `replace: true` displaces an existing entry (asymmetric or symmetric),
+     * a fresh `id` is minted; the displaced entry's resources are released
+     * best-effort. Failure of the storage delete is reported via `warning` on the
+     * result but does not roll back the replacement.
+     *
+     * Requires a {@link CryptoUtils.KeyStore.IPrivateKeyStorage} backend
+     * supplied at construction.
+     *
+     * @param name - Unique name for the entry
+     * @param options - Algorithm, optional description, replace flag
+     * @returns Success with the new entry, Failure if locked, no provider, or storage write failed
+     * @public
+     */
+    addKeyPair(name: string, options: IAddKeyPairOptions): Promise<Result<IAddKeyPairResult>>;
+    /**
+     * Retrieves the keypair for an asymmetric-keypair entry. The private key is
+     * loaded from {@link CryptoUtils.KeyStore.IPrivateKeyStorage} on every call —
+     * the keystore never caches private `CryptoKey` references between calls.
+     * The public key is re-imported from the vault's JWK so callers always
+     * receive a `CryptoKey` rather than the JWK form.
+     * @param name - Name of the entry
+     * @returns Success with `{ publicKey, privateKey }`, Failure if not found,
+     * locked, wrong type, no provider, or storage load failed.
+     * @public
+     */
+    getKeyPair(name: string): Promise<Result<{
+        publicKey: CryptoKey;
+        privateKey: CryptoKey;
+    }>>;
     /**
      * Lists secret names filtered by type.
      * @param type - The secret type to filter by
@@ -2282,7 +2726,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns Success with updated entry, Failure if source not found, target exists, or locked
      * @public
      */
-    renameSecret(oldName: string, newName: string): Result<IKeyStoreSecretEntry>;
+    renameSecret(oldName: string, newName: string): Result<IKeyStoreEntry>;
     /**
      * Saves the key store, returning the encrypted file content.
      * Requires the master password to encrypt.
@@ -2339,6 +2783,23 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * Shared by `unlock()` and `unlockWithKey()`.
      */
     private _decryptVault;
+    /**
+     * Releases the resources held by an entry being displaced from the vault.
+     * Symmetric entries get their key buffer zeroed in place. Asymmetric entries
+     * have their private-key blob best-effort deleted from
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}; if the storage call fails,
+     * a warning string is returned but the displacement still proceeds — the
+     * orphaned blob is left for consumer-side GC. Without a configured provider,
+     * asymmetric cleanup is silently skipped.
+     * @returns A warning string if storage cleanup failed, otherwise undefined.
+     */
+    private _releaseEntryResources;
+    /**
+     * Mints a fresh UUID v4 storage handle using the crypto provider's
+     * {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes}.
+     * Random-bytes failures propagate as Failure.
+     */
+    private _generateId;
 }
 
 /**
@@ -2347,6 +2808,31 @@ declare class KeyStore_2 implements IEncryptionProvider {
  */
 declare const KEYSTORE_FORMAT: KeyStoreFormat;
 
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreAsymmetricEntryJson | asymmetric keypair entry} in JSON form.
+ * The `publicKeyJwk` field passes through {@link CryptoUtils.KeyStore.Converters.jsonWebKeyShape | jsonWebKeyShape}
+ * (shape check only — see its docs); cryptographic correctness is enforced by
+ * `crypto.subtle.importKey` at use.
+ * @public
+ */
+declare const keystoreAsymmetricEntryJson: Converter<IKeyStoreAsymmetricEntryJson>;
+
+/**
+ * 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
+ */
+declare type KeyStoreAsymmetricSecretType = 'asymmetric-keypair';
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+declare const keystoreAsymmetricSecretType: Converter<KeyStoreAsymmetricSecretType>;
+
 /**
  * Converter for {@link CryptoUtils.KeyStore.IKeyStoreFile | encrypted key store file}.
  * @public
@@ -2372,25 +2858,59 @@ declare const keystoreFormat: Converter<KeyStoreFormat>;
 declare type KeyStoreLockState = 'locked' | 'unlocked';
 
 /**
- * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSecretEntryJson | key store secret entry} in JSON format.
- * The `type` field is optional for backwards compatibility — missing means `'encryption-key'`.
+ * Discriminated-union converter for any {@link CryptoUtils.KeyStore.IKeyStoreEntryJson | key store entry} in JSON form.
+ * Routes by the `type` field: `'asymmetric-keypair'` is parsed by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreAsymmetricEntryJson | keystoreAsymmetricEntryJson},
+ * anything else (including a missing `type` field for backwards compatibility) by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson}.
+ * @public
+ */
+declare const keystoreSecretEntryJson: Converter<IKeyStoreEntryJson>;
+
+/**
+ * Discriminator for any secret type stored in the vault.
+ * @public
+ */
+declare type KeyStoreSecretType = KeyStoreSymmetricSecretType | KeyStoreAsymmetricSecretType;
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | any key store secret type} discriminator.
+ * Accepts both symmetric and asymmetric type values.
+ * @public
+ */
+declare const keystoreSecretType: Converter<KeyStoreSecretType>;
+
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson | symmetric secret entry} in JSON form.
+ *
+ * @remarks
+ * Backwards compatibility with vaults written before asymmetric-keypair
+ * support: those entries may lack the `type` discriminator on the wire. To
+ * keep the model type honest (`type` is required on
+ * {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}, see its docs),
+ * we declare `type` in `optionalFields` so the inner `Converters.object` will
+ * accept input without it, then `.map()` injects the default
+ * `'encryption-key'` when missing. The output therefore always carries the
+ * discriminator and downstream code never sees the legacy missing-type form.
+ *
  * @public
  */
-declare const keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+declare const keystoreSymmetricEntryJson: Converter<IKeyStoreSymmetricEntryJson>;
 
 /**
- * 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
  */
-declare type KeyStoreSecretType = 'encryption-key' | 'api-key';
+declare type KeyStoreSymmetricSecretType = 'encryption-key' | 'api-key';
 
 /**
- * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
  * @public
  */
-declare const keystoreSecretType: Converter<KeyStoreSecretType>;
+declare const keystoreSymmetricSecretType: Converter<KeyStoreSymmetricSecretType>;
 
 /**
  * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
@@ -2604,6 +3124,31 @@ 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>>;
 }
 
 /**