@enbox/crypto 0.0.1

package/dist/esm/utils.js

@@ -0,0 +1,165 @@
+import { crypto } from '@noble/hashes/crypto';
+import { randomBytes as nobleRandomBytes } from '@noble/hashes/utils';
+/**
+ * A collection of cryptographic utility methods.
+ */
+export class CryptoUtils {
+    /**
+     * Determines the JOSE algorithm identifier of the digital signature algorithm based on the `alg` or
+     * `crv` property of a {@link Jwk | JWK}.
+     *
+     * If the `alg` property is present, its value takes precedence and is returned. Otherwise, the
+     * `crv` property is used to determine the algorithm.
+     *
+     * @memberof CryptoUtils
+     * @see {@link https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms | JOSE Algorithms}
+     * @see {@link https://datatracker.ietf.org/doc/draft-ietf-jose-fully-specified-algorithms/ | Fully-Specified Algorithms for JOSE and COSE}
+     *
+     * @example
+     * ```ts
+     * const publicKey: Jwk = {
+     *   "kty": "OKP",
+     *   "crv": "Ed25519",
+     *   "x": "FEJG7OakZi500EydXxuE8uMc8uaAzEJkmQeG8khXANw"
+     * }
+     * const algorithm = getJoseSignatureAlgorithmFromPublicKey(publicKey);
+     * console.log(algorithm); // Output: "EdDSA"
+     * ```
+     * @param publicKey - A JWK containing the `alg` and/or `crv` properties.
+     * @returns The name of the algorithm associated with the key.
+     * @throws Error if the algorithm cannot be determined from the provided input.
+     */
+    static getJoseSignatureAlgorithmFromPublicKey(publicKey) {
+        const curveToJoseAlgorithm = {
+            'Ed25519': 'EdDSA',
+            'P-256': 'ES256',
+            'P-384': 'ES384',
+            'P-521': 'ES512',
+            'secp256k1': 'ES256K',
+        };
+        // If the key contains an `alg` property that matches a JOSE registered algorithm identifier,
+        // return its value.
+        if (publicKey.alg && Object.values(curveToJoseAlgorithm).includes(publicKey.alg)) {
+            return publicKey.alg;
+        }
+        // If the key contains a `crv` property, return the corresponding algorithm.
+        if (publicKey.crv && Object.keys(curveToJoseAlgorithm).includes(publicKey.crv)) {
+            return curveToJoseAlgorithm[publicKey.crv];
+        }
+        throw new Error(`Unable to determine algorithm based on provided input: alg=${publicKey.alg}, crv=${publicKey.crv}. ` +
+            `Supported 'alg' values: ${Object.values(curveToJoseAlgorithm).join(', ')}. ` +
+            `Supported 'crv' values: ${Object.keys(curveToJoseAlgorithm).join(', ')}.`);
+    }
+    /**
+     * Generates secure pseudorandom values of the specified length using
+     * `crypto.getRandomValues`, which defers to the operating system.
+     *
+     * @memberof CryptoUtils
+     * @remarks
+     * This function is a wrapper around `randomBytes` from the '@noble/hashes'
+     * package. It's designed to be cryptographically strong, suitable for
+     * generating initialization vectors, nonces, and other random values.
+     *
+     * @see {@link https://www.npmjs.com/package/@noble/hashes | @noble/hashes on NPM} for more
+     * information about the underlying implementation.
+     *
+     * @example
+     * ```ts
+     * const bytes = randomBytes(32); // Generates 32 random bytes
+     * ```
+     *
+     * @param bytesLength - The number of bytes to generate.
+     * @returns A Uint8Array containing the generated random bytes.
+     */
+    static randomBytes(bytesLength) {
+        return nobleRandomBytes(bytesLength);
+    }
+    /**
+     * Generates a UUID (Universally Unique Identifier) using a
+     * cryptographically strong random number generator following
+     * the version 4 format, as specified in RFC 4122.
+     *
+     * A version 4 UUID is a randomly generated UUID. The 13th character
+     * is set to '4' to denote version 4, and the 17th character is one
+     * of '8', '9', 'A', or 'B' to comply with the variant 1 format of
+     * UUIDs (the high bits are set to '10').
+     *
+     * The UUID is a 36 character string, including hyphens, and looks like this:
+     * xxxxxxxx-xxxx-4xxx-axxx-xxxxxxxxxxxx
+     *
+     * Note that while UUIDs are not guaranteed to be unique, they are
+     * practically unique" given the large number of possible UUIDs and
+     * the randomness of generation.
+     * @memberof CryptoUtils
+     * @example
+     * ```ts
+     * const uuid = randomUuid();
+     * console.log(uuid); // Outputs a version 4 UUID, e.g., '123e4567-e89b-12d3-a456-426655440000'
+     * ```
+     *
+     * @returns A string containing a randomly generated, 36 character long v4 UUID.
+     */
+    static randomUuid() {
+        const uuid = crypto.randomUUID();
+        return uuid;
+    }
+    /**
+     * Generates a secure random PIN (Personal Identification Number) of a
+     * specified length.
+     *
+     * This function ensures that the generated PIN is cryptographically secure and
+     * uniformly distributed by using rejection sampling. It repeatedly generates
+     * random numbers until it gets one in the desired range [0, max]. This avoids
+     * bias introduced by simply taking the modulus or truncating the number.
+     *
+     * Note: The function can generate PINs of 3 to 10 digits in length.
+     * Any request for a PIN outside this range will result in an error.
+     *
+     * Example usage:
+     *
+     * ```ts
+     * const pin = randomPin({ length: 4 });
+     * console.log(pin); // Outputs a 4-digit PIN, e.g., "0231"
+     * ```
+     * @memberof CryptoUtils
+     * @param options - The options object containing the desired length of the generated PIN.
+     * @param options.length - The desired length of the generated PIN. The value should be
+     *                         an integer between 3 and 8 inclusive.
+     *
+     * @returns A string representing the generated PIN. The PIN will be zero-padded
+     *          to match the specified length, if necessary.
+     *
+     * @throws Will throw an error if the requested PIN length is less than 3 or greater than 8.
+     */
+    static randomPin({ length }) {
+        if (3 > length || length > 10) {
+            throw new Error('randomPin() can securely generate a PIN between 3 to 10 digits.');
+        }
+        const max = Math.pow(10, length) - 1;
+        let pin;
+        if (length <= 6) {
+            const rejectionRange = Math.pow(10, length);
+            do {
+                // Adjust the byte generation based on length.
+                const randomBuffer = CryptoUtils.randomBytes(Math.ceil(length / 2)); // 2 digits per byte.
+                const view = new DataView(randomBuffer.buffer);
+                // Convert the buffer to integer and take modulus based on length.
+                pin = view.getUint16(0, false) % rejectionRange;
+            } while (pin > max);
+        }
+        else {
+            const rejectionRange = Math.pow(10, 10); // For max 10 digit number.
+            do {
+                // Generates 4 random bytes.
+                const randomBuffer = CryptoUtils.randomBytes(4);
+                // Create a DataView to read from the randomBuffer.
+                const view = new DataView(randomBuffer.buffer);
+                // Transform bytes to number (big endian).
+                pin = view.getUint32(0, false) % rejectionRange;
+            } while (pin > max); // Reject if the number is outside the desired range.
+        }
+        // Pad the PIN with leading zeros to the desired length.
+        return pin.toString().padStart(length, '0');
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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"}

package/dist/types/algorithms/aes-ctr.d.ts

@@ -0,0 +1,121 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { Cipher } from '../types/cipher.js';
+import type { KeyGenerator } from '../types/key-generator.js';
+import type { DecryptParams, EncryptParams, GenerateKeyParams } from '../types/params-direct.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+/**
+ * The `AesCtrGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the AES-CTR algorithm.
+ */
+export interface AesCtrGenerateKeyParams extends GenerateKeyParams {
+    /** Specifies the algorithm variant for key generation in AES-CTR mode.
+     * The value determines the length of the key to be generated and must be one of the following:
+     * - `"A128CTR"`: Generates a 128-bit key.
+     * - `"A192CTR"`: Generates a 192-bit key.
+     * - `"A256CTR"`: Generates a 256-bit key.
+     */
+    algorithm: 'A128CTR' | 'A192CTR' | 'A256CTR';
+}
+/**
+ * The `AesCtrParams` interface defines the algorithm-specific parameters that should be passed
+ * into the `encrypt()` and `decrypt()` methods when using the AES-CTR algorithm.
+ */
+export interface AesCtrParams {
+    /** The initial value of the counter block. */
+    counter: Uint8Array;
+    /** The number of bits in the counter block that are used for the actual counter. */
+    length: number;
+}
+/**
+ * The `AesCtrAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the AES algorithm in Counter (CTR) mode. This class implements both {@link Cipher | `Cipher`} and
+ * { @link KeyGenerator | `KeyGenerator`} interfaces, providing key generation, encryption, and
+ * decryption features.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export declare class AesCtrAlgorithm extends CryptoAlgorithm implements Cipher<EncryptParams & AesCtrParams, DecryptParams & AesCtrParams>, KeyGenerator<AesCtrGenerateKeyParams, Jwk> {
+    /**
+     * Decrypts the provided data using AES-CTR.
+     *
+     * @remarks
+     * This method performs AES-CTR decryption on the given encrypted data using the specified key.
+     * Similar to the encryption process, it requires an initial counter block and the length
+     * of the counter block, along with the encrypted data and the decryption key. The method
+     * returns the decrypted data as a Uint8Array.
+     *
+     * @example
+     * ```ts
+     * const aesCtr = new AesCtrAlgorithm();
+     * const encryptedData = new Uint8Array([...]); // Encrypted data
+     * const counter = new Uint8Array(16); // 16-byte (128-bit) counter block used during encryption
+     * const key = { ... }; // A Jwk object representing the same AES key used for encryption
+     * const decryptedData = await aesCtr.decrypt({
+     *   data: encryptedData,
+     *   counter,
+     *   key,
+     *   length: 128 // Length of the counter in bits
+     * });
+     * ```
+     *
+     * @param params - The parameters for the decryption operation.
+     *
+     * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+     */
+    decrypt(params: DecryptParams & AesCtrParams): Promise<Uint8Array>;
+    /**
+     * Encrypts the provided data using AES-CTR.
+     *
+     * @remarks
+     * This method performs AES-CTR encryption on the given data using the specified key.
+     * It requires the initial counter block and the length of the counter block, alongside
+     * the data and key. The method is designed to work asynchronously and returns the
+     * encrypted data as a Uint8Array.
+     *
+     * @example
+     * ```ts
+     * const aesCtr = new AesCtrAlgorithm();
+     * const data = new TextEncoder().encode('Messsage');
+     * const counter = new Uint8Array(16); // 16-byte (128-bit) counter block
+     * const key = { ... }; // A Jwk object representing an AES key
+     * const encryptedData = await aesCtr.encrypt({
+     *   data,
+     *   counter,
+     *   key,
+     *   length: 128 // Length of the counter in bits
+     * });
+     * ```
+     *
+     * @param params - The parameters for the encryption operation.
+     *
+     * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+     */
+    encrypt(params: EncryptParams & AesCtrParams): Promise<Uint8Array>;
+    /**
+     * Generates a symmetric key for AES in Counter (CTR) mode in JSON Web Key (JWK) format.
+     *
+     * @remarks
+     * This method generates a symmetric AES key for use in CTR mode, based on the specified
+     * `algorithm` parameter which determines the key length. It uses cryptographically secure random
+     * number generation to ensure the uniqueness and security of the key. The key is returned in JWK
+     * format.
+     *
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const aesCtr = new AesCtrAlgorithm();
+     * const privateKey = await aesCtr.generateKey({ algorithm: 'A256CTR' });
+     * ```
+     *
+     * @param params - The parameters for the key generation.
+     *
+     * @returns A Promise that resolves to the generated symmetric key in JWK format.
+     */
+    generateKey({ algorithm }: AesCtrGenerateKeyParams): Promise<Jwk>;
+}
+//# sourceMappingURL=aes-ctr.d.ts.map

package/dist/types/algorithms/aes-ctr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-ctr.d.ts","sourceRoot":"","sources":["../../../src/algorithms/aes-ctr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGjG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE;;;;;OAKG;IACH,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,UAAU,CAAC;IAEpB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,eACnC,YAAW,MAAM,CAAC,aAAa,GAAG,YAAY,EAAE,aAAa,GAAG,YAAY,CAAC,EAClE,YAAY,CAAC,uBAAuB,EAAE,GAAG,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,OAAO,CAAC,MAAM,EACzB,aAAa,GAAG,YAAY,GAC3B,OAAO,CAAC,UAAU,CAAC;IAMtB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,OAAO,CAAC,MAAM,EACzB,aAAa,GAAG,YAAY,GAC3B,OAAO,CAAC,UAAU,CAAC;IAMtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,WAAW,CAAC,EAAE,SAAS,EAAE,EACpC,uBAAuB,GACtB,OAAO,CAAC,GAAG,CAAC;CAYhB"}

package/dist/types/algorithms/aes-gcm.d.ts

@@ -0,0 +1,152 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { Cipher } from '../types/cipher.js';
+import type { KeyGenerator } from '../types/key-generator.js';
+import type { DecryptParams, EncryptParams, GenerateKeyParams } from '../types/params-direct.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { AES_GCM_TAG_LENGTHS } from '../primitives/aes-gcm.js';
+/**
+ * The `AesGcmGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the AES-GCM algorithm.
+ */
+export interface AesGcmGenerateKeyParams extends GenerateKeyParams {
+    /** Specifies the algorithm variant for key generation in AES-GCM mode.
+     * The value determines the length of the key to be generated and must be one of the following:
+     * - `"A128GCM"`: Generates a 128-bit key.
+     * - `"A192GCM"`: Generates a 192-bit key.
+     * - `"A256GCM"`: Generates a 256-bit key.
+     */
+    algorithm: 'A128GCM' | 'A192GCM' | 'A256GCM';
+}
+/**
+ * The `AesGcmParams` interface defines the algorithm-specific parameters that should be passed
+ * into the `encrypt()` and `decrypt()` methods when using the AES-GCM algorithm.
+ */
+export interface AesGcmParams {
+    /**
+     * The `additionalData` property is used for authentication alongside encrypted data but isn't
+     * encrypted itself. It must match in both encryption and decryption; a mismatch will cause
+     * decryption to fail. This feature allows for the authentication of data without encrypting it.
+     *
+     * The `additionalData` property is optional and omitting it does not compromise encryption
+     * security.
+     */
+    additionalData?: Uint8Array;
+    /**
+     * The initialization vector (IV) must be unique for every encryption operation carried out with a
+     * given key. The IV need not be secret, but it must be unpredictable: that is, the IV must not be
+     * reused with the same key. The IV must be 12 bytes (96 bits) in length in accordance with the
+     * AES-GCM specification recommendedation to promote interoperability and efficiency.
+     *
+     * Note: It is OK to transmit the IV in the clear with the encrypted message.
+     */
+    iv: Uint8Array;
+    /**
+     * This property determines the size in bits of the authentication tag generated in the encryption
+     * operation and used for authentication in the corresponding decryption. In accordance with the
+     * AES-GCM specification, the tag length must be 96, 104, 112, 120 or 128.
+     *
+     * The `tagLength` property is optional and defaults to 128 bits if omitted.
+     */
+    tagLength?: typeof AES_GCM_TAG_LENGTHS[number];
+}
+/**
+ * The `AesGcmAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the AES algorithm in Galois/Counter Mode (GCM). This class implements both
+ * {@link Cipher | `Cipher`} and { @link KeyGenerator | `KeyGenerator`} interfaces, providing
+ * key generation, encryption, and decryption features.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export declare class AesGcmAlgorithm extends CryptoAlgorithm implements Cipher<AesGcmParams, AesGcmParams>, KeyGenerator<AesGcmGenerateKeyParams, 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 aesGcm = new AesGcmAlgorithm();
+     * 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.
+     *
+     * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+     */
+    decrypt(params: DecryptParams & AesGcmParams): 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 aesGcm = new AesGcmAlgorithm();
+     * 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.
+     *
+     * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+     */
+    encrypt(params: EncryptParams & AesGcmParams): Promise<Uint8Array>;
+    /**
+     * Generates a symmetric key for AES in Galois/Counter Mode (GCM) in JSON Web Key (JWK) format.
+     *
+     * @remarks
+     * This method generates a symmetric AES key for use in GCM mode, based on the specified
+     * `algorithm` parameter which determines the key length. It uses cryptographically secure random
+     * number generation to ensure the uniqueness and security of the key. The key is returned in JWK
+     * format.
+     *
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const aesGcm = new AesGcmAlgorithm();
+     * const privateKey = await aesGcm.generateKey({ algorithm: 'A256GCM' });
+     * ```
+     *
+     * @param params - The parameters for the key generation.
+     *
+     * @returns A Promise that resolves to the generated symmetric key in JWK format.
+     */
+    generateKey({ algorithm }: AesGcmGenerateKeyParams): Promise<Jwk>;
+}
+//# sourceMappingURL=aes-gcm.d.ts.map

package/dist/types/algorithms/aes-gcm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-gcm.d.ts","sourceRoot":"","sources":["../../../src/algorithms/aes-gcm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEjG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAU,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEvE;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE;;;;;OAKG;IACH,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,UAAU,CAAC;IAE5B;;;;;;;OAOG;IACH,EAAE,EAAE,UAAU,CAAC;IAEf;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,eACnC,YAAW,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,EAClC,YAAY,CAAC,uBAAuB,EAAE,GAAG,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACU,OAAO,CAAC,MAAM,EACzB,aAAa,GAAG,YAAY,GAC3B,OAAO,CAAC,UAAU,CAAC;IAMtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACU,OAAO,CAAC,MAAM,EACzB,aAAa,GAAG,YAAY,GAC3B,OAAO,CAAC,UAAU,CAAC;IAMtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,WAAW,CAAC,EAAE,SAAS,EAAE,EACpC,uBAAuB,GACtB,OAAO,CAAC,GAAG,CAAC;CAYhB"}

package/dist/types/algorithms/crypto-algorithm.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Base class for all cryptographic algorithm implementations.
+ */
+export declare abstract class CryptoAlgorithm {
+}
+//# sourceMappingURL=crypto-algorithm.d.ts.map

package/dist/types/algorithms/crypto-algorithm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-algorithm.d.ts","sourceRoot":"","sources":["../../../src/algorithms/crypto-algorithm.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,8BAAsB,eAAe;CAAG"}

package/dist/types/algorithms/ecdsa.d.ts

@@ -0,0 +1,154 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { Signer } from '../types/signer.js';
+import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
+import type { ComputePublicKeyParams, GenerateKeyParams, GetPublicKeyParams, SignParams, VerifyParams } from '../types/params-direct.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+/**
+ * The `EcdsaGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the ECDSA algorithm.
+ */
+export interface EcdsaGenerateKeyParams extends GenerateKeyParams {
+    /**
+     * A string defining the type of key to generate. The value must be one of the following:
+     * - `"ES256"`: ECDSA using the secp256r1 (P-256) curve and SHA-256.
+     * - `"ES256K"`: ECDSA using the secp256k1 curve and SHA-256.
+     * - `"secp256k1"`: ECDSA using the secp256k1 curve and SHA-256.
+     * - `"secp256r1"`: ECDSA using the secp256r1 (P-256) curve and SHA-256.
+     */
+    algorithm: 'ES256' | 'ES256K' | 'secp256k1' | 'secp256r1';
+}
+/**
+ * The `EcdsaAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the Elliptic Curve Digital Signature Algorithm (ECDSA). This class implements both
+ * {@link Signer | `Signer`} and { @link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`}
+ * interfaces, providing private key generation, public key derivation, and creation/verification
+ * of signatures.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export declare class EcdsaAlgorithm extends CryptoAlgorithm implements AsymmetricKeyGenerator<EcdsaGenerateKeyParams, Jwk, GetPublicKeyParams>, Signer<SignParams, VerifyParams> {
+    /**
+     * Derives the public key in JWK format from a given private key.
+     *
+     * @remarks
+     * This method takes a private key in JWK format and derives its corresponding public key,
+     * also in JWK format. The process ensures that the derived public key correctly corresponds to
+     * the given private key.
+     *
+     * @example
+     * ```ts
+     * const ecdsa = new EcdsaAlgorithm();
+     * const privateKey = { ... }; // A Jwk object representing a private key
+     * const publicKey = await ecdsa.computePublicKey({ key: privateKey });
+     * ```
+     *
+     * @param params - The parameters for the public key derivation.
+     * @param params.key - The private key in JWK format from which to derive the public key.
+     *
+     * @returns A Promise that resolves to the derived public key in JWK format.
+     */
+    computePublicKey({ key }: ComputePublicKeyParams): Promise<Jwk>;
+    /**
+     * Generates a new private key with the specified algorithm in JSON Web Key (JWK) format.
+     *
+     * @example
+     * ```ts
+     * const ecdsa = new EcdsaAlgorithm();
+     * const privateKey = await ecdsa.generateKey({ algorithm: 'ES256K' });
+     * ```
+     *
+     * @param params - The parameters for key generation.
+     * @param params.algorithm - The algorithm to use for key generation.
+     *
+     * @returns A Promise that resolves to the generated private key in JWK format.
+     */
+    generateKey({ algorithm }: EcdsaGenerateKeyParams): Promise<Jwk>;
+    /**
+     * Retrieves the public key properties from a given private key in JWK format.
+     *
+     * @remarks
+     * This method extracts the public key portion from an ECDSA private key in JWK format. It does
+     * so by removing the private key property 'd' and making a shallow copy, effectively yielding the
+     * public key.
+     *
+     * Note: This method offers a significant performance advantage, being about 200 times faster
+     * than `computePublicKey()`. However, it 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 object. This makes it suitable for scenarios where speed is
+     * critical and the private key's integrity is already assured.
+     *
+     * @example
+     * ```ts
+     * const ecdsa = new EcdsaAlgorithm();
+     * const privateKey = { ... }; // A Jwk object representing a private key
+     * const publicKey = await ecdsa.getPublicKey({ key: privateKey });
+     * ```
+     *
+     * @param params - The parameters for retrieving the public key properties.
+     * @param params.key - The private key in JWK format.
+     *
+     * @returns A Promise that resolves to the public key in JWK format.
+     */
+    getPublicKey({ key }: GetPublicKeyParams): Promise<Jwk>;
+    /**
+     * Generates an ECDSA signature of given data using a private key.
+     *
+     * @remarks
+     * This method uses the signature algorithm determined by the given `algorithm` to sign the
+     * provided data.
+     *
+     * The signature can later be verified by parties with access to the corresponding
+     * public key, ensuring that the data has not been tampered with and was indeed signed by the
+     * holder of the private key.
+     *
+     * @example
+     * ```ts
+     * const ecdsa = new EcdsaAlgorithm();
+     * const data = new TextEncoder().encode('Message');
+     * const privateKey = { ... }; // A Jwk object representing a private key
+     * const signature = await ecdsa.sign({
+     *   key: privateKey,
+     *   data
+     * });
+     * ```
+     *
+     * @param params - The parameters for the signing operation.
+     * @param params.key - The private key to use for signing, represented in JWK format.
+     * @param params.data - The data to sign.
+     *
+     * @returns A Promise resolving to the digital signature as a `Uint8Array`.
+     */
+    sign({ key, data }: SignParams): Promise<Uint8Array>;
+    /**
+     * Verifies an ECDSA signature associated with the provided data using the provided key.
+     *
+     * @remarks
+     * This method uses the signature algorithm determined by the `crv` property of the provided key
+     * to check the validity of a digital signature against the original data. It confirms whether the
+     * signature was created by the holder of the corresponding private key and that the data has not
+     * been tampered with.
+     *s
+     * @example
+     * ```ts
+     * const ecdsa = new EcdsaAlgorithm();
+     * const publicKey = { ... }; // Public key in JWK format corresponding to the private key that signed the data
+     * const signature = new Uint8Array([...]); // Signature to verify
+     * const data = new TextEncoder().encode('Message');
+     * const isValid = await ecdsa.verify({
+     *   key: publicKey,
+     *   signature,
+     *   data
+     * });
+     * ```
+     *
+     * @param params - The parameters for the verification operation.
+     * @param params.key - The key to use for verification.
+     * @param params.signature - The signature to verify.
+     * @param params.data - The data to verify.
+     *
+     * @returns A Promise resolving to a boolean indicating whether the signature is valid.
+     */
+    verify({ key, signature, data }: VerifyParams): Promise<boolean>;
+}
+//# sourceMappingURL=ecdsa.d.ts.map

package/dist/types/algorithms/ecdsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecdsa.d.ts","sourceRoot":"","sources":["../../../src/algorithms/ecdsa.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAIzI,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC;CAC3D;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,eAClC,YAAW,sBAAsB,CAAC,sBAAsB,EAAE,GAAG,EAAE,kBAAkB,CAAC,EACvE,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC;IAE3C;;;;;;;;;;;;;;;;;;;OAmBG;IACU,gBAAgB,CAAC,EAAE,GAAG,EAAE,EACnC,sBAAsB,GACrB,OAAO,CAAC,GAAG,CAAC;IAuBf;;;;;;;;;;;;;OAaG;IACU,WAAW,CAAC,EAAE,SAAS,EAAE,EACpC,sBAAsB,GACrB,OAAO,CAAC,GAAG,CAAC;IAmBf;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,YAAY,CAAC,EAAE,GAAG,EAAE,EAC/B,kBAAkB,GACjB,OAAO,CAAC,GAAG,CAAC;IAuBf;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACU,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,EAC7B,UAAU,GACT,OAAO,CAAC,UAAU,CAAC;IAmBtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACU,MAAM,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAC1C,YAAY,GACX,OAAO,CAAC,OAAO,CAAC;CAkBpB"}