@moqtap/codec 0.10.0 → 0.12.0

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

@@ -0,0 +1,68 @@
+// Draft-16 error, status and termination code registries.
+
+export const SessionErrorCode = {
+  NoError: 0x0n,
+  InternalError: 0x1n,
+  Unauthorized: 0x2n,
+  ProtocolViolation: 0x3n,
+  InvalidRequestId: 0x4n,
+  DuplicateTrackAlias: 0x5n,
+  KeyValueFormattingError: 0x6n,
+  TooManyRequests: 0x7n,
+  InvalidPath: 0x8n,
+  MalformedPath: 0x9n,
+  GoawayTimeout: 0x10n,
+  ControlMessageTimeout: 0x11n,
+  DataStreamTimeout: 0x12n,
+  AuthTokenCacheOverflow: 0x13n,
+  DuplicateAuthTokenAlias: 0x14n,
+  VersionNegotiationFailed: 0x15n,
+  MalformedAuthToken: 0x16n,
+  UnknownAuthTokenAlias: 0x17n,
+  ExpiredAuthToken: 0x18n,
+  InvalidAuthority: 0x19n,
+  MalformedAuthority: 0x1an,
+} as const
+export type SessionErrorCodeValue = (typeof SessionErrorCode)[keyof typeof SessionErrorCode]
+
+export const RequestErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  MalformedAuthToken: 0x4n,
+  ExpiredAuthToken: 0x5n,
+  DoesNotExist: 0x10n,
+  InvalidRange: 0x11n,
+  MalformedTrack: 0x12n,
+  DuplicateSubscription: 0x19n,
+  Uninterested: 0x20n,
+  PrefixOverlap: 0x30n,
+  InvalidJoiningRequestId: 0x32n,
+} as const
+export type RequestErrorCodeValue = (typeof RequestErrorCode)[keyof typeof RequestErrorCode]
+
+export const PublishDoneStatusCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  TrackEnded: 0x2n,
+  SubscriptionEnded: 0x3n,
+  GoingAway: 0x4n,
+  Expired: 0x5n,
+  TooFarBehind: 0x6n,
+  UpdateFailed: 0x8n,
+  MalformedTrack: 0x12n,
+} as const
+export type PublishDoneStatusCodeValue =
+  (typeof PublishDoneStatusCode)[keyof typeof PublishDoneStatusCode]
+
+export const DataStreamResetErrorCode = {
+  InternalError: 0x0n,
+  Cancelled: 0x1n,
+  DeliveryTimeout: 0x2n,
+  SessionClosed: 0x3n,
+  UnknownObjectStatus: 0x4n,
+  MalformedTrack: 0x12n,
+} as const
+export type DataStreamResetErrorCodeValue =
+  (typeof DataStreamResetErrorCode)[keyof typeof DataStreamResetErrorCode]

package/src/drafts/draft16/index.ts

