Expand description
DYNAUTH-12: tokens a service signs for the peers it forwards calls to. DYNAUTH-12 (D3, TM-4) · peer tokens: what a service signs for the peer a call is forwarded to, so the peer can check what it is told rather than believe who told it.
A token is a compact JWS (RFC 7515) of a JWT (RFC 7519), signed EdDSA
(Ed25519, RFC 8037), header {"alg":"EdDSA","typ":"plexus-peer+jwt","kid"}:
| claim | what |
|---|---|
iss | the issuing service’s key, key:<hex> |
sub | the original caller (the first hop’s admitted principal) |
act | the actor chain, nearest first, nested as RFC 8693 §4.1 nests it |
aud | exactly one peer: its key (key:<hex>), or pipe:<name> for a child on the issuer’s own pipe |
scope | space-separated grant@scope entries: the caller’s reach ∩ the peer’s needs ∩ consent |
cnf.jkt | the RFC 7638 thumbprint of the key that presents it (RFC 7800, RFC 9449 §6): the peer’s own for a token the service forwards; the presenter’s for an exchanged one (KEEL-19); absent for a pipe |
call, method | the forwarded call’s id and the method it names |
jti, iat, exp | unique; exp − iat ≤ 60 s |
Verifying (Verifier): alg is pinned to EdDSA (never read from the
token to choose an algorithm, RFC 8725 §3.1), typ must be
plexus-peer+jwt (§3.11), kid must name a key the verifier trusts (a
JWKS it was given or fetched, dyn.jwks), the signature is checked with
verify_strict, aud must be the verifier’s own, iat/exp within
±30 s of now and exp − iat ≤ 60 s, and a jti seen before is refused
until its exp (a replay cache bounded by 60 s × the call rate).
Proof of possession (prove, check_proof): whoever presents a
token bound to a key (cnf.jkt) — a remote peer calling its service back
under the call the token was minted for — signs a proof with that key:
a compact JWS, header {"alg":"EdDSA","typ":"plexus-pop+jwt","jwk"},
claims {ath, jti, method, call, iat} (ath: base64url sha256 of the
token, as DPoP’s, RFC 9449 §4.2). The proof’s key must be the token’s
cnf.jkt, its method and call the ones it is presented for, its
iat within ±30 s, its jti new. A peer on its issuer’s own pipe needs
no proof (D3: the pipe is the issuer’s alone). KEEL-19: the other way, a
service sends each forwarded hop with its own proof
(TokenIssuer::prove_forward, by the key that signed the token), and
a verifying child takes the hop only with it.
Exchange (TokenIssuer::exchange, RFC 8693 semantics): a token
presented for an onward call becomes one for the next peer — the same
sub, act extended by the presenter, aud the next peer, and a scope
that is the presented one’s or narrower, never wider (narrow).
KEEL-19: as a method (TokenIssuer::exchange_decided) it is the
service’s decision whether the presenter may reach that peer at all; the
token is bound to the presenter’s key (cnf), so the next peer takes it
only with the presenter’s proof; and a subject token is exchanged once
per (jti, audience, method).
Audit (DYNAUTH-7, TM-7): every mint and exchange writes one
AuditRecord — iss, sub, the actor chain, aud, scope, call, jti, exp,
method — as a tracing event on target plexus::audit and to the
issuer’s TokenAudit sink. Never the token, never a proof.
Structs§
- Actor
- One actor of the chain (RFC 8693 §4.1), the prior ones nested.
- Audit
Record - One audit record (TM-7): who acted through whom, for what. Never the token, a signature or a proof.
- Cnf
- The key a token is bound to (RFC 7800
cnf, RFC 9449jkt). - Exchange
Refused - KEEL-19: one refused exchange (TM-7): who presented what, for whom, and why it was refused. Never the token, a signature or a proof.
- Expect
- What a token must also say to be taken for this presentation.
- Jwk
- A public key as a JWK (RFC 8037:
ktyOKP,crvEd25519). - Jwks
- A JWK Set (RFC 7517 §5): what
dyn.jwksanswers. - Mint
Request - What one forwarded call’s token is minted from.
- Onward
- KEEL-19: what a service decided an exchange may give — the audience (its name and the key it proved) and the scope of the token for it.
- Peer
Claims - A peer token’s claims.
- PeerKey
- An Ed25519 key with its id (
key:<hex>): a service’s signing key, or a peer’s own.Debugnever shows the seed. - Proof
Cache - The proofs a presenter’s side has seen, each once (by its
jti, kept for twice the skew). - Token
Issuer - A service’s token issuer: its signing key (rotatable, the old one kept in the JWKS for one token lifetime and the skew), the lifetime it mints, and the audit sink.
- Verifier
- Checks tokens addressed to one audience, from the issuers it trusts,
each
jtionce.
Enums§
- Audit
Kind - What was done with a token.
- Exchange
Refusal - KEEL-19: why an exchange was refused, as a word.
- Token
Error - Why a token or a proof is refused. Says what, never the token.
Constants§
- ALG
- The one algorithm: EdDSA over Ed25519 (RFC 8037).
- EXCHANGE
- The method a proof of possession names to exchange a token
(
TokenIssuer::exchange), under the token’s owncall. - JWT_
TOKEN_ TYPE - RFC 8693’s identifier of the token type issued.
- KEY_
PROOF_ CONTEXT - The context a peer’s key proof at
_infois signed over (domain separation: no other signature can be passed off as one). KEEL-19: v2 binds the proof to its asker (a v1 proof is refused). - MAX_
LIFETIME - A token lives at most this long (
exp − iat), D3. - PROOF_
TYP - The
typof a proof of possession. - SKEW
- How far apart two clocks may be.
- TOKEN_
TYP - The
typof a peer token (RFC 8725 §3.11: explicit typing).
Traits§
- Token
Audit - Where audit records go besides
tracing(PRIVACY-1’s sink, when it is).
Functions§
- check_
key_ proof Deprecated - 0.11.0’s check of a key proof bound to no asker. KEEL-19: it refuses
every proof — an unbound proof can be relayed by another peer — naming
check_key_proof_for. - check_
key_ proof_ for - Check a peer’s
_infokey proof:key(key:<hex>) signednonce,backendandasker— the checker’s own principal, as the prover was to know it — withPeerKey::key_proof. A proof made for another asker does not verify. - check_
proof - Check
prooffor presentingtoken(whose claims areclaims) formethodundercall, as ofnow: signed by the keyclaims.cnf.jktnames, over this token, method and call, fresh, and not seen before. - ensure_
private_ dir - KEEL-19 (P5, KEEL-25) ·
diras a private directory: made (0700, its parents as the umask makes them) when missing; refused — naming it — when it is a symbolic link, not a directory, not this process’s effective user’s, or open to group or others in any way. - is_
within - Whether every entry of
inneris held byouter: the same grant, on the same scope or within oneouterholds (*). - key_of
- The key a
key:<64 hex>principal names. - mint_
scope - The scope a forwarded call’s token holds (D3: the caller’s reach ∩ the
peer’s needs ∩ consent): the forwarded grant on each scope the call was
admitted on (
reach,["*"]when everywhere), and each need’s grant on each scope both its consent and the reach hold. Never a scope the reach does not hold. - narrow
- The scope an exchange may give:
requested(all ofpresentedwhenNone), each entry kept only wherepresentedholds it — narrowed to the inner scope, never widened. RFC 8693 §2.1 downscoping. - now
- Seconds since the epoch, now.
- onward_
scope - DYNAUTH-6 (RFC 8693): the scope of the token for an onward call — one a
peer made back through its service under
presented, which reaches another peer. Never wider thanpresented: each need of the next peer only wherepresentedholds the same grant (narrow); the forwarded grant (the next peer’s terms) only on the scopes wherepresentedholdsadmitted— the grant the service admitted the onward call on, in its own terms (dyn.{peer}). Withinreachasmint_scopeis. - principal_
of key:<64 hex>— the principal a key proves (spec/00’s form).- prove
- A proof of possession by
keyfor presentingtokenformethodundercall(see the module docs). - prove_
at proveas ofiat.- random_
nonce - A fresh nonce (256 bits from the OS, base64url): what a mount asks a
peer to sign at
_info. - read_
private_ if_ any - KEEL-19 (P5): [
read_private] for a file that may be missing (None). - thumbprint
- RFC 7638 thumbprint of an Ed25519 key (OKP, RFC 8037 §2):
base64url(sha256(
{"crv":"Ed25519","kty":"OKP","x":"…"})). - token_
hash - base64url(sha256(token)) — a proof’s
ath.