@enbox/agent 0.0.1

package/dist/types/prototyping/crypto/primitives/aes-gcm.d.ts

@@ -0,0 +1,245 @@
+import type { Jwk } from '@enbox/crypto';
+/**
+ * Constant defining the AES key length values in bits.
+ *
+ * @remarks
+ * NIST publication FIPS 197 states:
+ * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt
+ * > and decrypt data in blocks of 128 bits.
+ *
+ * This implementation does not support key lengths that are different from the three values
+ * defined by this constant.
+ *
+ * @see {@link https://doi.org/10.6028/NIST.FIPS.197-upd1 | NIST FIPS 197}
+ */
+declare const AES_KEY_LENGTHS: readonly [128, 192, 256];
+/**
+ * Constant defining the AES-GCM tag length values in bits.
+ *
+ * @remarks
+ * NIST Special Publication 800-38D, Section 5.2.1.2 states that the tag length:
+ * > may be any one of the following five values: 128, 120, 112, 104, or 96
+ *
+ * Although the NIST specification allows for tag lengths of 32 or 64 bits in certain applications,
+ * the use of shorter tag lengths can be problematic for GCM due to targeted forgery attacks. As a
+ * precaution, this implementation does not support tag lengths that are different from the five
+ * values defined by this constant. See Appendix C of the NIST SP 800-38D specification for
+ * additional guidance and details.
+ *
+ * @see {@link https://doi.org/10.6028/NIST.SP.800-38D | NIST SP 800-38D}
+ */
+export declare const AES_GCM_TAG_LENGTHS: readonly [96, 104, 112, 120, 128];
+/**
+ * The `AesGcm` class provides a comprehensive set of utilities for cryptographic operations
+ * using the Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM). This class includes
+ * methods for key generation, encryption, decryption, and conversions between raw byte arrays
+ * and JSON Web Key (JWK) formats. It is designed to support AES-GCM, a symmetric key algorithm
+ * that is widely used for its efficiency, security, and provision of authenticated encryption.
+ *
+ * AES-GCM is particularly favored for scenarios that require both confidentiality and integrity
+ * of data. It integrates the counter mode of encryption with the Galois mode of authentication,
+ * offering high performance and parallel processing capabilities.
+ *
+ * Key Features:
+ * - Key Generation: Generate AES symmetric keys in JWK format.
+ * - Key Conversion: Transform keys between raw byte arrays and JWK formats.
+ * - Encryption: Encrypt data using AES-GCM with the provided symmetric key.
+ * - Decryption: Decrypt data encrypted with AES-GCM using the corresponding symmetric key.
+ *
+ * The methods in this class are asynchronous, returning Promises to accommodate various
+ * JavaScript environments.
+ *
+ * @example
+ * ```ts
+ * // Key Generation
+ * const length = 256; // Length of the key in bits (e.g., 128, 192, 256)
+ * const privateKey = await AesGcm.generateKey({ length });
+ *
+ * // Encryption
+ * const data = new TextEncoder().encode('Messsage');
+ * const iv = new Uint8Array(12); // 12-byte initialization vector
+ * const encryptedData = await AesGcm.encrypt({
+ *   data,
+ *   iv,
+ *   key: privateKey
+ * });
+ *
+ * // Decryption
+ * const decryptedData = await AesGcm.decrypt({
+ *   data: encryptedData,
+ *   iv,
+ *   key: privateKey
+ * });
+ *
+ * // Key Conversion
+ * const privateKeyBytes = await AesGcm.privateKeyToBytes({ privateKey });
+ * ```
+ */
+export declare class AesGcm {
+    /**
+   * Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method accepts a symmetric key represented as a byte array (Uint8Array) and
+   * converts it into a JWK object for use with AES-GCM (Advanced Encryption Standard -
+   * Galois/Counter Mode). 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 AesGcm.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.
+   */
+    static bytesToPrivateKey({ privateKeyBytes }: {
+        privateKeyBytes: Uint8Array;
+    }): Promise<Jwk>;
+    /**
+     * Decrypts the provided data using AES-GCM.
+     *
+     * @remarks
+     * This method performs AES-GCM decryption on the given encrypted data using the specified key.
+     * It requires an initialization vector (IV), the encrypted data along with the decryption key,
+     * and optionally, additional authenticated data (AAD). The method returns the decrypted data as a
+     * Uint8Array. The optional `tagLength` parameter specifies the size in bits of the authentication
+     * tag used when encrypting the data. If not specified, the default tag length of 128 bits is
+     * used.
+     *
+     * @example
+     * ```ts
+     * const encryptedData = new Uint8Array([...]); // Encrypted data
+     * const iv = new Uint8Array([...]); // Initialization vector used during encryption
+     * const additionalData = new Uint8Array([...]); // Optional additional authenticated data
+     * const key = { ... }; // A Jwk object representing the AES key
+     * const decryptedData = await AesGcm.decrypt({
+     *   data: encryptedData,
+     *   iv,
+     *   additionalData,
+     *   key,
+     *   tagLength: 128 // Optional tag length in bits
+     * });
+     * ```
+     *
+     * @param params - The parameters for the decryption operation.
+     * @param params.key - The key to use for decryption, represented in JWK format.
+     * @param params.data - The encrypted data to decrypt, represented as a Uint8Array.
+     * @param params.iv - The initialization vector, represented as a Uint8Array.
+     * @param params.additionalData - Optional additional authenticated data. Optional.
+     * @param params.tagLength - The length of the authentication tag in bits. Optional.
+     *
+     * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+     */
+    static decrypt({ key, data, iv, additionalData, tagLength }: {
+        key: Jwk;
+        data: Uint8Array;
+        iv: Uint8Array;
+        additionalData?: Uint8Array;
+        tagLength?: typeof AES_GCM_TAG_LENGTHS[number];
+    }): Promise<Uint8Array>;
+    /**
+     * Encrypts the provided data using AES-GCM.
+     *
+     * @remarks
+     * This method performs AES-GCM encryption on the given data using the specified key.
+     * It requires an initialization vector (IV), the encrypted data along with the decryption key,
+     * and optionally, additional authenticated data (AAD). The method returns the encrypted data as a
+     * Uint8Array. The optional `tagLength` parameter specifies the size in bits of the authentication
+     * tag generated in the encryption operation and used for authentication in the corresponding
+     * decryption. If not specified, the default tag length of 128 bits is used.
+     *
+     * @example
+     * ```ts
+     * const data = new TextEncoder().encode('Messsage');
+     * const iv = new Uint8Array([...]); // Initialization vector
+     * const additionalData = new Uint8Array([...]); // Optional additional authenticated data
+     * const key = { ... }; // A Jwk object representing an AES key
+     * const encryptedData = await AesGcm.encrypt({
+     *   data,
+     *   iv,
+     *   additionalData,
+     *   key,
+     *   tagLength: 128 // Optional tag length in bits
+     * });
+     * ```
+     *
+     * @param params - The parameters for the encryption operation.
+     * @param params.key - The key to use for encryption, represented in JWK format.
+     * @param params.data - The data to encrypt, represented as a Uint8Array.
+     * @param params.iv - The initialization vector, represented as a Uint8Array.
+     * @param params.additionalData - Optional additional authenticated data. Optional.
+     * @param params.tagLength - The length of the authentication tag in bits. Optional.
+     *
+     * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+     */
+    static encrypt({ data, iv, key, additionalData, tagLength }: {
+        key: Jwk;
+        data: Uint8Array;
+        iv: Uint8Array;
+        additionalData?: Uint8Array;
+        tagLength?: typeof AES_GCM_TAG_LENGTHS[number];
+    }): Promise<Uint8Array>;
+    /**
+     * Generates a symmetric key for AES in Galois/Counter Mode (GCM) in JSON Web Key (JWK) format.
+     *
+     * @remarks
+     * This method creates a new symmetric key of a specified length suitable for use with
+     * AES-GCM encryption. It leverages cryptographically secure random number generation
+     * to ensure the uniqueness and security of the key. The generated key adheres to the JWK
+     * format, facilitating compatibility with common cryptographic standards and ease of use
+     * in various cryptographic applications.
+     *
+     * The generated key includes these components:
+     * - `kty`: Key Type, set to 'oct' for Octet Sequence, indicating a symmetric key.
+     * - `k`: The symmetric key component, base64url-encoded.
+     * - `kid`: Key ID, generated based on the JWK thumbprint, providing a unique identifier.
+     *
+     * @example
+     * ```ts
+     * const length = 256; // Length of the key in bits (e.g., 128, 192, 256)
+     * const privateKey = await AesGcm.generateKey({ length });
+     * ```
+     *
+     * @param params - The parameters for the key generation.
+     * @param params.length - The length of the key in bits. Common lengths are 128, 192, and 256 bits.
+     *
+     * @returns A Promise that resolves to the generated symmetric key in JWK format.
+     */
+    static generateKey({ length }: {
+        length: typeof AES_KEY_LENGTHS[number];
+    }): Promise<Jwk>;
+    /**
+     * 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 focuses on the 'k' parameter of the JWK, which represents the symmetric key component
+     * in base64url encoding. The method decodes this value into a byte array, providing
+     * the symmetric key in its raw binary form.
+     *
+     * @example
+     * ```ts
+     * const privateKey = { ... }; // A symmetric key in JWK format
+     * const privateKeyBytes = await AesGcm.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.
+     */
+    static privateKeyToBytes({ privateKey }: {
+        privateKey: Jwk;
+    }): Promise<Uint8Array>;
+}
+export {};
+//# sourceMappingURL=aes-gcm.d.ts.map

