@enbox/crypto 0.0.3 → 0.0.4

package/src/algorithms/x25519.ts

@@ -0,0 +1,153 @@
+import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
+import type { Jwk } from '../jose/jwk.js';
+import type { KeyConverter } from '../types/key-converter.js';
+import type {
+  BytesToPrivateKeyParams,
+  ComputePublicKeyParams,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  PrivateKeyToBytesParams,
+} from '../types/params-direct.js';
+
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { isOkpPrivateJwk } from '../jose/jwk.js';
+import { X25519 } from '../primitives/x25519.js';
+
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+
+/**
+ * The `X25519GenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the X25519 key agreement algorithm.
+ */
+export interface X25519GenerateKeyParams extends GenerateKeyParams {
+  /**
+   * A string defining the type of key to generate. The value must be:
+   * - `"X25519"`: Elliptic-curve Diffie-Hellman (ECDH) using Curve25519.
+   */
+  algorithm: 'X25519';
+}
+
+/**
+ * The `X25519Algorithm` class provides a concrete implementation for key generation,
+ * public key derivation, and key conversion using the X25519 elliptic curve. X25519 is a
+ * key agreement curve (not a signature curve) used for ECDH key exchange in JWE encryption.
+ *
+ * This class implements the {@link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`} and
+ * {@link KeyConverter | `KeyConverter`} interfaces, providing private key generation,
+ * public key derivation, and byte/JWK conversion.
+ */
+export class X25519Algorithm extends CryptoAlgorithm
+  implements AsymmetricKeyGenerator<X25519GenerateKeyParams, Jwk, GetPublicKeyParams>,
+             KeyConverter {
+
+  /**
+   * Converts a raw private key in bytes to its corresponding JWK format.
+   *
+   * @param params - The parameters for the private key conversion.
+   * @param params.algorithm - Must be `'X25519'`.
+   * @param params.privateKeyBytes - The raw private key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the private key in JWK format.
+   */
+  public async bytesToPrivateKey({ algorithm, privateKeyBytes }:
+    BytesToPrivateKeyParams & { algorithm: 'X25519' }
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'X25519': {
+        return X25519.bytesToPrivateKey({ privateKeyBytes });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  /**
+   * Derives the public key in JWK format from a given X25519 private key.
+   *
+   * @param params - The parameters for the public key derivation.
+   * @param params.key - The private key in JWK format from which to derive the public key.
+   *
+   * @returns A Promise that resolves to the derived public key in JWK format.
+   */
+  public async computePublicKey({ key }:
+    ComputePublicKeyParams
+  ): Promise<Jwk> {
+    if (!isOkpPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');}
+
+    switch (key.crv) {
+
+      case 'X25519': {
+        return X25519.computePublicKey({ key });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Generates a new X25519 private key in JWK format.
+   *
+   * @param params - The parameters for key generation.
+   * @param params.algorithm - Must be `'X25519'`.
+   *
+   * @returns A Promise that resolves to the generated private key in JWK format.
+   */
+  async generateKey({ algorithm }:
+    X25519GenerateKeyParams
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'X25519': {
+        return X25519.generateKey();
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  /**
+   * Retrieves the public key properties from a given X25519 private key in JWK format.
+   *
+   * @param params - The parameters for retrieving the public key properties.
+   * @param params.key - The private key in JWK format.
+   *
+   * @returns A Promise that resolves to the public key in JWK format.
+   */
+  public async getPublicKey({ key }:
+    GetPublicKeyParams
+  ): Promise<Jwk> {
+    if (!isOkpPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');}
+
+    switch (key.crv) {
+
+      case 'X25519': {
+        return X25519.getPublicKey({ key });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Converts a private key from JWK format to a byte array.
+   *
+   * @param params - The parameters for the private key conversion.
+   * @param params.privateKey - The private key in JWK format.
+   *
+   * @returns A Promise that resolves to the private key as a Uint8Array.
+   */
+  public async privateKeyToBytes({ privateKey }:
+    PrivateKeyToBytesParams
+  ): Promise<Uint8Array> {
+    return X25519.privateKeyToBytes({ privateKey });
+  }
+}

package/src/index.ts

@@ -4,10 +4,14 @@ export * from './utils.js';
 
 export * from './algorithms/aes-ctr.js';
 export * from './algorithms/aes-gcm.js';
+export * from './algorithms/aes-kw.js';
 export * from './algorithms/crypto-algorithm.js';
 export * from './algorithms/ecdsa.js';
 export * from './algorithms/eddsa.js';
+export * from './algorithms/hkdf.js';
+export * from './algorithms/pbkdf2.js';
 export * from './algorithms/sha-2.js';
+export * from './algorithms/x25519.js';
 
 export * from './jose/jwe.js';
 export * from './jose/jwk.js';
@@ -19,6 +23,7 @@ export * from './primitives/aes-ctr.js';
 export * from './primitives/aes-gcm.js';
 export * from './primitives/aes-kw.js';
 export * from './primitives/concat-kdf.js';
+export * from './primitives/ecies-secp256k1.js';
 export * from './primitives/ed25519.js';
 export * from './primitives/hkdf.js';
 export * from './primitives/secp256r1.js';

package/src/local-key-manager.ts

@@ -2,11 +2,11 @@ import type { KeyValueStore } from '@enbox/common';
 import { MemoryStore } from '@enbox/common';
 
 import type { CryptoAlgorithm } from './algorithms/crypto-algorithm.js';
-import type { CryptoApi } from './types/crypto-api.js';
 import type { Hasher } from './types/hasher.js';
 import type { Jwk } from './jose/jwk.js';
 import type { KeyIdentifier } from './types/identifier.js';
 import type { KeyImporterExporter } from './types/key-io.js';
+import type { KeyManager } from './types/crypto-api.js';
 import type { Signer } from './types/signer.js';
 import type { AsymmetricKeyGenerator, KeyGenerator } from './types/key-generator.js';
 import type { GetPublicKeyParams, SignParams, VerifyParams } from './types/params-direct.js';
@@ -24,6 +24,7 @@ import type {
 import { EcdsaAlgorithm } from './algorithms/ecdsa.js';
 import { EdDsaAlgorithm } from './algorithms/eddsa.js';
 import { Sha2Algorithm } from './algorithms/sha-2.js';
+import { X25519Algorithm } from './algorithms/x25519.js';
 import { computeJwkThumbprint, isPrivateJwk, KEY_URI_PREFIX_JWK } from './jose/jwk.js';
 
 /**
@@ -50,6 +51,10 @@ const supportedAlgorithms = {
   'SHA-256': {
     implementation : Sha2Algorithm,
     names          : ['SHA-256']
+  },
+  'X25519': {
+    implementation : X25519Algorithm,
+    names          : ['X25519']
   }
 } satisfies {
   [key: string]: {
@@ -104,11 +109,11 @@ export interface LocalKeyManagerGenerateKeyParams extends KmsGenerateKeyParams {
    * - `"Ed25519"`
    * - `"secp256k1"`
    */
-  algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1';
+  algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1' | 'X25519';
 }
 
 export class LocalKeyManager implements
-    CryptoApi,
+    KeyManager,
     KeyImporterExporter<KmsImportKeyParams, KeyIdentifier, KmsExportKeyParams> {
 
   /**
@@ -242,7 +247,7 @@ export class LocalKeyManager implements
    * @remarks
    * This method generates a {@link https://datatracker.ietf.org/doc/html/rfc3986 | URI}
    * (Uniform Resource Identifier) for the given JWK, which uniquely identifies the key across all
-   * `CryptoApi` implementations. The key URI is constructed by appending the
+   * `KeyManager` implementations. The key URI is constructed by appending the
    * {@link https://datatracker.ietf.org/doc/html/rfc7638 | JWK thumbprint} to the prefix
    * `urn:jwk:`. The JWK thumbprint is deterministically computed from the JWK and is consistent
    * regardless of property order or optional property inclusion in the JWK. This ensures that the

package/src/primitives/ecies-secp256k1.ts

@@ -0,0 +1,113 @@
+import { concatBytes } from '@noble/ciphers/utils';
+import { gcm } from '@noble/ciphers/aes';
+import { hkdf } from '@noble/hashes/hkdf';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { sha256 } from '@noble/hashes/sha256';
+
+/**
+ * AEAD tag length for AES-256-GCM (16 bytes / 128 bits).
+ */
+const AEAD_TAG_LENGTH = 16;
+
+/**
+ * Nonce length for AES-256-GCM encryption.
+ */
+const NONCE_LENGTH = 16;
+
+/**
+ * Output of an ECIES-SECP256K1 encryption operation.
+ */
+export type EciesSecp256k1EncryptionOutput = {
+  /** The AES-GCM initialization vector. */
+  initializationVector: Uint8Array;
+  /** The ephemeral secp256k1 public key (compressed, 33 bytes). */
+  ephemeralPublicKey: Uint8Array;
+  /** The encrypted data. */
+  ciphertext: Uint8Array;
+  /** The AES-GCM authentication tag (16 bytes). */
+  messageAuthenticationCode: Uint8Array;
+};
+
+/**
+ * Input required for ECIES-SECP256K1 decryption.
+ */
+export type EciesSecp256k1EncryptionInput = EciesSecp256k1EncryptionOutput & {
+  /** The recipient's secp256k1 private key (raw 32 bytes). */
+  privateKey: Uint8Array;
+};
+
+/**
+ * Browser-compatible ECIES (Elliptic Curve Integrated Encryption Scheme) using secp256k1.
+ *
+ * Wire-format compatible with `eciesjs` v0.4.x configured with
+ * `isEphemeralKeyCompressed: true, isHkdfKeyCompressed: false` (the default).
+ *
+ * Protocol:
+ *   1. Generate an ephemeral secp256k1 key pair.
+ *   2. ECDH shared secret (uncompressed point).
+ *   3. HKDF-SHA-256 key derivation: `hkdf(sha256, ephemeralPubUncompressed || sharedPointUncompressed)`.
+ *   4. AES-256-GCM encryption with random 16-byte nonce.
+ *
+ * All underlying primitives (`@noble/ciphers`, `@noble/curves`, `@noble/hashes`)
+ * are pure JavaScript and work in Node, Bun, and browsers.
+ */
+export class EciesSecp256k1 {
+  /**
+   * Encrypt plaintext for a given secp256k1 public key.
+   * @param publicKeyBytes - Recipient's public key (compressed 33 bytes or uncompressed 65 bytes).
+   * @param plaintext - The data to encrypt.
+   */
+  public static encrypt(publicKeyBytes: Uint8Array, plaintext: Uint8Array): EciesSecp256k1EncryptionOutput {
+    // Generate ephemeral key pair.
+    const ephemeralPrivateKey = secp256k1.utils.randomPrivateKey();
+    const ephemeralPubCompressed = secp256k1.getPublicKey(ephemeralPrivateKey, true);
+    const ephemeralPubUncompressed = secp256k1.getPublicKey(ephemeralPrivateKey, false);
+
+    // ECDH: shared point (uncompressed).
+    const sharedPointUncompressed = secp256k1.getSharedSecret(ephemeralPrivateKey, publicKeyBytes, false);
+
+    // HKDF-SHA-256: derive 32-byte symmetric key.
+    // eciesjs (isHkdfKeyCompressed=false): master = senderPubUncompressed || sharedPointUncompressed
+    const symmetricKey = hkdf(sha256, concatBytes(ephemeralPubUncompressed, sharedPointUncompressed), undefined, undefined, 32);
+
+    // AES-256-GCM encrypt.
+    const nonce = randomBytes(NONCE_LENGTH);
+    const ciphered = gcm(symmetricKey, nonce).encrypt(plaintext); // ciphertext || tag
+
+    return {
+      ephemeralPublicKey        : ephemeralPubCompressed,
+      initializationVector      : nonce,
+      messageAuthenticationCode : ciphered.subarray(ciphered.length - AEAD_TAG_LENGTH),
+      ciphertext                : ciphered.subarray(0, ciphered.length - AEAD_TAG_LENGTH),
+    };
+  }
+
+  /**
+   * Decrypt ciphertext produced by {@link EciesSecp256k1.encrypt}.
+   * @param input - The encryption output plus the recipient's private key.
+   */
+  public static decrypt(input: EciesSecp256k1EncryptionInput): Uint8Array {
+    const { privateKey, ephemeralPublicKey, initializationVector, messageAuthenticationCode, ciphertext } = input;
+
+    // Decompress ephemeral public key (HKDF needs uncompressed form).
+    const ephemeralPubUncompressed = secp256k1.ProjectivePoint.fromHex(ephemeralPublicKey).toRawBytes(false);
+
+    // ECDH: shared point (uncompressed).
+    const sharedPointUncompressed = secp256k1.getSharedSecret(privateKey, ephemeralPublicKey, false);
+
+    // HKDF-SHA-256: derive 32-byte symmetric key (same derivation as encrypt).
+    const symmetricKey = hkdf(sha256, concatBytes(ephemeralPubUncompressed, sharedPointUncompressed), undefined, undefined, 32);
+
+    // AES-256-GCM decrypt: reconstruct the wire format (ciphertext || tag).
+    const ciphered = concatBytes(ciphertext, messageAuthenticationCode);
+    return gcm(symmetricKey, Uint8Array.from(initializationVector)).decrypt(ciphered);
+  }
+
+  /**
+   * Whether the ephemeral public key is compressed (always true for this implementation).
+   */
+  public static get isEphemeralKeyCompressed(): boolean {
+    return true;
+  }
+}

package/src/primitives/x25519.ts

@@ -345,32 +345,25 @@ export class X25519 {
   }
 
   /**
-   * Computes an RFC6090-compliant Elliptic Curve Diffie-Hellman (ECDH) shared secret
-   * using secp256k1 private and public keys in JSON Web Key (JWK) format.
+   * Computes an X25519 Elliptic Curve Diffie-Hellman (ECDH) shared secret
+   * using X25519 private and public keys in JSON Web Key (JWK) format.
    *
    * @remarks
    * This method facilitates the ECDH key agreement protocol, which is a method of securely
    * deriving a shared secret between two parties based on their private and public keys.
    * It takes the private key of one party (privateKeyA) and the public key of another
-   * party (publicKeyB) to compute a shared secret. The shared secret is derived from the
-   * x-coordinate of the elliptic curve point resulting from the multiplication of the
-   * public key with the private key.
-   *
-   * Note: When performing Elliptic Curve Diffie-Hellman (ECDH) key agreement,
-   * the resulting shared secret is a point on the elliptic curve, which
-   * consists of an x-coordinate and a y-coordinate. With a 256-bit curve like
-   * secp256k1, each of these coordinates is 32 bytes (256 bits) long. However,
-   * in the ECDH process, it's standard practice to use only the x-coordinate
-   * of the shared secret point as the resulting shared key. This is because
-   * the y-coordinate does not add to the entropy of the key, and both parties
-   * can independently compute the x-coordinate.  Consquently, this implementation
-   * omits the y-coordinate for simplicity and standard compliance.
+   * party (publicKeyB) to compute a shared secret. The shared secret is the raw output
+   * of the X25519 function as defined in RFC 7748.
+   *
+   * Note: Unlike Weierstrass curves (e.g., secp256k1), X25519 is a Montgomery curve
+   * where the ECDH output is a single 32-byte scalar value, not an (x, y) point.
+   * The result is used directly as the shared secret.
    *
    * @example
    * ```ts
    * const privateKeyA = { ... }; // A Jwk object for party A
    * const publicKeyB = { ... }; // A PublicKeyJwk object for party B
-   * const sharedSecret = await Secp256k1.sharedSecret({
+   * const sharedSecret = await X25519.sharedSecret({
    *   privateKeyA,
    *   publicKeyB
    * });

package/src/types/crypto-api.ts

@@ -1,8 +1,30 @@
+import type { AsymmetricKeyConverter } from './key-converter.js';
 import type { AsymmetricKeyGenerator } from './key-generator.js';
+import type { Cipher } from './cipher.js';
 import type { Hasher } from './hasher.js';
+import type { Jwk } from '../jose/jwk.js';
 import type { KeyIdentifier } from './identifier.js';
+import type { KeyWrapper } from './key-wrapper.js';
 import type { Signer } from './signer.js';
 import type {
+  BytesToPrivateKeyParams,
+  BytesToPublicKeyParams,
+  CipherParams,
+  DeriveKeyBytesParams,
+  DeriveKeyFromBytesParams,
+  DigestParams,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  PrivateKeyToBytesParams,
+  PublicKeyToBytesParams,
+  SignParams,
+  UnwrapKeyParams,
+  VerifyParams,
+  WrapKeyParams,
+} from './params-direct.js';
+import type { KeyBytesDeriver, SimpleKeyDeriver } from './key-deriver.js';
+import type {
+  KmsCipherParams,
   KmsDigestParams,
   KmsGenerateKeyParams,
   KmsGetKeyUriParams,
@@ -12,7 +34,7 @@ import type {
 } from './params-kms.js';
 
 /**
- * The `CryptoApi` interface integrates key generation, hashing, and signing functionalities,
+ * The `DsaApi` interface integrates key generation, hashing, and signing functionalities,
  * designed for use with a Key Management System (KMS). It extends `AsymmetricKeyGenerator` for
  * generating asymmetric keys, `Hasher` for hash digest computations, and `Signer` for signing and
  * verifying operations.
@@ -32,25 +54,121 @@ import type {
  *   identifier (e.g. JWK thumbprint, UUID generated by hosted KMS, etc.).
  * - Must support key generation, hashing, signing, and verifying operations.
  * - May be extended to support other cryptographic operations.
- * - Implementations of the `CryptoApi` interface can be passed as an argument to the public API
+ * - Implementations of the `DsaApi` interface can be passed as an argument to the public API
  *   methods of Web5 libraries that involve key material (e.g., DID creation, VC signing, arbitrary
  *   data signing/verification, etc.).
  */
-export interface CryptoApi<
+export interface DsaApi<
   GenerateKeyInput = KmsGenerateKeyParams,
   GenerateKeyOutput = KeyIdentifier,
   GetPublicKeyInput = KmsGetPublicKeyParams,
   DigestInput = KmsDigestParams,
   SignInput = KmsSignParams,
   VerifyInput = KmsVerifyParams
-> extends AsymmetricKeyGenerator<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput>,
+ > extends AsymmetricKeyGenerator<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput>,
           Hasher<DigestInput>,
-          Signer<SignInput, VerifyInput> {
+          Signer<SignInput, VerifyInput> {}
+
+/**
+ * The `CryptoApi` interface extends {@link DsaApi} with encryption, key conversion,
+ * key derivation, and key wrapping capabilities.
+ *
+ * This is the full-featured cryptographic API used by agent-level code that needs direct-key
+ * cipher, key conversion, and key derivation operations beyond what the base `DsaApi` provides.
+ */
+export interface CryptoApi<
+  GenerateKeyInput = GenerateKeyParams,
+  GenerateKeyOutput = Jwk,
+  GetPublicKeyInput = GetPublicKeyParams,
+  DigestInput = DigestParams,
+  SignInput = SignParams,
+  VerifyInput = VerifyParams,
+  EncryptInput = CipherParams,
+  DecryptInput = CipherParams,
+  BytesToPublicKeyInput = BytesToPublicKeyParams,
+  PublicKeyToBytesInput = PublicKeyToBytesParams,
+  BytesToPrivateKeyInput = BytesToPrivateKeyParams,
+  PrivateKeyToBytesInput = PrivateKeyToBytesParams,
+  DeriveKeyInput = DeriveKeyFromBytesParams,
+  DeriveKeyOutput = Jwk,
+  DeriveKeyBytesInput = DeriveKeyBytesParams,
+  DeriveKeyBytesOutput = Uint8Array,
+  WrapKeyInput = WrapKeyParams,
+  UnwrapKeyInput = UnwrapKeyParams
+> extends
+  DsaApi<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput, DigestInput, SignInput, VerifyInput>,
+  Cipher<EncryptInput, DecryptInput>,
+  AsymmetricKeyConverter<BytesToPublicKeyInput, PublicKeyToBytesInput, BytesToPrivateKeyInput, PrivateKeyToBytesInput>,
+  SimpleKeyDeriver<DeriveKeyInput, DeriveKeyOutput>,
+  KeyBytesDeriver<DeriveKeyBytesInput, DeriveKeyBytesOutput>,
+  KeyWrapper<WrapKeyInput, UnwrapKeyInput> {}
+
+/** @deprecated Use {@link CryptoApi} instead. */
+export type ExtendedCryptoApi<
+  GenerateKeyInput = GenerateKeyParams,
+  GenerateKeyOutput = Jwk,
+  GetPublicKeyInput = GetPublicKeyParams,
+  DigestInput = DigestParams,
+  SignInput = SignParams,
+  VerifyInput = VerifyParams,
+  EncryptInput = CipherParams,
+  DecryptInput = CipherParams,
+  BytesToPublicKeyInput = BytesToPublicKeyParams,
+  PublicKeyToBytesInput = PublicKeyToBytesParams,
+  BytesToPrivateKeyInput = BytesToPrivateKeyParams,
+  PrivateKeyToBytesInput = PrivateKeyToBytesParams,
+  DeriveKeyInput = DeriveKeyFromBytesParams,
+  DeriveKeyOutput = Jwk,
+  DeriveKeyBytesInput = DeriveKeyBytesParams,
+  DeriveKeyBytesOutput = Uint8Array,
+  WrapKeyInput = WrapKeyParams,
+  UnwrapKeyInput = UnwrapKeyParams
+> = CryptoApi<
+  GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput, DigestInput, SignInput, VerifyInput,
+  EncryptInput, DecryptInput, BytesToPublicKeyInput, PublicKeyToBytesInput,
+  BytesToPrivateKeyInput, PrivateKeyToBytesInput, DeriveKeyInput, DeriveKeyOutput,
+  DeriveKeyBytesInput, DeriveKeyBytesOutput, WrapKeyInput, UnwrapKeyInput
+>;
+
+/**
+ * Parameters for configuring a {@link KeyManager} implementation.
+ */
+export interface KeyManagerParams {
+  CipherInput?: unknown;
+  GenerateKeyInput?: unknown;
+  GenerateKeyOutput?: unknown;
+  GetPublicKeyInput?: unknown;
+  SignInput?: unknown;
+  VerifyInput?: unknown;
+}
+
+/**
+ * Default parameter types for {@link KeyManager}, using KMS-oriented types.
+ */
+export interface DefaultKeyManagerParams {
+  CipherInput: KmsCipherParams;
+  GenerateKeyInput: KmsGenerateKeyParams;
+  GenerateKeyOutput: KeyIdentifier;
+  GetPublicKeyInput: KmsGetPublicKeyParams;
+  SignInput: KmsSignParams;
+  VerifyInput: KmsVerifyParams;
+}
+
+/**
+ * The `KeyManager` interface integrates key generation and signing capabilities.
+ *
+ * Concrete implementations of this interface are intended to be used as a Key Management System
+ * (KMS), which is responsible for generating and storing cryptographic keys.
+ */
+export interface KeyManager<T extends KeyManagerParams = DefaultKeyManagerParams>
+  extends DsaApi<T['GenerateKeyInput'], T['GenerateKeyOutput'], T['GetPublicKeyInput'], KmsDigestParams, T['SignInput'], T['VerifyInput']> {
+
   /**
+   * Returns the Key URI for a given JWK.
    *
    * @param params - The parameters for getting the key URI.
    * @param params.key - The key to get the URI for.
    * @returns The key URI.
    */
   getKeyUri(params: KmsGetKeyUriParams): Promise<KeyIdentifier>;
-}
+}

package/src/types/key-converter.ts

@@ -2,8 +2,16 @@ import type { Jwk } from '../jose/jwk.js';
 
 /**
  * `KeyConverter` interface for converting private keys between byte array and JWK formats.
+ *
+ * @typeParam BytesToPrivateKeyInput - The input type for `bytesToPrivateKey`. Defaults to
+ *   `{ privateKeyBytes: Uint8Array }`.
+ * @typeParam PrivateKeyToBytesInput - The input type for `privateKeyToBytes`. Defaults to
+ *   `{ privateKey: Jwk }`.
  */
-export interface KeyConverter {
+export interface KeyConverter<
+  BytesToPrivateKeyInput = { privateKeyBytes: Uint8Array },
+  PrivateKeyToBytesInput = { privateKey: Jwk }
+> {
 
   /**
    * Converts a private key from a byte array to JWK format.
@@ -13,7 +21,7 @@ export interface KeyConverter {
    *
    * @returns A Promise that resolves to the private key in JWK format.
    */
-  bytesToPrivateKey(params: { privateKeyBytes: Uint8Array }): Promise<Jwk>;
+  bytesToPrivateKey(params: BytesToPrivateKeyInput): Promise<Jwk>;
 
   /**
    * Converts a private key from JWK format to a byte array.
@@ -23,14 +31,32 @@ export interface KeyConverter {
    *
    * @returns A Promise that resolves to the private key as a Uint8Array.
    */
-  privateKeyToBytes(params: { privateKey: Jwk }): Promise<Uint8Array>;
+  privateKeyToBytes(params: PrivateKeyToBytesInput): Promise<Uint8Array>;
 }
 
 /**
- * `AsymmetricKeyConverter` interface extends {@link KeyConverter |`KeyConverter`}, adding support
+ * `AsymmetricKeyConverter` interface extends {@link KeyConverter | `KeyConverter`}, adding support
  * for public key conversions.
+ *
+ * When used with default type parameters, this interface includes all four conversion methods
+ * (bytes-to/from private key AND bytes-to/from public key). When used with explicit type
+ * parameters, both the private and public key conversion types can be customized.
+ *
+ * @typeParam BytesToPublicKeyInput - The input type for `bytesToPublicKey`. Defaults to
+ *   `{ publicKeyBytes: Uint8Array }`.
+ * @typeParam PublicKeyToBytesInput - The input type for `publicKeyToBytes`. Defaults to
+ *   `{ publicKey: Jwk }`.
+ * @typeParam BytesToPrivateKeyInput - The input type for `bytesToPrivateKey`. Defaults to
+ *   `{ privateKeyBytes: Uint8Array }`.
+ * @typeParam PrivateKeyToBytesInput - The input type for `privateKeyToBytes`. Defaults to
+ *   `{ privateKey: Jwk }`.
  */
-export interface AsymmetricKeyConverter extends KeyConverter {
+export interface AsymmetricKeyConverter<
+  BytesToPublicKeyInput = { publicKeyBytes: Uint8Array },
+  PublicKeyToBytesInput = { publicKey: Jwk },
+  BytesToPrivateKeyInput = { privateKeyBytes: Uint8Array },
+  PrivateKeyToBytesInput = { privateKey: Jwk }
+> extends KeyConverter<BytesToPrivateKeyInput, PrivateKeyToBytesInput> {
   /**
    * Converts a public key from a byte array to JWK format.
    *
@@ -39,7 +65,7 @@ export interface AsymmetricKeyConverter extends KeyConverter {
    *
    * @returns A Promise that resolves to the public key in JWK format.
    */
-  bytesToPublicKey(params: { publicKeyBytes: Uint8Array }): Promise<Jwk>;
+  bytesToPublicKey(params: BytesToPublicKeyInput): Promise<Jwk>;
 
   /**
    * Converts a public key from JWK format to a byte array.
@@ -49,5 +75,5 @@ export interface AsymmetricKeyConverter extends KeyConverter {
    *
    * @returns A Promise that resolves to the public key as a Uint8Array.
    */
-  publicKeyToBytes(params: { publicKey: Jwk }): Promise<Uint8Array>;
+  publicKeyToBytes(params: PublicKeyToBytesInput): Promise<Uint8Array>;
 }