Expand description
Browser-side RFC 8693 token-exchange (#1314) for the wasm client. Pure
parsing helpers compile on all targets (unit-tested on native); the browser
fetch glue is wasm32-only.
Browser-side RFC 8693 token-exchange (#1314) for the wasm client.
The browser VfsShell exchanges an atproto/external JWT for a short-lived
hyprstream at+jwt Bearer, then presents that Bearer as the default JWT on
every RPC. This module holds:
- Pure helpers (
exchange_form_body,parse_exchange_response,subject_from_access_token) — target-agnostic, unit-tested on native. fetch_exchange_token— the browserfetchglue,wasm32-only (it usesweb_sys), mirroringbrowser_provisioning::fetch_browser_provisioning.
§Authority note
subject_from_access_token decodes the at+jwt sub without signature
verification. This is client-side bookkeeping only: it derives a display
Subject from the freshly-exchanged Bearer. The token’s authority is never
trusted from this decode — the server re-verifies the bearer on every RPC
(require_bearer_token / validate_oauth_access_token). The exchange
response does not echo sub, and the mint stamps sub = verified.sub
(token_exchange.rs), so the client decodes it from the minted token rather
than extending the server response.
Structs§
- Exchanged
Token - A successfully exchanged short-lived access token (#1314 / #1425).
- Session
Context - Server-derived browser viewer authority.
Enums§
- Nonce
Outcome - Outcome of one token-exchange fetch attempt, decided from the response’s
status/body/headers (RFC 9449 §8 nonce lifecycle). Pure / native-testable:
the
wasm32glue calls this after everyfetchto decide whether to return, retry with a fresh nonce, or fail (#1425 r1 P1#4). - Session
Kind - Token
Type - The OAuth
token_typeof anExchangedToken.
Constants§
- BROWSER_
PUBLIC_ CLIENT_ ID - The well-known public
client_idthe browser VfsShell presents at the RFC 8693 token-exchange endpoint (#1425). - GRANT_
TYPE - The RFC 8693 token-exchange grant type.
- ISSUED_
TOKEN_ TYPE - Issued-token type the #1314 endpoint always mints (at+jwt / access_token).
- SESSION_
EXCHANGE_ PATH - Browser session exchange route on the hyprstream OAuth origin.
- WHOAMI_
PATH - Server-derived viewer context route on the hyprstream OAuth origin.
Functions§
- assemble_
dpop_ proof - Assemble a complete DPoP proof JWT from the signing input and signature.
- classify_
exchange_ error_ code - Classify a
fetch_exchange_token(orverify_sender_bound_token) failure message into a stable error code forhyprstream-rpc-std::browser_session. - decide_
nonce_ outcome - Decide the next action for a token-exchange fetch attempt.
- dpop_
ath - Compute the DPoP
athvalue:base64url(SHA-256(access_token)). - ed25519_
dpop_ jkt - Compute the RFC 7638 JWK thumbprint (
cnf.jkt) for an Ed25519 public key. - ed25519_
dpop_ signing_ input - Build the RFC 9449 DPoP JWT signing input (
header.payload) for an Ed25519 key. The caller signssigning_inputwith the private key and assembles the proof viaassemble_dpop_proof. - exchange_
form_ body - Build the
application/x-www-form-urlencodedbody for an RFC 8693 exchange. - expires_
at_ ms - Compute the absolute expiry (
Date.now()-domain milliseconds) for a token whoseexpires_in(seconds, RFC 6749 §5.1) isexpires_in_secsrelative tonow_ms. A non-positiveexpires_inclamps tonow_ms(already expired) rather than underflowing. - generate_
dpop_ jti - Generate a fresh, random DPoP
jti(RFC 9449 requires a unique value per proof so the AS can detect replay). Pure / native-testable so JTI freshness is a plain unit test rather than something only exercisable inside thewasm32-only fetch glue (#1425 r1 P1#4). - is_
use_ dpop_ nonce_ response - Check whether an HTTP error response body is a
use_dpop_nonceerror (RFC 9449 §8). The browser retries with a fresh proof carrying theDPoP-Nonceresponse header. - parse_
exchange_ response - Parse the JSON body of a successful
POST /oauth/tokenexchange. - parse_
session_ context - Parse the exact session-exchange / whoami JSON response.
- subject_
from_ access_ token - Decode the
subclaim from an exchanged at+jwt and build aSubject. - verify_
sender_ bound_ token - Verify an
ExchangedTokenis actually sender-bound todpop_pubkeybefore the caller (the browser sender-bound exchange) trusts it (#1425 r2 P2).