@sdxc/crypto 0.0.0-pre.1

package/dist/hmac.js

@@ -0,0 +1,75 @@
+/**
+ * HMAC signing and verification over WebCrypto.
+ *
+ * Webhooks, signed URLs, and alert payloads all need a keyed MAC, and the risky
+ * half is the comparison: `verify` derives the expected MAC and checks it in
+ * constant time so no call site has to remember to avoid `===`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { Hex } from "./encoding.js";
+import { CryptoError, UnsupportedAlgorithmError } from "./errors.js";
+import { toBytes } from "./lib/bytes.js";
+import { timingSafeEqual } from "./timing-safe-equal.js";
+/** Hash functions WebCrypto exposes for HMAC keys. */
+const SUPPORTED_HASHES = ["SHA-1", "SHA-256", "SHA-384", "SHA-512"];
+/** Hash used when a caller does not ask for one. */
+const DEFAULT_HASH = "SHA-256";
+/**
+ * Signs a payload with a secret, returning the raw MAC bytes.
+ *
+ * @param secret Key material; text is read as UTF-8.
+ * @param payload Message to authenticate.
+ * @param options Hash selection.
+ * @returns MAC bytes, or a `CryptoError` when the hash is unsupported or the runtime refuses the key.
+ */
+async function sign(secret, payload, options = {}) {
+    let hash = options.hash ?? DEFAULT_HASH;
+    if (!SUPPORTED_HASHES.includes(hash))
+        return failure(new UnsupportedAlgorithmError(hash));
+    try {
+        let key = await crypto.subtle.importKey("raw", toBytes(secret), { name: "HMAC", hash }, false, [
+            "sign",
+        ]);
+        let signature = await crypto.subtle.sign("HMAC", key, toBytes(payload));
+        return success(new Uint8Array(signature));
+    }
+    catch {
+        return failure(new CryptoError("HMAC signing failed"));
+    }
+}
+/**
+ * Recomputes the MAC for a payload and compares it in constant time. A
+ * signature given as a string decodes as hex; an undecodable string resolves
+ * to a mismatch, so a malformed header fails closed automatically.
+ *
+ * @param secret Key material; text is read as UTF-8.
+ * @param payload Message the signature is supposed to cover.
+ * @param signature MAC to check, as bytes or as a hex string.
+ * @param options Hash selection; must match the hash used to sign.
+ * @returns Whether the signature matches, or a `CryptoError` when the MAC could not be computed.
+ * @example
+ * let ok = await hmac.verify(secret, body, request.headers.get("x-signature") ?? "");
+ */
+async function verify(secret, payload, signature, options = {}) {
+    let expected = await sign(secret, payload, options);
+    if (isFailure(expected))
+        return expected;
+    if (typeof signature === "string") {
+        let decoded = Hex.decode(signature);
+        if (isFailure(decoded))
+            return success(false);
+        return success(timingSafeEqual(expected.data, decoded.data));
+    }
+    return success(timingSafeEqual(expected.data, toBytes(signature)));
+}
+/**
+ * Keyed message authentication with a constant-time verifier.
+ *
+ * @example
+ * let mac = await hmac.sign(secret, payload);
+ * let ok = await hmac.verify(secret, payload, Hex.encode(unwrap(mac)));
+ */
+export const hmac = { sign, verify };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WebCrypto primitives with `Result`-based errors, portable to any runtime.
+ *
+ * Encoding, digests, HMAC, random tokens, password hashing, TOTP, and authenticated
+ * encryption live here once, so security-relevant details are decided in one place
+ * instead of being re-derived at every call site.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { BinaryLike, Bytes } from "./lib/bytes.js";
+export { Base64, Base64Url, Hex } from "./encoding.js";
+export { CryptoError, DecryptionError, InvalidEncodingError, InvalidEnvelopeError, InvalidKeyError, MalformedHashError, UnsupportedAlgorithmError, } from "./errors.js";
+export { sha256, sha384, sha512 } from "./hash.js";
+export { hmac } from "./hmac.js";
+export { password } from "./password.js";
+export { randomBytes, randomToken } from "./random.js";
+export { importKey, open, seal } from "./seal.js";
+export { timingSafeEqual } from "./timing-safe-equal.js";
+export { totp } from "./totp.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * WebCrypto primitives with `Result`-based errors, portable to any runtime.
+ *
+ * Encoding, digests, HMAC, random tokens, password hashing, TOTP, and authenticated
+ * encryption live here once, so security-relevant details are decided in one place
+ * instead of being re-derived at every call site.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { Base64, Base64Url, Hex } from "./encoding.js";
+export { CryptoError, DecryptionError, InvalidEncodingError, InvalidEnvelopeError, InvalidKeyError, MalformedHashError, UnsupportedAlgorithmError, } from "./errors.js";
+export { sha256, sha384, sha512 } from "./hash.js";
+export { hmac } from "./hmac.js";
+export { password } from "./password.js";
+export { randomBytes, randomToken } from "./random.js";
+export { importKey, open, seal } from "./seal.js";
+export { timingSafeEqual } from "./timing-safe-equal.js";
+export { totp } from "./totp.js";

