Architecture

SessionTether puts centralized state at the refresh boundary. Ordinary API traffic can continue using local access-token verification.

Request boundaries

Client ── access token ──→ API services
                          └─ verify locally

Client ── refresh token ─→ Authentication service
                          ├─ SessionTether
                          ├─ SessionStore / SQL adapter
                          └─ application access-token issuer

The core hashes incoming refresh credentials, asks the store for token and family state, validates eligibility, and delegates mutations to the store.

Semantics and mechanics

SessionTether owns the semantics. Database adapters own the mechanics. Both must preserve the contract. The core defines lifecycle policy and valid state transitions; adapters must implement the persistence and synchronization needed to preserve those transitions under concurrency and failures.

The required invariants, ownership matrix, and current implementation gaps are documented in Policies & Guarantees. These are design requirements, not claims that either SQL adapter satisfies the complete contract.

Token families

A family represents one named login session. Rotation adds token history to the same family. Revocation changes family state, invalidating every token in that family for future refresh validation.

In both SQL adapters, the family identifier is the SHA-256 hash of the initial refresh token. It stays the same as subsequent tokens rotate.

Table	Purpose
session_families	User UUID, stable family identifier, name, revocation timestamp
refresh_tokens	Individual token hashes, family references, consumption and expiration

The raw refresh token is returned to your application and is never written to these tables by the library.

Application responsibilities

SessionTether does not authenticate passwords or issue access tokens as part of creating a session. Your application combines those actions:

1. Verify the user's credentials.
2. Create a refresh session.
3. Issue an access token using your chosen issuer.
4. Deliver the credentials to the client.
5. Validate access tokens at your API boundary.
6. Use SessionTether when authentication needs renewal.

The included example demonstrates this split using jose for JWTs and SQLite for refresh sessions.

Revocation latency

Revoking a refresh family blocks future renewal. It cannot recall an already-issued, self-contained JWT. Immediate access-token invalidation requires an additional application mechanism such as a denylist or introspection, adding state to the request path.

Choose your own access-token lifetime based on the revocation delay your application can tolerate. SessionTether has no access-token lifetime setting.