Trait TokenBroker 

pub trait TokenBroker: Send + Sync {
    // Required method
    fn resolve<'a>(&'a self, caller_id: Option<&'a str>) -> ResolveFuture<'a>;

    // Provided methods
    fn resolve_bearer<'a>(&'a self, _bearer: &'a str) -> ResolveBearerFuture<'a> { ... }
    fn accepted_token_formats(&self) -> &'static [&'static str] { ... }
}

Server-side extension point that resolves secrets for a caller.

Implementations should be cheap to call (per-CallContext overhead); long-lived bundles ought to be cached by the broker itself.

Required Methods

fn resolve<'a>(&'a self, caller_id: Option<&'a str>) -> ResolveFuture<'a>

Resolve a secret bundle for the given caller.

• Ok(None) — no bundle is registered for this caller. Dispatch proceeds with ctx.secrets() = None; the tool falls back to whatever pre-broker mechanism it used (env vars, saved file).
• Ok(Some(bundle)) — bundle attached to the call.
• Err(_) — hard failure; dispatch returns ERR_BROKER_FAILED (1003) and Tool::call is not invoked.

Provided Methods

fn resolve_bearer<'a>(&'a self, _bearer: &'a str) -> ResolveBearerFuture<'a>

Resolve a bearer token (from an HTTP Authorization: Bearer … header) to a BearerIdentity. The HTTP listener calls this once per request before dispatch (SP-streamable-http §4.3).

• Ok(None) — bearer was syntactically acceptable but unknown to this broker. Listener treats as anonymous (or 401, per require_bearer).
• Ok(Some(identity)) — bearer validated; identity carries caller id, capabilities, optional secrets + expiry hints.
• Err(BrokerError::Lookup) — transient look-up failure (DB down, network blip). HTTP listener maps to 503 + Retry-After: 5 per SP-token-broker-phase2 §4.4. Brokers using Lookup for “malformed bearer” should switch to a synchronous reject path (e.g. return Ok(None)) so the listener emits 401 + WWW-Authenticate: Bearer error="invalid_token" instead.
• Err(BrokerError::Expired) — bearer recognised but past expiry.
• Err(BrokerError::Revoked) — bearer recognised but its grant was administratively revoked.
• Err(BrokerError::NotConfigured) — broker does not support bearer auth (default impl). Listener treats as anonymous mode.

Default impl returns Err(NotConfigured) so phase-1 brokers (InMemoryTokenBroker) and third-party brokers compile unchanged — the only adopters who get HTTP bearer auth are the ones who override this method (SP-streamable-http §4.4, SP-token-broker-phase2 §5).

fn accepted_token_formats(&self) -> &'static [&'static str]

Hint to the operator + diagnostics paths about which token format(s) this broker accepts (e.g. ["ce-pairing-code"], ["jwt-rs256"], ["opaque"]). Listener does NOT route on this — it is informational, surfaced through atd-ref-server --doctor and the /initialize server-info echo. Default &[] means “unspecified / introspect via try-resolve”. SP-token-broker-phase2 §4.2.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl TokenBroker for FileTokenBroker

impl TokenBroker for InMemoryTokenBroker