@moqtap/codec 0.10.0 → 0.11.0

package/src/drafts/draft08/index.ts

@@ -1,5 +1,7 @@
 export const DRAFT_VERSION = 0xff000008n
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft08Codec } from './codec.js'
 export {
   createDraft08Codec,
@@ -15,7 +17,26 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
+export type {
+  AnnounceErrorCodeValue,
+  FetchErrorCodeValue,
+  SessionErrorCodeValue,
+  SubscribeAnnouncesErrorCodeValue,
+  SubscribeDoneStatusCodeValue,
+  SubscribeErrorCodeValue,
+  TrackStatusCodeValue,
+} from './error-codes.js'
+export {
+  AnnounceErrorCode,
+  FetchErrorCode,
+  SessionErrorCode,
+  SubscribeAnnouncesErrorCode,
+  SubscribeDoneStatusCode,
+  SubscribeErrorCode,
+  TrackStatusCode,
+} from './error-codes.js'
 export {
   MESSAGE_ID_MAP,
   MESSAGE_TYPE_MAP,

package/src/drafts/draft09/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'
@@ -182,6 +183,11 @@ function decodeParams(r: BufferReader): Draft09Params {
 
     if (paramType === PARAM_AUTHORIZATION_INFO) {
       const bytes = r.readBytes(length)
+      // The credential is the whole value in this draft: a bare UTF-8 string,
+      // with no alias and no token type around it. What survives the overwrite
+      // is the parameter's presence, which is what says authorization was
+      // attempted at all.
+      recordAuthValueSpan(r.offset - length, length)
       result.authorization_info = textDecoder.decode(bytes)
     } else if (paramType === PARAM_DELIVERY_TIMEOUT) {
       const blob = r.readBytes(length)
@@ -975,3 +981,37 @@ export function createDraft09Codec(): Draft09Codec {
     createStreamDecoder,
   }
 }
+
+/**
+ * Overwrite every AUTHORIZATION_INFO value in a draft-09 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.readVarInt()
+    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/draft09/error-codes.ts

@@ -0,0 +1,76 @@
+// Draft-09 error, status and termination code registries.
+
+export const SessionErrorCode = {
+  NoError: 0x0n,
+  InternalError: 0x1n,
+  Unauthorized: 0x2n,
+  ProtocolViolation: 0x3n,
+  DuplicateTrackAlias: 0x4n,
+  ParameterLengthMismatch: 0x5n,
+  TooManySubscribes: 0x6n,
+  GoawayTimeout: 0x10n,
+  ControlMessageTimeout: 0x11n,
+  DataStreamTimeout: 0x12n,
+} as const
+export type SessionErrorCodeValue = (typeof SessionErrorCode)[keyof typeof SessionErrorCode]
+
+export const AnnounceErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  Uninterested: 0x4n,
+} as const
+export type AnnounceErrorCodeValue = (typeof AnnounceErrorCode)[keyof typeof AnnounceErrorCode]
+
+export const SubscribeErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  TrackDoesNotExist: 0x4n,
+  InvalidRange: 0x5n,
+  RetryTrackAlias: 0x6n,
+} as const
+export type SubscribeErrorCodeValue = (typeof SubscribeErrorCode)[keyof typeof SubscribeErrorCode]
+
+export const FetchErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  TrackDoesNotExist: 0x4n,
+  InvalidRange: 0x5n,
+} as const
+export type FetchErrorCodeValue = (typeof FetchErrorCode)[keyof typeof FetchErrorCode]
+
+export const SubscribeDoneStatusCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  TrackEnded: 0x2n,
+  SubscriptionEnded: 0x3n,
+  GoingAway: 0x4n,
+  Expired: 0x5n,
+  TooFarBehind: 0x6n,
+} as const
+export type SubscribeDoneStatusCodeValue =
+  (typeof SubscribeDoneStatusCode)[keyof typeof SubscribeDoneStatusCode]
+
+export const SubscribeAnnouncesErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  NamespacePrefixUnknown: 0x4n,
+} as const
+export type SubscribeAnnouncesErrorCodeValue =
+  (typeof SubscribeAnnouncesErrorCode)[keyof typeof SubscribeAnnouncesErrorCode]
+
+export const TrackStatusCode = {
+  InProgress: 0x00n,
+  TrackDoesNotExist: 0x01n,
+  NotYetBegun: 0x02n,
+  Finished: 0x03n,
+  RelayStatusUnavailable: 0x04n,
+} as const
+export type TrackStatusCodeValue = (typeof TrackStatusCode)[keyof typeof TrackStatusCode]

package/src/drafts/draft09/index.ts

@@ -1,5 +1,7 @@
 export const DRAFT_VERSION = 0xff000009n
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft09Codec } from './codec.js'
 export {
   createDraft09Codec,
@@ -15,7 +17,26 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
+export type {
+  AnnounceErrorCodeValue,
+  FetchErrorCodeValue,
+  SessionErrorCodeValue,
+  SubscribeAnnouncesErrorCodeValue,
+  SubscribeDoneStatusCodeValue,
+  SubscribeErrorCodeValue,
+  TrackStatusCodeValue,
+} from './error-codes.js'
+export {
+  AnnounceErrorCode,
+  FetchErrorCode,
+  SessionErrorCode,
+  SubscribeAnnouncesErrorCode,
+  SubscribeDoneStatusCode,
+  SubscribeErrorCode,
+  TrackStatusCode,
+} from './error-codes.js'
 export {
   MESSAGE_ID_MAP,
   MESSAGE_TYPE_MAP,

package/src/drafts/draft10/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'
@@ -182,6 +183,11 @@ function decodeParams(r: BufferReader): Draft10Params {
 
     if (paramType === PARAM_AUTHORIZATION_INFO) {
       const bytes = r.readBytes(length)
+      // The credential is the whole value in this draft: a bare UTF-8 string,
+      // with no alias and no token type around it. What survives the overwrite
+      // is the parameter's presence, which is what says authorization was
+      // attempted at all.
+      recordAuthValueSpan(r.offset - length, length)
       result.authorization_info = textDecoder.decode(bytes)
     } else if (paramType === PARAM_DELIVERY_TIMEOUT) {
       const blob = r.readBytes(length)
@@ -975,3 +981,37 @@ export function createDraft10Codec(): Draft10Codec {
     createStreamDecoder,
   }
 }
+
+/**
+ * Overwrite every AUTHORIZATION_INFO value in a draft-10 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.readVarInt()
+    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/draft10/error-codes.ts

@@ -0,0 +1,76 @@
+// Draft-10 error, status and termination code registries.
+
+export const SessionErrorCode = {
+  NoError: 0x0n,
+  InternalError: 0x1n,
+  Unauthorized: 0x2n,
+  ProtocolViolation: 0x3n,
+  DuplicateTrackAlias: 0x4n,
+  ParameterLengthMismatch: 0x5n,
+  TooManySubscribes: 0x6n,
+  GoawayTimeout: 0x10n,
+  ControlMessageTimeout: 0x11n,
+  DataStreamTimeout: 0x12n,
+} 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,
+  RetryTrackAlias: 0x6n,
+} 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,
+} as const
+export type SubscribeDoneStatusCodeValue =
+  (typeof SubscribeDoneStatusCode)[keyof typeof SubscribeDoneStatusCode]
+
+export const FetchErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  TrackDoesNotExist: 0x4n,
+  InvalidRange: 0x5n,
+} as const
+export type FetchErrorCodeValue = (typeof FetchErrorCode)[keyof typeof FetchErrorCode]
+
+export const AnnounceErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  Uninterested: 0x4n,
+} as const
+export type AnnounceErrorCodeValue = (typeof AnnounceErrorCode)[keyof typeof AnnounceErrorCode]
+
+export const SubscribeAnnouncesErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  NamespacePrefixUnknown: 0x4n,
+} as const
+export type SubscribeAnnouncesErrorCodeValue =
+  (typeof SubscribeAnnouncesErrorCode)[keyof typeof SubscribeAnnouncesErrorCode]
+
+export const TrackStatusCode = {
+  InProgress: 0x00n,
+  TrackDoesNotExist: 0x01n,
+  NotYetBegun: 0x02n,
+  Finished: 0x03n,
+  RelayStatusUnavailable: 0x04n,
+} as const
+export type TrackStatusCodeValue = (typeof TrackStatusCode)[keyof typeof TrackStatusCode]

package/src/drafts/draft10/index.ts

@@ -1,5 +1,7 @@
 export const DRAFT_VERSION = 0xff00000an
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft10Codec } from './codec.js'
 export {
   createDraft10Codec,
@@ -15,7 +17,26 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
+export type {
+  AnnounceErrorCodeValue,
+  FetchErrorCodeValue,
+  SessionErrorCodeValue,
+  SubscribeAnnouncesErrorCodeValue,
+  SubscribeDoneStatusCodeValue,
+  SubscribeErrorCodeValue,
+  TrackStatusCodeValue,
+} from './error-codes.js'
+export {
+  AnnounceErrorCode,
+  FetchErrorCode,
+  SessionErrorCode,
+  SubscribeAnnouncesErrorCode,
+  SubscribeDoneStatusCode,
+  SubscribeErrorCode,
+  TrackStatusCode,
+} from './error-codes.js'
 export {
   MESSAGE_ID_MAP,
   MESSAGE_TYPE_MAP,

package/src/drafts/draft11/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'
@@ -227,6 +228,7 @@ function decodeParams(r: BufferReader): Draft11Params {
         const token_type = r.readVarInt()
         const tokenBytesLen = length - (r.offset - startOff)
         const tokenBytes = r.readBytes(tokenBytesLen)
+        noteAuthTokenValue(startOff, length, tokenBytes)
         result.authorization_token = [
           ...(result.authorization_token ?? []),
           {
@@ -1054,3 +1056,61 @@ export function createDraft11Codec(): Draft11Codec {
     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-11 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/draft11/error-codes.ts

@@ -0,0 +1,106 @@
+// Draft-11 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,
+} 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,
+  RetryTrackAlias: 0x6n,
+  MalformedAuthToken: 0x10n,
+  UnknownAuthTokenAlias: 0x11n,
+  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,
+} as const
+export type SubscribeDoneStatusCodeValue =
+  (typeof SubscribeDoneStatusCode)[keyof typeof SubscribeDoneStatusCode]
+
+export const FetchErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  TrackDoesNotExist: 0x4n,
+  InvalidRange: 0x5n,
+  NoObjects: 0x6n,
+  InvalidJoiningSubscribeId: 0x7n,
+  MalformedAuthToken: 0x10n,
+  UnknownAuthTokenAlias: 0x11n,
+  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,
+  UnknownAuthTokenAlias: 0x11n,
+  ExpiredAuthToken: 0x12n,
+} as const
+export type AnnounceErrorCodeValue = (typeof AnnounceErrorCode)[keyof typeof AnnounceErrorCode]
+
+export const SubscribeAnnouncesErrorCode = {
+  InternalError: 0x0n,
+  Unauthorized: 0x1n,
+  Timeout: 0x2n,
+  NotSupported: 0x3n,
+  NamespacePrefixUnknown: 0x4n,
+  NamespacePrefixOverlap: 0x5n,
+  MalformedAuthToken: 0x10n,
+  UnknownAuthTokenAlias: 0x11n,
+  ExpiredAuthToken: 0x12n,
+} as const
+export type SubscribeAnnouncesErrorCodeValue =
+  (typeof SubscribeAnnouncesErrorCode)[keyof typeof SubscribeAnnouncesErrorCode]
+
+export const TrackStatusCode = {
+  InProgress: 0x00n,
+  TrackDoesNotExist: 0x01n,
+  NotYetBegun: 0x02n,
+  Finished: 0x03n,
+  RelayStatusUnavailable: 0x04n,
+} as const
+export type TrackStatusCodeValue = (typeof TrackStatusCode)[keyof typeof TrackStatusCode]
+
+export const StreamResetErrorCode = {
+  InternalError: 0x0n,
+  Cancelled: 0x1n,
+  DeliveryTimeout: 0x2n,
+  SessionClosed: 0x3n,
+} as const
+export type StreamResetErrorCodeValue =
+  (typeof StreamResetErrorCode)[keyof typeof StreamResetErrorCode]

package/src/drafts/draft11/index.ts

@@ -1,5 +1,7 @@
 export const DRAFT_VERSION = 0xff00000bn
 
+export type { AuthRedaction } from '../../core/auth-redaction.js'
+export { REDACTION_FILL } from '../../core/auth-redaction.js'
 export type { Draft11Codec } from './codec.js'
 export {
   createDraft11Codec,
@@ -13,7 +15,28 @@ export {
   encodeFetchStream,
   encodeMessage,
   encodeSubgroupStream,
+  redactAuthTokens,
 } from './codec.js'
+export type {
+  AnnounceErrorCodeValue,
+  FetchErrorCodeValue,
+  SessionErrorCodeValue,
+  StreamResetErrorCodeValue,
+  SubscribeAnnouncesErrorCodeValue,
+  SubscribeDoneStatusCodeValue,
+  SubscribeErrorCodeValue,
+  TrackStatusCodeValue,
+} from './error-codes.js'
+export {
+  AnnounceErrorCode,
+  FetchErrorCode,
+  SessionErrorCode,
+  StreamResetErrorCode,
+  SubscribeAnnouncesErrorCode,
+  SubscribeDoneStatusCode,
+  SubscribeErrorCode,
+  TrackStatusCode,
+} from './error-codes.js'
 export {
   MESSAGE_ID_MAP,
   MESSAGE_TYPE_MAP,

package/src/drafts/draft12/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'
@@ -148,6 +149,7 @@ function decodeSetupParams(r: BufferReader): Draft12SetupParams {
         const token_type = r.readVarInt()
         const tokenBytesLen = length - (r.offset - startOff)
         const tokenBytes = r.readBytes(tokenBytesLen)
+        noteAuthTokenValue(startOff, length, tokenBytes)
         result.authorization_token = [
           ...(result.authorization_token ?? []),
           {
@@ -257,6 +259,7 @@ function decodeParams(r: BufferReader): Draft12Params {
         const token_type = r.readVarInt()
         const tokenBytesLen = length - (r.offset - startOff)
         const tokenBytes = r.readBytes(tokenBytesLen)
+        noteAuthTokenValue(startOff, length, tokenBytes)
         result.authorization_token = [
           ...(result.authorization_token ?? []),
           {
@@ -1205,3 +1208,61 @@ export function createDraft12Codec(): Draft12Codec {
     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-12 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)
+}