package/dist/types/prototyping/crypto/primitives/aes-gcm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-gcm.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/primitives/aes-gcm.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAmBzC;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,eAAe,0BAA2B,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,mCAAoC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,MAAM;IACjB;;;;;;;;;;;;;;;;;;;;;;;;KAwBC;WACmB,iBAAiB,CAAC,EAAE,eAAe,EAAE,EAAE;QACzD,eAAe,EAAE,UAAU,CAAC;KAC7B,GAAG,OAAO,CAAC,GAAG,CAAC;IAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;WACiB,OAAO,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,EAAE;QACxE,GAAG,EAAE,GAAG,CAAC;QACT,IAAI,EAAE,UAAU,CAAC;QACjB,EAAE,EAAE,UAAU,CAAC;QACf,cAAc,CAAC,EAAE,UAAU,CAAC;QAC5B,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;KAChD,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;WACiB,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,EAAE;QACxE,GAAG,EAAE,GAAG,CAAC;QACT,IAAI,EAAE,UAAU,CAAC;QACjB,EAAE,EAAE,UAAU,CAAC;QACf,cAAc,CAAC,EAAE,UAAU,CAAC;QAC5B,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;KAChD,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BvB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACiB,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,EAAE,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;KACxC,GAAG,OAAO,CAAC,GAAG,CAAC;IAuBhB;;;;;;;;;;;;;;;;;;;OAmBG;WACiB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE;QACpD,UAAU,EAAE,GAAG,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,CAAC;CAWxB"}

