@enbox/crypto 0.0.1

package/src/primitives/xchacha20-poly1305.ts

@@ -0,0 +1,274 @@
+import { Convert } from '@enbox/common';
+import { xchacha20poly1305 } from '@noble/ciphers/chacha';
+import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
+
+import type { Jwk } from '../jose/jwk.js';
+
+import { computeJwkThumbprint, isOctPrivateJwk } from '../jose/jwk.js';
+
+/**
+ * Constant defining the length of the authentication tag in bytes for XChaCha20-Poly1305.
+ *
+ * @remarks
+ * The `POLY1305_TAG_LENGTH` is set to 16 bytes (128 bits), which is the standard size for the
+ * Poly1305 authentication tag in XChaCha20-Poly1305 encryption. This tag length ensures
+ * a strong level of security for message authentication, verifying the integrity and
+ * authenticity of the data during decryption.
+ */
+export const POLY1305_TAG_LENGTH = 16;
+
+/**
+ * The `XChaCha20Poly1305` class provides a suite of utilities for cryptographic operations
+ * using the XChaCha20-Poly1305 algorithm, a combination of the XChaCha20 stream cipher and the
+ * Poly1305 message authentication code (MAC). This class encompasses methods for key generation,
+ * encryption, decryption, and conversions between raw byte arrays and JSON Web Key (JWK) formats.
+ *
+ * XChaCha20-Poly1305 is renowned for its high security and efficiency, especially in scenarios
+ * involving large data volumes or where data integrity and confidentiality are paramount. The
+ * extended nonce size of XChaCha20 reduces the risks of nonce reuse, while Poly1305 provides
+ * a strong MAC ensuring data integrity.
+ *
+ * Key Features:
+ * - Key Generation: Generate XChaCha20-Poly1305 symmetric keys in JWK format.
+ * - Key Conversion: Transform keys between raw byte arrays and JWK formats.
+ * - Encryption: Encrypt data using XChaCha20-Poly1305, returning both ciphertext and MAC tag.
+ * - Decryption: Decrypt data and verify integrity using the XChaCha20-Poly1305 algorithm.
+ *
+ * The methods in this class are asynchronous, returning Promises to accommodate various
+ * JavaScript environments.
+ *
+ * @example
+ * ```ts
+ * // Key Generation
+ * const privateKey = await XChaCha20Poly1305.generateKey();
+ *
+ * // Encryption
+ * const data = new TextEncoder().encode('Messsage');
+ * const nonce = utils.randomBytes(24); // 24-byte nonce
+ * const additionalData = new TextEncoder().encode('Associated data');
+ * const { ciphertext, tag } = await XChaCha20Poly1305.encrypt({
+ *   data,
+ *   nonce,
+ *   additionalData,
+ *   key: privateKey
+ * });
+ *
+ * // Decryption
+ * const decryptedData = await XChaCha20Poly1305.decrypt({
+ *   data: ciphertext,
+ *   nonce,
+ *   tag,
+ *   additionalData,
+ *   key: privateKey
+ * });
+ *
+ * // Key Conversion
+ * const privateKeyBytes = await XChaCha20Poly1305.privateKeyToBytes({ privateKey });
+ * ```
+ */
+export class XChaCha20Poly1305 {
+  /**
+   * Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method takes a symmetric key represented as a byte array (Uint8Array) and converts it into
+   * a JWK object for use with the XChaCha20-Poly1305 algorithm. The process involves encoding the
+   * key into base64url format and setting the appropriate JWK parameters.
+   *
+   * The resulting JWK object includes the following properties:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence (representing a symmetric key).
+   * - `k`: The symmetric key, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   *
+   * @example
+   * ```ts
+   * const privateKeyBytes = new Uint8Array([...]); // Replace with actual symmetric key bytes
+   * const privateKey = await XChaCha20Poly1305.bytesToPrivateKey({ privateKeyBytes });
+   * ```
+   *
+   * @param params - The parameters for the symmetric key conversion.
+   * @param params.privateKeyBytes - The raw symmetric key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the symmetric key in JWK format.
+   */
+  public static async bytesToPrivateKey({ privateKeyBytes }: {
+    privateKeyBytes: Uint8Array;
+  }): Promise<Jwk> {
+    // Construct the private key in JWK format.
+    const privateKey: Jwk = {
+      k   : Convert.uint8Array(privateKeyBytes).toBase64Url(),
+      kty : 'oct'
+    };
+
+    // Compute the JWK thumbprint and set as the key ID.
+    privateKey.kid = await computeJwkThumbprint({ jwk: privateKey });
+
+    return privateKey;
+  }
+
+  /**
+   * Decrypts the provided data using XChaCha20-Poly1305.
+   *
+   * @remarks
+   * This method performs XChaCha20-Poly1305 decryption on the given encrypted data using the
+   * specified key, nonce, and authentication tag. It supports optional additional authenticated
+   * data (AAD) for enhanced security. The nonce must be 24 bytes long, consistent with XChaCha20's
+   * specifications.
+   *
+   * @example
+   * ```ts
+   * const encryptedData = new Uint8Array([...]); // Encrypted data
+   * const nonce = new Uint8Array(24); // 24-byte nonce
+   * const additionalData = new Uint8Array([...]); // Optional AAD
+   * const key = { ... }; // A Jwk object representing the XChaCha20-Poly1305 key
+   * const decryptedData = await XChaCha20Poly1305.decrypt({
+   *   data: encryptedData,
+   *   nonce,
+   *   additionalData,
+   *   key
+   * });
+   * ```
+   *
+   * @param params - The parameters for the decryption operation.
+   * @param params.data - The encrypted data to decrypt including the authentication tag,
+   *                      represented as a Uint8Array.
+   * @param params.key - The key to use for decryption, represented in JWK format.
+   * @param params.nonce - The nonce used during the encryption process.
+   * @param params.additionalData - Optional additional authenticated data.
+   *
+   * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+   */
+  public static async decrypt({ data, key, nonce, additionalData }: {
+    additionalData?: Uint8Array;
+    data: Uint8Array;
+    key: Jwk;
+    nonce: Uint8Array;
+  }): Promise<Uint8Array> {
+    // Convert the private key from JWK format to bytes.
+    const privateKeyBytes = await XChaCha20Poly1305.privateKeyToBytes({ privateKey: key });
+
+    const xc20p = xchacha20poly1305(privateKeyBytes, nonce, additionalData);
+    const plaintext = xc20p.decrypt(data);
+
+    return plaintext;
+  }
+
+  /**
+   * Encrypts the provided data using XChaCha20-Poly1305.
+   *
+   * @remarks
+   * This method performs XChaCha20-Poly1305 encryption on the given data using the specified key
+   * and nonce. It supports optional additional authenticated data (AAD) for enhanced security. The
+   * nonce must be 24 bytes long, as per XChaCha20's specifications. The method returns the
+   * encrypted data along with an authentication tag as a Uint8Array, ensuring both confidentiality
+   * and integrity of the data.
+   *
+   * @example
+   * ```ts
+   * const data = new TextEncoder().encode('Messsage');
+   * const nonce = utils.randomBytes(24); // 24-byte nonce
+   * const additionalData = new TextEncoder().encode('Associated data'); // Optional AAD
+   * const key = { ... }; // A Jwk object representing an XChaCha20-Poly1305 key
+   * const encryptedData = await XChaCha20Poly1305.encrypt({
+   *   data,
+   *   nonce,
+   *   additionalData,
+   *   key
+   * });
+   * ```
+   *
+   * @param params - The parameters for the encryption operation.
+   * @param params.data - The data to encrypt, represented as a Uint8Array.
+   * @param params.key - The key to use for encryption, represented in JWK format.
+   * @param params.nonce - A 24-byte nonce for the encryption process.
+   * @param params.additionalData - Optional additional authenticated data.
+   *
+   * @returns A Promise that resolves to a byte array containing the encrypted data and the
+   *          authentication tag.
+   */
+  public static async encrypt({ data, key, nonce, additionalData}: {
+    additionalData?: Uint8Array;
+    data: Uint8Array;
+    key: Jwk;
+    nonce: Uint8Array;
+  }): Promise<Uint8Array> {
+    // Convert the private key from JWK format to bytes.
+    const privateKeyBytes = await XChaCha20Poly1305.privateKeyToBytes({ privateKey: key });
+
+    const xc20p = xchacha20poly1305(privateKeyBytes, nonce, additionalData);
+    const ciphertext = xc20p.encrypt(data);
+
+    return ciphertext;
+  }
+
+  /**
+   * Generates a symmetric key for XChaCha20-Poly1305 in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method creates a new symmetric key suitable for use with the XChaCha20-Poly1305 algorithm.
+   * The key is generated using cryptographically secure random number generation to ensure its
+   * uniqueness and security. The XChaCha20-Poly1305 algorithm requires a 256-bit key (32 bytes),
+   * and this method adheres to that specification.
+   *
+   * Key components included in the JWK:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence.
+   * - `k`: The symmetric key component, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   *
+   * @example
+   * ```ts
+   * const privateKey = await XChaCha20Poly1305.generateKey();
+   * ```
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public static async generateKey(): Promise<Jwk> {
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle();
+
+    // Generate a random private key.
+    // See https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues#usage_notes for
+    // an explanation for why Web Crypto generateKey() is used instead of getRandomValues().
+    const webCryptoKey = await webCrypto.generateKey( { name: 'AES-CTR', length: 256 }, true, ['encrypt']);
+
+    // Export the private key in JWK format.
+    const { alg, ext, key_ops, ...privateKey } = await webCrypto.exportKey('jwk', webCryptoKey);
+
+    // Compute the JWK thumbprint and set as the key ID.
+    privateKey.kid = await computeJwkThumbprint({ jwk: privateKey });
+
+    return privateKey;
+  }
+
+  /**
+   * Converts a private key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).
+   *
+   * This method takes a symmetric key in JWK format and extracts its raw byte representation.
+   * It decodes the 'k' parameter of the JWK value, which represents the symmetric key in base64url
+   * encoding, into a byte array.
+   *
+   * @example
+   * ```ts
+   * const privateKey = { ... }; // A symmetric key in JWK format
+   * const privateKeyBytes = await XChaCha20Poly1305.privateKeyToBytes({ privateKey });
+   * ```
+   *
+   * @param params - The parameters for the symmetric key conversion.
+   * @param params.privateKey - The symmetric key in JWK format.
+   *
+   * @returns A Promise that resolves to the symmetric key as a Uint8Array.
+   */
+  public static async privateKeyToBytes({ privateKey }: {
+    privateKey: Jwk;
+  }): Promise<Uint8Array> {
+    // Verify the provided JWK represents a valid oct private key.
+    if (!isOctPrivateJwk(privateKey)) {
+      throw new Error(`XChaCha20Poly1305: The provided key is not a valid oct private key.`);
+    }
+
+    // Decode the provided private key to bytes.
+    const privateKeyBytes = Convert.base64Url(privateKey.k).toUint8Array();
+
+    return privateKeyBytes;
+  }
+}

