@moqtap/codec 0.10.0 → 0.12.0

package/src/drafts/draft18/index.ts

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

package/src/drafts/draft18/types.ts

@@ -41,14 +41,14 @@ export interface LargestObject {
 
 // Version-specific parameters (delta-encoded types, count-prefixed)
 export interface Draft18Params {
-  object_delivery_timeout?: bigint // 0x02 varint (renamed from delivery_timeout in draft-17)
+  object_delivery_timeout?: bigint // 0x02 varint; drafts 11-17 name the same codepoint 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
   subscription_filter?: SubscriptionFilter // 0x21 length-prefixed
   group_order?: bigint // 0x22 uint8
@@ -59,7 +59,7 @@ export interface Draft18Params {
 
 // Track properties (KVP encoding, no count prefix, read until end of payload)
 export interface Draft18TrackProperties {
-  object_delivery_timeout?: bigint // 0x02 even varint (renamed from delivery_timeout)
+  object_delivery_timeout?: bigint // 0x02 even varint; drafts 11-17 name the same codepoint 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
@@ -101,7 +101,7 @@ export interface Draft18Setup extends Draft18BaseMessage {
   readonly options: Draft18SetupOptions
 }
 
-// Subscribe — Required Request ID Delta REMOVED in draft-18
+// Subscribe — draft-18 Section 10.7. No Required Request ID Delta; draft-17 alone carries that field.
 export interface Draft18Subscribe extends Draft18BaseMessage {
   readonly type: 'subscribe'
   readonly request_id: bigint
@@ -159,7 +159,7 @@ export interface Draft18NamespaceDone extends Draft18BaseMessage {
   readonly namespace_suffix: string[]
 }
 
-// SUBSCRIBE_NAMESPACE — type 0x50, subscribe_options field removed in draft-18
+// SUBSCRIBE_NAMESPACE — type 0x50; no Subscribe Options field in draft-18.
 export interface Draft18SubscribeNamespace extends Draft18BaseMessage {
   readonly type: 'subscribe_namespace'
   readonly request_id: bigint
@@ -167,7 +167,7 @@ export interface Draft18SubscribeNamespace extends Draft18BaseMessage {
   readonly parameters: Draft18Params
 }
 
-// SUBSCRIBE_TRACKS — NEW in draft-18, type 0x51
+// SUBSCRIBE_TRACKS — type 0x51.
 export interface Draft18SubscribeTracks extends Draft18BaseMessage {
   readonly type: 'subscribe_tracks'
   readonly request_id: bigint
@@ -214,7 +214,7 @@ export interface Draft18FetchOk extends Draft18BaseMessage {
   readonly track_properties: Draft18TrackProperties
 }
 
-// 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 (Section 10.14).
 export interface Draft18TrackStatus extends Draft18BaseMessage {
   readonly type: 'track_status'
   readonly request_id: bigint
@@ -223,7 +223,7 @@ export interface Draft18TrackStatus extends Draft18BaseMessage {
   readonly parameters: Draft18Params
 }
 
-// REQUEST_OK — gained trailing Track Properties in draft-18
+// REQUEST_OK — carries trailing Track Properties after the parameters.
 export interface Draft18RequestOk extends Draft18BaseMessage {
   readonly type: 'request_ok'
   readonly parameters: Draft18Params
@@ -332,10 +332,18 @@ export type Draft18DataStream = 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.
+   * 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
 }
 
 export interface FetchStreamHeader {

package/src/drafts/draft19/codec.ts

@@ -1,3 +1,4 @@
+import { type AuthRedaction, recordAuthValueSpan, redactWith } 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'
@@ -191,10 +192,9 @@ function decodeSetupOptions(reader: BufferReader, payloadEnd: number): Draft19Se
       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) {
@@ -232,6 +232,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.
+ *
+ * The span falls out of the decode with no second walk. The Token Value is the
+ * tail of the Token structure — draft-19 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)
@@ -282,7 +308,7 @@ const PARAM_LARGEST_OBJECT = 0x09n
 const PARAM_FILL_TIMEOUT = 0x0an
 const PARAM_FORWARD = 0x10n
 const PARAM_SUBSCRIBER_PRIORITY = 0x20n
-const PARAM_LOCATION_FILTER = 0x21n // renamed from SUBSCRIPTION_FILTER in draft-19
+const PARAM_LOCATION_FILTER = 0x21n // LOCATION_FILTER (draft-19 Section 10.2.9); drafts 15-18 name 0x21 SUBSCRIPTION_FILTER
 const PARAM_GROUP_ORDER = 0x22n
 const PARAM_SUBGROUP_FILTER = 0x25n // NEW in draft-19
 const PARAM_OBJECTID_FILTER = 0x26n // NEW in draft-19
@@ -590,10 +616,9 @@ function decodeParams(reader: BufferReader, messageType: string): Draft19Params
     } 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) {
@@ -608,7 +633,7 @@ function decodeParams(reader: BufferReader, messageType: string): Draft19Params
     } else if (paramType === PARAM_FILL_TIMEOUT) {
       result.fill_timeout = reader.readVarInt()
     } else if (paramType === PARAM_FORWARD) {
-      // uint8 in draft-18 (was varint in draft-17)
+      // uint8 (Section 10.2.17); drafts 15 and 16 encode this as a varint
       result.forward = BigInt(reader.readUint8())
     } else if (paramType === PARAM_SUBSCRIBER_PRIORITY) {
       // uint8: single raw byte
@@ -1478,3 +1503,38 @@ export function createDraft19Codec(): Draft19Codec {
     createDataStreamDecoder,
   }
 }
+
+/**
+ * Overwrite every Authorization Token value in a draft-19 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)
+}