package/dist/types/prototyping/crypto/primitives/aes-kw.d.ts

@@ -0,0 +1,103 @@
+import type { Jwk } from '@enbox/crypto';
+import type { UnwrapKeyParams, WrapKeyParams } from '../types/params-direct.js';
+/**
+ * Constant defining the AES key length values in bits.
+ *
+ * @remarks
+ * NIST publication FIPS 197 states:
+ * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt
+ * > and decrypt data in blocks of 128 bits.
+ *
+ * This implementation does not support key lengths that are different from the three values
+ * defined by this constant.
+ *
+ * @see {@link https://doi.org/10.6028/NIST.FIPS.197-upd1 | NIST FIPS 197}
+ */
+declare const AES_KEY_LENGTHS: readonly [128, 192, 256];
+export declare class AesKw {
+    /**
+     * 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 AES (Advanced Encryption Standard)
+     * for key wrapping. 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 AesKw.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.
+     */
+    static bytesToPrivateKey({ privateKeyBytes }: {
+        privateKeyBytes: Uint8Array;
+    }): Promise<Jwk>;
+    /**
+     * Generates a symmetric key for AES for key wrapping in JSON Web Key (JWK) format.
+     *
+     * @remarks
+     * This method creates a new symmetric key of a specified length suitable for use with
+     * AES key wrapping. It uses cryptographically secure random number generation to
+     * ensure the uniqueness and security of the key. The generated key adheres to the JWK
+     * format, making it compatible with common cryptographic standards and easy to use in
+     * various cryptographic processes.
+     *
+     * The generated key includes the following components:
+     * - `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.
+     * - `alg`: Algorithm, set to 'A128KW', 'A192KW', or 'A256KW' for AES Key Wrap with the
+     *   specified key length.
+     *
+     * @example
+     * ```ts
+     * const length = 256; // Length of the key in bits (e.g., 128, 192, 256)
+     * const privateKey = await AesKw.generateKey({ length });
+     * ```
+     *
+     * @param params - The parameters for the key generation.
+     * @param params.length - The length of the key in bits. Common lengths are 128, 192, and 256 bits.
+     *
+     * @returns A Promise that resolves to the generated symmetric key in JWK format.
+     */
+    static generateKey({ length }: {
+        length: typeof AES_KEY_LENGTHS[number];
+    }): Promise<Jwk>;
+    /**
+     * 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 AesKw.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.
+     */
+    static privateKeyToBytes({ privateKey }: {
+        privateKey: Jwk;
+    }): Promise<Uint8Array>;
+    static unwrapKey({ wrappedKeyBytes, wrappedKeyAlgorithm, decryptionKey }: UnwrapKeyParams): Promise<Jwk>;
+    static wrapKey({ unwrappedKey, encryptionKey }: WrapKeyParams): Promise<Uint8Array>;
+}
+export {};
+//# sourceMappingURL=aes-kw.d.ts.map

