@enbox/crypto 0.0.2 → 0.0.4

package/src/types/params-direct.ts

@@ -1,11 +1,49 @@
-import type { Jwk } from '../jose/jwk.js';
 import type { AlgorithmIdentifier } from './identifier.js';
+import type { Jwk } from '../jose/jwk.js';
+
+/**
+ * Parameters for converting raw private key bytes to a JWK.
+ */
+export interface BytesToPrivateKeyParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+
+  /** The raw private key bytes. */
+  privateKeyBytes: Uint8Array;
+}
+
+/**
+ * Parameters for converting raw public key bytes to a JWK.
+ */
+export interface BytesToPublicKeyParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+
+  /** The raw public key bytes. */
+  publicKeyBytes: Uint8Array;
+}
 
 /**
  * Parameters for computing a public key.
  */
 export interface ComputePublicKeyParams extends GetPublicKeyParams { }
 
+/**
+ * Parameters for encryption and decryption operations.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface CipherParams {
+  /** A {@link Jwk} containing the key to be used for encryption or decryption. */
+  key: Jwk;
+
+  /** Data to be encrypted or decrypted. */
+  data: Uint8Array;
+
+  /** Additional algorithm-specific parameters for encryption or decryption. */
+  [key: string]: unknown;
+}
+
 /**
  * Parameters for decrypting data.
  */
@@ -42,6 +80,38 @@ 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.
+ */
+export interface DeriveKeyBytesParams {
+  /** The base key to be used for derivation as a byte array. */
+  baseKeyBytes: Uint8Array;
+
+  /** The desired length of the derived key in bits. */
+  length: number;
+}
+
 /**
  * Parameters for computing a hash digest.
  */
@@ -91,6 +161,39 @@ export interface SignParams {
   data: Uint8Array;
 }
 
+/**
+ * Parameters for converting a private key JWK to raw bytes.
+ */
+export interface PrivateKeyToBytesParams {
+  /** The private key in JWK format. */
+  privateKey: Jwk;
+}
+
+/**
+ * Parameters for converting a public key JWK to raw bytes.
+ */
+export interface PublicKeyToBytesParams {
+  /** The public key in JWK format. */
+  publicKey: Jwk;
+}
+
+/**
+ * Parameters for unwrapping a key.
+ */
+export interface UnwrapKeyParams {
+  /** A {@link Jwk} containing the key used to decrypt the unwrapped key. */
+  decryptionKey: Jwk;
+
+  /** 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 verifying a signature.
  */
@@ -103,4 +206,18 @@ export interface VerifyParams {
 
   /** The data associated with the signature. */
   data: Uint8Array;
+}
+
+/**
+ * Parameters for wrapping a key.
+ */
+export interface WrapKeyParams {
+  /** A {@link Jwk} containing the key used to encrypt the unwrapped key. */
+  encryptionKey: Jwk;
+
+  /** 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;
 }

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';
@@ -158,7 +161,7 @@ export class CryptoUtils {
       const rejectionRange = Math.pow(10, length);
       do {
         // Adjust the byte generation based on length.
-        const randomBuffer = CryptoUtils.randomBytes(Math.ceil(length / 2) );  // 2 digits per byte.
+        const randomBuffer = CryptoUtils.randomBytes(Math.ceil(length / 2) ); // 2 digits per byte.
         const view = new DataView(randomBuffer.buffer);
         // Convert the buffer to integer and take modulus based on length.
         pin = view.getUint16(0, false) % rejectionRange;
@@ -172,10 +175,60 @@ export class CryptoUtils {
         const view = new DataView(randomBuffer.buffer);
         // Transform bytes to number (big endian).
         pin = view.getUint32(0, false) % rejectionRange;
-      } while (pin > max);  // Reject if the number is outside the desired range.
+      } while (pin > max); // Reject if the number is outside the desired range.
     }
 
     // Pad the PIN with leading zeros to the desired length.
     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'
+  );
+}