@daloyjs/core 0.36.0 → 0.38.0

package/dist/http-signatures.js

@@ -0,0 +1,782 @@
+/**
+ * HTTP Message Signatures (RFC 9421).
+ *
+ * First-party, dependency-free sign + verify for server-to-server request
+ * authentication. Where {@link "./security.js" | verifyWebhookSignature} binds
+ * an HMAC to a request *body* and {@link "./mtls.js" | clientCertAuth}
+ * authenticates the TLS *peer*, HTTP Message Signatures bind a signature to a
+ * caller-chosen set of **HTTP message components** (method, path, authority,
+ * selected headers, …) carried in the standard `Signature` /
+ * `Signature-Input` headers — the IETF-standard answer to "prove this internal
+ * call came from a trusted peer."
+ *
+ * The implementation is runtime-portable (WebCrypto only — no `node:` imports)
+ * and secure-by-default on the verify path:
+ *
+ * - The verifier requires an explicit {@link VerifyMessageOptions.algorithms}
+ *   allowlist; there is no implicit "accept any algorithm" mode, and a
+ *   resolved key may pin its own algorithm to defeat algorithm-confusion.
+ * - `created` is required by default and the signature is rejected once it is
+ *   older than {@link DEFAULT_MAX_SIGNATURE_AGE_SECONDS}, or if `created` is in
+ *   the future / `expires` has passed (outside a small clock-skew tolerance).
+ * - A configurable {@link VerifyMessageOptions.requiredComponents} set must be
+ *   covered, so a peer cannot sign an empty/irrelevant component set.
+ * - Raw HMAC keys must be at least 32 bytes (RFC 7518 §3.2 floor); SHA-1 and
+ *   `alg: "none"`-style escapes do not exist.
+ *
+ * Supported algorithms map 1:1 onto the RFC 9421 HTTP Signature Algorithms
+ * registry: `hmac-sha256`, `ed25519`, `ecdsa-p256-sha256`, `ecdsa-p384-sha384`,
+ * `rsa-pss-sha512`, and `rsa-v1_5-sha256`.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { UnauthorizedError } from "./errors.js";
+/** Default signature label used when the caller does not supply one. */
+export const DEFAULT_SIGNATURE_LABEL = "sig1";
+/**
+ * Default maximum age (seconds) a signature's `created` timestamp may have
+ * before the verifier rejects it as stale. Mirrors the webhook-HMAC and
+ * Standard-Webhooks five-minute convention.
+ *
+ * @since 0.37.0
+ */
+export const DEFAULT_MAX_SIGNATURE_AGE_SECONDS = 300;
+/** Default clock-skew tolerance (seconds) for future `created` / `expires`. */
+export const DEFAULT_SIGNATURE_CLOCK_SKEW_SECONDS = 60;
+/** Hard cap on the length of a parsed `Signature` / `Signature-Input` header. */
+const MAX_HEADER_LENGTH = 8192;
+/** Minimum byte length for a raw HMAC secret (RFC 7518 §3.2). */
+const MIN_HMAC_KEY_BYTES = 32;
+const ENC = new TextEncoder();
+// ---------------------------------------------------------------------------
+// WebCrypto + encoding helpers
+// ---------------------------------------------------------------------------
+function getCrypto() {
+    const c = globalThis
+        .crypto;
+    if (!c?.subtle) {
+        throw new Error("http-signatures: WebCrypto SubtleCrypto API is unavailable on this runtime.");
+    }
+    return c;
+}
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function base64ToBytes(b64) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64) || b64.length % 4 !== 0)
+        return null;
+    try {
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+function isJsonWebKey(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        typeof v.kty === "string");
+}
+function isCryptoKey(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.type === "string" &&
+        typeof v.algorithm === "object");
+}
+function algSpec(alg) {
+    switch (alg) {
+        case "hmac-sha256":
+            return {
+                importParams: { name: "HMAC", hash: "SHA-256" },
+                signParams: { name: "HMAC" },
+                symmetric: true,
+            };
+        case "ed25519":
+            return {
+                importParams: { name: "Ed25519" },
+                signParams: { name: "Ed25519" },
+                symmetric: false,
+            };
+        case "ecdsa-p256-sha256":
+            return {
+                importParams: { name: "ECDSA", namedCurve: "P-256" },
+                signParams: { name: "ECDSA", hash: "SHA-256" },
+                symmetric: false,
+            };
+        case "ecdsa-p384-sha384":
+            return {
+                importParams: { name: "ECDSA", namedCurve: "P-384" },
+                signParams: { name: "ECDSA", hash: "SHA-384" },
+                symmetric: false,
+            };
+        case "rsa-pss-sha512":
+            return {
+                importParams: { name: "RSA-PSS", hash: "SHA-512" },
+                signParams: { name: "RSA-PSS", saltLength: 64 },
+                symmetric: false,
+            };
+        case "rsa-v1_5-sha256":
+            return {
+                importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+                signParams: { name: "RSASSA-PKCS1-v1_5" },
+                symmetric: false,
+            };
+    }
+}
+async function importKey(alg, material, usage) {
+    const spec = algSpec(alg);
+    const c = getCrypto();
+    if (isCryptoKey(material))
+        return material;
+    if (material instanceof Uint8Array) {
+        if (!spec.symmetric) {
+            throw new TypeError(`http-signatures: raw byte keys are only supported for hmac-sha256; got ${alg}.`);
+        }
+        if (material.byteLength < MIN_HMAC_KEY_BYTES) {
+            throw new TypeError(`http-signatures: hmac-sha256 secret must be at least ${MIN_HMAC_KEY_BYTES} bytes (RFC 7518 §3.2); got ${material.byteLength}.`);
+        }
+        return c.subtle.importKey("raw", material, spec.importParams, false, [usage]);
+    }
+    if (isJsonWebKey(material)) {
+        return c.subtle.importKey("jwk", material, spec.importParams, false, [
+            usage,
+        ]);
+    }
+    throw new TypeError("http-signatures: unsupported key material.");
+}
+function serializeSfString(s) {
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code < 0x20 || code > 0x7e) {
+            throw new TypeError(`http-signatures: value contains a non-printable-ASCII character and cannot be serialized as a structured-field string: ${JSON.stringify(s)}`);
+        }
+    }
+    return `"${s.replace(/([\\"])/g, "\\$1")}"`;
+}
+function serializeComponentId(c) {
+    let out = serializeSfString(c.name);
+    if (c.paramName !== undefined)
+        out += `;name=${serializeSfString(c.paramName)}`;
+    if (c.req)
+        out += ";req";
+    return out;
+}
+function serializeSignatureInput(components, params) {
+    let out = `(${components.map(serializeComponentId).join(" ")})`;
+    if (params.created !== undefined)
+        out += `;created=${params.created}`;
+    if (params.expires !== undefined)
+        out += `;expires=${params.expires}`;
+    if (params.keyid !== undefined)
+        out += `;keyid=${serializeSfString(params.keyid)}`;
+    if (params.alg !== undefined)
+        out += `;alg=${serializeSfString(params.alg)}`;
+    if (params.nonce !== undefined)
+        out += `;nonce=${serializeSfString(params.nonce)}`;
+    if (params.tag !== undefined)
+        out += `;tag=${serializeSfString(params.tag)}`;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Structured-field parsing (RFC 8941 subset)
+// ---------------------------------------------------------------------------
+class SfParseError extends Error {
+}
+function readSfString(src, start) {
+    if (src[start] !== '"')
+        throw new SfParseError("expected string");
+    let i = start + 1;
+    let out = "";
+    while (i < src.length) {
+        const ch = src[i];
+        if (ch === "\\") {
+            const next = src[i + 1];
+            if (next !== '"' && next !== "\\")
+                throw new SfParseError("bad escape");
+            out += next;
+            i += 2;
+            continue;
+        }
+        if (ch === '"')
+            return [out, i + 1];
+        const code = ch.charCodeAt(0);
+        if (code < 0x20 || code > 0x7e)
+            throw new SfParseError("bad string char");
+        out += ch;
+        i++;
+    }
+    throw new SfParseError("unterminated string");
+}
+function readKey(src, start) {
+    let i = start;
+    if (!/[a-z*]/.test(src[i] ?? ""))
+        throw new SfParseError("bad key start");
+    let out = "";
+    while (i < src.length && /[a-z0-9_\-.*]/.test(src[i])) {
+        out += src[i];
+        i++;
+    }
+    return [out, i];
+}
+/** Parse `;key=value` / `;key` params starting at `;`. */
+function readParams(src, start) {
+    const params = Object.create(null);
+    let i = start;
+    while (i < src.length && src[i] === ";") {
+        i++;
+        while (src[i] === " ")
+            i++;
+        const [key, ni] = readKey(src, i);
+        i = ni;
+        if (src[i] === "=") {
+            i++;
+            if (src[i] === '"') {
+                const [val, nj] = readSfString(src, i);
+                params[key] = val;
+                i = nj;
+            }
+            else if (src[i] === "?") {
+                if (src[i + 1] === "1")
+                    params[key] = true;
+                else if (src[i + 1] === "0")
+                    params[key] = false;
+                else
+                    throw new SfParseError("bad boolean");
+                i += 2;
+            }
+            else {
+                const m = /^-?\d+/.exec(src.slice(i));
+                if (!m)
+                    throw new SfParseError("bad param value");
+                params[key] = Number(m[0]);
+                i += m[0].length;
+            }
+        }
+        else {
+            params[key] = true;
+        }
+    }
+    return [params, i];
+}
+function toSignatureParams(raw) {
+    const out = {};
+    if (typeof raw.created === "number")
+        out.created = raw.created;
+    if (typeof raw.expires === "number")
+        out.expires = raw.expires;
+    if (typeof raw.keyid === "string")
+        out.keyid = raw.keyid;
+    if (typeof raw.alg === "string")
+        out.alg = raw.alg;
+    if (typeof raw.nonce === "string")
+        out.nonce = raw.nonce;
+    if (typeof raw.tag === "string")
+        out.tag = raw.tag;
+    return out;
+}
+/** Parse one `(...)<params>` inner list starting at `(`. */
+function parseInnerList(src, start) {
+    if (src[start] !== "(")
+        throw new SfParseError("expected inner list");
+    let i = start + 1;
+    const components = [];
+    while (i < src.length && src[i] !== ")") {
+        while (src[i] === " ")
+            i++;
+        if (src[i] === ")")
+            break;
+        const [name, ni] = readSfString(src, i);
+        i = ni;
+        const [cParams, nj] = readParams(src, i);
+        i = nj;
+        const comp = { name };
+        if (typeof cParams.name === "string")
+            comp.paramName = cParams.name;
+        if (cParams.req === true)
+            comp.req = true;
+        components.push(comp);
+        while (src[i] === " ")
+            i++;
+    }
+    if (src[i] !== ")")
+        throw new SfParseError("unterminated inner list");
+    i++;
+    const [rawParams, nk] = readParams(src, i);
+    i = nk;
+    const raw = src.slice(start, i).trim();
+    return [{ components, params: toSignatureParams(rawParams), raw }, i];
+}
+/** Parse the `Signature-Input` dictionary into a label → inner-list map. */
+function parseSignatureInput(headerValue) {
+    const out = new Map();
+    const src = headerValue;
+    let i = 0;
+    while (i < src.length) {
+        while (src[i] === " " || src[i] === "\t" || src[i] === ",")
+            i++;
+        if (i >= src.length)
+            break;
+        const [label, ni] = readKey(src, i);
+        i = ni;
+        if (src[i] !== "=")
+            throw new SfParseError("expected = after label");
+        i++;
+        const [inner, nj] = parseInnerList(src, i);
+        i = nj;
+        out.set(label, inner);
+    }
+    return out;
+}
+/** Parse the `Signature` dictionary into a label → raw bytes map. */
+function parseSignature(headerValue) {
+    const out = new Map();
+    const src = headerValue;
+    let i = 0;
+    while (i < src.length) {
+        while (src[i] === " " || src[i] === "\t" || src[i] === ",")
+            i++;
+        if (i >= src.length)
+            break;
+        const [label, ni] = readKey(src, i);
+        i = ni;
+        if (src[i] !== "=")
+            throw new SfParseError("expected = after label");
+        i++;
+        if (src[i] !== ":")
+            throw new SfParseError("expected byte sequence");
+        const end = src.indexOf(":", i + 1);
+        if (end === -1)
+            throw new SfParseError("unterminated byte sequence");
+        const b64 = src.slice(i + 1, end);
+        const bytes = base64ToBytes(b64);
+        if (!bytes)
+            throw new SfParseError("bad base64");
+        out.set(label, bytes);
+        i = end + 1;
+    }
+    return out;
+}
+class ComponentError extends Error {
+}
+function resolveComponentValue(c, msg) {
+    const name = c.name;
+    if (name === "@signature-params") {
+        throw new ComponentError("@signature-params cannot be a covered component");
+    }
+    if (name.startsWith("@")) {
+        if (c.req) {
+            throw new ComponentError(`the ;req parameter is not supported on ${name} in this context`);
+        }
+        switch (name) {
+            case "@method":
+                return msg.method.toUpperCase();
+            case "@target-uri":
+                return msg.url.href;
+            case "@authority":
+                return msg.url.host.toLowerCase();
+            case "@scheme":
+                return msg.url.protocol.replace(/:$/, "").toLowerCase();
+            case "@request-target":
+                return `${msg.url.pathname}${msg.url.search}`;
+            case "@path":
+                return msg.url.pathname;
+            case "@query":
+                return msg.url.search === "" ? "?" : msg.url.search;
+            case "@query-param": {
+                if (c.paramName === undefined) {
+                    throw new ComponentError("@query-param requires a ;name parameter");
+                }
+                const values = msg.url.searchParams.getAll(c.paramName);
+                if (values.length === 0) {
+                    throw new ComponentError(`@query-param;name="${c.paramName}" is not present in the query`);
+                }
+                return values[0];
+            }
+            case "@status":
+                if (msg.status === undefined) {
+                    throw new ComponentError("@status is only valid for responses");
+                }
+                return String(msg.status);
+            default:
+                throw new ComponentError(`unknown derived component ${name}`);
+        }
+    }
+    // HTTP field component.
+    if (name !== name.toLowerCase()) {
+        throw new ComponentError(`field component name must be lowercase: ${name}`);
+    }
+    if (c.req) {
+        throw new ComponentError("the ;req parameter is not supported in this context");
+    }
+    const value = msg.headers.get(name);
+    if (value === null) {
+        throw new ComponentError(`covered header "${name}" is not present`);
+    }
+    return value.trim().replace(/[ \t]*\r?\n[ \t]*/g, " ");
+}
+function buildSignatureBase(components, signatureParamsValue, msg) {
+    const seen = new Set();
+    let base = "";
+    for (const c of components) {
+        const id = serializeComponentId(c);
+        if (seen.has(id)) {
+            throw new ComponentError(`duplicate covered component ${id}`);
+        }
+        seen.add(id);
+        base += `${id}: ${resolveComponentValue(c, msg)}\n`;
+    }
+    base += `"@signature-params": ${signatureParamsValue}`;
+    return base;
+}
+function toHeaders(init) {
+    return init instanceof Headers ? init : new Headers(init ?? {});
+}
+function parseComponentSpec(spec) {
+    // Accept the canonical serialized form ("@query-param";name="x") or the
+    // bare convenience form `@query-param;name=x`.
+    if (spec.startsWith('"')) {
+        const [name, idx] = readSfString(spec, 0);
+        const [params] = readParams(spec, idx);
+        const comp = { name };
+        if (typeof params.name === "string")
+            comp.paramName = params.name;
+        if (params.req === true)
+            comp.req = true;
+        return comp;
+    }
+    const semi = spec.indexOf(";");
+    if (semi === -1)
+        return { name: spec };
+    const name = spec.slice(0, semi);
+    const comp = { name };
+    for (const part of spec.slice(semi + 1).split(";")) {
+        if (part === "req")
+            comp.req = true;
+        else if (part.startsWith("name=")) {
+            comp.paramName = part.slice(5).replace(/^"|"$/g, "");
+        }
+    }
+    return comp;
+}
+/**
+ * Compute HTTP Message Signature header values (RFC 9421) over the described
+ * message.
+ *
+ * @throws {TypeError} for unsupported algorithms, weak HMAC keys, or
+ *   unserializable parameter values.
+ * @throws {Error} when a covered component cannot be resolved (e.g. a covered
+ *   header is missing) or WebCrypto is unavailable.
+ * @since 0.37.0
+ */
+export async function signMessage(opts) {
+    const label = opts.label ?? DEFAULT_SIGNATURE_LABEL;
+    const url = opts.url instanceof URL ? opts.url : new URL(opts.url);
+    const components = (opts.components ?? ["@method", "@target-uri"]).map(parseComponentSpec);
+    const nowSeconds = Math.floor((opts.now ?? Date.now)() / 1000);
+    const params = {
+        created: opts.created ?? nowSeconds,
+        ...(opts.expires !== undefined ? { expires: opts.expires } : {}),
+        ...(opts.keyid !== undefined ? { keyid: opts.keyid } : {}),
+        ...(opts.includeAlg === false ? {} : { alg: opts.alg }),
+        ...(opts.nonce !== undefined ? { nonce: opts.nonce } : {}),
+        ...(opts.tag !== undefined ? { tag: opts.tag } : {}),
+    };
+    const signatureParamsValue = serializeSignatureInput(components, params);
+    const msg = {
+        method: opts.method,
+        url,
+        headers: toHeaders(opts.headers),
+        ...(opts.status !== undefined ? { status: opts.status } : {}),
+    };
+    const base = buildSignatureBase(components, signatureParamsValue, msg);
+    const key = await importKey(opts.alg, opts.key, "sign");
+    const spec = algSpec(opts.alg);
+    const sig = new Uint8Array(await getCrypto().subtle.sign(spec.signParams, key, ENC.encode(base)));
+    return {
+        signatureInput: `${label}=${signatureParamsValue}`,
+        signature: `${label}=:${bytesToBase64(sig)}:`,
+        signatureBase: base,
+        label,
+    };
+}
+/**
+ * Sign an outbound {@link Request} and return a new `Request` with the
+ * `Signature` and `Signature-Input` headers attached. The original request is
+ * not mutated.
+ *
+ * @since 0.37.0
+ */
+export async function signRequest(request, opts) {
+    const sig = await signMessage({
+        ...opts,
+        method: request.method,
+        url: request.url,
+        headers: request.headers,
+    });
+    const headers = new Headers(request.headers);
+    headers.set("signature-input", sig.signatureInput);
+    headers.set("signature", sig.signature);
+    return new Request(request, { headers });
+}
+function fail(reason) {
+    return { valid: false, reason };
+}
+/**
+ * Verify an HTTP Message Signature (RFC 9421) on a received message. Returns a
+ * structured result and never throws on a bad/forged signature — only on a
+ * programming error (e.g. WebCrypto unavailable).
+ *
+ * @since 0.37.0
+ */
+export async function verifyMessage(opts) {
+    if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+        throw new TypeError("verifyMessage(): an explicit, non-empty `algorithms` allowlist is required.");
+    }
+    const headers = toHeaders(opts.headers);
+    const sigInputRaw = headers.get("signature-input");
+    const sigRaw = headers.get("signature");
+    if (!sigInputRaw)
+        return fail("missing_signature_input");
+    if (!sigRaw)
+        return fail("missing_signature");
+    if (sigInputRaw.length > MAX_HEADER_LENGTH || sigRaw.length > MAX_HEADER_LENGTH) {
+        return fail("header_too_large");
+    }
+    let inputs;
+    let signatures;
+    try {
+        inputs = parseSignatureInput(sigInputRaw);
+        signatures = parseSignature(sigRaw);
+    }
+    catch {
+        return fail("malformed_signature_headers");
+    }
+    let label = opts.label;
+    if (label === undefined) {
+        if (inputs.size !== 1)
+            return fail("ambiguous_label");
+        label = inputs.keys().next().value;
+    }
+    const input = inputs.get(label);
+    const provided = signatures.get(label);
+    if (!input || !provided)
+        return fail("label_not_found");
+    const params = input.params;
+    const declaredAlg = params.alg;
+    const info = {
+        label,
+        ...(params.keyid !== undefined ? { keyid: params.keyid } : {}),
+        ...(declaredAlg !== undefined ? { alg: declaredAlg } : {}),
+        ...(params.tag !== undefined ? { tag: params.tag } : {}),
+    };
+    // Required components.
+    const requiredComponents = opts.requiredComponents ?? ["@method", "@path"];
+    const coveredIds = input.components.map(serializeComponentId);
+    for (const req of requiredComponents) {
+        const wanted = serializeComponentId(parseComponentSpec(req));
+        if (!coveredIds.includes(wanted))
+            return fail("missing_required_component");
+    }
+    // Tag check.
+    if (opts.requiredTag !== undefined && params.tag !== opts.requiredTag) {
+        return fail("tag_mismatch");
+    }
+    // Time checks.
+    const nowSeconds = Math.floor((opts.now ?? Date.now)() / 1000);
+    const tolerance = opts.toleranceSeconds ?? DEFAULT_SIGNATURE_CLOCK_SKEW_SECONDS;
+    const requireCreated = opts.requireCreated !== false;
+    if (params.created === undefined) {
+        if (requireCreated)
+            return fail("missing_created");
+    }
+    else {
+        if (params.created - tolerance > nowSeconds)
+            return fail("created_in_future");
+        const maxAge = opts.maxAgeSeconds ?? DEFAULT_MAX_SIGNATURE_AGE_SECONDS;
+        if (Number.isFinite(maxAge) && nowSeconds - params.created > maxAge) {
+            return fail("signature_stale");
+        }
+    }
+    if (params.expires !== undefined && nowSeconds - tolerance > params.expires) {
+        return fail("signature_expired");
+    }
+    // Replay check.
+    if (opts.isReplay) {
+        if (params.nonce === undefined)
+            return fail("missing_nonce");
+        if (await opts.isReplay(params.nonce, info))
+            return fail("replay_detected");
+    }
+    // Resolve the key + effective algorithm (defeating algorithm-confusion).
+    const resolved = await opts.resolveKey(info);
+    if (resolved === undefined)
+        return fail("key_not_found");
+    let keyMaterial;
+    let pinnedAlg;
+    if (resolved instanceof Uint8Array ||
+        isCryptoKey(resolved) ||
+        isJsonWebKey(resolved)) {
+        keyMaterial = resolved;
+    }
+    else {
+        keyMaterial = resolved.key;
+        pinnedAlg = resolved.alg;
+    }
+    const effectiveAlg = pinnedAlg ?? declaredAlg;
+    if (effectiveAlg === undefined)
+        return fail("unspecified_alg");
+    if (pinnedAlg !== undefined && declaredAlg !== undefined && pinnedAlg !== declaredAlg) {
+        return fail("alg_mismatch");
+    }
+    if (!opts.algorithms.includes(effectiveAlg))
+        return fail("alg_not_allowed");
+    // Rebuild the signature base (verbatim @signature-params value).
+    const url = opts.url instanceof URL ? opts.url : new URL(opts.url);
+    const msg = {
+        method: opts.method,
+        url,
+        headers,
+        ...(opts.status !== undefined ? { status: opts.status } : {}),
+    };
+    let base;
+    try {
+        base = buildSignatureBase(input.components, input.raw, msg);
+    }
+    catch {
+        return fail("component_resolution_failed");
+    }
+    let key;
+    try {
+        key = await importKey(effectiveAlg, keyMaterial, "verify");
+    }
+    catch {
+        return fail("invalid_key");
+    }
+    const spec = algSpec(effectiveAlg);
+    let ok;
+    try {
+        ok = await getCrypto().subtle.verify(spec.signParams, key, provided, ENC.encode(base));
+    }
+    catch {
+        return fail("verify_threw");
+    }
+    if (!ok)
+        return fail("invalid_signature");
+    return {
+        valid: true,
+        label,
+        alg: effectiveAlg,
+        components: coveredIds,
+        ...(params.keyid !== undefined ? { keyid: params.keyid } : {}),
+        ...(params.created !== undefined ? { created: params.created } : {}),
+        ...(params.expires !== undefined ? { expires: params.expires } : {}),
+        ...(params.nonce !== undefined ? { nonce: params.nonce } : {}),
+        ...(params.tag !== undefined ? { tag: params.tag } : {}),
+    };
+}
+/**
+ * Verify an HTTP Message Signature on an inbound {@link Request}. Thin wrapper
+ * over {@link verifyMessage} that pulls the method, URL, and headers from the
+ * request.
+ *
+ * @since 0.37.0
+ */
+export function verifyRequest(request, opts) {
+    return verifyMessage({
+        ...opts,
+        method: request.method,
+        url: request.url,
+        headers: request.headers,
+    });
+}
+/**
+ * Middleware that enforces a valid RFC 9421 HTTP Message Signature on inbound
+ * requests. On success the {@link VerifySuccess} is stamped on `ctx.state`; on
+ * a missing (unless `optional`) or invalid signature it throws
+ * {@link UnauthorizedError} (`401` + `Cache-Control: no-store`).
+ *
+ * @since 0.37.0
+ */
+export function httpSignatureAuth(opts) {
+    const stateKey = opts.stateKey ?? "httpSignature";
+    const message = opts.message ?? "Valid HTTP message signature required";
+    return {
+        async beforeHandle(ctx) {
+            const headers = ctx.request.headers;
+            if (opts.optional && !headers.has("signature"))
+                return undefined;
+            const result = await verifyRequest(ctx.request, opts);
+            if (!result.valid) {
+                throw new UnauthorizedError(`${message} (${result.reason})`);
+            }
+            ctx.state[stateKey] = result;
+            return undefined;
+        },
+    };
+}
+const CONTENT_DIGEST_HASH = {
+    "sha-256": "SHA-256",
+    "sha-512": "SHA-512",
+};
+function toBytes(body) {
+    return typeof body === "string" ? ENC.encode(body) : body;
+}
+/**
+ * Compute an RFC 9530 `Content-Digest` header value over `body`, e.g.
+ * `sha-256=:<base64>:`. Pair it with a `content-digest` covered component to
+ * bind the request body into the signature, then re-check it against the
+ * received body with {@link verifyContentDigest}.
+ *
+ * @since 0.37.0
+ */
+export async function contentDigest(body, opts = {}) {
+    const algorithm = opts.algorithm ?? "sha-256";
+    const hash = CONTENT_DIGEST_HASH[algorithm];
+    if (!hash) {
+        throw new TypeError(`contentDigest(): unsupported algorithm ${algorithm}`);
+    }
+    const digest = new Uint8Array(await getCrypto().subtle.digest(hash, toBytes(body)));
+    return `${algorithm}=:${bytesToBase64(digest)}:`;
+}
+/**
+ * Verify that an RFC 9530 `Content-Digest` header value matches `body`.
+ * Returns `false` for any malformed header or mismatch (never throws on bad
+ * input). Only `sha-256` / `sha-512` members are considered.
+ *
+ * @since 0.37.0
+ */
+export async function verifyContentDigest(header, body) {
+    if (typeof header !== "string" || header.length > MAX_HEADER_LENGTH) {
+        return false;
+    }
+    const bodyBytes = toBytes(body);
+    let matchedAny = false;
+    for (const member of header.split(",")) {
+        const m = /^\s*(sha-256|sha-512)=:([A-Za-z0-9+/]*={0,2}):\s*$/.exec(member);
+        if (!m)
+            continue;
+        const algorithm = m[1];
+        const expected = base64ToBytes(m[2]);
+        if (!expected)
+            return false;
+        const digest = new Uint8Array(await getCrypto().subtle.digest(CONTENT_DIGEST_HASH[algorithm], bodyBytes));
+        if (digest.length !== expected.length)
+            return false;
+        let diff = 0;
+        for (let i = 0; i < digest.length; i++)
+            diff |= digest[i] ^ expected[i];
+        if (diff !== 0)
+            return false;
+        matchedAny = true;
+    }
+    return matchedAny;
+}