@automate.ax/codec 0.84.0 → 0.86.1

package/dist/http.d.ts

@@ -1,17 +1,32 @@
 import * as z from "zod/mini";
 declare const JSON_VALUE_SCHEMA: z.ZodMiniJSONSchema;
 export type JsonValue = z.infer<typeof JSON_VALUE_SCHEMA>;
-export type HttpRequestBody = JsonValue | Uint8Array;
+export type HttpRequestFormValue = File | string;
+export type HttpRequestForm = Record<string, HttpRequestFormValue | HttpRequestFormValue[]>;
+export type HttpRequestBody = HttpRequestForm | JsonValue | Uint8Array;
 export type HttpRequestBodyType = "bytes" | "empty" | "form" | "json" | "text";
 export type DecodedHttpRequestBody = {
     body: HttpRequestBody;
     bodyType: HttpRequestBodyType;
 };
+/** An HTTP request body that can't be decoded as its declared media type. */
+export declare class HttpRequestBodyDecodeError extends Error {
+    readonly status: 400 | 413 | 415;
+    /**
+     * Creates a request error with its public HTTP status.
+     *
+     * @param message - Safe response message.
+     * @param status - HTTP status returned by ingress.
+     * @param options - Optional underlying error details.
+     */
+    constructor(message: string, status: 400 | 413 | 415, options?: ErrorOptions);
+}
 /**
  * Decodes HTTP request bytes according to the declared media type.
  *
  * @param rawBody - Exact request body bytes.
  * @param contentType - Declared Content-Type header, when present.
+ * @throws {HttpRequestBodyDecodeError} When a declared body can't be decoded.
  */
 export declare function decodeHttpRequestBody(rawBody: Uint8Array, contentType?: string): DecodedHttpRequestBody;
 export {};

package/dist/http.js

@@ -1,16 +1,56 @@
+import { MaxFileSizeExceededError, MaxHeaderSizeExceededError, MaxPartsExceededError, MaxTotalSizeExceededError, MultipartParseError, parseMultipart, } from "@remix-run/multipart-parser";
+import { parse as parseContentType } from "content-type";
+import { TextDecoder } from "node:util";
 import * as z from "zod/mini";
 const JSON_VALUE_SCHEMA = z.json();