package/dist/types/prototyping/crypto/primitives/aes-kw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-kw.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/primitives/aes-kw.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAKzC,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAGhF;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,eAAe,0BAA2B,CAAC;AAEjD,qBAAa,KAAK;IAChB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACiB,iBAAiB,CAAC,EAAE,eAAe,EAAE,EAAE;QACzD,eAAe,EAAE,UAAU,CAAC;KAC7B,GAAG,OAAO,CAAC,GAAG,CAAC;IAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;WACiB,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,EAAE,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;KACxC,GAAG,OAAO,CAAC,GAAG,CAAC;IAuBhB;;;;;;;;;;;;;;;;;;OAkBG;WACiB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE;QACpD,UAAU,EAAE,GAAG,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,CAAC;WAYH,SAAS,CAAC,EAAE,eAAe,EAAE,mBAAmB,EAAE,aAAa,EAAE,EACnF,eAAe,GACd,OAAO,CAAC,GAAG,CAAC;WAoDK,OAAO,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,EACzD,aAAa,GACZ,OAAO,CAAC,UAAU,CAAC;CAyDvB"}

package/dist/types/prototyping/crypto/primitives/hkdf.d.ts

@@ -0,0 +1,90 @@
+import { DeriveKeyBytesParams } from '../types/params-direct.js';
+/**
+ * The object that should be passed into `Hkdf.deriveKey()`, when using the HKDF algorithm.
+ */
+export type HkdfParams = {
+    /**
+     * A string representing the digest algorithm to use. This may be one of:
+     * - 'SHA-256'
+     * - 'SHA-384'
+     * - 'SHA-512'
+     */
+    hash: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /**
+     * The salt value to use in the derivation process.
+     *
+     * Ideally, the salt is a random or pseudo-random value with the same length as the output of the
+     * digest function. Unlike the input key material passed into deriveKey(), salt does not need to
+     * be kept secret.
+     *
+     * Note: The {@link https://datatracker.ietf.org/doc/html/rfc5869 | HKDF specification} states
+     *       that adding salt "adds significantly to the strength of HKDF".
+     */
+    salt: string | Uint8Array;
+    /**
+     * Optional application-specific information to use in the HKDF.
+     *
+     * If given, this value is used to bind the derived key to application-specific contextual
+     * information. This makes it possible to derive different keys for different contexts while using
+     * the same input key material.
+     *
+     * If not provided, the `info` value is set to an empty array.
+     *
+     * Note: It is important that the `info` value be independent and unrelated to the input key
+     * material.
+     */
+    info?: string | Uint8Array;
+};
+/**
+ * The `Hkdf` class provides an interface for HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
+ * as defined in RFC 5869.
+ *
+ * Note: The `baseKeyBytes` that will be the input key material for HKDF should be a high-entropy secret
+ * value, such as a cryptographic key. It should be kept confidential and not be derived from a
+ * low-entropy value, such as a password.
+ *
+ * @example
+ * ```ts
+ * const info = new Uint8Array([...]);
+ * const derivedKeyBytes = await Hkdf.deriveKeyBytes({
+ *   baseKeyBytes: new Uint8Array([...]), // Input keying material
+ *   hash: 'SHA-256', // The hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
+ *   salt: new Uint8Array([...]), // The salt value
+ *   info: new Uint8Array([...]), // Optional application-specific information
+ *   length: 256 // The length of the derived key in bits
+ * });
+ * ```
+ */
+export declare class Hkdf {
+    /**
+     * Derives a key using the HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
+     *
+     * This method generates a derived key using a hash function from input keying material given as
+     * `baseKeyBytes`. The length of the derived key can be specified. Optionally, it can also use a salt
+     * and info for the derivation process.
+     *
+     * HKDF is useful in various cryptographic applications and protocols, especially when
+     * there's a need to derive multiple keys from a single source of key material.
+     *
+     * Note: The `baseKeyBytes` that will be the input key material for HKDF should be a high-entropy
+     * secret value, such as a cryptographic key. It should be kept confidential and not be derived
+     * from a low-entropy value, such as a password.
+     *
+     * @example
+     * ```ts
+     * const info = new Uint8Array([...]);
+     * const derivedKeyBytes = await Hkdf.deriveKeyBytes({
+     *   baseKeyBytes: new Uint8Array([...]), // Input keying material
+     *   hash: 'SHA-256', // The hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
+     *   salt: new Uint8Array([...]), // The salt value
+     *   info: new Uint8Array([...]), // Optional application-specific information
+     *   length: 256 // The length of the derived key in bits
+     * });
+     * ```
+     *
+     * @param params - The parameters for key derivation.
+     * @returns A Promise that resolves to the derived key as a byte array.
+     */
+    static deriveKeyBytes({ baseKeyBytes, length, hash, salt, info }: DeriveKeyBytesParams & HkdfParams): Promise<Uint8Array>;
+}
+//# sourceMappingURL=hkdf.d.ts.map

