Skip to main content

Crate atlasauth

Crate atlasauth 

Source
Expand description

§atlasauth

The official Rust backend verification crate for Atlas. The Rust peer of @atlasauth/backend, atlas-go, and the Ruby SDK — same verification semantics, same claim names, same @no-email.invalid handling.

It does two things a Rust server needs:

  1. Verify a session token locally against the instance JWKS — RS256, ES256, ES384, PS256 or EdDSA (the key type must fit the header algorithm), with an explicit issuer, exp/nbf/iat checks, and an in-process JWKS cache keyed by URL that refetches on an unknown kid at most once a minute. No outbound call on the hot path.
  2. Verify an end-user API key (ak_…) against Atlas, with separate positive and negative caches so a busy API — or a caller hammering a bad key — does not hammer Atlas.
use atlasauth::AtlasBackend;

let backend = AtlasBackend::new(
    "https://your-instance-fapi.atlasauth.net",                         // issuer
    "https://your-instance-fapi.atlasauth.net/.well-known/jwks.json",   // jwks_url
)?;

let claims = backend.verify(session_jwt()).await?;
if claims.has_permission("billing:read") {
    // authorized
}

This is a server-side crate: it uses your instance secret key (sk_…) for API-key verification and must never ship to a browser or mobile app.

Structs§

AccessTokenOptions
What an API requires of an access token.
ApiKeyCap
A per-key spend cap as the verify result reports it.
ApiKeyCapUsage
A spend cap with its current-window usage, as the verify result reports it.
ApiKeyVerification
The verify verdict. A failed verification is valid = false, NOT an error; an ApiKeyError means the endpoint could not be reached or did not parse.
ApiKeyVerifier
Verifies end-user API keys against Atlas with separate positive/negative caches. Construct with ApiKeyVerifier::new (reqwest) or ApiKeyVerifier::builder.
ApiKeyVerifierBuilder
Builder for an ApiKeyVerifier.
AtlasBackend
Verifies Atlas session JWTs locally against the instance JWKS, with caching.
AtlasBackendBuilder
Builder for an AtlasBackend. Supply exactly one key source: a jwks_url (fetched + cached — the production default) or a static_jwks (fully offline — the hermetic path for CI).
AtlasBackendOptions
Configuration for an AtlasBackend. Build it with AtlasBackend::builder; the raw struct is public so options read clearly.
BackchannelLogoutResponse
What to answer to Atlas’s back-channel logout POST: 200 when the token verified (and your callback ended the sessions), 503 + Retry-After when Atlas should retry, 400 for a token that will never verify (Atlas never retries a 400).
Claims
A verified session’s claims. Construct one only via crate::AtlasBackend::verify; a bare Claims carries no proof.
ConfigError
A configuration error raised when building an crate::AtlasBackend or crate::ApiKeyVerifier with an impossible combination of options.
EmailAddress
A user’s email-address record, as the Backend API serializes it.
HmacDpopNonceSource
DPoP nonces derived from a secret and the clock: a nonce is good for the window it was issued in and the next one, so every instance sharing the secret agrees without shared state.
HttpResponse
A raw HTTP response, as a HttpPost transport returns it.
Jwk
One key in a JWKS document. Unknown members are ignored. n/e are the base64url-encoded RSA modulus and exponent, passed verbatim to jsonwebtoken’s DecodingKey::from_rsa_components.
Jwks
A JSON Web Key Set.
JwksCache
The in-process JWKS cache. Either serves a fixed static_jwks (fully offline — the hermetic path a customer’s CI uses) or fetches from url through a JwksSource, caching with a TTL and a throttled kid-miss refetch.
LegacyIssuer
One old issuer accepted during the cutover.
LogoutTokenClaims
The claims of a verified logout token. At least one of sub / sid is set: end every local session for sid when present, otherwise every session of sub.
LogoutTokenReplayCache
A small in-memory guard against a logout token being replayed: remember each accepted jti until it can no longer verify, and refuse a repeat.
MemoryDpopReplayStore
The in-process DpopReplayStore: entries live until they expire, at most max_entries of them.
OidcOrganization
The organization a sign-in was made in.
OidcOrganizationMembership
One membership from the orgs claim.
OidcSsoContext
The enterprise SSO context of a sign-in (the token’s sso_* claims).
ParsedKey
What parse_key_prefix learned from a credential’s prefix.
ReqwestTransport
A reqwest-backed transport. Cheap to clone (the inner reqwest::Client is an Arc).
ResourceRequest
What verification reads from an HTTP request: the method and URL (absolute, or a path resolved against AccessTokenOptions::public_origin) for the DPoP htu, and the Authorization and DPoP header values.
TransportError
A transport-level failure while talking to a remote endpoint (JWKS fetch or the API-key verify endpoint). Carries a human-readable message only; it is never surfaced to an end user.
TxnTokenClaims
The claims of a verified transaction token.
TxnTokenOptions
What to verify a transaction token against.
User
A user as the Backend API serializes it (GET /v1/users/:id). private/ unsafe metadata are never part of this surface. Unknown fields are kept in User::extra.

