@catbee/utils 2.0.1 → 2.0.3

package/crypto/index.cjs

@@ -56,6 +56,287 @@ function md5(input) {
   return hash("md5", input);
 }
 __name(md5, "md5");
+var DEFAULT_SIGNATURE_ENCODING = "base64url";
+var subtle = globalThis.crypto?.subtle ?? crypto.webcrypto.subtle;
+function getDigestLength(hash2) {
+  switch (hash2) {
+    case "SHA-256":
+      return 32;
+    case "SHA-384":
+      return 48;
+    case "SHA-512":
+      return 64;
+    default:
+      return 32;
+  }
+}
+__name(getDigestLength, "getDigestLength");
+function resolveKeyAlgorithm({ type = "RSA-PSS", modulusLength = 2048, hash: hash2 = "SHA-256", namedCurve = "P-256" }) {
+  switch (type) {
+    case "RSA":
+      if (!Number.isInteger(modulusLength) || modulusLength < 2048) {
+        throw new Error("RSA modulusLength must be an integer greater than or equal to 2048");
+      }
+      return {
+        name: "RSASSA-PKCS1-v1_5",
+        modulusLength,
+        publicExponent: new Uint8Array([
+          1,
+          0,
+          1
+        ]),
+        hash: hash2
+      };
+    case "RSA-PSS":
+      if (!Number.isInteger(modulusLength) || modulusLength < 2048) {
+        throw new Error("RSA-PSS modulusLength must be an integer greater than or equal to 2048");
+      }
+      return {
+        name: "RSA-PSS",
+        modulusLength,
+        publicExponent: new Uint8Array([
+          1,
+          0,
+          1
+        ]),
+        hash: hash2
+      };
+    case "ECDSA":
+      return {
+        name: "ECDSA",
+        namedCurve
+      };
+    case "Ed25519":
+      return {
+        name: "Ed25519"
+      };
+    default:
+      throw new Error(`Unsupported key type: ${type}. Supported types: RSA, RSA-PSS, ECDSA, Ed25519`);
+  }
+}
+__name(resolveKeyAlgorithm, "resolveKeyAlgorithm");
+function toBase64(buffer) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(buffer).toString("base64");
+  }
+  let binary = "";
+  const bytes = new Uint8Array(buffer);
+  const chunkSize = 32768;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+  }
+  return btoa(binary);
+}
+__name(toBase64, "toBase64");
+function toPEM(base64, type, formatPemLines, addPrefixSuffix) {
+  const formattedBase64 = formatPemLines ? base64.match(/.{1,64}/g)?.join("\n") ?? base64 : base64;
+  if (!addPrefixSuffix) {
+    return formattedBase64;
+  }
+  const prefix = `-----BEGIN ${type}-----`;
+  const suffix = `-----END ${type}-----`;
+  return `${prefix}
+${formattedBase64}
+${suffix}`;
+}
+__name(toPEM, "toPEM");
+function fromPEM(pem) {
+  const trimmedPem = pem.trim();
+  const format = trimmedPem.includes("BEGIN PRIVATE KEY") ? "pkcs8" : trimmedPem.includes("BEGIN PUBLIC KEY") ? "spki" : void 0;
+  if (!format) {
+    throw new Error("Unsupported PEM format. Expected PUBLIC KEY or PRIVATE KEY PEM block");
+  }
+  const base64 = trimmedPem.replace(/-----BEGIN [A-Z ]+-----/g, "").replace(/-----END [A-Z ]+-----/g, "").replace(/\s+/g, "");
+  return {
+    format,
+    binary: toArrayBuffer(Buffer.from(base64, "base64"))
+  };
+}
+__name(fromPEM, "fromPEM");
+function toBinary(data, encoding = "utf8") {
+  if (typeof data === "string") {
+    return Uint8Array.from(Buffer.from(data, encoding));
+  }
+  if (Buffer.isBuffer(data)) {
+    return Uint8Array.from(data);
+  }
+  return data;
+}
+__name(toBinary, "toBinary");
+function toArrayBuffer(data) {
+  const byteView = data instanceof Uint8Array ? data : Uint8Array.from(data);
+  const copy = new Uint8Array(byteView.byteLength);
+  copy.set(byteView);
+  return copy.buffer;
+}
+__name(toArrayBuffer, "toArrayBuffer");
+function inferKeyTypeFromJwk(jwk, fallback) {
+  if (fallback) {
+    return fallback;
+  }
+  const keyType = typeof jwk.kty === "string" ? jwk.kty : void 0;
+  const curve = typeof jwk.crv === "string" ? jwk.crv : void 0;
+  const algorithm = typeof jwk.alg === "string" ? jwk.alg : void 0;
+  if (keyType === "OKP" && curve === "Ed25519") {
+    return "Ed25519";
+  }
+  if (keyType === "EC") {
+    return "ECDSA";
+  }
+  if (keyType === "RSA") {
+    return algorithm?.startsWith("PS") ? "RSA-PSS" : "RSA";
+  }
+  throw new Error("Unable to infer key type from JWK. Provide import options with an explicit type");
+}
+__name(inferKeyTypeFromJwk, "inferKeyTypeFromJwk");
+function resolveDefaultUsages(format, usages) {
+  return usages ?? (format === "pkcs8" ? [
+    "sign"
+  ] : [
+    "verify"
+  ]);
+}
+__name(resolveDefaultUsages, "resolveDefaultUsages");
+function inferJwkUsages(jwk, usages) {
+  if (usages) {
+    return usages;
+  }
+  if (Array.isArray(jwk.key_ops)) {
+    const inferredFromKeyOps = jwk.key_ops.filter((usage) => usage === "sign" || usage === "verify");
+    if (inferredFromKeyOps.length === 0) {
+      throw new Error("JWK key_ops must include at least one of sign or verify when provided");
+    }
+    return inferredFromKeyOps;
+  }
+  if (typeof jwk.d === "string" && jwk.d.length > 0) {
+    return [
+      "sign"
+    ];
+  }
+  return [
+    "verify"
+  ];
+}
+__name(inferJwkUsages, "inferJwkUsages");
+function resolveSignAlgorithm(key, options = {}) {
+  const hash2 = options.hash ?? "SHA-256";
+  switch (key.algorithm.name) {
+    case "RSASSA-PKCS1-v1_5":
+      return "RSASSA-PKCS1-v1_5";
+    case "RSA-PSS": {
+      const keyAlgorithm = key.algorithm;
+      const pssHash = options.hash ?? keyAlgorithm.hash.name;
+      return {
+        name: "RSA-PSS",
+        saltLength: options.saltLength ?? getDigestLength(pssHash)
+      };
+    }
+    case "ECDSA":
+      return {
+        name: "ECDSA",
+        hash: hash2
+      };
+    case "Ed25519":
+      return "Ed25519";
+    default:
+      throw new Error(`Unsupported signing key algorithm: ${key.algorithm.name}`);
+  }
+}
+__name(resolveSignAlgorithm, "resolveSignAlgorithm");
+function arrayBufferToBuffer(buffer) {
+  return Buffer.from(buffer);
+}
+__name(arrayBufferToBuffer, "arrayBufferToBuffer");
+async function generateKeys(options = {}) {
+  const { type = "RSA-PSS", modulusLength = 2048, hash: hash2 = "SHA-256", namedCurve = "P-256", extractable = false, includeCryptoKeys = false, formatPemLines = true, addPrefixSuffix = true } = options;
+  const algorithm = resolveKeyAlgorithm({
+    type,
+    modulusLength,
+    hash: hash2,
+    namedCurve
+  });
+  const usages = [
+    "sign",
+    "verify"
+  ];
+  const keyPair = await subtle.generateKey(algorithm, extractable, usages);
+  const [publicKeyBuf, privateKeyBuf] = await Promise.all([
+    subtle.exportKey("spki", keyPair.publicKey),
+    extractable ? subtle.exportKey("pkcs8", keyPair.privateKey) : Promise.resolve(void 0)
+  ]);
+  const publicKeyBase64 = toBase64(publicKeyBuf);
+  const privateKeyBase64 = privateKeyBuf ? toBase64(privateKeyBuf) : void 0;
+  const result = {
+    type,
+    publicKey: toPEM(publicKeyBase64, "PUBLIC KEY", formatPemLines, addPrefixSuffix),
+    publicKeyBuffer: publicKeyBuf
+  };
+  if (privateKeyBase64 && privateKeyBuf) {
+    result.privateKey = toPEM(privateKeyBase64, "PRIVATE KEY", formatPemLines, addPrefixSuffix);
+    result.privateKeyBuffer = privateKeyBuf;
+  }
+  if (includeCryptoKeys) {
+    result.privateKeyCrypto = keyPair.privateKey;
+    result.publicKeyCrypto = keyPair.publicKey;
+  }
+  return result;
+}
+__name(generateKeys, "generateKeys");
+async function sign(data, privateKeyCrypto, options = {}) {
+  const algorithm = resolveSignAlgorithm(privateKeyCrypto, options);
+  const signature = await subtle.sign(algorithm, privateKeyCrypto, toArrayBuffer(toBinary(data, options.inputEncoding)));
+  return arrayBufferToBuffer(signature).toString(options.outputEncoding ?? DEFAULT_SIGNATURE_ENCODING);
+}
+__name(sign, "sign");
+async function verify(data, signature, publicKeyCrypto, options = {}) {
+  const algorithm = resolveSignAlgorithm(publicKeyCrypto, options);
+  const signatureBytes = typeof signature === "string" ? Uint8Array.from(Buffer.from(signature, options.signatureEncoding ?? DEFAULT_SIGNATURE_ENCODING)) : toBinary(signature);
+  return subtle.verify(algorithm, publicKeyCrypto, toArrayBuffer(signatureBytes), toArrayBuffer(toBinary(data, options.inputEncoding)));
+}
+__name(verify, "verify");
+async function importKey(key, options = {}) {
+  const extractable = options.extractable ?? false;
+  if (typeof key === "string") {
+    if (!options.type) {
+      throw new Error("Key type is required when importing PEM keys");
+    }
+    const { format, binary } = fromPEM(key);
+    const algorithm2 = resolveKeyAlgorithm({
+      type: options.type,
+      hash: options.hash,
+      namedCurve: options.namedCurve
+    });
+    return subtle.importKey(format, binary, algorithm2, extractable, resolveDefaultUsages(format, options.usages));
+  }
+  const keyType = inferKeyTypeFromJwk(key, options.type);
+  const algorithm = resolveKeyAlgorithm({
+    type: keyType,
+    hash: options.hash,
+    namedCurve: options.namedCurve
+  });
+  return subtle.importKey("jwk", key, algorithm, extractable, inferJwkUsages(key, options.usages));
+}
+__name(importKey, "importKey");
+async function exportKey(key, format = "jwk", options = {}) {
+  if (format === "jwk") {
+    return subtle.exportKey("jwk", key);
+  }
+  const binary = key.type === "private" ? await subtle.exportKey("pkcs8", key) : await subtle.exportKey("spki", key);
+  return toPEM(toBase64(binary), key.type === "private" ? "PRIVATE KEY" : "PUBLIC KEY", options.formatPemLines ?? true, options.addPrefixSuffix ?? true);
+}
+__name(exportKey, "exportKey");
+async function fingerprint(publicKey, encoding = "base64url") {
+  if (publicKey.type !== "public") {
+    throw new Error("fingerprint requires a public key");
+  }
+  const spki = await subtle.exportKey("spki", publicKey);
+  return crypto.createHash("sha256").update(arrayBufferToBuffer(spki)).digest(encoding);
+}
+__name(fingerprint, "fingerprint");
+async function getKeyId(publicKey) {
+  return fingerprint(publicKey, "base64url");
+}
+__name(getKeyId, "getKeyId");
 function randomString() {
   return sha256(id.uuid());
 }
