Skip to content

feat(relay)!: an attached token arrives as a token, not in the query - #8923

Merged
kixelated merged 4 commits into
mainfrom
quest/m2/auth-attach-token
Nov 17, 2026
Merged

kixelated merged 4 commits into
mainfrom
quest/m2/auth-attach-token

Conversation

@kixelated

@kixelated kixelated commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m2/auth-attach-token.md.

Summary

A credential a client attaches in band now reaches the auth server as Request.token (kind 0, the bytes as sent) and query stays exactly as dialed. The relay no longer knows the name jwt and no longer needs an attached token to be UTF-8.

  • Relay: attach sets token and leaves query alone. with_jwt and the UTF-8 refusal are deleted. Public rules refuse a request with a token and no longer read ?jwt= (see Decisions).
  • moq auth serve: an event with auth (attach, and that credential's revalidate and end) reads its JWT from token, so the dialed query's jwt neither conflicts with it nor stands in for it. Temporary migration: when such an event has no token, it is a previous-release relay's, which put the attached JWT in query, so that jwt is read instead. An event with auth and no credential at all is refused as malformed, never decided on the anonymous rules.
  • Docs and contracts: request.rs, js/auth/src/contract.ts, doc/bin/relay/auth.md.
  • Clients keep ?jwt= as the fallback before lite-07, unchanged. js/net is untouched, so no overlap with feat(net): a JS Connection reports the peer's verdict on its tokens #8902.

Impact

Rust and JS public API: doc comments only. Wire: none (no just test interop --all).

HTTP contract: breaking for attach. An auth server that read the attached credential from query jwt now sees the connection's first credential there and the attached one in token.

Migration for auth servers: for an event with auth set (attach, revalidate, end), read the credential from token and ignore query's credential. moq auth serve does, and for the rollout also still reads a previous-release relay's query shape (marked temporary in serve.rs; delete at the next version cut), so it is safe to deploy before the relays. An old server given a new relay's attach verifies the stale dialed query, so update auth servers first.

Downstream, checked at moq.pro 9373cdfb3: rs/edge/src/auth/mod.rs reads the credential only from request.query (query_jwt, :393), never request.token: End forgets the query credential (:1312-1317), Attach and Revalidate decide on the query's jwt (:1331, :1061, limits.rs:179/383/419). So moq.pro must read token before it meets a relay with this change; plain ?jwt= dials are unaffected. Kixel's src/mesh.ts:557 reads a credential query parameter, and its client has no attach use today. See Follow-ups.

Validation

  • quest gate cargo test -p moq-auth -p moq-relay passes, and just check.
  • Real surface: in_band_tokens_widen_and_withdraw_live_prefixes (relay over real QUIC and upgraded WebSocket against a scripted HTTP auth server) now asserts the attach request has query == "jwt=token" as dialed and token == {kind: 0, value: "replacement"}.
  • New unit tests: a binary (non-UTF-8, &/= bytes) token reaches the decider unchanged and the dialed query is untouched (a_binary_token_is_attached_unchanged); moq auth serve renews a session whose dialed query holds an expired jwt, on attach and revalidate, and refuses an attach without a token (an_attached_credential_is_read_from_its_token); the existing token-cap test now attaches through token.

Decisions

Taken on my recommendation while the maintainer was away; the maintainer confirmed 1, 2, 4 and 3 and kept the follow-up on 2026-11-16 (/quest-run).

  1. Public rules (--auth-public) no longer refuse a request whose query has a jwt; they refuse only a token. The quest says the relay holds no parameter name, and public rules have no server to ask. Cost: a pre-lite-07 client that dials a public relay with ?jwt= is now admitted on the public grant instead of refused. Alternative: keep the jwt read in presents_token, which keeps the name in the relay.
  2. moq auth serve keys on auth being set, not on event == attach, so revalidate and end of an attached credential read the same token (the relay replays the attach request for them). An event with auth and no credential is MalformedToken.
  3. (Review finding) A previous-release relay's attach and revalidate (auth set, no token, the credential in query) is still read from query, as a temporary migration, because moq.pro runs the newest and previous relay releases side by side. Alternative: refuse that shape and break in-band renewal on old relays during the rollout. Taken on the AGENTS.md rule; undo by returning MalformedToken for (Some, None) in jwt().
  4. The attached token's kind is 0, as the quest says.

Follow-ups

Caused by

No single PR: the jwt rewrite is as old as in-band attach.

Models

Size: S
Implementer: Claude Code, claude-sonnet-5-5, high effort (arm B)

(Written by Claude Sonnet 5.5 with high effort)

Review

Rewritten by quest review after each round.

  • Head: 5287e4e

  • Base: origin/main at 73d65ed

  • Risk: high, Credential selection affects the authentication boundary for relay users; an incorrect grant could expose data, which reverting the change cannot undo.

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1e468-53f4-7831-8bd9-e2b89e0928ec, round 2

  • Score: 9/10, No actionable defects found in the incremental changes: the temporary fallback supports previous-release relay attachments while preserving token precedence, with execution checks intentionally not run.

  • Raised the risk to high: Credential selection affects the authentication boundary for relay users; an incorrect grant could expose data, which reverting the change cannot undo.

  • Rounds: 2; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 2 commits November 16, 2026 04:34
An in-band credential now rides Request.token (kind 0, any bytes) on attach and
leaves query as dialed. The relay drops with_jwt, the UTF-8 refusal, and the
query jwt check in its public rules; moq auth serve reads an event with auth
from its token alone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title An attached token arrives as a token, not in the query feat(relay)!: an attached token arrives as a token, not in the query Nov 16, 2026
@kixelated
kixelated marked this pull request as ready for review November 16, 2026 12:51
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The relay now sends attached credentials in the token field without changing the dialed query. The auth server uses that token for attachment authorization and supports a query-JWT fallback when an older relay omits the token. Public-rule admission checks for a request token rather than a JWT query parameter. Documentation and tests describe and verify these behaviors, including binary token bytes and compatibility cases.

Merge Risk: Low · up to 5287e

Attached credentials now arrive in the request's token field and the dialed query is left unchanged. This is a breaking change for external auth servers that read the attached credential from the query; the downstream handler must be updated before it is paired with a relay carrying this change. Plain ?jwt= dials are unaffected, and the built-in auth server keeps a temporary fallback. The change is mergeable with awareness of the rollout ordering.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: an attached token now arrives in the token field instead of the query. The changeset moves in-band attached credentials to Request.token and leaves query unchanged, an…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description is specific and related to the changeset. It states that attached credentials now reach the auth server as Request.token, that query stays as dialed, and that the relay drops the jwt q…
Full details: Title check

Explanation

The title names the main change: an attached token now arrives in the token field instead of the query. The changeset moves in-band attached credentials to Request.token and leaves query unchanged, and the title is marked as a breaking change with the feat(relay) scope. The title is specific and accurate, though its wording is slightly terse.

Full details: Description check

Explanation

The description is specific and related to the changeset. It states that attached credentials now reach the auth server as Request.token, that query stays as dialed, and that the relay drops the jwt query rewrite and UTF-8 refusal. It also covers the moq auth serve token selection and temporary previous-release fallback, the breaking attach contract change, validation, and the downstream moq.pro impact. This matches the summary of changes in request.rs, serve.rs, auth.rs, refresh.rs, the contract docs, and the deleted quest document.

Finishing Touches

Simplify code

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 40c2bb29-5a41-4e40-adeb-0967accb72e4
Commits

Reviewing files that changed from the base of the PR and between d8bd7fb and 5287e4e.

Files selected for processing: 11

  • doc/bin/relay/auth.md
  • js/auth/src/contract.ts
  • quest/m2/README.md
  • quest/m2/auth-attach-downstream.md
  • quest/m2/auth-attach-token.md
  • quest/m2/auth-grants.md
  • rs/moq-auth/src/request.rs
  • rs/moq-auth/src/serve.rs
  • rs/moq-relay/src/auth.rs
  • rs/moq-relay/src/auth/refresh.rs
  • rs/moq-relay/tests/integration/auth_lifetime.rs
Files with no reviewable changes: 2

  • quest/m2/auth-attach-token.md
  • quest/m2/auth-grants.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

moq auth serve mishandles both of a previous-release relay's requests for an attached credential. It refuses the attach. For a revalidate it ignores the credential and decides on the anonymous rules. During a rollout with mixed relay versions, that breaks in-band renewal on the old relays.

Reviewed changes

I reviewed the relay, moq auth serve, the contract docs and the tests that move an attached credential from a rewritten query into Request.token.

  • Relay attach: refresh.rs now clones the connection's request and sets token to {kind: 0, bytes} without touching query. with_jwt and the UTF-8 refusal are removed. Revalidate and end replay the same facts, so they carry the token too.
  • Public rules: presents_token is removed, so public rules refuse a request only when it has a SETUP token. A ?jwt= query is now admitted on the public grant, as Decision 1 says.
  • moq auth serve: jwt() ignores the query whenever auth is set. answer() refuses an Attach that has no token.
  • Docs and contracts: the token field docs in request.rs, contract.ts and auth.md now describe the attached credential.
  • Tests: the refresh tests assert that the dialed query passes through unchanged. A binary token now reaches the decider unchanged, and the integration test checks the shape of the attach request.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread rs/moq-auth/src/serve.rs Resolved

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed commit: 9f99184af5f1181c6796ea7b748215edbd2beb0a.

I confirmed the mixed-relay rollout blocker. “Auth server first” is not a safe rollout with either server as written: the new server refuses old attaches, and an old query-only handler can authorize a new attach as the dial-time identity. For attach and attached revalidation, deploy a dual reader first: if token is present, validate it and never fall back to query on an invalid token; if absent, accept only the old attached-query shape with a valid credential, never anonymous. Cover both relay generations in the same integration test, then move relay senders.

Keeping the original query opaque and delivering raw token bytes is a good separation. Independently, the public-rule change admits clients presenting a query-only JWT on the anonymous grant; it does not bestow the JWT's grants, but it is a deliberate admission-policy change rather than a necessary part of moving the attachment. I'd keep that decision separate from the compatibility fix.

Static review only; I did not run auth tests or check live deployments. COMMENT only, not approval.

kixelated and others added 2 commits November 16, 2026 17:56
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… from the query

A relay before this change rewrote an attached credential into the query's jwt
and cleared the token. Keep reading that shape on attach and revalidate as a
marked temporary migration, and refuse an event with auth that carries no
credential rather than deciding it on the anonymous rules.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed commit: 5287e4ecd9f76b3ab9bcb68feb0ec88145368cfc.

The built-in auth server now handles both relay generations for attach and revalidate. The current relay sends token on attach, and the server never falls back to the query when that field is present. I’d add a negative fixture with a valid dial JWT and an invalid or expired attached token to pin that rule.

The built-in fix does not make a query-only external auth handler safe for the new sender. Update and verify those handlers before rolling out the relay, then remove the temporary missing-token fallback after the last old sender is gone. Until then, a missing token plus a query JWT is indistinguishable from the old format. Static review only; no tests or deploys run.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The mixed-relay concern from the prior review is fixed.

Reviewed changes

This review covers the changes since the prior Pullfrog review at 9f99184. The merge of main brought in only quest README churn.

  • Temporary migration in jwt(): when a request has auth but no token, jwt() now reads the query's jwt, which is the shape a previous-release relay sends. It refuses the request as MalformedToken when there is no query jwt either. When token is present, the query is still ignored, so a bad attached token never falls back to the dial credential.
  • answer() guard: the Attach guard checks only for a missing auth again. decide_root and decide call jwt() before reaching the mTLS or public rules, so an attachment with no credential is refused on both attach and revalidate rather than decided anonymously.
  • Tests: added a_previous_relays_attachment_is_read_from_its_query for attach and revalidate, plus checks that a bare attachment is refused.
  • Docs and quest: auth.md mentions the temporary query read. auth-attach-downstream.md records that moq.pro's edge reads only query and has to be updated before it meets a relay with this change.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit da1c9c9 Nov 17, 2026
8 checks passed
@kixelated
kixelated deleted the quest/m2/auth-attach-token branch November 17, 2026 07:20
kixelated added a commit that referenced this pull request Nov 18, 2026
The publish side buffered what a widened grant newly showed after its
flush, then rested with it unsent: the grant's wakeup was spent.

Also repairs two bench fixtures: moq-lite-07's Announce Stream holds a
uni stream grant beside the delivery-credit groups, and an attached
token arrives as the request's token since #8923.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant