@enbox/crypto 0.0.1

package/src/types/key-compressor.ts

@@ -0,0 +1,25 @@
+/**
+ * `KeyCompressor` interface for converting public keys between compressed and uncompressed form.
+ */
+export interface KeyCompressor {
+
+  /**
+   * Converts a public key to its compressed form.
+   *
+   * @param params - The parameters for the public key compression.
+   * @param params.publicKeyBytes - The public key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the compressed public key as a Uint8Array.
+   */
+  compressPublicKey(params: { publicKeyBytes: Uint8Array }): Promise<Uint8Array>;
+
+  /**
+   * Converts a public key to its uncompressed form.
+   *
+   * @param params - The parameters for the public key decompression.
+   * @param params.publicKeyBytes - The public key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the uncompressed public key as a Uint8Array.
+   */
+  decompressPublicKey(params: { publicKeyBytes: Uint8Array }): Promise<Uint8Array>;
+}

package/src/types/key-converter.ts

@@ -0,0 +1,53 @@
+import type { Jwk } from '../jose/jwk.js';
+
+/**
+ * `KeyConverter` interface for converting private keys between byte array and JWK formats.
+ */
+export interface KeyConverter {
+
+  /**
+   * Converts a private key from a byte array to JWK format.
+   *
+   * @param params - The parameters for the private key conversion.
+   * @param params.privateKeyBytes - The raw private key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the private key in JWK format.
+   */
+  bytesToPrivateKey(params: { privateKeyBytes: Uint8Array }): Promise<Jwk>;
+
+  /**
+   * 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.
+   */
+  privateKeyToBytes(params: { privateKey: Jwk }): Promise<Uint8Array>;
+}
+
+/**
+ * `AsymmetricKeyConverter` interface extends {@link KeyConverter |`KeyConverter`}, adding support
+ * for public key conversions.
+ */
+export interface AsymmetricKeyConverter extends KeyConverter {
+  /**
+   * Converts a public key from a byte array to JWK format.
+   *
+   * @param params - The parameters for the public key conversion.
+   * @param params.publicKeyBytes - The raw public key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the public key in JWK format.
+   */
+  bytesToPublicKey(params: { publicKeyBytes: Uint8Array }): Promise<Jwk>;
+
+  /**
+   * Converts a public key from JWK format to a byte array.
+   *
+   * @param params - The parameters for the public key conversion.
+   * @param params.publicKey - The public key in JWK format.
+   *
+   * @returns A Promise that resolves to the public key as a Uint8Array.
+   */
+  publicKeyToBytes(params: { publicKey: Jwk }): Promise<Uint8Array>;
+}

package/src/types/key-deriver.ts

@@ -0,0 +1,43 @@
+/**
+ * The `KeyDeriver` interface provides methods for key derivation. It includes the methods
+ * `deriveBits()` to derive cryptographic bits and `deriveKey()` to derive JWK keys from input data
+ * using specific algorithms. This interface is designed to support various key derivation
+ * algorithms, accommodating different input and output types.
+ *
+ * Both methods return a Promise that resolves to the derived cryptographic material.
+ */
+export interface KeyDeriver<
+  DeriveBitsInput,
+  DeriveKeyInput,
+  DeriveKeyOutput
+> {
+  /**
+   * Generates a specified number of cryptographic bits from given input parameters.
+   *
+   * @remarks
+   * The `deriveBits()` method of the {@link KeyDeriver | `KeyDeriver`} interface is used to create
+   * cryptographic material such as initialization vectors or keys from various sources. The method
+   * takes in parameters specific to the chosen key derivation algorithm and outputs a promise that
+   * resolves to a `Uint8Array` containing the derived bits.
+   *
+   * @param params - The parameters for the bit derivation process, specific to the chosen algorithm.
+   *
+   * @returns A Promise resolving to the derived bits as a `Uint8Array`.
+   */
+  deriveBits(params: DeriveBitsInput): Promise<Uint8Array>;
+
+  /**
+   * Derives a cryptographic key in JWK format based on the provided input parameters.
+   *
+   * @remarks
+   * The `deriveKey()` method of the {@link KeyDeriver | `KeyDeriver`} interface is utilized to
+   * generate cryptographic keys for operations like encryption, decryption, or signing. The method
+   * takes in parameters tailored to the key derivation algorithm being used and returns a promise
+   * that resolves to the derived key.
+   *
+   * @param params - The parameters for the key derivation process, customized for the specific algorithm.
+   *
+   * @returns A Promise resolving to the derived key in the specified output format.
+   */
+  deriveKey(params: DeriveKeyInput): Promise<DeriveKeyOutput>;
+}