package/dist/lib/base32.d.ts

@@ -0,0 +1,33 @@
+/**
+ * RFC 4648 base32 codec, kept internal to serve TOTP secrets.
+ *
+ * Authenticator apps and `otpauth://` URIs only speak base32, so shared secrets
+ * need this alphabet even though the rest of the package standardizes on hex and
+ * base64url for its public encoding surface.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { InvalidEncodingError } from "../errors.js";
+import type { Bytes } from "./bytes.js";
+/**
+ * Encodes bytes as unpadded uppercase base32.
+ *
+ * Padding is omitted because authenticator apps reject or mangle `=` inside the
+ * `secret` parameter of an enrollment URI.
+ *
+ * @param bytes Secret material to encode.
+ * @returns Base32 string over `A-Z` and `2-7`.
+ */
+export declare function encode(bytes: Uint8Array): string;
+/**
+ * Decodes base32 text, ignoring case, padding, and separating whitespace.
+ *
+ * Users retype secrets by hand and apps present them in spaced groups; any other
+ * character fails, so a typo never silently decodes differently.
+ *
+ * @param text Base32 string to decode.
+ * @returns Decoded bytes, or `InvalidEncodingError` when a character is invalid.
+ */
+export declare function decode(text: string): Result<Bytes, InvalidEncodingError>;

package/dist/lib/base32.js

@@ -0,0 +1,70 @@
+/**
+ * RFC 4648 base32 codec, kept internal to serve TOTP secrets.
+ *
+ * Authenticator apps and `otpauth://` URIs only speak base32, so shared secrets
+ * need this alphabet even though the rest of the package standardizes on hex and
+ * base64url for its public encoding surface.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { InvalidEncodingError } from "../errors.js";
+/** RFC 4648 base32 alphabet, uppercase and without the padding character. */
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/** Bits contributed by one base32 character. */
+const BITS_PER_CHAR = 5;
+/** Bits in one byte, the width drained from the accumulator per output byte. */
+const BITS_PER_BYTE = 8;
+/**
+ * Encodes bytes as unpadded uppercase base32.
+ *
+ * Padding is omitted because authenticator apps reject or mangle `=` inside the
+ * `secret` parameter of an enrollment URI.
+ *
+ * @param bytes Secret material to encode.
+ * @returns Base32 string over `A-Z` and `2-7`.
+ */
+export function encode(bytes) {
+    let out = "";
+    let buffer = 0;
+    let bits = 0;
+    for (let byte of bytes) {
+        buffer = (buffer << BITS_PER_BYTE) | byte;
+        bits += BITS_PER_BYTE;
+        while (bits >= BITS_PER_CHAR) {
+            bits -= BITS_PER_CHAR;
+            out += BASE32_ALPHABET.charAt((buffer >> bits) & 0x1f);
+        }
+    }
+    if (bits > 0)
+        out += BASE32_ALPHABET.charAt((buffer << (BITS_PER_CHAR - bits)) & 0x1f);
+    return out;
+}
+/**
+ * Decodes base32 text, ignoring case, padding, and separating whitespace.
+ *
+ * Users retype secrets by hand and apps present them in spaced groups; any other
+ * character fails, so a typo never silently decodes differently.
+ *
+ * @param text Base32 string to decode.
+ * @returns Decoded bytes, or `InvalidEncodingError` when a character is invalid.
+ */
+export function decode(text) {
+    let normalized = text.replaceAll(/[\s-]/g, "").replace(/=+$/, "").toUpperCase();
+    let bytes = [];
+    let buffer = 0;
+    let bits = 0;
+    for (let char of normalized) {
+        let value = BASE32_ALPHABET.indexOf(char);
+        if (value === -1)
+            return failure(new InvalidEncodingError("base32"));
+        buffer = (buffer << BITS_PER_CHAR) | value;
+        bits += BITS_PER_CHAR;
+        if (bits >= BITS_PER_BYTE) {
+            bits -= BITS_PER_BYTE;
+            bytes.push((buffer >> bits) & 0xff);
+        }
+    }
+    return success(new Uint8Array(bytes));
+}

