@enbox/agent 0.0.1

package/src/prototyping/crypto/algorithms/aes-kw.ts

@@ -0,0 +1,164 @@
+import type { GenerateKeyParams, Jwk, KeyConverter, KeyGenerator, KeyWrapper } from '@enbox/crypto';
+
+import { CryptoAlgorithm } from '@enbox/crypto';
+
+import type { BytesToPrivateKeyParams, PrivateKeyToBytesParams, UnwrapKeyParams, WrapKeyParams } from '../types/params-direct.js';
+
+import { AesKw } from '../primitives/aes-kw.js';
+import { RequireOnly } from '@enbox/common';
+
+/**
+ * The `AesKwGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the AES-KW algorithm.
+ */
+export interface AesKwGenerateKeyParams extends GenerateKeyParams {
+  /** Specifies the algorithm variant for key generation in AES-KW mode.
+   * The value determines the length of the key to be generated and must be one of the following:
+   * - `"A128KW"`: AES Key Wrap using a 128-bit key.
+   * - `"A192KW"`: AES Key Wrap using a 192-bit key.
+   * - `"A256KW"`: AES Key Wrap using a 256-bit key.
+   */
+  algorithm: 'A128KW' | 'A192KW' | 'A256KW';
+}
+
+/**
+ * The `AesKwAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the AES algorithm for key wrapping. This class implements both
+ * {@link KeyGenerator | `KeyGenerator`} and {@link KeyWrapper | `KeyWrapper`} interfaces, providing
+ * key generation, key wrapping, and key unwrapping features.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export class AesKwAlgorithm extends CryptoAlgorithm
+  implements KeyConverter,
+             KeyGenerator<AesKwGenerateKeyParams, Jwk>,
+             KeyWrapper<WrapKeyParams, UnwrapKeyParams> {
+
+  public async bytesToPrivateKey({ privateKeyBytes }:
+    RequireOnly<BytesToPrivateKeyParams, 'privateKeyBytes'>
+  ): Promise<Jwk> {
+    // Convert the byte array to a JWK.
+    const privateKey = await AesKw.bytesToPrivateKey({ privateKeyBytes });
+
+    // Set the `alg` property based on the key length.
+    privateKey.alg = { 16: 'A128KW', 24: 'A192KW', 32: 'A256KW' }[privateKeyBytes.length];
+
+    return privateKey;
+  }
+
+  /**
+   * Generates a symmetric key for AES for key wrapping in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method generates a symmetric AES key for use in key wrapping 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.
+   * - `alg`: Algorithm, set to 'A128KW', 'A192KW', or 'A256KW' for AES Key Wrap with the
+   *   specified key length.
+   *
+   * @example
+   * ```ts
+   * const aesKw = new AesKwAlgorithm();
+   * const privateKey = await aesKw.generateKey({ algorithm: 'A256KW' });
+   * ```
+   *
+   * @param params - The parameters for the key generation.
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public async generateKey({ algorithm }:
+    AesKwGenerateKeyParams
+  ): Promise<Jwk> {
+    // Map algorithm name to key length.
+    const length = { A128KW: 128, A192KW: 192, A256KW: 256 }[algorithm] as 128 | 192 | 256;
+
+    // Generate a random private key.
+    const privateKey = await AesKw.generateKey({ length });
+
+    // Set the `alg` property based on the specified algorithm.
+    privateKey.alg = algorithm;
+
+    return privateKey;
+  }
+
+  public async privateKeyToBytes({ privateKey }:
+    PrivateKeyToBytesParams
+  ): Promise<Uint8Array> {
+    // Convert the JWK to a byte array.
+    const privateKeyBytes = await AesKw.privateKeyToBytes({ privateKey });
+
+    return privateKeyBytes;
+  }
+
+  /**
+   * Decrypts a wrapped key using the AES Key Wrap algorithm.
+   *
+   * @remarks
+   * This method unwraps a previously wrapped cryptographic key using the AES Key Wrap algorithm.
+   * The wrapped key, provided as a byte array, is unwrapped using the decryption key specified in
+   * the parameters.
+   *
+   * This operation is useful for securely receiving keys transmitted over untrusted mediums. The
+   * method returns the unwrapped key as a JSON Web Key (JWK).
+   *
+   * @example
+   * ```ts
+   * const aesKw = new AesKwAlgorithm();
+   * const wrappedKeyBytes = new Uint8Array([...]); // Byte array of a wrapped AES-256 GCM key
+   * const decryptionKey = { ... }; // A Jwk object representing the AES unwrapping key
+   * const unwrappedKey = await aesKw.unwrapKey({
+   *   wrappedKeyBytes,
+   *   wrappedKeyAlgorithm: 'A256GCM',
+   *   decryptionKey
+   * });
+   * ```
+   *
+   * @param params - The parameters for the key unwrapping operation.
+   *
+   * @returns A Promise that resolves to the unwrapped key in JWK format.
+   */
+  public async unwrapKey(params:
+    UnwrapKeyParams
+  ): Promise<Jwk> {
+    const unwrappedKey = await AesKw.unwrapKey(params);
+
+    return unwrappedKey;
+  }
+
+  /**
+   * Encrypts a given key using the AES Key Wrap algorithm.
+   *
+   * @remarks
+   * This method wraps a given cryptographic key using the AES Key Wrap algorithm. The private key
+   * to be wrapped is provided in the form of a JSON Web Key (JWK).
+   *
+   * This operation is useful for securely transmitting keys over untrusted mediums. The method
+   * returns the wrapped key as a byte array.
+   *
+   * @example
+   * ```ts
+   * const aesKw = new AesKwAlgorithm();
+   * const unwrappedKey = { ... }; // A Jwk object representing the key to be wrapped
+   * const encryptionKey = { ... }; // A Jwk object representing the AES wrapping key
+   * const wrappedKeyBytes = await aesKw.wrapKey({ unwrappedKey, encryptionKey });
+   * ```
+   *
+   * @param params - The parameters for the key wrapping operation.
+   *
+   * @returns A Promise that resolves to the wrapped key as a Uint8Array.
+   */
+  public async wrapKey(params:
+    WrapKeyParams
+  ): Promise<Uint8Array> {
+    const wrappedKeyBytes = AesKw.wrapKey(params);
+
+    return wrappedKeyBytes;
+  }
+}