package/src/types/key-generator.ts

@@ -0,0 +1,119 @@
+import type { Jwk } from '../jose/jwk.js';
+
+/**
+ * The `KeyGenerator` interface provides a method for cryptographic key generation. It includes
+ * the `generateKey()` method to produce keys for cryptographic operations, supporting various
+ * algorithms and configurations. This interface is adaptable to different key generation
+ * requirements and can produce keys in formats such as JWK.
+ *
+ * The method returns a Promise that resolves to the generated key in the specified format.
+ */
+export interface KeyGenerator<
+  GenerateKeyInput,
+  GenerateKeyOutput
+> {
+  /**
+   * Generates a cryptographic key based on the provided parameters.
+   *
+   * @remarks
+   * The `generateKey()` method of the {@link KeyGenerator | `KeyGenerator`} interface generates
+   * private keys suitable for various cryptographic operations. This method can adapt to different
+   * key generation algorithms and input parameters.
+   *
+   * @param params - Optional parameters for the key generation process, specific to the chosen
+   *                 algorithm.
+   *
+   * @returns A Promise resolving to the generated private key in the specified output format.
+   */
+  generateKey(params?: GenerateKeyInput): Promise<GenerateKeyOutput>;
+}
+
+/**
+ * The `AsymmetricKeyGenerator` interface extends {@link KeyGenerator | `KeyGenerator`}, adding
+ * methods specific to asymmetric public keys. It supports generating asymmetric private keys and
+ * obtaining the public key from a private key.
+ *
+ * This interface is designed for asymmetric cryptographic operations where both public and private
+ * keys are used.
+ */
+export interface AsymmetricKeyGenerator<
+  GenerateKeyInput,
+  GenerateKeyOutput,
+  GetPublicKeyInput
+> extends KeyGenerator<GenerateKeyInput, GenerateKeyOutput> {
+  /**
+   * Optional method that mathetmatically derives the public key in JWK format from a given private
+   * key.
+   *
+   * @param params - The parameters for public key computation.
+   *
+   * @returns A Promise resolving to the public key in JWK format.
+   */
+  computePublicKey?(params: GetPublicKeyInput): Promise<Jwk>;
+
+  /**
+   * Extracts the public key portion from the given public key in JWK format.
+   *
+   * @remarks
+   * Unlike `computePublicKey()`, the `getPublicKey()` method 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 JWK object. This makes it suitable for
+   * scenarios where speed is critical and the private key's integrity is already assured.
+   *
+   * @param params - The parameters for public key retrieval.
+   *
+   * @returns A Promise resolving to the public key in JWK format.
+   */
+  getPublicKey(params: GetPublicKeyInput): Promise<Jwk>;
+}
+
+/**
+ * Infers the supported algorithm type from the `generateKey` method of a key generator.
+ *
+ * @remarks
+ * The `InferKeyGeneratorAlgorithm` utility type extracts the algorithm type from the input
+ * parameters of the `generateKey` method implemented in a key generator. This type is useful when
+ * working with various cryptographic key generators, as it enables TypeScript to infer the
+ * supported algorithms based on the key generator's implementation. This inference ensures type
+ * safety and improves developer experience by providing relevant suggestions and checks for the
+ * supported algorithms during development.
+ *
+ * This utility type can be particularly advantageous in contexts where the specific key generator
+ * may vary, but the code needs to adapt dynamically based on the supported algorithms of the
+ * provided key generator instance.
+ *
+ * @example
+ * ```ts
+ * export interface MyKmsGenerateKeyParams extends KmsGenerateKeyParams {
+ *  algorithm: 'Ed25519' | 'secp256k1';
+ * }
+ *
+ * class MyKms implements KeyGenerator<MyKmsGenerateKeyParams, Jwk> {
+ *   generateKey(params: MyKmsGenerateKeyParams): Promise<Jwk> {
+ *     // Implementation for generating a key...
+ *   }
+ * }
+ *
+ * type SupportedAlgorithms = InferKeyGeneratorAlgorithm<MyKms>;
+ * // `SupportedAlgorithms` will be inferred as 'Ed25519' | 'secp256k1'
+ * ```
+ *
+ * @template T - The type of the key generator from which to infer the algorithm type.
+ */
+export type InferKeyGeneratorAlgorithm<T> = T extends {
+    /**
+     * The `generateKey` method signature from which the algorithm type is inferred.
+     * This is an internal implementation detail and not part of the public API.
+     */
+    generateKey(params: infer P): any;
+  }
+  ? P extends {
+      /**
+       * The `algorithm` property within the parameters of `generateKey`.
+       * This internal element is used to infer the algorithm type.
+       */
+      algorithm: infer A
+    }
+    ? A
+    : never
+  : never;