package/dist/lib/bytes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Byte conversion helpers shared by every module in this package.
+ *
+ * One `TextEncoder`/`TextDecoder` pair is reused so string payloads always turn
+ * into the same UTF-8 bytes, and every public function can accept text or binary
+ * without each module re-deciding what "data" means.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Data accepted wherever this package takes "bytes": text is read as UTF-8.
+ *
+ * @example
+ * await sha256("hello");
+ * await sha256(new Uint8Array([1, 2, 3]));
+ */
+export type BinaryLike = string | Uint8Array | ArrayBuffer;
+/**
+ * Byte buffers this package produces: views over a non-shared `ArrayBuffer`.
+ *
+ * WebCrypto refuses views backed by a `SharedArrayBuffer`, so every function that
+ * returns bytes returns them in a form that can be fed straight back in.
+ */
+export type Bytes = Uint8Array<ArrayBuffer>;
+/**
+ * Normalizes any accepted input into bytes WebCrypto will accept.
+ *
+ * An `ArrayBuffer` is wrapped directly, so callers must not mutate a buffer once
+ * handed over; only a `SharedArrayBuffer` view is copied.
+ *
+ * @param data Text or binary payload.
+ * @returns Bytes backing the payload.
+ */
+export declare function toBytes(data: BinaryLike): Bytes;
+/**
+ * Decodes bytes as UTF-8 text, substituting the replacement character for invalid sequences.
+ *
+ * Authenticated decryption already proves the bytes are the ones that were
+ * sealed, so a lossy decode here means the plaintext held non-UTF-8 bytes.
+ *
+ * @param bytes Bytes to read as text.
+ * @returns Decoded string.
+ */
+export declare function toText(bytes: Uint8Array): string;

package/dist/lib/bytes.js

@@ -0,0 +1,44 @@
+/**
+ * Byte conversion helpers shared by every module in this package.
+ *
+ * One `TextEncoder`/`TextDecoder` pair is reused so string payloads always turn
+ * into the same UTF-8 bytes, and every public function can accept text or binary
+ * without each module re-deciding what "data" means.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Shared UTF-8 encoder, so string inputs hash and sign identically everywhere. */
+const ENCODER = new TextEncoder();
+/** Shared UTF-8 decoder used to read plaintext back out of byte buffers. */
+const DECODER = new TextDecoder();
+/**
+ * Normalizes any accepted input into bytes WebCrypto will accept.
+ *
+ * An `ArrayBuffer` is wrapped directly, so callers must not mutate a buffer once
+ * handed over; only a `SharedArrayBuffer` view is copied.
+ *
+ * @param data Text or binary payload.
+ * @returns Bytes backing the payload.
+ */
+export function toBytes(data) {
+    if (typeof data === "string")
+        return ENCODER.encode(data);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (data.buffer instanceof ArrayBuffer)
+        return data;
+    return new Uint8Array(data);
+}
+/**
+ * Decodes bytes as UTF-8 text, substituting the replacement character for invalid sequences.
+ *
+ * Authenticated decryption already proves the bytes are the ones that were
+ * sealed, so a lossy decode here means the plaintext held non-UTF-8 bytes.
+ *
+ * @param bytes Bytes to read as text.
+ * @returns Decoded string.
+ */
+export function toText(bytes) {
+    return DECODER.decode(bytes);
+}

