​

ADR 0021: Pluggable Authentication: the AuthProvider Seam

​

Status

​

Date

• 2026-10-28: proposed. The refusal envelope (§1) is built for REST, RPC unary and RPC batch.
• 2026-10-29: updated for cratestack#1246, which also renders refusals on MCP Streamable HTTP and sync, fixes sync’s leak of Internal detail, and builds MCP credential presence as a builder option (CredentialPresence) rather than the trait method first proposed in §4.

​

The standing decision this ADR serves

​

Decisions for the maintainer

​

Context

​

Facts at d3c476a (0.17.0) and d8b088e (the #1208 branch)

1. The trait. AuthProvider has one method, authenticate(&RequestContext) -> Result<CratestackContext, Self::Error>, with type Error: Into<CratestackError> (context.rs). A header-only closure implements it through a blanket impl.
2. The request. RequestContext carries method, path, query, headers, the full buffered body and the in-process extensions (trusted, unlike headers). Body-hash schemes (bdh-style device signatures, SigV4-style content hashes) can therefore verify today.
3. The context. CratestackContext holds an auth identity (a flat field map) and a principal (actor, session and tenant facets plus a claims map). Both are untyped. auth_field(path) resolves dotted paths across both. Two private, non-serializable facts sit next to them: the system flag (SystemContext) and the VerifiedSigner an envelope recorded (ADR 0006 §12). Neither can be set by a provider.
4. Policies read conventions, not a contract. hasRole(r) reads role, then actor.role, and compares one string. inTenant(t) reads tenant.id as a string (eval.rs). auth().<path> is resolved at compile time against the schema’s auth block and read with auth_field at run time. Framework code reads the caller’s id in at least three ways: principal_actor_id() (actor.id, then claims.id, then auth.id, strings only), MCP’s admission key (principal_id, which also renders an integer id as its digits, so that auth User { id Int } schemas work), and the WebTransport session key in #1238 (actor.id, then id, then sub). COSE’s signer principal writes id = "cose:<thumbprint>". cratestack-sync asks an application-supplied resolver.
5. The only shipped mapper is product-specific. cratestack-auth’s principal_to_cratestack_context emits actor { id, enrollmentStatus, kycStatus, … }, session { clientId, boundKeyId, requestNonce, … }, id, clientId, role, kycStatus, kycDossierId. An external library has nothing documented to map to.
6. Refusals. Before #1208, into_response() always set details: None and a provider could only choose between UNAUTHORIZED and FORBIDDEN with a message. Clients that sort refusals by reason (fespalier’s device-signature classifier: attestation_expired means renew, key_not_bound means signed out, DEVICE_REVOKED means revoked; OAuth’s invalid_token and insufficient_scope) could not work through the generated router. fespalier’s examples/cratestack refuses in a tower layer in front of the router instead.
7. Each transport calls the provider its own way. REST and RPC unary authenticate per request. RPC batch authenticates the envelope once and hands every frame a CachedAuthProvider. SSE model subscriptions authenticate GET /rpc/subscribe/<op_id> once, before the stream. MCP Streamable HTTP requires Authorization: Bearer before the provider runs (streamable_http/auth.rs). cratestack-sync turns any provider error into 401 unauthenticated (server/http/mod.rs). The WebTransport binding in cratestack#1238 (open) authenticates once per session.
8. Composition is hand-written. CoseAuthProvider wraps an inner provider: the inner one runs first, its authenticated answer or its error is returned as is, and only an anonymous answer falls back to the verified signer (signer_provider.rs).

​

Goals and non-goals

• a built-in OAuth or OIDC server, or a user store;
• schema grammar for freshness or step-up. That is cratestack#1244, which builds on §1 and §2;
• any change to the COSE envelope wire format (ADR 0006);
• any dependency of a framework crate on an auth library.

​

Decision

​

1. The refusal envelope (D1)

​

As built in #1208

• The refusal becomes CratestackError::AuthRefused through into_error(), and there is deliberately no From<AuthRefusal> for CratestackError. A second From impl on CratestackError makes every ? whose error type was inferred through the reflexive From<T> for T ambiguous (E0283), in generated code and in application code alike. The trait’s type Error: Into<CratestackError> is unchanged, so no existing provider breaks.
• The code stays framework-owned. The epic’s first sketch let a provider choose the wire code. The built design does not: a client that switches on UNAUTHORIZED or unauthenticated keeps working, and a provider’s own reason travels as a member. By convention that member is named error, the name RFC 6750 uses and fespalier’s classifier reads ({"code": "UNAUTHORIZED", "message": "attestation expired", "error": "attestation_expired"}). The convention is documented, not enforced.
• Only 401 and 403. A refusal is about who the caller is. A provider that cannot decide (a JWKS endpoint is down) returns Unavailable or Internal, which keep their canned public messages. A refusal is never a 5xx.
• No byte changes for anyone else. CratestackErrorResponse and RpcErrorBody gain a public extra map, serialized by hand as a known-length map, never #[serde(flatten)] (which a CBOR encoder writes as an indefinite-length map). An envelope without extra members encodes byte for byte as before, in JSON and in CBOR (cratestack-codec-cbor/tests/error_envelope_bytes.rs). Unknown members of an envelope read from the wire are collected into extra.
• Challenges ride on the error, not in the envelope. Every encoder takes them off the error before it is consumed and appends them to the response (auth_challenge.rs). The RPC binding re-encodes a handler’s REST-shaped error into an RPC body and copies the header across. The streaming (@stream) and middleware error paths attach them too.

​

The transport matrix

​

2. The principal contract (D2)

​

Reserved names

​

A builder and typed readers in core

let ctx = CratestackContext::builder("user-42")         // sub
    .roles(["admin", "teller"])
    .tenant("acme")                                     // tenant.id
    .auth_time(1_793_000_000)
    .amr(["hwk", "user"])
    .acr("urn:example:loa:2")
    .cnf_jkt(jwk_thumbprint)                            // base64url
    .key_role(KeyRole::UserPresent)
    .claim("kycStatus", Value::String("verified".into())) // free-form
    .build();

​

How the readers use it

• subject() reads sub, then actor.id, then id, and renders an integer as its decimal digits (MCP’s principal_id rule). Every framework read of “who” moves to it: principal_actor_id(), the MCP admission key, and the WebTransport session key and principal-change check. cratestack-sync’s principal resolver defaults to it. Today these readers disagree on the order and on integer ids. A provider that sets sub gets the same answer everywhere.
• hasRole(r) is true when roles contains r, or role equals r, or actor.role equals r. The two legacy reads stay, so no existing policy changes meaning.
• inTenant(t) reads tenant.id, unchanged.
• auth().<path> is unchanged: the schema’s auth block declares what a policy may read. A schema that declares a reserved name must declare it with the contract’s type (for example roles String[]), and the semantic checker says so. The policy operators that compare auth_time or test membership in amr are #1244’s grammar, not this ADR’s.

​

The product-specific mapping in cratestack-auth

1. It also emits the contract names it knows: sub (the user id, or svc:<key id> for a service caller), roles (from the verified role claim), and cnf from the id-token’s key binding. auth_time and amr are #1244’s child story 8.
2. A second mapper emits only the contract names plus the free-form claims a deployment selects, for applications that are not Webank.
3. SignedRequestAuthProvider takes the mapper as configuration. Which one is the default is Q2.

​

3. Canonical request versus wire request (D3)

1. method is the operation’s declared method, not whatever the client sent: POST for every RPC call, GET for a subscription, CONNECT for a WebTransport session.
2. path is the route CrateStack declares, relative to the router’s own root. A mount prefix never appears: a router nested under /api hands the provider /rpc/<op_id>, not /api/rpc/<op_id>. A client signs its request path minus the base URL’s path. The internal /$procs/... path never appears on transport rpc either.
3. query is the raw query string exactly as received, where the operation reads one (REST model reads, and a WebTransport CONNECT, whose ?codec=cbor|json is the fallback for a client that cannot negotiate the subprotocol), and None everywhere else.
4. body is the exact bytes the router received, before decoding, and never re-encoded. Behind the COSE envelope layer that is the opened payload. A provider that needs the sealed message reads the recorded VerifiedSigner, not the body.
5. headers and extensions are the request’s own. A synthesized request (a WebTransport Init) says in its transport’s documentation which headers it substitutes.

​

4. MCP credential presence (D4)

​

As built in #1246: a builder option

​

Still proposed: a defaulted trait method, for the chain (D5)

fn credential<'r>(&self, request: &RequestContext<'r>) -> Credential<'r> {
    Credential::bearer(request.headers) // today's check, unchanged
}