package/src/types/key-io.ts

@@ -0,0 +1,42 @@
+import type { Jwk } from '../jose/jwk.js';
+
+/**
+ * The `KeyImporterExporter` interface provides methods for importing and exporting cryptographic
+ * keys. It includes `importKey()` for importing external keys, and `exportKey()` for exporting a
+ * cryptographic key to an external JWK object.
+ *
+ * This interface is designed to handle various key formats and is adaptable for different
+ * cryptographic environments and requirements.
+ */
+export interface KeyImporterExporter<
+  ImportKeyInput,
+  ImportKeyOutput,
+  ExportKeyInput
+> {
+  /**
+   * Exports a cryptographic key to an external JWK object.
+   *
+   * @remarks
+   * The `exportKey()` method of the {@link KeyImporterExporter | `KeyImporterExporter`} interface
+   * returns a cryptographic key in JWK format, facilitating interoperability and backup.
+   *
+   * @param params - The parameters for the key export operation.
+   *
+   * @returns A Promise resolving to the exported key in JWK format.
+   */
+  exportKey(params: ExportKeyInput): Promise<Jwk>;
+
+  /**
+   * Imports an external key in JWK format.
+   *
+   * @remarks
+   * The `importKey()` method of the {@link KeyImporterExporter | `KeyImporterExporter`} interface
+   * takes as input an external key in JWK format and typically returns a key identifier reference
+   * for the imported key.
+   *
+   * @param params - The parameters for the key import operation.
+   *
+   * @returns A Promise resolving to the key identifier of the imported key.
+   */
+  importKey(params: ImportKeyInput): Promise<ImportKeyOutput>;
+}

package/src/types/key-wrapper.ts

@@ -0,0 +1,42 @@
+import type { Jwk } from '../jose/jwk.js';
+
+/**
+ * The `KeyWrapper` interface provides methods for wrapping and unwrapping cryptographic keys.
+ * It includes `wrapKey()` for securely encapsulating a key within another key, and `unwrapKey()`
+ * for extracting the original key from its wrapped state.
+ *
+ * This interface is crucial in scenarios where secure key management and exchange are required,
+ * ensuring that keys remain protected during transit or storage.
+ */
+export interface KeyWrapper<
+  WrapKeyInput,
+  UnwrapKeyInput
+> {
+  /**
+   * Wraps a cryptographic key using another key, typically for secure key transmission or storage.
+   *
+   * @remarks
+   * The `wrapKey()` method of the {@link KeyWrapper | `KeyWrapper`} interface secures a
+   * cryptographic key by encapsulating it within another key, producing a wrapped key represented
+   * as a `Uint8Array`.
+   *
+   * @param params - The parameters for the key wrapping operation.
+   *
+   * @returns A Promise resolving to the wrapped key as a `Uint8Array`.
+   */
+  wrapKey(params: WrapKeyInput): Promise<Uint8Array>;
+
+  /**
+   * Unwraps a previously wrapped cryptographic key, restoring it to its original form.
+   *
+   * @remarks
+   * The `unwrapKey()` method of the {@link KeyWrapper | `KeyWrapper`} interface reverses the
+   * wrapping process, extracting the original key from its wrapped state, typically for use in
+   * cryptographic operations.
+   *
+   * @param params - The parameters for the key unwrapping operation.
+   *
+   * @returns A Promise resolving to the unwrapped key in a cryptographic format, usually JWK.
+   */
+  unwrapKey(params: UnwrapKeyInput): Promise<Jwk>;
+}

package/src/types/params-direct.ts