+const TEXT_APPLICATION_MEDIA_TYPES = new Set([
+    "application/javascript",
+    "application/json-seq",
+    "application/ndjson",
+    "application/sql",
+    "application/toml",
+    "application/x-ndjson",
+    "application/x-yaml",
+    "application/yaml",
+]);
+const XML_DECLARATION_ENCODING = /^<\?xml\s+[^>]*?\bencoding\s*=\s*(["'])([a-z][a-z\d._-]*)\1/i;
+/** An HTTP request body that can't be decoded as its declared media type. */
+export class HttpRequestBodyDecodeError extends Error {
+    status;
+    /**
+     * Creates a request error with its public HTTP status.
+     *
+     * @param message - Safe response message.
+     * @param status - HTTP status returned by ingress.
+     * @param options - Optional underlying error details.
+     */
+    constructor(message, status, options) {
+        super(message, options);
+        this.status = status;
+        this.name = "HttpRequestBodyDecodeError";
+    }
+}
 /**
  * Decodes HTTP request bytes according to the declared media type.
  *
  * @param rawBody - Exact request body bytes.
  * @param contentType - Declared Content-Type header, when present.
+ * @throws {HttpRequestBodyDecodeError} When a declared body can't be decoded.
  */
 export function decodeHttpRequestBody(rawBody, contentType) {
     if (rawBody.byteLength === 0) {
         return { body: null, bodyType: "empty" };
     }
-    const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    const parsedContentType = contentType
+        ? parseContentType(contentType)
+        : undefined;
+    const mediaType = parsedContentType?.type.toLowerCase() ?? "";
+    if (mediaType === "multipart/form-data") {
+        return {
+            body: decodeMultipartForm(rawBody, parsedContentType?.parameters.boundary),
+            bodyType: "form",
+        };
+    }
     if (mediaType === "application/x-www-form-urlencoded") {
         const values = new Map();
         for (const [key, value] of new URLSearchParams(decodeText(rawBody))) {
@@ -29,24 +69,183 @@ export function decodeHttpRequestBody(rawBody, contentType) {
         };
     }
     if (mediaType === "application/json" || mediaType.endsWith("+json")) {
+        try {
+            return {
+                body: JSON_VALUE_SCHEMA.parse(JSON.parse(decodeText(rawBody))),
+                bodyType: "json",
+            };
+        }
+        catch (cause) {
+            throw new HttpRequestBodyDecodeError("Request body is not valid JSON.", 400, { cause });
+        }
+    }
+    if (isXmlMediaType(mediaType)) {
         return {
-            body: JSON_VALUE_SCHEMA.parse(JSON.parse(decodeText(rawBody))),
-            bodyType: "json",
+            body: decodeText(rawBody, getXmlCharset(rawBody, parsedContentType?.parameters.charset)),
+            bodyType: "text",
         };
     }
     if (mediaType.startsWith("text/") ||
-        mediaType === "application/javascript" ||
-        mediaType === "application/xml" ||
-        mediaType.endsWith("+xml")) {
-        return { body: decodeText(rawBody), bodyType: "text" };
+        TEXT_APPLICATION_MEDIA_TYPES.has(mediaType) ||
+        mediaType.endsWith("+yaml")) {
+        return {
+            body: decodeText(rawBody, parsedContentType?.parameters.charset),
+            bodyType: "text",
+        };
     }
     return { body: rawBody, bodyType: "bytes" };
 }
 /**
- * Decodes request bytes as UTF-8, replacing invalid byte sequences.
+ * Decodes a multipart form into fields and files grouped by field name.
  *
- * @param rawBody - Exact request body bytes.
+ * @param rawBody - Exact multipart request bytes.
+ * @param boundary - Boundary declared by the multipart Content-Type.
+ * @throws {HttpRequestBodyDecodeError} When the form is malformed or exceeds
+ *   parser limits.
+ */
+function decodeMultipartForm(rawBody, boundary) {
+    if (!boundary) {
+        throw new HttpRequestBodyDecodeError("Multipart form Content-Type is missing its boundary.", 400);
+    }
+    try {
+        const values = new Map();
+        for (const part of parseMultipart(rawBody, {
+            boundary,
+            // Ingress already buffers the complete request. Preserve its existing
+            // size behavior instead of imposing the parser's lower file defaults.
+            maxFileSize: rawBody.byteLength,
+            maxTotalSize: rawBody.byteLength,
+        })) {
+            if (!part.name) {
+                throw new HttpRequestBodyDecodeError("Multipart form part is missing its field name.", 400);
+            }
+            const partContentType = part.headers["content-type"]
+                ? parseContentType(part.headers["content-type"])
+                : undefined;
+            const value = part.isFile
+                ? new File([part.arrayBuffer], part.filename ?? "", {
+                    lastModified: 0,
+                    type: part.mediaType ?? "application/octet-stream",
+                })
+                : decodeText(part.bytes, partContentType?.parameters.charset);
+            const existing = values.get(part.name);
+            if (existing)
+                existing.push(value);
+            else
+                values.set(part.name, [value]);
+        }
+        return Object.fromEntries([...values].map(([key, entries]) => [
+            key,
+            entries.length === 1 ? entries[0] : entries,
+        ]));
+    }
+    catch (cause) {
+        if (cause instanceof HttpRequestBodyDecodeError)
+            throw cause;
+        if (cause instanceof MaxFileSizeExceededError ||
+            cause instanceof MaxHeaderSizeExceededError ||
+            cause instanceof MaxPartsExceededError ||
+            cause instanceof MaxTotalSizeExceededError) {
+            throw new HttpRequestBodyDecodeError("Multipart form exceeds the supported size or part count.", 413, { cause });
+        }
+        if (cause instanceof MultipartParseError || cause instanceof TypeError) {
+            throw new HttpRequestBodyDecodeError("Request body is not valid multipart form data.", 400, { cause });
+        }
+        throw cause;
+    }
+}
+/**
+ * Decodes bytes with the declared character encoding, defaulting to UTF-8.
+ *
+ * @param rawBody - Text body bytes.
+ * @param charset - WHATWG character encoding label.
+ * @throws {HttpRequestBodyDecodeError} When the encoding is unsupported or the
+ *   bytes are invalid for it.
+ */
+function decodeText(rawBody, charset = "utf-8") {
+    try {
+        return new TextDecoder(charset, { fatal: true }).decode(rawBody);
+    }
+    catch (cause) {
+        if (cause instanceof RangeError) {
+            throw new HttpRequestBodyDecodeError(`Request body uses unsupported character encoding ${charset}.`, 415, { cause });
+        }
+        throw new HttpRequestBodyDecodeError(`Request body is not valid ${charset} text.`, 400, { cause });
+    }
+}
+/**
+ * Selects XML encoding using BOM, MIME charset, then the XML declaration.
+ *
+ * @param rawBody - XML body bytes.
+ * @param declaredCharset - MIME charset parameter, when present.
+ */
+function getXmlCharset(rawBody, declaredCharset) {
+    const bomCharset = detectXmlBom(rawBody);
+    if (bomCharset)
+        return bomCharset;
+    if (declaredCharset)
+        return declaredCharset;
+    const inferredCharset = detectXmlBytePattern(rawBody) ?? "utf-8";
+    try {
+        return (XML_DECLARATION_ENCODING.exec(new TextDecoder(inferredCharset).decode(rawBody.subarray(0, 1024)))?.[2] ?? inferredCharset);
+    }
+    catch {
+        return inferredCharset;
+    }
+}
+/**
+ * Detects a Unicode byte order mark.
+ *
+ * @param rawBody - XML body bytes.
+ */
+function detectXmlBom(rawBody) {
+    if (startsWithBytes(rawBody, [0x00, 0x00, 0xfe, 0xff]))
+        return "utf-32be";
+    if (startsWithBytes(rawBody, [0xff, 0xfe, 0x00, 0x00]))
+        return "utf-32le";
+    if (startsWithBytes(rawBody, [0xef, 0xbb, 0xbf]))
+        return "utf-8";
+    if (startsWithBytes(rawBody, [0xfe, 0xff]))
+        return "utf-16be";
+    if (startsWithBytes(rawBody, [0xff, 0xfe]))
+        return "utf-16le";
+}
+/**
+ * Infers XML encodings whose opening declaration has a distinctive byte form.
+ *
+ * @param rawBody - XML body bytes.
+ */
+function detectXmlBytePattern(rawBody) {
+    if (startsWithBytes(rawBody, [0x00, 0x00, 0x00, 0x3c]))
+        return "utf-32be";
+    if (startsWithBytes(rawBody, [0x3c, 0x00, 0x00, 0x00]))
+        return "utf-32le";
+    if (startsWithBytes(rawBody, [0x00, 0x3c, 0x00, 0x3f]))
+        return "utf-16be";
+    if (startsWithBytes(rawBody, [0x3c, 0x00, 0x3f, 0x00]))
+        return "utf-16le";
+    if (startsWithBytes(rawBody, [0x4c, 0x6f, 0xa7, 0x94]))
+        return "ibm037";
+}
+/**
+ * Checks an exact byte prefix.
+ *
+ * @param rawBody - Complete body bytes.
+ * @param prefix - Bytes expected at the start.
+ */
+function startsWithBytes(rawBody, prefix) {
+    return prefix.every((byte, index) => rawBody[index] === byte);
+}
+/**
+ * Recognizes XML media types that require XML encoding precedence.
+ *
+ * @param mediaType - Normalized media type.
  */
-function decodeText(rawBody) {
-    return new TextDecoder().decode(rawBody);
+function isXmlMediaType(mediaType) {
+    return (mediaType === "application/xml" ||
+        mediaType === "application/xml-dtd" ||
+        mediaType === "application/xml-external-parsed-entity" ||
+        mediaType === "text/xml" ||
+        mediaType === "text/xml-external-parsed-entity" ||
+        mediaType.endsWith("+xml"));
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+export { isSensitivityMask, projectSensitivityMask, redactSensitiveValue, type SensitivityMask, type StructuralSensitivityMask, } from "./sensitivity.js";
 export type { ObjectProducingSchema, ProducingSchema } from "./schema.js";
 /**
  * Values accepted by the codec encoder, including recursively nested containers

package/dist/index.js

@@ -2,6 +2,7 @@ import * as z from "zod";
 import { isPlainObject } from "./lib/utils.js";
 import { packr } from "./packr.js";
 import { bufferAsyncValues } from "./walk.js";
+export { isSensitivityMask, projectSensitivityMask, redactSensitiveValue, } from "./sensitivity.js";
 /**
  * Asserts that a value belongs to the codec's supported input surface.
  *

package/dist/sensitivity.d.ts

@@ -0,0 +1,39 @@
+import type { Encodable } from "./index.js";
+/** Runtime representation of a whole-value or structural sensitivity policy. */
+export type SensitivityMask = true | readonly SensitivityMask[] | {
+    readonly [key: string]: SensitivityMask | undefined;
+};
+/** Codec object types whose internal properties are not maskable structure. */
+type AtomicEncodableObject = ArrayBuffer | ArrayBufferView | Blob | Date | File | Headers | Map<unknown, unknown> | RegExp | Request | Response | Set<unknown> | URL | URLSearchParams;
+/**
+ * Mirrors an output value with `true` at each subtree that must not be exposed.
+ *
+ * A one-element array mask applies to every array element. Non-structural codec
+ * values can only be marked wholly sensitive.
+ */
+export type StructuralSensitivityMask<T> = true | (T extends unknown ? NonNullable<T> extends AtomicEncodableObject ? never : NonNullable<T> extends readonly (infer TItem)[] ? readonly [StructuralSensitivityMask<TItem>] : NonNullable<T> extends object ? {
+    readonly [TKey in keyof NonNullable<T>]?: StructuralSensitivityMask<NonNullable<T>[TKey]>;
+} : never : never);
+/**
+ * Returns whether a value is a valid runtime sensitivity mask.
+ *
+ * @param value - Candidate mask.
+ */
+export declare function isSensitivityMask(value: unknown): value is SensitivityMask;
+/**
+ * Replaces structurally sensitive subtrees with `undefined` for persistence in
+ * author-visible execution data.
+ *
+ * @param value - Validated codec value being projected.
+ * @param mask - Structural policy declared by the value's producer.
+ * @throws {TypeError} When the mask does not match the value structure.
+ */
+export declare function redactSensitiveValue<T extends Encodable>(value: T, mask: SensitivityMask): T | undefined;
+/**
+ * Projects a structural mask through one property access.
+ *
+ * @param mask - Parent sensitivity mask.
+ * @param property - Accessed property name or array index.
+ */
+export declare function projectSensitivityMask(mask: SensitivityMask | undefined, property: string): SensitivityMask | undefined;
+export {};

package/dist/sensitivity.js

@@ -0,0 +1,65 @@
+import { isPlainObject } from "./lib/utils.js";
+/**
+ * Returns whether a value is a valid runtime sensitivity mask.
+ *
+ * @param value - Candidate mask.
+ */
+export function isSensitivityMask(value) {
+    if (value === true)
+        return true;
+    if (Array.isArray(value)) {
+        return value.length === 1 && isSensitivityMask(value[0]);
+    }
+    return (typeof value === "object" &&
+        value !== null &&
+        isPlainObject(value) &&
+        Object.keys(value).length > 0 &&
+        Object.values(value).every(isSensitivityMask));
+}
+export function redactSensitiveValue(value, mask) {
+    if (mask === true)
+        return undefined;
+    if (isSensitivityArray(mask)) {
+        if (!Array.isArray(value)) {
+            throw new TypeError("Array sensitivity masks require array values.");
+        }
+        return value.map((item) => redactSensitiveValue(item, mask[0]));
+    }
+    if (typeof value !== "object" || value === null || !isPlainObject(value)) {
+        throw new TypeError("Object sensitivity masks require plain-object values.");
+    }
+    if (Object.keys(mask).some((key) => !Object.hasOwn(value, key))) {
+        throw new TypeError("Object sensitivity masks may only name properties present in the value.");
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        mask[key] ? redactSensitiveValue(item, mask[key]) : item,
+    ]));
+}
+/**
+ * Projects a structural mask through one property access.
+ *
+ * @param mask - Parent sensitivity mask.
+ * @param property - Accessed property name or array index.
+ */
+export function projectSensitivityMask(mask, property) {
+    if (mask === true)
+        return true;
+    if (!mask)
+        return;
+    if (isSensitivityArray(mask)) {
+        const index = Number(property);
+        if (!Number.isInteger(index) || index < 0)
+            return;
+        return mask[0];
+    }
+    return mask[property];
+}
+/**
+ * Narrows the readonly array branch that `Array.isArray` cannot express.
+ *
+ * @param mask - Runtime sensitivity mask.
+ */
+function isSensitivityArray(mask) {
+    return Array.isArray(mask);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/codec",
-  "version": "0.84.0",
+  "version": "0.86.1",
   "description": "Msgpack-based encoding helpers for Automate.ax runtime data.",
   "license": "MIT",
   "repository": {
@@ -63,7 +63,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "devDependencies": {
-    "@internal/config": "0.1.0",
+    "@internal/config": "0.2.0",
     "@types/bun": "latest",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@zachsents/oxlint-config": "^0.4.1",
@@ -74,7 +74,9 @@
     "zshy": "^0.7.2"
   },
   "dependencies": {
+    "@remix-run/multipart-parser": "^0.16.4",
     "@standard-schema/spec": "^1.1.0",
+    "content-type": "^3.0.0",
     "msgpackr": "^1.11.9",
     "zod": "^4.3.6"
   }

package/src/http.ts

@@ -1,10 +1,39 @@
+import {
+  MaxFileSizeExceededError,
+  MaxHeaderSizeExceededError,
+  MaxPartsExceededError,
+  MaxTotalSizeExceededError,
+  MultipartParseError,
+  parseMultipart,
+} from "@remix-run/multipart-parser"
+import { parse as parseContentType } from "content-type"
+import { TextDecoder } from "node:util"
 import * as z from "zod/mini"
 
 const JSON_VALUE_SCHEMA = z.json()
+const TEXT_APPLICATION_MEDIA_TYPES = new Set([
+  "application/javascript",
+  "application/json-seq",
+  "application/ndjson",
+  "application/sql",
+  "application/toml",
+  "application/x-ndjson",
+  "application/x-yaml",
+  "application/yaml",
+])
+const XML_DECLARATION_ENCODING =
+  /^<\?xml\s+[^>]*?\bencoding\s*=\s*(["'])([a-z][a-z\d._-]*)\1/i
 
 export type JsonValue = z.infer<typeof JSON_VALUE_SCHEMA>
 
-export type HttpRequestBody = JsonValue | Uint8Array
+export type HttpRequestFormValue = File | string
+
+export type HttpRequestForm = Record<
+  string,
+  HttpRequestFormValue | HttpRequestFormValue[]
+>
+
+export type HttpRequestBody = HttpRequestForm | JsonValue | Uint8Array
 
 export type HttpRequestBodyType = "bytes" | "empty" | "form" | "json" | "text"
 
@@ -13,11 +42,31 @@ export type DecodedHttpRequestBody = {
   bodyType: HttpRequestBodyType
 }
 
+/** An HTTP request body that can't be decoded as its declared media type. */
+export class HttpRequestBodyDecodeError extends Error {
+  /**
+   * Creates a request error with its public HTTP status.
+   *
+   * @param message - Safe response message.
+   * @param status - HTTP status returned by ingress.
+   * @param options - Optional underlying error details.
+   */
+  constructor(
+    message: string,
+    public readonly status: 400 | 413 | 415,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+    this.name = "HttpRequestBodyDecodeError"
+  }
+}
+
 /**
  * Decodes HTTP request bytes according to the declared media type.
  *
  * @param rawBody - Exact request body bytes.
  * @param contentType - Declared Content-Type header, when present.
+ * @throws {HttpRequestBodyDecodeError} When a declared body can't be decoded.
  */
 export function decodeHttpRequestBody(
   rawBody: Uint8Array,
@@ -27,7 +76,20 @@ export function decodeHttpRequestBody(
     return { body: null, bodyType: "empty" }
   }
 
-  const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? ""
+  const parsedContentType = contentType
+    ? parseContentType(contentType)
+    : undefined
+  const mediaType = parsedContentType?.type.toLowerCase() ?? ""
+  if (mediaType === "multipart/form-data") {
+    return {
+      body: decodeMultipartForm(
+        rawBody,
+        parsedContentType?.parameters.boundary,
+      ),
+      bodyType: "form",
+    }
+  }
+
   if (mediaType === "application/x-www-form-urlencoded") {
     const values = new Map<string, string[]>()
     for (const [key, value] of new URLSearchParams(decodeText(rawBody))) {
@@ -47,29 +109,219 @@ export function decodeHttpRequestBody(
   }
 
   if (mediaType === "application/json" || mediaType.endsWith("+json")) {
+    try {
+      return {
+        body: JSON_VALUE_SCHEMA.parse(JSON.parse(decodeText(rawBody))),
+        bodyType: "json",
+      }
+    } catch (cause) {
+      throw new HttpRequestBodyDecodeError(
+        "Request body is not valid JSON.",
+        400,
+        { cause },
+      )
+    }
+  }
+
+  if (isXmlMediaType(mediaType)) {
     return {
-      body: JSON_VALUE_SCHEMA.parse(JSON.parse(decodeText(rawBody))),
-      bodyType: "json",
+      body: decodeText(
+        rawBody,
+        getXmlCharset(rawBody, parsedContentType?.parameters.charset),
+      ),
+      bodyType: "text",
     }
   }
 
   if (
     mediaType.startsWith("text/") ||
-    mediaType === "application/javascript" ||
-    mediaType === "application/xml" ||
-    mediaType.endsWith("+xml")
+    TEXT_APPLICATION_MEDIA_TYPES.has(mediaType) ||
+    mediaType.endsWith("+yaml")
   ) {
-    return { body: decodeText(rawBody), bodyType: "text" }
+    return {
+      body: decodeText(rawBody, parsedContentType?.parameters.charset),
+      bodyType: "text",
+    }
   }
 
   return { body: rawBody, bodyType: "bytes" }
 }
 
 /**
- * Decodes request bytes as UTF-8, replacing invalid byte sequences.
+ * Decodes a multipart form into fields and files grouped by field name.
  *
- * @param rawBody - Exact request body bytes.
+ * @param rawBody - Exact multipart request bytes.
+ * @param boundary - Boundary declared by the multipart Content-Type.
+ * @throws {HttpRequestBodyDecodeError} When the form is malformed or exceeds
+ *   parser limits.
+ */
+function decodeMultipartForm(rawBody: Uint8Array, boundary?: string) {
+  if (!boundary) {
+    throw new HttpRequestBodyDecodeError(
+      "Multipart form Content-Type is missing its boundary.",
+      400,
+    )
+  }
+
+  try {
+    const values = new Map<string, HttpRequestFormValue[]>()
+    for (const part of parseMultipart(rawBody, {
+      boundary,
+      // Ingress already buffers the complete request. Preserve its existing
+      // size behavior instead of imposing the parser's lower file defaults.
+      maxFileSize: rawBody.byteLength,
+      maxTotalSize: rawBody.byteLength,
+    })) {
+      if (!part.name) {
+        throw new HttpRequestBodyDecodeError(
+          "Multipart form part is missing its field name.",
+          400,
+        )
+      }
+
+      const partContentType = part.headers["content-type"]
+        ? parseContentType(part.headers["content-type"])
+        : undefined
+      const value = part.isFile
+        ? new File([part.arrayBuffer], part.filename ?? "", {
+            lastModified: 0,
+            type: part.mediaType ?? "application/octet-stream",
+          })
+        : decodeText(part.bytes, partContentType?.parameters.charset)
+      const existing = values.get(part.name)
+      if (existing) existing.push(value)
+      else values.set(part.name, [value])
+    }
+
+    return Object.fromEntries(
+      [...values].map(([key, entries]) => [
+        key,
+        entries.length === 1 ? entries[0]! : entries,
+      ]),
+    )
+  } catch (cause) {
+    if (cause instanceof HttpRequestBodyDecodeError) throw cause
+    if (
+      cause instanceof MaxFileSizeExceededError ||
+      cause instanceof MaxHeaderSizeExceededError ||
+      cause instanceof MaxPartsExceededError ||
+      cause instanceof MaxTotalSizeExceededError
+    ) {
+      throw new HttpRequestBodyDecodeError(
+        "Multipart form exceeds the supported size or part count.",
+        413,
+        { cause },
+      )
+    }
+    if (cause instanceof MultipartParseError || cause instanceof TypeError) {
+      throw new HttpRequestBodyDecodeError(
+        "Request body is not valid multipart form data.",
+        400,
+        { cause },
+      )
+    }
+    throw cause
+  }
+}
+
+/**
+ * Decodes bytes with the declared character encoding, defaulting to UTF-8.
+ *
+ * @param rawBody - Text body bytes.
+ * @param charset - WHATWG character encoding label.
+ * @throws {HttpRequestBodyDecodeError} When the encoding is unsupported or the
+ *   bytes are invalid for it.
+ */
+function decodeText(rawBody: Uint8Array, charset = "utf-8") {
+  try {
+    return new TextDecoder(charset, { fatal: true }).decode(rawBody)
+  } catch (cause) {
+    if (cause instanceof RangeError) {
+      throw new HttpRequestBodyDecodeError(
+        `Request body uses unsupported character encoding ${charset}.`,
+        415,
+        { cause },
+      )
+    }
+    throw new HttpRequestBodyDecodeError(
+      `Request body is not valid ${charset} text.`,
+      400,
+      { cause },
+    )
+  }
+}
+
+/**
+ * Selects XML encoding using BOM, MIME charset, then the XML declaration.
+ *
+ * @param rawBody - XML body bytes.
+ * @param declaredCharset - MIME charset parameter, when present.
  */
-function decodeText(rawBody: Uint8Array) {
-  return new TextDecoder().decode(rawBody)
+function getXmlCharset(rawBody: Uint8Array, declaredCharset?: string) {
+  const bomCharset = detectXmlBom(rawBody)
+  if (bomCharset) return bomCharset
+  if (declaredCharset) return declaredCharset
+
+  const inferredCharset = detectXmlBytePattern(rawBody) ?? "utf-8"
+  try {
+    return (
+      XML_DECLARATION_ENCODING.exec(
+        new TextDecoder(inferredCharset).decode(rawBody.subarray(0, 1024)),
+      )?.[2] ?? inferredCharset
+    )
+  } catch {
+    return inferredCharset
+  }
+}
+
+/**
+ * Detects a Unicode byte order mark.
+ *
+ * @param rawBody - XML body bytes.
+ */
+function detectXmlBom(rawBody: Uint8Array) {
+  if (startsWithBytes(rawBody, [0x00, 0x00, 0xfe, 0xff])) return "utf-32be"
+  if (startsWithBytes(rawBody, [0xff, 0xfe, 0x00, 0x00])) return "utf-32le"
+  if (startsWithBytes(rawBody, [0xef, 0xbb, 0xbf])) return "utf-8"
+  if (startsWithBytes(rawBody, [0xfe, 0xff])) return "utf-16be"
+  if (startsWithBytes(rawBody, [0xff, 0xfe])) return "utf-16le"
+}
+
+/**
+ * Infers XML encodings whose opening declaration has a distinctive byte form.
+ *
+ * @param rawBody - XML body bytes.
+ */
+function detectXmlBytePattern(rawBody: Uint8Array) {
+  if (startsWithBytes(rawBody, [0x00, 0x00, 0x00, 0x3c])) return "utf-32be"
+  if (startsWithBytes(rawBody, [0x3c, 0x00, 0x00, 0x00])) return "utf-32le"
+  if (startsWithBytes(rawBody, [0x00, 0x3c, 0x00, 0x3f])) return "utf-16be"
+  if (startsWithBytes(rawBody, [0x3c, 0x00, 0x3f, 0x00])) return "utf-16le"
+  if (startsWithBytes(rawBody, [0x4c, 0x6f, 0xa7, 0x94])) return "ibm037"
+}
+
+/**
+ * Checks an exact byte prefix.
+ *
+ * @param rawBody - Complete body bytes.
+ * @param prefix - Bytes expected at the start.
+ */
+function startsWithBytes(rawBody: Uint8Array, prefix: number[]) {
+  return prefix.every((byte, index) => rawBody[index] === byte)
+}
+
+/**
+ * Recognizes XML media types that require XML encoding precedence.
+ *
+ * @param mediaType - Normalized media type.
+ */
+function isXmlMediaType(mediaType: string) {
+  return (
+    mediaType === "application/xml" ||
+    mediaType === "application/xml-dtd" ||
+    mediaType === "application/xml-external-parsed-entity" ||
+    mediaType === "text/xml" ||
+    mediaType === "text/xml-external-parsed-entity" ||
+    mediaType.endsWith("+xml")
+  )
 }

package/src/index.ts

@@ -3,6 +3,14 @@ import { isPlainObject } from "./lib/utils"
 import { packr } from "./packr"
 import { bufferAsyncValues } from "./walk"
 
+export {
+  isSensitivityMask,
+  projectSensitivityMask,
+  redactSensitiveValue,
+  type SensitivityMask,
+  type StructuralSensitivityMask,
+} from "./sensitivity"
+
 export type { ObjectProducingSchema, ProducingSchema } from "./schema"
 
 /**

package/src/sensitivity.ts

@@ -0,0 +1,137 @@
+import { isPlainObject } from "./lib/utils"
+import type { Encodable } from "./index"
+
+/** Runtime representation of a whole-value or structural sensitivity policy. */
+export type SensitivityMask =
+  | true
+  | readonly SensitivityMask[]
+  | { readonly [key: string]: SensitivityMask | undefined }
+
+/** Codec object types whose internal properties are not maskable structure. */
+type AtomicEncodableObject =
+  | ArrayBuffer
+  | ArrayBufferView
+  | Blob
+  | Date
+  | File
+  | Headers
+  | Map<unknown, unknown>
+  | RegExp
+  | Request
+  | Response
+  | Set<unknown>
+  | URL
+  | URLSearchParams
+
+/**
+ * Mirrors an output value with `true` at each subtree that must not be exposed.
+ *
+ * A one-element array mask applies to every array element. Non-structural codec
+ * values can only be marked wholly sensitive.
+ */
+export type StructuralSensitivityMask<T> =
+  | true
+  | (T extends unknown
+      ? NonNullable<T> extends AtomicEncodableObject
+        ? never
+        : NonNullable<T> extends readonly (infer TItem)[]
+          ? readonly [StructuralSensitivityMask<TItem>]
+          : NonNullable<T> extends object
+            ? {
+                readonly [TKey in keyof NonNullable<T>]?: StructuralSensitivityMask<
+                  NonNullable<T>[TKey]
+                >
+              }
+            : never
+      : never)
+
+/**
+ * Returns whether a value is a valid runtime sensitivity mask.
+ *
+ * @param value - Candidate mask.
+ */
+export function isSensitivityMask(value: unknown): value is SensitivityMask {
+  if (value === true) return true
+  if (Array.isArray(value)) {
+    return value.length === 1 && isSensitivityMask(value[0])
+  }
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    isPlainObject(value) &&
+    Object.keys(value).length > 0 &&
+    Object.values(value).every(isSensitivityMask)
+  )
+}
+
+/**
+ * Replaces structurally sensitive subtrees with `undefined` for persistence in
+ * author-visible execution data.
+ *
+ * @param value - Validated codec value being projected.
+ * @param mask - Structural policy declared by the value's producer.
+ * @throws {TypeError} When the mask does not match the value structure.
+ */
+export function redactSensitiveValue<T extends Encodable>(
+  value: T,
+  mask: SensitivityMask,
+): T | undefined
+export function redactSensitiveValue(
+  value: Encodable,
+  mask: SensitivityMask,
+): Encodable {
+  if (mask === true) return undefined
+
+  if (isSensitivityArray(mask)) {
+    if (!Array.isArray(value)) {
+      throw new TypeError("Array sensitivity masks require array values.")
+    }
+    return value.map((item) => redactSensitiveValue(item, mask[0]!))
+  }
+
+  if (typeof value !== "object" || value === null || !isPlainObject(value)) {
+    throw new TypeError("Object sensitivity masks require plain-object values.")
+  }
+  if (Object.keys(mask).some((key) => !Object.hasOwn(value, key))) {
+    throw new TypeError(
+      "Object sensitivity masks may only name properties present in the value.",
+    )
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      mask[key] ? redactSensitiveValue(item, mask[key]) : item,
+    ]),
+  )
+}
+
+/**
+ * Projects a structural mask through one property access.
+ *
+ * @param mask - Parent sensitivity mask.
+ * @param property - Accessed property name or array index.
+ */
+export function projectSensitivityMask(
+  mask: SensitivityMask | undefined,
+  property: string,
+): SensitivityMask | undefined {
+  if (mask === true) return true
+  if (!mask) return
+  if (isSensitivityArray(mask)) {
+    const index = Number(property)
+    if (!Number.isInteger(index) || index < 0) return
+    return mask[0]!
+  }
+  return mask[property]
+}
+
+/**
+ * Narrows the readonly array branch that `Array.isArray` cannot express.
+ *
+ * @param mask - Runtime sensitivity mask.
+ */
+function isSensitivityArray(
+  mask: SensitivityMask,
+): mask is readonly SensitivityMask[] {
+  return Array.isArray(mask)
+}