@enbox/crypto 0.0.3 → 0.0.4

package/src/types/key-deriver.ts

@@ -40,4 +40,53 @@ export interface KeyDeriver<
    * @returns A Promise resolving to the derived key in the specified output format.
    */
   deriveKey(params: DeriveKeyInput): Promise<DeriveKeyOutput>;
+}
+
+/**
+ * The `SimpleKeyDeriver` interface provides a single `deriveKey()` method for key derivation,
+ * without the `deriveBits()` method that {@link KeyDeriver} includes.
+ *
+ * This is useful for implementations that only need key derivation (not raw bit derivation).
+ */
+export interface SimpleKeyDeriver<
+  DeriveKeyInput,
+  DeriveKeyOutput,
+> {
+  /**
+   * Derives a cryptographic key based on the provided input parameters.
+   *
+   * @param params - The parameters for the key derivation process.
+   *
+   * @returns A Promise resolving to the derived key in the specified output format.
+   */
+  deriveKey(params: DeriveKeyInput): Promise<DeriveKeyOutput>;
+}
+
+/**
+ * The `KeyBytesDeriver` interface provides a method for deriving a byte array using a key
+ * derivation algorithm.
+ *
+ * The `deriveKeyBytes()` method derives cryptographic bits from input data using the specified
+ * key derivation algorithm. This interface is designed to support various key derivation
+ * algorithms, accommodating different input and output types.
+ */
+export interface KeyBytesDeriver<
+  DeriveKeyBytesInput,
+  DeriveKeyBytesOutput
+> {
+  /**
+   * Generates a specified number of cryptographic bits from given input parameters.
+   *
+   * @remarks
+   * The `deriveKeyBytes()` method of the {@link KeyBytesDeriver | `KeyBytesDeriver`} 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 key derivation process, specific to the chosen
+   *                 algorithm.
+   *
+   * @returns A Promise resolving to the derived bits in the specified format.
+   */
+  deriveKeyBytes(params: DeriveKeyBytesInput): Promise<DeriveKeyBytesOutput>;
 }

package/src/types/key-io.ts

@@ -39,4 +39,44 @@ export interface KeyImporterExporter<
    * @returns A Promise resolving to the key identifier of the imported key.
    */
   importKey(params: ImportKeyInput): Promise<ImportKeyOutput>;
