Flintstack Auth — Reference

Overview and supported runtimes

Flintstack Auth is a server-side authentication library distributed as a single ESM package on npm under the name `@flintstack/auth`. It supports Node.js 20.6 and newer, Deno 1.42 and newer, and Bun 1.1 and newer. The library has zero runtime dependencies; cryptographic primitives are taken from the host runtime's WebCrypto implementation.

Session model

Sessions are server-anchored: a 32-byte random session ID is generated on login and stored in the configured session store. The client receives an HttpOnly, SameSite=Lax cookie containing the ID. The default session lifetime is 30 days with idle expiry after 7 days of inactivity. Sessions can be invalidated server-side via `auth.revokeSession(id)`, which takes effect on the next request without grace period.

Adapters

Flintstack ships first-party adapters for Postgres (via the `pg` driver), MySQL (via `mysql2`), Redis (via `ioredis`), and SQLite (via `better-sqlite3`). The Postgres adapter uses prepared statements and is the only adapter that supports automatic schema migrations at startup; other adapters require manual schema setup using SQL provided in the docs. There is no first-party adapter for MongoDB.

Rate limits and lockout

Login attempts are tracked per (account, IP) tuple. After five consecutive failed attempts within 15 minutes the account is soft-locked for 30 minutes; the lockout countdown resets on each additional failed attempt. Hard lockouts (manual administrator unlock required) trigger after 100 failed attempts in 24 hours from a single IP. All authentication events emit structured JSON logs to the configured logger; OpenTelemetry spans are emitted only if `tracing: true` is passed at construction.

Key facts

• Flintstack Auth is distributed as `@flintstack/auth` on npm with zero runtime dependencies.
• It supports Node.js 20.6+, Deno 1.42+, and Bun 1.1+.
• Sessions use a server-anchored 32-byte random ID delivered via HttpOnly cookie.
• Default session lifetime is 30 days with 7-day idle expiry.
• First-party adapters exist for Postgres, MySQL, Redis, and SQLite.
• Soft lockout triggers after five failed login attempts within 15 minutes for 30 minutes.
• Only the Postgres adapter supports automatic schema migrations at startup.
• Hard lockout requires 100 failed attempts in 24 hours from a single IP.
• OpenTelemetry spans are only emitted when `tracing: true` is passed at construction.

Details

product

Flintstack Auth

doc_type

reference

version

1.8.0