Repository navigation
quest: certificate credentials and a challenge proof for the mesh #8190
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -50,6 +50,12 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: | |
| process declares fresh. | ||
| - Addressing is announcement: each node publishes under `mesh/<id>/...`, and | ||
| reaching an ID is subscribing there. There is no separate directory. | ||
| - Certificates can stand in for the token (decided 2026-11-07, maintainer, | ||
| Kixel's planning): a downstream mesh that must admit and evict devices | ||
| with no internet issues long-lived certificates from its own signers, and | ||
| [certificate credentials](/quest/m3/mesh/cert-credentials.md) checks them | ||
| against a trust store it supplies. The coordinator's token stays the | ||
| default for `moq auth`. | ||
|
Comment on lines
+53
to
+58
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
| - The token is the binding: enrollment proves the device key, then the | ||
| coordinator issues a grant to publish `mesh/<id>/**` and subscribe | ||
| `mesh/**`, plus publish on its own [socket](/doc/concept/socket.md) | ||
|
|
@@ -97,6 +103,7 @@ the third, and survives a relay restart. | |
| - [Endpoint API](/quest/m3/mesh/endpoint.md) - an iroh-shaped `Endpoint` that connects to an endpoint ID and service and accepts byte streams | ||
| - [Mesh relay node](/quest/m3/mesh/node.md) - a relay node enrolls into a mesh, dials its relays, and admits only enrolled LAN peers | ||
| - [Mesh enrollment is bounded and revocation takes effect](/quest/m3/mesh/device-bounds.md) - a reusable key enrolls a bounded number of devices and a revoked device loses access within a bounded time | ||
| - [Certificate credentials](/quest/m3/mesh/cert-credentials.md) - a certificate chain and a proof signature stand in for a JWT, checked against a trust store the application swaps live | ||
| - [Address hints](/quest/m3/mesh/addr.md) - nodes publish their addresses on mesh tracks and dial each other directly where mDNS cannot find them | ||
| - [Sparse overlay](/quest/m3/mesh/overlay.md) - each node keeps about log N deterministic direct links, forwards for the rest, and falls back to relays across a partition | ||
| - [JS mesh enrollment client](/quest/m3/mesh/js-enroll.md) - `@moq/auth` enrolls and refreshes from JS like `moq_auth::mesh::Client` | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # [M] Certificate credentials | ||
|
|
||
| ## Goal | ||
|
|
||
| A client can present an X.509 certificate chain over its Ed25519 key in place | ||
| of a JWT: in the `jwt` query, as a moq-transport SETUP token, and on every | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The presentation list names |
||
| transport, browsers included. The credential is the chain plus a proof | ||
| signature over the relay's host name, the dialed path, and the current time, | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The proof binds "the relay's host name", but |
||
| so a captured chain alone admits nothing. `moq-auth` parses and verifies it | ||
|
Comment on lines
+7
to
+9
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
| against a trust store the embedding application supplies and swaps at | ||
| runtime: its anchors, and a check for whether a certificate is revoked. A | ||
| relay or node using that store refuses a chain that fails it, and closes | ||
| sessions it admitted earlier once their certificate is revoked or the anchors | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The eviction promise needs a re-check that is off by default: |
||
| change, at its next re-check. The application turns a verified chain into a | ||
| grant, the way in-process admissions already decide. `moq_auth::mesh::Client` | ||
| can present such a credential, and `@moq/auth` builds one from a | ||
| non-extractable WebCrypto Ed25519 key. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-07 (maintainer, Kixel's `/quest-plan`): a mesh whose devices | ||
| must admit and evict each other with no internet needs credentials that last | ||
| longer than a coordinator token and can be checked offline, so Kixel moved its | ||
| devices from coordinator-minted JWTs to 30-day certificates from the mesh's | ||
| own signers. Presenting the certificate as the token, rather than over mTLS, | ||
| gives one path that also crosses relays that accept only their own cluster's | ||
| client certificates, WebSocket fallbacks, and browsers, which cannot present | ||
| client certificates over WebTransport. The signer log, revocation set, and | ||
| their sync stay in Kixel; this quest is the generic format and hook. | ||
|
|
||
| - Verify chains with webpki. Name constraints work only on dNSName (webpki | ||
| rejects URI constraints and lacks directoryName), so document scopes | ||
| carried as DNS names. | ||
| - The trust store is a handle the application updates, not a callback per | ||
| connection. Re-check live sessions on the relay's existing `--revalidate` | ||
| cadence. | ||
| - The time-window proof comes first. Its replay window (a relay that saw a | ||
| credential could reuse it at the same host within the skew) closes with the | ||
| [challenge proof](/quest/m4/cert-challenge.md). Settle the skew and the | ||
| signed encoding before coding, and record them in `doc/bin/relay/auth.md`. | ||
| - Browsers: WebCrypto Ed25519 keys sign in current Chrome, Firefox, and | ||
| Safari; confirm it before relying on it, and fail loud where it is missing. | ||
| - Overlaps [moq-dev/moq#8149](https://github.com/moq-dev/moq/pull/8149)'s | ||
| bounded revocation for `moq auth`'s own mesh coordinator, which keeps | ||
| JWTs; this quest does not change that coordinator's tokens. | ||
|
|
||
| Tests: a valid chain admits; a revoked or unanchored one, a proof for another | ||
| host or path, and a stale proof are refused; a session admitted before its | ||
| certificate is revoked closes on the next re-check; swapping the anchors | ||
| applies without a restart; a JS client presents a credential from a WebCrypto | ||
| key and a Rust relay admits it. | ||
|
|
||
| Public API: new credential types in `moq-auth` and `@moq/auth`, and a trust | ||
| store handle on the relay. Wire: a new credential form wherever a JWT is | ||
| accepted. | ||
|
|
||
| ## Required | ||
|
|
||
| - [Mesh relay node](/quest/m3/mesh/node.md) - the node that checks these credentials for its LAN peers | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -23,6 +23,10 @@ CLI verbs, service install, and UI moved to Kixel. Carried over from it: | |
| `doc/bin/relay/auth.md#mesh-enrollment`. Pass the hostname as the default | ||
| name. | ||
| - Nothing is served unless the embedding application names it. | ||
| - A LAN peer proves its enrollment with the coordinator token, or with a | ||
| [certificate credential](/quest/m3/mesh/cert-credentials.md) when the | ||
| embedding application supplies a trust store (decided 2026-11-07, | ||
| maintainer). | ||
|
Comment on lines
+26
to
+29
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
|
|
||
| Tests in network namespaces: two relay nodes enroll through `moq auth`, take | ||
| the LAN link when they share a segment and the relay path otherwise, refuse | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # [S] Challenge proof for certificate credentials | ||
|
|
||
| ## Goal | ||
|
|
||
| A relay can ask a client presenting a [certificate credential](/quest/m3/mesh/cert-credentials.md) | ||
| to sign a fresh nonce instead of a timestamp, so a credential replayed within | ||
| the time window admits nothing. Clients that support it answer the | ||
| challenge; a relay configured to require it refuses time-window proofs. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-07 (maintainer, Kixel's `/quest-plan`: "plan the challenge, | ||
| but do the simple thing first"): certificate credentials ship with a | ||
| time-window proof, and this closes its replay window later. Settle where the | ||
| nonce rides (SETUP parameters on moq-transport and moq-lite, and what a | ||
| WebSocket or HTTP admission does) and what one extra round trip costs a | ||
| connect, measured, before coding. | ||
|
|
||
| Tests: a replayed time-window proof is refused when the relay requires the | ||
| challenge; a client signs the nonce and is admitted; a mismatched nonce is | ||
| refused. | ||
|
|
||
| Public API: a challenge option on the relay and the clients. Wire: a nonce | ||
| exchanged during setup. | ||
|
|
||
| ## Required | ||
|
|
||
| - [Certificate credentials](/quest/m3/mesh/cert-credentials.md) - the credential this hardens |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Certificates can now stand in for the token, but the bullet below still says "Membership is the coordinator's token only; a Tailnet-Lock analog was declined" and "Relays need no new check" (lines 59-66). Amend that decision here so the epic states one membership rule, and say which check a relay gains; the Non-goals line 22 ("a member list that a compromised coordinator cannot extend") may also need narrowing for Kixel's own signers.