@@ -213,13 +494,18 @@ __name(verifyPassword, "verifyPassword");
 exports.createSignedToken = createSignedToken;
 exports.decrypt = decrypt;
 exports.encrypt = encrypt;
+exports.exportKey = exportKey;
+exports.fingerprint = fingerprint;
 exports.generateApiKey = generateApiKey;
+exports.generateKeys = generateKeys;
 exports.generateNonce = generateNonce;
 exports.generateRandomBytes = generateRandomBytes;
 exports.generateRandomBytesAsString = generateRandomBytesAsString;
+exports.getKeyId = getKeyId;
 exports.hash = hash;
 exports.hashPassword = hashPassword;
 exports.hmac = hmac;
+exports.importKey = importKey;
 exports.md5 = md5;
 exports.pbkdf2Hash = pbkdf2Hash;
 exports.randomString = randomString;
@@ -228,5 +514,7 @@ exports.secureRandomInt = secureRandomInt;
 exports.sha1 = sha1;
 exports.sha256 = sha256;
 exports.sha256Hmac = sha256Hmac;
+exports.sign = sign;
+exports.verify = verify;
 exports.verifyPassword = verifyPassword;
 exports.verifySignedToken = verifySignedToken;

package/crypto/index.d.ts

@@ -22,7 +22,7 @@
  * SOFTWARE.
  */
 
