Introduction

SessionTether is a TypeScript session-management library for revocable authentication on top of stateless access tokens. It centralizes long-lived refresh-session state while letting API services verify short-lived access tokens locally.

Two layers of trust

Layer	Responsibility	Validation
Access token	Authorize normal API requests	Your JWT or access-token implementation
Refresh session	Decide whether authentication may continue	SessionTether and your session store

An access token says the authentication server trusted a user recently. A refresh token asks whether that trust should continue.

What the library implements

• Cryptographically random opaque refresh tokens and SHA-256 token hashing.
• Named sessions, refresh-token validation, and token rotation.
• A configurable, fixed grace window for consumed-token retries, followed by family revocation on reuse outside that window.
• Per-family and per-user revocation.
• Active-session listing and retention-based cleanup.
• SQLite and PostgreSQL adapters with explicit schema setup helpers.
• Token utilities and scrypt password utilities.

What your application owns

Your application authenticates users, issues and verifies access tokens, authorizes requests, configures cookies, and handles delivery of password-reset links. SessionTether does not issue JWTs.

How a request moves through the system

1. Your application authenticates a user and creates a refresh session.
2. It issues its own short-lived access token and delivers both credentials.
3. API services verify the access token using your application's rules.
4. When renewal is needed, the authentication service asks SessionTether to rotate the refresh token.
5. Successful rotation returns a replacement refresh token. A grace retry returns the user identifier without another replacement.
6. Revoking the family blocks later refresh validation; issued access tokens keep their own expiration.

A family identifies one login session across rotations. Its identifier is stable; the raw refresh credential changes. Use the family identifier for session listing and revocation, and the raw credential for validation and rotation.

Early implementation

These docs describe the current v0.1.0 source. The README's proposed API and planned adapters are not the implemented contract. Both SQL adapters use transactional conditional consumption to prevent duplicate successors. Family revocation is synchronized with rotation, and expiration is rechecked at the locked consumption decision point. Read implementation status before integration.

Where to start

Follow the quick start to configure SQLite and create a session. For a complete local authentication flow, run the example application.