@moqtap/codec 0.10.0 → 0.12.0

package/dist/types-DDwidj2d.d.ts

@@ -0,0 +1,371 @@
+interface UnknownParam {
+    readonly id: string;
+    readonly length: number;
+    readonly raw_hex: string;
+}
+interface AuthorizationToken {
+    readonly alias_type: bigint;
+    readonly token_alias?: bigint;
+    readonly token_type?: bigint;
+    readonly token_value?: Uint8Array;
+}
+interface Draft21SetupOptions {
+    path?: string;
+    authorization_token?: readonly AuthorizationToken[];
+    max_auth_token_cache_size?: bigint;
+    authority?: string;
+    max_filter_ranges?: bigint;
+    moqt_implementation?: string;
+    max_request_updates?: bigint;
+    unknown?: UnknownParam[];
+}
+/**
+ * LOCATION_FILTER (0x21) — draft-21 Section 3.3.1.
+ *
+ * The draft-19 `Filter Type` discriminator (0x1 Next Group Start / 0x2 Largest
+ * Object / 0x3 AbsoluteStart / 0x4 AbsoluteRange) is gone; the shape is the
+ * number of vi64 fields the value holds. The fields below carry the wire
+ * values verbatim, unresolved:
+ *
+ *  - 1 field  → `start_group` alone is RELATIVE: start is
+ *               {Largest Object.Group + 1 - start_group, 0}. Open-ended.
+ *  - 2 fields → absolute start {start_group, start_object}, except that
+ *               {0, 0} means the Next Object. Open-ended.
+ *  - 3 fields → end group is `start_group + end_group_delta`; `end_object`
+ *               omitted means every object in that group.
+ *  - 4 fields → the fully specified INCLUSIVE range
+ *               {start_group, start_object} … {start_group + end_group_delta,
+ *               end_object}.
+ *
+ * `removed: true` is the `Length == 0` form, which in REQUEST_UPDATE removes an
+ * existing filter.
+ *
+ * The range is inclusive at both ends. draft-19's "last Object, plus 1" and
+ * "Object == 0 means the whole group" conventions are gone, so nothing here is
+ * ever incremented or decremented on the way in or out.
+ */
+interface LocationFilter {
+    readonly start_group?: bigint;
+    readonly start_object?: bigint;
+    readonly end_group_delta?: bigint;
+    readonly end_object?: bigint;
+    readonly removed?: boolean;
+}
+interface RangeFilterRange {
+    readonly start: bigint;
+    readonly end?: bigint;
+}
+interface RangeFilter {
+    readonly set_id?: bigint;
+    readonly property_type?: bigint;
+    readonly ranges?: RangeFilterRange[];
+    readonly removed?: boolean;
+}
+interface LargestObject {
+    readonly group: bigint;
+    readonly object: bigint;
+}
+/**
+ * FILL_PARAMETERS (0x23) value — NEW in draft-20 (Section 9.20.16).
+ *
+ * A separate parameter scope carrying only the settings that differ from the
+ * subscription's. Table 6 closes the list to exactly these eight types;
+ * TRACK_PROPERTY_FILTER (0x29) is deliberately excluded.
+ *
+ * The mere presence of the parameter is what requests a fill fetch stream, so
+ * an empty value is meaningful — it asks for a fill with everything inherited.
+ */
+interface Draft21FillParameters {
+    fill_timeout?: bigint;
+    subscriber_priority?: bigint;
+    location_filter?: LocationFilter;
+    group_order?: bigint;
+    subgroup_filter?: readonly RangeFilter[];
+    objectid_filter?: readonly RangeFilter[];
+    priority_filter?: readonly RangeFilter[];
+    object_property_filter?: readonly RangeFilter[];
+}
+interface Draft21Params {
+    object_delivery_timeout?: bigint;
+    authorization_token?: readonly AuthorizationToken[];
+    rendezvous_timeout?: bigint;
+    subgroup_delivery_timeout?: bigint;
+    expires?: bigint;
+    largest_object?: LargestObject;
+    fill_timeout?: bigint;
+    forward?: bigint;
+    subscriber_priority?: bigint;
+    location_filter?: LocationFilter;
+    group_order?: bigint;
+    fill_parameters?: Draft21FillParameters;
+    subgroup_filter?: readonly RangeFilter[];
+    objectid_filter?: readonly RangeFilter[];
+    priority_filter?: readonly RangeFilter[];
+    object_property_filter?: readonly RangeFilter[];
+    track_property_filter?: readonly RangeFilter[];
+    new_group_request?: bigint;
+    track_namespace_prefix?: string[];
+    include_properties?: bigint;
+    unknown?: UnknownParam[];
+}
+interface Draft21TrackProperties {
+    object_delivery_timeout?: bigint;
+    max_cache_duration?: bigint;
+    subgroup_delivery_timeout?: bigint;
+    immutable_properties?: Uint8Array;
+    default_publisher_priority?: bigint;
+    default_publisher_group_order?: bigint;
+    dynamic_groups?: bigint;
+    unknown?: UnknownParam[];
+}
+type Draft21MessageType = 'setup' | 'subscribe' | 'subscribe_ok' | 'request_update' | 'publish_state_notify' | 'publish' | 'publish_done' | 'publish_namespace' | 'namespace' | 'namespace_done' | 'subscribe_namespace' | 'subscribe_tracks' | 'publish_skipped' | 'fetch' | 'fetch_ok' | 'track_status' | 'request_ok' | 'request_error' | 'goaway';
+interface Draft21BaseMessage {
+    readonly type: Draft21MessageType;
+}
+interface Draft21Setup extends Draft21BaseMessage {
+    readonly type: 'setup';
+    readonly options: Draft21SetupOptions;
+}
+interface Draft21Subscribe extends Draft21BaseMessage {
+    readonly type: 'subscribe';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft21Params;
+}
+interface Draft21SubscribeOk extends Draft21BaseMessage {
+    readonly type: 'subscribe_ok';
+    readonly track_alias: bigint;
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+interface Draft21RequestUpdate extends Draft21BaseMessage {
+    readonly type: 'request_update';
+    readonly request_id: bigint;
+    readonly parameters: Draft21Params;
+}
+/**
+ * PUBLISH_STATE_NOTIFY (0x22) — NEW in draft-20, Section 9.10.
+ *
+ * No Request ID: the message is identified by the subscription's bidirectional
+ * stream it arrives on, like SUBSCRIBE_OK, PUBLISH_DONE and FETCH_OK.
+ */
+interface Draft21PublishStateNotify extends Draft21BaseMessage {
+    readonly type: 'publish_state_notify';
+    readonly parameters: Draft21Params;
+}
+interface Draft21Publish extends Draft21BaseMessage {
+    readonly type: 'publish';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly track_alias: bigint;
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+interface Draft21PublishDone extends Draft21BaseMessage {
+    readonly type: 'publish_done';
+    readonly status_code: bigint;
+    /**
+     * Number of streams opened for the subscription, including empty subgroups
+     * and — new in draft-20 — fill fetch streams (Section 9.9), or the
+     * `UNKNOWN_STREAM_COUNT` sentinel exported from `codec.ts` (2^64 - 1, raised
+     * from draft-19's 2^62 - 1) when the publisher cannot state it exactly.
+     *
+     * `bigint`, not `number`: the sentinel does not fit a double.
+     */
+    readonly stream_count: bigint;
+    readonly reason_phrase: string;
+}
+interface Draft21PublishNamespace extends Draft21BaseMessage {
+    readonly type: 'publish_namespace';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly parameters: Draft21Params;
+}
+interface Draft21Namespace extends Draft21BaseMessage {
+    readonly type: 'namespace';
+    readonly namespace_suffix: string[];
+}
+interface Draft21NamespaceDone extends Draft21BaseMessage {
+    readonly type: 'namespace_done';
+    readonly namespace_suffix: string[];
+}
+interface Draft21SubscribeNamespace extends Draft21BaseMessage {
+    readonly type: 'subscribe_namespace';
+    readonly request_id: bigint;
+    readonly namespace_prefix: string[];
+    readonly parameters: Draft21Params;
+}
+interface Draft21SubscribeTracks extends Draft21BaseMessage {
+    readonly type: 'subscribe_tracks';
+    readonly request_id: bigint;
+    readonly namespace_prefix: string[];
+    readonly parameters: Draft21Params;
+}
+interface Draft21PublishSkipped extends Draft21BaseMessage {
+    readonly type: 'publish_skipped';
+    readonly namespace_suffix: string[];
+    readonly track_name: string;
+}
+/**
+ * FETCH (0x16) — the byte layout was rewritten in draft-20 (Section 9.11).
+ *
+ * Gone: the `Fetch Type` field and its enum, the `Standalone Fetch` and
+ * `Joining Fetch` structures, and the inline `Start Location` / `End Location`.
+ * Track Namespace and Track Name are inline fields of FETCH itself, and the
+ * range travels in the LOCATION_FILTER parameter. A FETCH with no
+ * LOCATION_FILTER covers {0,0} through Largest Object, inclusive.
+ *
+ * The codepoint did not change, so a draft-19 decoder fed one of these reads
+ * the Number of Track Namespace Fields count as a Fetch Type and mis-parses in
+ * silence. There is no in-band version signal that catches it.
+ */
+interface Draft21Fetch extends Draft21BaseMessage {
+    readonly type: 'fetch';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft21Params;
+}
+/**
+ * FETCH_OK (0x18) — bytes identical to draft-19, meaning changed.
+ *
+ * `end_group` / `end_object` are the INCLUSIVE end of the range the response
+ * covers: the last Object actually covered. draft-19's "the last Object, plus
+ * 1; or 0 to indicate the entire Group" is gone (draft-21 Section 9.12 with
+ * Section 3.3.1). The same bytes mean a different object under the two drafts,
+ * and nothing on the wire distinguishes them.
+ */
+interface Draft21FetchOk extends Draft21BaseMessage {
+    readonly type: 'fetch_ok';
+    readonly end_of_track: number;
+    readonly end_group: bigint;
+    readonly end_object: bigint;
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+interface Draft21TrackStatus extends Draft21BaseMessage {
+    readonly type: 'track_status';
+    readonly request_id: bigint;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+    readonly parameters: Draft21Params;
+}
+interface Draft21RequestOk extends Draft21BaseMessage {
+    readonly type: 'request_ok';
+    readonly parameters: Draft21Params;
+    readonly track_properties: Draft21TrackProperties;
+}
+/**
+ * Redirect structure, used inside REQUEST_ERROR when error_code = REDIRECT (0x34).
+ *
+ * draft-21 Section 9.4.1 names the namespace/name pair "the Redirect target"
+ * and dropped draft-19's rule that a zero-length pair meant "reuse the values
+ * from the original request". An empty namespace and name are now a literal
+ * empty namespace and name.
+ */
+interface Redirect {
+    readonly connect_uri: string;
+    readonly track_namespace: string[];
+    readonly track_name: string;
+}
+interface Draft21RequestError extends Draft21BaseMessage {
+    readonly type: 'request_error';
+    readonly error_code: bigint;
+    readonly retry_interval: bigint;
+    readonly reason_phrase: string;
+    readonly redirect?: Redirect;
+}
+interface Draft21GoAway extends Draft21BaseMessage {
+    readonly type: 'goaway';
+    readonly new_session_uri: string;
+    readonly timeout: bigint;
+}
+type Draft21Message = Draft21Setup | Draft21Subscribe | Draft21SubscribeOk | Draft21RequestUpdate | Draft21PublishStateNotify | Draft21Publish | Draft21PublishDone | Draft21PublishNamespace | Draft21Namespace | Draft21NamespaceDone | Draft21SubscribeNamespace | Draft21SubscribeTracks | Draft21PublishSkipped | Draft21Fetch | Draft21FetchOk | Draft21TrackStatus | Draft21RequestOk | Draft21RequestError | Draft21GoAway;
+interface ObjectPayload {
+    readonly type: 'object';
+    readonly byteOffset: number;
+    readonly payloadByteOffset: number;
+    readonly objectId: bigint;
+    /** The Object ID Delta as it appeared on the wire, before delta resolution. */
+    readonly objectIdDelta?: bigint;
+    readonly payloadLength: number;
+    readonly status?: bigint;
+    readonly extensionData: Uint8Array;
+    readonly objectProperties?: Record<string, bigint>;
+    readonly payload: Uint8Array;
+}
+interface SubgroupStream {
+    readonly type: 'subgroup';
+    /** SUBGROUP_HEADER `Type Flags` (draft-21 Section 11.3.1). */
+    readonly headerType: number;
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly firstObject?: boolean;
+    readonly objects: ObjectPayload[];
+}
+interface DatagramObject {
+    readonly type: 'datagram';
+    /** OBJECT_DATAGRAM `Type Flags` (draft-21 Section 11.2.1). */
+    readonly datagramType: number;
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    readonly objectId: bigint;
+    readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly objectStatus?: bigint;
+    readonly objectProperties?: Record<string, bigint>;
+    readonly payloadLength: number;
+    readonly payload: Uint8Array;
+}
+interface FetchObjectPayload extends ObjectPayload {
+    readonly serializationFlags: number;
+    readonly groupId: bigint;
+    /** The Group ID Delta as it appeared on the wire, before delta resolution. */
+    readonly groupIdDelta?: bigint;
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+    readonly objectProperties?: Record<string, bigint>;
+}
+interface FetchStream {
+    readonly type: 'fetch';
+    /**
+     * The Request ID of the message that opened the stream. In draft-21 that is
+     * not necessarily a FETCH: a fill fetch stream (Section 3.4) carries the
+     * Request ID of the SUBSCRIBE or REQUEST_UPDATE that requested the fill.
+     */
+    readonly requestId: bigint;
+    readonly objects: FetchObjectPayload[];
+}
+type Draft21DataStream = SubgroupStream | DatagramObject | FetchStream;
+interface SubgroupStreamHeader {
+    readonly type: 'subgroup_header';
+    /**
+     * SUBGROUP_HEADER `Type Flags`, the same value `SubgroupStream.headerType`
+     * carries. It is reported so the incremental decoder does not drop the flags
+     * the header encodes, which is what lets a consumer tell the modes apart.
+     */
+    readonly headerType: number;
+    readonly trackAlias: bigint;
+    readonly groupId: bigint;
+    /**
+     * Under Subgroup Mode 0b01 this is the first Object's ID, which is why the
+     * header is not emitted until that Object has been read.
+     */
+    readonly subgroupId: bigint;
+    readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly firstObject?: boolean;
+}
+interface FetchStreamHeader {
+    readonly type: 'fetch_header';
+    readonly requestId: bigint;
+}
+type DataStreamHeader = SubgroupStreamHeader | FetchStreamHeader;
+type DataStreamEvent = DataStreamHeader | ObjectPayload;
+
+export type { Draft21SubscribeNamespace as A, Draft21SubscribeOk as B, Draft21SubscribeTracks as C, Draft21Message as D, Draft21TrackProperties as E, FetchStreamHeader as F, Draft21TrackStatus as G, FetchObjectPayload as H, LocationFilter as I, RangeFilterRange as J, Redirect as K, LargestObject as L, ObjectPayload as O, RangeFilter as R, SubgroupStreamHeader as S, UnknownParam as U, Draft21MessageType as a, DataStreamEvent as b, Draft21DataStream as c, DatagramObject as d, FetchStream as e, SubgroupStream as f, DataStreamHeader as g, Draft21BaseMessage as h, Draft21Fetch as i, Draft21FetchOk as j, Draft21FillParameters as k, Draft21GoAway as l, Draft21Namespace as m, Draft21NamespaceDone as n, Draft21Params as o, Draft21Publish as p, Draft21PublishDone as q, Draft21PublishNamespace as r, Draft21PublishSkipped as s, Draft21PublishStateNotify as t, Draft21RequestError as u, Draft21RequestOk as v, Draft21RequestUpdate as w, Draft21Setup as x, Draft21SetupOptions as y, Draft21Subscribe as z };

package/dist/{types-Bg86GGVZ.d.cts → types-DxXNP32l.d.cts}

@@ -234,10 +234,18 @@ interface FetchStream {
 type Draft18DataStream = SubgroupStream | DatagramObject | FetchStream;
 interface SubgroupStreamHeader {
     readonly type: 'subgroup_header';
+    /**
+     * The stream Type Flags, the same value `SubgroupStream.headerType` carries.
+     * It is reported so the incremental decoder does not drop the flags the
+     * header encodes, which is what lets a consumer tell the modes apart.
+     */
+    readonly headerType: number;
     readonly trackAlias: bigint;
     readonly groupId: bigint;
     readonly subgroupId: bigint;
     readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly firstObject?: boolean;
 }
 interface FetchStreamHeader {
     readonly type: 'fetch_header';

package/dist/{types-Bg86GGVZ.d.ts → types-DxXNP32l.d.ts}

@@ -234,10 +234,18 @@ interface FetchStream {
 type Draft18DataStream = SubgroupStream | DatagramObject | FetchStream;
 interface SubgroupStreamHeader {
     readonly type: 'subgroup_header';
+    /**
+     * The stream Type Flags, the same value `SubgroupStream.headerType` carries.
+     * It is reported so the incremental decoder does not drop the flags the
+     * header encodes, which is what lets a consumer tell the modes apart.
+     */
+    readonly headerType: number;
     readonly trackAlias: bigint;
     readonly groupId: bigint;
     readonly subgroupId: bigint;
     readonly publisherPriority: number;
+    readonly endOfGroup?: boolean;
+    readonly firstObject?: boolean;
 }
 interface FetchStreamHeader {
     readonly type: 'fetch_header';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/codec",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "MoQT wire-format codec and session state machine — multi-draft, zero dependencies",
   "type": "module",
   "license": "MIT",
@@ -208,6 +208,18 @@
       "types": "./dist/draft20-session.d.ts",
       "import": "./dist/draft20-session.js",
       "require": "./dist/draft20-session.cjs"
+    },
+    "./draft21": {
+      "bun": "./src/drafts/draft21/index.ts",
+      "types": "./dist/draft21.d.ts",
+      "import": "./dist/draft21.js",
+      "require": "./dist/draft21.cjs"
+    },
+    "./draft21/session": {
+      "bun": "./src/drafts/draft21/session.ts",
+      "types": "./dist/draft21-session.d.ts",
+      "import": "./dist/draft21-session.js",
+      "require": "./dist/draft21-session.cjs"
     }
   },
   "files": [
@@ -221,9 +233,9 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@moqtap/test-vectors": "^0.15.0",
+    "@moqtap/test-vectors": "^0.17.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.2.7"
   }
 }

package/src/core/auth-redaction.ts

@@ -0,0 +1,190 @@
+/**
+ * Overwriting Authorization Token values at the point of parse.
+ *
+ * A collector that ships a customer's control plane verbatim is useful — the
+ * control plane is the part of a session a player library cannot misreport —
+ * right up until it also ships the bearer token sitting in a SETUP option or a
+ * SUBSCRIBE parameter. At that point a debugging tool has become a
+ * credential-exfiltration path.
+ *
+ * The fix has to happen **where the parse happens**, not on the way out. Bytes
+ * that were merely *masked before upload* still sat in memory in a form a later
+ * feature — a dump, an export, a bug — could reach. So this module hangs off
+ * the decoders themselves: the one pass that reads a Token Value is the pass
+ * that records where it was, and the value is overwritten before the frame is
+ * handed to anything that retains it.
+ *
+ * ── What is overwritten, and what deliberately is not
+ *
+ * Only the **Token Value** (draft-20 Section 10.2.2, Figure 5). The Alias Type,
+ * the Token Alias and the Token Type all stay:
+ *
+ *  - the parameter's *presence* distinguishes a session that failed to
+ *    authenticate from one that never tried, and losing that distinction blinds
+ *    the tool at exactly the moment it is most wanted;
+ *  - the Token Alias is how you see the same credential being reused across
+ *    messages, which is a real debugging signal and is not itself a secret;
+ *  - `USE_ALIAS` and `DELETE` carry no value at all, so those frames pass
+ *    through untouched and it is visible that they did.
+ *
+ * The overwrite is **length-preserving**. That is not an aesthetic choice: a
+ * control frame carries a fixed 16-bit Message Length, and every offset a
+ * caller has already computed into the frame stays valid only if the frame does
+ * not change size. Preserving the length also preserves the fact that a token
+ * of *some* size was sent.
+ *
+ * ── Why a span sink and not a return value
+ *
+ * A Token Value is read in `decodeParams` and `decodeSetupOptions`, which sit
+ * under a dozen per-message payload decoders per draft. Threading a redaction
+ * channel out through all of them would mean changing every one of those
+ * signatures, in every draft, to carry something almost none of them use.
+ *
+ * The sink is module state, which is safe here for one specific reason and it
+ * is worth being explicit about it: **decoding is synchronous and single
+ * threaded, and no decoder re-enters the redactor.** {@link redactWith} opens
+ * the capture, runs one decode to completion, and closes it in a `finally`.
+ * There is no `await` between those points, so no second capture can interleave
+ * with the first.
+ */
+
+/**
+ * The byte written over a redacted Token Value.
+ *
+ * Zero, so that a redacted frame is obviously not a token rather than
+ * plausibly one. A caller who needs to tell "redacted" from "the peer really
+ * sent zeros" has {@link AuthRedaction.redacted}, which counts what was
+ * overwritten.
+ */
+export const REDACTION_FILL = 0x00
+
+/**
+ * The result of a redaction pass over one control frame.
+ */
+export interface AuthRedaction {
+  /**
+   * The frame with every Token Value overwritten, exactly as long as the input.
+   *
+   * When nothing needed redacting this is the **same reference** as the input,
+   * so the common case costs no copy. Callers that retain it must copy for the
+   * same reason they would have had to copy the input.
+   */
+  readonly bytes: Uint8Array
+  /** How many Token Values were overwritten. */
+  readonly redacted: number
+  /**
+   * A span was recorded that could not be applied to the frame.
+   *
+   * This means the offset arithmetic and the frame disagree, which is a defect
+   * rather than a wire condition. **A caller must not treat {@link bytes} as
+   * clean when this is set** — the safe response is to drop the frame's raw
+   * bytes rather than ship them, because the one thing that is certain is that
+   * a token was seen and its position is not trusted.
+   */
+  readonly incomplete: boolean
+  /**
+   * Whether the message parsed all the way through.
+   *
+   * A frame can be perfectly legitimate and still not decode: an unknown or
+   * extension message codepoint is something a peer is allowed to send, and a
+   * collector ships those raw on purpose rather than losing the whole control
+   * plane over one of them. But a message that cannot be parsed is a message
+   * whose parameters cannot be walked, so `redacted === 0` on such a frame
+   * means "nothing was found", not "there is nothing there".
+   *
+   * That residual is narrow and it is real, and the only dishonest thing to do
+   * with it is hide it. Count the frames where this is false, so the gap in the
+   * guarantee is a number somebody can look at.
+   */
+  readonly decoded: boolean
+}
+
+/**
+ * Payload-relative `[start, length]` pairs, flat. `null` when not capturing —
+ * which is the state every ordinary decode runs in, so the recording hook costs
+ * one null check on a path that is otherwise untouched.
+ */
+let spans: number[] | null = null
+
+/**
+ * Record that a Token Value occupies `length` bytes at `start`, measured from
+ * the beginning of the **payload** the current decoder is reading.
+ *
+ * Called from the draft decoders. A zero-length value records nothing: there is
+ * nothing to overwrite, and a zero-length span would only inflate the count.
+ */
+export function recordAuthValueSpan(start: number, length: number): void {
+  if (spans === null || length <= 0) return
+  spans.push(start, length)
+}
+
+/**
+ * Run `decode` with span capture suspended.
+ *
+ * For decoders that read a parameter block out of a **nested** buffer — draft-20's
+ * `FILL_PARAMETERS` is the case that exists today. Offsets recorded inside a
+ * nested reader are relative to that reader, and applying them to the outer
+ * payload would overwrite unrelated bytes: not a failed redaction but a
+ * corrupted frame, and a silent one. Scope rules already forbid an
+ * AUTHORIZATION_TOKEN inside FILL_PARAMETERS, so this guards against a future
+ * nesting rather than a present one — which is exactly when it is cheap to add.
+ */
+export function withoutAuthValueSpans<T>(decode: () => T): T {
+  const saved = spans
+  spans = null
+  try {
+    return decode()
+  } finally {
+    spans = saved
+  }
+}
+
+/**
+ * Decode `frame` once, capturing Token Value spans, and return the frame with
+ * those values overwritten.
+ *
+ * `payloadStart` is where the message payload begins inside the frame; the
+ * spans the decoders record are payload-relative, and this is what makes them
+ * frame-relative. `decode` may fail — a malformed message decodes partially and
+ * throws or returns an error — and **spans recorded before it failed are still
+ * applied**, because a value that was read is a value that was exposed
+ * regardless of what happened afterwards.
+ *
+ * `decode` reports whether it parsed the whole message; a throw counts as no.
+ */
+export function redactWith(
+  frame: Uint8Array,
+  payloadStart: number,
+  decode: () => boolean,
+): AuthRedaction {
+  const outer = spans
+  spans = []
+  let captured: number[]
+  let decoded = false
+  try {
+    decoded = decode()
+  } catch {
+    // The caller's decoder threw. Whatever it recorded before it did is real.
+  } finally {
+    captured = spans
+    spans = outer
+  }
+
+  if (captured.length === 0) return { bytes: frame, redacted: 0, incomplete: false, decoded }
+
+  let out: Uint8Array | null = null
+  let redacted = 0
+  let incomplete = false
+  for (let i = 0; i < captured.length; i += 2) {
+    const start = payloadStart + (captured[i] as number)
+    const length = captured[i + 1] as number
+    if (payloadStart < 0 || start < 0 || start + length > frame.length) {
+      incomplete = true
+      continue
+    }
+    if (out === null) out = frame.slice()
+    out.fill(REDACTION_FILL, start, start + length)
+    redacted++
+  }
+  return { bytes: out ?? frame, redacted, incomplete, decoded }
+}

package/src/core/types.ts

@@ -14,6 +14,7 @@ export type Draft =
   | '18'
   | '19'
   | '20'
+  | '21'
 
 // Base codec interface — draft-specific codecs extend this
 export interface BaseCodec<M> {