Struct SessionTokenRegistry 

pub struct SessionTokenRegistry { /* private fields */ }

Thread-safe registry of active session tokens.

Implementations

impl SessionTokenRegistry

pub fn new() -> Self

pub fn register( &self, token: String, scope: impl Into<GrantScope>, max_connections: u32, )

Register a new token. Replaces any existing token with the same value.

pub fn register_with_expiry_ms( &self, token: String, scope: impl Into<GrantScope>, max_connections: u32, expires_at_ms: Option<u64>, )

Register a new token with an optional absolute Unix-millisecond expiry.

pub fn validate_and_consume(&self, token: &str) -> Result<GrantScope, String>

Validate a token and increment its use count.

Returns Ok(scope) on success, Err(reason) on failure. If the registry is empty, only a tokenless low-level/manual connection receives the compatibility verdict. A presented bearer token must always match a registered capability; otherwise arbitrary strings could be promoted into trust by higher layers.

pub fn validate_and_consume_for_connection( &self, token: &str, connection_id: Option<&str>, ) -> Result<GrantScope, String>

Validate a token, increment its use count, and optionally record the connection_id so revoke_by_scope can return affected connections.

pub fn validate_and_consume_for_connection_with_payload( &self, token: &str, connection_id: Option<&str>, payload_suffix: Option<&str>, ) -> Result<GrantScope, String>

Validate a raw session token with optional compact payload metadata.

Legacy callers may omit payload_suffix; modern compound-ticket callers should provide it so the host can enforce the payload audience, expiry, token binding, and nonce replay checks instead of seeing only the raw bearer token.

pub fn validate_with_cached_response( &self, token: &str, connection_id: &str, ) -> Result<GrantScope, String>

Phase 1 verdict-only API. Returns the deterministic admission verdict for (token, connection_id) without running any post-admission side effects (no accept_replacement_peer, no WebRTC recovery, no transport replacement). Callers must:

1. Call this to compute the verdict.
2. Write + flush the response to the wire.
3. Then run their post-admission side effects (e.g. via Client::run_post_session_token_admission_side_effects).

This separation is what eliminates the 0 bytes read race where the host’s lifecycle hooks would retire the very transport the response writer was using before it could flush.

pub fn validate_with_cached_response_and_payload( &self, token: &str, connection_id: &str, payload_suffix: Option<&str>, ) -> Result<GrantScope, String>

pub fn begin_admission_response( &self, connection_id: &str, ) -> AdmissionResponseGuard

Mark a session-token response writer as in-flight for connection_id. Returns a guard whose Drop decrements the counter. While any guard is alive for a given connection, the transport must not be closed/retired by lifecycle code (see is_session_token_admission_in_flight).

pub fn try_begin_admission_response( &self, connection_id: &str, ) -> Option<AdmissionResponseGuard>

Atomically begin a response writer unless terminal retirement already owns this connection.

pub fn try_begin_admission_presentation( &self, connection_id: &str, ) -> Option<AdmissionPresentationGuard>

Atomically acquire the sole outbound presenter for one connection. Host response writers may coexist because they operate in the opposite direction, while duplicate outbound attempts and retirement are fenced.

pub fn try_begin_transport_retirement( &self, connection_id: &str, ) -> Option<AdmissionRetirementGuard>

Atomically acquire transport retirement unless a response writer or outbound presenter already owns the connection.

Physical health replacement and terminal admission timeout share this fence. Both must serialize teardown against an in-flight protocol exchange; the guard itself does not decide whether logical admission is retained or forgotten.

pub fn try_begin_admission_retirement( &self, connection_id: &str, ) -> Option<AdmissionRetirementGuard>

Admission-timeout spelling retained for the terminal caller.

pub fn is_session_token_admission_in_flight(&self, connection_id: &str) -> bool

True while a session-token response writer or the sole outbound presenter is mid-flight for connection_id. Lifecycle code must defer transport teardown while this returns true.

pub fn is_session_token_presentation_in_flight( &self, connection_id: &str, ) -> bool

pub fn admission_fingerprint(&self, connection_id: &str) -> Option<String>

pub fn admission_epoch(&self, connection_id: &str) -> Option<u64>

pub fn revoke(&self, token: &str) -> Vec<String>

Revoke a specific token.

pub fn revoke_by_scope(&self, scope: impl AsRef<str>) -> Vec<String>

Revoke all tokens and logical admissions with the given scope.

validated_connections records tokens this runtime validated from a peer. admissions also records the opposite direction after a remote host approves this runtime’s token. Scope revocation is a logical-session boundary, so both directions must be returned to the lifecycle owner.

pub fn clear(&self)

Remove all tokens and validated connection bindings.

pub fn is_empty(&self) -> bool

True if no restricted session tokens are registered.

pub fn admission(&self, connection_id: &str) -> SessionAdmission

pub fn is_session_token_admitted_for_connection( &self, connection_id: &str, ) -> bool

True when this runtime validated a token presented by the remote peer.

Used to detect duplicate token frames on the same logical connection (e.g. new iroh substreams re-sending the compound ticket) — those must not re-trigger native WebRTC upgrade recovery, which is only appropriate for the first token presentation.

pub fn mark_rejected(&self, connection_id: &str, reason: impl Into<String>)

pub fn mark_accepted( &self, connection_id: &str, mechanism: SessionAdmissionMechanism, scope: Option<GrantScope>, authoritative_device_id: Option<String>, )

pub fn bind_connection_scope( &self, connection_id: &str, scope: impl Into<GrantScope>, authoritative_device_id: Option<String>, )

pub fn forget_connection(&self, connection_id: &str)

pub fn set_native_trusted_connection_verifier( &self, verifier: Option<NativeTrustedConnectionVerifier>, )

pub fn evaluate_trusted_native_connection( &self, context: &NativeTrustedConnectionContext, ) -> Option<String>

Trait Implementations

impl Clone for SessionTokenRegistry

fn clone(&self) -> SessionTokenRegistry

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for SessionTokenRegistry

fn default() -> SessionTokenRegistry

Returns the “default value” for a type.