package/src/primitives/xchacha20.ts

@@ -0,0 +1,247 @@
+import { Convert } from '@enbox/common';
+import { xchacha20 } from '@noble/ciphers/chacha';
+import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
+
+import type { Jwk } from '../jose/jwk.js';
+
+import { computeJwkThumbprint, isOctPrivateJwk } from '../jose/jwk.js';
+
+/**
+ * The `XChaCha20` class provides a comprehensive suite of utilities for cryptographic operations
+ * using the XChaCha20 symmetric encryption algorithm. This class includes methods for key
+ * generation, encryption, decryption, and conversions between raw byte arrays and JSON Web Key
+ * (JWK) formats. XChaCha20 is an extended nonce variant of ChaCha20, a stream cipher designed for
+ * high-speed encryption with substantial security margins.
+ *
+ * The XChaCha20 algorithm is particularly well-suited for encrypting large volumes of data or
+ * data streams, especially where random access is required. The class adheres to standard
+ * cryptographic practices, ensuring robustness and security in its implementations.
+ *
+ * Key Features:
+ * - Key Generation: Generate XChaCha20 symmetric keys in JWK format.
+ * - Key Conversion: Transform keys between raw byte arrays and JWK formats.
+ * - Encryption: Encrypt data using XChaCha20 with the provided symmetric key.
+ * - Decryption: Decrypt data encrypted with XChaCha20 using the corresponding symmetric key.
+ *
+ * The methods in this class are asynchronous, returning Promises to accommodate various
+ * JavaScript environments.
+ *
+ * @example
+ * ```ts
+ * // Key Generation
+ * const privateKey = await XChaCha20.generateKey();
+ *
+ * // Encryption
+ * const data = new TextEncoder().encode('Messsage');
+ * const nonce = utils.randomBytes(24); // 24-byte nonce for XChaCha20
+ * const encryptedData = await XChaCha20.encrypt({
+ *   data,
+ *   nonce,
+ *   key: privateKey
+ * });
+ *
+ * // Decryption
+ * const decryptedData = await XChaCha20.decrypt({
+ *   data: encryptedData,
+ *   nonce,
+ *   key: privateKey
+ * });
+ *
+ * // Key Conversion
+ * const privateKeyBytes = await XChaCha20.privateKeyToBytes({ privateKey });
+ * ```
+ */
+export class XChaCha20 {
+  /**
+   * Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method takes a symmetric key represented as a byte array (Uint8Array) and
+   * converts it into a JWK object for use with the XChaCha20 symmetric encryption algorithm. The
+   * conversion process involves encoding the key into base64url format and setting the appropriate
+   * JWK parameters.
+   *
+   * The resulting JWK object includes the following properties:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence (representing a symmetric key).
+   * - `k`: The symmetric key, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   *
+   * @example
+   * ```ts
+   * const privateKeyBytes = new Uint8Array([...]); // Replace with actual symmetric key bytes
+   * const privateKey = await XChaCha20.bytesToPrivateKey({ privateKeyBytes });
+   * ```
+   *
+   * @param params - The parameters for the symmetric key conversion.
+   * @param params.privateKeyBytes - The raw symmetric key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the symmetric key in JWK format.
+   */
+  public static async bytesToPrivateKey({ privateKeyBytes }: {
+    privateKeyBytes: Uint8Array;
+  }): Promise<Jwk> {
+    // Construct the private key in JWK format.
+    const privateKey: Jwk = {
+      k   : Convert.uint8Array(privateKeyBytes).toBase64Url(),
+      kty : 'oct'
+    };
+
+    // Compute the JWK thumbprint and set as the key ID.
+    privateKey.kid = await computeJwkThumbprint({ jwk: privateKey });
+
+    return privateKey;
+  }
+
+  /**
+   * Decrypts the provided data using XChaCha20.
+   *
+   * @remarks
+   * This method performs XChaCha20 decryption on the given encrypted data using the specified key
+   * and nonce. The nonce should be the same as used in the encryption process and must be 24 bytes
+   * long. The method returns the decrypted data as a Uint8Array.
+   *
+   * @example
+   * ```ts
+   * const encryptedData = new Uint8Array([...]); // Encrypted data
+   * const nonce = new Uint8Array(24); // 24-byte nonce used during encryption
+   * const key = { ... }; // A Jwk object representing the XChaCha20 key
+   * const decryptedData = await XChaCha20.decrypt({
+   *   data: encryptedData,
+   *   nonce,
+   *   key
+   * });
+   * ```
+   *
+   * @param params - The parameters for the decryption operation.
+   * @param params.data - The encrypted data to decrypt, represented as a Uint8Array.
+   * @param params.key - The key to use for decryption, represented in JWK format.
+   * @param params.nonce - The nonce used during the encryption process.
+   *
+   * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+   */
+  public static async decrypt({ data, key, nonce }: {
+    data: Uint8Array;
+    key: Jwk;
+    nonce: Uint8Array;
+  }): Promise<Uint8Array> {
+    // Convert the private key from JWK format to bytes.
+    const privateKeyBytes = await XChaCha20.privateKeyToBytes({ privateKey: key });
+
+    const ciphertext = xchacha20(privateKeyBytes, nonce, data);
+
+    return ciphertext;
+  }
+
+  /**
+   * Encrypts the provided data using XChaCha20.
+   *
+   * @remarks
+   * This method performs XChaCha20 encryption on the given data using the specified key and nonce.
+   * The nonce must be 24 bytes long, ensuring a high level of security through a vast nonce space,
+   * reducing the risks associated with nonce reuse. The method returns the encrypted data as a
+   * Uint8Array.
+   *
+   * @example
+   * ```ts
+   * const data = new TextEncoder().encode('Messsage');
+   * const nonce = utils.randomBytes(24); // 24-byte nonce for XChaCha20
+   * const key = { ... }; // A Jwk object representing an XChaCha20 key
+   * const encryptedData = await XChaCha20.encrypt({
+   *   data,
+   *   nonce,
+   *   key
+   * });
+   * ```
+   *
+   * @param params - The parameters for the encryption operation.
+   * @param params.data - The data to encrypt, represented as a Uint8Array.
+   * @param params.key - The key to use for encryption, represented in JWK format.
+   * @param params.nonce - A 24-byte nonce for the encryption process.
+   *
+   * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+   */
+  public static async encrypt({ data, key, nonce }: {
+    data: Uint8Array;
+    key: Jwk;
+    nonce: Uint8Array;
+  }): Promise<Uint8Array> {
+    // Convert the private key from JWK format to bytes.
+    const privateKeyBytes = await XChaCha20.privateKeyToBytes({ privateKey: key });
+
+    const plaintext = xchacha20(privateKeyBytes, nonce, data);
+
+    return plaintext;
+  }
+
+  /**
+   * Generates a symmetric key for XChaCha20 in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method creates a new symmetric key suitable for use with the XChaCha20 encryption
+   * algorithm. The key is generated using cryptographically secure random number generation
+   * to ensure its uniqueness and security. The XChaCha20 algorithm requires a 256-bit key
+   * (32 bytes), and this method adheres to that specification.
+   *
+   * Key components included in the JWK:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence.
+   * - `k`: The symmetric key component, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   *
+   * @example
+   * ```ts
+   * const privateKey = await XChaCha20.generateKey();
+   * ```
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public static async generateKey(): Promise<Jwk> {
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle();
+
+    // Generate a random private key.
+    // See https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues#usage_notes for
+    // an explanation for why Web Crypto generateKey() is used instead of getRandomValues().
+    const webCryptoKey = await webCrypto.generateKey( { name: 'AES-CTR', length: 256 }, true, ['encrypt']);
+
+    // Export the private key in JWK format.
+    const { alg, ext, key_ops, ...privateKey } = await webCrypto.exportKey('jwk', webCryptoKey);
+
+    // Compute the JWK thumbprint and set as the key ID.
+    privateKey.kid = await computeJwkThumbprint({ jwk: privateKey });
+
+    return privateKey;
+  }
+
+  /**
+   * Converts a private key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).
+   *
+   * @remarks
+   * This method takes a symmetric key in JWK format and extracts its raw byte representation.
+   * It decodes the 'k' parameter of the JWK value, which represents the symmetric key in base64url
+   * encoding, into a byte array.
+   *
+   * @example
+   * ```ts
+   * const privateKey = { ... }; // A symmetric key in JWK format
+   * const privateKeyBytes = await XChaCha20.privateKeyToBytes({ privateKey });
+   * ```
+   *
+   * @param params - The parameters for the symmetric key conversion.
+   * @param params.privateKey - The symmetric key in JWK format.
+   *
+   * @returns A Promise that resolves to the symmetric key as a Uint8Array.
+   */
+  public static async privateKeyToBytes({ privateKey }: {
+    privateKey: Jwk;
+  }): Promise<Uint8Array> {
+    // Verify the provided JWK represents a valid oct private key.
+    if (!isOctPrivateJwk(privateKey)) {
+      throw new Error(`XChaCha20: The provided key is not a valid oct private key.`);
+    }
+
+    // Decode the provided private key to bytes.
+    const privateKeyBytes = Convert.base64Url(privateKey.k).toUint8Array();
+
+    return privateKeyBytes;
+  }
+}