@@ -0,0 +1,106 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { AlgorithmIdentifier } from './identifier.js';
+
+/**
+ * Parameters for computing a public key.
+ */
+export interface ComputePublicKeyParams extends GetPublicKeyParams { }
+
+/**
+ * Parameters for decrypting data.
+ */
+export interface DecryptParams {
+  /** A {@link Jwk} containing the key to be used for decryption. */
+  key: Jwk;
+
+  /** Data to be decrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for deriving bits.
+ */
+export interface DeriveBitsParams {
+  /** A {@link Jwk} containing the base key to be used for derivation. */
+  key: Jwk;
+
+  /**
+   * The number of bits to derive. To be compatible with all browsers, the number should be a
+   * multiple of 8.
+   */
+  length: number;
+}
+
+/**
+ * Parameters for deriving a key.
+ */
+export interface DeriveKeyParams {
+  /** A {@link Jwk} containing the base key to be used for derivation. */
+  key: Jwk;
+
+  /** An object defining the algorithm-specific parameters for the derived key. */
+  derivedKeyParams: unknown
+}
+
+/**
+ * Parameters for computing a hash digest.
+ */
+export interface DigestParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+
+  /** Data to be digested. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for encrypting data.
+ */
+export interface EncryptParams {
+  /** A {@link Jwk} containing the key to be used for encryption. */
+  key: Jwk;
+
+  /** Data to be encrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for generating a key.
+ */
+export interface GenerateKeyParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+}
+
+/**
+ * Parameters for retrieving a public key.
+ */
+export interface GetPublicKeyParams {
+  /** A {@link Jwk} containing the key from which to derive the public key. */
+  key: Jwk;
+}
+
+/**
+ * Parameters for signing data.
+ */
+export interface SignParams {
+  /** A {@link Jwk} containing the key used for signing. */
+  key: Jwk;
+
+  /** Data to be signed. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for verifying a signature.
+ */
+export interface VerifyParams {
+  /** A {@link Jwk} containing the key used for verification. */
+  key: Jwk;
+
+  /** The signature to verify. */
+  signature: Uint8Array;
+
+  /** The data associated with the signature. */
+  data: Uint8Array;
+}

package/src/types/params-enclosed.ts

@@ -0,0 +1,50 @@
+/**
+ * Parameters for enclosed decryption operations.
+ *
+ * Note: This interface is intended to be used with a closure that captures the key and
+ * algorithm-specific parameters so that arbitrary data can be decrypted without exposing the key or
+ * parameters to the caller.
+ */
+export interface EnclosedDecryptParams {
+  /** Data to be decrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for enclosed encryption operations.
+ *
+ * Note: This interface is intended to be used with a closure that captures the key and
+ * algorithm-specific parameters so that arbitrary data can be encrypted without exposing the key or
+ * parameters to the caller.
+ */
+export interface EnclosedEncryptParams {
+  /** Data to be encrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for enclosed signing operations.
+ *
+ * Note: This interface is intended to be used with a closure that captures the key and
+ * algorithm-specific parameters so that arbitrary data can be signed without exposing the key or
+ * parameters to the caller.
+ */
+export interface EnclosedSignParams {
+  /** Data to be signed. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for enclosed verification operations.
+ *
+ * Note: This interface is intended to be used with a closure that captures the key and
+ * algorithm-specific parameters so that signatures of arbitrary data can be verified without
+ * exposing the key or parameters to the caller.
+ */
+export interface EnclosedVerifyParams {
+  /** Signature to be verified. */
+  signature: Uint8Array;
+
+  /** Data associated with the signature. */
+  data: Uint8Array;
+}

package/src/types/params-kms.ts

@@ -0,0 +1,156 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { AlgorithmIdentifier, KeyIdentifier } from './identifier.js';
+
+/**
+ * Parameters for KMS-based decryption operations. Intended for use with a Key Management System.
+ */
+export interface KmsDecryptParams {
+  /** Identifier for the private key in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** Data to be decrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for KMS-based derivation of bits. Intended for use with a Key Management System.
+ */
+export interface KmsDeriveBitsParams {
+  /** Identifier for the key used in derivation in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /**
+   * The number of bits to derive. To be compatible with all browsers, the number should be a
+   * multiple of 8.
+   */
+  length: number;
+}
+
+/**
+ * Parameters for KMS-based key derivation. Intended for use with a Key Management System.
+ */
+export interface KmsDeriveKeyParams {
+  /** Identifier for the base key used in derivation in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** An object defining the algorithm-specific parameters for the derived key. */
+  derivedKeyParams: unknown
+}
+
+/**
+ * Parameters for KMS-based digest computation. Intended for use with a Key Management System.
+ */
+export interface KmsDigestParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+
+  /** Data to be digested. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for KMS-based encryption operations. Intended for use with a Key Management System.
+ */
+export interface KmsEncryptParams {
+  /** Identifier for the private key in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** Data to be encrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for exporting a key from a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsExportKeyParams {
+  /** Identifier for the private key to be exported from the KMS. */
+  keyUri: KeyIdentifier;
+}
+
+/**
+ * Parameters for generating a key in a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsGenerateKeyParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+}
+
+/**
+ * Parameters for computing the Key URI of a public key. Intended for use with a Key Management
+ * System.
+ */
+export interface KmsGetKeyUriParams {
+  /** A {@link Jwk} containing the public key for which the Key URI will be computed. */
+  key: Jwk;
+}
+
+/**
+ * Parameters for retrieving a public key from a KMS using the private key's URI. Intended for use
+ * with a Key Management System.
+ */
+export interface KmsGetPublicKeyParams {
+  /** Identifier for the private key in the KMS. */
+  keyUri: KeyIdentifier;
+}
+
+/**
+ * Parameters for importing a private key into a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsImportKeyParams {
+  /** A {@link Jwk} containing the key to be imported into the KMS. */
+  key: Jwk;
+}
+
+/**
+ * Parameters for KMS-based signing operations. Intended for use with a Key Management System.
+ */
+export interface KmsSignParams {
+  /** Identifier for the signing private key in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** Data to be signed. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for verifying a signature using a key from a KMS. Intended for use with a Key
+ * Management System.
+ */
+export interface KmsVerifyParams {
+  /** A {@link Jwk} containing the public key to be used for verification. */
+  key: Jwk;
+
+  /** The signature to verify. */
+  signature: Uint8Array;
+
+  /** The data associated with the signature. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for wrapping a key using a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsWrapKeyParams {
+  /** A {@link Jwk} containing the private key to be wrapped. */
+  key: Jwk;
+
+  /** Identifier for the private key in the KMS to be used for the wrapping operation. */
+  wrappingKeyId: KeyIdentifier;
+
+  /** Algorithm to be used for wrapping. */
+  wrapAlgorithm: AlgorithmIdentifier;
+}
+
+/**
+ * Parameters for unwrapping a key using a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsUnwrapKeyParams {
+  /** The wrapped key in a byte array. */
+  wrappedKey: Uint8Array;
+
+  /** Identifier for the private key in the KMS to be used for the unwrapping operation. */
+  unwrappingKeyId: KeyIdentifier;
+
+  /** Algorithm to be used for unwrapping. */
+  unwrapAlgorithm: AlgorithmIdentifier;
+}

package/src/types/signer.ts

@@ -0,0 +1,50 @@
+import type { EnclosedSignParams, EnclosedVerifyParams } from './params-enclosed.js';
+
+/**
+ * The `Signer` interface provides methods for signing data and verifying signatures.
+ *
+ * It includes `sign()` for creating signatures and `verify()` for confirming the validity of
+ * signatures. The interface is designed to be flexible, accommodating various signing algorithms
+ * and their unique parameters.
+ *
+ * It defaults to using {@link EnclosedSignParams | `EnclosedSignParams`} and
+ * {@link EnclosedVerifyParams | `EnclosedVerifyParams`}, which are intended to be used with a
+ * closure that captures the key and algorithm-specific parameters so that arbitrary data can be
+ * signed and verified without exposing the key or parameters to the caller. However, the
+ * interface can be extended to support other parameter types, such as {@link SignParams |
+* `SignParams`} and {@link VerifyParams | `VerifyParams`}, which are intended to be used when
+* the key and algorithm-specific parameters are known to the caller.
+ */
+export interface Signer<
+  SignInput = EnclosedSignParams,
+  VerifyInput = EnclosedVerifyParams
+> {
+  /**
+   * Signs the provided data.
+   *
+   * @remarks
+   * The `sign()` method of the {@link Signer | `Signer`} interface generates a digital signature
+   * for the given data using a cryptographic key. This signature can be used to verify the data's
+   * authenticity and integrity.
+   *
+   * @param params - The parameters for the signing operation.
+   *
+   * @returns A Promise resolving to the digital signature as a `Uint8Array`.
+   */
+  sign(params: SignInput): Promise<Uint8Array>;
+
+  /**
+   * Verifies a digital signature associated the provided data.
+   *
+   * @remarks
+   * The `verify()` method of the {@link Signer | `Signer`} interface checks the validity of a
+   * digital signature against the original data and a cryptographic key. It confirms whether the
+   * signature was created by the holder of the corresponding private key and that the data has not
+   * been tampered with.
+   *
+   * @param params - The parameters for the verification operation.
+   *
+   * @returns A Promise resolving to a boolean indicating whether the signature is valid.
+   */
+  verify(params: VerifyInput): Promise<boolean>;
+}