hanzio 1.2.0 → 2.0.0

package/src/{math → color}/metricsSeriesColors.ts

@@ -1,21 +1,33 @@
+import { lerp, normalize } from '../math/scale'
+import { colorFunctionArgs, parseColor } from './contrast'
+
 /**
- * Shared metrics chart series color assignment for web (CSS tokens) and Expo (hex palette).
- * Same hash + collision strategy so labels map to the same slot index everywhere.
+ * Stable series color assignment: the same hash + collision strategy maps a
+ * label to the same palette slot index on every platform.
  */
 
-/** Matches PrimeVue semantic palette slot count (cyan…blue) and Expo SERIES_COLORS length */
+/** Default palette slot count. */
 export const METRICS_SERIES_PALETTE_SIZE = 10
 
 /**
  * FNV-1a 32-bit hash — stable palette index for a string key.
  */
-export function hashStringToColorIndex(str: string): number {
+export function hashStringToColorIndex(
+	str: string,
+	paletteSize = METRICS_SERIES_PALETTE_SIZE
+): number {
 	let hash = 2166136261
 	for (let i = 0; i < str.length; i++) {
 		hash ^= str.charCodeAt(i)
 		hash = Math.imul(hash, 16777619)
 	}
-	return Math.abs(hash) % METRICS_SERIES_PALETTE_SIZE
+	return Math.abs(hash) % paletteSize
+}
+
+/** Stable pick from `palette` for `seed` (same seed → same item). Throws on an empty palette. */
+export function pickFromPalette<T>(seed: string, palette: readonly T[]): T {
+	if (palette.length === 0) throw new RangeError('palette is empty')
+	return palette[hashStringToColorIndex(seed, palette.length)]!
 }
 
 function circularHueDistance(
@@ -59,23 +71,24 @@ export function seriesColorKey(label: string | undefined, key: string): string {
 /**
  * Map each distinct key to a palette index (hash preference, then max-min circular spacing).
  */
-export function resolveSeriesColorMap(keys: string[]): Map<string, number> {
+export function resolveSeriesColorMap(
+	keys: string[],
+	paletteSize = METRICS_SERIES_PALETTE_SIZE
+): Map<string, number> {
 	const result = new Map<string, number>()
 	const uniqueKeys = [...new Set(keys)]
 	if (uniqueKeys.length === 0) return result
 
-	const paletteSize = METRICS_SERIES_PALETTE_SIZE
-
 	if (uniqueKeys.length === 1) {
 		const only = uniqueKeys[0]!
-		result.set(only, hashStringToColorIndex(only))
+		result.set(only, hashStringToColorIndex(only, paletteSize))
 		return result
 	}
 
 	const usedIndices = new Set<number>()
 	const entries = uniqueKeys.map((key) => ({
 		key,
-		preferred: hashStringToColorIndex(key)
+		preferred: hashStringToColorIndex(key, paletteSize)
 	}))
 
 	for (const entry of entries) {
@@ -114,53 +127,38 @@ export type ResolveColorsByKeysResult = {
 export function createResolveColorsByKeys(
 	keys: string[],
 	getSeriesColor: (index: number) => string,
-	getSeriesHoverColor: (index: number) => string
+	getSeriesHoverColor: (index: number) => string,
+	paletteSize = METRICS_SERIES_PALETTE_SIZE
 ): ResolveColorsByKeysResult {
-	const colorMap = resolveSeriesColorMap(keys)
+	const colorMap = resolveSeriesColorMap(keys, paletteSize)
+	const indexOf = (key: string) =>
+		colorMap.get(key) ?? hashStringToColorIndex(key, paletteSize)
 	return {
-		getColor: (key: string) =>
-			getSeriesColor(colorMap.get(key) ?? hashStringToColorIndex(key)),
-		getHoverColor: (key: string) =>
-			getSeriesHoverColor(colorMap.get(key) ?? hashStringToColorIndex(key))
+		getColor: (key: string) => getSeriesColor(indexOf(key)),
+		getHoverColor: (key: string) => getSeriesHoverColor(indexOf(key))
 	}
 }
 
-function clamp(value: number, min: number, max: number): number {
-	return Math.min(max, Math.max(min, value))
-}
-
 /**
- * Add alpha to hex, rgb(), or rgba() strings.
+ * Apply `alpha` (0..1) to a color, replacing any existing alpha.
+ *
+ * - `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` → `rgba(r, g, b, a)` (works in React Native)
+ * - `rgb()`/`rgba()`/`hsl()`/`hsla()`, comma or space syntax → `rgba(…)` / `hsla(…)`
+ * - anything else (CSS variables, named colors, `oklch()`, …) →
+ *   `color-mix(in srgb, <color> <alpha*100>%, transparent)` (web only)
  */
 export function withAlpha(color: string, alpha: number): string {
 	const trimmed = color.trim()
+	const rgba = parseColor(trimmed)
+	const fn = rgba && colorFunctionArgs(trimmed)
 
-	if (trimmed.startsWith('#')) {
-		const hex = trimmed.slice(1)
-		const normalized =
-			hex.length === 3
-				? hex
-						.split('')
-						.map((c) => c + c)
-						.join('')
-				: hex
-		if (normalized.length === 6) {
-			const r = Number.parseInt(normalized.slice(0, 2), 16)
-			const g = Number.parseInt(normalized.slice(2, 4), 16)
-			const b = Number.parseInt(normalized.slice(4, 6), 16)
-			return `rgba(${r}, ${g}, ${b}, ${alpha})`
-		}
-	}
-
-	if (trimmed.startsWith('rgb(')) {
-		return trimmed.replace('rgb(', 'rgba(').replace(')', `, ${alpha})`)
+	if (fn?.name === 'hsl') {
+		const [h, s, l] = fn.args
+		return `hsla(${h}, ${s}, ${l}, ${alpha})`
 	}
+	if (rgba) return `rgba(${rgba.r}, ${rgba.g}, ${rgba.b}, ${alpha})`
 
-	if (trimmed.startsWith('rgba(')) {
-		return trimmed.replace(/,\s*[\d.]+\)$/, `, ${alpha})`)
-	}
-
-	return trimmed
+	return `color-mix(in srgb, ${trimmed} ${alpha * 100}%, transparent)`
 }
 
 /**
@@ -199,10 +197,10 @@ export function getHeatmapCellStyle(params: {
 		}
 	}
 
-	const normalized = clamp((value - min) / (max - min), 0, 1)
-	const alpha = minAlpha + (maxAlpha - minAlpha) * normalized
-
 	return {
-		backgroundColor: withAlpha(baseColor, alpha)
+		backgroundColor: withAlpha(
+			baseColor,
+			lerp(minAlpha, maxAlpha, normalize(value, min, max))
+		)
 	}
 }

package/src/cool-console-log/index.ts

@@ -40,11 +40,44 @@ export const terminalColors = {
 
 export type TerminalColor = keyof typeof terminalColors
 
+const noColors = Object.fromEntries(
+	Object.keys(terminalColors).map((key) => [key, ''])
+) as unknown as typeof terminalColors
+
+function getProcessEnvironment():
+	| Record<string, string | undefined>
+	| undefined {
+	return typeof process === 'undefined' ? undefined : process.env
+}
+
+function isDev(): boolean {
+	return getProcessEnvironment()?.NODE_ENV !== 'production'
+}
+
+/**
+ * Whether stdout should get ANSI colors: `NO_COLOR` disables, `FORCE_COLOR`
+ * (other than `'0'`) enables, otherwise only when stdout is a TTY.
+ * Always false where `process` doesn't exist (browsers, Workers).
+ */
+export function supportsColor(): boolean {
+	const env = getProcessEnvironment()
+	if (!env || env.NO_COLOR) return false
+	if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0') return true
+	return process.stdout?.isTTY === true
+}
+
 /** Log levels supported by the logger */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
 
-/** Attributes that can be passed to log methods */
-export type LogAttributes = Record<string, string | number | boolean>
+const levelRank: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+}
+
+/** Attributes that can be passed to log methods. Objects are rendered as compact JSON. */
+export type LogAttributes = Record<string, unknown>
 
 /** Log method signature */
 export type LogMethod = (message: string, attributes?: LogAttributes) => void
@@ -55,6 +88,8 @@ export type CoolLogger = {
 	info: LogMethod
 	warn: LogMethod
 	error: LogMethod
+	/** Returns a logger that adds `attributes` to every entry (call-site attributes win). */
+	child: (attributes: LogAttributes) => CoolLogger
 }
 
 /** Color config per log level */
@@ -65,11 +100,24 @@ const levelColors: Record<LogLevel, { badge: string; text: string }> = {
 	error: { badge: terminalColors.red, text: terminalColors.brightRed }
 }
 
+function formatValue(value: unknown): string {
+	if (value instanceof Error) return String(value)
+	if (typeof value !== 'object' || value === null) return String(value)
+	try {
+		return JSON.stringify(value)
+	} catch (_error) {
+		return '[Unserializable]'
+	}
+}
+
 /** Format attributes as a compact colored string */
 function formatAttributes(attrs?: LogAttributes): string {
 	if (!attrs || Object.keys(attrs).length === 0) return ''
 	const formatted = Object.entries(attrs)
-		.map(([k, v]) => `${terminalColors.dim}${k}=${terminalColors.reset}${v}`)
+		.map(
+			([k, v]) =>
+				`${terminalColors.dim}${k}=${terminalColors.reset}${formatValue(v)}`
+		)
 		.join(' ')
 	return ` ${formatted}`
 }
@@ -78,9 +126,11 @@ function formatAttributes(attrs?: LogAttributes): string {
  * Options for creating a cool logger
  */
 export type CoolLoggerOptions = {
-	/** Only use colors in development (default: true) */
+	/** Only use colors in development (default: true). Colors also require `supportsColor()`. */
 	colorsInDevOnly?: boolean
-	/** Callback for each log entry (e.g., to add to OpenTelemetry span) */
+	/** Lowest level that is printed (default: 'debug' in dev, 'info' in production) */
+	minLevel?: LogLevel
+	/** Callback for each log entry, before level filtering (e.g., to add to OpenTelemetry span) */
 	onLog?: (level: LogLevel, message: string, attributes?: LogAttributes) => void
 }
 
@@ -93,40 +143,53 @@ export type CoolLoggerOptions = {
  * logger.info('User logged in', { userId: '123' })
  * logger.warn('Rate limit approaching', { remaining: 10 })
  * logger.error('Payment failed', { reason: 'insufficient_funds' })
+ * const requestLog = logger.child({ requestId: 'abc' })
  * ```
  */
 export function createCoolLogger(options: CoolLoggerOptions = {}): CoolLogger {
-	const { colorsInDevOnly = true, onLog } = options
-	const isDev = process.env.NODE_ENV !== 'production'
-	const useColors = colorsInDevOnly ? isDev : true
-
-	const createLogMethod =
-		(level: LogLevel): LogMethod =>
-		(message, attributes) => {
-			// Call the onLog callback if provided
-			onLog?.(level, message, attributes)
-
-			// Skip debug logs in production
-			if (level === 'debug' && !isDev) return
-
-			if (useColors) {
-				const { badge, text } = levelColors[level]
-				const label = level.toUpperCase().padEnd(5)
-				const attrStr = formatAttributes(attributes)
-				console.log(
-					`${badge}[${label}]${terminalColors.reset} ${text}${message}${terminalColors.reset}${attrStr}`
-				)
-			} else {
-				console[level](`[${level.toUpperCase()}]`, message, attributes ?? '')
+	const dev = isDev()
+	const {
+		colorsInDevOnly = true,
+		minLevel = dev ? 'debug' : 'info',
+		onLog
+	} = options
+	const useColors = supportsColor() && (!colorsInDevOnly || dev)
+
+	const createLogger = (base?: LogAttributes): CoolLogger => {
+		const createLogMethod =
+			(level: LogLevel): LogMethod =>
+			(message, callAttributes) => {
+				const attributes =
+					base && callAttributes
+						? { ...base, ...callAttributes }
+						: (callAttributes ?? base)
+
+				onLog?.(level, message, attributes)
+
+				if (levelRank[level] < levelRank[minLevel]) return
+
+				if (useColors) {
+					const { badge, text } = levelColors[level]
+					const label = level.toUpperCase().padEnd(5)
+					const attrStr = formatAttributes(attributes)
+					console.log(
+						`${badge}[${label}]${terminalColors.reset} ${text}${message}${terminalColors.reset}${attrStr}`
+					)
+				} else {
+					console[level](`[${level.toUpperCase()}]`, message, attributes ?? '')
+				}
 			}
-		}
 
-	return {
-		debug: createLogMethod('debug'),
-		info: createLogMethod('info'),
-		warn: createLogMethod('warn'),
-		error: createLogMethod('error')
+		return {
+			debug: createLogMethod('debug'),
+			info: createLogMethod('info'),
+			warn: createLogMethod('warn'),
+			error: createLogMethod('error'),
+			child: (attributes) => createLogger({ ...base, ...attributes })
+		}
 	}
+
+	return createLogger()
 }
 
 /**
@@ -151,11 +214,10 @@ export function logOperationSummary(
 	options: { devOnly?: boolean; error?: Error | unknown } = {}
 ): void {
 	const { devOnly = true, error } = options
-	const isDev = process.env.NODE_ENV !== 'production'
 
-	if (devOnly && !isDev) return
+	if (devOnly && !isDev()) return
 
-	const c = terminalColors
+	const c = supportsColor() ? terminalColors : noColors
 	const statusIcon = success
 		? `${c.brightGreen}✓${c.reset}`
 		: `${c.brightRed}✗${c.reset}`
@@ -172,7 +234,34 @@ export function logOperationSummary(
 }
 
 /**
- * Helper to colorize text for console output
+ * Starts timing an operation. Call the returned `done` to log it via `logOperationSummary`.
+ *
+ * @example
+ * ```ts
+ * const done = startOperation('user.create')
+ * try {
+ *   await doSomething()
+ *   done()
+ * } catch (error) {
+ *   done(false, error)
+ * }
+ * ```
+ */
+export function startOperation(
+	operationName: string,
+	options: { devOnly?: boolean } = {}
+): (success?: boolean, error?: unknown) => void {
+	const start = performance.now()
+	return (success = true, error) =>
+		logOperationSummary(operationName, performance.now() - start, success, {
+			...options,
+			error
+		})
+}
+
+/**
+ * Helper to colorize text for console output. Returns `text` unchanged in
+ * production or when colors aren't supported (see `supportsColor`).
  *
  * @example
  * ```ts
@@ -185,8 +274,7 @@ export function colorize(
 	color: TerminalColor,
 	...modifiers: TerminalColor[]
 ): string {
-	const isDev = process.env.NODE_ENV !== 'production'
-	if (!isDev) return text
+	if (!isDev() || !supportsColor()) return text
 
 	const colorCodes = [
 		terminalColors[color],
@@ -210,9 +298,8 @@ export function logBanner(
 	options: { devOnly?: boolean } = {}
 ): void {
 	const { devOnly = true } = options
-	const isDev = process.env.NODE_ENV !== 'production'
 
-	if (devOnly && !isDev) {
+	if ((devOnly && !isDev()) || !supportsColor()) {
 		console.log(`=== ${text} ===`)
 		return
 	}

package/src/crypto/encoding.ts

@@ -0,0 +1,83 @@
+const BYTE_CHUNK_SIZE = 0x8000
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/
+const BASE64URL = /^[A-Za-z0-9_-]*={0,2}$/
+const HEX = /^(?:[0-9a-fA-F]{2})*$/
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
+export type BytesLike = Uint8Array | ArrayBuffer
+
+export function utf8Encode(value: string): Uint8Array<ArrayBuffer> {
+	return textEncoder.encode(value)
+}
+
+/** Invalid UTF-8 sequences become U+FFFD (same as `TextDecoder` / `Buffer#toString`). */
+export function utf8Decode(bytes: BytesLike): string {
+	return textDecoder.decode(bytes)
+}
+
+/** Standard base64 with `=` padding. */
+export function encodeBase64(bytes: BytesLike): string {
+	const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+	let binary = ''
+	for (let offset = 0; offset < view.length; offset += BYTE_CHUNK_SIZE) {
+		binary += String.fromCharCode(
+			...view.subarray(offset, offset + BYTE_CHUNK_SIZE)
+		)
+	}
+	return btoa(binary)
+}
+
+/** Decodes standard base64 (padding optional). Throws `TypeError` on invalid input. */
+export function decodeBase64(value: string): Uint8Array<ArrayBuffer> {
+	if (!BASE64.test(value)) throw new TypeError('Invalid base64 string')
+	const unpadded = value.replace(/=+$/, '')
+	if (unpadded.length % 4 === 1) throw new TypeError('Invalid base64 string')
+
+	const binary = atob(unpadded.padEnd(Math.ceil(unpadded.length / 4) * 4, '='))
+	const bytes = new Uint8Array(binary.length)
+	for (let index = 0; index < binary.length; index += 1) {
+		bytes[index] = binary.charCodeAt(index)
+	}
+	return bytes
+}
+
+/** URL-safe base64 without padding (RFC 4648 §5). */
+export function encodeBase64Url(bytes: BytesLike): string {
+	return encodeBase64(bytes)
+		.replaceAll('+', '-')
+		.replaceAll('/', '_')
+		.replace(/=+$/, '')
+}
+
+/** Decodes URL-safe base64 (padding optional). Throws `TypeError` on invalid input. */
+export function decodeBase64Url(value: string): Uint8Array<ArrayBuffer> {
+	if (!BASE64URL.test(value)) throw new TypeError('Invalid base64url string')
+	return decodeBase64(value.replaceAll('-', '+').replaceAll('_', '/'))
+}
+
+/** Lowercase hex. */
+export function bytesToHex(bytes: BytesLike): string {
+	const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+	let hex = ''
+	for (const byte of view) hex += byte.toString(16).padStart(2, '0')
+	return hex
+}
+
+/** Decodes hex (either case). Throws `TypeError` on odd length or non-hex characters. */
+export function hexToBytes(value: string): Uint8Array<ArrayBuffer> {
+	if (!HEX.test(value)) throw new TypeError('Invalid hex string')
+	const bytes = new Uint8Array(value.length / 2)
+	for (let index = 0; index < bytes.length; index += 1) {
+		bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16)
+	}
+	return bytes
+}
+
+/** UTF-8 for strings; a copy for bytes, so Web Crypto always gets an `ArrayBuffer`-backed view. */
+export function toBytes(data: string | BytesLike): Uint8Array<ArrayBuffer> {
+	if (typeof data === 'string') return utf8Encode(data)
+	return data instanceof Uint8Array
+		? new Uint8Array(data)
+		: new Uint8Array(data.slice(0))
+}

package/src/crypto/hash.ts

@@ -0,0 +1,170 @@
+import {
+	type BytesLike,
+	bytesToHex,
+	decodeBase64,
+	decodeBase64Url,
+	encodeBase64,
+	encodeBase64Url,
+	hexToBytes,
+	toBytes,
+	utf8Encode
+} from './encoding'
+
+export type HmacAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512'
+export type SignatureEncoding = 'hex' | 'base64' | 'base64url'
+
+export type HmacSignOptions = {
+	/** Default: `'SHA-256'` */
+	algorithm?: HmacAlgorithm
+	/** Default: `'hex'` */
+	encoding?: SignatureEncoding
+}
+
+export type HmacVerifyOptions = HmacSignOptions & {
+	/** Required prefix stripped before decoding, e.g. `'sha256='`. Missing prefix → `false`. */
+	prefix?: string
+}
+
+const HMAC_ALGORITHMS: readonly string[] = ['SHA-256', 'SHA-384', 'SHA-512']
+const RANDOM_CHUNK_SIZE = 0x10000
+const ENCODERS: Record<SignatureEncoding, (bytes: Uint8Array) => string> = {
+	hex: bytesToHex,
+	base64: encodeBase64,
+	base64url: encodeBase64Url
+}
+const DECODERS: Record<
+	SignatureEncoding,
+	(value: string) => Uint8Array<ArrayBuffer>
+> = { hex: hexToBytes, base64: decodeBase64, base64url: decodeBase64Url }
+
+/**
+ * Constant-time equality for strings (compared as UTF-8) or bytes. Runs over the
+ * longer input, so timing reveals at most the lengths, never where they differ.
+ */
+export function safeEqual(
+	a: string | Uint8Array,
+	b: string | Uint8Array
+): boolean {
+	const left = typeof a === 'string' ? utf8Encode(a) : a
+	const right = typeof b === 'string' ? utf8Encode(b) : b
+	const length = Math.max(left.length, right.length)
+	let diff = left.length ^ right.length
+	for (let index = 0; index < length; index += 1) {
+		diff |= (left[index] ?? 0) ^ (right[index] ?? 0)
+	}
+	return diff === 0
+}
+
+/** Cryptographically secure random bytes. */
+export function randomBytes(byteLength: number): Uint8Array<ArrayBuffer> {
+	if (!Number.isSafeInteger(byteLength) || byteLength < 0) {
+		throw new RangeError('byteLength must be a non-negative integer')
+	}
+	const cryptoApi = globalThis.crypto
+	if (!cryptoApi?.getRandomValues) {
+		throw new Error('Web Crypto is not available in this runtime')
+	}
+	const bytes = new Uint8Array(byteLength)
+	// getRandomValues rejects more than 65536 bytes per call.
+	for (let offset = 0; offset < byteLength; offset += RANDOM_CHUNK_SIZE) {
+		cryptoApi.getRandomValues(
+			bytes.subarray(offset, offset + RANDOM_CHUNK_SIZE)
+		)
+	}
+	return bytes
+}
+
+/** Random base64url token. 32 bytes → 43 characters, 256 bits of entropy. */
+export function randomToken(byteLength = 32): string {
+	if (!Number.isSafeInteger(byteLength) || byteLength < 1) {
+		throw new RangeError('byteLength must be a positive integer')
+	}
+	return encodeBase64Url(randomBytes(byteLength))
+}
+
+export async function sha256(data: string | BytesLike): Promise<Uint8Array> {
+	return new Uint8Array(
+		await getSubtleCrypto().digest('SHA-256', toBytes(data))
+	)
+}
+
+export async function sha256Hex(data: string | BytesLike): Promise<string> {
+	return bytesToHex(await sha256(data))
+}
+
+export async function hmacSign(
+	secret: string | BytesLike,
+	data: string | BytesLike,
+	options: HmacSignOptions = {}
+): Promise<string> {
+	const { algorithm = 'SHA-256', encoding = 'hex' } = options
+	assertEncoding(encoding)
+	const key = await importHmacKey(secret, algorithm, 'sign')
+	const signature = await getSubtleCrypto().sign('HMAC', key, toBytes(data))
+	return ENCODERS[encoding](new Uint8Array(signature))
+}
+
+/**
+ * Checks `signature` against the HMAC of `data` using Web Crypto's `verify`
+ * (constant-time). Malformed or wrongly-prefixed signatures return `false`;
+ * configuration problems (empty secret, unknown algorithm) throw.
+ */
+export async function verifyHmacSignature(
+	secret: string | BytesLike,
+	data: string | BytesLike,
+	signature: string,
+	options: HmacVerifyOptions = {}
+): Promise<boolean> {
+	const { algorithm = 'SHA-256', encoding = 'hex', prefix } = options
+	assertEncoding(encoding)
+	const key = await importHmacKey(secret, algorithm, 'verify')
+
+	let encoded = signature
+	if (prefix !== undefined) {
+		if (!signature.startsWith(prefix)) return false
+		encoded = signature.slice(prefix.length)
+	}
+
+	let received: Uint8Array<ArrayBuffer>
+	try {
+		received = DECODERS[encoding](encoded)
+	} catch (_error) {
+		return false
+	}
+	return getSubtleCrypto().verify('HMAC', key, received, toBytes(data))
+}
+
+function importHmacKey(
+	secret: string | BytesLike,
+	algorithm: HmacAlgorithm,
+	usage: 'sign' | 'verify'
+): Promise<CryptoKey> {
+	if (!HMAC_ALGORITHMS.includes(algorithm)) {
+		throw new TypeError(`Unsupported HMAC algorithm: ${algorithm}`)
+	}
+	const keyBytes = toBytes(secret)
+	if (keyBytes.length === 0)
+		throw new TypeError('HMAC secret must not be empty')
+	return getSubtleCrypto().importKey(
+		'raw',
+		keyBytes,
+		{ name: 'HMAC', hash: algorithm },
+		false,
+		[usage]
+	)
+}
+
+function assertEncoding(encoding: SignatureEncoding): void {
+	if (!Object.hasOwn(ENCODERS, encoding)) {
+		throw new TypeError(`Unsupported signature encoding: ${encoding}`)
+	}
+}
+
+/** @internal */
+export function getSubtleCrypto(): SubtleCrypto {
+	const subtle = globalThis.crypto?.subtle
+	if (!subtle) {
+		throw new Error('Web Crypto is not available in this runtime')
+	}
+	return subtle
+}

package/src/crypto/index.ts

@@ -0,0 +1,26 @@
+export {
+	type BytesLike,
+	bytesToHex,
+	decodeBase64,
+	decodeBase64Url,
+	encodeBase64,
+	encodeBase64Url,
+	hexToBytes,
+	utf8Decode,
+	utf8Encode
+} from './encoding'
+export {
+	type HmacAlgorithm,
+	type HmacSignOptions,
+	type HmacVerifyOptions,
+	hmacSign,
+	randomBytes,
+	randomToken,
+	type SignatureEncoding,
+	safeEqual,
+	sha256,
+	sha256Hex,
+	verifyHmacSignature
+} from './hash'
+export * from './sealer'
+export * from './webhook'