package/dist/password.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Password hashing with PBKDF2-HMAC-SHA256 through WebCrypto.
+ *
+ * Hashes are stored in a self-describing string that carries its own cost
+ * parameters, so the iteration count can be raised without a schema change:
+ * verification uses the parameters found in the stored value, and `needsRehash`
+ * reports when that value is behind current policy.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { CryptoError } from "./errors.js";
+/**
+ * Hashes a password with the current policy and a fresh random salt.
+ *
+ * @param secret Plaintext password.
+ * @returns Encoded hash such as `$pbkdf2-sha256$i=600000$<salt>$<key>`, or a `CryptoError`.
+ * @example
+ * let stored = await password.hash(form.password);
+ */
+declare function hash(secret: string): Promise<Result<string, CryptoError>>;
+/**
+ * Checks a password against an encoded hash using the hash's own parameters.
+ *
+ * A wrong password is `success(false)`; only an unusable stored value or a runtime
+ * failure is a `Failure`, which keeps "wrong password" and "cannot check" apart.
+ *
+ * @param stored Encoded hash previously produced by `hash`.
+ * @param secret Plaintext password to check.
+ * @returns Whether the password matches, or why the check could not run.
+ * @example
+ * let ok = await password.verify(user.passwordHash, form.password);
+ */
+declare function verify(stored: string, secret: string): Promise<Result<boolean, CryptoError>>;
+/**
+ * Reports whether a stored hash is behind current policy.
+ *
+ * True for a lower iteration count, a shorter salt or key, or a value this
+ * module cannot parse, matching how upgrade-on-login replaces foreign hashes.
+ *
+ * @param stored Encoded hash to inspect.
+ * @returns Whether the value should be replaced after the next successful login.
+ * @example
+ * if (isValid && password.needsRehash(user.passwordHash)) await rehash(form.password);
+ */
+declare function needsRehash(stored: string): boolean;
+/**
+ * Password hashing, verification, and upgrade detection.
+ *
+ * @example
+ * let stored = unwrap(await password.hash("secret"));
+ * let ok = unwrap(await password.verify(stored, "secret")); // true
+ * password.needsRehash(stored); // false
+ */
+export declare const password: {
+    hash: typeof hash;
+    verify: typeof verify;
+    needsRehash: typeof needsRehash;
+};
+export {};

package/dist/password.js

