@moqtap/codec 0.9.0 → 0.11.0

package/src/drafts/draft13/codec.ts

@@ -1,3 +1,4 @@
+import { type AuthRedaction, recordAuthValueSpan, redactWith } from '../../core/auth-redaction.js'
 import { BufferReader } from '../../core/buffer-reader.js'
 import { BufferWriter } from '../../core/buffer-writer.js'
 import { bytesToHex, hexToBytes } from '../../core/hex.js'
@@ -115,7 +116,7 @@ function encodeSetupParams(params: Draft13SetupParams, w: BufferWriter): void {
   let count = 0
   if (params.path !== undefined) count++
   if (params.max_request_id !== undefined) count++
-  if (params.authorization_token !== undefined) count++
+  count += params.authorization_token?.length ?? 0
   if (params.max_auth_token_cache_size !== undefined) count++
   if (params.unknown) count += params.unknown.length
 
@@ -131,9 +132,9 @@ function encodeSetupParams(params: Draft13SetupParams, w: BufferWriter): void {
     w.writeVarInt(SETUP_PARAM_MAX_REQUEST_ID)
     w.writeVarInt(params.max_request_id)
   }
-  if (params.authorization_token !== undefined) {
+  for (const token of params.authorization_token ?? []) {
     w.writeVarInt(SETUP_PARAM_AUTHORIZATION_TOKEN)
-    encodeAuthorizationToken(params.authorization_token, w)
+    encodeAuthorizationToken(token, w)
   }
   if (params.max_auth_token_cache_size !== undefined) {
     w.writeVarInt(SETUP_PARAM_MAX_AUTH_TOKEN_CACHE_SIZE)
@@ -185,7 +186,10 @@ function decodeSetupParams(r: BufferReader): Draft13SetupParams {
         const bytes = r.readBytes(length)
         result.path = textDecoder.decode(bytes)
       } else if (paramType === SETUP_PARAM_AUTHORIZATION_TOKEN) {
-        result.authorization_token = decodeAuthorizationToken(r, length)
+        const valueStart = r.offset
+        const token = decodeAuthorizationToken(r, length)
+        noteAuthTokenValue(valueStart, length, token.token_value)
+        result.authorization_token = [...(result.authorization_token ?? []), token]
       } else {
         const bytes = r.readBytes(length)
         unknown.push({
@@ -207,7 +211,7 @@ function decodeSetupParams(r: BufferReader): Draft13SetupParams {
 function encodeParams(params: Draft13Params, w: BufferWriter): void {
   let count = params.unknown ? params.unknown.length : 0
   if (params.delivery_timeout !== undefined) count++
-  if (params.authorization_token !== undefined) count++
+  count += params.authorization_token?.length ?? 0
   if (params.max_cache_duration !== undefined) count++
   w.writeVarInt(count)
 
@@ -216,10 +220,10 @@ function encodeParams(params: Draft13Params, w: BufferWriter): void {
     w.writeVarInt(PARAM_DELIVERY_TIMEOUT)
     w.writeVarInt(params.delivery_timeout)
   }
-  if (params.authorization_token !== undefined) {
+  for (const token of params.authorization_token ?? []) {
     // AUTHORIZATION_TOKEN = 0x03 (odd → length-prefixed)
     w.writeVarInt(PARAM_AUTHORIZATION_TOKEN)
-    encodeAuthorizationToken(params.authorization_token, w)
+    encodeAuthorizationToken(token, w)
   }
   if (params.max_cache_duration !== undefined) {
     // MAX_CACHE_DURATION = 0x04 (even → bare varint)
@@ -275,7 +279,10 @@ function decodeParams(r: BufferReader): Draft13Params {
       const length = Number(r.readVarInt())
 
       if (paramType === PARAM_AUTHORIZATION_TOKEN) {
-        result.authorization_token = decodeAuthorizationToken(r, length)
+        const valueStart = r.offset
+        const token = decodeAuthorizationToken(r, length)
+        noteAuthTokenValue(valueStart, length, token.token_value)
+        result.authorization_token = [...(result.authorization_token ?? []), token]
       } else {
         const bytes = r.readBytes(length)
         unknown.push({
@@ -425,7 +432,7 @@ function encodeAnnounceCancelPayload(
   w.writeString(msg.reason_phrase)
 }
 
-// Draft-13: subscribe_namespace (renamed from subscribe_announces, same wire format)
+// Draft-13 subscribe_namespace (0x11) — byte-identical to the payload draft-12 spells subscribe_announces.
 function encodeSubscribeNamespacePayload(
   msg: Draft13Message & { type: 'subscribe_namespace' },
   w: BufferWriter,
@@ -547,7 +554,7 @@ function encodeFetchCancelPayload(
   w.writeVarInt(msg.request_id)
 }
 
-// Draft-13: track_status is now SUBSCRIBE-like
+// Draft-13 Section 8.20: the TRACK_STATUS message format is identical to SUBSCRIBE.
 function encodeTrackStatusPayload(
   msg: Draft13Message & { type: 'track_status' },
   w: BufferWriter,
@@ -777,7 +784,6 @@ function decodeAnnounceCancelPayload(r: BufferReader): Draft13Message {
   return { type: 'announce_cancel', track_namespace, error_code, reason_phrase }
 }
 
-// Draft-13: subscribe_namespace (renamed from subscribe_announces)
 function decodeSubscribeNamespacePayload(r: BufferReader): Draft13Message {
   const request_id = r.readVarInt()
   const track_namespace_prefix = r.readTuple()
@@ -1293,3 +1299,61 @@ export function createDraft13Codec(): Draft13Codec {
     createStreamDecoder,
   }
 }
+
+/**
+ * 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-13 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)
+}

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

@@ -0,0 +1,107 @@
+// Draft-13 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,
+} as const
+export type SessionErrorCodeValue = (typeof SessionErrorCode)[keyof typeof SessionErrorCode]
+
+export const SubscribeErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  TrackDoesNotExist: 0x4n,
+  InvalidRange: 0x5n,
+  MalformedAuthToken: 0x10n,
+  ExpiredAuthToken: 0x12n,
+} as const
+export type SubscribeErrorCodeValue = (typeof SubscribeErrorCode)[keyof typeof SubscribeErrorCode]
+
+export const SubscribeDoneStatusCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  TrackEnded: 0x2n,
+  SubscriptionEnded: 0x3n,
+  GoingAway: 0x4n,
+  Expired: 0x5n,
+  TooFarBehind: 0x6n,
+  MalformedTrack: 0x7n,
+} as const
+export type SubscribeDoneStatusCodeValue =
+  (typeof SubscribeDoneStatusCode)[keyof typeof SubscribeDoneStatusCode]
+
+export const PublishErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  Uninterested: 0x4n,
+} as const
+export type PublishErrorCodeValue = (typeof PublishErrorCode)[keyof typeof PublishErrorCode]
+
+export const FetchErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  TrackDoesNotExist: 0x4n,
+  InvalidRange: 0x5n,
+  NoObjects: 0x6n,
+  InvalidJoiningRequestId: 0x7n,
+  UnknownStatusInRange: 0x8n,
+  MalformedTrack: 0x9n,
+  MalformedAuthToken: 0x10n,
+  ExpiredAuthToken: 0x12n,
+} as const
+export type FetchErrorCodeValue = (typeof FetchErrorCode)[keyof typeof FetchErrorCode]
+
+export const AnnounceErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  Uninterested: 0x4n,
+  MalformedAuthToken: 0x10n,
+  ExpiredAuthToken: 0x12n,
+} as const
+export type AnnounceErrorCodeValue = (typeof AnnounceErrorCode)[keyof typeof AnnounceErrorCode]
+
+export const SubscribeNamespaceErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  NamespacePrefixUnknown: 0x4n,
+  NamespacePrefixOverlap: 0x5n,
+  MalformedAuthToken: 0x10n,
+  ExpiredAuthToken: 0x12n,
+} as const
+export type SubscribeNamespaceErrorCodeValue =
+  (typeof SubscribeNamespaceErrorCode)[keyof typeof SubscribeNamespaceErrorCode]
+
+export const StreamResetErrorCode = {
+  InternalError: 0x0n,
+  Cancelled: 0x1n,
+  DeliveryTimeout: 0x2n,
+  SessionClosed: 0x3n,
+} as const
+export type StreamResetErrorCodeValue =
+  (typeof StreamResetErrorCode)[keyof typeof StreamResetErrorCode]

package/src/drafts/draft13/index.ts

@@ -1,5 +1,7 @@
 export const DRAFT_VERSION = 0xff00000dn
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft13Codec } from './codec.js'
 export {
   createDraft13Codec,
@@ -13,7 +15,28 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
+export type {
+  AnnounceErrorCodeValue,
+  FetchErrorCodeValue,
+  PublishErrorCodeValue,
+  SessionErrorCodeValue,
+  StreamResetErrorCodeValue,
+  SubscribeDoneStatusCodeValue,
+  SubscribeErrorCodeValue,
+  SubscribeNamespaceErrorCodeValue,
+} from './error-codes.js'
+export {
+  AnnounceErrorCode,
+  FetchErrorCode,
+  PublishErrorCode,
+  SessionErrorCode,
+  StreamResetErrorCode,
+  SubscribeDoneStatusCode,
+  SubscribeErrorCode,
+  SubscribeNamespaceErrorCode,
+} from './error-codes.js'
 export {
   MESSAGE_ID_MAP,
   MESSAGE_TYPE_MAP,

package/src/drafts/draft13/types.ts

@@ -21,7 +21,7 @@ export interface AuthorizationToken {
 export interface Draft13SetupParams {
   path?: string // 0x01 odd
   max_request_id?: bigint // 0x02 even
-  authorization_token?: AuthorizationToken // 0x03 odd
+  authorization_token?: readonly AuthorizationToken[] // 0x03 odd
   max_auth_token_cache_size?: bigint // 0x04 even
   unknown?: UnknownParam[]
 }
@@ -29,7 +29,7 @@ export interface Draft13SetupParams {
 // Version-specific parameters — even/odd convention
 export interface Draft13Params {
   delivery_timeout?: bigint // 0x02 even
-  authorization_token?: AuthorizationToken // 0x03 odd
+  authorization_token?: readonly AuthorizationToken[] // 0x03 odd
   max_cache_duration?: bigint // 0x04 even
   unknown?: UnknownParam[]
 }
@@ -181,7 +181,7 @@ export interface Draft13AnnounceCancel extends Draft13BaseMessage {
   readonly reason_phrase: string
 }
 
-// Subscribe Namespace (renamed from subscribe_announces in draft-12)
+// Subscribe Namespace — type 0x11; drafts 07-12 name the same codepoint SUBSCRIBE_ANNOUNCES
 export interface Draft13SubscribeNamespace extends Draft13BaseMessage {
   readonly type: 'subscribe_namespace'
   readonly request_id: bigint

package/src/drafts/draft14/codec.ts

@@ -1,3 +1,4 @@
+import { type AuthRedaction, recordAuthValueSpan, redactWith } from '../../core/auth-redaction.js'
 import { BufferReader } from '../../core/buffer-reader.js'
 import { BufferWriter } from '../../core/buffer-writer.js'
 import { bytesToHex, hexToBytes } from '../../core/hex.js'
@@ -78,7 +79,7 @@ function encodeSetupParams(params: Draft14Params, writer: BufferWriter): void {
   if (params.role !== undefined) count++
   if (params.path !== undefined) count++
   if (params.max_request_id !== undefined) count++
-  if (params.authorization_token !== undefined) count++
+  count += params.authorization_token?.length ?? 0
   if (params.authority !== undefined) count++
   if (params.max_auth_token_cache_size !== undefined) count++
   if (params.moqt_implementation !== undefined) count++
@@ -100,9 +101,9 @@ function encodeSetupParams(params: Draft14Params, writer: BufferWriter): void {
     writer.writeVarInt(PARAM_MAX_REQUEST_ID)
     writer.writeVarInt(params.max_request_id)
   }
-  if (params.authorization_token !== undefined) {
+  for (const token of params.authorization_token ?? []) {
     writer.writeVarInt(PARAM_AUTHORIZATION_TOKEN)
-    const tok = params.authorization_token
+    const tok = token
     const tmpWriter = new BufferWriter(64)
     tmpWriter.writeVarInt(tok.alias_type)
     if (tok.token_type !== undefined) {
@@ -183,11 +184,15 @@ function decodeSetupParams(reader: BufferReader): Draft14Params {
         if (tokenReader.remaining > 0) {
           tok.token_type = tokenReader.readVarInt()
           if (tokenReader.remaining > 0) {
-            const tokenValue = tokenReader.readBytesView(tokenReader.remaining)
-            tok.token_value = new Uint8Array(tokenValue)
+            const value = new Uint8Array(tokenReader.readBytesView(tokenReader.remaining))
+            tok.token_value = value
+            noteAuthTokenValue(reader.offset - length, length, value)
           }
         }
-        result.authorization_token = tok as unknown as AuthorizationToken
+        result.authorization_token = [
+          ...(result.authorization_token ?? []),
+          tok as unknown as AuthorizationToken,
+        ]
       } else if (paramType === PARAM_AUTHORITY) {
         result.authority = textDecoder.decode(bytes)
       } else if (paramType === PARAM_MOQT_IMPLEMENTATION) {
@@ -209,7 +214,7 @@ function decodeSetupParams(reader: BufferReader): Draft14Params {
 function encodeMessageParams(params: Draft14Params, writer: BufferWriter): void {
   let count = 0
   if (params.delivery_timeout !== undefined) count++
-  if (params.authorization_token !== undefined) count++
+  count += params.authorization_token?.length ?? 0
   if (params.max_cache_duration !== undefined) count++
   if (params.unknown) count += params.unknown.length
 
@@ -219,9 +224,9 @@ function encodeMessageParams(params: Draft14Params, writer: BufferWriter): void
     writer.writeVarInt(PARAM_DELIVERY_TIMEOUT)
     writer.writeVarInt(params.delivery_timeout)
   }
-  if (params.authorization_token !== undefined) {
+  for (const token of params.authorization_token ?? []) {
     writer.writeVarInt(PARAM_AUTHORIZATION_TOKEN)
-    const tok = params.authorization_token
+    const tok = token
     const tmpWriter = new BufferWriter(64)
     tmpWriter.writeVarInt(tok.alias_type)
     if (tok.token_type !== undefined) {
@@ -286,11 +291,15 @@ function decodeMessageParams(reader: BufferReader): Draft14Params {
         if (tokenReader.remaining > 0) {
           tok.token_type = tokenReader.readVarInt()
           if (tokenReader.remaining > 0) {
-            const tokenValue = tokenReader.readBytesView(tokenReader.remaining)
-            tok.token_value = new Uint8Array(tokenValue)
+            const value = new Uint8Array(tokenReader.readBytesView(tokenReader.remaining))
+            tok.token_value = value
+            noteAuthTokenValue(reader.offset - length, length, value)
           }
         }
-        result.authorization_token = tok as unknown as AuthorizationToken
+        result.authorization_token = [
+          ...(result.authorization_token ?? []),
+          tok as unknown as AuthorizationToken,
+        ]
       } else {
         unknown.push({
           id: `0x${paramType.toString(16)}`,
@@ -1380,3 +1389,61 @@ export function createDraft14Codec(): Draft14Codec {
     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-14 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)
+}