amethyst/nestsClient/specs/EGG-02.md

EGG-02: Auth & WebTransport handshake

status: draft requires: EGG-01, NIP-98 category: required

Summary

To open the audio plane (EGG-03), a peer first proves identity to a per-room auth sidecar (moq-auth) using a NIP-98 HTTP signature, receives a short-lived JWT, then opens a WebTransport session against the moq-relay carrying the JWT in the URL.

Two separate URLs are involved: the service tag from EGG-01 is the auth sidecar; the endpoint tag is the relay.

Wire format

Step 1 — token request

POST <service>/auth
Authorization: Nostr <base64(NIP-98 kind:27235 event JSON)>
Content-Type:  application/json; charset=utf-8

{ "namespace": "nests/<kind>:<host_pubkey_hex>:<room_d>",
  "publish":   <boolean> }

<kind> is 30312 for nests audio rooms (EGG-01).

The <service> URL is the EGG-01 service tag value with any trailing / stripped, then /auth appended literally.

The body is a single-line UTF-8 JSON object — the server hashes the exact bytes sent to compare against NIP-98's payload tag, so producers MUST NOT pretty-print or re-order keys after signing.

The <host_pubkey_hex> is the host's pubkey, lowercase hex. The <room_d> is the EGG-01 d tag (which by EGG-01 rule 9 cannot contain :, so the namespace is unambiguous without escaping).

NIP-98 event shape

The signed kind 27235 event MUST carry exactly these tags (NIP-98 §1):

{
  "kind": 27235,
  "pubkey": "<requester pubkey hex>",
  "created_at": <unix seconds>,
  "tags": [
    ["u",       "<service>/auth"],   // exact request URL, scheme included
    ["method",  "POST"],
    ["payload", "<sha256 of request body, lowercase hex>"]
  ],
  "content": "",
  "id":  "<...>",
  "sig": "<...>"
}

The event JSON is then serialized (NIP-01 canonical form), encoded as RFC 4648 standard Base64 (NOT base64url; pad with =), prefixed with Nostr (literal, including the trailing space), and placed in the Authorization header.

Step 2 — token response

HTTP/1.1 200 OK
Content-Type: application/json

{ "token": "<jwt>" }

The JWT carries (at minimum):

claim	meaning
root	The exact namespace echoed back. Authorisation is scoped here.
get	Read-allowed sub-paths; for nests this is [""] (any).
put	Publish-allowed sub-paths. For listeners: []. For speakers: [<own pubkey hex>].
iat	Unix seconds; issuance.
exp	Unix seconds; expiry. MUST be iat + 600 for nests today.

JWT signing

The JWT MUST be signed with alg: "ES256" (ECDSA on the NIST P-256 curve, RFC 7518 §3.4). The auth sidecar MUST publish its public verification keys as a JWKS at:

GET <service>/.well-known/jwks.json

The response is an application/json body shaped per RFC 7517:

{
  "keys": [
    {
      "kty": "EC", "crv": "P-256", "alg": "ES256",
      "use": "sig", "kid": "<key id>",
      "x": "<base64url x>", "y": "<base64url y>"
    }
  ]
}

The relay (EGG-03 endpoint) MUST verify inbound JWTs against this JWKS. Relays SHOULD cache the JWKS for at most 5 minutes so a key rotation propagates without requiring a relay restart. A relay that cannot reach the JWKS endpoint MUST refuse new sessions rather than fall through to "trust the unverified token".

Step 3 — WebTransport CONNECT

:method  = CONNECT
:protocol = webtransport
:scheme  = https
:authority = <host:port from `endpoint`>
:path    = /<namespace>?jwt=<token>

The relay reads the JWT from the ?jwt= query string. No Authorization header is used at this step.

Behavior

1. Listening peers MUST request publish: false. Speaking peers MUST request publish: true AND the JWT's put claim MUST list the speaker's own pubkey hex.
2. The auth sidecar's TLS certificate MUST be a publicly-trusted chain. The relay's TLS chain MAY be self-signed in development; production deployments MUST use a public chain.
3. The auth sidecar SHOULD reject any request whose NIP-98 created_at is more than 60 s in the past or future.
4. The JWT lifetime is fixed at 600 s. There is no refresh endpoint. A client that needs a longer session MUST mint a fresh token and open a new WebTransport session before the old token expires; see the deployment-side commentary in nestsClient/plans/.
5. The relay MUST close the WebTransport session within 30 s of exp. A peer receiving an unexpected close MUST be prepared to mint a fresh token and reconnect.
6. The relay MUST NOT trust the WebTransport authority for authorisation — only the JWT's root claim. A token issued for namespace A MUST NOT be accepted on a session opened against namespace B.
7. A peer MUST NOT log the JWT or include it in error reports. The token is a bearer credential.

Error taxonomy

The auth sidecar MUST use the following HTTP status codes for POST /auth. Bodies are application/json and follow the shape { "error": "<machine slug>", "reason": "<human string>" }. Receivers MAY ignore reason but MUST surface error to user-facing error toasts.

status	error slug	when
200	—	success; body is { "token": "<jwt>" }
400	bad_request	malformed JSON body, missing namespace, unknown content-type
400	bad_namespace	namespace does not match nests/<kind>:<hexpubkey>:<d>
401	bad_nip98	Authorization header missing, malformed, or id/sig invalid
401	wrong_url	NIP-98 u tag does not match the actual request URL
401	wrong_method	NIP-98 method tag is not POST
401	wrong_payload	NIP-98 payload tag does not match sha256 of the body bytes
401	stale	NIP-98 created_at outside the ±60 s tolerance
403	room_closed	room status is closed (EGG-01) or planned (EGG-08)
403	not_invited	room status is private and requester is not on the allowlist
403	publish_forbidden	publish: true requested but caller is not a speaker per EGG-07
410	unknown_room	no kind:30312 known to the sidecar for (host, d)
429	rate_limited	per-pubkey or per-IP rate limit; Retry-After header SHOULD be set
5xx	internal	sidecar internal error

Receivers MUST treat unknown 4xx slugs as "fatal, do not retry" and unknown 5xx slugs as "transient, retry with exponential backoff".

The relay (EGG-03 endpoint) signals authorization failures through WebTransport CONNECT response codes, NOT through the auth-sidecar table:

WT status	meaning
200	session established
401	JWT signature invalid, expired, or fails the JWKS check
403	JWT root does not match the path namespace, or put claim missing for a publishing peer
404	path namespace unknown to the relay

Example

> POST https://moq.nostrnests.com/auth
> Authorization: Nostr eyJ...kind27235...
> Content-Type: application/json
>
> {"namespace":"nests/30312:abchost:office-hours-2026-04","publish":false}

< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {"token":"eyJhbGc..."}

> CONNECT :path=/nests/30312:abchost:office-hours-2026-04?jwt=eyJhbGc...
< 200 OK   (WebTransport session established)

Compatibility

EGG-03 (audio plane) operates inside the WebTransport session this EGG opens. EGG-12 (catalog) shares the same session.