Module auth 

Auth capability trait. See plan/ecosystem/02-capabilities.md (Auth section).

An AuthPlugin resolves a request to an authenticated principal and (optionally) drives a login/logout flow. The shape is deliberately vendor-neutral: no JWT-specific fields (iss, aud, alg), no OAuth specifics (redirect_uri, scopes, nonce). Provider-specific knobs live in the plugin’s own config section, not on the trait.

Design notes (E1, not yet stabilised)

Sync, not async. Every other plugin trait in this crate is sync (middleware.rs, cache.rs, lifecycle.rs, transform.rs). The plan sketch in 02-capabilities.md uses async fn, but matching the existing convention here keeps the WASM/QuickJS/nsjail ABI consistent (plugins compiled to WASM cannot expose native async at the host boundary) and avoids pulling async-trait into a dependency-minimal leaf crate. Backends that need async I/O (OAuth callbacks, JWKS fetches) can use tokio::runtime::Handle::current().block_on(..) the same way bext-server’s JWKS fetcher already does.

Errors as String. Matches every other trait in this crate. An associated error type would be the first in the API surface and make cross-capability composition (e.g. an auth plugin calling a session plugin) awkward.

Session issuance is delegated. The Session capability owns session storage. An AuthPlugin declares requires_capabilities = [Session] in its manifest; at runtime the host wires a SessionId through resolve and logout rather than making this trait carry session state. This keeps the two capabilities independent as required by 00-architecture.md principle 6.

Login-flow methods are optional. Validation-only backends (JWT, opaque bearer) implement resolve and leave begin_login, complete_login, logout as default-no-ops. Full OAuth / magic-link / passkey backends override all four. This lets the existing bext-server::middleware::auth JWT middleware port cleanly without inventing stub flows it cannot service.

Structs

AuthRequestContext

Per-request context passed to every AuthPlugin method.

AuthUser

An authenticated principal. Vendor-neutral: every concept here (subject, tenancy, role, permissions, free-form attributes) maps cleanly to JWT claims, OAuth profiles, LDAP records, and custom auth stores.

CallbackData

Data a caller hands to complete_login — whatever the upstream provider sends back in its callback (OAuth code+state, magic-link token, passkey assertion, etc.).

LoginParams

Parameters a caller passes when initiating a login flow.

Enums

AuthProviderKind

What kind of auth flow a provider implements. Runtime uses this to decide which HTTP routes to mount (e.g. only OAuth needs a /auth/callback route) and to surface provider shape in admin UI.

LoginAction

Result of begin_login — what the runtime should do to continue the login flow.

Traits

AuthPlugin

An auth provider plugin.