@@ -0,0 +1,163 @@
+/**
+ * Password hashing with PBKDF2-HMAC-SHA256 through WebCrypto.
+ *
+ * Hashes are stored in a self-describing string that carries its own cost
+ * parameters, so the iteration count can be raised without a schema change:
+ * verification uses the parameters found in the stored value, and `needsRehash`
+ * reports when that value is behind current policy.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { Base64Url } from "./encoding.js";
+import { CryptoError, MalformedHashError, UnsupportedAlgorithmError } from "./errors.js";
+import { toBytes } from "./lib/bytes.js";
+import { randomBytes } from "./random.js";
+import { timingSafeEqual } from "./timing-safe-equal.js";
+/**
+ * Current iteration count for new hashes.
+ *
+ * PBKDF2 is not memory-hard, so this number carries the entire cost budget;
+ * raising it is the whole upgrade, since `needsRehash` reports the change.
+ */
+const PBKDF2_ITERATIONS = 600_000;
+/** Salt length for new hashes, in bytes. */
+const PBKDF2_SALT_BYTES = 16;
+/** Derived key length for new hashes, in bytes. */
+const PBKDF2_KEY_BYTES = 32;
+/** Algorithm tag written into, and required by, the encoded format. */
+const PBKDF2_ALGORITHM_ID = "pbkdf2-sha256";
+/** Hash function inside PBKDF2, fixed by the algorithm tag. */
+const PBKDF2_HASH = "SHA-256";
+/** Upper bound on a stored iteration count, so a bad value cannot stall a request. */
+const PBKDF2_MAX_ITERATIONS = 10_000_000;
+/** Number of fields in the encoded format, counting the leading empty one. */
+const ENCODED_FIELDS = 5;
+/** Only supported parameter field: the iteration count. */
+const ITERATIONS_PARAM = /^i=(\d+)$/;
+/** Bits per byte, used to turn a key length into a `deriveBits` length. */
+const BITS_PER_BYTE = 8;
+/**
+ * Parses an encoded hash into its cost parameters and material.
+ *
+ * Anything not written by this module is a failure, which is the signal a caller
+ * needs to route the value to a legacy verifier instead of guessing.
+ *
+ * @param stored Encoded hash string.
+ * @returns Parsed parameters, or the reason the value is unusable.
+ */
+function parse(stored) {
+    let fields = stored.split("$");
+    if (fields.length !== ENCODED_FIELDS || fields[0] !== "") {
+        return failure(new MalformedHashError("unexpected field count"));
+    }
+    let [, algorithm = "", params = "", salt = "", key = ""] = fields;
+    if (algorithm !== PBKDF2_ALGORITHM_ID)
+        return failure(new UnsupportedAlgorithmError(algorithm));
+    let match = ITERATIONS_PARAM.exec(params);
+    if (!match?.[1])
+        return failure(new MalformedHashError("unreadable parameters"));
+    let iterations = Number.parseInt(match[1], 10);
+    if (iterations < 1 || iterations > PBKDF2_MAX_ITERATIONS) {
+        return failure(new MalformedHashError("iteration count out of range"));
+    }
+    let decodedSalt = Base64Url.decode(salt);
+    if (isFailure(decodedSalt) || decodedSalt.data.length === 0) {
+        return failure(new MalformedHashError("unreadable salt"));
+    }
+    let decodedKey = Base64Url.decode(key);
+    if (isFailure(decodedKey) || decodedKey.data.length === 0) {
+        return failure(new MalformedHashError("unreadable derived key"));
+    }
+    return success({ iterations, salt: decodedSalt.data, key: decodedKey.data });
+}
+/**
+ * Runs PBKDF2-HMAC-SHA256 over a secret with the given cost parameters.
+ *
+ * @param secret Plaintext password.
+ * @param salt Salt to derive with.
+ * @param iterations Iteration count to apply.
+ * @param length Output length in bytes.
+ * @returns Derived bytes, or a `CryptoError` if the runtime refuses the derivation.
+ */
+async function derive(secret, salt, iterations, length) {
+    try {
+        let key = await crypto.subtle.importKey("raw", toBytes(secret), "PBKDF2", false, [
+            "deriveBits",
+        ]);
+        let bits = await crypto.subtle.deriveBits({ name: "PBKDF2", salt, iterations, hash: PBKDF2_HASH }, key, length * BITS_PER_BYTE);
+        return success(new Uint8Array(bits));
+    }
+    catch {
+        return failure(new CryptoError("Password derivation failed"));
+    }
+}
+/**
+ * Hashes a password with the current policy and a fresh random salt.
+ *
+ * @param secret Plaintext password.
+ * @returns Encoded hash such as `$pbkdf2-sha256$i=600000$<salt>$<key>`, or a `CryptoError`.
+ * @example
+ * let stored = await password.hash(form.password);
+ */
+async function hash(secret) {
+    let salt = randomBytes(PBKDF2_SALT_BYTES);
+    let derived = await derive(secret, salt, PBKDF2_ITERATIONS, PBKDF2_KEY_BYTES);
+    if (isFailure(derived))
+        return derived;
+    let encodedSalt = Base64Url.encode(salt);
+    let encodedKey = Base64Url.encode(derived.data);
+    return success(`$${PBKDF2_ALGORITHM_ID}$i=${PBKDF2_ITERATIONS}$${encodedSalt}$${encodedKey}`);
+}
+/**
+ * Checks a password against an encoded hash using the hash's own parameters.
+ *
+ * A wrong password is `success(false)`; only an unusable stored value or a runtime
+ * failure is a `Failure`, which keeps "wrong password" and "cannot check" apart.
+ *
+ * @param stored Encoded hash previously produced by `hash`.
+ * @param secret Plaintext password to check.
+ * @returns Whether the password matches, or why the check could not run.
+ * @example
+ * let ok = await password.verify(user.passwordHash, form.password);
+ */
+async function verify(stored, secret) {
+    let parsed = parse(stored);
+    if (isFailure(parsed))
+        return parsed;
+    let derived = await derive(secret, parsed.data.salt, parsed.data.iterations, parsed.data.key.length);
+    if (isFailure(derived))
+        return derived;
+    return success(timingSafeEqual(derived.data, parsed.data.key));
+}
+/**
+ * Reports whether a stored hash is behind current policy.
+ *
+ * True for a lower iteration count, a shorter salt or key, or a value this
+ * module cannot parse, matching how upgrade-on-login replaces foreign hashes.
+ *
+ * @param stored Encoded hash to inspect.
+ * @returns Whether the value should be replaced after the next successful login.
+ * @example
+ * if (isValid && password.needsRehash(user.passwordHash)) await rehash(form.password);
+ */
+function needsRehash(stored) {
+    let parsed = parse(stored);
+    if (isFailure(parsed))
+        return true;
+    if (parsed.data.iterations < PBKDF2_ITERATIONS)
+        return true;
+    if (parsed.data.salt.length < PBKDF2_SALT_BYTES)
+        return true;
+    return parsed.data.key.length < PBKDF2_KEY_BYTES;
+}
+/**
+ * Password hashing, verification, and upgrade detection.
+ *
+ * @example
+ * let stored = unwrap(await password.hash("secret"));
+ * let ok = unwrap(await password.verify(stored, "secret")); // true
+ * password.needsRehash(stored); // false
+ */
+export const password = { hash, verify, needsRehash };