package/src/types/cipher.ts

@@ -0,0 +1,53 @@
+import type { EnclosedEncryptParams, EnclosedDecryptParams } from './params-enclosed.js';
+
+/**
+ * The `Cipher` interface provides methods for encrypting and decrypting data.
+ *
+ * It defines two core functions: `encrypt()` for converting plaintext to ciphertext using specific
+ * algorithm parameters, and `decrypt()` for the reverse process, turning ciphertext back into
+ * plaintext. These methods operate asynchronously and return promises that resolve to the processed
+ * data, whether encrypted or decrypted.
+ *
+ * The interface is designed to be flexible, accommodating various encryption algorithms and their
+ * unique parameters. It defaults to using {@link EnclosedEncryptParams | `EnclosedEncryptParams`}
+ * and {@link EnclosedDecryptParams | `EnclosedDecryptParams`}, which are intended to be used with
+ * a closure that captures the key and algorithm-specific parameters so that arbitrary data can be
+ * encrypted and decrypted without exposing the key or parameters to the caller. However, the
+ * interface can be extended to support other parameter types, such as {@link EncryptParams |
+ * `EncryptParams`} and {@link DecryptParams | `DecryptParams`}, which are intended to be used when
+ * the key and algorithm-specific parameters are known to the caller.
+ */
+export interface Cipher<
+  EncryptInput = EnclosedEncryptParams,
+  DecryptInput = EnclosedDecryptParams
+> {
+  /**
+   * Encrypts the provided data.
+   *
+   * @remarks
+   * The `encrypt()` method of the {@link Cipher |`Cipher`} interface encrypts data.
+   *
+   * It typically takes the data to encrypt (also known as "plaintext") and algorithm-specific
+   * parameters as input and returns the encrypted data (also known as "ciphertext").
+   *
+   * @param params - The parameters for the encryption operation.
+   *
+   * @returns A Promise which will be fulfilled with the encrypted data.
+   */
+  encrypt(params: EncryptInput): Promise<Uint8Array>;
+
+  /**
+   * Decrypts the provided data.
+   *
+   * @remarks
+   * The `decrypt()` method of the {@link Cipher |`Cipher`} interface decrypts encrypted data.
+   *
+   * It typically takes the data to decrypt (also known as "ciphertext") and algorithm-specific
+   * parameters as input and returns the decrypted data (also known as "plaintext").
+   *
+   * @param params - The parameters for the decryption operation.
+   *
+   * @returns A Promise which will be fulfilled with the decrypted data.
+   */
+  decrypt(params: DecryptInput): Promise<Uint8Array>;
+}

