@enbox/crypto 0.0.1

package/src/algorithms/eddsa.ts

@@ -0,0 +1,243 @@
+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,
+  GenerateKeyParams,
+  GetPublicKeyParams,
+  ComputePublicKeyParams,
+} from '../types/params-direct.js';
+
+import { Ed25519 } from '../primitives/ed25519.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { isOkpPrivateJwk, isOkpPublicJwk } from '../jose/jwk.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>,
+             Signer<SignParams, VerifyParams> {
+
+  /**
+   * 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 Error(`Unsupported curve: ${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}`);
+      }
+    }
+  }
+
+  /**
+   * 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 Error(`Unsupported curve: ${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 Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+}

package/src/algorithms/sha-2.ts

@@ -0,0 +1,65 @@
+import type { Hasher } from '../types/hasher.js';
+import type { DigestParams } from '../types/params-direct.js';
+
+import { Sha256 } from '../primitives/sha256.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+
+/**
+ * The `Sha2DigestParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `digest()` method when using the SHA-2 algorithm.
+ */
+export interface Sha2DigestParams extends DigestParams {
+  /**
+   * A string defining the name of hash function to use. The value must be one of the following:
+   * - `"SHA-256"`: Generates a 256-bit digest.
+   */
+  algorithm: 'SHA-256';
+}
+
+/**
+ * The `Sha2Algorithm` class is an implementation of the {@link Hasher | `Hasher`} interface for the
+ * SHA-2 family of cryptographic hash functions. The `digest` method takes the algorithm identifier
+ * 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.
+ */
+export class Sha2Algorithm extends CryptoAlgorithm
+  implements Hasher<Sha2DigestParams> {
+
+  /**
+   * Generates a hash digest of the provided data.
+   *
+   * @remarks
+   * A digest is the output of the hash function. It's a fixed-size string of bytes
+   * that uniquely represents the data input into the hash function. The digest is often used for
+   * data integrity checks, as any alteration in the input data results in a significantly
+   * different digest.
+   *
+   * It takes the algorithm identifier of the hash function and data to digest as input and returns
+   * the digest of the data.
+   *
+   * @example
+   * ```ts
+   * const sha2 = new Sha2Algorithm();
+   * const data = new TextEncoder().encode('Messsage');
+   * const digest = await sha2.digest({ data });
+   * ```
+   *
+   * @param params - The parameters for the digest operation.
+   * @param params.algorithm - The name of hash function to use.
+   * @param params.data - The data to digest.
+   *
+   * @returns A Promise which will be fulfilled with the hash digest.
+   */
+  public async digest({ algorithm, data }: Sha2DigestParams): Promise<Uint8Array> {
+    switch (algorithm) {
+
+      case 'SHA-256': {
+        const hash = await Sha256.digest({ data });
+        return hash;
+      }
+    }
+
+  }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+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/crypto-algorithm.js';
+export * from './algorithms/ecdsa.js';
+export * from './algorithms/eddsa.js';
+export * from './algorithms/sha-2.js';
+
+export * from './jose/jwe.js';
+export * from './jose/jwk.js';
+export * from './jose/jws.js';
+export * from './jose/jwt.js';
+export * from './jose/utils.js';
+
+export * from './primitives/aes-ctr.js';
+export * from './primitives/aes-gcm.js';
+export * from './primitives/concat-kdf.js';
+export * from './primitives/ed25519.js';
+export * from './primitives/secp256r1.js';
+export * from './primitives/pbkdf2.js';
+export * from './primitives/secp256k1.js';
+export * from './primitives/sha256.js';
+export * from './primitives/x25519.js';
+export * from './primitives/xchacha20.js';
+export * from './primitives/xchacha20-poly1305.js';
+
+export type * from './types/cipher.js';
+export type * from './types/crypto-api.js';
+export type * from './types/hasher.js';
+export type * from './types/identifier.js';
+export type * from './types/key-compressor.js';
+export type * from './types/key-converter.js';
+export type * from './types/key-deriver.js';
+export type * from './types/key-generator.js';
+export type * from './types/key-io.js';
+export type * from './types/key-wrapper.js';
+export type * from './types/params-direct.js';
+export type * from './types/params-enclosed.js';
+export type * from './types/params-kms.js';
+export type * from './types/signer.js';

package/src/jose/jwe.ts

@@ -0,0 +1,196 @@
+import type { JoseHeaderParams } from './jws.js';
+
+/**
+ * JSON Web Encryption (JWE) Header Parameters
+ *
+ * The Header Parameter names for use in JWEs are registered in the IANA "JSON Web Signature and
+ * Encryption Header Parameters" registry.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1 | RFC 7516, Section 4.1}
+ */
+export interface JweHeaderParams extends JoseHeaderParams {
+  /**
+   * Algorithm Header Parameter
+   *
+   * Identifies the cryptographic algorithm used to encrypt or determine the value of the Content
+   * Encryption Key (CEK). The encrypted content is not usable if the "alg" value does not represent
+   * a supported algorithm, or if the recipient does not have a key that can be used with that
+   * algorithm.
+   *
+   * "alg" values should either be registered in the IANA "JSON Web Signature and Encryption
+   * Algorithms" registry or be a value that contains a Collision-Resistant Name. The "alg" value is
+   * a case-sensitive ASCII string.  This Header Parameter MUST be present and MUST be understood
+   * and processed by implementations.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.1 | RFC 7516, Section 4.1.1}
+   */
+  alg:
+    // AES Key Wrap with default initial value using 128-bit key
+    | 'A128KW'
+    // AES Key Wrap with default initial value using 192-bit key
+    | 'A192KW'
+    // AES Key Wrap with default initial value using 256-bit key
+    | 'A256KW'
+    // Direct use of a shared symmetric key as the CEK
+    | 'dir'
+    // Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF
+    | 'ECDH-ES'
+    // ECDH-ES using Concat KDF and CEK wrapped with "A128KW"
+    | 'ECDH-ES+A128KW'
+    // ECDH-ES using Concat KDF and CEK wrapped with "A192KW"
+    | 'ECDH-ES+A192KW'
+    // ECDH-ES using Concat KDF and CEK wrapped with "A256KW"
+    | 'ECDH-ES+A256KW'
+    // Key wrapping with AES GCM using 128-bit key
+    | 'A128GCMKW'
+    // Key wrapping with AES GCM using 192-bit key
+    | 'A192GCMKW'
+    // Key wrapping with AES GCM using 256-bit key
+    | 'A256GCMKW'
+    // PBES2 with HMAC SHA-256 and "A128KW" wrapping
+    | 'PBES2-HS256+A128KW'
+    // PBES2 with HMAC SHA-384 and "A192KW" wrapping
+    | 'PBES2-HS384+A192KW'
+    // PBES2 with HMAC SHA-512 and "A256KW" wrapping
+    | 'PBES2-HS512+A256KW'
+    // PBES2 with HMAC SHA-512 and "XC20PKW" wrapping
+    | 'PBES2-HS512+XC20PKW'
+    // an unregistered, case-sensitive, collision-resistant string
+    | string;
+
+  /**
+   * Agreement PartyUInfo Header Parameter
+   *
+   * The "apu" (agreement PartyUInfo) value is a base64url-encoded octet sequence containing
+   * information about the producer of the JWE.  This information is used by the recipient to
+   * determine the key agreement algorithm and key encryption algorithm to use to decrypt the JWE.
+   *
+   * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+   * that uses public key cryptography.
+   */
+  apu?: Uint8Array;
+
+  /**
+   * Agreement PartyVInfo Header Parameter
+   *
+   * The "apv" (agreement PartyVInfo) value is a base64url-encoded octet sequence containing
+   * information about the recipient of the JWE.  This information is used by the recipient to
+   * determine the key agreement algorithm and key encryption algorithm to use to decrypt the JWE.
+   *
+   * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+   * that uses public key cryptography.
+   */
+  apv?: Uint8Array;
+
+  /**
+   * Critical Header Parameter
+   *
+   * Indicates that extensions to JOSE RFCs are being used that MUST be understood and processed.
+   */
+  crit?: string[]
+
+  /**
+   * Encryption Algorithm Header Parameter
+   *
+   * Identifies the content encryption algorithm used to encrypt and integrity-protect (also
+   * known as "authenticated encryption") the plaintext and to integrity-protect the Additional
+   * Authenticated Data (AAD), if any.  This algorithm MUST be an AEAD algorithm with a specified
+   * key length.
+   *
+   * The encrypted content is not usable if the "enc" value does not represent a supported
+   * algorithm.  "enc" values should either be registered in the IANA "JSON Web Signature and
+   * Encryption Algorithms" registry or be a value that contains a Collision-Resistant Name. The
+   * "enc" value is a case-sensitive ASCII string containing a StringOrURI value. This Header
+   * Parameter MUST be present and MUST be understood and processed by implementations.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.2 | RFC 7516, Section 4.1.2}
+   */
+  enc:
+    // AES_128_CBC_HMAC_SHA_256 authenticated encryption algorithm,
+    // as defined in RFC 7518, Section 5.2.3
+    | 'A128CBC-HS256'
+    // AES_192_CBC_HMAC_SHA_384 authenticated encryption algorithm,
+    // as defined in RFC 7518, Section 5.2.4
+    | 'A192CBC-HS384'
+    // AES_256_CBC_HMAC_SHA_512 authenticated encryption algorithm,
+    // as defined in RFC 7518, Section 5.2.5
+    | 'A256CBC-HS512'
+    // AES GCM using 128-bit key
+    | 'A128GCM'
+    // AES GCM using 192-bit key
+    | 'A192GCM'
+    // AES GCM using 256-bit key
+    | 'A256GCM'
+    // XChaCha20-Poly1305 authenticated encryption algorithm
+    | 'XC20P'
+    // an unregistered, case-sensitive, collision-resistant string
+    | string;
+
+  /**
+   * Ephemeral Public Key Header Parameter
+   *
+   * The "epk" (ephemeral public key) value created by the originator for the use in key agreement
+   * algorithms.  It is the ephemeral public key that corresponds to the key used to encrypt the
+   * JWE.  This value is represented as a JSON Web Key (JWK).
+   *
+   * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+   * that uses public key cryptography.
+   */
+  epk?: Uint8Array;
+
+  /**
+   * Initialization Vector Header Parameter
+   *
+   * The "iv" (initialization vector) value is a base64url-encoded octet sequence used by the
+   * specified "enc" algorithm.  The length of this Initialization Vector value MUST be exactly
+   * equal to the value that would be produced by the "enc" algorithm.
+   *
+   * Note: With symmetric encryption algorithms such as AES GCM, this Header Parameter MUST
+   * be present and MUST be understood and processed by implementations.
+   */
+  iv?: Uint8Array;
+
+  /**
+   * PBES2 Count Header Parameter
+   *
+   * The "p2c" (PBES2 count) value is an integer indicating the number of iterations of the PBKDF2
+   * algorithm performed during key derivation.
+   *
+   * Note: The iteration count adds computational expense, ideally compounded by the possible range
+   * of keys introduced by the salt.  A minimum iteration count of 1000 is RECOMMENDED.
+   */
+  p2c?: number;
+
+  /**
+   * PBES2 Salt Input Header Parameter
+   *
+   * The "p2s" (PBES2 salt) value is a base64url-encoded octet sequence used as the salt value
+   * input to the PBKDF2 algorithm during key derivation.
+   *
+   * The salt value used is (UTF8(Alg) || 0x00 || Salt Input), where Alg is the "alg" (algorithm)
+   * Header Parameter value.
+   *
+   * Note: The salt value is used to ensure that each key derived from the master key is
+   * independent of every other key. A suitable source of salt value is a sequence of
+   * cryptographically random bytes containing 8 or more octets.
+   */
+  p2s?: string;
+
+  /**
+   * Authentication Tag Header Parameter
+   *
+   * The "tag" value is a base64url-encoded octet sequence containing the value of the
+   * Authentication Tag output by the specified "enc" algorithm.  The length of this
+   * Authentication Tag value MUST be exactly equal to the value that would be produced by the
+   * "enc" algorithm.
+   *
+   * Note: With authenticated encryption algorithms such as AES GCM, this Header Parameter MUST
+   * be present and MUST be understood and processed by implementations.
+   */
+  tag?: Uint8Array;
+
+  /**
+   * Additional Public or Private Header Parameter names.
+   */
+  [key: string]: unknown
+}