package/dist/random.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cryptographically strong random bytes and the tokens built from them.
+ *
+ * `randomToken` is the shape most secrets in the repository need: enough entropy
+ * to be unguessable, base64url so it survives URLs and headers, and an optional
+ * prefix that makes a leaked key greppable and revocable by kind.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Bytes } from "./lib/bytes.js";
+/**
+ * Fills a new buffer with cryptographically strong random bytes.
+ *
+ * @param size Number of bytes to generate; must be an integer in 0..65536.
+ * @returns A fresh buffer of exactly `size` random bytes.
+ * @throws {RangeError} If `size` is not an integer within the range the runtime can fill.
+ * @example
+ * let iv = randomBytes(12);
+ */
+export declare function randomBytes(size: number): Bytes;
+/**
+ * Types for `randomToken`.
+ */
+export declare namespace randomToken {
+    /** Token shape and entropy. */
+    interface Options {
+        /**
+         * Bytes of entropy behind the token.
+         * @default 32
+         */
+        bytes?: number;
+        /**
+         * Prefix joined with `_`, so a leaked key is searchable and attributable.
+         * @example "sk"
+         */
+        prefix?: string;
+    }
+}
+/**
+ * Generates a URL-safe random token, optionally namespaced by a prefix.
+ *
+ * Unpadded base64url avoids escaping in a URL, header, or file name; the
+ * prefix lets a leaked token be recognized and revoked by kind.
+ *
+ * @param options Entropy and prefix.
+ * @returns The token, as `<prefix>_<random>` when a prefix is given.
+ * @throws {RangeError} If `options.bytes` is not an integer the runtime can fill.
+ * @example
+ * randomToken({ bytes: 32, prefix: "sk" }); // "sk_9f1...".
+ */
+export declare function randomToken(options?: randomToken.Options): string;

package/dist/random.js

@@ -0,0 +1,50 @@
+/**
+ * Cryptographically strong random bytes and the tokens built from them.
+ *
+ * `randomToken` is the shape most secrets in the repository need: enough entropy
+ * to be unguessable, base64url so it survives URLs and headers, and an optional
+ * prefix that makes a leaked key greppable and revocable by kind.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { Base64Url } from "./encoding.js";
+/** Largest buffer `crypto.getRandomValues` fills in a single call. */
+const MAX_RANDOM_BYTES = 65536;
+/** Entropy used when a caller does not pick a size: 256 bits. */
+const DEFAULT_TOKEN_BYTES = 32;
+/** Character joining a token prefix to its random part. */
+const PREFIX_SEPARATOR = "_";
+/**
+ * Fills a new buffer with cryptographically strong random bytes.
+ *
+ * @param size Number of bytes to generate; must be an integer in 0..65536.
+ * @returns A fresh buffer of exactly `size` random bytes.
+ * @throws {RangeError} If `size` is not an integer within the range the runtime can fill.
+ * @example
+ * let iv = randomBytes(12);
+ */
+export function randomBytes(size) {
+    if (!Number.isInteger(size) || size < 0 || size > MAX_RANDOM_BYTES) {
+        throw new RangeError(`randomBytes size must be an integer between 0 and ${MAX_RANDOM_BYTES}`);
+    }
+    return crypto.getRandomValues(new Uint8Array(size));
+}
+/**
+ * Generates a URL-safe random token, optionally namespaced by a prefix.
+ *
+ * Unpadded base64url avoids escaping in a URL, header, or file name; the
+ * prefix lets a leaked token be recognized and revoked by kind.
+ *
+ * @param options Entropy and prefix.
+ * @returns The token, as `<prefix>_<random>` when a prefix is given.
+ * @throws {RangeError} If `options.bytes` is not an integer the runtime can fill.
+ * @example
+ * randomToken({ bytes: 32, prefix: "sk" }); // "sk_9f1...".
+ */
+export function randomToken(options = {}) {
+    let token = Base64Url.encode(randomBytes(options.bytes ?? DEFAULT_TOKEN_BYTES));
+    if (!options.prefix)
+        return token;
+    return `${options.prefix}${PREFIX_SEPARATOR}${token}`;
+}