@enbox/agent 0.1.3 → 0.1.4

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

@@ -1,160 +0,0 @@
-import type { RequireOnly } from '@enbox/common';
-import type { BytesToPrivateKeyParams, GenerateKeyParams, Jwk, KeyConverter, KeyGenerator, KeyWrapper, PrivateKeyToBytesParams, UnwrapKeyParams, WrapKeyParams } from '@enbox/crypto';
-
-import { AesKw, CryptoAlgorithm } from '@enbox/crypto';
-
-/**
- * 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

@@ -1,366 +0,0 @@
-import type {
-  AsymmetricKeyConverter,
-  AsymmetricKeyGenerator,
-  ComputePublicKeyParams,
-  GenerateKeyParams,
-  GetPublicKeyParams,
-  Jwk,
-  KeyConverter,
-  Signer,
-  SignParams,
-  VerifyParams,
-} from '@enbox/crypto';
-
-import { CryptoAlgorithm, isEcPrivateJwk, isEcPublicJwk, Secp256k1, Secp256r1 } from '@enbox/crypto';
-
-import type { BytesToPrivateKeyParams, BytesToPublicKeyParams, PrivateKeyToBytesParams, PublicKeyToBytesParams } from '../types/params-direct.js';
-import { CryptoError, CryptoErrorCode } from '../crypto-error.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}`);
-      }
-    }
-  }
-}