@zudojs/crypto 0.1.0 → 1.1.0

package/dist/node/nodeCryptoProvider/primitives/nodeCryptoProvider.hash.js

@@ -1,15 +1,20 @@
 import { createHash, createHmac } from "node:crypto";
 import { toBytes, nodeHashAlgorithm } from "../nodeCryptoProvider.helper.js";
 export async function hash(algorithm, data) {
+    const digestName = nodeHashAlgorithm(algorithm);
     const normalized = toBytes(data);
-    const hasher = createHash(nodeHashAlgorithm(algorithm));
+    const hasher = createHash(digestName);
     hasher.update(normalized);
     return new Uint8Array(hasher.digest());
 }
 export async function hmac(algorithm, key, data) {
+    const digestName = nodeHashAlgorithm(algorithm);
     const normalizedKey = toBytes(key);
+    if (normalizedKey.byteLength === 0) {
+        throw new TypeError("HMAC key must not be empty.");
+    }
     const normalizedData = toBytes(data);
-    const h = createHmac(nodeHashAlgorithm(algorithm), normalizedKey);
+    const h = createHmac(digestName, normalizedKey);
     h.update(normalizedData);
     return new Uint8Array(h.digest());
 }

package/dist/node/nodeCryptoProvider/primitives/nodeCryptoProvider.random.d.ts

@@ -1,4 +1,10 @@
 export declare function randomBytesImpl(length: number): Promise<Uint8Array>;
+/**
+ * Returns a uniformly distributed integer in `[min, max)`.
+ *
+ * Delegates to `node:crypto.randomInt`, which is unbiased for ranges up
+ * to 2^48. A range of exactly one value returns `min`.
+ */
 export declare function randomIntImpl(min: number, max: number): Promise<number>;
 export declare function randomUUIDImpl(): Promise<string>;
 //# sourceMappingURL=nodeCryptoProvider.random.d.ts.map

package/dist/node/nodeCryptoProvider/primitives/nodeCryptoProvider.random.js

@@ -1,39 +1,39 @@
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomInt } from "node:crypto";
+/** Largest range accepted by `node:crypto.randomInt`. */
+const MAX_RANGE = 2 ** 48;
 export async function randomBytesImpl(length) {
     if (!Number.isInteger(length) || length <= 0) {
         throw new TypeError("randomBytes length must be a positive integer.");
     }
     return new Uint8Array(randomBytes(length));
 }
+/**
+ * Returns a uniformly distributed integer in `[min, max)`.
+ *
+ * Delegates to `node:crypto.randomInt`, which is unbiased for ranges up
+ * to 2^48. A range of exactly one value returns `min`.
+ */
 export async function randomIntImpl(min, max) {
-    if (!Number.isInteger(min) || !Number.isInteger(max)) {
-        throw new TypeError("randomInt bounds must be integers.");
+    if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max)) {
+        throw new TypeError("randomInt bounds must be safe integers.");
     }
     if (max <= min) {
         throw new RangeError("max must be greater than min.");
     }
     const range = max - min;
