Crate authentication_verifier 

Offline PASETO v4.public token verification against the authentication-service’s published Ed25519 keys.

The offline verification model

The authentication-service is the federation’s single auth provider. A user session lives server-side (a Postgres-backed cookie session); from that session the service mints short-lived PASETO v4.public access tokens and publishes its Ed25519 public keys at /.well-known/paseto-keys. Every other service verifies those tokens offline: fetch the key set once at boot, build a Verifier, then call Verifier::verify per request. There is no shared secret and no per-request introspection call.

“Offline” is the key property and the reason this crate exists. Because v4.public is asymmetric (Ed25519), the signer (auth-service) holds the private key and the verifiers (every peer service) hold only the public key. A peer can therefore confirm a token’s authenticity with no network round-trip on the hot path, no shared symmetric secret to distribute, and no introspection endpoint to depend on for availability. The only network interaction is the one-time (or rare) key fetch, available out of band or via the optional fetch feature.

This replaces the crate’s previous RS256-JWT + JWKS design (≤ 0.1.x): PASETO is a versioned, misuse-resistant token format with no algorithm agility, so the “alg confusion” / alg=none class of JWT attacks does not exist. See agents/share/authentication-sessions.md in the monorepo for the family-wide design.

Authorization (ABAC)

Since 0.3 the crate is also the family’s shared authorization foundation: verified Claims carry the subject’s attributes in the attrs claim, and the abac module provides the pure policy engine (Policy, Rule, Action, Policy::evaluate → Decision) that the nine entity services call from their blanket /api/* guards. See agents/share/authorization-attributes.md for the design.

Security properties

• Asymmetric trust. Verifiers never possess signing material, so a compromised peer cannot mint tokens — it can only verify them.
• No algorithm agility. The token header is the literal string v4.public; there is no alg field to downgrade and no none.
• Key selection by kid. The verifying key is chosen by the token’s (authenticated) footer kid; a forged or stale kid simply matches no known key.
• Issuer / audience / expiry enforcement. Beyond a valid signature, every token must carry the expected iss, the expected aud, an unexpired exp, and (if present) a satisfied nbf.

Features

• fetch (off by default) — adds [Verifier::from_paseto_keys_url], which pulls the key set over HTTPS via reqwest (rustls). With the feature off the crate does no I/O and the caller supplies the key set as a serde_json::Value.

Example

// Normally the keys come from the auth-service; an empty set here
// keeps the doctest offline and dependency-free.
let keys: serde_json::Value = serde_json::json!({ "keys": [] });
let verifier = Verifier::from_paseto_keys_value(&keys, "authentication-service", "main-x-service")?;
let claims = verifier.verify("v4.public...")?;
println!("authenticated subject: {}", claims.sub);

Re-exports

pub use abac::Action;

pub use abac::ActionPattern;

pub use abac::Decision;

pub use abac::Effect;

pub use abac::Policy;

pub use abac::ReloadablePolicy;

pub use abac::Rule;

Modules

abac

Attribute-based access control (ABAC) — the family’s shared authorization engine.

Structs

Claims

Verified token claims. Mirrors the auth-service Claims exactly so a token signed there round-trips here. sub carries the user pid.

ReloadableVerifier

A hot-reloadable Verifier holder for key rotation: the active verifier (its published Ed25519 key set) can be swapped at runtime — e.g. by a periodic re-fetch of /.well-known/paseto-keys — without a restart, while the per-request verify path stays lock-light.

Verifier

A set of published verification keys (indexed by kid) plus the issuer / audience policy applied to every token. Construct once at boot, then share behind an Arc and call verify per request — verification is read-only and allocation-light.

Enums

VerifyError

Failure modes for key-set loading and token verification.