docs: add AuthHook trait design proposal#169
Conversation
Design sketch for a pluggable AuthHook trait to support intra-scope authorization in the relay. Covers the trait surface, supporting types, invocation points, and reference implementation sketches for PrivacyPass and C4M (CAT for MoQ) auth schemes. Intended as a shared reference for contributors working on PP and C4M implementations in parallel.
englishm-cloudflare
force-pushed
the
docs/authhook-design
branch
from
a18a789 to
4f48888
Compare
thibmeu
left a comment
thibmeu
left a comment
There was a problem hiding this comment.
overall seems to be the right shape to experiment with
|
|
||
| ## DenyReason → wire codes | ||
|
|
||
| On the SETUP path, any `Verdict::Deny(_)` produces session termination with `UNAUTHORIZED (0x2)`. The reason phrase carries the deny reason for diagnostic purposes. |
There was a problem hiding this comment.
This might be limiting for Privacy Pass integration in MoQ, which needs to reply with a challenge. See Section 3.4.5.1 of privacy-pass-moq-auth
Similar to C4M which has some of its own code, I suspect different authentication method would have difjferent Deny Reason.
| /// A fully-resolved AUTHORIZATION TOKEN parameter. Alias bookkeeping is | ||
| /// handled by the relay's transport layer; the hook always sees Type+Value | ||
| /// pairs, never raw alias directives. | ||
| pub struct AuthBlob { | ||
| /// Token type from the IANA "MOQT Auth Token Type" registry. | ||
| pub token_type: u64, | ||
| pub token_value: Bytes, | ||
| } |
There was a problem hiding this comment.
probably worth mentioning AUTHORIZATION TOKEN parameter directly.
Specifically, there are possible alias
Token {
Alias Type (vi64),
[Token Alias (vi64),]
[Token Type (vi64),]
[Token Value (..)]
}
|
|
||
| 1. Parsing AUTHORIZATION TOKEN parameters from SETUP and per-message KVPs. | ||
| 2. Resolving aliases (REGISTER → store, USE_ALIAS → look up, DELETE → retire) using an `AuthTokenCache`. | ||
| 3. Surfacing the resolved set as `Vec<AuthBlob>` — `(token_type, token_value)` pairs — to the hook. |
There was a problem hiding this comment.
as mentioned before: need some issue in moqt
|
|
||
| The relay's request pipeline, with `AuthHook` invocation points: | ||
|
|
||
| | Stage | Hook call | On `Deny` | |
There was a problem hiding this comment.
leaving here because I think we need to dive before having an answer: this is a place where order might matters: decode before scope, or even scope before knowing the right challenge to return (think of two distinct namespace that use two distinct issuers).
| Publish { namespace: &'a TrackNamespace, track: &'a str }, | ||
| Subscribe { namespace: &'a TrackNamespace, track: &'a str }, | ||
| SubscribeNamespace { prefix: &'a TrackNamespace }, | ||
| Fetch { namespace: &'a TrackNamespace, track: &'a str }, | ||
| TrackStatus { namespace: &'a TrackNamespace, track: &'a str }, |
There was a problem hiding this comment.
question: is &str the right interface? privacy-pass-moq-auth uses bytes, which I think avoid the whole UTF-8/normalisation question.
I would suggest &[u8] or something similar
|
|
||
| - **No request mutation.** The hook returns allow or deny; it cannot rewrite namespaces or substitute auth scopes. | ||
| - **No outbound credential management.** If the relay needs to present credentials to an upstream origin, that is a separate concern (a future `UpstreamAuthProvider` trait or similar). `AuthHook` is strictly for incoming authorization. | ||
| - **No relay-side verdict cache.** Implementations that want per-session caching (e.g., parse a token once at SETUP and apply cached claims on subsequent operations) manage that state internally. |
There was a problem hiding this comment.
I like that design choice. Beyond the fact that everyone has different requirements, for privacy pass it's actually part of the privacy model
|
|
||
| `AuthHook` is called at two points in the relay's request pipeline: | ||
|
|
||
| 1. **At session establishment** — after AUTHORIZATION TOKEN parameters from CLIENT_SETUP have been decoded. Used to validate session-level credentials. |
There was a problem hiding this comment.
probably worth using SETUP consistently instead of CLIENT_SETUP given draft -18 collapses them (despite still being defined)
|
|
||
| ## Forward-portability across MoQT draft versions | ||
|
|
||
| The initial PP and C4M PoC implementations will target **draft-16**, which is the version currently deployed in the reference relay. The next planned implementation target after the PoCs is **draft-18** (draft-17 will be skipped). Supporting multiple MoQT draft versions simultaneously in the relay is not a current goal, but it is something we expect to revisit after draft-18 lands. |
There was a problem hiding this comment.
asgree with -16 as a target. there is some discrepencies in the wording that importsd some wording from draft 18 though: SETUP/CLIENT_SETUP/SERVER_SETUP for isntance. The assumption there is already a MOQT Auth Token Type registry, possibly others
3 participants
Design sketch for a pluggable AuthHook trait to support intra-scope
authorization in the relay. Covers the trait surface, supporting types,
invocation points, and reference implementation sketches for PrivacyPass
and C4M (CAT for MoQ) auth schemes.
Intended as a shared reference for contributors working on PP and C4M
implementations in parallel.