Skip to content

Session and signing-key changes in 0.15

Upgrade checklist

  1. Stop all 0.14 workers before starting 0.15 workers. Mixed-version refresh writers are unsupported. Back up your database before schema migration.
  2. Postgres: run the normal tracked migration command. Migration 4 adds nullable authenticated_at to 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.
  3. 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.
  4. 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.
  5. Configure JWT grace_period >= expires_in. Shorter grace now fails configuration validation because it could invalidate still-live tokens.
  6. 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.