package/dist/types/prototyping/crypto/primitives/hkdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hkdf.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/primitives/hkdf.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAExC;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,IAAI;IACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;WACiB,cAAc,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAuB,EAAE,EAC9F,oBAAoB,GAAG,UAAU,GAChC,OAAO,CAAC,UAAU,CAAC;CAuBvB"}

package/dist/types/prototyping/crypto/primitives/pbkdf2.d.ts

@@ -0,0 +1,84 @@
+import type { DeriveKeyBytesParams } from '../types/params-direct.js';
+/**
+ * The object that should be passed into `Pbkdf2.deriveKeyBytes()`, when using the PBKDF2 algorithm.
+ */
+export interface Pbkdf2Params {
+    /**
+     * A string representing the digest algorithm to use. This may be one of:
+     * - 'SHA-256'
+     * - 'SHA-384'
+     * - 'SHA-512'
+     */
+    hash: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /**
+     * The salt value to use in the derivation process, as a Uint8Array. This should be a random or
+     * pseudo-random value of at least 16 bytes. Unlike the `password`, `salt` does not need to be
+     * kept secret.
+     */
+    salt: Uint8Array;
+    /**
+     * A `Number` representing the number of iterations the hash function will be executed in
+     * `deriveKey()`. This impacts the computational cost of the `deriveKey()` operation, making it
+     * more resistant to dictionary attacks. The higher the number, the more secure, but also slower,
+     * the operation. Choose a value that balances security needs and performance for your
+     * application.
+     */
+    iterations: number;
+}
+/**
+ * The `Pbkdf2` class provides a secure way to derive cryptographic keys from a password
+ * using the PBKDF2 (Password-Based Key Derivation Function 2) algorithm.
+ *
+ * The PBKDF2 algorithm is widely used for generating keys from passwords, as it applies
+ * a pseudorandom function to the input password along with a salt value and iterates the
+ * process multiple times to increase the key's resistance to brute-force attacks.
+ *
+ * Notes:
+ * - The `baseKeyBytes` that will be the input key material for PBKDF2 is expected to be a low-entropy
+ *   value, such as a password or passphrase. It should be kept confidential.
+ * - In 2023, {@link https://web.archive.org/web/20230123232056/https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2 | OWASP recommended}
+ *   a minimum of 600,000 iterations for PBKDF2-HMAC-SHA256 and 210,000 for PBKDF2-HMAC-SHA512.
+ *
+ * @example
+ * ```ts
+ * // Key Derivation
+ * const derivedKeyBytes = await Pbkdf2.deriveKeyBytes({
+ *   baseKeyBytes: new TextEncoder().encode('password'), // The password as a Uint8Array
+ *   hash: 'SHA-256', // The hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
+ *   salt: new Uint8Array([...]), // The salt value
+ *   iterations: 600_000, // The number of iterations
+ *   length: 256 // The length of the derived key in bits
+ * });
+ * ```
+ *
+ * @remarks
+ * This class relies on the availability of the Web Crypto API.
+ */
+export declare class Pbkdf2 {
+    /**
+     * Derives a cryptographic key from a password using the PBKDF2 algorithm.
+     *
+     * @remarks
+     * This method applies the PBKDF2 algorithm to the provided password along with
+     * a salt value and iterates the process a specified number of times. It uses
+     * a cryptographic hash function to enhance security and produce a key of the
+     * desired length. The method is capable of utilizing either the Web Crypto API
+     * or the Node.js Crypto module, depending on the environment's support.
+     *
+     * @example
+     * ```ts
+     * const derivedKeyBytes = await Pbkdf2.deriveKeyBytes({
+     *   baseKeyBytes: new TextEncoder().encode('password'), // The password as a Uint8Array
+     *   hash: 'SHA-256', // The hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
+     *   salt: new Uint8Array([...]), // The salt value
+     *   iterations: 600_000, // The number of iterations
+     *   length: 256 // The length of the derived key in bits
+     * });
+     * ```
+     *
+     * @param params - The parameters for key derivation.
+     * @returns A Promise that resolves to the derived key as a byte array.
+     */
+    static deriveKeyBytes({ baseKeyBytes, hash, salt, iterations, length }: DeriveKeyBytesParams & Pbkdf2Params): Promise<Uint8Array>;
+}
+//# sourceMappingURL=pbkdf2.d.ts.map