-    const bytesNeeded = Math.ceil(Math.log2(range) / 8);
-    const limit = Math.floor(256 ** bytesNeeded / range) * range;
-    while (true) {
-        const bytes = await randomBytesImpl(bytesNeeded);
-        let value = 0;
-        for (let i = 0; i < bytesNeeded; i += 1) {
-            value = (value << 8) | bytes[i];
-        }
-        value = value >>> 0;
-        if (value < limit) {
-            return min + (value % range);
-        }
+    if (range > MAX_RANGE) {
+        throw new RangeError(`randomInt range must not exceed 2^48.`);
     }
+    if (range === 1) {
+        return min;
+    }
+    return randomInt(min, max);
 }
 export async function randomUUIDImpl() {
     const bytes = await randomBytesImpl(16);
     bytes[6] = (bytes[6] & 0x0f) | 0x40;
     bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    const hex = Array.from(bytes)
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("");
+    const hex = Buffer.from(bytes).toString("hex");
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 //# sourceMappingURL=nodeCryptoProvider.random.js.map

package/dist/node/nodeCryptoProvider/primitives/nodeCryptoProvider.signing.d.ts

@@ -1,13 +1,11 @@
-import type { SignatureAlgorithm, CryptoInput } from "../../../cryptoProvider/index.js";
-export declare function sign(options: {
-    key: CryptoInput;
-    data: CryptoInput;
-    algorithm?: SignatureAlgorithm;
-}): Promise<Uint8Array>;
-export declare function verify(options: {
-    key: CryptoInput;
-    data: CryptoInput;
-    signature: Uint8Array;
-    algorithm?: SignatureAlgorithm;
-}): Promise<boolean>;
+import type { SignOptions, VerifyOptions } from "../../../cryptoProvider/index.js";
+export declare function sign(options: SignOptions): Promise<Uint8Array>;
+/**
+ * Verifies a signature.
+ *
+ * Returns false for a malformed key, malformed signature or mismatching
+ * data. Throws only for programmer errors (unsupported algorithm, key
+ * type that cannot be used with the algorithm).
+ */
+export declare function verify(options: VerifyOptions): Promise<boolean>;
 //# sourceMappingURL=nodeCryptoProvider.signing.d.ts.map

package/dist/node/nodeCryptoProvider/primitives/nodeCryptoProvider.signing.js

@@ -1,29 +1,84 @@
-import { createPrivateKey, createPublicKey, createSign, createVerify, sign as signImpl, verify as verifyImpl, } from "node:crypto";
-import { toBytes, nodeSignatureAlgorithm, } from "../nodeCryptoProvider.helper.js";
+import { isSignatureAlgorithmName } from "../../../cryptoProvider/cryptoProvider.type.js";
+import { createSign, createVerify, sign as signImpl, verify as verifyImpl, } from "node:crypto";
+import { CryptoOperation } from "@zudojs/errors";
+import { toBytes } from "../nodeCryptoProvider.helper.js";
+import { signatureError } from "../../../cryptoErrors/cryptoErrors.helper.js";
+import { toPrivateKey, toPublicKey, } from "../../signing/signing.conversion.js";
+import { nodeSignatureAlgorithm, expectedAsymmetricKeyType, } from "../../signing/signing.utils.js";
+function assertAlgorithm(algorithm, operation) {
+    if (!isSignatureAlgorithmName(algorithm)) {
+        throw signatureError(`Unsupported signature algorithm: ${String(algorithm)}.`, operation, typeof algorithm === "string" ? algorithm : undefined);
+    }
+}
+/**
+ * Ensures the key's type matches the requested algorithm so that the
+ * algorithm label is a real integrity assertion (an EC key cannot sign
+ * under "rsa-sha256").
+ */
+function assertKeyType(key, algorithm, operation) {
+    const expected = expectedAsymmetricKeyType(algorithm);
+    if (key.asymmetricKeyType !== expected) {
+        throw signatureError(`Signature algorithm "${algorithm}" requires a ${expected} key, received ${String(key.asymmetricKeyType)}.`, operation, algorithm);
+    }
+}
 export async function sign(options) {
     const algorithm = options.algorithm ?? "ed25519";
-    const key = toBytes(options.key);
+    assertAlgorithm(algorithm, CryptoOperation.SIGN);
     const data = toBytes(options.data);
-    const privateKey = createPrivateKey(key);
-    if (algorithm === "ed25519") {
-        return new Uint8Array(signImpl(null, data, privateKey));
-    }
-    const signer = createSign(nodeSignatureAlgorithm(algorithm));
-    signer.update(data);
-    signer.end();
-    return new Uint8Array(signer.sign(privateKey));
+    let privateKey;
+    try {
+        privateKey = toPrivateKey(options.key);
+    }
+    catch (error) {
+        throw signatureError("Invalid private key.", CryptoOperation.SIGN, algorithm, error);
+    }
+    assertKeyType(privateKey, algorithm, CryptoOperation.SIGN);
+    try {
+        if (algorithm === "ed25519") {
+            return new Uint8Array(signImpl(null, data, privateKey));
+        }
+        const signer = createSign(nodeSignatureAlgorithm(algorithm));
+        signer.update(data);
+        signer.end();
+        return new Uint8Array(signer.sign(privateKey));
+    }
+    catch (error) {
+        throw signatureError("Signing failed.", CryptoOperation.SIGN, algorithm, error);
+    }
 }
+/**
+ * Verifies a signature.
+ *
+ * Returns false for a malformed key, malformed signature or mismatching
+ * data. Throws only for programmer errors (unsupported algorithm, key
+ * type that cannot be used with the algorithm).
+ */
 export async function verify(options) {
     const algorithm = options.algorithm ?? "ed25519";
-    const key = toBytes(options.key);
+    assertAlgorithm(algorithm, CryptoOperation.VERIFY_SIGNATURE);
+    if (!(options.signature instanceof Uint8Array)) {
+        return false;
+    }
     const data = toBytes(options.data);
-    const publicKey = createPublicKey(key);
-    if (algorithm === "ed25519") {
-        return verifyImpl(null, data, publicKey, options.signature);
-    }
-    const verifier = createVerify(nodeSignatureAlgorithm(algorithm));
-    verifier.update(data);
-    verifier.end();
-    return verifier.verify(publicKey, options.signature);
+    let publicKey;
+    try {
+        publicKey = toPublicKey(options.key);
+    }
+    catch {
+        return false;
+    }
+    assertKeyType(publicKey, algorithm, CryptoOperation.VERIFY_SIGNATURE);
+    try {
+        if (algorithm === "ed25519") {
+            return verifyImpl(null, data, publicKey, options.signature);
+        }
+        const verifier = createVerify(nodeSignatureAlgorithm(algorithm));
+        verifier.update(data);
+        verifier.end();
+        return verifier.verify(publicKey, options.signature);
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=nodeCryptoProvider.signing.js.map

package/dist/node/signing/signing.conversion.d.ts

@@ -1,9 +1,19 @@
 import type { CryptoKey } from "../../cryptoKey/cryptoKey.type.js";
 import { type KeyObject } from "node:crypto";
 /**
- * Converts a CryptoKey into a Node.js KeyObject.
+ * Key material accepted by the conversion helpers.
+ *
+ * - `KeyObject`: used as-is.
+ * - `string`: PEM text.
+ * - `Uint8Array`/`ArrayBuffer`: PEM text when the bytes start with
+ *   `-----BEGIN`, otherwise DER (PKCS#8 for private keys, SPKI for
+ *   public keys).
+ */
+export type KeyMaterial = KeyObject | string | Uint8Array | ArrayBuffer;
+/**
+ * Converts a CryptoKey holding a PKCS#8 DER Ed25519 key into a KeyObject.
  */
 export declare function cryptoKeyToPrivateKey(key: CryptoKey): KeyObject;
-export declare function toPrivateKey(key: KeyObject | string | Uint8Array): KeyObject;
-export declare function toPublicKey(key: KeyObject | string | Uint8Array): KeyObject;
+export declare function toPrivateKey(key: KeyMaterial): KeyObject;
+export declare function toPublicKey(key: KeyMaterial): KeyObject;
 //# sourceMappingURL=signing.conversion.d.ts.map

package/dist/node/signing/signing.conversion.js

@@ -1,7 +1,19 @@
 import { createPrivateKey, createPublicKey } from "node:crypto";
 import { isKeyObject } from "./signing.utils.js";
+const PEM_PREFIX = Buffer.from("-----BEGIN", "utf8");
+function looksLikePem(bytes) {
+    if (bytes.byteLength < PEM_PREFIX.byteLength) {
+        return false;
+    }
+    for (let index = 0; index < PEM_PREFIX.byteLength; index += 1) {
+        if (bytes[index] !== PEM_PREFIX[index]) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
- * Converts a CryptoKey into a Node.js KeyObject.
+ * Converts a CryptoKey holding a PKCS#8 DER Ed25519 key into a KeyObject.
  */
 export function cryptoKeyToPrivateKey(key) {
     if (key.algorithm !== "ed25519") {
@@ -23,14 +35,18 @@ export function toPrivateKey(key) {
     if (typeof key === "string") {
         return createPrivateKey(key);
     }
-    if (key instanceof Uint8Array) {
-        return createPrivateKey({
-            key: Buffer.from(key),
-            format: "der",
-            type: "pkcs8",
-        });
+    const bytes = key instanceof ArrayBuffer ? new Uint8Array(key) : key;
+    if (!(bytes instanceof Uint8Array)) {
+        throw new TypeError("Invalid private key.");
     }
-    throw new TypeError("Invalid private key.");
+    if (looksLikePem(bytes)) {
+        return createPrivateKey(Buffer.from(bytes));
+    }
+    return createPrivateKey({
+        key: Buffer.from(bytes),
+        format: "der",
+        type: "pkcs8",
+    });
 }
 export function toPublicKey(key) {
     if (isKeyObject(key)) {
@@ -39,13 +55,17 @@ export function toPublicKey(key) {
     if (typeof key === "string") {
         return createPublicKey(key);
     }
-    if (key instanceof Uint8Array) {
-        return createPublicKey({
-            key: Buffer.from(key),
-            format: "der",
-            type: "spki",
-        });
+    const bytes = key instanceof ArrayBuffer ? new Uint8Array(key) : key;
+    if (!(bytes instanceof Uint8Array)) {
+        throw new TypeError("Invalid public key.");
+    }
+    if (looksLikePem(bytes)) {
+        return createPublicKey(Buffer.from(bytes));
     }
-    throw new TypeError("Invalid public key.");
+    return createPublicKey({
+        key: Buffer.from(bytes),
+        format: "der",
+        type: "spki",
+    });
 }
 //# sourceMappingURL=signing.conversion.js.map

package/dist/node/signing/signing.core.d.ts

@@ -1,4 +1,5 @@
 import { type KeyObject } from "node:crypto";
+import { type KeyMaterial } from "./signing.conversion.js";
 /**
  * Generates an Ed25519 key pair.
  */
@@ -17,5 +18,5 @@ export declare function exportPublicKeyPem(publicKey: KeyObject): string;
 /**
  * Creates a public key from a private key.
  */
-export declare function derivePublicKey(privateKey: KeyObject | string | Uint8Array): KeyObject;
+export declare function derivePublicKey(privateKey: KeyMaterial): KeyObject;
 //# sourceMappingURL=signing.core.d.ts.map

package/dist/node/signing/signing.core.js

@@ -1,6 +1,5 @@
-import { generateKeyPairSync, createPrivateKey, createPublicKey, } from "node:crypto";
-import { CryptoAlgorithm } from "../../cryptoConstants/cryptoConstants.type.js";
-import { cryptoKeyToPrivateKey, toPrivateKey } from "./signing.conversion.js";
+import { generateKeyPairSync, createPublicKey } from "node:crypto";
+import { toPrivateKey } from "./signing.conversion.js";
 import { assertKeyObject } from "./signing.utils.js";
 /**
  * Generates an Ed25519 key pair.

package/dist/node/signing/signing.utils.d.ts

@@ -1,9 +1,17 @@
 import type { SignatureAlgorithm } from "../../cryptoProvider/index.js";
-import type { KeyObject } from "node:crypto";
+import { KeyObject } from "node:crypto";
 /**
- * Maps a signature algorithm to a Node.js hash algorithm name.
+ * Maps a signature algorithm to the OpenSSL digest name used with
+ * `createSign`/`createVerify`.
+ *
+ * Ed25519 is a pure signature scheme and has no digest; use
+ * `crypto.sign(null, ...)` for it instead.
  */
 export declare function nodeSignatureAlgorithm(algorithm: SignatureAlgorithm): string;
+/**
+ * Returns the `KeyObject.asymmetricKeyType` a signature algorithm requires.
+ */
+export declare function expectedAsymmetricKeyType(algorithm: SignatureAlgorithm): "rsa" | "ec" | "ed25519";
 /**
  * Checks whether a value is a Node.js KeyObject.
  */

package/dist/node/signing/signing.utils.js

@@ -1,5 +1,10 @@
+import { KeyObject } from "node:crypto";
 /**
- * Maps a signature algorithm to a Node.js hash algorithm name.
+ * Maps a signature algorithm to the OpenSSL digest name used with
+ * `createSign`/`createVerify`.
+ *
+ * Ed25519 is a pure signature scheme and has no digest; use
+ * `crypto.sign(null, ...)` for it instead.
  */
 export function nodeSignatureAlgorithm(algorithm) {
     switch (algorithm) {
@@ -21,14 +26,30 @@ export function nodeSignatureAlgorithm(algorithm) {
             throw new TypeError(`Unsupported signature algorithm: ${String(algorithm)}.`);
     }
 }
+/**
+ * Returns the `KeyObject.asymmetricKeyType` a signature algorithm requires.
+ */
+export function expectedAsymmetricKeyType(algorithm) {
+    switch (algorithm) {
+        case "rsa-sha256":
+        case "rsa-sha384":
+        case "rsa-sha512":
+            return "rsa";
+        case "ecdsa-sha256":
+        case "ecdsa-sha384":
+        case "ecdsa-sha512":
+            return "ec";
+        case "ed25519":
+            return "ed25519";
+        default:
+            throw new TypeError(`Unsupported signature algorithm: ${String(algorithm)}.`);
+    }
+}
 /**
  * Checks whether a value is a Node.js KeyObject.
  */
 export function isKeyObject(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "type" in value &&
-        "export" in value);
+    return value instanceof KeyObject;
 }
 /**
  * Asserts that a value is a Node.js KeyObject.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/crypto",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Cryptographic primitives for hashing, encryption, tokens, and secure random generation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,25 +13,27 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo",
+    "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "engines": {
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/errors": "0.1.0"
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/errors": "1.0.1"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "devDependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"
@@ -44,8 +46,20 @@
     "security"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/crypto"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}