@sdxc/digest-fields 2026.10.23 → 2026.10.25

package/README.md

@@ -2,7 +2,7 @@
 
 RFC 9530 `Content-Digest` and `Repr-Digest`, plus the RFC 3230 `Digest` header.
 
-Compute, write, read and verify the HTTP digest fields, including the `Want-Content-Digest` and `Want-Repr-Digest` preferences and the legacy `Digest` header that draft-cavage HTTP signatures cover.
+Compute, write, read and verify the HTTP digest fields, including the `Want-Content-Digest` and `Want-Repr-Digest` preferences, `Unencoded-Digest` and `Want-Unencoded-Digest` from [HTTP Unencoded Digest](https://datatracker.ietf.org/doc/draft-ietf-httpbis-unencoded-digest/), and the legacy `Digest` header that draft-cavage HTTP signatures cover.
 
 ## Installation
 
@@ -59,6 +59,12 @@ let checked = await verify(request.headers, await request.bytes(), { field: "con
 if (isFailure(checked)) return new Response(checked.error.message, { status: 400 });
 ```
 
+`Unencoded-Digest` covers the representation before content coding. Pass `decode: true` when the body is still coded as `Content-Encoding` says (`gzip`, `x-gzip`, `deflate`, `identity`), and leave it off for a body `fetch` already decoded:
+
+```typescript
+await verify(request.headers, await request.bytes(), { field: "unencoded-digest", decode: true });
+```
+
 ## API
 
 ### `digest(bytes: BinaryLike, algorithm: DigestAlgorithm): Promise<Result<Uint8Array, DigestError>>`
@@ -81,7 +87,7 @@ Writes a field. `Digest` uppercases algorithm names (`SHA-256=…`), the form dr
 
 ### `verify(headers: Headers, body: BinaryLike, options: VerifyOptions): Promise<Result<void, DigestError>>`
 
-Checks a body against `options.field`: `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; entries for other algorithms are skipped.
+Checks a body against `options.field`: `content-digest`, `repr-digest`, `unencoded-digest` or `digest`. `options.decode` removes the `Content-Encoding` codings before checking `unencoded-digest`; `decodeContent(body, contentEncoding)` does the same on its own. Every `sha-256` and `sha-512` entry must match, so a forged entry next to a valid one still fails; entries for other algorithms are skipped.
 
 ### `DIGEST_ALGORITHMS`
 
@@ -98,6 +104,7 @@ The failure every function answers with; `code` says which check failed:
 | `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                                 |
+| `coding`                | `decode` met an unknown content coding or a corrupt body       |
 | `crypto`                | The runtime refused the hash                                   |
 
 ### Types
@@ -108,7 +115,7 @@ The failure every function answers with; `code` says which check failed:
 
 #### `DigestField` and `DigestValueField`
 
-`"content-digest" | "repr-digest" | "want-content-digest" | "want-repr-digest" | "digest"`. `DigestValueField` is the three that carry digests.
+`"content-digest" | "repr-digest" | "unencoded-digest" | "want-content-digest" | "want-repr-digest" | "want-unencoded-digest" | "digest"`. `DigestValueField` is the four that carry digests.
 
 #### `Digests`, `Preferences` and `FieldValues`
 
@@ -120,7 +127,7 @@ The union of `DigestError` codes in the table above.
 
 #### `VerifyOptions`
 
-`{ field: DigestValueField }`.
+`{ field: DigestValueField; decode?: boolean }`.
 
 ## Pattern: Signing-Ready Outbound Request
 

package/dist/decode.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Removes the content codings a `Content-Encoding` field lists, recovering the unencoded
+ * representation an `Unencoded-Digest` covers, so a receiver holding still-coded bytes can
+ * verify that field without re-encoding anything.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { BinaryLike, Bytes } from "@sdxc/crypto";
+import type { Result } from "@sdxc/result";
+import { DigestError } from "./errors.js";
+/**
+ * Decodes a body through every coding a `Content-Encoding` value lists, last applied first,
+ * as the codings were stacked in the listed order. An empty value or `identity` leaves the
+ * bytes as they are.
+ *
+ * @param body - The content as received, still coded.
+ * @param contentEncoding - The `Content-Encoding` value, or `null` when the field is absent.
+ * @returns The unencoded bytes, or `coding` when a coding is not `gzip`, `x-gzip`, `deflate`
+ *   or `identity`, or when the body does not decode.
+ * @example await decodeContent(gzipped, "gzip") // success(the original bytes)
+ */
+export declare function decodeContent(body: BinaryLike, contentEncoding: string | null): Promise<Result<Bytes, DigestError>>;

package/dist/decode.js

@@ -0,0 +1,79 @@
+/**
+ * Removes the content codings a `Content-Encoding` field lists, recovering the unencoded
+ * representation an `Unencoded-Digest` covers, so a receiver holding still-coded bytes can
+ * verify that field without re-encoding anything.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { DigestError } from "./errors.js";
+/** Shared UTF-8 encoder, so a text body turns into the same bytes `digest` hashes. */
+const ENCODER = new TextEncoder();
+/** Each decodable content coding, keyed by its registered name, with its stream format. */
+const DECODERS = {
+    identity: null,
+    gzip: "gzip",
+    "x-gzip": "gzip",
+    deflate: "deflate",
+};
+/**
+ * Decodes a body through every coding a `Content-Encoding` value lists, last applied first,
+ * as the codings were stacked in the listed order. An empty value or `identity` leaves the
+ * bytes as they are.
+ *
+ * @param body - The content as received, still coded.
+ * @param contentEncoding - The `Content-Encoding` value, or `null` when the field is absent.
+ * @returns The unencoded bytes, or `coding` when a coding is not `gzip`, `x-gzip`, `deflate`
+ *   or `identity`, or when the body does not decode.
+ * @example await decodeContent(gzipped, "gzip") // success(the original bytes)
+ */
+export async function decodeContent(body, contentEncoding) {
+    let codings = (contentEncoding ?? "")
+        .split(",")
+        .map((coding) => coding.trim().toLowerCase())
+        .filter((coding) => coding !== "")
+        .reverse();
+    let bytes = toBytes(body);
+    for (let coding of codings) {
+        if (!Object.hasOwn(DECODERS, coding)) {
+            return failure(new DigestError("coding", `Cannot decode the ${coding} content coding`));
+        }
+        let format = DECODERS[coding];
+        if (!format)
+            continue;
+        let decoded = await decompress(bytes, format);
+        if (isFailure(decoded))
+            return decoded;
+        bytes = decoded.data;
+    }
+    return success(bytes);
+}
+/**
+ * Runs bytes through one platform decompression stream, turning a corrupt body into a
+ * `coding` failure.
+ *
+ * @param bytes - The coded bytes.
+ * @param format - The stream format of the coding.
+ */
+async function decompress(bytes, format) {
+    try {
+        let stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream(format));
+        return success(new Uint8Array(await new Response(stream).arrayBuffer()));
+    }
+    catch (error) {
+        return failure(new DigestError("coding", `The body does not decode as ${format}`, { cause: error }));
+    }
+}
+/**
+ * Normalizes a body into bytes, reading text as UTF-8.
+ *
+ * @param body - Text or binary content.
+ */
+function toBytes(body) {
+    if (typeof body === "string")
+        return ENCODER.encode(body);
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    return body.slice();
+}

package/dist/digest.d.ts

@@ -21,7 +21,8 @@ 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 bytes - The content (for `Content-Digest`), the representation (for `Repr-Digest`)
+ *   or the representation before content coding (for `Unencoded-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.

package/dist/digest.js

@@ -22,7 +22,8 @@ export function isDigestAlgorithm(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 bytes - The content (for `Content-Digest`), the representation (for `Repr-Digest`)
+ *   or the representation before content coding (for `Unencoded-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.

package/dist/errors.d.ts

@@ -10,7 +10,7 @@
  * 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";
+export type DigestErrorCode = "missing" | "malformed" | "invalid" | "unsupported-algorithm" | "mismatch" | "coding" | "crypto";
 /** Returned inside a `Failure` by every function in this package, never thrown. */
 export declare class DigestError extends Error {
     name: string;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * Reads, writes and verifies the HTTP digest fields: RFC 9530's `Content-Digest` and
+ * `Repr-Digest`, HTTP Unencoded Digest's `Unencoded-Digest`, 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
@@ -10,6 +10,7 @@ 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 { decodeContent } from "./decode.js";
 export { DigestError } from "./errors.js";
 export { parse } from "./parse.js";
 export { stringify } from "./stringify.js";

package/dist/index.js

@@ -1,12 +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.
+ * Reads, writes and verifies the HTTP digest fields: RFC 9530's `Content-Digest` and
+ * `Repr-Digest`, HTTP Unencoded Digest's `Unencoded-Digest`, 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 { decodeContent } from "./decode.js";
 export { DigestError } from "./errors.js";
 export { parse } from "./parse.js";
 export { stringify } from "./stringify.js";

package/dist/parse.d.ts

@@ -12,8 +12,8 @@ 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
+ * `Content-Digest`, `Repr-Digest` and `Unencoded-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.
  *
@@ -24,6 +24,12 @@ import { DigestError } from "./errors.js";
  * @example parse("SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=", "digest")
  */
 export declare function parse<Field extends DigestField>(value: string, field: Field): Result<FieldValues[Field], DigestError>;
+/**
+ * Whether a field is one of the Structured Field Dictionaries whose members are digests.
+ *
+ * @param field - The field name, lowercase.
+ */
+export declare function isDigestsField(field: DigestField): boolean;
 /**
  * Whether a bare item is a valid preference weight.
  *

package/dist/parse.js

@@ -16,7 +16,7 @@ const MAX_PREFERENCE = 10;
 export function parse(value, field) {
     if (field === "digest")
         return parseLegacy(value);
-    if (field === "content-digest" || field === "repr-digest")
+    if (isDigestsField(field))
         return parseDigests(value, field);
     return parsePreferences(value, field);
 }
@@ -104,6 +104,14 @@ function parseLegacy(value) {
     }
     return success(Object.fromEntries(entries));
 }
+/**
+ * Whether a field is one of the Structured Field Dictionaries whose members are digests.
+ *
+ * @param field - The field name, lowercase.
+ */
+export function isDigestsField(field) {
+    return field === "content-digest" || field === "repr-digest" || field === "unencoded-digest";
+}
 /**
  * Whether a bare item is a valid preference weight.
  *

package/dist/stringify.js

@@ -10,15 +10,14 @@ 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";
+import { isDigestsField, 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") {
+    if (isDigestsField(field))
         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`));

package/dist/types.d.ts

@@ -9,12 +9,12 @@
 /** 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.
+ * The fields this package reads and writes: the four of RFC 9530, the HTTP Unencoded Digest
+ * pair, 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";
+export type DigestField = "content-digest" | "repr-digest" | "unencoded-digest" | "want-content-digest" | "want-repr-digest" | "want-unencoded-digest" | "digest";
 /** The fields that carry digests of a body, as opposed to preferences for one. */
-export type DigestValueField = "content-digest" | "repr-digest" | "digest";
+export type DigestValueField = "content-digest" | "repr-digest" | "unencoded-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`.
@@ -22,14 +22,16 @@ export type DigestValueField = "content-digest" | "repr-digest" | "digest";
 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.
+ * (most preferred), as the `Want-*-Digest` fields 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;
+    "unencoded-digest": Digests;
     digest: Digests;
     "want-content-digest": Preferences;
     "want-repr-digest": Preferences;
+    "want-unencoded-digest": Preferences;
 }

package/dist/verify.d.ts

@@ -12,8 +12,15 @@ 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`. */
+    /** The field to check, lowercase: `content-digest`, `repr-digest`, `unencoded-digest` or `digest`. */
     field: DigestValueField;
+    /**
+     * Whether the body is still coded as `Content-Encoding` says, for `unencoded-digest`:
+     * `verify` then decodes it before hashing. Leave it off for a body already decoded,
+     * as `fetch` hands a response's.
+     * @default false
+     */
+    decode?: boolean;
 }
 /**
  * Verifies a body against a digest field. Every `sha-256` and `sha-512` entry the field
@@ -24,7 +31,8 @@ export interface VerifyOptions {
  * @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`.
+ *   `unsupported-algorithm` (no `sha-256` or `sha-512` entry), `mismatch`, `coding` (the
+ *   body does not decode) 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

@@ -8,6 +8,7 @@
  */
 import { timingSafeEqual } from "@sdxc/crypto";
 import { failure, isFailure, success } from "@sdxc/result";
+import { decodeContent } from "./decode.js";
 import { digest, isDigestAlgorithm } from "./digest.js";
 import { DigestError } from "./errors.js";
 import { parse } from "./parse.js";
@@ -20,7 +21,8 @@ import { parse } from "./parse.js";
  * @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`.
+ *   `unsupported-algorithm` (no `sha-256` or `sha-512` entry), `mismatch`, `coding` (the
+ *   body does not decode) or `crypto`.
  * @example await verify(request.headers, body, { field: "content-digest" })
  */
 export async function verify(headers, body, options) {
@@ -30,11 +32,14 @@ export async function verify(headers, body, options) {
     let parsed = parse(text, options.field);
     if (isFailure(parsed))
         return parsed;
+    let content = await hashedContent(headers, body, options);
+    if (isFailure(content))
+        return content;
     let checked = 0;
     for (let [algorithm, expected] of Object.entries(parsed.data)) {
         if (!isDigestAlgorithm(algorithm))
             continue;
-        let actual = await digest(body, algorithm);
+        let actual = await digest(content.data, algorithm);
         if (isFailure(actual))
             return actual;
         if (!timingSafeEqual(actual.data, expected)) {
@@ -47,3 +52,16 @@ export async function verify(headers, body, options) {
     }
     return success(undefined);
 }
+/**
+ * The bytes a field's digests cover: the body as received, or for `unencoded-digest` with
+ * `decode` set, the body with every listed content coding removed.
+ *
+ * @param headers - The message headers holding `Content-Encoding`.
+ * @param body - The body as received.
+ * @param options - Which field to check and whether to decode.
+ */
+async function hashedContent(headers, body, options) {
+    if (options.field !== "unencoded-digest" || !options.decode)
+        return success(body);
+    return decodeContent(body, headers.get("content-encoding"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/digest-fields",
-	"version": "2026.10.23",
+	"version": "2026.10.25",
 	"description": "RFC 9530 Content-Digest and Repr-Digest, plus the RFC 3230 Digest header",
 	"license": "MIT",
 	"type": "module",
@@ -10,9 +10,9 @@
 	"dependencies": {
 		"@sdxc/crypto": "2026.10.23",
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/structured-fields": "2026.10.16"
+		"@sdxc/structured-fields": "2026.10.25"
 	},
-	"gitHead": "8e428ddf15290d44500a9618ec4d04bd7629fa99",
+	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
 	"publishConfig": {
 		"access": "public"
 	},