Module auth 

Handshake state machine + auth method dispatch.

Hello / HelloAck payloads are JSON for the initial cut. CBOR migration tracked as a follow-up — JSON keeps the v2 wire debuggable from a hex dump and reuses the engine’s existing crate::serde_json codec without a new dep.

Auth methods supported in v2.1:

• bearer — token in AuthResponse, validated against AuthStore
• anonymous — only when AuthStore is disabled; no challenge

Structs

Hello

Decode the JSON-shaped Hello payload sent by a v2 client.

Enums

AuthOutcome

Outcome of validate_auth_response.

Constants

SUPPORTED_METHODS

Methods we know how to handle today.

Functions

base64_std

base64_std_decode

build_auth_fail

build_auth_ok

Build the AuthOk payload the server sends after a successful auth.

build_hello_ack

Build the HelloAck the server sends back. chosen_auth is the strongest method both sides support; chosen_version is min(client_max, server_max).

build_scram_auth_ok

Build the AuthOk payload for a successful SCRAM completion. Carries the server signature so the client can verify the server also knew the verifier.

build_scram_server_first

Build the SCRAM server-first-message. Sent in AuthRequest. Format: r=<client_nonce><server_nonce>,s=<salt_b64>,i=<iter>.

new_server_nonce

Generate a 24-byte server nonce, base64-encoded. Cryptographic randomness sourced from the engine’s existing random_bytes helper so SCRAM doesn’t introduce a new RNG path.

parse_jwt

Parse a compact-serialized JWT into a DecodedJwt. RFC 7519 shape: <base64url(header)>.<base64url(payload)>.<base64url(signature)>. The validator does the heavy lifting (signature, claims, expiry); this function just splits + decodes.

parse_scram_client_final

Parse SCRAM client-final-message. Format: c=<channel_binding_b64>,r=<combined_nonce>,p=<proof_b64>.

parse_scram_client_first

Parse a SCRAM client-first-message. Format: n,,n=<user>,r=<client_nonce> (no channel binding, no authzid). Returns (username, client_nonce, bare_message).

pick_auth_method

Server’s policy for picking an auth method given the client’s preferences. Strongest-first ordering — but when the server has no auth backend configured (server_anon_ok = true), anonymous wins over bearer because bearer validation would fail anyway. v2.1 supports bearer + anonymous; future versions prepend scram-sha-256, mtls, oauth-jwt to the priority list.

validate_auth_response

Validate the AuthResponse payload for the chosen method.

validate_oauth_jwt

Validate a JWT through the supplied OAuthValidator. Returns (username, role) on success, or a refusal reason.

validate_oauth_jwt_full

Tenant-aware variant of validate_oauth_jwt. Returns (tenant, username, role) so the caller can mint a session pinned to the tenant carried by the configured tenant_claim.