@enbox/crypto 0.0.3 → 0.0.5

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>;
 }

package/src/types/key-deriver.ts

@@ -40,4 +40,53 @@ export interface KeyDeriver<
    * @returns A Promise resolving to the derived key in the specified output format.
    */
   deriveKey(params: DeriveKeyInput): Promise<DeriveKeyOutput>;
+}
+
+/**
+ * The `SimpleKeyDeriver` interface provides a single `deriveKey()` method for key derivation,
+ * without the `deriveBits()` method that {@link KeyDeriver} includes.
+ *
+ * This is useful for implementations that only need key derivation (not raw bit derivation).
+ */
+export interface SimpleKeyDeriver<
+  DeriveKeyInput,
+  DeriveKeyOutput,
+> {
+  /**
+   * Derives a cryptographic key based on the provided input parameters.
+   *
+   * @param params - The parameters for the key derivation process.
+   *
+   * @returns A Promise resolving to the derived key in the specified output format.
+   */
+  deriveKey(params: DeriveKeyInput): Promise<DeriveKeyOutput>;
+}
+
+/**
+ * The `KeyBytesDeriver` interface provides a method for deriving a byte array using a key
+ * derivation algorithm.
+ *
+ * The `deriveKeyBytes()` method derives cryptographic bits from input data using the specified
+ * key derivation algorithm. This interface is designed to support various key derivation
+ * algorithms, accommodating different input and output types.
+ */
+export interface KeyBytesDeriver<
+  DeriveKeyBytesInput,
+  DeriveKeyBytesOutput
+> {
+  /**
+   * Generates a specified number of cryptographic bits from given input parameters.
+   *
+   * @remarks
+   * The `deriveKeyBytes()` method of the {@link KeyBytesDeriver | `KeyBytesDeriver`} interface is
+   * used to create cryptographic material such as initialization vectors or keys from various
+   * sources. The method takes in parameters specific to the chosen key derivation algorithm and
+   * outputs a promise that resolves to a `Uint8Array` containing the derived bits.
+   *
+   * @param params - The parameters for the key derivation process, specific to the chosen
+   *                 algorithm.
+   *
+   * @returns A Promise resolving to the derived bits in the specified format.
+   */
+  deriveKeyBytes(params: DeriveKeyBytesInput): Promise<DeriveKeyBytesOutput>;
 }

package/src/types/key-io.ts

@@ -39,4 +39,44 @@ export interface KeyImporterExporter<
    * @returns A Promise resolving to the key identifier of the imported key.
    */
   importKey(params: ImportKeyInput): Promise<ImportKeyOutput>;
+}
+
+/**
+ * The `KeyExporter` interface provides a method for exporting cryptographic keys.
+ */
+export interface KeyExporter<ExportKeyInput, ExportKeyOutput = Jwk> {
+  /**
+   * Exports a cryptographic key to an external JWK object.
+   *
+   * @param params - The parameters for the key export operation.
+   *
+   * @returns A Promise resolving to the exported key in JWK format.
+   */
+  exportKey(params: ExportKeyInput): Promise<ExportKeyOutput>;
+}
+
+/**
+ * The `KeyImporter` interface provides a method for importing cryptographic keys.
+ */
+export interface KeyImporter<ImportKeyInput, ImportKeyOutput = void> {
+  /**
+   * Imports an external key in JWK format.
+   *
+   * @param params - The parameters for the key import operation.
+   *
+   * @returns A Promise resolving to the key identifier of the imported key.
+   */
+  importKey(params: ImportKeyInput): Promise<ImportKeyOutput>;
+}
+
+/**
+ * The `KeyDeleter` interface provides a method for deleting cryptographic keys.
+ */
+export interface KeyDeleter<DeleteKeyInput> {
+  /**
+   * Deletes a cryptographic key from the key store.
+   *
+   * @param params - The parameters for the key deletion operation.
+   */
+  deleteKey(params: DeleteKeyInput): Promise<void>;
 }

package/src/types/params-direct.ts

@@ -80,6 +80,27 @@ export interface DeriveKeyParams {
   derivedKeyParams: unknown
 }
 
+/**
+ * Parameters for deriving a key from raw byte-based key material.
+ *
+ * Unlike {@link DeriveKeyParams} which operates on JWK keys, this interface works with raw
+ * byte arrays as the base key input, making it suitable for agent-level key derivation where
+ * keys originate from passphrases, seed phrases, or other byte-oriented sources.
+ */
+export interface DeriveKeyFromBytesParams {
+  /** The algorithm identifier. */
+  algorithm: string;
+
+  /** The base key to be used for derivation as a byte array. */
+  baseKeyBytes: Uint8Array;
+
+  /** The algorithm identifier for the derived key. */
+  derivedKeyAlgorithm?: string;
+
+  /** Additional algorithm-specific parameters for key derivation. */
+  [key: string]: unknown;
+}
+
 /**
  * Parameters for derivation of cryptographic byte arrays.
  */

