Trait AuthPlugin 

pub trait AuthPlugin: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn provider_kind(&self) -> AuthProviderKind;
    fn resolve(
        &self,
        ctx: &AuthRequestContext,
    ) -> Result<Option<AuthUser>, String>;

    // Provided methods
    fn begin_login(
        &self,
        _ctx: &AuthRequestContext,
        _params: LoginParams,
    ) -> Result<LoginAction, String> { ... }
    fn complete_login(
        &self,
        _ctx: &AuthRequestContext,
        _callback: CallbackData,
    ) -> Result<AuthUser, String> { ... }
    fn logout(&self, _ctx: &AuthRequestContext) -> Result<(), String> { ... }
}

An auth provider plugin.

Lifecycle (validation-only flow):

1. Every incoming request: host calls resolve(ctx) → Some(user) or None.
2. On logout: host calls logout(ctx) (default no-op for stateless providers).

Lifecycle (interactive flow):

1. User hits a protected route, not yet authed: runtime calls begin_login(ctx, params) and applies the returned LoginAction.
2. User returns via the callback route: runtime calls complete_login(ctx, callback) and — on success — asks the active Session provider to issue a session keyed to user.subject.
3. Subsequent requests: resolve(ctx) reads ctx.session_id, looks the session up via the Session capability, and returns the user.
4. On logout: logout(ctx) and the Session capability deletes.

The plugin never issues sessions directly — that’s the Session capability’s job (see session.rs).

Required Methods

fn name(&self) -> &str

Unique identifier (e.g. "auth-jwt", "auth-oauth2-github").

fn provider_kind(&self) -> AuthProviderKind

What flow shape this provider implements. The runtime uses this to decide which HTTP routes to mount and to gate calls to the optional login-flow methods below.

fn resolve(&self, ctx: &AuthRequestContext) -> Result<Option<AuthUser>, String>

Resolve the current request to an authenticated user.

Returns Ok(None) for “not logged in” (not an error). Returns Err(..) only for malformed credentials or backend failures the caller should surface as 401/500.

This is the only required method — validation-only backends (JWT, opaque bearer) implement just this one.

Provided Methods

fn begin_login( &self, _ctx: &AuthRequestContext, _params: LoginParams, ) -> Result<LoginAction, String>

Initiate an interactive login flow.

Default: Err("login flow not supported by this provider"). Token-validation backends keep the default.

fn complete_login( &self, _ctx: &AuthRequestContext, _callback: CallbackData, ) -> Result<AuthUser, String>

Complete an interactive login at the callback route.

On success, returns the authenticated AuthUser. The runtime then hands that user to the active Session provider to issue a session; this plugin does not persist session state itself.

Default: Err("login flow not supported by this provider").

fn logout(&self, _ctx: &AuthRequestContext) -> Result<(), String>

Invalidate auth state for the current request.

For stateless providers this is a no-op (the token expires on its own). For interactive providers this hooks any provider-side revocation (OAuth token revoke endpoint, magic-link one-time-use marking). The runtime still calls the Session capability to delete the session row — this method only handles provider-side cleanup.

Default: Ok(()).

Implementors