package/src/types/crypto-api.ts

@@ -0,0 +1,56 @@
+import type { Hasher } from './hasher.js';
+import type { Signer } from './signer.js';
+import type { KeyIdentifier } from './identifier.js';
+import type { AsymmetricKeyGenerator } from './key-generator.js';
+import type {
+  KmsSignParams,
+  KmsDigestParams,
+  KmsVerifyParams,
+  KmsGetKeyUriParams,
+  KmsGenerateKeyParams,
+  KmsGetPublicKeyParams,
+} from './params-kms.js';
+
+/**
+ * The `CryptoApi` 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.
+ *
+ * Concrete implementations of this interface are intended to be used with a KMS, which is
+ * responsible for generating and storing cryptographic keys. The KMS is also responsible for
+ * performing cryptographic operations using the keys it manages. The KMS is typically a cloud
+ * service, but it can also be a hardware device or software application.
+ *
+ * Guidelines for implementing this interface:
+ * - Must use JSON Web Keys ({@link Jwk | JWK}) as the key format.
+ * - Must IANA registered JSON Object Signing and Encryption
+ *   {@ link https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms | (JOSE)}
+ *   names for algorithm, curves, etc. whenever possible.
+ * - All I/O that interacts with private or secret keys must be done via reference using a
+ *   {@link KeyIdentifier | `KeyIdentifier`}. Implementations can use any string as the key
+ *   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
+ *   methods of Web5 libraries that involve key material (e.g., DID creation, VC signing, arbitrary
+ *   data signing/verification, etc.).
+ */
+export interface CryptoApi<
+  GenerateKeyInput = KmsGenerateKeyParams,
+  GenerateKeyOutput = KeyIdentifier,
+  GetPublicKeyInput = KmsGetPublicKeyParams,
+  DigestInput = KmsDigestParams,
+  SignInput = KmsSignParams,
+  VerifyInput = KmsVerifyParams
+> extends AsymmetricKeyGenerator<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput>,
+          Hasher<DigestInput>,
+          Signer<SignInput, VerifyInput> {
+  /**
+   *
+   * @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/hasher.ts

@@ -0,0 +1,32 @@
+/**
+ * The `Hasher` interface provides a method for generating digests of data using hash functions.
+ * It defines the core function `digest()` for processing variable-size input data to produce a
+ * fixed-size output (the "digest") which uniquely represents the input data.
+ *
+ * This method operates asynchronously and returns a digest, often used for data integrity checks.
+ * The interface can be implemented with various hash algorithms and their unique parameters.
+ *
+ * The interface is designed to accommodate byte array input data but can be extended to support
+ * other input types as needed.
+ */
+export interface Hasher<DigestInput> {
+  /**
+   * Generates a hash digest of the provided data.
+   *
+   * @remarks
+   * The `digest()` method of the {@link Hasher | `Hasher`} interface generates a hash digest of the
+   * input data.
+   *
+   * A digest is the output of the hash function. It's a fixed-size string of bytes
+   * that uniquely represents the data input into the hash function. The digest is often used for
+   * data integrity checks, as any alteration in the input data results in a significantly
+   * different digest.
+   *
+   * It typically takes the data to digest as input and returns the digest of the data.
+   *
+   * @param params - The parameters for the digest operation.
+   *
+   * @returns A Promise which will be fulfilled with the hash digest.
+   */
+  digest(params: DigestInput): Promise<Uint8Array>;
+}

package/src/types/identifier.ts

@@ -0,0 +1,16 @@
+/**
+ * Represents an identifier for a cryptographic algorithm.
+ *
+ * This is typically a string that specifies the name of the algorithm, such as 'ES256K', 'A256GCM',
+ * 'SHA-256', etc. It's used to refer to the specific algorithm in cryptographic operations.
+ */
+export type AlgorithmIdentifier = string;
+
+/**
+ * Denotes an identifier for a cryptographic key.
+ *
+ * It's a string used to uniquely identify a key within a given context, such as in key management
+ * systems (KMS) or cryptographic protocols. This identifier can be a simple string, a UUID, a URI,
+ * or any format chosen to suit the application's needs.
+ */
+export type KeyIdentifier = string;