@enbox/crypto 0.0.2 → 0.0.4

package/src/algorithms/sha-2.ts

@@ -1,8 +1,8 @@
-import type { Hasher } from '../types/hasher.js';
 import type { DigestParams } from '../types/params-direct.js';
+import type { Hasher } from '../types/hasher.js';
 
-import { Sha256 } from '../primitives/sha256.js';
 import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { Sha256 } from '../primitives/sha256.js';
 
 /**
  * The `Sha2DigestParams` interface defines the algorithm-specific parameters that should be
@@ -22,7 +22,7 @@ export interface Sha2DigestParams extends DigestParams {
  * of the hash function and arbitrary data as input and returns the hash digest of the data.
  *
  * This class is typically accessed through implementations that extend the
- * {@link CryptoApi | `CryptoApi`} interface.
+ * {@link DsaApi | `DsaApi`} interface.
  */
 export class Sha2Algorithm extends CryptoAlgorithm
   implements Hasher<Sha2DigestParams> {

package/src/algorithms/x25519.ts

@@ -0,0 +1,153 @@
+import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
+import type { Jwk } from '../jose/jwk.js';
+import type { KeyConverter } from '../types/key-converter.js';
+import type {
+  BytesToPrivateKeyParams,
+  ComputePublicKeyParams,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  PrivateKeyToBytesParams,
+} from '../types/params-direct.js';
+
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { isOkpPrivateJwk } from '../jose/jwk.js';
+import { X25519 } from '../primitives/x25519.js';
+
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+
+/**
+ * The `X25519GenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the X25519 key agreement algorithm.
+ */
+export interface X25519GenerateKeyParams extends GenerateKeyParams {
+  /**
+   * A string defining the type of key to generate. The value must be:
+   * - `"X25519"`: Elliptic-curve Diffie-Hellman (ECDH) using Curve25519.
+   */
+  algorithm: 'X25519';
+}
+
+/**
+ * The `X25519Algorithm` class provides a concrete implementation for key generation,
+ * public key derivation, and key conversion using the X25519 elliptic curve. X25519 is a
+ * key agreement curve (not a signature curve) used for ECDH key exchange in JWE encryption.
+ *
+ * This class implements the {@link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`} and
+ * {@link KeyConverter | `KeyConverter`} interfaces, providing private key generation,
+ * public key derivation, and byte/JWK conversion.
+ */
+export class X25519Algorithm extends CryptoAlgorithm
+  implements AsymmetricKeyGenerator<X25519GenerateKeyParams, Jwk, GetPublicKeyParams>,
+             KeyConverter {
+
+  /**
+   * Converts a raw private key in bytes to its corresponding JWK format.
+   *
+   * @param params - The parameters for the private key conversion.
+   * @param params.algorithm - Must be `'X25519'`.
+   * @param params.privateKeyBytes - The raw private key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the private key in JWK format.
+   */
+  public async bytesToPrivateKey({ algorithm, privateKeyBytes }:
+    BytesToPrivateKeyParams & { algorithm: 'X25519' }
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'X25519': {
+        return X25519.bytesToPrivateKey({ privateKeyBytes });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  /**
+   * Derives the public key in JWK format from a given X25519 private key.
+   *
+   * @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 'X25519': {
+        return X25519.computePublicKey({ key });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Generates a new X25519 private key in JWK format.
+   *
+   * @param params - The parameters for key generation.
+   * @param params.algorithm - Must be `'X25519'`.
+   *
+   * @returns A Promise that resolves to the generated private key in JWK format.
+   */
+  async generateKey({ algorithm }:
+    X25519GenerateKeyParams
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'X25519': {
+        return X25519.generateKey();
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Algorithm not supported: ${algorithm}`);
+      }
+    }
+  }
+
+  /**
+   * Retrieves the public key properties from a given X25519 private key in JWK format.
+   *
+   * @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 'X25519': {
+        return X25519.getPublicKey({ key });
+      }
+
+      default: {
+        throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async privateKeyToBytes({ privateKey }:
+    PrivateKeyToBytesParams
+  ): Promise<Uint8Array> {
+    return X25519.privateKeyToBytes({ privateKey });
+  }
+}

package/src/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',
+}

package/src/index.ts

@@ -1,12 +1,17 @@
+export * from './crypto-error.js';
 export * from './local-key-manager.js';
 export * from './utils.js';
 
 export * from './algorithms/aes-ctr.js';
 export * from './algorithms/aes-gcm.js';
+export * from './algorithms/aes-kw.js';
 export * from './algorithms/crypto-algorithm.js';
 export * from './algorithms/ecdsa.js';
 export * from './algorithms/eddsa.js';
+export * from './algorithms/hkdf.js';
+export * from './algorithms/pbkdf2.js';
 export * from './algorithms/sha-2.js';
+export * from './algorithms/x25519.js';
 
 export * from './jose/jwe.js';
 export * from './jose/jwk.js';
@@ -16,8 +21,11 @@ export * from './jose/utils.js';
 
 export * from './primitives/aes-ctr.js';
 export * from './primitives/aes-gcm.js';
+export * from './primitives/aes-kw.js';
 export * from './primitives/concat-kdf.js';
+export * from './primitives/ecies-secp256k1.js';
 export * from './primitives/ed25519.js';
+export * from './primitives/hkdf.js';
 export * from './primitives/secp256r1.js';
 export * from './primitives/pbkdf2.js';
 export * from './primitives/secp256k1.js';

package/src/jose/jwk.ts

@@ -106,7 +106,7 @@ export type JwkType =
    * A type of public key that is used with algorithms such as EdDSA (Ed25519 and
    * Ed448 curves) and ECDH (X25519 and X448 curves).
    */
-  | 'OKP'
+  | 'OKP';
 
 /**
  * JSON Web Key Elliptic Curve
@@ -155,7 +155,7 @@ export type JwkParamsAnyKeyType = {
   'x5t#S256'?: string;
   /** JWK X.509 URL Parameter */
   x5u?: string;
-}
+};
 
 /** Parameters used with "EC" (elliptic curve) public keys. */
 export type JwkParamsEcPublic = Omit<JwkParamsAnyKeyType, 'alg' | 'kty'> & {
@@ -194,7 +194,7 @@ export type JwkParamsEcPublic = Omit<JwkParamsAnyKeyType, 'alg' | 'kty'> & {
    * MUST be present only for secp256k1 public keys.
    */
   y?: string;
-}
+};
 
 /** Parameters used with "EC" (elliptic curve) private keys. */
 export type JwkParamsEcPrivate = JwkParamsEcPublic & {
@@ -205,7 +205,7 @@ export type JwkParamsEcPrivate = JwkParamsEcPublic & {
    * MUST be present for all EC private keys.
    */
   d: string;
-}
+};
 
 /** Parameters used with "OKP" (octet key pair) public keys. */
 export type JwkParamsOkpPublic =
@@ -229,7 +229,7 @@ export type JwkParamsOkpPublic =
    * strings as private and public keys.
    */
   kty: 'OKP';
-}
+};
 
 /** Parameters used with "OKP" (octet key pair) private keys. */
 export type JwkParamsOkpPrivate = JwkParamsOkpPublic & {
@@ -288,7 +288,7 @@ export type JwkParamsOctPrivate = Omit<JwkParamsAnyKeyType, 'alg' | 'kty'> & {
    * symmetric signature algorithms.
    */
   kty: 'oct';
-}
+};
 
 /** Parameters Used with "RSA" public keys. */
 export type JwkParamsRsaPublic = Omit<JwkParamsAnyKeyType, 'kty'> & {
@@ -519,11 +519,11 @@ export async function computeJwkThumbprint({ jwk }: {
  * @returns True if the object is a valid EC private JWK; otherwise, false.
  */
 export function isEcPrivateJwk(obj: unknown): obj is JwkParamsEcPrivate {
-  if (!obj || typeof obj !== 'object') return false;
-  if (!('kty' in obj && 'crv' in obj && 'x' in obj && 'd' in obj)) return false;
-  if (obj.kty !== 'EC') return false;
-  if (typeof obj.d !== 'string') return false;
-  if (typeof obj.x !== 'string') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
+  if (!('kty' in obj && 'crv' in obj && 'x' in obj && 'd' in obj)) {return false;}
+  if (obj.kty !== 'EC') {return false;}
+  if (typeof obj.d !== 'string') {return false;}
+  if (typeof obj.x !== 'string') {return false;}
   return true;
 }
 
@@ -534,11 +534,11 @@ export function isEcPrivateJwk(obj: unknown): obj is JwkParamsEcPrivate {
  * @returns True if the object is a valid EC public JWK; otherwise, false.
  */
 export function isEcPublicJwk(obj: unknown): obj is JwkParamsEcPublic {
-  if (!obj || typeof obj !== 'object') return false;
-  if (!('kty' in obj && 'crv' in obj && 'x' in obj)) return false;
-  if ('d' in obj) return false;
-  if (obj.kty !== 'EC') return false;
-  if (typeof obj.x !== 'string') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
+  if (!('kty' in obj && 'crv' in obj && 'x' in obj)) {return false;}
+  if ('d' in obj) {return false;}
+  if (obj.kty !== 'EC') {return false;}
+  if (typeof obj.x !== 'string') {return false;}
   return true;
 }
 
@@ -549,10 +549,10 @@ export function isEcPublicJwk(obj: unknown): obj is JwkParamsEcPublic {
  * @returns True if the object is a valid oct private JWK; otherwise, false.
  */
 export function isOctPrivateJwk(obj: unknown): obj is JwkParamsOctPrivate {
-  if (!obj || typeof obj !== 'object') return false;
-  if (!('kty' in obj && 'k' in obj)) return false;
-  if (obj.kty !== 'oct') return false;
-  if (typeof obj.k !== 'string') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
+  if (!('kty' in obj && 'k' in obj)) {return false;}
+  if (obj.kty !== 'oct') {return false;}
+  if (typeof obj.k !== 'string') {return false;}
   return true;
 }
 
@@ -563,11 +563,11 @@ export function isOctPrivateJwk(obj: unknown): obj is JwkParamsOctPrivate {
  * @returns True if the object is a valid OKP private JWK; otherwise, false.
  */
 export function isOkpPrivateJwk(obj: unknown): obj is JwkParamsOkpPrivate {
-  if (!obj || typeof obj !== 'object') return false;
-  if (!('kty' in obj && 'crv' in obj && 'x' in obj && 'd' in obj)) return false;
-  if (obj.kty !== 'OKP') return false;
-  if (typeof obj.d !== 'string') return false;
-  if (typeof obj.x !== 'string') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
+  if (!('kty' in obj && 'crv' in obj && 'x' in obj && 'd' in obj)) {return false;}
+  if (obj.kty !== 'OKP') {return false;}
+  if (typeof obj.d !== 'string') {return false;}
+  if (typeof obj.x !== 'string') {return false;}
   return true;
 }
 
@@ -578,11 +578,11 @@ export function isOkpPrivateJwk(obj: unknown): obj is JwkParamsOkpPrivate {
  * @returns True if the object is a valid OKP public JWK; otherwise, false.
  */
 export function isOkpPublicJwk(obj: unknown): obj is JwkParamsOkpPublic {
-  if (!obj || typeof obj !== 'object') return false;
-  if ('d' in obj) return false;
-  if (!('kty' in obj && 'crv' in obj && 'x' in obj)) return false;
-  if (obj.kty !== 'OKP') return false;
-  if (typeof obj.x !== 'string') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
+  if ('d' in obj) {return false;}
+  if (!('kty' in obj && 'crv' in obj && 'x' in obj)) {return false;}
+  if (obj.kty !== 'OKP') {return false;}
+  if (typeof obj.x !== 'string') {return false;}
   return true;
 }
 
@@ -593,7 +593,7 @@ export function isOkpPublicJwk(obj: unknown): obj is JwkParamsOkpPublic {
  * @returns True if the object is a valid private JWK; otherwise, false.
  */
 export function isPrivateJwk(obj: unknown): obj is PrivateKeyJwk {
-  if (!obj || typeof obj !== 'object') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
 
   const kty = (obj as { kty: string }).kty;
 
@@ -616,7 +616,7 @@ export function isPrivateJwk(obj: unknown): obj is PrivateKeyJwk {
  * @returns True if the object is a valid public JWK; otherwise, false.
  */
 export function isPublicJwk(obj: unknown): obj is PublicKeyJwk {
-  if (!obj || typeof obj !== 'object') return false;
+  if (!obj || typeof obj !== 'object') {return false;}
 
   const kty = (obj as { kty: string }).kty;
 

package/src/local-key-manager.ts

@@ -1,28 +1,30 @@
-import { KeyValueStore, MemoryStore } from '@enbox/common';
+import type { KeyValueStore } from '@enbox/common';
+import { MemoryStore } from '@enbox/common';
 
-import type { Jwk } from './jose/jwk.js';
+import type { CryptoAlgorithm } from './algorithms/crypto-algorithm.js';
 import type { Hasher } from './types/hasher.js';
-import type { Signer } from './types/signer.js';
-import type { CryptoApi } from './types/crypto-api.js';
+import type { Jwk } from './jose/jwk.js';
 import type { KeyIdentifier } from './types/identifier.js';
 import type { KeyImporterExporter } from './types/key-io.js';
-import type { KeyGenerator, AsymmetricKeyGenerator } from './types/key-generator.js';
+import type { KeyManager } from './types/crypto-api.js';
+import type { Signer } from './types/signer.js';
+import type { AsymmetricKeyGenerator, KeyGenerator } from './types/key-generator.js';
 import type { GetPublicKeyParams, SignParams, VerifyParams } from './types/params-direct.js';
 import type {
-  KmsSignParams,
   KmsDigestParams,
-  KmsVerifyParams,
   KmsExportKeyParams,
-  KmsGetKeyUriParams,
-  KmsImportKeyParams,
   KmsGenerateKeyParams,
+  KmsGetKeyUriParams,
   KmsGetPublicKeyParams,
+  KmsImportKeyParams,
+  KmsSignParams,
+  KmsVerifyParams,
 } from './types/params-kms.js';
 
-import { Sha2Algorithm } from './algorithms/sha-2.js';
 import { EcdsaAlgorithm } from './algorithms/ecdsa.js';
 import { EdDsaAlgorithm } from './algorithms/eddsa.js';
-import { CryptoAlgorithm } from './algorithms/crypto-algorithm.js';
+import { Sha2Algorithm } from './algorithms/sha-2.js';
+import { X25519Algorithm } from './algorithms/x25519.js';
 import { computeJwkThumbprint, isPrivateJwk, KEY_URI_PREFIX_JWK } from './jose/jwk.js';
 
 /**
@@ -49,11 +51,15 @@ const supportedAlgorithms = {
   'SHA-256': {
     implementation : Sha2Algorithm,
     names          : ['SHA-256']
+  },
+  'X25519': {
+    implementation : X25519Algorithm,
+    names          : ['X25519']
   }
 } satisfies {
   [key: string]: {
     implementation : typeof CryptoAlgorithm;
-    names          : string[];
+    names : string[];
   }
 };
 
@@ -103,11 +109,11 @@ export interface LocalKeyManagerGenerateKeyParams extends KmsGenerateKeyParams {
    * - `"Ed25519"`
    * - `"secp256k1"`
    */
-  algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1';
+  algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1' | 'X25519';
 }
 
 export class LocalKeyManager implements
-    CryptoApi,
+    KeyManager,
     KeyImporterExporter<KmsImportKeyParams, KeyIdentifier, KmsExportKeyParams> {
 
   /**
@@ -241,7 +247,7 @@ export class LocalKeyManager implements
    * @remarks
    * This method generates a {@link https://datatracker.ietf.org/doc/html/rfc3986 | URI}
    * (Uniform Resource Identifier) for the given JWK, which uniquely identifies the key across all
-   * `CryptoApi` implementations. The key URI is constructed by appending the
+   * `KeyManager` implementations. The key URI is constructed by appending the
    * {@link https://datatracker.ietf.org/doc/html/rfc7638 | JWK thumbprint} to the prefix
    * `urn:jwk:`. The JWK thumbprint is deterministically computed from the JWK and is consistent
    * regardless of property order or optional property inclusion in the JWK. This ensures that the
@@ -335,7 +341,7 @@ export class LocalKeyManager implements
   public async importKey({ key }:
     KmsImportKeyParams
   ): Promise<KeyIdentifier> {
-    if (!isPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be a private key in JWK format.');
+    if (!isPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be a private key in JWK format.');}
 
     // Make a deep copy of the key to avoid mutating the original.
     const privateKey = structuredClone(key);

package/src/primitives/aes-ctr.ts

@@ -296,7 +296,7 @@ export class AesCtr {
     length: typeof AES_KEY_LENGTHS[number];
   }): Promise<Jwk> {
     // Validate the key length.
-    if (!AES_KEY_LENGTHS.includes(length as any)) {
+    if (!(AES_KEY_LENGTHS as readonly number[]).includes(length)) {
       throw new RangeError(`The key length is invalid: Must be ${AES_KEY_LENGTHS.join(', ')} bits`);
     }
 

package/src/primitives/aes-gcm.ts

@@ -187,7 +187,7 @@ export class AesGcm {
     }
 
     // Validate the tag length.
-    if (tagLength && !AES_GCM_TAG_LENGTHS.includes(tagLength as any)) {
+    if (tagLength && !(AES_GCM_TAG_LENGTHS as readonly number[]).includes(tagLength)) {
       throw new RangeError(`The tag length is invalid: Must be ${AES_GCM_TAG_LENGTHS.join(', ')} bits`);
     }
 
@@ -203,7 +203,7 @@ export class AesGcm {
       name: 'AES-GCM',
       iv,
       ...(tagLength && { tagLength }),
-      ...(additionalData && { additionalData})
+      ...(additionalData && { additionalData })
     };
 
     // Decrypt the data.
@@ -263,7 +263,7 @@ export class AesGcm {
     }
 
     // Validate the tag length.
-    if (tagLength && !AES_GCM_TAG_LENGTHS.includes(tagLength as any)) {
+    if (tagLength && !(AES_GCM_TAG_LENGTHS as readonly number[]).includes(tagLength)) {
       throw new RangeError(`The tag length is invalid: Must be ${AES_GCM_TAG_LENGTHS.join(', ')} bits`);
     }
 
@@ -279,7 +279,7 @@ export class AesGcm {
       name: 'AES-GCM',
       iv,
       ...(tagLength && { tagLength }),
-      ...(additionalData && { additionalData})
+      ...(additionalData && { additionalData })
     };
 
     // Encrypt the data.
@@ -321,7 +321,7 @@ export class AesGcm {
     length: typeof AES_KEY_LENGTHS[number];
   }): Promise<Jwk> {
     // Validate the key length.
-    if (!AES_KEY_LENGTHS.includes(length as any)) {
+    if (!(AES_KEY_LENGTHS as readonly number[]).includes(length)) {
       throw new RangeError(`The key length is invalid: Must be ${AES_KEY_LENGTHS.join(', ')} bits`);
     }