CryptoUtils

Hashing, encryption, tokens, UUIDs, Base64, and constant-time comparison utilities.

Import

import { CryptoUtils } from "bytekit/crypto-utils";

What it does

CryptoUtils exposes static methods for common cryptographic and encoding operations: secure token generation, UUID v4, Base64 encoding/decoding (standard and URL-safe), hashing (simple and SubtleCrypto-based), HMAC, AES-256-GCM encryption/decryption, and constant-time string comparison.

simpleHash is a fast 32-bit hash intended for non-security use cases (hash maps, fingerprinting). For security-sensitive hashing use hash() or hmac().

v3 breaking change: hash() and hmac() now throw if no secure crypto backend (crypto.subtle in browsers, or Node.js crypto) is available. The previous silent fallback to weak algorithms has been removed.

Methods

generateToken(length?)

const token = CryptoUtils.generateToken(64);
// "a3f1…" (128 hex characters)

Generates a cryptographically random hex token.

Parameter	Type	Default	Description
length	number	32	Number of random bytes (output is length * 2 hex chars).

generateUUID()

const id = CryptoUtils.generateUUID();
// "550e8400-e29b-41d4-a716-446655440000"

Returns a random UUID v4 string.

base64Encode(str)

const encoded = CryptoUtils.base64Encode("Hello, world!");

Encodes a string to standard Base64.

base64Decode(str)

const decoded = CryptoUtils.base64Decode(encoded);

Decodes a standard Base64 string.

base64UrlEncode(str)

const safe = CryptoUtils.base64UrlEncode(payload);

Encodes a string to URL-safe Base64 (replaces +/ with -_, strips =).

base64UrlDecode(str)

const decoded = CryptoUtils.base64UrlDecode(safe);

Decodes a URL-safe Base64 string.

simpleHash(str)

const hash = CryptoUtils.simpleHash("cache-key-123");

Returns a fast, non-cryptographic 32-bit hash string. Suitable for cache keys or bucketing.

hash(str, algorithm?)

const digest = await CryptoUtils.hash("sensitive-data", "SHA-512");

Computes a cryptographic hash using the SubtleCrypto API.

v3: Throws if no secure crypto backend is available. Ensure crypto.subtle (browser) or Node.js crypto is present before calling.

Parameter	Type	Default	Description
str	string	—	Input string.
algorithm	string	"SHA-256"	Hash algorithm (SHA-1, SHA-256, SHA-384, SHA-512).

hmac(message, secret, algorithm?)

const signature = await CryptoUtils.hmac(payload, webhookSecret, "SHA-256");

Computes an HMAC digest.

v3: Throws if no secure crypto backend is available instead of returning an empty string.

Parameter	Type	Default	Description
message	string	—	Message to sign.
secret	string	—	HMAC secret key.
algorithm	string	"SHA-256"	Hash algorithm.

verifyHash(str, hash, algorithm?)

const valid = await CryptoUtils.verifyHash("data", expectedHash, "SHA-256");

Hashes str and compares it to hash. Returns true if they match.

encrypt(str, key)

const ciphertext = await CryptoUtils.encrypt("secret message", encryptionKey);

Encrypts a string using AES-256-GCM. The returned string includes the IV and auth tag, so it is self-contained.

decrypt(encrypted, key)

const plaintext = await CryptoUtils.decrypt(ciphertext, encryptionKey);

Decrypts a string previously encrypted with encrypt.

randomBytes(length)

const bytes = CryptoUtils.randomBytes(16);

Returns a Uint8Array of cryptographically random bytes.

constantTimeCompare(a, b)

const match = CryptoUtils.constantTimeCompare(provided, expected);

Compares two strings in constant time to prevent timing attacks. Returns true if they are equal.

Examples

Webhook signature verification

import { CryptoUtils } from "bytekit/crypto-utils";

async function verifyWebhook(body: string, signature: string, secret: string) {
  const expected = await CryptoUtils.hmac(body, secret, "SHA-256");
  return CryptoUtils.constantTimeCompare(signature, expected);
}

Token-based authentication

import { CryptoUtils } from "bytekit/crypto-utils";

const sessionToken = CryptoUtils.generateToken(32);
const hashedToken = await CryptoUtils.hash(sessionToken, "SHA-256");

// Store `hashedToken` in the database
// Send `sessionToken` to the client

Encrypt sensitive data at rest

import { CryptoUtils } from "bytekit/crypto-utils";

const key = CryptoUtils.generateToken(32);

const encrypted = await CryptoUtils.encrypt("SSN: 123-45-6789", key);
const decrypted = await CryptoUtils.decrypt(encrypted, key);
// "SSN: 123-45-6789"

Use constantTimeCompare whenever you compare tokens, signatures, or hashes to prevent timing side-channel attacks.

Async methods (hash, hmac, encrypt, decrypt, verifyHash) use the Web Crypto API (SubtleCrypto) and require a secure context (HTTPS) in browsers.