Module authz 

Spike: request-scoped identity and authorization for the network surfaces.

The shipped auth module authenticates a connection: its Authenticator returns a bare bool, so a request either passes the bearer-token gate or it does not, and no identity survives into the handler. That is enough for a single trusted operator, but it cannot express three things this spike explores:

1. Optional, layered enforcement. A surface may run wide open, require only authentication, or require authentication and per-operation authorization — chosen at deploy time without recompiling.
2. External identity providers on a shared, public system. A transactor or peer server exposed to many tenants must accept tokens minted by someone else (an OIDC issuer, an mTLS CA) and turn them into a local Principal, not compare them to a single static secret.
3. Many users, different views, one server. Because identity is bound to the request (not the connection), one hosted peer can answer two callers concurrently and give each a different authorization decision and a different ViewFilter over the same database.

The model is deliberately transport-adjacent: Guard bundles a chosen (IdentityProvider, Authorizer) pair, and IdentityInterceptor is the only tonic-facing piece. A deployment that wants none of this constructs Guard::disabled and behaves exactly as today.

Authn is synchronous and authz is asynchronous, on purpose: authenticating a request is local verification (a token compare, a signature check against cached keys, an mTLS subject) and it runs inside the synchronous tonic Interceptor; authorizing one may consult an external policy oracle (OpenFGA / Auth0 FGA answer a per-decision network Check), and it runs handler-side where awaiting is free. A provider that genuinely needs I/O (OIDC token introspection) caches results and refreshes out of band, so IdentityProvider::authenticate stays a cheap synchronous lookup.

See docs/design/auth.md for how this maps onto the RPC surface and the migration away from the bool authenticator.

Structs

Access

A specific access: an Action on an optional target database.

AllowAll

Permits every access. Used when a surface requires authentication but not authorization (or none at all, paired with AllowAnonymous).

AllowAnonymous

Accepts everyone as Principal::anonymous. Used when a surface does not require authentication.

AttributeAllowlist

A ViewFilter that hides every attribute outside an allowlist.

CompositeProvider

Tries a list of providers in order, so one shared system can accept several issuers at once (static tokens for internal tools, OIDC for humans, mTLS for services). The first provider to accept wins; the first to reject stops the chain. If every provider abstains, the composite abstains too — whether that becomes anonymous access or a rejection is the Guard’s policy.

Credentials

Raw credentials extracted from a request, before authentication.

ExternalTokens

Adapts a TokenVerifier into an IdentityProvider.

Grant

A grant held by a role: which actions, over which databases, with what view.

Guard

A chosen (IdentityProvider, Authorizer) pair — the policy a surface enforces. One Guard serves every request on a surface; identity is derived per request, so a single guard handles many concurrent callers.

IdentityInterceptor

tonic interceptor that authenticates each request and stashes the resulting Principal in the request extensions. Because it runs per request, two callers on the same connection get their own identities — the basis for multi-tenant serving. Handlers then call principal and Guard::authorize once they know the concrete Access.

PolicyAuthorizer

A role-based authorizer: a principal’s roles select Grants, and the union of matching grants decides the access. Deny-by-default — an access no grant covers is refused.

Principal

An authenticated (or anonymous) caller, carried in request extensions.

StaticTokens

Maps a fixed set of bearer tokens to fixed principals.

Enums

Action

The operation a request wants to perform, for authorization.

ActionClass

A coarse class of action, so grants need not list every Action.

AuthError

Failure of authentication or authorization.

Decision

The outcome of an authorization check.

Traits

Authorizer

Decides whether a Principal may perform an Access.

IdentityProvider

Turns credentials into a Principal, or declines.

TokenVerifier

Verifies an opaque bearer token minted by an external issuer.

ViewFilter

Restricts what a principal may see within a database it is allowed to read.

Functions

principal

Reads the Principal an IdentityInterceptor attached to a request, defaulting to anonymous when no interceptor ran (e.g. embedded transport).