@@ -1,5 +1,7 @@
 export const DRAFT_VERSION = 0xff000010n
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft16Codec } from './codec.js'
 export {
   createDataStreamDecoder,
@@ -16,7 +18,20 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
+export type {
+  DataStreamResetErrorCodeValue,
+  PublishDoneStatusCodeValue,
+  RequestErrorCodeValue,
+  SessionErrorCodeValue,
+} from './error-codes.js'
+export {
+  DataStreamResetErrorCode,
+  PublishDoneStatusCode,
+  RequestErrorCode,
+  SessionErrorCode,
+} from './error-codes.js'
 export {
   MESSAGE_ID_MAP,
   MESSAGE_TYPE_MAP,

package/src/drafts/draft16/messages.ts

@@ -1,21 +1,21 @@
 // Draft-16 message type wire IDs
 
-export const MSG_REQUEST_UPDATE = 0x02n // renamed from SUBSCRIBE_UPDATE
+export const MSG_REQUEST_UPDATE = 0x02n
 export const MSG_SUBSCRIBE = 0x03n
 export const MSG_SUBSCRIBE_OK = 0x04n
 export const MSG_REQUEST_ERROR = 0x05n
 export const MSG_PUBLISH_NAMESPACE = 0x06n
 export const MSG_REQUEST_OK = 0x07n
-export const MSG_NAMESPACE = 0x08n // new in draft-16
+export const MSG_NAMESPACE = 0x08n // NAMESPACE (draft-16 Section 9.21); draft-15 has no 0x8 control message
 export const MSG_PUBLISH_NAMESPACE_DONE = 0x09n
 export const MSG_UNSUBSCRIBE = 0x0an
 export const MSG_PUBLISH_DONE = 0x0bn
 export const MSG_PUBLISH_NAMESPACE_CANCEL = 0x0cn
 export const MSG_TRACK_STATUS = 0x0dn
-export const MSG_NAMESPACE_DONE = 0x0en // new in draft-16
+export const MSG_NAMESPACE_DONE = 0x0en // NAMESPACE_DONE (draft-16 Section 9.23); draft-15 has no 0xE control message
 export const MSG_GOAWAY = 0x10n
 export const MSG_SUBSCRIBE_NAMESPACE = 0x11n
-// 0x14 (UNSUBSCRIBE_NAMESPACE) removed in draft-16
+// 0x14 is unassigned in draft-16 (Section 9, Table 1); draft-15 binds it to UNSUBSCRIBE_NAMESPACE.
 export const MSG_MAX_REQUEST_ID = 0x15n
 export const MSG_FETCH = 0x16n
 export const MSG_FETCH_CANCEL = 0x17n

package/src/drafts/draft16/session-fsm.ts

@@ -370,7 +370,6 @@ export class Draft16SessionFSM {
     return { ok: true, phase: this._phase, sideEffects }
   }
 
-  // Renamed from handleSubscribeUpdate in draft-15
   private handleRequestUpdate(
     message: Draft16Message,
     sideEffects: SideEffect[],

package/src/drafts/draft16/types.ts

@@ -41,7 +41,9 @@ export interface LargestObject {
   readonly object: bigint
 }
 
-// Track extensions (separate parameter set in draft-16)
+// Track Extensions — a trailing sequence of Extension Headers on SUBSCRIBE_OK, PUBLISH and
+// FETCH_OK, carried alongside the parameters rather than among them; draft-16 is the only
+// draft that carries it
 export interface Draft16TrackExtensions {
   delivery_timeout?: bigint // 0x02 even
   max_cache_duration?: bigint // 0x04 even
@@ -109,7 +111,8 @@ export interface Draft16ServerSetup extends Draft16BaseMessage {
   readonly parameters: Draft16SetupParams
 }
 
-// Subscribe — fields moved to parameters
+// SUBSCRIBE — type 0x3; drafts 07-14 carry the subscriber priority, group order, filter and
+// (from draft-11) forward flag as fields of the message, drafts 15 and 16 as parameters
 export interface Draft16Subscribe extends Draft16BaseMessage {
   readonly type: 'subscribe'
   readonly request_id: bigint
@@ -126,7 +129,7 @@ export interface Draft16SubscribeOk extends Draft16BaseMessage {
   readonly track_extensions?: Draft16TrackExtensions
 }
 
-// Renamed from subscribe_update in draft-15
+// Request Update — type 0x2; drafts 07-15 name the same codepoint SUBSCRIBE_UPDATE
 export interface Draft16RequestUpdate extends Draft16BaseMessage {
   readonly type: 'request_update'
   readonly request_id: bigint
@@ -172,13 +175,17 @@ export interface Draft16PublishNamespace extends Draft16BaseMessage {
   readonly parameters: Draft16Params
 }
 
-// Simplified in draft-16: just request_id
+// PUBLISH_NAMESPACE_DONE — type 0x9, keyed by request_id here; drafts 07-15 carry the Track
+// Namespace in that position and name the codepoint UNANNOUNCE before draft-14; no draft from
+// 17 on carries the message
 export interface Draft16PublishNamespaceDone extends Draft16BaseMessage {
   readonly type: 'publish_namespace_done'
   readonly request_id: bigint
 }
 
-// Changed in draft-16: request_id + error_code + reason_phrase
+// PUBLISH_NAMESPACE_CANCEL — type 0xC, keyed by request_id here; drafts 07-15 carry the Track
+// Namespace in that position with the same error_code + reason_phrase after it, and name the
+// codepoint ANNOUNCE_CANCEL before draft-14; no draft from 17 on carries the message
 export interface Draft16PublishNamespaceCancel extends Draft16BaseMessage {
   readonly type: 'publish_namespace_cancel'
   readonly request_id: bigint
@@ -186,7 +193,7 @@ export interface Draft16PublishNamespaceCancel extends Draft16BaseMessage {
   readonly reason_phrase: string
 }
 
-// subscribe_namespace gains subscribe_options in draft-16
+// Only drafts 16 and 17 carry a subscribe_options field on SUBSCRIBE_NAMESPACE
 export interface Draft16SubscribeNamespace extends Draft16BaseMessage {
   readonly type: 'subscribe_namespace'
   readonly request_id: bigint
@@ -207,7 +214,7 @@ export interface Draft16NamespaceDone extends Draft16BaseMessage {
   readonly namespace_suffix: string[]
 }
 
-// unsubscribe_namespace is REMOVED in draft-16
+// No draft from 16 on carries UNSUBSCRIBE_NAMESPACE; drafts 13 through 15 do
 
 // Fetch — same structure as draft-15
 export interface StandaloneFetch {
@@ -264,7 +271,7 @@ export interface Draft16RequestOk extends Draft16BaseMessage {
   readonly parameters: Draft16Params
 }
 
-// request_error gains retry_interval in draft-16
+// REQUEST_ERROR — type 0x5; draft-15's carries no retry_interval, every draft from 16 on does
 export interface Draft16RequestError extends Draft16BaseMessage {
   readonly type: 'request_error'
   readonly request_id: bigint
@@ -371,10 +378,17 @@ export type Draft16DataStream = 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
 }
 
 export interface FetchStreamHeader {

package/src/drafts/draft17/codec.ts

@@ -1,3 +1,4 @@
+import { type AuthRedaction, recordAuthValueSpan, redactWith } from '../../core/auth-redaction.js'
 import { Draft17BufferReader as BufferReader } from '../../core/buffer-reader.js'
 import { Draft17BufferWriter as BufferWriter } from '../../core/buffer-writer.js'
 import { bytesToHex, hexToBytes } from '../../core/hex.js'
@@ -168,10 +169,9 @@ function decodeSetupOptions(reader: BufferReader, payloadEnd: number): Draft17Se
       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.token_value)
+        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) {
@@ -200,10 +200,14 @@ function encodeAuthorizationToken(token: AuthorizationToken, w: BufferWriter): v
     w.writeVarInt(token.token_alias ?? 0n)
   }
   if (aliasType === 1 || aliasType === 3) {
-    // REGISTER, USE_VALUE: token_type + token_value present
+    // REGISTER, USE_VALUE: token_type + token_value present.
+    // In draft-17 the Token Value is NOT length-prefixed inside the Token
+    // structure; it consumes the remainder of the outer length-prefixed buffer.
+    // Figure 5 writes it as `Token Value (..)`, and the only length genuinely
+    // present is the Key-Value-Pair's own, which is what "uses Length-prefixed
+    // encoding" describes. Draft-18 repeats that figure and prose verbatim.
     w.writeVarInt(token.token_type ?? 0n)
     const tv = token.token_value ?? new Uint8Array(0)
-    w.writeVarInt(BigInt(tv.byteLength))
     w.writeBytes(tv)
   }
 }
@@ -218,8 +222,8 @@ function decodeAuthorizationToken(r: BufferReader): AuthorizationToken {
   }
   if (aliasType === 1 || aliasType === 3) {
     ;(result as { token_type: bigint }).token_type = r.readVarInt()
-    const len = Number(r.readVarInt())
-    const bytes = r.readBytes(len)
+    // Token Value extends to the end of the outer length-prefixed buffer
+    const bytes = r.readBytes(r.remaining)
     ;(result as { token_value: Uint8Array }).token_value = bytes
   }
 
@@ -414,10 +418,9 @@ function decodeParams(reader: BufferReader, messageType: string): Draft17Params
     } 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.token_value)
+      result.authorization_token = [...(result.authorization_token ?? []), token]
     } else if (paramType === PARAM_RENDEZVOUS_TIMEOUT) {
       result.rendezvous_timeout = reader.readVarInt()
     } else if (paramType === PARAM_EXPIRES) {
@@ -1250,3 +1253,61 @@ export function createDraft17Codec(): Draft17Codec {
     createDataStreamDecoder,
   }
 }
+
+/**
+ * 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
+ * last field of the Token structure, so its start is the parameter value's end
+ * minus the value's own length. The fields before it are left alone
+ * deliberately: Alias Type, Token Alias and Token Type are structure rather
+ * than secret, and they are what distinguishes a session that failed to
+ * authenticate from one that never tried.
+ *
+ * A token carrying no value at all -- DELETE and USE_ALIAS -- records nothing,
+ * and its frame passes through untouched.
+ */
+function noteAuthTokenValue(
+  valueStart: number,
+  valueLength: number,
+  value: Uint8Array | undefined,
+): void {
+  if (value === undefined || value.byteLength === 0) return
+  recordAuthValueSpan(valueStart + valueLength - value.byteLength, value.byteLength)
+}
+
+/**
+ * Overwrite every Authorization Token value in a draft-17 control frame.
+ *
+ * One decode, whose *output is discarded*: the point is not to read the
+ * message, it is to learn where the credentials 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 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 credential. Reported as not decoded rather than as clean: a
+    // 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)
+}