@lastshotlabs/bunshot 0.0.8 → 0.0.10

package/README.md

@@ -60,6 +60,48 @@ bun add @lastshotlabs/bunshot
 
 ---
 
+## Peer Dependencies
+
+Bunshot declares the following as peer dependencies so you control their versions and avoid duplicate installs in your app.
+
+### Required
+
+These must be installed in every consuming app:
+
+```bash
+bun add hono zod
+```
+
+| Package | Required version |
+|---|---|
+| `hono` | `>=4.12 <5` |
+| `zod` | `>=4.0 <5` |
+
+### Optional
+
+Install only what your app actually uses:
+
+```bash
+# MongoDB auth / sessions / cache
+bun add mongoose
+
+# Redis sessions, cache, rate limiting, or BullMQ
+bun add ioredis
+
+# Background job queues
+bun add bullmq
+```
+
+| Package | Required version | When you need it |
+|---|---|---|
+| `mongoose` | `>=9.0 <10` | `db.auth: "mongo"`, `db.sessions: "mongo"`, or `db.cache: "mongo"` |
+| `ioredis` | `>=5.0 <6` | `db.redis: true` (the default), or any store set to `"redis"` |
+| `bullmq` | `>=5.0 <6` | Workers / queues |
+
+If you're running fully on SQLite or memory (no Redis, no MongoDB), none of the optional peers are needed.
+
+---
+
 ## Quick Start
 
 ```ts
@@ -78,11 +120,15 @@ That's it. Your app gets:
 |---|---|
 | `POST /auth/register` | Create account, returns JWT |
 | `POST /auth/login` | Login, returns JWT (includes `emailVerified` when verification is configured) |
-| `POST /auth/logout` | Invalidates session |
+| `POST /auth/logout` | Invalidates the current session only |
 | `GET /auth/me` | Returns current user's `userId`, `email`, `emailVerified`, and `googleLinked` (requires login) |
 | `POST /auth/set-password` | Set or update password (requires login) |
+| `GET /auth/sessions` | List active sessions with metadata — IP, user-agent, timestamps (requires login) |
+| `DELETE /auth/sessions/:sessionId` | Revoke a specific session by ID (requires login) |
 | `POST /auth/verify-email` | Verify email with token (when `emailVerification` is configured) |
 | `POST /auth/resend-verification` | Resend verification email (requires login, when `emailVerification` is configured) |
+| `POST /auth/forgot-password` | Request a password reset email (when `passwordReset` is configured) |
+| `POST /auth/reset-password` | Reset password using a token from the reset email (when `passwordReset` is configured) |
 | `GET /health` | Health check |
 | `GET /docs` | Scalar API docs UI |
 | `GET /openapi.json` | OpenAPI spec |
@@ -195,18 +241,31 @@ await createServer({
 
 Import `appConnection` and register models on it. This ensures your models use the correct connection whether you're on a single DB or a separate tenant DB.
 
+`appConnection` is a lazy proxy — calling `.model()` at the top level works fine even before `connectMongo()` has been called. Mongoose buffers any queries until the connection is established.
+
 ```ts
 // src/models/Product.ts
-import { appConnection, mongoose } from "@lastshotlabs/bunshot";
+import { appConnection } from "@lastshotlabs/bunshot";
+import { Schema } from "mongoose";
+import type { HydratedDocument } from "mongoose";
+
+interface IProduct {
+  name: string;
+  price: number;
+}
 
