Enum BearerOutcome 

#[non_exhaustive]
pub enum BearerOutcome {
    Anonymous,
    Validated(BearerIdentity),
    HeaderMissing,
    BearerEmpty,
    NoBrokerConfigured,
    Unknown,
    Expired,
    Revoked(String),
    BrokerNotConfigured,
    Lookup(String),
    Internal(String),
}

Outcome of a single bearer resolution.

The route handler in server.rs consumes this via Self::http_status / Self::www_authenticate / Self::retry_after / Self::rejection_message to build the response. Variants are deliberately fine-grained to match SP-token-broker-phase2 §4.4’s observable-distinction contract: adopters’ UIs (Celia’s “agent revoked” toast vs “code expired” prompt vs “you mistyped, try again”) need them.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Anonymous

No Authorization header present and require_bearer == false. Route handler proceeds with an empty CapabilitySet.

Validated(BearerIdentity)

Bearer header present and broker returned Ok(Some(identity)).

HeaderMissing

require_bearer == true and no Authorization header.

BearerEmpty

Authorization: Bearer present but token after the prefix is empty — pure client error (per spec §4.4 input contract).

NoBrokerConfigured

Header present and recognised as Bearer … but no broker is wired into HttpServerConfig.shared.token_broker. Adopter-side deployment misconfiguration (501 — server cannot honor the contract it claims).

Unknown

Broker returned Ok(None) — token is well-formed but unknown.

Expired

Broker returned Err(Expired).

Revoked(String)

Broker returned Err(Revoked(reason)).

BrokerNotConfigured

Broker returned Err(NotConfigured) — broker is wired but its resolve_bearer is the default-impl stub. Distinct from NoBrokerConfigured: the broker exists, it just won’t engage.

Lookup(String)

Broker returned Err(Lookup(reason)) — transient look-up failure (DB hiccup, network blip). Spec §4.4 says 503 + Retry-After: 5. The 2026-04 phase-1 doc had this conflated with “malformed bearer”; phase-2 clarifies it as transient.

Internal(String)

Broker returned Err(Internal(reason)) — broker bug. 500.

Implementations

impl BearerOutcome

pub fn http_status(&self) -> StatusCode

HTTP status code this outcome maps to. Validated / Anonymous return 200 as a sentinel — they should not be passed to the error response path.

pub fn www_authenticate(&self) -> Option<&'static str>

Value for the WWW-Authenticate header, or None if no auth-challenge should be sent.

pub fn retry_after(&self) -> Option<u64>

Value for the Retry-After header in seconds, or None. Per spec §4.4, only the transient Lookup outcome sends this.

pub fn rejection_message(&self) -> Option<String>

Human-readable rejection message for the error response body. None for the success / continue outcomes.

pub fn is_admitted(&self) -> bool

true if this outcome means “continue dispatch”; false if the response is an early-return error.

Trait Implementations

impl Debug for BearerOutcome

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

Formats the value using the given formatter.