feat(net): declare the offered Setup extensions with setup::Extensions

doc/bin/relay/config.md

@@ -7,8 +7,9 @@ description: TOML reference for moq-relay
 
 `moq-relay relay.toml`. Every key is also a CLI flag and environment variable
 that joins the section and key: `listen.tls.cert` is `--listen-tls-cert` /
-`MOQ_LISTEN_TLS_CERT`. The exception is `listen.bind`, spelled `--listen` /
-`MOQ_LISTEN`. Precedence is CLI, then env, then file, then defaults.
+`MOQ_LISTEN_TLS_CERT`. The exceptions: `listen.bind` is spelled `--listen` /
+`MOQ_LISTEN`, and `listen.extensions` and `connect.extensions` are TOML only.
+Precedence is CLI, then env, then file, then defaults.
 `moq-relay --help` lists every flag.
 
 ## \[listen]
@@ -32,6 +33,10 @@ bind = "127.0.0.1:4444"
 [listen.unix]                        # Plaintext qmux over a Unix socket, gated by peer credentials.
 bind = "/run/moq/internal.sock"
 allow.uid = [1001]
+
+[listen.extensions]                  # moq-transport SETUP extensions to offer, each on by default.
+auth = false                         # Decline MoQ Auth (draft 17+).
+solicit = false                      # Decline MoQ Solicit, so peers may announce unasked.
 ```
 
 `timeout` bounds the whole handshake, transport through MoQ SETUP, so a peer
@@ -163,6 +168,8 @@ tls.cert = "relay.pem"               # Present a client certificate (mTLS to pee
 tls.key = "relay.key"
 goaway.redirect = "same-host"        # How far to trust a draining peer's redirect URI.
 goaway.handover = "10s"              # Cap on how long the drained upstream keeps serving.
+extensions.auth = false              # Decline MoQ Auth on outbound moq-transport sessions.
+extensions.solicit = false           # Decline MoQ Solicit. Both default to on, as in [listen.extensions].
 ```
 
 A draining upstream may name a replacement URI. `same-host` follows it only

doc/concept/standard.md

@@ -43,6 +43,9 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists,
 [active-count](/draft/moq-active-count) to count the `NAMESPACE` messages
 before a `SUBSCRIBE_NAMESPACE` is caught up, and
 [probe](/draft/moq-probe) for bandwidth estimation.