-const ProductSchema = new mongoose.Schema({
+export type ProductDocument = HydratedDocument<IProduct>;
+
+const ProductSchema = new Schema<IProduct>({
   name: { type: String, required: true },
   price: { type: Number, required: true },
 }, { timestamps: true });
 
-export const Product = appConnection.model("Product", ProductSchema);
+export const Product = appConnection.model<IProduct>("Product", ProductSchema);
 ```
 
+> **Note:** Import types (`HydratedDocument`, `Schema`, etc.) directly from `"mongoose"` — the `appConnection` and `mongoose` exports from bunshot are runtime proxies and cannot be used as TypeScript namespaces.
+
 ---
 
 ## Jobs (BullMQ)
@@ -722,13 +781,27 @@ await createServer({
         await resend.emails.send({ to: email, subject: "Verify your email", text: `Token: ${token}` });
       },
     },
+    passwordReset: {                        // optional — only active when primaryField is "email"
+      tokenExpiry: 60 * 60,                 // default: 3600 (1 hour) — token TTL in seconds
+      onSend: async (email, token) => {     // called by POST /auth/forgot-password — use any email provider
+        await resend.emails.send({ to: email, subject: "Reset your password", text: `Token: ${token}` });
+      },
+    },
     rateLimit: {                            // optional — built-in auth endpoint rate limiting
       login:              { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 failures / 15 min
       register:           { windowMs: 60 * 60 * 1000, max: 5  }, // default: 5 attempts / hour (per IP)
       verifyEmail:        { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
       resendVerification: { windowMs: 60 * 60 * 1000, max: 3  }, // default: 3 attempts / hour (per user)
+      forgotPassword:     { windowMs: 15 * 60 * 1000, max: 5  }, // default: 5 attempts / 15 min (per IP)
+      resetPassword:      { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
       store: "redis",                       // default: "redis" when Redis is enabled, else "memory"
     },
+    sessionPolicy: {                        // optional — session concurrency and metadata
+      maxSessions: 6,                       // default: 6 — max simultaneous sessions per user; oldest evicted when exceeded
+      persistSessionMetadata: true,         // default: true — keep IP/UA/timestamp row after session expires (for device detection)
+      includeInactiveSessions: false,       // default: false — include expired/deleted sessions in GET /auth/sessions
+      trackLastActive: false,               // default: false — update lastActiveAt on every auth'd request (adds one DB write)
+    },
     oauth: {
       providers: { google: { ... }, apple: { ... } }, // omit a provider to disable it
       postRedirect: "/dashboard",           // default: "/"
@@ -791,7 +864,7 @@ await createServer({
 });
 ```
 
-Redis key namespacing: when Redis is used, all keys are prefixed with `appName` (`session:{appName}:{userId}`, `oauth:{appName}:state:{state}`, `cache:{appName}:{key}`) so multiple apps sharing one Redis instance never collide.
+Redis key namespacing: when Redis is used, all keys are prefixed with `appName` (`session:{appName}:{sessionId}`, `usersessions:{appName}:{userId}`, `oauth:{appName}:state:{state}`, `cache:{appName}:{key}`) so multiple apps sharing one Redis instance never collide.
 
 ---
 
@@ -860,7 +933,7 @@ clearMemoryStore();
 
 ## Auth Flow
 
-Sessions are backed by Redis by default (`session:{appName}:{userId}`). Set `db.sessions: "mongo"` to store them in MongoDB instead — useful when running without Redis. See [Running without Redis](#running-without-redis).
+Sessions are backed by Redis by default. Each login creates an independent session keyed by a UUID (`session:{appName}:{sessionId}`), so multiple devices / tabs can be logged in simultaneously. Set `db.sessions: "mongo"` to store them in MongoDB instead — useful when running without Redis. See [Running without Redis](#running-without-redis).
 
 ### Browser clients
 1. `POST /auth/login` → JWT set as HttpOnly cookie automatically
@@ -870,6 +943,20 @@ Sessions are backed by Redis by default (`session:{appName}:{userId}`). Set `db.
 1. `POST /auth/login` → read `token` from response body
 2. Send `x-user-token: <token>` header on every request
 
+### Session management
+
+Each login creates an independent session so multiple devices stay logged in simultaneously. The framework enforces a configurable cap (default: 6) — the oldest session is evicted when the limit is exceeded.
+
+```
+GET    /auth/sessions             → [{ sessionId, createdAt, lastActiveAt, expiresAt, ipAddress, userAgent, isActive }]
+DELETE /auth/sessions/:sessionId  → revoke a specific session (other sessions unaffected)
+POST   /auth/logout               → revoke only the current session
+```
+
+Session metadata (IP address, user-agent, timestamps) is persisted even after a session expires when `sessionPolicy.persistSessionMetadata: true` (default). This enables tenant apps to detect logins from novel devices or locations and prompt for MFA or send a security alert.
+
+Set `sessionPolicy.includeInactiveSessions: true` to surface expired/deleted sessions in `GET /auth/sessions` with `isActive: false` — useful for a full device-history UI similar to Google or Meta's account security page.
+
 ### Protecting routes
 
 ```ts
@@ -972,6 +1059,8 @@ All built-in auth endpoints are rate-limited out of the box with sensible defaul
 | `POST /auth/register` | IP address | Every attempt | 5 / hour |
 | `POST /auth/verify-email` | IP address | Every attempt | 10 / 15 min |
 | `POST /auth/resend-verification` | User ID (authenticated) | Every attempt | 3 / hour |
+| `POST /auth/forgot-password` | IP address | Every attempt | 5 / 15 min |
+| `POST /auth/reset-password` | IP address | Every attempt | 10 / 15 min |
 
 Login is keyed by the **identifier being targeted** — an attacker rotating IPs to brute-force `alice@example.com` is blocked regardless of source IP. A successful login resets the counter so legitimate users aren't locked out.
 
@@ -1454,7 +1543,8 @@ import {
 
   // Auth utilities
   signToken, verifyToken,
-  createSession, getSession, deleteSession, setSessionStore,
+  createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount,
+  evictOldestSession, updateSessionLastActive, setSessionStore,
   createVerificationToken, getVerificationToken, deleteVerificationToken,  // email verification tokens
   bustAuthLimit, trackAttempt, isLimited,          // auth rate limiting — use in custom routes or admin unlocks
   buildFingerprint,                                // HTTP fingerprint hash (IP-independent) — use in custom bot detection logic

package/dist/adapters/memoryAuth.d.ts

@@ -1,10 +1,15 @@
 import type { AuthAdapter } from "../lib/authAdapter";
+import type { SessionMetadata, SessionInfo } from "../lib/session";
 /** Reset all in-memory state. Useful for test isolation. */
 export declare const clearMemoryStore: () => void;
 export declare const memoryAuthAdapter: AuthAdapter;
-export declare const memoryCreateSession: (userId: string, token: string) => void;
-export declare const memoryGetSession: (userId: string) => string | null;
-export declare const memoryDeleteSession: (userId: string) => void;
+export declare const memoryCreateSession: (userId: string, token: string, sessionId: string, metadata?: SessionMetadata) => void;
+export declare const memoryGetSession: (sessionId: string) => string | null;
+export declare const memoryDeleteSession: (sessionId: string) => void;
+export declare const memoryGetUserSessions: (userId: string) => SessionInfo[];
+export declare const memoryGetActiveSessionCount: (userId: string) => number;
+export declare const memoryEvictOldestSession: (userId: string) => void;
+export declare const memoryUpdateSessionLastActive: (sessionId: string) => void;
 export declare const memoryStoreOAuthState: (state: string, codeVerifier?: string, linkUserId?: string) => void;
 export declare const memoryConsumeOAuthState: (state: string) => {
     codeVerifier?: string;
@@ -20,3 +25,8 @@ export declare const memoryGetVerificationToken: (token: string) => {
     email: string;
 } | null;
 export declare const memoryDeleteVerificationToken: (token: string) => void;
+export declare const memoryCreateResetToken: (token: string, userId: string, email: string, ttlSeconds: number) => void;
+export declare const memoryConsumeResetToken: (hash: string) => {
+    userId: string;
+    email: string;
+} | null;

package/dist/adapters/memoryAuth.js

@@ -1,18 +1,23 @@
 import { HttpError } from "../lib/HttpError";
+import { getPersistSessionMetadata, getIncludeInactiveSessions } from "../lib/appConfig";
 const _users = new Map();
 const _byEmail = new Map();
-const _sessions = new Map();
+const _sessions = new Map(); // sessionId → session
+const _userSessionIds = new Map(); // userId → Set<sessionId>
 const _oauthStates = new Map();
 const _cache = new Map();
 const _verificationTokens = new Map();
+const _resetTokens = new Map();
 /** Reset all in-memory state. Useful for test isolation. */
 export const clearMemoryStore = () => {
     _users.clear();
     _byEmail.clear();
     _sessions.clear();
+    _userSessionIds.clear();
     _oauthStates.clear();
     _cache.clear();
     _verificationTokens.clear();
+    _resetTokens.clear();
 };
 // ---------------------------------------------------------------------------
 // Auth adapter
@@ -132,17 +137,99 @@ export const memoryAuthAdapter = {
 // Session helpers (used by src/lib/session.ts)
 // ---------------------------------------------------------------------------
 const SESSION_TTL_MS = 60 * 60 * 24 * 7 * 1000; // 7 days
-export const memoryCreateSession = (userId, token) => {
-    _sessions.set(userId, { token, expiresAt: Date.now() + SESSION_TTL_MS });
+export const memoryCreateSession = (userId, token, sessionId, metadata) => {
+    const now = Date.now();
+    const session = {
+        sessionId, userId, token,
+        createdAt: now, lastActiveAt: now, expiresAt: now + SESSION_TTL_MS,
+        ipAddress: metadata?.ipAddress,
+        userAgent: metadata?.userAgent,
+    };
+    _sessions.set(sessionId, session);
+    if (!_userSessionIds.has(userId))
+        _userSessionIds.set(userId, new Set());
+    _userSessionIds.get(userId).add(sessionId);
 };
-export const memoryGetSession = (userId) => {
-    const entry = _sessions.get(userId);
-    if (!entry || entry.expiresAt <= Date.now())
+export const memoryGetSession = (sessionId) => {
+    const entry = _sessions.get(sessionId);
+    if (!entry || !entry.token || entry.expiresAt <= Date.now())
         return null;
     return entry.token;
 };
-export const memoryDeleteSession = (userId) => {
-    _sessions.delete(userId);
+export const memoryDeleteSession = (sessionId) => {
+    const entry = _sessions.get(sessionId);
+    if (!entry)
+        return;
+    if (getPersistSessionMetadata()) {
+        entry.token = null;
+    }
+    else {
+        _sessions.delete(sessionId);
+        _userSessionIds.get(entry.userId)?.delete(sessionId);
+    }
+};
+export const memoryGetUserSessions = (userId) => {
+    const ids = _userSessionIds.get(userId);
+    if (!ids)
+        return [];
+    const now = Date.now();
+    const includeInactive = getIncludeInactiveSessions();
+    const persist = getPersistSessionMetadata();
+    const results = [];
+    for (const sessionId of ids) {
+        const s = _sessions.get(sessionId);
+        if (!s)
+            continue;
+        const isActive = !!s.token && s.expiresAt > now;
+        if (!isActive && !persist)
+            continue;
+        if (!isActive && !includeInactive)
+            continue;
+        results.push({
+            sessionId: s.sessionId,
+            createdAt: s.createdAt,
+            lastActiveAt: s.lastActiveAt,
+            expiresAt: s.expiresAt,
+            ipAddress: s.ipAddress,
+            userAgent: s.userAgent,
+            isActive,
+        });
+    }
+    return results;
+};
+export const memoryGetActiveSessionCount = (userId) => {
+    const ids = _userSessionIds.get(userId);
+    if (!ids)
+        return 0;
+    const now = Date.now();
+    let count = 0;
+    for (const sessionId of ids) {
+        const s = _sessions.get(sessionId);
+        if (s && s.token && s.expiresAt > now)
+            count++;
+    }
+    return count;
+};
+export const memoryEvictOldestSession = (userId) => {
+    const ids = _userSessionIds.get(userId);
+    if (!ids)
+        return;
+    const now = Date.now();
+    let oldest = null;
+    for (const sessionId of ids) {
+        const s = _sessions.get(sessionId);
+        if (!s || !s.token || s.expiresAt <= now)
+            continue;
+        if (!oldest || s.createdAt < oldest.createdAt)
+            oldest = s;
+    }
+    if (oldest)
+        memoryDeleteSession(oldest.sessionId);
+};
+export const memoryUpdateSessionLastActive = (sessionId) => {
+    const entry = _sessions.get(sessionId);
+    if (entry)
+        entry.lastActiveAt = Date.now();
 };
 // ---------------------------------------------------------------------------
 // OAuth state helpers (used by src/lib/oauth.ts)
@@ -205,3 +292,24 @@ export const memoryGetVerificationToken = (token) => {
 export const memoryDeleteVerificationToken = (token) => {
     _verificationTokens.delete(token);
 };
+// ---------------------------------------------------------------------------
+// Password reset token helpers (used by src/lib/resetPassword.ts)
+// ---------------------------------------------------------------------------
+export const memoryCreateResetToken = (token, userId, email, ttlSeconds) => {
+    const now = Date.now();
+    // Opportunistically purge expired entries to prevent unbounded memory growth
+    for (const [k, v] of _resetTokens) {
+        if (v.expiresAt <= now)
+            _resetTokens.delete(k);
+    }
+    _resetTokens.set(token, { userId, email, expiresAt: now + ttlSeconds * 1000 });
+};
+export const memoryConsumeResetToken = (hash) => {
+    const entry = _resetTokens.get(hash);
+    if (!entry || entry.expiresAt <= Date.now()) {
+        _resetTokens.delete(hash);
+        return null;
+    }
+    _resetTokens.delete(hash);
+    return { userId: entry.userId, email: entry.email };
+};

package/dist/adapters/sqliteAuth.d.ts

@@ -1,9 +1,14 @@
 import type { AuthAdapter } from "../lib/authAdapter";
 export declare const setSqliteDb: (path: string) => void;
 export declare const sqliteAuthAdapter: AuthAdapter;
-export declare const sqliteCreateSession: (userId: string, token: string) => void;
-export declare const sqliteGetSession: (userId: string) => string | null;
-export declare const sqliteDeleteSession: (userId: string) => void;
+import type { SessionMetadata, SessionInfo } from "../lib/session";
+export declare const sqliteCreateSession: (userId: string, token: string, sessionId: string, metadata?: SessionMetadata) => void;
+export declare const sqliteGetSession: (sessionId: string) => string | null;
+export declare const sqliteDeleteSession: (sessionId: string) => void;
+export declare const sqliteGetUserSessions: (userId: string) => SessionInfo[];
+export declare const sqliteGetActiveSessionCount: (userId: string) => number;
+export declare const sqliteEvictOldestSession: (userId: string) => void;
+export declare const sqliteUpdateSessionLastActive: (sessionId: string) => void;
 export declare const sqliteStoreOAuthState: (state: string, codeVerifier?: string, linkUserId?: string) => void;
 export declare const sqliteConsumeOAuthState: (state: string) => {
     codeVerifier?: string;
@@ -20,4 +25,9 @@ export declare const sqliteGetVerificationToken: (token: string) => {
     email: string;
 } | null;
 export declare const sqliteDeleteVerificationToken: (token: string) => void;
+export declare const sqliteCreateResetToken: (token: string, userId: string, email: string, ttlSeconds: number) => void;
+export declare const sqliteConsumeResetToken: (hash: string) => {
+    userId: string;
+    email: string;
+} | null;
 export declare const startSqliteCleanup: (intervalMs?: number) => ReturnType<typeof setInterval>;

package/dist/adapters/sqliteAuth.js

@@ -32,11 +32,22 @@ function initSchema(db) {
         db.run("ALTER TABLE users ADD COLUMN emailVerified INTEGER NOT NULL DEFAULT 0");
     }
     catch { /* already exists */ }
+    // Migrate legacy sessions table (userId PK) to new multi-session schema (sessionId PK)
+    try {
+        db.run("ALTER TABLE sessions RENAME TO sessions_legacy");
+    }
+    catch { /* already migrated */ }
     db.run(`CREATE TABLE IF NOT EXISTS sessions (
-    userId    TEXT PRIMARY KEY,
-    token     TEXT NOT NULL,
-    expiresAt INTEGER NOT NULL
+    sessionId    TEXT PRIMARY KEY,
+    userId       TEXT NOT NULL,
+    token        TEXT,
+    createdAt    INTEGER NOT NULL,
+    lastActiveAt INTEGER NOT NULL,
+    expiresAt    INTEGER NOT NULL,
+    ipAddress    TEXT,
+    userAgent    TEXT
   )`);
+    db.run("CREATE INDEX IF NOT EXISTS idx_sessions_userId ON sessions(userId)");
     db.run(`CREATE TABLE IF NOT EXISTS oauth_states (
     state        TEXT PRIMARY KEY,
     codeVerifier TEXT,
@@ -54,6 +65,12 @@ function initSchema(db) {
     email     TEXT NOT NULL,
     expiresAt INTEGER NOT NULL
   )`);
+    db.run(`CREATE TABLE IF NOT EXISTS password_resets (
+    token     TEXT PRIMARY KEY,
+    userId    TEXT NOT NULL,
+    email     TEXT NOT NULL,
+    expiresAt INTEGER NOT NULL
+  )`);
 }
 // ---------------------------------------------------------------------------
 // Auth adapter
@@ -161,20 +178,63 @@ export const sqliteAuthAdapter = {
         return row?.emailVerified === 1;
     },
 };
-// ---------------------------------------------------------------------------
-// Session helpers (used by src/lib/session.ts)
-// ---------------------------------------------------------------------------
+import { getPersistSessionMetadata, getIncludeInactiveSessions } from "../lib/appConfig";
 const SESSION_TTL_MS = 60 * 60 * 24 * 7 * 1000; // 7 days
-export const sqliteCreateSession = (userId, token) => {
-    const expiresAt = Date.now() + SESSION_TTL_MS;
-    getDb().run("INSERT INTO sessions (userId, token, expiresAt) VALUES (?, ?, ?) ON CONFLICT(userId) DO UPDATE SET token = excluded.token, expiresAt = excluded.expiresAt", [userId, token, expiresAt]);
+export const sqliteCreateSession = (userId, token, sessionId, metadata) => {
+    const now = Date.now();
+    const expiresAt = now + SESSION_TTL_MS;
+    getDb().run("INSERT INTO sessions (sessionId, userId, token, createdAt, lastActiveAt, expiresAt, ipAddress, userAgent) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [sessionId, userId, token, now, now, expiresAt, metadata?.ipAddress ?? null, metadata?.userAgent ?? null]);
+};
+export const sqliteGetSession = (sessionId) => {
+    const row = getDb().query("SELECT token FROM sessions WHERE sessionId = ? AND expiresAt > ?").get(sessionId, Date.now());
+    if (!row || !row.token)
+        return null;
+    return row.token;
+};
+export const sqliteDeleteSession = (sessionId) => {
+    if (getPersistSessionMetadata()) {
+        getDb().run("UPDATE sessions SET token = NULL WHERE sessionId = ?", [sessionId]);
+    }
+    else {
+        getDb().run("DELETE FROM sessions WHERE sessionId = ?", [sessionId]);
+    }
+};
+export const sqliteGetUserSessions = (userId) => {
+    const now = Date.now();
+    const rows = getDb().query("SELECT sessionId, token, createdAt, lastActiveAt, expiresAt, ipAddress, userAgent FROM sessions WHERE userId = ? ORDER BY createdAt ASC").all(userId);
+    const includeInactive = getIncludeInactiveSessions();
+    const persist = getPersistSessionMetadata();
+    const results = [];
+    for (const row of rows) {
+        const isActive = !!row.token && row.expiresAt > now;
+        if (!isActive && !persist)
+            continue;
+        if (!isActive && !includeInactive)
+            continue;
+        results.push({
+            sessionId: row.sessionId,
+            createdAt: row.createdAt,
+            lastActiveAt: row.lastActiveAt,
+            expiresAt: row.expiresAt,
+            ipAddress: row.ipAddress ?? undefined,
+            userAgent: row.userAgent ?? undefined,
+            isActive,
+        });
+    }
+    return results;
 };
-export const sqliteGetSession = (userId) => {
-    const row = getDb().query("SELECT token FROM sessions WHERE userId = ? AND expiresAt > ?").get(userId, Date.now());
-    return row?.token ?? null;
+export const sqliteGetActiveSessionCount = (userId) => {
+    const row = getDb().query("SELECT COUNT(*) AS count FROM sessions WHERE userId = ? AND token IS NOT NULL AND expiresAt > ?").get(userId, Date.now());
+    return row?.count ?? 0;
 };
-export const sqliteDeleteSession = (userId) => {
-    getDb().run("DELETE FROM sessions WHERE userId = ?", [userId]);
+export const sqliteEvictOldestSession = (userId) => {
+    const now = Date.now();
+    const oldest = getDb().query("SELECT sessionId FROM sessions WHERE userId = ? AND token IS NOT NULL AND expiresAt > ? ORDER BY createdAt ASC LIMIT 1").get(userId, now);
+    if (oldest)
+        sqliteDeleteSession(oldest.sessionId);
+};
+export const sqliteUpdateSessionLastActive = (sessionId) => {
+    getDb().run("UPDATE sessions SET lastActiveAt = ? WHERE sessionId = ?", [Date.now(), sessionId]);
 };
 // ---------------------------------------------------------------------------
 // OAuth state helpers (used by src/lib/oauth.ts)
@@ -228,15 +288,33 @@ export const sqliteDeleteVerificationToken = (token) => {
     getDb().run("DELETE FROM email_verifications WHERE token = ?", [token]);
 };
 // ---------------------------------------------------------------------------
+// Password reset token helpers (used by src/lib/resetPassword.ts)
+// ---------------------------------------------------------------------------
+export const sqliteCreateResetToken = (token, userId, email, ttlSeconds) => {
+    const expiresAt = Date.now() + ttlSeconds * 1000;
+    getDb().run("INSERT INTO password_resets (token, userId, email, expiresAt) VALUES (?, ?, ?, ?)", [token, userId, email, expiresAt]);
+};
+export const sqliteConsumeResetToken = (hash) => {
+    const row = getDb().query("DELETE FROM password_resets WHERE token = ? AND expiresAt > ? RETURNING userId, email").get(hash, Date.now());
+    return row ?? null;
+};
+// ---------------------------------------------------------------------------
 // Optional periodic cleanup of expired rows
 // ---------------------------------------------------------------------------
 export const startSqliteCleanup = (intervalMs = 3_600_000) => {
     return setInterval(() => {
         const db = getDb();
         const now = Date.now();
-        db.run("DELETE FROM sessions WHERE expiresAt <= ?", [now]);
+        if (getPersistSessionMetadata()) {
+            // Null out tokens for expired sessions but keep the metadata row
+            db.run("UPDATE sessions SET token = NULL WHERE expiresAt <= ? AND token IS NOT NULL", [now]);
+        }
+        else {
+            db.run("DELETE FROM sessions WHERE expiresAt <= ?", [now]);
+        }
         db.run("DELETE FROM oauth_states WHERE expiresAt <= ?", [now]);
         db.run("DELETE FROM cache_entries WHERE expiresAt IS NOT NULL AND expiresAt <= ?", [now]);
         db.run("DELETE FROM email_verifications WHERE expiresAt <= ?", [now]);
+        db.run("DELETE FROM password_resets WHERE expiresAt <= ?", [now]);
     }, intervalMs);
 };

package/dist/app.d.ts

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { MiddlewareHandler } from "hono";
 import type { AppEnv } from "./lib/context";
-import type { PrimaryField, EmailVerificationConfig } from "./lib/appConfig";
+import type { PrimaryField, EmailVerificationConfig, PasswordResetConfig } from "./lib/appConfig";
 import type { AuthAdapter } from "./lib/authAdapter";
 import type { OAuthProviderConfig } from "./lib/oauth";
 type StoreType = "redis" | "mongo" | "sqlite" | "memory";
@@ -82,6 +82,16 @@ export interface AuthRateLimitConfig {
         windowMs?: number;
         max?: number;
     };
+    /** Max forgot-password requests per IP per window. Default: 5 per 15 min. */
+    forgotPassword?: {
+        windowMs?: number;
+        max?: number;
+    };
+    /** Max reset-password attempts per IP per window. Default: 10 per 15 min. */
+    resetPassword?: {
+        windowMs?: number;
+        max?: number;
+    };
     /**
      * Store backend for auth rate limit counters.
      * Defaults to "redis" when Redis is enabled, otherwise "memory".
@@ -116,10 +126,37 @@ export interface AuthConfig {
      * Provide an onSend callback to send the verification email via any provider (Resend, SendGrid, etc.).
      */
     emailVerification?: EmailVerificationConfig;
+    /**
+     * Password reset configuration. Only active when primaryField is "email".
+     * Provide an onSend callback to send the reset email via any provider (Resend, SendGrid, etc.).
+     * Mounts POST /auth/forgot-password and POST /auth/reset-password.
+     */
+    passwordReset?: PasswordResetConfig;
     /** Rate limit configuration for built-in auth endpoints. */
     rateLimit?: AuthRateLimitConfig;
+    /** Session concurrency and metadata persistence policy. */
+    sessionPolicy?: AuthSessionPolicyConfig;
+}
+export interface AuthSessionPolicyConfig {
+    /** Max simultaneous active sessions per user. Oldest is evicted when exceeded. Default: 6. */
+    maxSessions?: number;
+    /**
+     * Retain session metadata (IP, user-agent, timestamps) after a session expires or is deleted.
+     * Enables future novel-device/location detection. Default: true.
+     */
+    persistSessionMetadata?: boolean;
+    /**
+     * Include inactive (expired/deleted) sessions in GET /auth/sessions.
+     * Only meaningful when persistSessionMetadata is true. Default: false.
+     */
+    includeInactiveSessions?: boolean;
+    /**
+     * Update lastActiveAt on every authenticated request.
+     * Adds one DB write per auth'd request. Default: false.
+     */
+    trackLastActive?: boolean;
 }
-export type { PrimaryField, EmailVerificationConfig };
+export type { PrimaryField, EmailVerificationConfig, PasswordResetConfig };
 export interface BotProtectionConfig {
     /**
      * List of IPv4 CIDRs (e.g. "198.51.100.0/24"), IPv4 addresses, or IPv6 addresses to block outright.