@enbox/crypto 0.0.1

package/dist/types/primitives/xchacha20.d.ts

@@ -0,0 +1,186 @@
+import type { Jwk } 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 declare 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.
+     */
+    static bytesToPrivateKey({ privateKeyBytes }: {
+        privateKeyBytes: Uint8Array;
+    }): Promise<Jwk>;
+    /**
+     * 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.
+     */
+    static decrypt({ data, key, nonce }: {
+        data: Uint8Array;
+        key: Jwk;
+        nonce: Uint8Array;
+    }): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    static encrypt({ data, key, nonce }: {
+        data: Uint8Array;
+        key: Jwk;
+        nonce: Uint8Array;
+    }): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    static generateKey(): 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 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.
+     */
+    static privateKeyToBytes({ privateKey }: {
+        privateKey: Jwk;
+    }): Promise<Uint8Array>;
+}
+//# sourceMappingURL=xchacha20.d.ts.map

package/dist/types/primitives/xchacha20.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xchacha20.d.ts","sourceRoot":"","sources":["../../../src/primitives/xchacha20.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACiB,iBAAiB,CAAC,EAAE,eAAe,EAAE,EAAE;QACzD,eAAe,EAAE,UAAU,CAAC;KAC7B,GAAG,OAAO,CAAC,GAAG,CAAC;IAahB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;WACiB,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAChD,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC;QACT,KAAK,EAAE,UAAU,CAAC;KACnB,GAAG,OAAO,CAAC,UAAU,CAAC;IASvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;WACiB,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAChD,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC;QACT,KAAK,EAAE,UAAU,CAAC;KACnB,GAAG,OAAO,CAAC,UAAU,CAAC;IASvB;;;;;;;;;;;;;;;;;;;;OAoBG;WACiB,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC;IAkB/C;;;;;;;;;;;;;;;;;;OAkBG;WACiB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE;QACpD,UAAU,EAAE,GAAG,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,CAAC;CAWxB"}

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

@@ -0,0 +1,49 @@
+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>;
+}
+//# sourceMappingURL=cipher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cipher.d.ts","sourceRoot":"","sources":["../../../src/types/cipher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEzF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,MAAM,CACrB,YAAY,GAAG,qBAAqB,EACpC,YAAY,GAAG,qBAAqB;IAEpC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEnD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACpD"}

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

@@ -0,0 +1,40 @@
+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>;
+}
+//# sourceMappingURL=crypto-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-api.d.ts","sourceRoot":"","sources":["../../../src/types/crypto-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,SAAS,CACxB,gBAAgB,GAAG,oBAAoB,EACvC,iBAAiB,GAAG,aAAa,EACjC,iBAAiB,GAAG,qBAAqB,EACzC,WAAW,GAAG,eAAe,EAC7B,SAAS,GAAG,aAAa,EACzB,WAAW,GAAG,eAAe,CAC7B,SAAQ,sBAAsB,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,CAAC,EAC9E,MAAM,CAAC,WAAW,CAAC,EACnB,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC/D"}

package/dist/types/types/hasher.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=hasher.d.ts.map

package/dist/types/types/hasher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasher.d.ts","sourceRoot":"","sources":["../../../src/types/hasher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,MAAM,CAAC,WAAW;IACjC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAClD"}

package/dist/types/types/identifier.d.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;
+//# sourceMappingURL=identifier.d.ts.map

package/dist/types/types/identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.d.ts","sourceRoot":"","sources":["../../../src/types/identifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC"}

package/dist/types/types/key-compressor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `KeyCompressor` interface for converting public keys between compressed and uncompressed form.
+ */
+export interface KeyCompressor {
+    /**
+     * Converts a public key to its compressed form.
+     *
+     * @param params - The parameters for the public key compression.
+     * @param params.publicKeyBytes - The public key as a Uint8Array.
+     *
+     * @returns A Promise that resolves to the compressed public key as a Uint8Array.
+     */
+    compressPublicKey(params: {
+        publicKeyBytes: Uint8Array;
+    }): Promise<Uint8Array>;
+    /**
+     * Converts a public key to its uncompressed form.
+     *
+     * @param params - The parameters for the public key decompression.
+     * @param params.publicKeyBytes - The public key as a Uint8Array.
+     *
+     * @returns A Promise that resolves to the uncompressed public key as a Uint8Array.
+     */
+    decompressPublicKey(params: {
+        publicKeyBytes: Uint8Array;
+    }): Promise<Uint8Array>;
+}
+//# sourceMappingURL=key-compressor.d.ts.map

package/dist/types/types/key-compressor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-compressor.d.ts","sourceRoot":"","sources":["../../../src/types/key-compressor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAE5B;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/E;;;;;;;OAOG;IACH,mBAAmB,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAClF"}

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

