@enbox/crypto 0.0.1 → 0.0.3

package/src/algorithms/ecdsa.ts

@@ -1,11 +1,17 @@
+import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
 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 type {
+  ComputePublicKeyParams,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  SignParams,
+  VerifyParams,
+} from '../types/params-direct.js';
 
+import { CryptoAlgorithm } from './crypto-algorithm.js';
 import { Secp256k1 } from '../primitives/secp256k1.js';
 import { Secp256r1 } from '../primitives/secp256r1.js';
-import { CryptoAlgorithm } from './crypto-algorithm.js';
 import { isEcPrivateJwk, isEcPublicJwk } from '../jose/jwk.js';
 
 /**
@@ -60,7 +66,7 @@ export class EcdsaAlgorithm extends CryptoAlgorithm
   public async computePublicKey({ key }:
     ComputePublicKeyParams
   ): Promise<Jwk> {
-    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+    if (!isEcPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');}
 
     switch (key.crv) {
 
@@ -146,7 +152,7 @@ export class EcdsaAlgorithm extends CryptoAlgorithm
   public async getPublicKey({ key }:
     GetPublicKeyParams
   ): Promise<Jwk> {
-    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+    if (!isEcPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');}
 
     switch (key.crv) {
 
@@ -199,7 +205,7 @@ export class EcdsaAlgorithm extends CryptoAlgorithm
   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.');
+    if (!isEcPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');}
 
     switch (key.crv) {
 
@@ -249,7 +255,7 @@ export class EcdsaAlgorithm extends CryptoAlgorithm
   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.');
+    if (!isEcPublicJwk(key)) {throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) public key.');}
 
     switch (key.crv) {
 

package/src/algorithms/eddsa.ts

@@ -1,16 +1,16 @@
+import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
 import type { Jwk } from '../jose/jwk.js';
 import type { Signer } from '../types/signer.js';
-import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
 import type {
-  SignParams,
-  VerifyParams,
+  ComputePublicKeyParams,
   GenerateKeyParams,
   GetPublicKeyParams,
-  ComputePublicKeyParams,
+  SignParams,
+  VerifyParams,
 } from '../types/params-direct.js';
 
-import { Ed25519 } from '../primitives/ed25519.js';
 import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { Ed25519 } from '../primitives/ed25519.js';
 import { isOkpPrivateJwk, isOkpPublicJwk } from '../jose/jwk.js';
 
 /**
@@ -62,7 +62,7 @@ export class EdDsaAlgorithm extends CryptoAlgorithm
   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.');
+    if (!isOkpPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');}
 
     switch (key.crv) {
 
@@ -134,7 +134,7 @@ export class EdDsaAlgorithm extends CryptoAlgorithm
   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.');
+    if (!isOkpPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');}
 
     switch (key.crv) {
 
@@ -181,7 +181,7 @@ export class EdDsaAlgorithm extends CryptoAlgorithm
   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.');
+    if (!isOkpPrivateJwk(key)) {throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) private key.');}
 
     switch (key.crv) {
 
@@ -227,7 +227,7 @@ export class EdDsaAlgorithm extends CryptoAlgorithm
   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.');
+    if (!isOkpPublicJwk(key)) {throw new TypeError('Invalid key provided. Must be an octet key pair (OKP) public key.');}
 
     switch (key.crv) {
 

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

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,3 +1,4 @@
+export * from './crypto-error.js';
 export * from './local-key-manager.js';
 export * from './utils.js';
 
@@ -16,8 +17,10 @@ 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/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,29 @@
-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 { Hasher } from './types/hasher.js';
-import type { Signer } from './types/signer.js';
+import type { CryptoAlgorithm } from './algorithms/crypto-algorithm.js';
 import type { CryptoApi } from './types/crypto-api.js';
+import type { Hasher } from './types/hasher.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 { 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 { computeJwkThumbprint, isPrivateJwk, KEY_URI_PREFIX_JWK } from './jose/jwk.js';
 
 /**
@@ -53,7 +54,7 @@ const supportedAlgorithms = {
 } satisfies {
   [key: string]: {
     implementation : typeof CryptoAlgorithm;
-    names          : string[];
+    names : string[];
   }
 };
 
@@ -335,7 +336,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`);
     }