@enbox/agent 0.0.1

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

@@ -0,0 +1,310 @@
+import type {
+  Jwk,
+  Signer,
+  SignParams,
+  KeyConverter,
+  VerifyParams,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  AsymmetricKeyConverter,
+  AsymmetricKeyGenerator,
+  ComputePublicKeyParams,
+} from '@enbox/crypto';
+
+import { CryptoAlgorithm, Ed25519, isOkpPrivateJwk, isOkpPublicJwk } from '@enbox/crypto';
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+import { BytesToPrivateKeyParams, BytesToPublicKeyParams, PrivateKeyToBytesParams, PublicKeyToBytesParams } from '../types/params-direct.js';
+
+/**
+ * The `EdDsaGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the EdDSA algorithm.
+ */
+export interface EdDsaGenerateKeyParams extends GenerateKeyParams {
+  /**
+   * A string defining the type of key to generate. The value must be one of the following:
+   * - `"Ed25519"`: EdDSA using the Ed25519 curve.
+   */
+  algorithm: 'Ed25519';
+}
+
+/**
+ * The `EdDsaAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the Edwards-curve Digital Signature Algorithm (EdDSA). 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 EdDsaAlgorithm extends CryptoAlgorithm
+  implements AsymmetricKeyGenerator<EdDsaGenerateKeyParams, Jwk, GetPublicKeyParams>,
+             KeyConverter, AsymmetricKeyConverter,
+             Signer<SignParams, VerifyParams> {
+
+  public async bytesToPrivateKey({ algorithm, privateKeyBytes }:
+    BytesToPrivateKeyParams & { algorithm: 'Ed25519' }
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'Ed25519': {
+        const privateKey = await Ed25519.bytesToPrivateKey({ privateKeyBytes });
+        privateKey.alg = 'EdDSA';
+        return privateKey;
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  public async bytesToPublicKey({ algorithm, publicKeyBytes }:
+    BytesToPublicKeyParams & { algorithm: 'Ed25519' }
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'Ed25519': {
+        const publicKey = await Ed25519.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 eddsa = new EdDsaAlgorithm();
+   * const privateKey = { ... }; // A Jwk object representing a private key
+   * const publicKey = await eddsa.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 (!isOkpPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');
+
+    switch (key.crv) {
+
+      case 'Ed25519': {
+        const publicKey = await Ed25519.computePublicKey({ key });
+        publicKey.alg = 'EdDSA';
+        return publicKey;
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Generates a new private key with the specified algorithm in JSON Web Key (JWK) format.
+   *
+   * @example
+   * ```ts
+   * const eddsa = new EdDsaAlgorithm();
+   * const privateKey = await eddsa.generateKey({ algorithm: 'Ed25519' });
+   * ```
+   *
+   * @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.
+   */
+  async generateKey({ algorithm }:
+    EdDsaGenerateKeyParams
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'Ed25519': {
+        const privateKey = await Ed25519.generateKey();
+        privateKey.alg = 'EdDSA';
+        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 EdDSA 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 100 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 eddsa = new EdDsaAlgorithm();
+   * const privateKey = { ... }; // A Jwk object representing a private key
+   * const publicKey = await eddsa.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 (!isOkpPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');
+
+    switch (key.crv) {
+
+      case 'Ed25519': {
+        const publicKey = await Ed25519.getPublicKey({ key });
+        publicKey.alg = 'EdDSA';
+        return publicKey;
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  public async privateKeyToBytes({ privateKey }:
+    PrivateKeyToBytesParams
+  ): Promise<Uint8Array> {
+    switch (privateKey.crv) {
+
+      case 'Ed25519': {
+        return await Ed25519.privateKeyToBytes({ privateKey });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${privateKey.crv}`);
+      }
+    }
+  }
+
+  public async publicKeyToBytes({ publicKey }:
+    PublicKeyToBytesParams
+  ): Promise<Uint8Array> {
+    switch (publicKey.crv) {
+
+      case 'Ed25519': {
+        return await Ed25519.publicKeyToBytes({ publicKey });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${publicKey.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Generates an EdDSA 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 eddsa = new EdDsaAlgorithm();
+   * const data = new TextEncoder().encode('Message');
+   * const privateKey = { ... }; // A Jwk object representing a private key
+   * const signature = await eddsa.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 (!isOkpPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');
+
+    switch (key.crv) {
+
+      case 'Ed25519': {
+        return await Ed25519.sign({ key, data });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Verifies an EdDSA 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 eddsa = new EdDsaAlgorithm();
+   * 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 eddsa.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 (!isOkpPublicJwk(key)) throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) public key.');
+
+    switch (key.crv) {
+
+      case 'Ed25519': {
+        return await Ed25519.verify({ key, signature, data });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Curve not supported: ${key.crv}`);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,40 @@
+import { CryptoAlgorithm } from '@enbox/crypto';
+
+import type { DeriveKeyBytesParams } from '../types/params-direct.js';
+
+import { Hkdf, HkdfParams } from '../primitives/hkdf.js';
+import { KeyBytesDeriver } from '../types/key-deriver.js';
+
+/**
+ * The `HkdfDeriveKeyBytesParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `deriveKeyBytes()` method when using the HKDF algorithm.
+ */
+export interface HkdfDeriveKeyBytesParams extends DeriveKeyBytesParams {
+  /** Specifies the algorithm variant for HKDF key derivation.
+   * The value determines the hash function that will be used and must be one of the following:
+   * - `"HKDF-256"`: HKDF with SHA-256.
+   * - `"HKDF-384"`: HKDF with SHA-384.
+   * - `"HKDF-512"`: HKDF with SHA-512.
+   */
+  algorithm: 'HKDF-256' | 'HKDF-384' | 'HKDF-512';
+}
+
+export class HkdfAlgorithm extends CryptoAlgorithm
+  implements KeyBytesDeriver<HkdfDeriveKeyBytesParams, Uint8Array> {
+
+  public async deriveKeyBytes({ algorithm, ...params }:
+    HkdfDeriveKeyBytesParams & Omit<HkdfParams, 'hash'>
+  ): Promise<Uint8Array> {
+    // Map algorithm name to hash function.
+    const hash = {
+      'HKDF-256' : 'SHA-256' as const,
+      'HKDF-384' : 'SHA-384' as const,
+      'HKDF-512' : 'SHA-512' as const
+    }[algorithm];
+
+    // Derive a cryptographic byte array using HKDF.
+    const derivedKeyBytes = await Hkdf.deriveKeyBytes({ ...params, hash });
+
+    return derivedKeyBytes;
+  }
+}

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

@@ -0,0 +1,44 @@
+import { CryptoAlgorithm } from '@enbox/crypto';
+
+import type { Pbkdf2Params } from '../primitives/pbkdf2.js';
+import type { KeyBytesDeriver } from '../types/key-deriver.js';
+import type { DeriveKeyBytesParams } from '../types/params-direct.js';
+
+import { Pbkdf2 } from '../primitives/pbkdf2.js';
+
+/**
+ * The `Pbkdf2DeriveKeyBytesParams` interface defines the algorithm-specific parameters that
+ * should be passed into the `deriveKeyBytes()` method when using the PBKDF2 algorithm.
+ */
+export interface Pbkdf2DeriveKeyBytesParams extends DeriveKeyBytesParams {
+  /** Specifies the algorithm variant for PBKDF2 key derivation.
+   * The value determines the hash function that will be used and must be one of the following:
+   * - `"PBKDF2-HS256+A128KW"`: PBKDF2 with HMAC SHA-256 and A128KW key wrapping.
+   * - `"PBKDF2-HS384+A192KW"`: PBKDF2 with HMAC SHA-384 and A192KW key wrapping.
+   * - `"PBKDF2-HS512+A256KW"`: PBKDF2 with HMAC SHA-512 and A256KW key wrapping.
+   */
+  algorithm: 'PBES2-HS256+A128KW' | 'PBES2-HS384+A192KW' | 'PBES2-HS512+A256KW';
+}
+
+export class Pbkdf2Algorithm extends CryptoAlgorithm
+  implements KeyBytesDeriver<Pbkdf2DeriveKeyBytesParams, Uint8Array> {
+
+  public async deriveKeyBytes({ algorithm, ...params }:
+    Pbkdf2DeriveKeyBytesParams & Omit<Pbkdf2Params, 'hash'>
+  ): Promise<Uint8Array> {
+    // Extract the hash function component of the `algorithm` parameter.
+    const [, hashFunction] = algorithm.split(/[-+]/);
+
+    // Map from JOSE algorithm name to "SHA" hash function identifier.
+    const hash = {
+      'HS256' : 'SHA-256' as const,
+      'HS384' : 'SHA-384' as const,
+      'HS512' : 'SHA-512' as const
+    }[hashFunction]!;
+
+    // Derive a cryptographic byte array using PBKDF2.
+    const derivedKeyBytes = await Pbkdf2.deriveKeyBytes({ ...params, hash });
+
+    return derivedKeyBytes;
+  }
+}

package/src/prototyping/crypto/crypto-error.ts

@@ -0,0 +1,45 @@
+/**
+ * A custom error class for Crypto-related errors.
+ */
+export class CryptoError extends Error {
+  /**
+   * Constructs an instance of CryptoError, a custom error class for handling Crypto-related errors.
+   *
+   * @param code - A {@link CryptoErrorCode} representing the specific type of error encountered.
+   * @param message - A human-readable description of the error.
+   */
+  constructor(public code: CryptoErrorCode, message: string) {
+    super(message);
+    this.name = 'CryptoError';
+
+    // Ensures that instanceof works properly, the correct prototype chain when using inheritance,
+    // and that V8 stack traces (like Chrome, Edge, and Node.js) are more readable and relevant.
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    // Captures the stack trace in V8 engines (like Chrome, Edge, and Node.js).
+    // In non-V8 environments, the stack trace will still be captured.
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CryptoError);
+    }
+  }
+}
+
+/**
+ * An enumeration of possible Crypto error codes.
+ */
+export enum CryptoErrorCode {
+  /** The supplied algorithm identifier is not supported by the implementation. */
+  AlgorithmNotSupported = 'algorithmNotSupported',
+
+  /** The encoding operation (either encoding or decoding) failed. */
+  EncodingError = 'encodingError',
+
+  /** The JWE supplied does not conform to valid syntax. */
+  InvalidJwe = 'invalidJwe',
+
+  /** The JWK supplied does not conform to valid syntax. */
+  InvalidJwk = 'invalidJwk',
+
+  /** The requested operation is not supported by the implementation. */
+  OperationNotSupported = 'operationNotSupported',
+}