Session and signing-key changes in 0.15
Upgrade checklist
- Stop all 0.14 workers before starting 0.15 workers. Mixed-version refresh writers are unsupported. Back up your database before schema migration.
- Postgres: run the normal tracked migration command. Migration 4 adds nullable
authenticated_atto sessions and refresh credentials and deletes all existing refresh credentials. Users must sign in again to obtain refresh credentials; already issued access sessions keep their normal lifetime. - MongoDB: run normal Beanie initialization. It creates the refresh-family coordination collection and indexes. Existing refresh rows have no family state, are rejected, and require a new sign-in. No attempt is made to infer a JWT identity from old random IDs. Old rows can expire normally or be removed during a maintenance window. No replica set is required.
- Custom session strategies with refresh enabled must implement
RefreshSessionStrategy.renew(user, *, session_id, authenticated_at, ip, user_agent). It must preserve authentication age, including an unknown (None) age. Built-in startup validation rejects unsupported strategies. - Configure JWT
grace_period >= expires_in. Shorter grace now fails configuration validation because it could invalidate still-live tokens. - All workers sharing signing-key storage must share algorithm, encryption mode, secret/secret-rotation configuration, lifetime, and grace policy.
The refresh invalidation and fail-closed capability requirement are explicit security exceptions to the normal deprecation window: preserving the old behavior would retain refresh credentials that logout could not invalidate. The database is not rolled back by downgrading the package. Restore a tested backup or keep the additive schema; invalidate refresh credentials and require sign-in before any downgrade. Never resume old workers against active 0.15 Mongo family state.
Logical JWT sessions
New access JWTs contain a protected sid of the form jwt:<32 lowercase hex>.
Reading, refreshing, rotating, exchanging /token, and the set-auth-jwt
response header preserve this identity when based on an existing JWT session.
Custom payload builders cannot overwrite sid, sub, iss, aud, iat,
exp, or auth_time. Public SessionId accepts the new protocol format in
addition to existing database IDs.
JWT sid is a protocol identifier, not a Mongo document reference. Mongo stores
it as a string in refresh credentials; database-session references and all
Mongo-owned user/token/family IDs remain BSON ObjectIds. Arbitrary non-ObjectId
session strings are still rejected by the Mongo adapter.
Legacy access JWTs without sid remain readable until expiry and receive a
stable legacy-jwt:<SHA-256> identity. Their authentication age is unknown.
They cannot renew old refresh families. A new login establishes both a new
logical session identity and a known authentication timestamp.
Logout revokes the logical session's entire refresh family. Revoke-other keeps all refresh evidence for the current family, including consumed ancestors, so replay detection is retained after refresh. Existing access JWTs are still stateless: logout, family revocation, and revoke-other do not instantly invalidate already issued JWTs. They remain cryptographically valid until expiry. This release does not add a JWT denylist or pretend to provide immediate stateless revocation. Fastauth's configured account policy may additionally reject a user when reading a session.
Authentication age
Credential/OTP authentication records authenticated_at. Refresh and access
rotation preserve that value, rather than making a session freshly
authenticated. Existing database sessions and refresh rows default to unknown
(None), never to their migration time. JWTs carry this value as auth_time.
The timestamp is independent of access-token issuance time (iat).
Mongo standalone refresh invariant
For a configured refresh collection Prefresh_tokensS, coordination state is
stored in Prefresh_tokensS_families. A document keyed by the ObjectId family
root contains the active token, its expiry, associated access-session references,
and a revoked flag.
The Mongo adapter's create_refresh_token now starts root families only
(family_id == id before adapter ID normalization). Use
rotate_refresh_token to create successors; direct child insertion cannot
establish a safe consume/publication boundary and is rejected. Custom code
calling RefreshTokenService.persist with a preexisting Mongo family should
use the normal rotate service instead.
Rotation inserts a candidate, then atomically compares and swaps the family's active token while registering the candidate session. Only the CAS winner can publish credentials. Revocation atomically marks this same document revoked before collecting and deleting associated sessions/tokens. A late rotation cannot reopen a revoked family. If deletion fails, the durable revoked state rejects refresh credentials and associated database-session reads; repeating revocation retries cleanup. Once prior access sessions are deleted, their references are removed so an active family's session list remains bounded.
Family tombstones deliberately have no TTL. Do not manually delete or recreate active family state. Retained state consumes one small document per sign-in family; it is not removed by the current expired-token maintenance job. Plan storage retention accordingly. Stale or orphaned candidate credentials from interrupted operations are never published and cannot become the active token.
JWKS shared-worker behavior
The built-in local signer reads shared key state on every sign. Rotation due to
rotation_interval is checked during signing, so ongoing traffic rotates keys
without restarts or a background scheduler. Idle applications rotate on their
next signing operation.
Rotation publishes a replacement before retiring observed old keys. Public keys
remain available until their grace deadline. Concurrent startup or rotation may
create multiple active keys; that is explicitly supported. Workers choose the
newest (created_at, kid) pair deterministically and all published active keys
remain verifiable. This design does not promise exactly one active database row
or use a per-process lock as cross-worker coordination.
Custom KmsSigner implementations must provide equivalent current-key and
retirement guarantees. The built-in coherence guarantee applies to
LocalKmsSigner; a custom signer that caches a retired key cannot inherit it
merely by implementing sign.
Supported first-party matrix and verification
Memory, Postgres, and MongoDB support both database and JWT sessions, with
refresh enabled or disabled. JWT mode requires JwtPlugin and JwksKeyStore.
Memory storage is process-local and is not shared multi-worker storage.
The adapter test suites inherit the same mounted-HTTP matrix: sign-up, session read, refresh, sign-in, revoke-other, logout, and rejected post-logout refresh. They also exercise independent JWKS registries sharing each backend. Mongo has a deterministic revocation-snapshot/rotation race regression and cleanup-failure coverage. Run Docker-backed tests without skips before treating a build as a verified persistent-backend release; a skipped local suite is not evidence of Mongo or Postgres execution.