Struct SessionCredential 

pub struct SessionCredential { /* private fields */ }

Authentication state whose lifetime is exactly one session.

A “session” is whatever the embedder binds this to — an accepted TCP connection, a TLS session, an HTTP/2 stream. This crate deliberately does not know: binding it is transport-specific, and the mechanism is not.

What this is for. Verifying a credential costs real work — on one machine ~800 ns for an HMAC-backed scheme, against ~107 ns for an entire quota admission. Left per-request it dominates everything the rest of the stack does. Doing it once per session and comparing thereafter brings the per-request cost to ~16 ns.

What it must never become. A cached credential proves identity, never authorization. A hit skips the verifier and nothing else: the caller still runs admission against the current snapshot, so status, staleness, permissions, rate and quota are decided fresh every request. Revocation stays bounded by snapshot refresh exactly as it is without this cache.

A cached answer is also bounded by whatever validity the verifier attached to it (Verified::reusable_until), so an expiring scheme — PASETO, JWT, a client certificate — does not get to outlive its own expiry just because the session stayed open.

Clones share one slot, so concurrent requests on a multiplexed session authenticate independently without a lock.

Implementations

impl SessionCredential

pub fn new() -> Self

An empty cache. Give each session its own.

pub fn authenticate<V: CredentialVerifier + ?Sized>( &self, credential: Option<&[u8]>, verifier: &V, now: Timestamp, ) -> Option<Principal>

Resolve credential to a Principal as of now, verifying it only when this session has not already verified exactly these bytes, or when the previous answer is no longer reusable.

credential is the credential itself, with any transport framing already removed — the Bearer prefix, the header name, the cookie attributes. Pass the same bytes you would pass to CredentialVerifier::verify; this compares and verifies the same slice, so there is no second value to fall out of step with it.

now is supplied by the caller rather than read here, because this runs on the request path and the request path does not read clocks (INVARIANTS.md GL-5).

None means the session presented nothing, and clears any prior proof.

The ordering below is load bearing: a credential that does not match the cached one invalidates the cache before its replacement is verified, so a failed verification can never leave the previous principal reusable. Failed verification is never cached.

pub fn is_authenticated(&self) -> bool

Whether this session currently holds a verified credential. For tests and diagnostics; the credential itself is never exposed.

Trait Implementations

impl Clone for SessionCredential

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionCredential

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SessionCredential

fn default() -> Self

Returns the “default value” for a type.