Skip to main content

Module peer_token

Module peer_token 

Source
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"}:

claimwhat
issthe issuing service’s key, key:<hex>
subthe original caller (the first hop’s admitted principal)
actthe actor chain, nearest first, nested as RFC 8693 §4.1 nests it
audexactly one peer: its key (key:<hex>), or pipe:<name> for a child on the issuer’s own pipe
scopespace-separated grant@scope entries: the caller’s reach ∩ the peer’s needs ∩ consent
cnf.jktthe 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, methodthe forwarded call’s id and the method it names
jti, iat, expunique; 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.
AuditRecord
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 9449 jkt).
ExchangeRefused
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: kty OKP, crv Ed25519).
Jwks
A JWK Set (RFC 7517 §5): what dyn.jwks answers.
MintRequest
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.
PeerClaims
A peer token’s claims.
PeerKey
An Ed25519 key with its id (key:<hex>): a service’s signing key, or a peer’s own. Debug never shows the seed.
ProofCache
The proofs a presenter’s side has seen, each once (by its jti, kept for twice the skew).
TokenIssuer
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 jti once.

Enums§

AuditKind
What was done with a token.
ExchangeRefusal
KEEL-19: why an exchange was refused, as a word.
TokenError
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 own call.
JWT_TOKEN_TYPE
RFC 8693’s identifier of the token type issued.
KEY_PROOF_CONTEXT
The context a peer’s key proof at _info is 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 typ of a proof of possession.
SKEW
How far apart two clocks may be.
TOKEN_TYP
The typ of a peer token (RFC 8725 §3.11: explicit typing).

Traits§

TokenAudit
Where audit records go besides tracing (PRIVACY-1’s sink, when it is).

Functions§

check_key_proofDeprecated
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 _info key proof: key (key:<hex>) signed nonce, backend and asker — the checker’s own principal, as the prover was to know it — with PeerKey::key_proof. A proof made for another asker does not verify.
check_proof
Check proof for presenting token (whose claims are claims) for method under call, as of now: signed by the key claims.cnf.jkt names, over this token, method and call, fresh, and not seen before.
ensure_private_dir
KEEL-19 (P5, KEEL-25) · dir as 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 inner is held by outer: the same grant, on the same scope or within one outer holds (*).
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 of presented when None), each entry kept only where presented holds 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 than presented: each need of the next peer only where presented holds the same grant (narrow); the forwarded grant (the next peer’s terms) only on the scopes where presented holds admitted — the grant the service admitted the onward call on, in its own terms (dyn.{peer}). Within reach as mint_scope is.
principal_of
key:<64 hex> — the principal a key proves (spec/00’s form).
prove
A proof of possession by key for presenting token for method under call (see the module docs).
prove_at
prove as of iat.
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.