@sdxc/crypto 0.0.0-pre.1

package/dist/encoding.js

@@ -0,0 +1,244 @@
+/**
+ * Hex, base64, and base64url codecs used by every other module in this package.
+ *
+ * Encoding differences (padding, letter case, URL-safe alphabet) turn into
+ * interoperability bugs when each call site rewrites them, so all three codecs
+ * live here, each with one canonical output shape and a validating decoder.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { InvalidEncodingError } from "./errors.js";
+import { toBytes, toText } from "./lib/bytes.js";
+/** Lowercase hex digits; encoding always emits from this alphabet. */
+const HEX_ALPHABET = "0123456789abcdef";
+/** Hex strings must have an even length and only hex digits, either case. */
+const HEX_PATTERN = /^(?:[0-9a-fA-F]{2})*$/;
+/** Base64url payloads allow the URL-safe alphabet plus optional trailing padding. */
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*={0,2}$/;
+/** Standard base64 payloads come in whole quartets, the last one padded to length. */
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Bytes a base64 group carries; a length off this multiple leaves a short final group. */
+const GROUP_BYTES = 3;
+/** Characters a full base64 group spans; one character past a multiple holds no whole byte. */
+const GROUP_CHARS = 4;
+/** ASCII code of `=`, the character that fills a short final group out to four. */
+const PADDING_CODE = 0x3d;
+/** Code points a reverse lookup covers, which spans every base64 character. */
+const ASCII_RANGE = 128;
+/** Standard base64 alphabet (RFC 4648 §4); a character's index is the value it carries. */
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** URL-safe base64 alphabet (RFC 4648 §5); a character's index is the value it carries. */
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/**
+ * Builds an alphabet's reverse lookup: a string whose character at each ASCII code
+ * point carries the six-bit value that code point stands for.
+ *
+ * Keying by code point resolves a character in a single `charCodeAt`, which keeps
+ * decoding linear in the input length for multi-megabyte payloads.
+ */
+function toValueLookup(alphabet) {
+    let values = Array.from({ length: ASCII_RANGE }).fill("\0");
+    for (let value = 0; value < alphabet.length; value++) {
+        values[alphabet.charCodeAt(value)] = String.fromCharCode(value);
+    }
+    return values.join("");
+}
+/** Reverse lookup for the standard alphabet, keyed by ASCII code point. */
+const BASE64_VALUES = toValueLookup(BASE64_ALPHABET);
+/** Reverse lookup for the URL-safe alphabet, keyed by ASCII code point. */
+const BASE64URL_VALUES = toValueLookup(BASE64URL_ALPHABET);
+/**
+ * Encodes bytes over a base64 alphabet, one character per six bits of input.
+ *
+ * Characters land in a single buffer sized from the input length, so a
+ * multi-megabyte payload encodes in one pass and one allocation.
+ *
+ * @param bytes Payload to encode.
+ * @param alphabet Alphabet supplying a character for each six-bit value.
+ * @param padded Whether a short final group is filled out to four characters with `=`.
+ * @returns Encoded text.
+ */
+function encodeBase64(bytes, alphabet, padded) {
+    let remainder = bytes.length % GROUP_BYTES;
+    let tail = remainder === 0 ? 0 : padded ? GROUP_CHARS : remainder + 1;
+    let out = new Uint8Array(((bytes.length - remainder) / GROUP_BYTES) * GROUP_CHARS + tail);
+    let accumulator = 0;
+    let pending = 0;
+    let cursor = 0;
+    for (let byte of bytes) {
+        accumulator = (accumulator << 8) | byte;
+        pending += 8;
+        while (pending >= 6) {
+            pending -= 6;
+            out[cursor++] = alphabet.charCodeAt((accumulator >> pending) & 0x3f);
+        }
+    }
+    if (pending > 0)
+        out[cursor++] = alphabet.charCodeAt((accumulator << (6 - pending)) & 0x3f);
+    while (cursor < out.length)
+        out[cursor++] = PADDING_CODE;
+    return toText(out);
+}
+/**
+ * Decodes base64 text written in the alphabet a reverse lookup describes.
+ *
+ * The bits a short final group leaves over must be zero, which maps the strings of
+ * each payload length one-to-one onto byte strings, so a text whose final character
+ * was altered fails the decode.
+ *
+ * @param text Text whose character set the caller has already validated.
+ * @param values Reverse lookup for the alphabet the text is written in.
+ * @param encoding Encoding name the error reports.
+ * @returns Decoded bytes, or `InvalidEncodingError` when the text is not the canonical encoding of any byte string.
+ */
+function decodeBase64(text, values, encoding) {
+    let end = text.length;
+    while (end > 0 && text.charCodeAt(end - 1) === PADDING_CODE)
+        end--;
+    let remainder = end % GROUP_CHARS;
+    if (remainder === 1)
+        return failure(new InvalidEncodingError(encoding));
+    let groups = (end - remainder) / GROUP_CHARS;
+    let bytes = new Uint8Array(groups * GROUP_BYTES + (remainder === 0 ? 0 : remainder - 1));
+    let accumulator = 0;
+    let pending = 0;
+    let cursor = 0;
+    for (let index = 0; index < end; index++) {
+        accumulator = (accumulator << 6) | values.charCodeAt(text.charCodeAt(index));
+        pending += 6;
+        if (pending >= 8) {
+            pending -= 8;
+            bytes[cursor++] = (accumulator >> pending) & 0xff;
+        }
+    }
+    if ((accumulator & ((1 << pending) - 1)) !== 0) {
+        return failure(new InvalidEncodingError(encoding));
+    }
+    return success(bytes);
+}
+/**
+ * Lowercase hexadecimal encoding, the canonical text form for digests and MACs.
+ *
+ * @example
+ * Hex.encode(new Uint8Array([255, 0])); // "ff00"
+ */
+export class Hex {
+    /**
+     * Encodes bytes (or UTF-8 text) as lowercase hex.
+     *
+     * @param data Payload to encode.
+     * @returns Hex string, two characters per byte, never padded or uppercased.
+     * @example
+     * Hex.encode("hi"); // "6869"
+     */
+    static encode(data) {
+        let bytes = toBytes(data);
+        let out = "";
+        for (let byte of bytes) {
+            out += HEX_ALPHABET.charAt(byte >> 4);
+            out += HEX_ALPHABET.charAt(byte & 0x0f);
+        }
+        return out;
+    }
+    /**
+     * Decodes a hex string, accepting either letter case.
+     *
+     * An odd length or a non-hex character rejects the whole input up front, so a
+     * truncated signature always fails verification against a prefix.
+     *
+     * @param text Hex string to decode.
+     * @returns Decoded bytes, or `InvalidEncodingError` when the input is not hex.
+     * @example
+     * Hex.decode("ff00"); // success(Uint8Array [255, 0])
+     */
+    static decode(text) {
+        if (!HEX_PATTERN.test(text))
+            return failure(new InvalidEncodingError("hex"));
+        let bytes = new Uint8Array(text.length / 2);
+        for (let index = 0; index < bytes.length; index++) {
+            bytes[index] = Number.parseInt(text.slice(index * 2, index * 2 + 2), 16);
+        }
+        return success(bytes);
+    }
+}
+/**
+ * Unpadded base64url encoding, safe in URLs, headers, and file names.
+ *
+ * @example
+ * Base64Url.encode(new Uint8Array([251, 255])); // "-_8"
+ */
+export class Base64Url {
+    /**
+     * Encodes bytes (or UTF-8 text) as base64url without `=` padding.
+     *
+     * Padding is dropped because these values travel in URLs and query strings,
+     * where `=` needs escaping; `decode` accepts it back either way.
+     *
+     * @param data Payload to encode.
+     * @returns Base64url string using only `A-Z`, `a-z`, `0-9`, `-`, and `_`.
+     * @example
+     * Base64Url.encode("hi"); // "aGk"
+     */
+    static encode(data) {
+        return encodeBase64(toBytes(data), BASE64URL_ALPHABET, false);
+    }
+    /**
+     * Decodes base64url text, tolerating present or absent `=` padding.
+     *
+     * The URL-safe alphabet is the whole accepted input set, and a short final
+     * group's leftover bits must be zero, so two accepted strings decode to the same
+     * bytes exactly when they differ only in trailing `=`.
+     *
+     * @param text Base64url string to decode.
+     * @returns Decoded bytes, or `InvalidEncodingError` when the input is not canonical base64url.
+     * @example
+     * Base64Url.decode("aGk"); // success(bytes for "hi")
+     */
+    static decode(text) {
+        if (!BASE64URL_PATTERN.test(text))
+            return failure(new InvalidEncodingError("base64url"));
+        return decodeBase64(text, BASE64URL_VALUES, "base64url");
+    }
+}
+/**
+ * Padded standard base64, the alphabet RFC 4648 §4 defines.
+ *
+ * @example
+ * Base64.encode(new Uint8Array([251, 255])); // "+/8="
+ */
+export class Base64 {
+    /**
+     * Encodes bytes (or UTF-8 text) as standard base64 with `=` padding.
+     *
+     * Text becomes its UTF-8 bytes first, so a payload outside Latin-1 encodes to
+     * the octets a peer decodes it back from, as the `user:password` credentials of
+     * HTTP Basic authentication require (RFC 7617 §2.1).
+     *
+     * @param data Payload to encode.
+     * @returns Base64 string over `A-Z`, `a-z`, `0-9`, `+`, `/`, padded to a multiple of four characters.
+     * @example
+     * Base64.encode("Aladdin:open sesame"); // "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+     */
+    static encode(data) {
+        return encodeBase64(toBytes(data), BASE64_ALPHABET, true);
+    }
+    /**
+     * Decodes standard base64 text carrying its full `=` padding.
+     *
+     * The standard alphabet with full padding is the whole accepted input set, and a
+     * short final group's leftover bits must be zero, so one byte string has exactly
+     * one accepted spelling.
+     *
+     * @param text Base64 string to decode.
+     * @returns Decoded bytes, or `InvalidEncodingError` when the input is not canonical padded base64.
+     * @example
+     * Base64.decode("aGk="); // success(bytes for "hi")
+     */
+    static decode(text) {
+        if (!BASE64_PATTERN.test(text))
+            return failure(new InvalidEncodingError("base64"));
+        return decodeBase64(text, BASE64_VALUES, "base64");
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Error values returned by every failing operation in this package.
+ *
+ * All of them extend `CryptoError`, so one `instanceof` check covers the whole
+ * package while the subclasses let callers branch on the cause. Messages carry
+ * only the shape of the problem, never secrets, hashes, or ciphertext.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Base class for every error this package returns inside a `Result`.
+ *
+ * Use it as the error type in signatures and as the `instanceof` check when
+ * callers handle every cause the same way.
+ *
+ * @example
+ * if (isFailure(result) && result.error instanceof CryptoError) reportFailure();
+ */
+export declare class CryptoError extends Error {
+    name: string;
+}
+/**
+ * A string could not be decoded with the encoding it was expected to use.
+ *
+ * The offending input is deliberately absent from the message, because the same
+ * error covers secrets such as TOTP seeds and sealed payloads.
+ *
+ * @example
+ * let bytes = Hex.decode("zz"); // failure(new InvalidEncodingError("hex"))
+ */
+export declare class InvalidEncodingError extends CryptoError {
+    name: string;
+    /**
+     * @param encoding Name of the expected encoding, such as "hex" or "base64url".
+     */
+    constructor(encoding: string);
+}
+/**
+ * A stored password hash's format diverges from the one this package writes.
+ *
+ * Callers see this for values produced by a different hashing scheme, which is
+ * the signal to fall back to a compatibility path or to force a reset.
+ */
+export declare class MalformedHashError extends CryptoError {
+    name: string;
+    /**
+     * @param reason Fixed description of the structural problem, free of stored material.
+     */
+    constructor(reason: string);
+}
+/**
+ * An algorithm identifier is syntactically valid yet unsupported here.
+ *
+ * The identifier is sanitized before it reaches the message, so a hostile stored
+ * value cannot smuggle content into logs.
+ */
+export declare class UnsupportedAlgorithmError extends CryptoError {
+    name: string;
+    /**
+     * @param algorithm Algorithm identifier, sanitized down to a short tag.
+     */
+    constructor(algorithm: string);
+}
+/**
+ * Raw key material could not be turned into a usable `CryptoKey`.
+ *
+ * Raised for wrong key sizes and for material the runtime rejects; the key bytes
+ * themselves never appear in the message.
+ */
+export declare class InvalidKeyError extends CryptoError {
+    name: string;
+    /**
+     * @param reason Fixed description of why the key was rejected.
+     */
+    constructor(reason: string);
+}
+/**
+ * A sealed value's structure diverges from the versioned envelope format.
+ *
+ * Raised before decryption begins, so it flags a structural problem independent
+ * of whether the key or the authentication tag would have matched.
+ */
+export declare class InvalidEnvelopeError extends CryptoError {
+    name: string;
+    /**
+     * @param reason Fixed description of the envelope problem, free of ciphertext.
+     */
+    constructor(reason: string);
+}
+/**
+ * Authenticated decryption failed for a well-formed envelope.
+ *
+ * The message is intentionally identical for a wrong key and for tampered
+ * ciphertext, so failures cannot be used as an oracle.
+ */
+export declare class DecryptionError extends CryptoError {
+    name: string;
+    constructor();
+}

package/dist/errors.js

@@ -0,0 +1,124 @@
+/**
+ * Error values returned by every failing operation in this package.
+ *
+ * All of them extend `CryptoError`, so one `instanceof` check covers the whole
+ * package while the subclasses let callers branch on the cause. Messages carry
+ * only the shape of the problem, never secrets, hashes, or ciphertext.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Longest algorithm tag kept in an error message before it is truncated. */
+const MAX_TAG_LENGTH = 32;
+/**
+ * Reduces a value to a short `[A-Za-z0-9-]` tag safe to place in a message.
+ *
+ * Algorithm identifiers come from stored values, so this treats them as
+ * untrusted, dropping disallowed characters and truncating the result.
+ */
+function sanitizeTag(value) {
+    let tag = value.replaceAll(/[^A-Za-z0-9-]/g, "").slice(0, MAX_TAG_LENGTH);
+    return tag.length > 0 ? tag : "unknown";
+}
+/**
+ * Base class for every error this package returns inside a `Result`.
+ *
+ * Use it as the error type in signatures and as the `instanceof` check when
+ * callers handle every cause the same way.
+ *
+ * @example
+ * if (isFailure(result) && result.error instanceof CryptoError) reportFailure();
+ */
+export class CryptoError extends Error {
+    name = "CryptoError";
+}
+/**
+ * A string could not be decoded with the encoding it was expected to use.
+ *
+ * The offending input is deliberately absent from the message, because the same
+ * error covers secrets such as TOTP seeds and sealed payloads.
+ *
+ * @example
+ * let bytes = Hex.decode("zz"); // failure(new InvalidEncodingError("hex"))
+ */
+export class InvalidEncodingError extends CryptoError {
+    name = "InvalidEncodingError";
+    /**
+     * @param encoding Name of the expected encoding, such as "hex" or "base64url".
+     */
+    constructor(encoding) {
+        super(`Invalid ${encoding} input`);
+    }
+}
+/**
+ * A stored password hash's format diverges from the one this package writes.
+ *
+ * Callers see this for values produced by a different hashing scheme, which is
+ * the signal to fall back to a compatibility path or to force a reset.
+ */
+export class MalformedHashError extends CryptoError {
+    name = "MalformedHashError";
+    /**
+     * @param reason Fixed description of the structural problem, free of stored material.
+     */
+    constructor(reason) {
+        super(`Malformed password hash: ${reason}`);
+    }
+}
+/**
+ * An algorithm identifier is syntactically valid yet unsupported here.
+ *
+ * The identifier is sanitized before it reaches the message, so a hostile stored
+ * value cannot smuggle content into logs.
+ */
+export class UnsupportedAlgorithmError extends CryptoError {
+    name = "UnsupportedAlgorithmError";
+    /**
+     * @param algorithm Algorithm identifier, sanitized down to a short tag.
+     */
+    constructor(algorithm) {
+        super(`Unsupported algorithm: ${sanitizeTag(algorithm)}`);
+    }
+}
+/**
+ * Raw key material could not be turned into a usable `CryptoKey`.
+ *
+ * Raised for wrong key sizes and for material the runtime rejects; the key bytes
+ * themselves never appear in the message.
+ */
+export class InvalidKeyError extends CryptoError {
+    name = "InvalidKeyError";
+    /**
+     * @param reason Fixed description of why the key was rejected.
+     */
+    constructor(reason) {
+        super(`Invalid key: ${reason}`);
+    }
+}
+/**
+ * A sealed value's structure diverges from the versioned envelope format.
+ *
+ * Raised before decryption begins, so it flags a structural problem independent
+ * of whether the key or the authentication tag would have matched.
+ */
+export class InvalidEnvelopeError extends CryptoError {
+    name = "InvalidEnvelopeError";
+    /**
+     * @param reason Fixed description of the envelope problem, free of ciphertext.
+     */
+    constructor(reason) {
+        super(`Invalid sealed value: ${reason}`);
+    }
+}
+/**
+ * Authenticated decryption failed for a well-formed envelope.
+ *
+ * The message is intentionally identical for a wrong key and for tampered
+ * ciphertext, so failures cannot be used as an oracle.
+ */
+export class DecryptionError extends CryptoError {
+    name = "DecryptionError";
+    constructor() {
+        super("Decryption failed");
+    }
+}

package/dist/hash.d.ts

@@ -0,0 +1,52 @@
+/**
+ * SHA-2 digests over text or binary payloads.
+ *
+ * These are the lookup hashes for values that must stay searchable, such as API
+ * keys stored as digests: the same input always produces the same bytes, so a row
+ * can be found by hashing the presented secret instead of storing it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { BinaryLike, Bytes } from "./lib/bytes.js";
+import { CryptoError } from "./errors.js";
+/**
+ * Hashes a payload with SHA-256.
+ *
+ * Unsalted and deterministic by design, which makes it right for lookups and
+ * fingerprints and wrong for passwords; use `password.hash` for those.
+ *
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The 32 digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ * @example
+ * let digest = await sha256(apiKey);
+ * if (isSuccess(digest)) lookupBy(Hex.encode(digest.data));
+ */
+export declare function sha256(data: BinaryLike): Promise<Result<Bytes, CryptoError>>;
+/**
+ * Hashes a payload with SHA-384.
+ *
+ * The digest an OpenID Connect token hash claim needs when the ID token is signed
+ * with an `ES384`, `RS384`, or `PS384` algorithm (OpenID Connect Core §3.1.3.6).
+ *
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The 48 digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ * @example
+ * let digest = unwrap(await sha384(accessToken));
+ * let atHash = Base64Url.encode(digest.subarray(0, digest.length / 2));
+ */
+export declare function sha384(data: BinaryLike): Promise<Result<Bytes, CryptoError>>;
+/**
+ * Hashes a payload with SHA-512.
+ *
+ * The digest an OpenID Connect token hash claim needs when the ID token is signed
+ * with an `ES512`, `RS512`, or `PS512` algorithm (OpenID Connect Core §3.1.3.6).
+ *
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The 64 digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ * @example
+ * let digest = unwrap(await sha512(accessToken));
+ * let atHash = Base64Url.encode(digest.subarray(0, digest.length / 2));
+ */
+export declare function sha512(data: BinaryLike): Promise<Result<Bytes, CryptoError>>;

package/dist/hash.js

@@ -0,0 +1,77 @@
+/**
+ * SHA-2 digests over text or binary payloads.
+ *
+ * These are the lookup hashes for values that must stay searchable, such as API
+ * keys stored as digests: the same input always produces the same bytes, so a row
+ * can be found by hashing the presented secret instead of storing it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { CryptoError } from "./errors.js";
+import { toBytes } from "./lib/bytes.js";
+/**
+ * Digests a payload with one WebCrypto hash, reporting a refusal as a value.
+ *
+ * Every exported digest routes through here, so the three of them agree on how
+ * text is encoded and on what a runtime failure looks like to a caller.
+ *
+ * @param algorithm Digest name as WebCrypto spells it.
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ */
+async function digest(algorithm, data) {
+    try {
+        let hashed = await crypto.subtle.digest(algorithm, toBytes(data));
+        return success(new Uint8Array(hashed));
+    }
+    catch {
+        return failure(new CryptoError(`${algorithm} digest failed`));
+    }
+}
+/**
+ * Hashes a payload with SHA-256.
+ *
+ * Unsalted and deterministic by design, which makes it right for lookups and
+ * fingerprints and wrong for passwords; use `password.hash` for those.
+ *
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The 32 digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ * @example
+ * let digest = await sha256(apiKey);
+ * if (isSuccess(digest)) lookupBy(Hex.encode(digest.data));
+ */
+export function sha256(data) {
+    return digest("SHA-256", data);
+}
+/**
+ * Hashes a payload with SHA-384.
+ *
+ * The digest an OpenID Connect token hash claim needs when the ID token is signed
+ * with an `ES384`, `RS384`, or `PS384` algorithm (OpenID Connect Core §3.1.3.6).
+ *
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The 48 digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ * @example
+ * let digest = unwrap(await sha384(accessToken));
+ * let atHash = Base64Url.encode(digest.subarray(0, digest.length / 2));
+ */
+export function sha384(data) {
+    return digest("SHA-384", data);
+}
+/**
+ * Hashes a payload with SHA-512.
+ *
+ * The digest an OpenID Connect token hash claim needs when the ID token is signed
+ * with an `ES512`, `RS512`, or `PS512` algorithm (OpenID Connect Core §3.1.3.6).
+ *
+ * @param data Text (read as UTF-8) or bytes to digest.
+ * @returns The 64 digest bytes, or a `CryptoError` if the runtime rejects the operation.
+ * @example
+ * let digest = unwrap(await sha512(accessToken));
+ * let atHash = Base64Url.encode(digest.subarray(0, digest.length / 2));
+ */
+export function sha512(data) {
+    return digest("SHA-512", data);
+}

package/dist/hmac.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 type { Result } from "@sdxc/result";
+import type { BinaryLike, Bytes } from "./lib/bytes.js";
+import { CryptoError } from "./errors.js";
+/** Hash functions WebCrypto exposes for HMAC keys. */
+declare const SUPPORTED_HASHES: readonly ["SHA-1", "SHA-256", "SHA-384", "SHA-512"];
+/**
+ * Types for the `hmac` operations.
+ */
+export declare namespace hmac {
+    /** Hash function backing an HMAC key. */
+    type Hash = (typeof SUPPORTED_HASHES)[number];
+    /** Shared options for signing and verifying. */
+    interface Options {
+        /**
+         * Hash function to key.
+         * @default "SHA-256"
+         */
+        hash?: Hash;
+    }
+}
+/**
+ * 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.
+ */
+declare function sign(secret: BinaryLike, payload: BinaryLike, options?: hmac.Options): Promise<Result<Bytes, CryptoError>>;
+/**
+ * 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") ?? "");
+ */
+declare function verify(secret: BinaryLike, payload: BinaryLike, signature: BinaryLike, options?: hmac.Options): Promise<Result<boolean, CryptoError>>;
+/**
+ * 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 declare const hmac: {
+    sign: typeof sign;
+    verify: typeof verify;
+};
+export {};