pub enum Credential<'r> {
    Absent,
    Present { redact: Option<&'r str> },
    Malformed(&'static str),
}

• By default the MCP service uses Credential::bearer whatever the provider says. The MCP conformance job keeps testing a spec-conformant server.
• A deployment that opts in on the Streamable HTTP builder asks provider.credential(..) instead. Absent still gets the Bearer challenge with resource_metadata, so OAuth clients still discover the authorization server; Malformed is a 400 invalid_request; Present { redact } runs the provider and redacts that string from logged detail.
• An anonymous answer is still a 401, the query-token refusal stays, and refusals render as in §1.

​

5. Composition (D5)

let auth = first_success(oauth).or(device_signature).or(cose_signer);

1. If credential() says Absent, skip it without calling authenticate. A strict provider that refuses a request without its credential can therefore sit in a chain.
2. If it returns an authenticated context, return it.
3. If it returns an error (a refusal or otherwise), return that error. A credential one provider refuses is never rescued by another: that is CoseAuthProvider’s rule 1, and it fails closed.
4. If it returns an anonymous context, go on to the next.

​

6. The conformance kit (D6)

#[tokio::test]
async fn my_provider_conforms() {
    cratestack::testing::auth_conformance(MyProvider::new(keys))
        .accepts(|canonical| sign(canonical))                // a valid credential for this request
        .refuses(|canonical| expired(canonical), expected)   // a refused credential and its AuthRefusal
        .run()
        .await;
}

• the same verdict on every transport: an accepted credential yields the same subject(), and a refused one the same refusal;
• the same rendering: status, RPC or REST code, message, members, details and challenges, per the matrix in §1 (whole-batch for batch, the MCP challenge first on MCP);
• the canonical request of §3 exactly, including the body bytes and the absence of the mount prefix;
• one call per request: a batch is authenticated once, and a skipped chain member is not called;
• nothing leaks: an Internal error from the provider stays canned, and a refusal’s members can never replace code, message or details.

​

7. The independence guarantee (D7)

• The example that wires an external library is excluded from the workspace, with its own [workspace] root and lockfile, so Cargo’s feature unification cannot hide anything. The epic’s child story 10 is superseded by cratestack#1245’s examples/auth-pluggable (one schema, three providers: in-house, Authkestra devsig, Authkestra OIDC), so the two are built once.
• A CI job asserts, from the workspace root, that no workspace member’s dependency graph contains an authkestra package (cargo metadata over every member, and cargo tree --workspace -i per known package name, which must find nothing), and, from the example’s root, that it does. The second assertion keeps the first from passing because the example quietly stopped using the library.
• The example uses only public facade paths: a grep of its src/ for __private must find nothing.
• The example runs the conformance kit.

​

Consequences

• A code-classifying or non-Bearer scheme needs no tower layer in front of the router.
• An external library and the in-house providers use the same public surface, proven by one kit.
• Every framework read of “who” agrees, and policies keep their meaning.
• #1244 gets the claims (auth_time, amr, acr, key_role) and the refusal channel it needs.

• Two new public concepts in core (Credential, the builder) and one defaulted trait method.
• Reserved names constrain what a schema’s auth block may declare under those names.
• The kit must grow with every transport. A transport it does not drive is a transport where parity is unproven.
• The sync error body grows a forbidden code and members, which is a sync protocol change.

​

Alternatives considered

​

Open questions for the maintainer

​

Implementation plan

1. This ADR.
2. AuthRefusal, REST and RPC unary: built (#1208, in #1246).
3. RPC batch, SSE, middleware and sync rendering (§1): built in #1246.
4. MCP refusal rendering and CredentialPresence (§1, §4): built in #1246. The defaulted AuthProvider::credential method moves to story 7, with the chain that needs it.
5. The principal contract, builder and readers; hasRole over roles (§2).
6. The canonical-request rule and its tests; the sync and WebTransport call sites (§3).
7. The first-success chain (§5), with the defaulted AuthProvider::credential method (§4).
8. The conformance kit (§6).
9. SignedRequestAuthProvider and CoseAuthProvider onto the public seam, passing the kit.
10. The independence guard, with #1245’s examples/auth-pluggable (§7).
11. Generated clients: the refusal’s members and details typed on CratestackRestException and CratestackRpcException, in Rust, Dart and TypeScript together (transport parity).