package/src/prototyping/crypto/algorithms/ecdsa.ts

@@ -0,0 +1,365 @@
+import type {
+  Jwk,
+  Signer,
+  SignParams,
+  KeyConverter,
+  VerifyParams,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  AsymmetricKeyConverter,
+  AsymmetricKeyGenerator,
+  ComputePublicKeyParams,
+} from '@enbox/crypto';
+
+import { CryptoAlgorithm, isEcPrivateJwk, isEcPublicJwk, Secp256k1, Secp256r1 } from '@enbox/crypto';
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+import { BytesToPrivateKeyParams, BytesToPublicKeyParams, PrivateKeyToBytesParams, PublicKeyToBytesParams } from '../types/params-direct.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 class EcdsaAlgorithm extends CryptoAlgorithm
+  implements AsymmetricKeyGenerator<EcdsaGenerateKeyParams, Jwk, GetPublicKeyParams>,
+             KeyConverter, AsymmetricKeyConverter,
+             Signer<SignParams, VerifyParams> {
+
+  public async bytesToPrivateKey({ algorithm, privateKeyBytes }:
+    BytesToPrivateKeyParams & { algorithm: 'ES256' | 'ES256K' | 'secp256k1' | 'secp256r1' }
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'ES256K':
+      case 'secp256k1': {
+        const privateKey = await Secp256k1.bytesToPrivateKey({ privateKeyBytes });
+        privateKey.alg = 'EdDSA';
+        return privateKey;
+      }
+
+      case 'ES256':
+      case 'secp256r1': {
+        const privateKey = await Secp256r1.bytesToPrivateKey({ privateKeyBytes });
+        privateKey.alg = 'EdDSA';
+        return privateKey;
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  public async bytesToPublicKey({ algorithm, publicKeyBytes }:
+    BytesToPublicKeyParams & { algorithm: 'ES256' | 'ES256K' | 'secp256k1' | 'secp256r1' }
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'ES256K':
+      case 'secp256k1': {
+        const publicKey = await Secp256k1.bytesToPublicKey({ publicKeyBytes });
+        publicKey.alg = 'EdDSA';
+        return publicKey;
+      }
+
+      case 'ES256':
+      case 'secp256r1': {
+        const publicKey = await Secp256r1.bytesToPublicKey({ publicKeyBytes });
+        publicKey.alg = 'EdDSA';
+        return publicKey;
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async computePublicKey({ key }:
+    ComputePublicKeyParams
+  ): Promise<Jwk> {
+    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        const publicKey = await Secp256k1.computePublicKey({ key });
+        publicKey.alg = 'ES256K';
+        return publicKey;
+      }
+
+      case 'P-256': {
+        const publicKey = await Secp256r1.computePublicKey({ key });
+        publicKey.alg = 'ES256';
+        return publicKey;
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async generateKey({ algorithm }:
+    EcdsaGenerateKeyParams
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'ES256K':
+      case 'secp256k1': {
+        const privateKey = await Secp256k1.generateKey();
+        privateKey.alg = 'ES256K';
+        return privateKey;
+      }
+
+      case 'ES256':
+      case 'secp256r1': {
+        const privateKey = await Secp256r1.generateKey();
+        privateKey.alg = 'ES256';
+        return privateKey;
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async getPublicKey({ key }:
+    GetPublicKeyParams
+  ): Promise<Jwk> {
+    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        const publicKey = await Secp256k1.getPublicKey({ key });
+        publicKey.alg = 'ES256K';
+        return publicKey;
+      }
+
+      case 'P-256': {
+        const publicKey = await Secp256r1.getPublicKey({ key });
+        publicKey.alg = 'ES256';
+        return publicKey;
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  public async privateKeyToBytes({ privateKey }:
+    PrivateKeyToBytesParams
+  ): Promise<Uint8Array> {
+    switch (privateKey.crv) {
+
+      case 'secp256k1': {
+        return await Secp256k1.privateKeyToBytes({ privateKey });
+      }
+
+      case 'P-256': {
+        return await Secp256r1.privateKeyToBytes({ privateKey });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${privateKey.crv}`);
+      }
+    }
+  }
+
+  public async publicKeyToBytes({ publicKey }:
+    PublicKeyToBytesParams
+  ): Promise<Uint8Array> {
+    switch (publicKey.crv) {
+
+      case 'secp256k1': {
+        return await Secp256k1.publicKeyToBytes({ publicKey });
+      }
+
+      case 'P-256': {
+        return await Secp256r1.publicKeyToBytes({ publicKey });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${publicKey.crv}`);
+      }
+    }
+  }
+
+  /**
+   * 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`.
+   */
+  public async sign({ key, data }:
+    SignParams
+  ): Promise<Uint8Array> {
+    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        return await Secp256k1.sign({ key, data });
+      }
+
+      case 'P-256': {
+        return await Secp256r1.sign({ key, data });
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async verify({ key, signature, data }:
+    VerifyParams
+  ): Promise<boolean> {
+    if (!isEcPublicJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) public key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        return await Secp256k1.verify({ key, signature, data });
+      }
+
+      case 'P-256': {
+        return await Secp256r1.verify({ key, signature, data });
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+}