Enums§

AccessTokenResult
The verdict of AtlasBackend::verify_access_token.
ApiKeyError
The result of an API-key verification call.
FetchOutcome
The last JWKS-cache action, exposed so a caller (or a test) can assert the rate limit actually bit.
KeyKind
What a credential is, by its prefix.
VerifyError
Why a session-token verification failed. Coarse by design.

Constants§

BACKCHANNEL_LOGOUT_EVENT
The events member a logout token must carry.
BACKCHANNEL_RETRY_AFTER_SECONDS
Seconds to put in Retry-After when the issuer’s keys could not be fetched.
CLOCK_SKEW_SECONDS
§7.3: five seconds either side, matching the server’s minting tolerance.
DEFAULT_BASE_URL
The public API host. Override for self-hosted instances.
DEFAULT_MAX_ENTRIES
Default max entries per cache (positive and negative each): 10 000.
DEFAULT_NEGATIVE_TTL_MS
Default negative-cache TTL: thirty seconds.
DEFAULT_POSITIVE_TTL_MS
Default positive-cache TTL: five minutes.
DEFAULT_TTL_MS
§7.3 serves Cache-Control: max-age=3600; honoured rather than ignored.
DPOP_ALGS
The JWS algorithms accepted on a DPoP proof (and advertised in challenges and metadata). ES512 is not offered: the signature backend has no P-521.
DPOP_CLOCK_SKEW_SECONDS
Clock skew tolerated on a proof’s iat.
DPOP_PROOF_MAX_AGE_SECONDS
How old a DPoP proof may be.
LEGACY_ISSUER_ALGS
Better Auth’s jwt plugin algorithms this crate can verify (the default for LegacyIssuer::algorithms). ES512 is the one Better Auth algorithm missing — see the module docs.
LEGACY_SUBJECT_CACHE_MAX
Cap on cached subjects, so a stream of distinct tokens cannot grow memory without bound.
LEGACY_SUBJECT_TTL_MS
How long a resolved sub → Atlas id mapping is reused, in milliseconds.
LOGOUT_TOKEN_TYPE
The JWT typ header a logout token carries.
NO_EMAIL_SENTINEL_DOMAIN
The domain Atlas appends when a provider shares no email: the address is shaped "<provider>-<provider_user_id>@no-email.invalid". It is never a deliverable address and must never be shown to a user or used as an identity.
OIDC_ORGANIZATION_PARAM
The authorize parameter that pins the organization (id or slug) a sign-in is made in.
OIDC_SCOPE_ORGANIZATIONS
The scope that adds the orgs membership list to the ID token and userinfo.
REFETCH_INTERVAL_MS
§7.3: at most one refetch per minute, however many kid-misses arrive.
SIGNING_ALGS
The JWS algorithms Atlas signs tokens with: an instance key is RS256 (the default), ES256, ES384, PS256 or EdDSA. Every verifier in this crate is pinned to exactly this list: none and HMAC never verify, and the token’s kid selects one published key whose type fixes which algorithm applies.

Traits§