package/src/types/params-kms.ts

@@ -153,4 +153,71 @@ export interface KmsUnwrapKeyParams {
 
   /** Algorithm to be used for unwrapping. */
   unwrapAlgorithm: AlgorithmIdentifier;
+}
+
+/**
+ * Parameters for KMS-based encryption and decryption operations.
+ *
+ * Intended for use with a Key Management System where the key is referenced by URI.
+ */
+export interface KmsCipherParams {
+  /** Identifier for the private key in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** Data to be encrypted or decrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for KMS-based derivation of a byte array from a given base key.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface KmsDeriveKeyBytesParams {
+  /** Identifier for the base key used in derivation in the KMS. */
+  baseKeyUri: KeyIdentifier;
+
+  /** The desired length of the derived key in bits. */
+  length: number;
+}
+
+/**
+ * Parameters for KMS-based key unwrapping. Intended for use with a Key Management System where
+ * the decryption key is referenced by URI.
+ */
+export interface KmsUriUnwrapKeyParams {
+  /** Identifier for the private key in the KMS used for decrypting the wrapped key. */
+  decryptionKeyUri: KeyIdentifier;
+
+  /** The wrapped private key as a byte array. */
+  wrappedKeyBytes: Uint8Array;
+
+  /** The algorithm identifier of the key encrypted in `wrappedKeyBytes`. */
+  wrappedKeyAlgorithm: string;
+
+  /** An object defining the algorithm-specific parameters for decrypting the `wrappedKeyBytes`. */
+  decryptParams?: unknown;
+}
+
+/**
+ * Parameters for KMS-based key wrapping. Intended for use with a Key Management System where
+ * the encryption key is referenced by URI.
+ */
+export interface KmsUriWrapKeyParams {
+  /** Identifier for the private key in the KMS used for encrypting the unwrapped key. */
+  encryptionKeyUri: KeyIdentifier;
+
+  /** A {@link Jwk} containing the private key to be wrapped. */
+  unwrappedKey: Jwk;
+
+  /** An object defining the algorithm-specific parameters for encrypting the `unwrappedKey`. */
+  encryptParams?: unknown;
+}
+
+/**
+ * Parameters for KMS-based key deletion. Intended for use with a Key Management System.
+ */
+export interface KmsDeleteKeyParams {
+  /** Identifier for the key to be deleted in the KMS. */
+  keyUri: KeyIdentifier;
 }

package/src/utils.ts

@@ -1,4 +1,7 @@
+import type { Cipher } from './types/cipher.js';
 import type { Jwk } from './jose/jwk.js';
+import type { KeyWrapper } from './types/key-wrapper.js';
+import type { KeyExporter, KeyImporter } from './types/key-io.js';
 
 import { crypto } from '@noble/hashes/crypto';
 import { randomBytes as nobleRandomBytes } from '@noble/hashes/utils';
@@ -179,3 +182,53 @@ export class CryptoUtils {
     return pin.toString().padStart(length, '0');
   }
 }
+
+/**
+ * Type guard that checks whether the given object implements the {@link Cipher} interface.
+ */
+export function isCipher<EncryptInput, DecryptInput>(
+  obj: unknown
+): obj is Cipher<EncryptInput, DecryptInput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'encrypt' in obj && typeof obj.encrypt === 'function'
+    && 'decrypt' in obj && typeof obj.decrypt === 'function'
+  );
+}
+
+/**
+ * Type guard that checks whether the given object implements the {@link KeyExporter} interface.
+ */
+export function isKeyExporter<ExportKeyInput, ExportKeyOutput>(
+  obj: unknown
+): obj is KeyExporter<ExportKeyInput, ExportKeyOutput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'exportKey' in obj && typeof obj.exportKey === 'function'
+  );
+}
+
+/**
+ * Type guard that checks whether the given object implements the {@link KeyImporter} interface.
+ */
+export function isKeyImporter<ImportKeyInput, ImportKeyOutput>(
+  obj: unknown
+): obj is KeyImporter<ImportKeyInput, ImportKeyOutput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'importKey' in obj && typeof obj.importKey === 'function'
+  );
+}
+
+/**
+ * Type guard that checks whether the given object implements the {@link KeyWrapper} interface.
+ */
+export function isKeyWrapper<WrapKeyInput, UnwrapKeyInput>(
+  obj: unknown
+): obj is KeyWrapper<WrapKeyInput, UnwrapKeyInput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'wrapKey' in obj && typeof obj.wrapKey === 'function'
+    && 'unwrapKey' in obj && typeof obj.unwrapKey === 'function'
+  );
+}