@@ -0,0 +1,57 @@
+import type { Jwk } from '../jose/jwk.js';
+/**
+ * `KeyConverter` interface for converting private keys between byte array and JWK formats.
+ */
+export interface KeyConverter {
+    /**
+     * 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: {
+        privateKeyBytes: Uint8Array;
+    }): 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: {
+        privateKey: Jwk;
+    }): Promise<Uint8Array>;
+}
+/**
+ * `AsymmetricKeyConverter` interface extends {@link KeyConverter |`KeyConverter`}, adding support
+ * for public key conversions.
+ */
+export interface AsymmetricKeyConverter extends KeyConverter {
+    /**
+     * 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: {
+        publicKeyBytes: Uint8Array;
+    }): 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: {
+        publicKey: Jwk;
+    }): Promise<Uint8Array>;
+}
+//# sourceMappingURL=key-converter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"key-converter.d.ts","sourceRoot":"","sources":["../../../src/types/key-converter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,YAAY;IAE3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE;QAAE,eAAe,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzE;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrE;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D;;;;;;;OAOG;IACH,gBAAgB,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvE;;;;;;;OAOG;IACH,gBAAgB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE"}

package/dist/types/types/key-deriver.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The `KeyDeriver` interface provides methods for key derivation. It includes the methods
+ * `deriveBits()` to derive cryptographic bits and `deriveKey()` to derive JWK keys from input data
+ * using specific algorithms. This interface is designed to support various key derivation
+ * algorithms, accommodating different input and output types.
+ *
+ * Both methods return a Promise that resolves to the derived cryptographic material.
+ */
+export interface KeyDeriver<DeriveBitsInput, DeriveKeyInput, DeriveKeyOutput> {
+    /**
+     * Generates a specified number of cryptographic bits from given input parameters.
+     *
+     * @remarks
+     * The `deriveBits()` method of the {@link KeyDeriver | `KeyDeriver`} 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 bit derivation process, specific to the chosen algorithm.
+     *
+     * @returns A Promise resolving to the derived bits as a `Uint8Array`.
+     */
+    deriveBits(params: DeriveBitsInput): Promise<Uint8Array>;
+    /**
+     * Derives a cryptographic key in JWK format based on the provided input parameters.
+     *
+     * @remarks
+     * The `deriveKey()` method of the {@link KeyDeriver | `KeyDeriver`} interface is utilized to
+     * generate cryptographic keys for operations like encryption, decryption, or signing. The method
+     * takes in parameters tailored to the key derivation algorithm being used and returns a promise
+     * that resolves to the derived key.
+     *
+     * @param params - The parameters for the key derivation process, customized for the specific algorithm.
+     *
+     * @returns A Promise resolving to the derived key in the specified output format.
+     */
+    deriveKey(params: DeriveKeyInput): Promise<DeriveKeyOutput>;
+}
+//# sourceMappingURL=key-deriver.d.ts.map

package/dist/types/types/key-deriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-deriver.d.ts","sourceRoot":"","sources":["../../../src/types/key-deriver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CACzB,eAAe,EACf,cAAc,EACd,eAAe;IAEf;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEzD;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7D"}

package/dist/types/types/key-generator.d.ts

@@ -0,0 +1,105 @@
+import type { Jwk } from '../jose/jwk.js';
+/**
+ * The `KeyGenerator` interface provides a method for cryptographic key generation. It includes
+ * the `generateKey()` method to produce keys for cryptographic operations, supporting various
+ * algorithms and configurations. This interface is adaptable to different key generation
+ * requirements and can produce keys in formats such as JWK.
+ *
+ * The method returns a Promise that resolves to the generated key in the specified format.
+ */
+export interface KeyGenerator<GenerateKeyInput, GenerateKeyOutput> {
+    /**
+     * Generates a cryptographic key based on the provided parameters.
+     *
+     * @remarks
+     * The `generateKey()` method of the {@link KeyGenerator | `KeyGenerator`} interface generates
+     * private keys suitable for various cryptographic operations. This method can adapt to different
+     * key generation algorithms and input parameters.
+     *
+     * @param params - Optional parameters for the key generation process, specific to the chosen
+     *                 algorithm.
+     *
+     * @returns A Promise resolving to the generated private key in the specified output format.
+     */
+    generateKey(params?: GenerateKeyInput): Promise<GenerateKeyOutput>;
+}
+/**
+ * The `AsymmetricKeyGenerator` interface extends {@link KeyGenerator | `KeyGenerator`}, adding
+ * methods specific to asymmetric public keys. It supports generating asymmetric private keys and
+ * obtaining the public key from a private key.
+ *
+ * This interface is designed for asymmetric cryptographic operations where both public and private
+ * keys are used.
+ */
+export interface AsymmetricKeyGenerator<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput> extends KeyGenerator<GenerateKeyInput, GenerateKeyOutput> {
+    /**
+     * Optional method that mathetmatically derives the public key in JWK format from a given private
+     * key.
+     *
+     * @param params - The parameters for public key computation.
+     *
+     * @returns A Promise resolving to the public key in JWK format.
+     */
+    computePublicKey?(params: GetPublicKeyInput): Promise<Jwk>;
+    /**
+     * Extracts the public key portion from the given public key in JWK format.
+     *
+     * @remarks
+     * Unlike `computePublicKey()`, the `getPublicKey()` method does not mathematically validate the
+     * private key, nor does it derive the public key from the private key. It simply extracts
+     * existing public key properties from the private key JWK object. This makes it suitable for
+     * scenarios where speed is critical and the private key's integrity is already assured.
+     *
+     * @param params - The parameters for public key retrieval.
+     *
+     * @returns A Promise resolving to the public key in JWK format.
+     */
+    getPublicKey(params: GetPublicKeyInput): Promise<Jwk>;
+}
+/**
+ * Infers the supported algorithm type from the `generateKey` method of a key generator.
+ *
+ * @remarks
+ * The `InferKeyGeneratorAlgorithm` utility type extracts the algorithm type from the input
+ * parameters of the `generateKey` method implemented in a key generator. This type is useful when
+ * working with various cryptographic key generators, as it enables TypeScript to infer the
+ * supported algorithms based on the key generator's implementation. This inference ensures type
+ * safety and improves developer experience by providing relevant suggestions and checks for the
+ * supported algorithms during development.
+ *
+ * This utility type can be particularly advantageous in contexts where the specific key generator
+ * may vary, but the code needs to adapt dynamically based on the supported algorithms of the
+ * provided key generator instance.
+ *
+ * @example
+ * ```ts
+ * export interface MyKmsGenerateKeyParams extends KmsGenerateKeyParams {
+ *  algorithm: 'Ed25519' | 'secp256k1';
+ * }
+ *
+ * class MyKms implements KeyGenerator<MyKmsGenerateKeyParams, Jwk> {
+ *   generateKey(params: MyKmsGenerateKeyParams): Promise<Jwk> {
+ *     // Implementation for generating a key...
+ *   }
+ * }
+ *
+ * type SupportedAlgorithms = InferKeyGeneratorAlgorithm<MyKms>;
+ * // `SupportedAlgorithms` will be inferred as 'Ed25519' | 'secp256k1'
+ * ```
+ *
+ * @template T - The type of the key generator from which to infer the algorithm type.
+ */
+export type InferKeyGeneratorAlgorithm<T> = T extends {
+    /**
+     * The `generateKey` method signature from which the algorithm type is inferred.
+     * This is an internal implementation detail and not part of the public API.
+     */
+    generateKey(params: infer P): any;
+} ? P extends {
+    /**
+     * The `algorithm` property within the parameters of `generateKey`.
+     * This internal element is used to infer the algorithm type.
+     */
+    algorithm: infer A;
+} ? A : never : never;
+//# sourceMappingURL=key-generator.d.ts.map

package/dist/types/types/key-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-generator.d.ts","sourceRoot":"","sources":["../../../src/types/key-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAC3B,gBAAgB,EAChB,iBAAiB;IAEjB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB,CACrC,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,CACjB,SAAQ,YAAY,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IACzD;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE3D;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI,CAAC,SAAS;IAClD;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC;CACnC,GACC,CAAC,SAAS;IACR;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,CAAA;CACnB,GACC,CAAC,GACD,KAAK,GACP,KAAK,CAAC"}

package/dist/types/types/key-io.d.ts

@@ -0,0 +1,37 @@
+import type { Jwk } from '../jose/jwk.js';
+/**
+ * The `KeyImporterExporter` interface provides methods for importing and exporting cryptographic
+ * keys. It includes `importKey()` for importing external keys, and `exportKey()` for exporting a
+ * cryptographic key to an external JWK object.
+ *
+ * This interface is designed to handle various key formats and is adaptable for different
+ * cryptographic environments and requirements.
+ */
+export interface KeyImporterExporter<ImportKeyInput, ImportKeyOutput, ExportKeyInput> {
+    /**
+     * Exports a cryptographic key to an external JWK object.
+     *
+     * @remarks
+     * The `exportKey()` method of the {@link KeyImporterExporter | `KeyImporterExporter`} interface
+     * returns a cryptographic key in JWK format, facilitating interoperability and backup.
+     *
+     * @param params - The parameters for the key export operation.
+     *
+     * @returns A Promise resolving to the exported key in JWK format.
+     */
+    exportKey(params: ExportKeyInput): Promise<Jwk>;
+    /**
+     * Imports an external key in JWK format.
+     *
+     * @remarks
+     * The `importKey()` method of the {@link KeyImporterExporter | `KeyImporterExporter`} interface
+     * takes as input an external key in JWK format and typically returns a key identifier reference
+     * for the imported key.
+     *
+     * @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>;
+}
+//# sourceMappingURL=key-io.d.ts.map

package/dist/types/types/key-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-io.d.ts","sourceRoot":"","sources":["../../../src/types/key-io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB,CAClC,cAAc,EACd,eAAe,EACf,cAAc;IAEd;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEhD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7D"}