DpopNonceSource
Hands out the server nonce a DPoP proof must carry (RFC 9449 §8) and checks one. current goes to the client in the DPoP-Nonce header; valid accepts the nonces still in force.
DpopReplayStore
Guards against a DPoP proof being used twice. Back it with something every instance of your API shares (Redis SET key 1 NX PX ttl, a unique database key) when it runs on more than one; MemoryDpopReplayStore protects a single process.
HttpPost
Something that can POST a JSON body with a bearer token. Implemented by the built-in reqwest transport (behind reqwest-transport) and by any mock.
JwksSource
Something that can fetch (and parse) a JWKS from a URL. Implemented by the built-in reqwest transport (behind the reqwest-transport feature) and by any custom/mock transport a caller supplies.
SubjectResolver
Maps a legacy token’s sub (the old provider’s user id) to the Atlas user id. None refuses the token. Implemented for any Fn(&str, &Map<String, Value>) -> Option<String> through LegacyIssuer::resolve_subject, and by [BackendSubjectResolver] (feature backend), which looks the user up by external_id.

Functions§

authenticated_within
Whether auth_time (epoch seconds) is within max_age_seconds of now_ms. A missing or non-finite auth_time is never recent.
build_challenge
An RFC 6750 / RFC 9449 / RFC 9728 challenge for scheme Bearer or DPoP (a DPoP challenge also lists the accepted proof algorithms).
build_www_authenticate
An RFC 6750 / RFC 9728 Bearer challenge. Without error it is the bare “authentication required” challenge (no token was sent).
dpop_access_token_hash
The ath a DPoP proof carries for token: base64url(SHA-256(token)).
is_access_token
Whether key is a one-hour Atlas access token from an operator token exchange (atlas_live_at_…).
is_partner_link_secret
Whether key is a partner-link secret (atlas_live_pl_…).
is_platform_key
Whether key is a platform key in either format (atlas_live_psk_… or psk_…).
is_publishable_key
Whether key is a publishable key (pk_live_… / pk_test_…).
is_secret_key
Whether key is an instance secret key in either format (atlas_live_sk_… or sk_live_…).
is_webhook_secret
Whether key is a webhook signing secret in either format (atlas_live_whsec_… or whsec_…). Webhook verification is unchanged: the whole string is the HMAC key.
jwk_thumbprint
The RFC 7638 SHA-256 thumbprint (base64url) of a public EC, RSA or OKP JWK: the cnf.jkt a DPoP-bound token carries. None for an unsupported or incomplete key.
mfa_org_satisfied
Whether the session meets the active organization’s MFA policy: true when the organization does not require MFA, or the token says org_mfa_ok. The claims describe the ACTIVE organization only: pass org (its Atlas id or external id) to also require that the token’s active organization is that one.
mfa_satisfied
The “requires MFA” rule: the server’s mfa_satisfied verdict when present, else mfa == true, else used_multi_factor, else an enterprise SSO sign-in. The same rule as Claims::mfa_satisfied, over loose values.
normalize_htu
Reduce a URL to the form RFC 9449 §4.3 compares htu in: scheme and host lower-cased, the default port dropped, an empty path as /, no query or fragment. None for anything but an absolute http(s) URL.
oidc_authorize_url_with_organization
Add (or replace) the organization authorize parameter: the sign-in must be made in that organization (a user who is not a member gets access_denied) and the token’s org_* claims are that organization’s.
oidc_organization_of
The organization a sign-in was made in, or None when none was involved.
oidc_organizations_of
Every membership (the orgs claim), or None when the organizations scope was not requested.
oidc_sso_of
The enterprise SSO connection the user signed in through, or None.
parse_key_prefix
Classify a credential by its prefix, accepting the suite format (atlas_live_sk_…) and the legacy one (sk_live_…, pk_test_…, psk_…, whsec_…). None for anything else.
protected_resource_metadata
The RFC 9728 protected-resource metadata document for your API.
protected_resource_metadata_path
The RFC 9728 well-known path for a resource identifier (path-inserted form).
protected_resource_metadata_requiring_dpop
protected_resource_metadata that also advertises dpop_bound_access_tokens_required (pair it with require_dpop).
real_email
Returns Some(email) when email is a real address, or None when it is empty or the @no-email.invalid placeholder. The one function every other email helper funnels through.
system_clock
The default clock: the real system time, in epoch milliseconds.
used_multi_factor
Whether the claims prove a second factor: acr is urn:atlas:acr:mfa, or amr includes mfa.
verify_transaction_token
Verify token against the issuer’s keys. Every failure is one coarse error string; nothing is revealed about which check failed.

Type Aliases§

BoxFuture
A boxed future, so the JwksSource trait stays object-safe without pulling in async-trait (keeps the dependency set minimal).
Clock
A source of “now”, in epoch milliseconds.