package/dist/types/prototyping/crypto/primitives/pbkdf2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbkdf2.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/primitives/pbkdf2.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAExC;;;;OAIG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,MAAM;IACjB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;WACiB,cAAc,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,EACjF,oBAAoB,GAAG,YAAY,GAClC,OAAO,CAAC,UAAU,CAAC;CAyBvB"}

package/dist/types/prototyping/crypto/types/cipher.d.ts

@@ -0,0 +1,14 @@
+export type InferCipherAlgorithm<T> = T extends {
+    /**
+     * The `encrypt` method signature from which the algorithm type is inferred.
+     * This is an internal implementation detail and not part of the public API.
+     */
+    encrypt(params: infer P): any;
+} ? P extends {
+    /**
+     * The `algorithm` property within the parameters of `encrypt`.
+     * This internal element is used to infer the algorithm type.
+     */
+    algorithm: infer A;
+} ? A : never : never;
+//# sourceMappingURL=cipher.d.ts.map

package/dist/types/prototyping/crypto/types/cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/types/cipher.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,SAAS;IAC9C;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC;CAC/B,GACC,CAAC,SAAS;IACR;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,CAAA;CACnB,GACC,CAAC,GACD,KAAK,GACP,KAAK,CAAC"}

package/dist/types/prototyping/crypto/types/crypto-api.d.ts

