@moqtap/codec 0.10.0 → 0.11.0

package/src/drafts/draft19/error-codes.ts

@@ -36,7 +36,9 @@ export const RequestErrorCode = {
   DoesNotExist: 0x10n,
   InvalidRange: 0x11n,
   MalformedTrack: 0x12n,
-  // DuplicateSubscription (0x19) removed in draft-19 — multiple concurrent subscriptions per Track are now allowed
+  // 0x19 is unassigned in draft-19: Section 5.1 lets an endpoint hold multiple concurrent
+  // subscriptions to the same Track, so there is no DuplicateSubscription error. Draft-18
+  // binds 0x19 to DUPLICATE_SUBSCRIPTION.
   Uninterested: 0x20n,
   PrefixOverlap: 0x30n,
   NamespaceTooLarge: 0x31n,

package/src/drafts/draft19/index.ts

@@ -2,6 +2,8 @@
 
 export const DRAFT_VERSION = 0xff000013n
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft19Codec } from './codec.js'
 export {
   createDataStreamDecoder,
@@ -18,6 +20,7 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
 export type {
   DataStreamResetCodeValue,

package/src/drafts/draft19/messages.ts

@@ -15,7 +15,9 @@ export const MSG_GOAWAY = 0x10n
 export const MSG_FETCH = 0x16n
 export const MSG_FETCH_OK = 0x18n
 export const MSG_PUBLISH = 0x1dn
-// In draft-18 PUBLISH_OK is an alias for REQUEST_OK (0x07). Kept as alias.
+// PUBLISH_OK is not a codepoint of its own: it is a REQUEST_OK (0x07) sent in
+// reply to a PUBLISH (draft-19 Section 10.5). 0x1E is RESERVED (Section 10,
+// Table 5).
 export const MSG_PUBLISH_OK = MSG_REQUEST_OK
 export const MSG_SUBSCRIBE_NAMESPACE = 0x50n
 export const MSG_SUBSCRIBE_TRACKS = 0x51n

package/src/drafts/draft19/types.ts

@@ -27,7 +27,7 @@ export interface Draft19SetupOptions {
   unknown?: UnknownParam[]
 }
 
-// Location filter parameter (renamed from SubscriptionFilter in draft-19)
+// Location Filter parameter, 0x21; drafts 15 through 18 name that parameter SUBSCRIPTION_FILTER
 export interface LocationFilter {
   readonly filter_type: bigint
   readonly start_group?: bigint
@@ -57,16 +57,16 @@ export interface LargestObject {
 
 // Version-specific parameters (delta-encoded types, count-prefixed)
 export interface Draft19Params {
-  object_delivery_timeout?: bigint // 0x02 varint (renamed from delivery_timeout in draft-17)
+  object_delivery_timeout?: bigint // 0x02 varint; drafts 11-17 name this parameter DELIVERY TIMEOUT
   authorization_token?: readonly AuthorizationToken[] // 0x03 length-prefixed nested
   rendezvous_timeout?: bigint // 0x04 varint
   subgroup_delivery_timeout?: bigint // 0x06 varint (NEW in draft-18)
   expires?: bigint // 0x08 varint
   largest_object?: LargestObject // 0x09 Location (2 bare varints)
   fill_timeout?: bigint // 0x0a varint (NEW in draft-18)
-  forward?: bigint // 0x10 uint8 (was varint in draft-17)
+  forward?: bigint // 0x10 uint8; drafts 15 and 16 encode this parameter as a varint
   subscriber_priority?: bigint // 0x20 uint8
-  location_filter?: LocationFilter // 0x21 length-prefixed (renamed from subscription_filter in draft-19)
+  location_filter?: LocationFilter // 0x21 length-prefixed; SUBSCRIPTION_FILTER on drafts 15-18
   group_order?: bigint // 0x22 uint8
   // Section 5.1.3 permits each of the five more than once in a message: a
   // filter parameter carries one SetID, so two alternatives over the same
@@ -83,7 +83,7 @@ export interface Draft19Params {
 
 // Track properties (KVP encoding, no count prefix, read until end of payload)
 export interface Draft19TrackProperties {
-  object_delivery_timeout?: bigint // 0x02 even varint (renamed from delivery_timeout)
+  object_delivery_timeout?: bigint // 0x02 even varint; drafts 11-17 name this parameter DELIVERY TIMEOUT
   max_cache_duration?: bigint // 0x04 even varint
   subgroup_delivery_timeout?: bigint // 0x06 even varint (NEW in draft-18)
   immutable_properties?: Uint8Array // 0x0b odd length-prefixed
@@ -125,7 +125,8 @@ export interface Draft19Setup extends Draft19BaseMessage {
   readonly options: Draft19SetupOptions
 }
 
-// Subscribe — Required Request ID Delta REMOVED in draft-18
+// SUBSCRIBE — type 0x3; draft-17 is the only draft that carries a Required Request ID Delta
+// after the request_id, there and on every other request message (draft-17 Section 9.2)
 export interface Draft19Subscribe extends Draft19BaseMessage {
   readonly type: 'subscribe'
   readonly request_id: bigint
@@ -183,7 +184,7 @@ export interface Draft19NamespaceDone extends Draft19BaseMessage {
   readonly namespace_suffix: string[]
 }
 
-// SUBSCRIBE_NAMESPACE — type 0x50, subscribe_options field removed in draft-18
+// SUBSCRIBE_NAMESPACE — type 0x50; only drafts 16 and 17 carry a subscribe_options field here
 export interface Draft19SubscribeNamespace extends Draft19BaseMessage {
   readonly type: 'subscribe_namespace'
   readonly request_id: bigint
@@ -191,7 +192,7 @@ export interface Draft19SubscribeNamespace extends Draft19BaseMessage {
   readonly parameters: Draft19Params
 }
 
-// SUBSCRIBE_TRACKS — NEW in draft-18, type 0x51
+// SUBSCRIBE_TRACKS — type 0x51; no draft before 18 carries this message
 export interface Draft19SubscribeTracks extends Draft19BaseMessage {
   readonly type: 'subscribe_tracks'
   readonly request_id: bigint
@@ -238,7 +239,8 @@ export interface Draft19FetchOk extends Draft19BaseMessage {
   readonly track_properties: Draft19TrackProperties
 }
 
-// Track Status — same format as subscribe in draft-18 (without required_request_id_delta)
+// Track Status — format identical to SUBSCRIBE (Section 10.7), minus the subscriber
+// parameters related to Track delivery (e.g. SUBSCRIBER_PRIORITY, Section 10.2.7).
 export interface Draft19TrackStatus extends Draft19BaseMessage {
   readonly type: 'track_status'
   readonly request_id: bigint
@@ -247,7 +249,7 @@ export interface Draft19TrackStatus extends Draft19BaseMessage {
   readonly parameters: Draft19Params
 }
 
-// REQUEST_OK — gained trailing Track Properties in draft-18
+// REQUEST_OK — carries trailing Track Properties after the parameters (Section 10.5); drafts 15-17 have no such field
 export interface Draft19RequestOk extends Draft19BaseMessage {
   readonly type: 'request_ok'
   readonly parameters: Draft19Params
@@ -274,7 +276,8 @@ export interface Draft19GoAway extends Draft19BaseMessage {
   readonly type: 'goaway'
   readonly new_session_uri: string
   readonly timeout: bigint
-  // Request ID removed from GOAWAY in draft-19 — control and request streams share one format
+  // Draft-18 is the only draft that puts a Request ID on GOAWAY, and carries it only when the
+  // message goes on the control stream; on every other draft the message has no such field
 }
 
 // Union of all draft-18 control messages
@@ -356,10 +359,18 @@ export type Draft19DataStream = SubgroupStream | DatagramObject | FetchStream
 // Streaming data stream decoder types
 export interface SubgroupStreamHeader {
   readonly type: 'subgroup_header'
+  /**
+   * The stream Type Flags, the same value `SubgroupStream.headerType` carries.
+   * Without it the incremental decoder drops every flag the header encodes
+   * and a consumer cannot 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
 }
 
 export interface FetchStreamHeader {

package/src/drafts/draft20/codec.ts

@@ -1,3 +1,9 @@
+import {
+  type AuthRedaction,
+  recordAuthValueSpan,
+  redactWith,
+  withoutAuthValueSpans,
+} from '../../core/auth-redaction.js'
 import { MoqtBufferReader as BufferReader } from '../../core/buffer-reader.js'
 import { MoqtBufferWriter as BufferWriter } from '../../core/buffer-writer.js'
 import { bytesToHex, hexToBytes } from '../../core/hex.js'
@@ -216,10 +222,9 @@ function decodeSetupOptions(reader: BufferReader, payloadEnd: number): Draft20Se
       if (optType === SETUP_OPT_PATH) {
         result.path = textDecoder.decode(bytes)
       } else if (optType === SETUP_OPT_AUTHORIZATION_TOKEN) {
-        result.authorization_token = [
-          ...(result.authorization_token ?? []),
-          decodeAuthorizationToken(new BufferReader(bytes)),
-        ]
+        const token = decodeAuthorizationToken(new BufferReader(bytes))
+        noteAuthTokenValue(reader.offset - length, length, token)
+        result.authorization_token = [...(result.authorization_token ?? []), token]
       } else if (optType === SETUP_OPT_AUTHORITY) {
         result.authority = textDecoder.decode(bytes)
       } else if (optType === SETUP_OPT_MOQT_IMPLEMENTATION) {
@@ -257,6 +262,32 @@ function encodeAuthorizationToken(token: AuthorizationToken, w: BufferWriter): v
   }
 }
 
+/**
+ * Record where a Token Value sits, so it can be overwritten before the frame
+ * reaches anything that keeps it (Section 1.6).
+ *
+ * The span falls out of the decode with no second walk. The Token Value is the
+ * tail of the Token structure — draft-20 Section 10.2.2, Figure 5: it is NOT
+ * length-prefixed inside the Token and consumes the remainder of the outer
+ * length-prefixed parameter value. So its start is the parameter value's end
+ * minus the value's own length, and the fields before it (Alias Type, Token
+ * Alias, Token Type) are left alone deliberately: they are structure, not
+ * secret, and they are what distinguishes a session that failed to
+ * authenticate from one that never tried.
+ *
+ * DELETE (0x0) and USE_ALIAS (0x2) carry no value at all, so they record
+ * nothing and their frames pass through untouched.
+ */
+function noteAuthTokenValue(
+  valueStart: number,
+  valueLength: number,
+  token: AuthorizationToken,
+): void {
+  const value = token.token_value
+  if (value === undefined || value.byteLength === 0) return
+  recordAuthValueSpan(valueStart + valueLength - value.byteLength, value.byteLength)
+}
+
 function decodeAuthorizationToken(r: BufferReader): AuthorizationToken {
   const alias_type = r.readVarInt()
   const aliasType = Number(alias_type)
@@ -395,7 +426,7 @@ function decodeRangeFilter(reader: BufferReader, hasProperty: boolean): RangeFil
   return property_type !== undefined ? { set_id, property_type, ranges } : { set_id, ranges }
 }
 
-// ─── LOCATION_FILTER (0x21) — restructured in draft-20 (Section 5.1.2) ──────
+// ─── LOCATION_FILTER (0x21) — draft-20 Section 5.1.2 ───────────────────────
 
 /**
  * Encode a LOCATION_FILTER value.
@@ -517,9 +548,11 @@ function decodeLocationFilter(reader: BufferReader): LocationFilter {
  * Read out of draft-20's per-parameter sections, not carried over from
  * draft-19. The biggest delta is that `request_ok` — which is also PUBLISH_OK,
  * REQUEST_UPDATE_OK, TRACK_STATUS_OK, SUBSCRIBE_NAMESPACE_OK,
- * SUBSCRIBE_TRACKS_OK and PUBLISH_NAMESPACE_OK — lost every subscription
- * parameter it used to carry. Only EXPIRES (0x08) and LARGEST_OBJECT (0x09)
- * still name it. Subscription parameters travel on PUBLISH (initial values) and
+ * SUBSCRIBE_TRACKS_OK and PUBLISH_NAMESPACE_OK — carries almost no subscription
+ * parameter. Only EXPIRES (0x08) names it, where draft-19 also lists it on
+ * OBJECT_DELIVERY_TIMEOUT (0x02), SUBGROUP_DELIVERY_TIMEOUT (0x06), FORWARD
+ * (0x10), SUBSCRIBER_PRIORITY (0x20), LOCATION_FILTER (0x21) and
+ * NEW_GROUP_REQUEST (0x32). Subscription parameters travel on PUBLISH (initial values) and
  * REQUEST_UPDATE (changes) instead.
  *
  * `fill_parameters` in a set means the type is one of the eight Table 6 permits
@@ -549,24 +582,24 @@ const PARAMETER_SCOPE = new Map<bigint, Set<string>>([
   [PARAM_SUBGROUP_DELIVERY_TIMEOUT, new Set(['subscribe', 'publish', 'request_update'])],
   // 0x08 EXPIRES (10.2.16) — the one parameter that still names PUBLISH_OK.
   [PARAM_EXPIRES, new Set(['subscribe_ok', 'publish', 'request_ok'])],
-  // 0x09 LARGEST_OBJECT (10.2.17) — gained PUBLISH_STATE_NOTIFY in draft-20.
+  // 0x09 LARGEST_OBJECT (10.2.17) — PUBLISH_STATE_NOTIFY here; draft-19 (10.2.16) omits it.
   [
     PARAM_LARGEST_OBJECT,
     new Set(['subscribe_ok', 'publish', 'request_ok', 'publish_state_notify']),
   ],
   // 0x0A FILL_TIMEOUT (10.2.5) — FETCH, or nested inside FILL_PARAMETERS.
   [PARAM_FILL_TIMEOUT, new Set(['fetch', FILL_SCOPE])],
-  // 0x10 FORWARD (10.2.18) — lost PUBLISH_OK, gained PUBLISH_STATE_NOTIFY.
+  // 0x10 FORWARD (10.2.18) — PUBLISH_STATE_NOTIFY here where draft-19 (10.2.17) lists PUBLISH_OK.
   [
     PARAM_FORWARD,
     new Set(['subscribe', 'request_update', 'publish', 'subscribe_tracks', 'publish_state_notify']),
   ],
-  // 0x20 SUBSCRIBER_PRIORITY (10.2.7) — lost PUBLISH_OK, gained PUBLISH.
+  // 0x20 SUBSCRIBER_PRIORITY (10.2.7) — PUBLISH here where draft-19 lists PUBLISH_OK.
   [
     PARAM_SUBSCRIBER_PRIORITY,
     new Set(['subscribe', 'publish', 'fetch', 'request_update', FILL_SCOPE]),
   ],
-  // 0x21 LOCATION_FILTER (10.2.9) — lost PUBLISH_OK, gained PUBLISH and PUBLISH_STATE_NOTIFY.
+  // 0x21 LOCATION_FILTER (10.2.9) — PUBLISH and PUBLISH_STATE_NOTIFY here where draft-19 lists PUBLISH_OK.
   [
     PARAM_LOCATION_FILTER,
     new Set([
@@ -578,12 +611,12 @@ const PARAMETER_SCOPE = new Map<bigint, Set<string>>([
       FILL_SCOPE,
     ]),
   ],
-  // 0x22 GROUP_ORDER (10.2.8) — gained PUBLISH and FILL_PARAMETERS nesting.
+  // 0x22 GROUP_ORDER (10.2.8) — PUBLISH and FILL_PARAMETERS nesting here; draft-19 has neither.
   [PARAM_GROUP_ORDER, new Set(['subscribe', 'publish', 'subscribe_tracks', 'fetch', FILL_SCOPE])],
   // 0x23 FILL_PARAMETERS (10.2.15) — NEW. Subscriptions only, and never nested
   // in itself: a FETCH already is a fetch, so it has nothing to fill.
   [PARAM_FILL_PARAMETERS, new Set(['subscribe', 'request_update'])],
-  // 0x25-0x28 range filters (5.1.4) — lost PUBLISH_OK, gained FILL_PARAMETERS nesting.
+  // 0x25-0x28 range filters (5.1.4) — permitted inside FILL_PARAMETERS (Table 6).
   [
     PARAM_SUBGROUP_FILTER,
     new Set(['fetch', 'subscribe', 'subscribe_tracks', 'request_update', FILL_SCOPE]),
@@ -600,11 +633,11 @@ const PARAMETER_SCOPE = new Map<bigint, Set<string>>([
     PARAM_OBJECT_PROPERTY_FILTER,
     new Set(['fetch', 'subscribe', 'subscribe_tracks', 'request_update', FILL_SCOPE]),
   ],
-  // 0x29 TRACK_PROPERTY_FILTER (10.2.14) — lost PUBLISH_OK; NOT permitted
-  // inside FILL_PARAMETERS. A relay forwarding a downstream FILL_PARAMETERS
-  // upstream has to strip it rather than trip this rule.
+  // 0x29 TRACK_PROPERTY_FILTER (10.2.14) — NOT permitted inside
+  // FILL_PARAMETERS: Table 6 omits it. A relay forwarding a downstream
+  // FILL_PARAMETERS upstream has to strip it rather than trip this rule.
   [PARAM_TRACK_PROPERTY_FILTER, new Set(['subscribe_tracks', 'request_update'])],
-  // 0x32 NEW_GROUP_REQUEST (10.2.19) — lost PUBLISH_OK.
+  // 0x32 NEW_GROUP_REQUEST (10.2.19) — draft-19 (10.2.18) also lists PUBLISH_OK.
   [PARAM_NEW_GROUP_REQUEST, new Set(['subscribe', 'request_update'])],
   // 0x34 TRACK_NAMESPACE_PREFIX (10.2.20) — REQUEST_UPDATE for a namespace subscription.
   [PARAM_TRACK_NAMESPACE_PREFIX, new Set(['request_update'])],
@@ -826,10 +859,9 @@ function decodeParams(reader: BufferReader, messageType: string): Draft20Params
     } else if (paramType === PARAM_AUTHORIZATION_TOKEN) {
       const length = Number(reader.readVarInt())
       const bytes = reader.readBytes(length)
-      result.authorization_token = [
-        ...(result.authorization_token ?? []),
-        decodeAuthorizationToken(new BufferReader(bytes)),
-      ]
+      const token = decodeAuthorizationToken(new BufferReader(bytes))
+      noteAuthTokenValue(reader.offset - length, length, token)
+      result.authorization_token = [...(result.authorization_token ?? []), token]
     } else if (paramType === PARAM_RENDEZVOUS_TIMEOUT) {
       result.rendezvous_timeout = reader.readVarInt()
     } else if (paramType === PARAM_SUBGROUP_DELIVERY_TIMEOUT) {
@@ -926,7 +958,7 @@ function decodeFillParameters(reader: BufferReader): Draft20FillParameters {
   const length = Number(reader.readVarInt())
   const valueBytes = reader.readBytes(length)
   const nested = new BufferReader(valueBytes)
-  const params = decodeParams(nested, FILL_SCOPE)
+  const params = withoutAuthValueSpans(() => decodeParams(nested, FILL_SCOPE))
   if (nested.remaining > 0) {
     // The parameter count and the byte length disagree. The draft does not say
     // what to do; leaving the slack unread would let a sender smuggle bytes no
@@ -1747,3 +1779,38 @@ export function createDraft20Codec(): Draft20Codec {
     createDataStreamDecoder,
   }
 }
+
+/**
+ * Overwrite every Authorization Token value in a draft-20 control frame.
+ *
+ * One decode, whose *output is discarded*: the point is not to read the
+ * message, it is to learn where the tokens were so the caller never has to hold
+ * a frame that contains one. A caller that also wants the message should decode
+ * the **redacted** frame with {@link decodeMessage}, which then cannot produce a
+ * token value because there is no longer one in the bytes.
+ *
+ * A frame that fails to decode is still redacted as far as the decode got. That
+ * is the useful direction to fail in: a value that was read is a value that was
+ * exposed, whatever went wrong after it.
+ *
+ * See {@link AuthRedaction.incomplete} for the one result a caller must not
+ * treat as clean, and {@link AuthRedaction.decoded} for the residual it cannot
+ * close.
+ */
+export function redactAuthTokens(bytes: Uint8Array): AuthRedaction {
+  let payloadStart: number
+  try {
+    const probe = new BufferReader(bytes)
+    probe.readVarInt()
+    probe.readUint8()
+    probe.readUint8()
+    payloadStart = probe.offset
+  } catch {
+    // Too short to carry a message header, and so too short for the parameters
+    // that carry a token. Reported as not decoded rather than as clean: the
+    // framer only ever emits complete frames, so a caller that gets here is
+    // holding something this function did not check.
+    return { bytes, redacted: 0, incomplete: false, decoded: false }
+  }
+  return redactWith(bytes, payloadStart, () => decodeMessage(bytes).ok)
+}