-import { BinaryToTextEncoding, CipherGCMTypes } from 'node:crypto';
+import { CipherGCMTypes, BinaryToTextEncoding } from 'node:crypto';
 
 type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'utf-16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
 /**
@@ -75,6 +75,233 @@ declare function sha256(input: string, encoding?: BinaryToTextEncoding): string;
  * @returns {string} MD5 hash as a string.
  */
 declare function md5(input: string): string;
+/**
+ * Supported asymmetric key types for generation.
+ *
+ * - `RSA`       → RSASSA-PKCS1-v1_5 (legacy compatibility)
+ * - `RSA-PSS`   → Recommended RSA variant with modern padding
+ * - `ECDSA`     → Elliptic Curve (fast, smaller keys)
+ * - `Ed25519`   → Modern, simple, highly secure (recommended)
+ */
+type EncKeyType = 'RSA' | 'RSA-PSS' | 'ECDSA' | 'Ed25519';
+/**
+ * Options to configure key pair generation.
+ */
+interface GenerateKeyOptions {
+    /**
+     * Type of key algorithm to generate.
+     * @default 'RSA-PSS'
+     */
+    type?: EncKeyType;
+    /**
+     * RSA modulus length in bits.
+     * Recommended: 2048 or 3072 (4096 for high security).
+     * @default 2048
+     */
+    modulusLength?: number;
+    /**
+     * Hash algorithm used for signing.
+     *
+     * ⚠️ For ECDSA, hash is used during sign/verify, not key generation.
+     * @default 'SHA-256'
+     */
+    hash?: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /**
+     * Named curve for ECDSA keys.
+     * @default 'P-256'
+     */
+    namedCurve?: 'P-256' | 'P-384' | 'P-521';
+    /**
+     * Whether the private key can be exported.
+     *
+     * ⚠️ Set to `false` in production if you don't need to export keys.
+     * @default false
+     */
+    extractable?: boolean;
+    /**
+     * Whether to include generated CryptoKey objects in the result.
+     *
+     * Useful when private key export is disabled (`extractable: false`) but
+     * you still want to sign/verify with the in-memory keys.
+     * @default false
+     */
+    includeCryptoKeys?: boolean;
+    /**
+     * Whether to format Base64 output into 64-character lines (PEM style).
+     * @default true
+     */
+    formatPemLines?: boolean;
+    /**
+     * Whether to include PEM prefix/suffix headers.
+     *
+     * Example:
+     * -----BEGIN PRIVATE KEY-----
+     * -----END PRIVATE KEY-----
+     *
+     * @default true
+     */
+    addPrefixSuffix?: boolean;
+}
+/**
+ * Result object returned from {@link generateKeys}
+ */
+interface GenerateKeyResult {
+    /** Algorithm type used */
+    type: EncKeyType;
+    /** PEM or Base64 encoded private key (only when extractable is true) */
+    privateKey?: string;
+    /** PEM or Base64 encoded public key */
+    publicKey: string;
+    /** Raw PKCS8 private key buffer (only when extractable is true) */
+    privateKeyBuffer?: ArrayBuffer;
+    /** Raw SPKI public key buffer */
+    publicKeyBuffer: ArrayBuffer;
+    /** Optional generated private CryptoKey */
+    privateKeyCrypto?: CryptoKey;
+    /** Optional generated public CryptoKey */
+    publicKeyCrypto?: CryptoKey;
+}
+type SupportedAlgorithm = RsaHashedKeyGenParams | EcKeyGenParams | {
+    name: 'Ed25519';
+};
+type SignatureEncoding = 'base64' | 'base64url' | 'hex';
+interface SignatureOptions {
+    /**
+     * Hash algorithm used for ECDSA signatures.
+     *
+     * ⚠️ For ECDSA, hash is used during sign/verify, not key generation.
+     * @default 'SHA-256'
+     */
+    hash?: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /**
+     * Salt length for RSA-PSS signatures.
+     * Defaults to the digest length of the configured hash.
+     */
+    saltLength?: number;
+    /**
+     * Output encoding for generated signatures.
+     * @default 'base64url'
+     */
+    outputEncoding?: SignatureEncoding;
+    /**
+     * Input encoding when the payload is a string.
+     * @default 'utf8'
+     */
+    inputEncoding?: BufferEncoding;
+}
+interface VerifyOptions extends Omit<SignatureOptions, 'outputEncoding'> {
+    /**
+     * Encoding of the provided signature when it is a string.
+     * @default 'base64url'
+     */
+    signatureEncoding?: SignatureEncoding;
+}
+interface ImportKeyOptions {
+    /**
+     * Explicit key type. Required for PEM import when the algorithm cannot be inferred.
+     */
+    type?: EncKeyType;
+    /**
+     * Hash algorithm used with RSA and ECDSA operations.
+     *
+     * ⚠️ For ECDSA, hash is used during sign/verify, not key generation.
+     * @default 'SHA-256'
+     */
+    hash?: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /**
+     * Named curve for ECDSA keys.
+     * @default 'P-256'
+     */
+    namedCurve?: 'P-256' | 'P-384' | 'P-521';
+    /**
+     * Whether the imported key can be exported.
+     * @default false
+     */
+    extractable?: boolean;
+    /**
+     * Allowed operations for the imported key.
+     * Defaults to `['sign']` for private keys and `['verify']` for public keys.
+     */
+    usages?: Array<'sign' | 'verify'>;
+}
+interface ExportKeyOptions {
+    /**
+     * Whether to format Base64 output into 64-character lines (PEM style).
+     * @default true
+     */
+    formatPemLines?: boolean;
+    /**
+     * Whether to include PEM prefix/suffix headers.
+     * @default true
+     */
+    addPrefixSuffix?: boolean;
+}
+/**
+ * Generates an asymmetric cryptographic key pair using Web Crypto API.
+ *
+ * Supports RSA, RSA-PSS, ECDSA, and Ed25519.
+ *
+ * @param options - Configuration for key generation
+ *
+ * @returns Promise resolving to generated key pair (PEM + raw buffers)
+ *
+ * @example
+ * ```ts
+ * const keys = await generateKeys({
+ *   type: 'RSA-PSS',
+ *   modulusLength: 2048
+ * });
+ *
+ * console.log(keys.publicKey);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const keys = await generateKeys({
+ *   type: 'Ed25519',
+ *   extractable: false
+ * });
+ * ```
+ *
+ * @remarks
+ * - Uses `crypto.subtle.generateKey`
+ * - Private key is exported in PKCS#8 format
+ * - Public key is exported in SPKI format
+ * - Ed25519 requires modern runtime support (Node 18+, modern browsers)
+ *
+ * ⚠️ Security Notes:
+ * - Avoid logging private keys in production
+ * - Prefer `extractable: false` when possible
+ * - Store keys securely (e.g., KMS, HSM)
+ */
+declare function generateKeys(options?: GenerateKeyOptions): Promise<GenerateKeyResult>;
+/**
+ * Signs data with a private key generated or imported through Web Crypto.
+ * ⚠️ ECDSA signatures are DER-encoded.
+ * Some systems (e.g., JWT ES256, blockchain) require raw (r || s) format.
+ * Conversion may be required depending on the consumer.
+ */
+declare function sign(data: string | Buffer | Uint8Array, privateKeyCrypto: CryptoKey, options?: SignatureOptions): Promise<string>;
+/**
+ * Verifies a signature with a public key generated or imported through Web Crypto.
+ */
+declare function verify(data: string | Buffer | Uint8Array, signature: string | Buffer | Uint8Array, publicKeyCrypto: CryptoKey, options?: VerifyOptions): Promise<boolean>;
+/**
+ * Imports a PEM or JWK asymmetric key into Web Crypto.
+ */
+declare function importKey(key: string | JsonWebKey, options?: ImportKeyOptions): Promise<CryptoKey>;
+/**
+ * Exports an asymmetric CryptoKey as JWK or PEM.
+ */
+declare function exportKey(key: CryptoKey, format?: 'jwk' | 'pem', options?: ExportKeyOptions): Promise<JsonWebKey | string>;
+/**
+ * Produces a stable SHA-256 fingerprint for a public key.
+ */
+declare function fingerprint(publicKey: CryptoKey, encoding?: SignatureEncoding): Promise<string>;
+/**
+ * Generates a unique identifier for a public key by computing its fingerprint.
+ */
+declare function getKeyId(publicKey: CryptoKey): Promise<string>;
 /**
  * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
  *
@@ -244,5 +471,5 @@ declare function hashPassword(password: string, saltLength?: number, keyLength?:
  */
 declare function verifyPassword(password: string, hash: string): Promise<boolean>;
 
-export { createSignedToken, decrypt, encrypt, generateApiKey, generateNonce, generateRandomBytes, generateRandomBytesAsString, hash, hashPassword, hmac, md5, pbkdf2Hash, randomString, safeCompare, secureRandomInt, sha1, sha256, sha256Hmac, verifyPassword, verifySignedToken };
-export type { BufferEncoding, DecryptionOptions, EncryptionOptions, EncryptionResult };
+export { createSignedToken, decrypt, encrypt, exportKey, fingerprint, generateApiKey, generateKeys, generateNonce, generateRandomBytes, generateRandomBytesAsString, getKeyId, hash, hashPassword, hmac, importKey, md5, pbkdf2Hash, randomString, safeCompare, secureRandomInt, sha1, sha256, sha256Hmac, sign, verify, verifyPassword, verifySignedToken };
+export type { BufferEncoding, DecryptionOptions, EncKeyType, EncryptionOptions, EncryptionResult, ExportKeyOptions, GenerateKeyOptions, GenerateKeyResult, ImportKeyOptions, SignatureEncoding, SignatureOptions, SupportedAlgorithm, VerifyOptions };