+}
+
+/**
+ * The `KeyExporter` interface provides a method for exporting cryptographic keys.
+ */
+export interface KeyExporter<ExportKeyInput, ExportKeyOutput = Jwk> {
+  /**
+   * Exports a cryptographic key to an external JWK object.
+   *
+   * @param params - The parameters for the key export operation.
+   *
+   * @returns A Promise resolving to the exported key in JWK format.
+   */
+  exportKey(params: ExportKeyInput): Promise<ExportKeyOutput>;
+}
+
+/**
+ * The `KeyImporter` interface provides a method for importing cryptographic keys.
+ */
+export interface KeyImporter<ImportKeyInput, ImportKeyOutput = void> {
+  /**
+   * Imports an external key in JWK format.
+   *
+   * @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>;
+}
+
+/**
+ * The `KeyDeleter` interface provides a method for deleting cryptographic keys.
+ */
+export interface KeyDeleter<DeleteKeyInput> {
+  /**
+   * Deletes a cryptographic key from the key store.
+   *
+   * @param params - The parameters for the key deletion operation.
+   */
+  deleteKey(params: DeleteKeyInput): Promise<void>;
 }

package/src/types/params-direct.ts

@@ -80,6 +80,27 @@ export interface DeriveKeyParams {
   derivedKeyParams: unknown
 }
 
+/**
+ * Parameters for deriving a key from raw byte-based key material.
+ *
+ * Unlike {@link DeriveKeyParams} which operates on JWK keys, this interface works with raw
+ * byte arrays as the base key input, making it suitable for agent-level key derivation where
+ * keys originate from passphrases, seed phrases, or other byte-oriented sources.
+ */
+export interface DeriveKeyFromBytesParams {
+  /** The algorithm identifier. */
+  algorithm: string;
+
+  /** The base key to be used for derivation as a byte array. */
+  baseKeyBytes: Uint8Array;
+
+  /** The algorithm identifier for the derived key. */
+  derivedKeyAlgorithm?: string;
+
+  /** Additional algorithm-specific parameters for key derivation. */
+  [key: string]: unknown;
+}
+
 /**
  * Parameters for derivation of cryptographic byte arrays.
  */

package/src/types/params-kms.ts

@@ -153,4 +153,71 @@ export interface KmsUnwrapKeyParams {
 
   /** Algorithm to be used for unwrapping. */
   unwrapAlgorithm: AlgorithmIdentifier;
+}
+
+/**
+ * Parameters for KMS-based encryption and decryption operations.
+ *
+ * Intended for use with a Key Management System where the key is referenced by URI.
+ */
+export interface KmsCipherParams {
+  /** Identifier for the private key in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** Data to be encrypted or decrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for KMS-based derivation of a byte array from a given base key.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface KmsDeriveKeyBytesParams {
+  /** Identifier for the base key used in derivation in the KMS. */
+  baseKeyUri: KeyIdentifier;
+
+  /** The desired length of the derived key in bits. */
+  length: number;
+}
+
+/**
+ * Parameters for KMS-based key unwrapping. Intended for use with a Key Management System where
+ * the decryption key is referenced by URI.
+ */
+export interface KmsUriUnwrapKeyParams {
+  /** Identifier for the private key in the KMS used for decrypting the wrapped key. */
+  decryptionKeyUri: KeyIdentifier;
+
+  /** The wrapped private key as a byte array. */
+  wrappedKeyBytes: Uint8Array;
+
+  /** The algorithm identifier of the key encrypted in `wrappedKeyBytes`. */
+  wrappedKeyAlgorithm: string;
+
+  /** An object defining the algorithm-specific parameters for decrypting the `wrappedKeyBytes`. */
+  decryptParams?: unknown;
+}
+
+/**
+ * Parameters for KMS-based key wrapping. Intended for use with a Key Management System where
+ * the encryption key is referenced by URI.
+ */
+export interface KmsUriWrapKeyParams {
+  /** Identifier for the private key in the KMS used for encrypting the unwrapped key. */
+  encryptionKeyUri: KeyIdentifier;
+
+  /** A {@link Jwk} containing the private key to be wrapped. */
+  unwrappedKey: Jwk;
+
+  /** An object defining the algorithm-specific parameters for encrypting the `unwrappedKey`. */
+  encryptParams?: unknown;
+}
+
+/**
+ * Parameters for KMS-based key deletion. Intended for use with a Key Management System.
+ */
+export interface KmsDeleteKeyParams {
+  /** Identifier for the key to be deleted in the KMS. */
+  keyUri: KeyIdentifier;
 }

package/src/utils.ts

@@ -1,4 +1,7 @@
+import type { Cipher } from './types/cipher.js';
 import type { Jwk } from './jose/jwk.js';
+import type { KeyWrapper } from './types/key-wrapper.js';
+import type { KeyExporter, KeyImporter } from './types/key-io.js';
 
 import { crypto } from '@noble/hashes/crypto';
 import { randomBytes as nobleRandomBytes } from '@noble/hashes/utils';
@@ -179,3 +182,53 @@ export class CryptoUtils {
     return pin.toString().padStart(length, '0');
   }
 }
+
+/**
+ * Type guard that checks whether the given object implements the {@link Cipher} interface.
+ */
+export function isCipher<EncryptInput, DecryptInput>(
+  obj: unknown
+): obj is Cipher<EncryptInput, DecryptInput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'encrypt' in obj && typeof obj.encrypt === 'function'
+    && 'decrypt' in obj && typeof obj.decrypt === 'function'
+  );
+}
+
+/**
+ * Type guard that checks whether the given object implements the {@link KeyExporter} interface.
+ */
+export function isKeyExporter<ExportKeyInput, ExportKeyOutput>(
+  obj: unknown
+): obj is KeyExporter<ExportKeyInput, ExportKeyOutput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'exportKey' in obj && typeof obj.exportKey === 'function'
+  );
+}
+
+/**
+ * Type guard that checks whether the given object implements the {@link KeyImporter} interface.
+ */
+export function isKeyImporter<ImportKeyInput, ImportKeyOutput>(
+  obj: unknown
+): obj is KeyImporter<ImportKeyInput, ImportKeyOutput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'importKey' in obj && typeof obj.importKey === 'function'
+  );
+}
+
+/**
+ * Type guard that checks whether the given object implements the {@link KeyWrapper} interface.
+ */
+export function isKeyWrapper<WrapKeyInput, UnwrapKeyInput>(
+  obj: unknown
+): obj is KeyWrapper<WrapKeyInput, UnwrapKeyInput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'wrapKey' in obj && typeof obj.wrapKey === 'function'
+    && 'unwrapKey' in obj && typeof obj.unwrapKey === 'function'
+  );
+}