feat(net): decode a request's AUTHORIZATION TOKEN by the SETUP rules

doc/concept/standard.md

@@ -29,7 +29,7 @@ subset drops. What a peer actually observes against this implementation:
 - **History is one group.** A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed.
 - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later.
 - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both.
-- **One credential per session**, carried in `SETUP` and forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A token attached to an individual request is ignored. An alias reference or a second token closes the session.
+- **One credential per session**, carried in `SETUP` and forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. A token attached to an individual request is otherwise decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` is refused unread, so its token is not decoded.
 - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, range filters, `TRACK_STATUS` to a JavaScript publisher, `SUBSCRIBE_TRACKS`, and the fetch forms above. On draft 19 and later, and in Rust on drafts 14 through 16, a subscription update may change only priority; any other update ends that subscription.
 - **Datagrams** are a single normal object at object 0, forwarded without renumbering. Anything else is dropped, and a malformed one closes the session. Rust and JavaScript both carry them on every draft.
 - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127.
@@ -52,7 +52,7 @@ See [Encryption](/concept/hang#encryption).
 
 ### Deliberate deviations
 
-These three answers differ from the draft on purpose. They are the
+These four answers differ from the draft on purpose. They are the
 product's model, not bugs, and the relay does not change them.
 
 - **One publisher per path.** A broadcast path names one piece of content, so a
@@ -76,6 +76,11 @@ product's model, not bugs, and the relay does not change them.
   requires an established upstream subscription before `SUBSCRIBE_OK`. From
   moq-lite 05 the track stream answers first, and a missing track is refused
   before `SUBSCRIBE_OK`.
+- **An unknown token alias closes the session.** No alias is ever registered,
+  so a `DELETE` or `USE_ALIAS` token on a request names one that does not exist.
+  [Draft 21 §8.9](https://www.ietf.org/archive/id/draft-ietf-moq-transport-21.html#section-8.9)
+  rejects the message, but `UNKNOWN_AUTH_TOKEN_ALIAS` exists only as a session
+  termination code, so we close the session with it.
 
 ## MSF
 

drafts/draft-lcurley-moq-lite.md

@@ -292,8 +292,12 @@ Sent when terminating the session, via the transport's session close.
 | ------- | ------------- | ----------- |
 |  0x11  | CONTROL_MESSAGE_TIMEOUT | The peer took too long to respond to a control message. |
 | ------- | ------------- | ----------- |
+|  0x13  | AUTH_TOKEN_CACHE_OVERFLOW | A token registration would exceed the advertised token cache size. |
+| ------- | ------------- | ----------- |
 |  0x15  | VERSION_NEGOTIATION_FAILED | No version could be negotiated. |
 | ------- | ------------- | ----------- |
+|  0x17  | UNKNOWN_AUTH_TOKEN_ALIAS | A token named an alias that was never registered. |
+| ------- | ------------- | ----------- |
 
 ### Stream Error Codes
 Sent when resetting a stream (RESET_STREAM), or when refusing to receive one (STOP_SENDING).
@@ -1552,6 +1556,7 @@ The `Message Length` describes the payload size on the wire.
 - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list.
 - Capped the Message Length of every message except FRAME at 65,535 bytes.
 - Added the TOO_MANY_REQUESTS (0x7) session code, closing a session whose peer goes past the endpoint's bound on subscriptions or announcements.
+- Added the AUTH_TOKEN_CACHE_OVERFLOW (0x13) and UNKNOWN_AUTH_TOKEN_ALIAS (0x17) session codes, with moq-transport's meaning.
 - Limited AUTH_OK Expires to 2^53 - 1 milliseconds, with an out-of-range value closing the session with PROTOCOL_VIOLATION.
 - Invalid UTF-8 or an oversized AUTH_ERROR reason closes the session with PROTOCOL_VIOLATION.
 - Added the Auth Stream (0x7) with AUTH, AUTH_OK, and AUTH_ERROR: either endpoint presents a token on its own stream and learns the [path patterns](#path-pattern) it may publish and subscribe to. The union of a session's open grants is its scope. A shrink withdraws what it no longer covers, and an announcement outside the scope closes the session with UNAUTHORIZED. A peer without the stream resets it.

js/net/src/error.test.ts

@@ -209,7 +209,9 @@ test("the code tables match the spec", () => {
 	expect(Number(SessionCode.Cancel)).toBe(0x0);
 	expect(Number(SessionCode.Unauthorized)).toBe(0x2);
 	expect(Number(SessionCode.GoawayTimeout)).toBe(0x10);
+	expect(Number(SessionCode.AuthTokenCacheOverflow)).toBe(0x13);
 	expect(Number(SessionCode.Version)).toBe(0x15);
+	expect(Number(SessionCode.UnknownAuthTokenAlias)).toBe(0x17);
 	expect(Number(StreamCode.Cancel)).toBe(0x1);
 	expect(Number(StreamCode.SessionClosed)).toBe(0x3);
 	expect(Number(StreamCode.TooFarBehind)).toBe(0x5);

js/net/src/error.ts

@@ -44,8 +44,12 @@ export const SessionCode = Object.freeze(
 		GoawayTimeout: 0x10 as SessionCode,
 		/** A control message took too long. */
 		Timeout: 0x11 as SessionCode,
+		/** A token registration would exceed the advertised token cache size, which is 0 when unadvertised. */
+		AuthTokenCacheOverflow: 0x13 as SessionCode,
 		/** No version could be negotiated. */
 		Version: 0x15 as SessionCode,
+		/** A token named an alias that was never registered. */
+		UnknownAuthTokenAlias: 0x17 as SessionCode,
 	} as const),
 );
 
@@ -296,9 +300,13 @@ export class RefusedRedirect extends Error {
  * @public
  */
 export class ProtocolViolation extends Error {
-	constructor(message: string, options?: { cause?: unknown }) {
+	/** The session code to close with: `ProtocolViolation` unless the draft names a more specific one. */
+	readonly code: SessionCode;
+
+	constructor(message: string, options?: { cause?: unknown; code?: SessionCode }) {
 		super(message, options);
 		this.name = "ProtocolViolation";
+		this.code = options?.code ?? SessionCode.ProtocolViolation;
 	}
 }
 

js/net/src/ietf/cluster.test.ts

@@ -9,6 +9,7 @@ import * as Namespace from "./namespace.ts";
 import { Parameters, SetupOption, SetupOptions } from "./parameters.ts";
 import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts";
 import { SubscribeNamespaceEntry } from "./subscribe_namespace.ts";
+import { MalformedAuthToken } from "./token.ts";
 import { type IetfVersion, Version } from "./version.ts";
 
 const VERSION = Version.DRAFT_19;
@@ -241,7 +242,7 @@ test("Cluster: a negotiated PUBLISH_NAMESPACE may carry AUTHORIZATION_TOKEN", as
 				await wr.u62(1n);
 				await Namespace.encode(wr, Path.from("alice.hang"));
 				const params = Cluster.intoParams(advert);
-				params.bytes.set(0x03n, new Uint8Array([1, 2, 3])); // AUTHORIZATION_TOKEN
+				params.bytes.set(0x03n, new Uint8Array([0x03, 0x00, 0xaa])); // AUTHORIZATION_TOKEN: USE_VALUE, type 0
 				await params.encode(wr, version);
 			});
 		},
@@ -251,6 +252,20 @@ test("Cluster: a negotiated PUBLISH_NAMESPACE may carry AUTHORIZATION_TOKEN", as
 	expect(decoded.cluster).toEqual(advert);
 });
 
+test("Cluster: a repeated AUTHORIZATION_TOKEN refuses only the advertisement", async () => {
+	// USE_VALUE, type 0, value 0xAA, twice. A repeated key codes as a delta of 0.
+	const tokens = [2, 0x03, 3, 0x03, 0x00, 0xaa, 0, 3, 0x03, 0x00, 0xaa];
+	const frame = (body: number[]) => new Uint8Array([0, body.length, ...body]);
+
+	// Request ID 1 for namespace "a". The repeat is refused before the missing HOP_PATH is.
+	const advert = PublishNamespace.decode(reader(frame([1, 1, 1, 0x61, ...tokens])), VERSION, true);
+	await expect(advert).rejects.toThrow(MalformedAuthToken);
+	await expect(advert).rejects.toMatchObject({ requestId: 1n });
+
+	const update = PublishNamespaceUpdate.decode(reader(frame([1, ...tokens])), VERSION);
+	await expect(update).rejects.toThrow(MalformedAuthToken);
+});
+
 test("Cluster: every malformed PUBLISH_NAMESPACE update is a protocol violation", async () => {
 	const valid = await encode(new PublishNamespaceUpdate({ requestId: 1n, update: { cost: 2n } }));
 	const trailing = new Uint8Array(valid.byteLength + 1);

js/net/src/ietf/cluster.ts

@@ -29,6 +29,7 @@ import { type Hop, HopSchema, MAX_HOPS, UNKNOWN_HOP } from "../hop.ts";
 import type { Reader } from "../stream.ts";
 import * as Varint from "../varint.ts";
 import { Parameters, SetupOption, type SetupOptions } from "./parameters.ts";
+import { MalformedAuthToken } from "./token.ts";
 import { type IetfVersion, Version } from "./version.ts";
 
 /**
@@ -222,6 +223,8 @@ export async function decodeParams(
 	try {
 		params = await Parameters.decode(r, version, message);
 	} catch (err) {
+		// Keep a violation's own code, such as a request token's, and a refusal of the request alone.
+		if (err instanceof ProtocolViolation || err instanceof MalformedAuthToken) throw err;
 		throw new ProtocolViolation(reason(err), { cause: err });
 	}