toklyn

Why I built it

Every project I worked on re-implemented refresh tokens, and most got rotation and reuse detection wrong: tokens that never expire, refreshes that race each other, or a stolen token that keeps working after the user logs out. toklyn is the version I wanted to stop rewriting. You keep your own login logic (passwords, OAuth, magic links), and toklyn takes over from "this user is who they claim to be".

What it does

• Issues short-lived JWT access tokens and long-lived opaque refresh tokens, and stores sessions server-side
• Rotates the refresh token on every refresh and revokes the session when a consumed token is presented again, as RFC 9700 recommends
• Lets you list a user's sessions, revoke one, or sign a user out everywhere
• Runs an onRefresh hook before each refresh, so a disabled user is signed out and role changes reach the next access token
• Verifies tokens offline (signature and expiry, no store call) or online (the session must still be active, and it fails closed if the store is down)

How it works

Refresh tokens look like <sessionId>.<256-bit random>, and only a SHA-256 hash of the whole string is stored, so a database leak does not leak usable tokens. Each session has an absolute lifetime that rotation never extends.

Rotation is a single atomic store operation: validate, consume, insert the successor, or revoke on reuse. Each store implements it natively: one statement per operation on PostgreSQL, a locking transaction on MySQL, conditional updates on MongoDB and Lua scripts on Redis. A shared contract suite in toklyn/testing runs the same checks against every store, including custom ones.

Packages

• toklyn: the core, plus toklyn/http (framework-neutral request handling), toklyn/testing and toklyn/test-utils
• @toklyn/express, @toklyn/fastify, @toklyn/nest and @toklyn/next: middleware, hooks, guards, decorators, route handlers and server-component helpers
• @toklyn/store: PostgreSQL, MySQL/MariaDB, SQLite, MongoDB and Redis/Valkey/Upstash stores

Security model

• Pins the JWT algorithm per key and requires sub, sid, jti, iat and exp (RFC 8725)
• Enforces minimum HMAC key sizes and fails at startup on a missing or weak secret
• Sets cookies HttpOnly, Secure and __Host-, and treats duplicate cookies as missing to block cookie tossing
• Checks Fetch Metadata and Origin on cookie-authenticated writes, and returns identical 401 responses with Cache-Control: no-store
• Publishes JWKS for asymmetric keys, with key caching, refetch on unknown kid and an algorithm allow-list on the verifying side

Engineering and release

• One runtime dependency (jose), Web Crypto only, ESM and CommonJS builds, and types checked with strict and are-the-types-wrong
• CI on Node 22 and 24 against real PostgreSQL, MySQL, MariaDB, MongoDB and Redis, plus Edge Runtime and Bun runs
• Property-based tests, CodeQL, OpenSSF Scorecard and an OpenSSF Best Practices passing badge
• Versioned and published with Changesets; runnable examples for every framework, database and ORM, including Prisma, Drizzle, TypeORM and Mongoose