+Both libraries offer solicit and auth (draft 17 and later) unless a side's
+`extensions` setting declines one, which connects it as a peer that does not
+speak that extension. The pooled JavaScript `Connection` has no such setting yet.
 [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts
 application payloads, so relays still forward named tracks they cannot read.
 See [Encryption](/concept/hang#encryption).

js/net/src/connection/accept.ts

@@ -3,6 +3,7 @@ import * as Lite from "../lite/index.ts";
 import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts";
 import { Stream } from "../stream.ts";
 import type { Established } from "./established.ts";
+import * as Extensions from "./extensions.ts";
 import { forwardAnnounced } from "./forward.ts";
 import { exchangeSetup } from "./handshake.ts";
 
@@ -33,6 +34,9 @@ export interface AcceptProps {
 	 * nothing. The entries retract when the session dies; see the `consume` connect option.
 	 */
 	consume?: OriginProducer;
+
+	/** The moq-transport extensions to offer, each on unless set to `false`. */
+	extensions?: Extensions.Extensions;
 }
 
 /** The per-session wiring shared by every negotiated protocol path. */
@@ -41,6 +45,8 @@ type SessionProps = {
 	publish?: OriginConsumer;
 	/** Whether this side dialed; only the dialing side aborts on a publication its grant does not cover. */
 	client: boolean;
+	/** The moq-transport extensions this side offers. */
+	extensions: Extensions.Offered;
 };
 
 /**
@@ -70,6 +76,7 @@ async function acceptInner(
 		discovery: props.discovery ?? true,
 		publish: props.publish,
 		client: false,
+		extensions: Extensions.offered(props.extensions),
 	};
 
 	if (protocol === Ietf.ALPN.DRAFT_22) {
@@ -118,7 +125,12 @@ async function acceptAlpn(
 	version: Ietf.IetfVersion,
 	wiring: SessionProps,
 ): Promise<Established> {
-	const { control, early, solicit, hidden, cluster, auth } = await exchangeSetup(transport, version, "moq-lite-js");
+	const { control, early, solicit, hidden, cluster, auth } = await exchangeSetup(
+		transport,
+		version,
+		"moq-lite-js",
+		wiring.extensions,
+	);
 
 	return new Ietf.Connection({
 		...wiring,
@@ -164,7 +176,7 @@ async function acceptSetup(
 	const params = new Ietf.SetupOptions();
 	params.setVarint(Ietf.SetupOption.MaxRequestId, Ietf.initialMaxRequestId(true));
 	params.setBytes(Ietf.SetupOption.Implementation, encoder.encode("moq-lite-js"));
-	Ietf.solicitIntoSetup(params);
+	Extensions.intoSetup(params, wiring.extensions, version);
 	Ietf.hiddenIntoSetup(params);
 
 	const server = new Ietf.ServerSetup({ version, parameters: params });
@@ -224,7 +236,7 @@ async function acceptNegotiated(
 	const params = new Ietf.SetupOptions();
 	params.setVarint(Ietf.SetupOption.MaxRequestId, Ietf.initialMaxRequestId(true));
 	params.setBytes(Ietf.SetupOption.Implementation, encoder.encode("moq-lite-js"));
-	Ietf.solicitIntoSetup(params);
+	Extensions.intoSetup(params, wiring.extensions, setupVersion);
 	Ietf.hiddenIntoSetup(params);
 
 	const server = new Ietf.ServerSetup({ version: selectedVersion, parameters: params });

js/net/src/connection/connect.ts

@@ -9,6 +9,7 @@ import * as Hex from "../util/hex.ts";
 import { redact } from "../util/log.ts";
 import { isWebTransportSupported } from "./browser.ts";
 import type { Established } from "./established.ts";
+import * as Extensions from "./extensions.ts";
 import { forwardAnnounced } from "./forward.ts";
 import { exchangeSetup } from "./handshake.ts";
 
@@ -110,6 +111,9 @@ export interface ConnectProps {
 	 */
 	consume?: OriginProducer;
 
+	/** The moq-transport extensions to offer, each on unless set to `false`. */
+	extensions?: Extensions.Extensions;
+
 	/**
 	 * Aborts the connection attempt with the signal's reason. An already-aborted
 	 * signal rejects before anything opens, and aborting after the connection is
@@ -124,6 +128,8 @@ type SessionProps = {
 	publish?: OriginConsumer;
 	/** Whether this side dialed; only the dialing side aborts on a publication its grant does not cover. */
 	client: boolean;
+	/** The moq-transport extensions this side offers. */
+	extensions: Extensions.Offered;
 };
 
 // Save if WebSocket won the last race, so we won't give QUIC a head start next time.
@@ -170,6 +176,7 @@ async function connectInner(url: URL, props: Omit<ConnectProps, "url">, abort: P
 		discovery: props.discovery ?? true,
 		publish: props.publish,
 		client: true,
+		extensions: Extensions.offered(props.extensions),
 	};
 
 	if (props.transport) {
@@ -310,7 +317,7 @@ async function negotiate(url: URL, session: WebTransport, wiring: SessionProps):
 	const params = new Ietf.SetupOptions();
 	params.setVarint(Ietf.SetupOption.MaxRequestId, Ietf.initialMaxRequestId(false));
 	params.setBytes(Ietf.SetupOption.Implementation, encoder.encode("moq-lite-js"));
-	Ietf.solicitIntoSetup(params);
+	Extensions.intoSetup(params, wiring.extensions, setupVersion);
 	Ietf.hiddenIntoSetup(params);
 
 	const client = new Ietf.ClientSetup({
@@ -367,7 +374,12 @@ async function handshakeAlpn(
 	version: Ietf.IetfVersion,
 	wiring: SessionProps,
 ): Promise<Established> {
-	const { control, early, solicit, hidden, cluster, auth } = await exchangeSetup(session, version, "moq-lite-js");
+	const { control, early, solicit, hidden, cluster, auth } = await exchangeSetup(
+		session,
+		version,
+		"moq-lite-js",
+		wiring.extensions,
+	);
 
 	return new Ietf.Connection({
 		...wiring,

js/net/src/connection/extensions.test.ts

@@ -0,0 +1,105 @@
+import { expect, spyOn, test } from "bun:test";
+import { SessionCode } from "../error.ts";
+import { AuthMessage, AuthOk } from "../ietf/auth.ts";
+import { PublishNamespace } from "../ietf/publish_namespace.ts";
+import { RequestOk } from "../ietf/request.ts";
+import { ALPN, Version } from "../ietf/version.ts";
+import { createMockTransportPair } from "../mock.ts";
+import * as Path from "../path.ts";
+import { Stream } from "../stream.ts";
+import { accept } from "./accept.ts";
+import { type Extensions, offered } from "./extensions.ts";
+import { exchangeSetup } from "./handshake.ts";
+
+const VERSION = Version.DRAFT_18;
+const URL_ = new URL("https://example.com");
+
+/** What each side learns from the other's SETUP when each offers `client` and `server`. */
+async function handshake(client: Extensions, server: Extensions) {
+	const pair = createMockTransportPair(ALPN.DRAFT_18);
+	const [dialed, accepted] = await Promise.all([
+		exchangeSetup(pair.client, VERSION, "test", offered(client)),
+		exchangeSetup(pair.server, VERSION, "test", offered(server)),
+	]);
+	return { dialed, accepted };
+}
+
+/** Accept a draft-18 session offering `extensions`, against a peer offering every extension. */
+async function acceptWith(extensions: Extensions) {
+	const pair = createMockTransportPair(ALPN.DRAFT_18);
+	const [peer, connection] = await Promise.all([
+		exchangeSetup(pair.client, VERSION, "test", offered()),
+		accept({ transport: pair.server, url: URL_, extensions }),
+	]);
+	return { pair, peer, connection };
+}
+
+test("every extension is offered by default", () => {
+	expect(offered()).toEqual({ auth: true, solicit: true });
+	expect(offered({ solicit: false })).toEqual({ auth: true, solicit: false });
+});
+
+test("a declined extension stays out of SETUP", async () => {
+	// Control: both sides offer both.
+	const all = await handshake({}, {});
+	expect(all.accepted.solicit).toBe(true);
+	expect(all.accepted.auth).toBe(true);
+	expect(all.dialed.auth).toBe(true);
+
+	const none = await handshake({ auth: false, solicit: false }, {});
+	expect(none.accepted.solicit).toBeUndefined();
+	expect(none.accepted.auth).toBe(false);
+	// Negotiated only when both offer it, so the declining side does not speak it either.
+	expect(none.dialed.auth).toBe(false);
+	expect(none.dialed.solicit).toBe(true);
+});
+
+test("an AUTH to a side that declined it closes the session", async () => {
+	// Control: offered by both, the connection credential is granted.
+	const offering = await acceptWith({});
+	const granted = await Stream.open(offering.pair.client, { version: VERSION });
+	await new AuthMessage(0n, new Uint8Array()).encode(granted.writer, VERSION);
+	expect(await granted.reader.u53()).toBe(AuthOk.id);
+	offering.connection.close();
+
+	const logged = spyOn(console, "error").mockImplementation(() => void 0);
+	try {
+		const declined = await acceptWith({ auth: false });
+		const refused = await Stream.open(declined.pair.client, { version: VERSION });
+		// The session closes on the message type alone, so the rest of the write may fail.
+		await new AuthMessage(0n, new Uint8Array()).encode(refused.writer, VERSION).catch(() => undefined);
+		const info = await declined.pair.client.closed;
+		expect(info.closeCode).toBe(SessionCode.ProtocolViolation);
+	} finally {
+		logged.mockRestore();
+	}
+});
+
+test("a side that declined solicit takes an unsolicited announce", async () => {
+	const announce = async (session: Awaited<ReturnType<typeof acceptWith>>) => {
+		const stream = await Stream.open(session.pair.client, { version: VERSION });
+		await stream.writer.u53(PublishNamespace.id);
+		await new PublishNamespace({
+			requestId: 0n,
+			trackNamespace: Path.from("room"),
+			cluster: { hops: [session.peer.cluster.self], cost: 0n },
+		}).encode(stream.writer, VERSION);
+		return stream;
+	};
+
+	const declined = await acceptWith({ solicit: false });
+	const taken = await announce(declined);
+	expect(await taken.reader.u53()).toBe(RequestOk.id);
+	declined.connection.close();
+
+	// Control: our SETUP declared it, so the peer that implements it broke it.
+	const logged = spyOn(console, "error").mockImplementation(() => void 0);
+	try {
+		const declaring = await acceptWith({});
+		await announce(declaring);
+		await declaring.pair.client.closed;
+		expect(logged).toHaveBeenCalled();
+	} finally {
+		logged.mockRestore();
+	}
+});

js/net/src/connection/extensions.ts

@@ -0,0 +1,27 @@
+import * as Ietf from "../ietf/index.ts";
+
+/**
+ * The moq-transport extensions a session offers in its SETUP, each on unless set to `false`.
+ * Turning one off connects as a peer that does not speak it. moq-lite carries both in its
+ * core, so this only changes moq-transport sessions.
+ */
+export interface Extensions {
+	/** The MoQ Auth extension: tokens presented and granted on their own stream (draft-17+). */
+	auth?: boolean;
+	/** The MoQ Solicit extension: the peer answers our SUBSCRIBE_NAMESPACE rather than announcing unasked. */
+	solicit?: boolean;
+}
+
+/** Every extension resolved to whether it is offered. */
+export type Offered = Required<Extensions>;
+
+/** Resolve each unset extension to offered. */
+export function offered(extensions?: Extensions): Offered {
+	return { auth: extensions?.auth ?? true, solicit: extensions?.solicit ?? true };
+}
+
+/** Write the options for the offered extensions into a SETUP. */
+export function intoSetup(params: Ietf.SetupOptions, extensions: Offered, version: Ietf.IetfVersion) {
+	if (extensions.solicit) Ietf.solicitIntoSetup(params);
+	if (extensions.auth) Ietf.Auth.intoSetup(params, version);
+}

js/net/src/connection/handshake.ts

@@ -2,6 +2,7 @@ import { StreamError } from "../error.ts";
 import { type Hop, randomHop } from "../hop.ts";
 import * as Ietf from "../ietf/index.ts";
 import { Reader, Stream, UnexpectedEnd, Writer } from "../stream.ts";
+import * as Extensions from "./extensions.ts";
 
 /**
  * Draft-17+ SETUP exchange. Each side opens a uni stream, writes its Setup
@@ -12,16 +13,17 @@ import { Reader, Stream, UnexpectedEnd, Writer } from "../stream.ts";
  * Returns the control stream, the uni streams that arrived before it (see
  * {@link receiveSetup}), plus what the peer's SETUP declared: whether it requires
  * solicitation, which decides whether we announce namespaces unprompted (see the MoQ Solicit
- * extension), its Hop ID (see the MoQ Cluster extension), and whether it offered MoQ Auth.
- * We declare all three ourselves on
- * every session: we send SUBSCRIBE_NAMESPACE for each prefix we want, so an unsolicited
- * advertisement can tell us nothing we won't have asked for, and a peer that knows our Hop
- * ID can withhold the advertisements that already flowed through us.
+ * extension), its Hop ID (see the MoQ Cluster extension), and whether MoQ Auth is negotiated.
+ * We declare our Hop ID on every session, and Solicit and Auth unless `extensions` declines
+ * them: we send SUBSCRIBE_NAMESPACE for each prefix we want, so an unsolicited advertisement
+ * can tell us nothing we won't have asked for, and a peer that knows our Hop ID can withhold
+ * the advertisements that already flowed through us.
  */
 export async function exchangeSetup(
 	transport: WebTransport,
 	version: Ietf.IetfVersion,
 	implementation: string,
+	extensions: Extensions.Offered,
 ): Promise<{
 	control: Stream;
 	early: Reader[];
@@ -33,9 +35,8 @@ export async function exchangeSetup(
 	const encoder = new TextEncoder();
 	const params = new Ietf.SetupOptions();
 	params.setBytes(Ietf.SetupOption.Implementation, encoder.encode(implementation));
-	Ietf.solicitIntoSetup(params);
+	Extensions.intoSetup(params, extensions, version);
 	Ietf.hiddenIntoSetup(params);
-	Ietf.Auth.intoSetup(params, version);
 
 	// One id per session, like the moq-lite connection: nothing in this process forwards
 	// between sessions, so there is nothing for a shared id to detect.
@@ -55,7 +56,8 @@ export async function exchangeSetup(
 		solicit: received.solicit,
 		hidden: received.hidden,
 		cluster: { self, peer: received.cluster },
-		auth: received.auth,
+		// Negotiated only when both sides offer it.
+		auth: received.auth && extensions.auth,
 	};
 }
 

js/net/src/connection/index.ts

@@ -14,6 +14,7 @@ export {
 	type WebTransportProps,
 } from "./connect.ts";
 export type { Established } from "./established.ts";
+export type { Extensions } from "./extensions.ts";
 export { Connection, type ConnectionProps } from "./pool.ts";
 export type { Probe, Stats } from "./stats.ts";
 export type { Transport } from "./transport.ts";

js/net/src/connection/pool.ts

@@ -20,6 +20,7 @@ import {
 	type WebTransportProps as WebTransportPropsType,
 } from "./connect.ts";
 import type { Established as EstablishedType } from "./established.ts";
+import type { Extensions as ExtensionsType } from "./extensions.ts";
 import type { GoawayProps, Redirect as RedirectType } from "./goaway.ts";
 import { Reload, type ReloadDelay, type ReloadStatus } from "./reload.ts";
 import type { Probe as ProbeType, Stats as StatsType } from "./stats.ts";
@@ -372,6 +373,8 @@ export namespace Connection {
 	export type CertificateHash = CertificateHashType;
 	/** An established one-shot session. */
 	export type Established = EstablishedType;
+	/** The moq-transport extensions a one-shot session offers. */
+	export type Extensions = ExtensionsType;
 }
 
 /** Throw if `props` cannot be honored, rather than silently dropping them. */