Implementation status

This documentation follows the current v0.1.0 implementation in src/, including working-tree changes. The repository README also contains proposals; those are not promises of available behavior.

Available now

Feature	Current implementation
Opaque refresh tokens	32 random bytes encoded as base64url
Stored token hashes	SHA-256, hex encoded
Session creation	Family and initial token commit together in one SQL transaction
Validation	Missing, revoked, consumed, and expired checks
Rotation	Conditional consumption and replacement in one SQL transaction
Retry grace	Fixed reuseGraceTTL window; default 30 seconds, 0 disables it
Replay response	Consumed-token reuse outside grace revokes its family
Revocation	One family or all families belonging to a user
Revocation ordering	Active-family write lock serializes SQL rotation with both revocation methods
Session listing	All families or only active families
Cleanup	Retention-based removal of inactive families and tokens
SQLite	Knex-based adapter and table setup helper
PostgreSQL	Knex/pg adapter, table setup helper, and BIGINT timestamp normalization
Password helpers	scrypt hashing and timing-safe comparison
Public store types	SessionStore, RefreshTokenDetails, SessionSummary, and PruneResult

Current limits

• Expiration is checked before rotation and rechecked at the locked consumption decision point; expiry after that decision does not abort commit. Family revocation is synchronized with rotation through an active-family write lock.
• Rotation extends the replacement token's expiration by expiryTTL. There is no separate absolute family lifetime or idle timeout configuration.
• There is no built-in JWT issuer, access-token TTL option, security-version API, Express middleware, or Fastify/NestJS integration.
• MongoDB, Redis, and memory adapters are not included.
• revokeSession() forwards its argument directly to the store. Pass the family's tokenHash identifier, not a raw refresh token.
• The schema helper creates missing tables; it does not migrate existing table layouts.

The Policies & Guarantees page defines the required correctness contract and identifies the current gaps. A configurable grace window and consumed-token conflict handling are implemented. Broader policy selection and a full shared adapter conformance suite remain unfinished.

Design documents

The repository's docs/architecture/ and docs/threat-model.md contain architectural questions and unresolved decisions. docs/decisions/ defines the ADR workflow. TODO items and examples in those files do not establish implemented guarantees.