@sdxc/digest-fields 0.0.0-stage → 2026.10.9

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @sdxc/digest-fields
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+RFC 9530 `Content-Digest`, `Repr-Digest` and their `Want-*` preferences, plus the RFC 3230 `Digest` header that draft-cavage HTTP signatures cover.
+
+## Installation
+
+```sh
+npm add @sdxc/digest-fields
+```
+
+Every function answers a `Result` from [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), which installs with this package. Digests run on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest).
+
+## Usage
+
+```typescript
+import { digest, stringify, verify } from "@sdxc/digest-fields";
+import { isFailure, unwrap } from "@sdxc/result";
+
+let body = new TextEncoder().encode(JSON.stringify(activity));
+let bytes = unwrap(await digest(body, "sha-256"));
+
+let headers = new Headers({
+	"content-digest": unwrap(stringify({ "sha-256": bytes }, "content-digest")), // "sha-256=:…:"
+	digest: unwrap(stringify({ "sha-256": bytes }, "digest")), // "SHA-256=…"
+});
+
+let checked = await verify(request.headers, await request.bytes(), { field: "content-digest" });
+if (isFailure(checked)) return new Response(checked.error.message, { status: 400 });
+```
+
+Reading a field into its value model:
+
+```typescript
+import { parse } from "@sdxc/digest-fields";
+
+parse("sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:", "content-digest");
+// success({ "sha-256": Uint8Array(32) })
+
+parse("sha-512=3, sha-256=10", "want-content-digest");
+// success({ "sha-512": 3, "sha-256": 10 })
+```
+
+## API
+
+### `digest(bytes: BinaryLike, algorithm: DigestAlgorithm): Promise<Result<Uint8Array, DigestError>>`
+
+Hashes a body with `sha-256` or `sha-512`. Text is read as UTF-8, so pass the exact bytes sent when the body is not UTF-8 text.
+
+```typescript
+let bytes = await digest(body, "sha-256");
+// same as
+let bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", body));
+```
+
+### `parse(value: string, field: DigestField): Result<FieldValues[field], DigestError>`
+
+Reads a field into digest bytes (`content-digest`, `repr-digest`, `digest`) or preference weights from 0 to 10 (`want-content-digest`, `want-repr-digest`), keyed by lowercase algorithm name. The RFC 9530 fields go through the Structured Field grammar of [`@sdxc/structured-fields`](https://www.npmjs.com/package/@sdxc/structured-fields). `Digest` accepts algorithm names in any case, and drops an entry for another algorithm whose value is not base64, such as `UNIXsum=30637`.
+
+### `stringify(value: FieldValues[field], field: DigestField): Result<string, DigestError>`
+
+Writes a field. `Digest` uppercases algorithm names (`SHA-256=…`), which is how every draft-cavage verifier reads them. An empty value answers `""`, meaning "do not send the field".
+
+### `verify(headers: Headers, body: BinaryLike, options: { field: DigestValueField }): Promise<Result<void, DigestError>>`
+
+Checks a body against `content-digest`, `repr-digest` or `digest`. Every `sha-256` and `sha-512` entry must match, so a forged entry next to a valid one still fails, and entries for other algorithms are skipped.
+
+### `DIGEST_ALGORITHMS`
+
+`["sha-256", "sha-512"]`, the algorithms `digest` and `verify` compute.
+
+### `DigestError`
+
+The failure every function answers with. `code` says which check failed:
+
+| `code`                  | When                                                           |
+| ----------------------- | -------------------------------------------------------------- |
+| `missing`               | `verify` found no such field                                   |
+| `malformed`             | The field text does not fit its grammar                        |
+| `invalid`               | `stringify` got a name the field cannot carry or a bad weight  |
+| `unsupported-algorithm` | No `sha-256`/`sha-512` entry to check, or `digest` got another |
+| `mismatch`              | The body differs from a digest                                 |
+| `crypto`                | The runtime refused the hash                                   |
+
+### Types
+
+#### `DigestAlgorithm`
+
+`"sha-256" | "sha-512"`.
+
+#### `DigestField`
+
+`"content-digest" | "repr-digest" | "want-content-digest" | "want-repr-digest" | "digest"`. `DigestValueField` is the three that carry digests.
+
+#### `Digests` and `Preferences`
+
+`Record<string, Uint8Array>` and `Record<string, number>`, keyed by lowercase algorithm name. `FieldValues` maps each field to the one it carries.
+
+## Pattern: Answering `Want-Content-Digest`
+
+Send the algorithm the client weighs highest, falling back to `sha-256`.
+
+```typescript
+import { DIGEST_ALGORITHMS, digest, parse, stringify } from "@sdxc/digest-fields";
+import { isSuccess, unwrap } from "@sdxc/result";
+
+function preferred(request: Request) {
+	let wanted = parse(request.headers.get("want-content-digest") ?? "", "want-content-digest");
+	if (!isSuccess(wanted)) return "sha-256";
+	let weights = wanted.data;
+	let ranked = DIGEST_ALGORITHMS.filter((name) => (weights[name] ?? 0) > 0);
+	ranked.sort((a, b) => (weights[b] ?? 0) - (weights[a] ?? 0));
+	return ranked[0] ?? "sha-256";
+}
+
+let body = new TextEncoder().encode(JSON.stringify(data));
+let algorithm = preferred(request);
+let bytes = unwrap(await digest(body, algorithm));
+
+return new Response(body, {
+	headers: { "content-digest": unwrap(stringify({ [algorithm]: bytes }, "content-digest")) },
+});
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/digest-fields": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/digest.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Computes the digest of a body with one of the algorithms the digest fields name, the
+ * value a sender writes into `Content-Digest` or `Digest` and a receiver recomputes.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { BinaryLike, Bytes } from "@sdxc/crypto";
+import type { Result } from "@sdxc/result";
+import type { DigestAlgorithm } from "./types.js";
+import { DigestError } from "./errors.js";
+/** The algorithms this package computes, for narrowing a name read from a field. */
+export declare const DIGEST_ALGORITHMS: readonly DigestAlgorithm[];
+/**
+ * Whether a lowercase algorithm name is one `digest` computes.
+ *
+ * @param name - An algorithm name as a field spells it, already lowercased.
+ */
+export declare function isDigestAlgorithm(name: string): name is DigestAlgorithm;
+/**
+ * Digests a body. Text is read as UTF-8, so pass the exact bytes sent on the wire when a
+ * body is not UTF-8 text.
+ *
+ * @param bytes - The content (for `Content-Digest`) or representation (for `Repr-Digest`).
+ * @param algorithm - `sha-256` or `sha-512`.
+ * @returns The digest bytes, `unsupported-algorithm` for any other name, or `crypto` when
+ *   the runtime refuses the hash.
+ * @example
+ * let bytes = await digest(body, "sha-256"); // success(32 bytes)
+ */
+export declare function digest(bytes: BinaryLike, algorithm: DigestAlgorithm): Promise<Result<Bytes, DigestError>>;

package/dist/digest.js

@@ -0,0 +1,41 @@
+/**
+ * Computes the digest of a body with one of the algorithms the digest fields name, the
+ * value a sender writes into `Content-Digest` or `Digest` and a receiver recomputes.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { sha256, sha512 } from "@sdxc/crypto";
+import { failure, isFailure, success } from "@sdxc/result";
+import { DigestError } from "./errors.js";
+/** The algorithms this package computes, for narrowing a name read from a field. */
+export const DIGEST_ALGORITHMS = ["sha-256", "sha-512"];
+/**
+ * Whether a lowercase algorithm name is one `digest` computes.
+ *
+ * @param name - An algorithm name as a field spells it, already lowercased.
+ */
+export function isDigestAlgorithm(name) {
+    return DIGEST_ALGORITHMS.includes(name);
+}
+/**
+ * Digests a body. Text is read as UTF-8, so pass the exact bytes sent on the wire when a
+ * body is not UTF-8 text.
+ *
+ * @param bytes - The content (for `Content-Digest`) or representation (for `Repr-Digest`).
+ * @param algorithm - `sha-256` or `sha-512`.
+ * @returns The digest bytes, `unsupported-algorithm` for any other name, or `crypto` when
+ *   the runtime refuses the hash.
+ * @example
+ * let bytes = await digest(body, "sha-256"); // success(32 bytes)
+ */
+export async function digest(bytes, algorithm) {
+    if (!isDigestAlgorithm(algorithm)) {
+        return failure(new DigestError("unsupported-algorithm", "Unsupported digest algorithm"));
+    }
+    let hashed = algorithm === "sha-256" ? await sha256(bytes) : await sha512(bytes);
+    if (isFailure(hashed)) {
+        return failure(new DigestError("crypto", hashed.error.message, { cause: hashed.error }));
+    }
+    return success(hashed.data);
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one failure every function in this package answers with, carrying a code a caller
+ * branches on, so a missing field, a malformed one and a body that does not match stay
+ * distinguishable without parsing messages.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Why a digest field could not be read, written or verified. `mismatch` is the only code
+ * that says the content changed; every other code is about the field itself.
+ */
+export type DigestErrorCode = "missing" | "malformed" | "invalid" | "unsupported-algorithm" | "mismatch" | "crypto";
+/** Returned inside a `Failure` by every function in this package, never thrown. */
+export declare class DigestError extends Error {
+    name: string;
+    /** Machine-readable cause, for a caller that maps it to its own error or status. */
+    readonly code: DigestErrorCode;
+    /**
+     * @param code - Why the field failed.
+     * @param message - The explanation a log shows.
+     * @param options - The underlying error, when one was raised.
+     */
+    constructor(code: DigestErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,23 @@
+/**
+ * The one failure every function in this package answers with, carrying a code a caller
+ * branches on, so a missing field, a malformed one and a body that does not match stay
+ * distinguishable without parsing messages.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Returned inside a `Failure` by every function in this package, never thrown. */
+export class DigestError extends Error {
+    name = "DigestError";
+    /** Machine-readable cause, for a caller that maps it to its own error or status. */
+    code;
+    /**
+     * @param code - Why the field failed.
+     * @param message - The explanation a log shows.
+     * @param options - The underlying error, when one was raised.
+     */
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads, writes and verifies the HTTP digest fields: RFC 9530's `Content-Digest`,
+ * `Repr-Digest` and their `Want-*` preferences, and RFC 3230's legacy `Digest` that
+ * draft-cavage HTTP signatures still cover.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { DigestErrorCode } from "./errors.js";
+export type { DigestAlgorithm, DigestField, DigestValueField, Digests, FieldValues, Preferences, } from "./types.js";
+export type { VerifyOptions } from "./verify.js";
+export { DIGEST_ALGORITHMS, digest } from "./digest.js";
+export { DigestError } from "./errors.js";
+export { parse } from "./parse.js";
+export { stringify } from "./stringify.js";
+export { verify } from "./verify.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Reads, writes and verifies the HTTP digest fields: RFC 9530's `Content-Digest`,
+ * `Repr-Digest` and their `Want-*` preferences, and RFC 3230's legacy `Digest` that
+ * draft-cavage HTTP signatures still cover.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { DIGEST_ALGORITHMS, digest } from "./digest.js";
+export { DigestError } from "./errors.js";
+export { parse } from "./parse.js";
+export { stringify } from "./stringify.js";
+export { verify } from "./verify.js";

package/dist/parse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reads a digest field into its value model: RFC 9530 fields through the Structured Field
+ * grammar, and RFC 3230's `Digest` through its own comma-separated `ALG=base64` grammar,
+ * so a caller holds one shape whichever field a sender used.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { DigestField, FieldValues } from "./types.js";
+import { DigestError } from "./errors.js";
+/**
+ * Parses a field value into its model.
+ *
+ * `Content-Digest` and `Repr-Digest` answer digest bytes keyed by algorithm, and the
+ * `Want-*` fields answer preference weights. `Digest` reads algorithm names in any case
+ * and keys them lowercase; an entry for an algorithm outside `sha-256`/`sha-512` whose
+ * value is not base64 (RFC 3230's `UNIXsum`, say) is left out.
+ *
+ * @param value - The field value, several field lines joined with `, ` as `Headers#get` does.
+ * @param field - Which field the value came from, lowercase.
+ * @returns The model, or `malformed` naming why the value does not fit the field.
+ * @example parse("sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:", "content-digest")
+ * @example parse("SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=", "digest")
+ */
+export declare function parse<Field extends DigestField>(value: string, field: Field): Result<FieldValues[Field], DigestError>;
+/**
+ * Whether a bare item is a valid preference weight.
+ *
+ * @param value - The member's bare item.
+ */
+export declare function isPreference(value: unknown): value is number;

package/dist/parse.js

@@ -0,0 +1,123 @@
+/**
+ * Reads a digest field into its value model: RFC 9530 fields through the Structured Field
+ * grammar, and RFC 3230's `Digest` through its own comma-separated `ALG=base64` grammar,
+ * so a caller holds one shape whichever field a sender used.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { Base64 } from "@sdxc/crypto";
+import { failure, isFailure, success } from "@sdxc/result";
+import { parse as parseStructured } from "@sdxc/structured-fields";
+import { isDigestAlgorithm } from "./digest.js";
+import { DigestError } from "./errors.js";
+/** The highest weight a `Want-*-Digest` preference may carry (RFC 9530 §4). */
+const MAX_PREFERENCE = 10;
+export function parse(value, field) {
+    if (field === "digest")
+        return parseLegacy(value);
+    if (field === "content-digest" || field === "repr-digest")
+        return parseDigests(value, field);
+    return parsePreferences(value, field);
+}
+/**
+ * Reads an RFC 9530 Dictionary whose members are Byte Sequences.
+ *
+ * @param value - The field value.
+ * @param field - The field name, for the message.
+ */
+function parseDigests(value, field) {
+    let parsed = parseDictionary(value, field);
+    if (isFailure(parsed))
+        return parsed;
+    let entries = [];
+    for (let [algorithm, member] of Object.entries(parsed.data)) {
+        if (!("value" in member) || !(member.value instanceof Uint8Array)) {
+            return failure(malformed(field, `${algorithm} is not a byte sequence`));
+        }
+        entries.push([algorithm, member.value]);
+    }
+    return success(Object.fromEntries(entries));
+}
+/**
+ * Reads an RFC 9530 `Want-*` Dictionary whose members are Integers from 0 to 10.
+ *
+ * @param value - The field value.
+ * @param field - The field name, for the message.
+ */
+function parsePreferences(value, field) {
+    let parsed = parseDictionary(value, field);
+    if (isFailure(parsed))
+        return parsed;
+    let entries = [];
+    for (let [algorithm, member] of Object.entries(parsed.data)) {
+        if (!("value" in member) || !isPreference(member.value)) {
+            return failure(malformed(field, `${algorithm} is not an integer from 0 to 10`));
+        }
+        entries.push([algorithm, member.value]);
+    }
+    return success(Object.fromEntries(entries));
+}
+/**
+ * Parses the Structured Field Dictionary every RFC 9530 field is defined as.
+ *
+ * @param value - The field value.
+ * @param field - The field name, for the message.
+ */
+function parseDictionary(value, field) {
+    let parsed = parseStructured(value, "dictionary");
+    if (isFailure(parsed)) {
+        return failure(new DigestError("malformed", `Malformed ${field}: ${parsed.error.message}`, {
+            cause: parsed.error,
+        }));
+    }
+    return parsed;
+}
+/**
+ * Reads RFC 3230's `Digest`: `ALG=base64` entries separated by commas. Empty entries,
+ * which a trailing comma leaves, are skipped; a repeated algorithm fails, so a second
+ * entry can never stand in for a mismatching first.
+ *
+ * @param value - The field value.
+ */
+function parseLegacy(value) {
+    let entries = [];
+    for (let entry of value.split(",")) {
+        let trimmed = entry.trim();
+        if (trimmed === "")
+            continue;
+        let separator = trimmed.indexOf("=");
+        if (separator <= 0)
+            return failure(malformed("digest", "an entry has no algorithm"));
+        let algorithm = trimmed.slice(0, separator).trim().toLowerCase();
+        if (entries.some(([seen]) => seen === algorithm)) {
+            return failure(malformed("digest", `${algorithm} is repeated`));
+        }
+        let decoded = Base64.decode(trimmed.slice(separator + 1).trim());
+        if (isFailure(decoded)) {
+            if (isDigestAlgorithm(algorithm)) {
+                return failure(malformed("digest", `${algorithm} is not base64`));
+            }
+            continue;
+        }
+        entries.push([algorithm, decoded.data]);
+    }
+    return success(Object.fromEntries(entries));
+}
+/**
+ * Whether a bare item is a valid preference weight.
+ *
+ * @param value - The member's bare item.
+ */
+export function isPreference(value) {
+    return (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= MAX_PREFERENCE);
+}
+/**
+ * A `malformed` failure naming the field and the reason.
+ *
+ * @param field - The field name.
+ * @param reason - What is wrong with it.
+ */
+function malformed(field, reason) {
+    return new DigestError("malformed", `Malformed ${field}: ${reason}`);
+}

package/dist/stringify.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Writes a digest field from its value model: RFC 9530 fields as canonical Structured
+ * Field Dictionaries, and RFC 3230's `Digest` with the uppercase algorithm names and
+ * padded base64 that every draft-cavage verifier reads.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { DigestField, FieldValues } from "./types.js";
+import { DigestError } from "./errors.js";
+/**
+ * Serializes a field value. An empty value answers `""`, which a caller reads as "do not
+ * send the field".
+ *
+ * @param value - Digest bytes, or preference weights for a `Want-*` field, keyed by algorithm.
+ * @param field - Which field to write, lowercase.
+ * @returns The field text, or `invalid` for an algorithm name the field cannot carry or a
+ *   weight outside 0 to 10.
+ * @example stringify({ "sha-256": bytes }, "content-digest") // success("sha-256=:…:")
+ * @example stringify({ "sha-256": bytes }, "digest") // success("SHA-256=…")
+ */
+export declare function stringify<Field extends DigestField>(value: FieldValues[Field], field: Field): Result<string, DigestError>;

package/dist/stringify.js

@@ -0,0 +1,56 @@
+/**
+ * Writes a digest field from its value model: RFC 9530 fields as canonical Structured
+ * Field Dictionaries, and RFC 3230's `Digest` with the uppercase algorithm names and
+ * padded base64 that every draft-cavage verifier reads.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { Base64 } from "@sdxc/crypto";
+import { failure, isFailure, success } from "@sdxc/result";
+import { stringify as stringifyStructured } from "@sdxc/structured-fields";
+import { DigestError } from "./errors.js";
+import { isPreference } from "./parse.js";
+/** An RFC 3230 algorithm name: a token, which keeps `=` and `,` out of it. */
+const LEGACY_ALGORITHM_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+export function stringify(value, field) {
+    if (field === "digest")
+        return stringifyLegacy(value);
+    if (field === "content-digest" || field === "repr-digest") {
+        return stringifyDictionary(value, field);
+    }
+    for (let [algorithm, weight] of Object.entries(value)) {
+        if (!isPreference(weight)) {
+            return failure(new DigestError("invalid", `${algorithm} must weigh an integer from 0 to 10`));
+        }
+    }
+    return stringifyDictionary(value, field);
+}
+/**
+ * Writes an RFC 9530 Dictionary, whose keys must be lowercase Structured Field keys.
+ *
+ * @param value - The members, byte sequences or integers.
+ * @param field - The field name, for the message.
+ */
+function stringifyDictionary(value, field) {
+    let text = stringifyStructured(value, "dictionary");
+    if (isFailure(text)) {
+        return failure(new DigestError("invalid", `Invalid ${field}: ${text.error.message}`, { cause: text.error }));
+    }
+    return success(text.data);
+}
+/**
+ * Writes RFC 3230's `Digest`, with algorithm names uppercased as its registry spells them.
+ *
+ * @param value - Digest bytes keyed by algorithm.
+ */
+function stringifyLegacy(value) {
+    let entries = [];
+    for (let [algorithm, bytes] of Object.entries(value)) {
+        if (!LEGACY_ALGORITHM_PATTERN.test(algorithm)) {
+            return failure(new DigestError("invalid", "Invalid digest: an algorithm is not a token"));
+        }
+        entries.push(`${algorithm.toUpperCase()}=${Base64.encode(bytes)}`);
+    }
+    return success(entries.join(", "));
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The value model of the digest fields: which fields exist, which algorithms this package
+ * computes, and what each field parses to, so `parse` and `stringify` agree on one shape
+ * per field.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The algorithms `digest` and `verify` compute, spelled as RFC 9530 registers them. */
+export type DigestAlgorithm = "sha-256" | "sha-512";
+/**
+ * The fields this package reads and writes: the four of RFC 9530, and RFC 3230's legacy
+ * `Digest`, which draft-cavage HTTP signatures cover.
+ */
+export type DigestField = "content-digest" | "repr-digest" | "want-content-digest" | "want-repr-digest" | "digest";
+/** The fields that carry digests of a body, as opposed to preferences for one. */
+export type DigestValueField = "content-digest" | "repr-digest" | "digest";
+/**
+ * Digest bytes keyed by lowercase algorithm name. Algorithms this package does not compute
+ * are kept, so a field round-trips; `verify` checks only `sha-256` and `sha-512`.
+ */
+export type Digests = Record<string, Uint8Array>;
+/**
+ * Preference weights keyed by lowercase algorithm name, from `0` (not acceptable) to `10`
+ * (most preferred), as `Want-Content-Digest` and `Want-Repr-Digest` carry them.
+ */
+export type Preferences = Record<string, number>;
+/** What each field parses to and what `stringify` accepts for it. */
+export interface FieldValues {
+    "content-digest": Digests;
+    "repr-digest": Digests;
+    digest: Digests;
+    "want-content-digest": Preferences;
+    "want-repr-digest": Preferences;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * The value model of the digest fields: which fields exist, which algorithms this package
+ * computes, and what each field parses to, so `parse` and `stringify` agree on one shape
+ * per field.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/dist/verify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Checks a body against the digest field a sender attached, the step that ties a signed
+ * header to the bytes it describes: an HTTP signature covers the field, and this proves
+ * the field matches the content.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { BinaryLike } from "@sdxc/crypto";
+import type { Result } from "@sdxc/result";
+import type { DigestValueField } from "./types.js";
+import { DigestError } from "./errors.js";
+/** What `verify` needs besides the headers and the body. */
+export interface VerifyOptions {
+    /** The field to check, lowercase: `content-digest`, `repr-digest` or legacy `digest`. */
+    field: DigestValueField;
+}
+/**
+ * Verifies a body against a digest field. Every `sha-256` and `sha-512` entry the field
+ * carries must match, so one forged entry next to a valid one still fails; entries for
+ * other algorithms are skipped.
+ *
+ * @param headers - The message headers holding the field.
+ * @param body - The exact bytes received; text is read as UTF-8.
+ * @param options - Which field to check.
+ * @returns Success when every supported entry matches, else `missing`, `malformed`,
+ *   `unsupported-algorithm` (no `sha-256` or `sha-512` entry), `mismatch` or `crypto`.
+ * @example await verify(request.headers, body, { field: "content-digest" })
+ */
+export declare function verify(headers: Headers, body: BinaryLike, options: VerifyOptions): Promise<Result<void, DigestError>>;

package/dist/verify.js

@@ -0,0 +1,49 @@
+/**
+ * Checks a body against the digest field a sender attached, the step that ties a signed
+ * header to the bytes it describes: an HTTP signature covers the field, and this proves
+ * the field matches the content.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { timingSafeEqual } from "@sdxc/crypto";
+import { failure, isFailure, success } from "@sdxc/result";
+import { digest, isDigestAlgorithm } from "./digest.js";
+import { DigestError } from "./errors.js";
+import { parse } from "./parse.js";
+/**
+ * Verifies a body against a digest field. Every `sha-256` and `sha-512` entry the field
+ * carries must match, so one forged entry next to a valid one still fails; entries for
+ * other algorithms are skipped.
+ *
+ * @param headers - The message headers holding the field.
+ * @param body - The exact bytes received; text is read as UTF-8.
+ * @param options - Which field to check.
+ * @returns Success when every supported entry matches, else `missing`, `malformed`,
+ *   `unsupported-algorithm` (no `sha-256` or `sha-512` entry), `mismatch` or `crypto`.
+ * @example await verify(request.headers, body, { field: "content-digest" })
+ */
+export async function verify(headers, body, options) {
+    let text = headers.get(options.field);
+    if (text === null)
+        return failure(new DigestError("missing", `Missing ${options.field}`));
+    let parsed = parse(text, options.field);
+    if (isFailure(parsed))
+        return parsed;
+    let checked = 0;
+    for (let [algorithm, expected] of Object.entries(parsed.data)) {
+        if (!isDigestAlgorithm(algorithm))
+            continue;
+        let actual = await digest(body, algorithm);
+        if (isFailure(actual))
+            return actual;
+        if (!timingSafeEqual(actual.data, expected)) {
+            return failure(new DigestError("mismatch", `The body does not match its ${options.field} ${algorithm}`));
+        }
+        checked++;
+    }
+    if (checked === 0) {
+        return failure(new DigestError("unsupported-algorithm", `${options.field} carries no sha-256 or sha-512`));
+    }
+    return success(undefined);
+}

package/package.json

@@ -1,6 +1,33 @@
 {
-  "name": "@sdxc/digest-fields",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sdxc/digest-fields",
+	"version": "2026.10.9",
+	"description": "RFC 9530 Content-Digest and Repr-Digest, plus the RFC 3230 Digest header",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/crypto": "2026.10.9",
+		"@sdxc/result": "2026.10.6",
+		"@sdxc/structured-fields": "2026.10.6"
+	},
+	"gitHead": "64fa732ed0a8ca8693a35aeef6345ae5be2534ef",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/digest-fields"
+	},
+	"homepage": "https://sdxc.sergiodxa.com/api/digest-fields",
+	"author": {
+		"name": "Sergio Xalambrí",
+		"url": "https://sergiodxa.com"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/sergiodxa"
+	}
+}