@@ -0,0 +1,35 @@
+import type { Jwk, CryptoApi as OldCryptoApi, KeyWrapper, SignParams, DigestParams, VerifyParams, GenerateKeyParams, GetPublicKeyParams, Cipher } from '@enbox/crypto';
+import type { KeyConverter } from './key-converter.js';
+import type { AsymmetricKeyConverter } from './key-converter.js';
+import type { KeyBytesDeriver, KeyDeriver } from './key-deriver.js';
+import type { BytesToPrivateKeyParams, BytesToPublicKeyParams, CipherParams, DeriveKeyBytesParams, DeriveKeyParams, PrivateKeyToBytesParams, PublicKeyToBytesParams, UnwrapKeyParams, WrapKeyParams } from './params-direct.js';
+/**
+ * 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.
+ *
+ * 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 `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 DsaApi<GenerateKeyInput = GenerateKeyParams, GenerateKeyOutput = Jwk, GetPublicKeyInput = GetPublicKeyParams, DigestInput = DigestParams, SignInput = SignParams, VerifyInput = VerifyParams> extends OldCryptoApi<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput, DigestInput, SignInput, VerifyInput> {
+}
+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 = DeriveKeyParams, DeriveKeyOutput = Jwk, DeriveKeyBytesInput = DeriveKeyBytesParams, DeriveKeyBytesOutput = Uint8Array, WrapKeyInput = WrapKeyParams, UnwrapKeyInput = UnwrapKeyParams> extends DsaApi<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput, DigestInput, SignInput, VerifyInput>, Cipher<EncryptInput, DecryptInput>, AsymmetricKeyConverter<BytesToPublicKeyInput, PublicKeyToBytesInput>, KeyConverter<BytesToPrivateKeyInput, PrivateKeyToBytesInput>, KeyDeriver<DeriveKeyInput, DeriveKeyOutput>, KeyBytesDeriver<DeriveKeyBytesInput, DeriveKeyBytesOutput>, KeyWrapper<WrapKeyInput, UnwrapKeyInput> {
+}
+//# sourceMappingURL=crypto-api.d.ts.map

package/dist/types/prototyping/crypto/types/crypto-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-api.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/types/crypto-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,GAAG,EACH,SAAS,IAAI,YAAY,EACzB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,EACP,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEhO;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,MAAM,CACrB,gBAAgB,GAAG,iBAAiB,EACpC,iBAAiB,GAAG,GAAG,EACvB,iBAAiB,GAAG,kBAAkB,EACtC,WAAW,GAAG,YAAY,EAC1B,SAAS,GAAG,UAAU,EACtB,WAAW,GAAG,YAAY,CAC1B,SAAQ,YAAY,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC;CAAG;AAEtH,MAAM,WAAW,SAAS,CACxB,gBAAgB,GAAG,iBAAiB,EACpC,iBAAiB,GAAG,GAAG,EACvB,iBAAiB,GAAG,kBAAkB,EACtC,WAAW,GAAG,YAAY,EAC1B,SAAS,GAAG,UAAU,EACtB,WAAW,GAAG,YAAY,EAC1B,YAAY,GAAG,YAAY,EAC3B,YAAY,GAAG,YAAY,EAC3B,qBAAqB,GAAG,sBAAsB,EAC9C,qBAAqB,GAAG,sBAAsB,EAC9C,sBAAsB,GAAG,uBAAuB,EAChD,sBAAsB,GAAG,uBAAuB,EAChD,cAAc,GAAG,eAAe,EAChC,eAAe,GAAG,GAAG,EACrB,mBAAmB,GAAG,oBAAoB,EAC1C,oBAAoB,GAAG,UAAU,EACjC,YAAY,GAAG,aAAa,EAC5B,cAAc,GAAG,eAAe,CAChC,SACA,MAAM,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC,EACnG,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,EAClC,sBAAsB,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,EACpE,YAAY,CAAC,sBAAsB,EAAE,sBAAsB,CAAC,EAC5D,UAAU,CAAC,cAAc,EAAE,eAAe,CAAC,EAC3C,eAAe,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,EAC1D,UAAU,CAAC,YAAY,EAAE,cAAc,CAAC;CAAG"}

package/dist/types/prototyping/crypto/types/key-converter.d.ts

@@ -0,0 +1,49 @@
+import type { Jwk } from '@enbox/crypto';
+/**
+ * `KeyConverter` interface for converting private keys between byte array and JWK formats.
+ */
+export interface KeyConverter<BytesToPrivateKeyInput, PrivateKeyToBytesInput> {
+    /**
+     * Converts a private key from a byte array to JWK format.
+     *
+     * @param params - The parameters for the private key conversion.
+     * @param params.privateKeyBytes - The raw private key as a Uint8Array.
+     *
+     * @returns A Promise that resolves to the private key in JWK format.
+     */
+    bytesToPrivateKey(params: BytesToPrivateKeyInput): Promise<Jwk>;
+    /**
+     * 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.
+     */
+    privateKeyToBytes(params: PrivateKeyToBytesInput): Promise<Uint8Array>;
+}
+/**
+ * `AsymmetricKeyConverter` interface extends {@link KeyConverter |`KeyConverter`}, adding support
+ * for public key conversions.
+ */
+export interface AsymmetricKeyConverter<BytesToPublicKeyInput, PublicKeyToBytesInput> {
+    /**
+     * Converts a public key from a byte array to JWK format.
+     *
+     * @param params - The parameters for the public key conversion.
+     * @param params.publicKeyBytes - The raw public key as a Uint8Array.
+     *
+     * @returns A Promise that resolves to the public key in JWK format.
+     */
+    bytesToPublicKey(params: BytesToPublicKeyInput): Promise<Jwk>;
+    /**
+     * Converts a public key from JWK format to a byte array.
+     *
+     * @param params - The parameters for the public key conversion.
+     * @param params.publicKey - The public key in JWK format.
+     *
+     * @returns A Promise that resolves to the public key as a Uint8Array.
+     */
+    publicKeyToBytes(params: PublicKeyToBytesInput): Promise<Uint8Array>;
+}
+//# sourceMappingURL=key-converter.d.ts.map

package/dist/types/prototyping/crypto/types/key-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-converter.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/types/key-converter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,sBAAsB,EAAE,sBAAsB;IAE1E;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEhE;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,qBAAqB,EAAE,qBAAqB;IAClF;;;;;;;OAOG;IACH,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE9D;;;;;;;OAOG;IACH,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtE"}