@lastshotlabs/bunshot 0.0.7 → 0.0.9

package/README.md

@@ -78,9 +78,11 @@ 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) |
 | `GET /health` | Health check |
@@ -729,6 +731,12 @@ await createServer({
       resendVerification: { windowMs: 60 * 60 * 1000, max: 3  }, // default: 3 attempts / hour (per user)
       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 +799,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 +868,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 +878,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
@@ -1454,7 +1476,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;

package/dist/adapters/memoryAuth.js

@@ -1,7 +1,9 @@
 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();
@@ -10,6 +12,7 @@ export const clearMemoryStore = () => {
     _users.clear();
     _byEmail.clear();
     _sessions.clear();
+    _userSessionIds.clear();
     _oauthStates.clear();
     _cache.clear();
     _verificationTokens.clear();
@@ -132,17 +135,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)

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;

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,
@@ -161,20 +172,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 = (userId) => {
-    const row = getDb().query("SELECT token FROM sessions WHERE userId = ? AND expiresAt > ?").get(userId, Date.now());
-    return row?.token ?? 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 = (userId) => {
-    getDb().run("DELETE FROM sessions WHERE userId = ?", [userId]);
+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 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 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)
@@ -234,7 +288,13 @@ 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]);

package/dist/app.d.ts

@@ -118,6 +118,27 @@ export interface AuthConfig {
     emailVerification?: EmailVerificationConfig;
     /** 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 interface BotProtectionConfig {

package/dist/app.js

@@ -8,7 +8,7 @@ import { rateLimit } from "./middleware/rateLimit";
 import { bearerAuth } from "./middleware/bearerAuth";
 import { identify } from "./middleware/identify";
 import { HEADER_USER_TOKEN } from "./lib/constants";
-import { setAppName, setAppRoles, setDefaultRole, setPrimaryField, setEmailVerificationConfig } from "./lib/appConfig";
+import { setAppName, setAppRoles, setDefaultRole, setPrimaryField, setEmailVerificationConfig, setMaxSessions, setPersistSessionMetadata, setIncludeInactiveSessions, setTrackLastActive } from "./lib/appConfig";
 import { setEmailVerificationStore } from "./lib/emailVerification";
 import { setAuthRateLimitStore } from "./lib/authRateLimit";
 import { setAuthAdapter } from "./lib/authAdapter";
@@ -40,6 +40,7 @@ export const createApp = async (config) => {
     const primaryField = authConfig.primaryField ?? "email";
     const emailVerification = authConfig.emailVerification;
     const authRateLimit = authConfig.rateLimit;
+    const sessionPolicy = authConfig.sessionPolicy ?? {};
     const { sqlite, mongo = "single", redis: enableRedis = true } = db;
     // Smart fallback: pick the best available store rather than blindly defaulting to "redis"
     const defaultStore = enableRedis
@@ -88,6 +89,10 @@ export const createApp = async (config) => {
     setEmailVerificationConfig(emailVerification ?? null);
     setEmailVerificationStore(sessions);
     setAuthRateLimitStore(authRateLimit?.store ?? (enableRedis ? "redis" : "memory"));
+    setMaxSessions(sessionPolicy.maxSessions ?? 6);
+    setPersistSessionMetadata(sessionPolicy.persistSessionMetadata ?? true);
+    setIncludeInactiveSessions(sessionPolicy.includeInactiveSessions ?? false);
+    setTrackLastActive(sessionPolicy.trackLastActive ?? false);
     if (defaultRole && !authAdapter.setRoles) {
         throw new Error(`createApp: "defaultRole" is set to "${defaultRole}" but the auth adapter does not implement setRoles. Add setRoles to your adapter or remove defaultRole.`);
     }

package/dist/index.d.ts

@@ -13,7 +13,8 @@ export { connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo, authC
 export { connectRedis, disconnectRedis, getRedis } from "./lib/redis";
 export { createQueue, createWorker } from "./lib/queue";
 export type { Job } from "./lib/queue";
-export { createSession, getSession, deleteSession, setSessionStore } from "./lib/session";
+export { createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount, evictOldestSession, updateSessionLastActive, setSessionStore } from "./lib/session";
+export type { SessionMetadata, SessionInfo } from "./lib/session";
 export { createVerificationToken, getVerificationToken, deleteVerificationToken } from "./lib/emailVerification";
 export { bustAuthLimit, trackAttempt, isLimited } from "./lib/authRateLimit";
 export type { LimitOpts } from "./lib/authRateLimit";

package/dist/index.js

@@ -11,7 +11,7 @@ export { log } from "./lib/logger";
 export { connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo, authConnection, appConnection, mongoose } from "./lib/mongo";
 export { connectRedis, disconnectRedis, getRedis } from "./lib/redis";
 export { createQueue, createWorker } from "./lib/queue";
-export { createSession, getSession, deleteSession, setSessionStore } from "./lib/session";
+export { createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount, evictOldestSession, updateSessionLastActive, setSessionStore } from "./lib/session";
 export { createVerificationToken, getVerificationToken, deleteVerificationToken } from "./lib/emailVerification";
 export { bustAuthLimit, trackAttempt, isLimited } from "./lib/authRateLimit";
 export { validate } from "./lib/validate";

package/dist/lib/appConfig.d.ts

@@ -18,3 +18,11 @@ export declare const getPrimaryField: () => PrimaryField;
 export declare const setEmailVerificationConfig: (config: EmailVerificationConfig | null) => void;
 export declare const getEmailVerificationConfig: () => EmailVerificationConfig | null;
 export declare const getTokenExpiry: () => number;
+export declare const setMaxSessions: (n: number) => void;
+export declare const getMaxSessions: () => number;
+export declare const setPersistSessionMetadata: (v: boolean) => void;
+export declare const getPersistSessionMetadata: () => boolean;
+export declare const setIncludeInactiveSessions: (v: boolean) => void;
+export declare const getIncludeInactiveSessions: () => boolean;
+export declare const setTrackLastActive: (v: boolean) => void;
+export declare const getTrackLastActive: () => boolean;

package/dist/lib/appConfig.js

@@ -15,3 +15,18 @@ export const setEmailVerificationConfig = (config) => { _emailVerificationConfig
 export const getEmailVerificationConfig = () => _emailVerificationConfig;
 const DEFAULT_TOKEN_EXPIRY = 60 * 60 * 24; // 24 hours
 export const getTokenExpiry = () => _emailVerificationConfig?.tokenExpiry ?? DEFAULT_TOKEN_EXPIRY;
+// ---------------------------------------------------------------------------
+// Session policy
+// ---------------------------------------------------------------------------
+let _maxSessions = 6;
+let _persistSessionMetadata = true;
+let _includeInactiveSessions = false;
+let _trackLastActive = false;
+export const setMaxSessions = (n) => { _maxSessions = Number.isFinite(n) && n >= 1 ? Math.floor(n) : 1; };
+export const getMaxSessions = () => _maxSessions;
+export const setPersistSessionMetadata = (v) => { _persistSessionMetadata = v; };
+export const getPersistSessionMetadata = () => _persistSessionMetadata;
+export const setIncludeInactiveSessions = (v) => { _includeInactiveSessions = v; };
+export const getIncludeInactiveSessions = () => _includeInactiveSessions;
+export const setTrackLastActive = (v) => { _trackLastActive = v; };
+export const getTrackLastActive = () => _trackLastActive;

package/dist/lib/context.d.ts

@@ -2,6 +2,7 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 export type AppVariables = {
     authUserId: string | null;
     roles: string[] | null;
+    sessionId: string | null;
 };
 export type AppEnv = {
     Variables: AppVariables;

package/dist/lib/jwt.d.ts

@@ -1,2 +1,2 @@
-export declare const signToken: (userId: string) => Promise<string>;
+export declare const signToken: (userId: string, sessionId: string) => Promise<string>;
 export declare const verifyToken: (token: string) => Promise<import("jose").JWTPayload>;

package/dist/lib/jwt.js

@@ -1,7 +1,7 @@
 import { SignJWT, jwtVerify } from "jose";
 const isProd = process.env.NODE_ENV === "production";
 const secret = new TextEncoder().encode(isProd ? process.env.JWT_SECRET_PROD : process.env.JWT_SECRET_DEV);
-export const signToken = async (userId) => new SignJWT({ sub: userId })
+export const signToken = async (userId, sessionId) => new SignJWT({ sub: userId, sid: sessionId })
     .setProtectedHeader({ alg: "HS256" })
     .setExpirationTime("7d")
     .sign(secret);

package/dist/lib/session.d.ts

@@ -1,6 +1,23 @@
+export interface SessionMetadata {
+    ipAddress?: string;
+    userAgent?: string;
+}
+export interface SessionInfo {
+    sessionId: string;
+    createdAt: number;
+    lastActiveAt: number;
+    expiresAt: number;
+    ipAddress?: string;
+    userAgent?: string;
+    isActive: boolean;
+}
 type SessionStore = "redis" | "mongo" | "sqlite" | "memory";
 export declare const setSessionStore: (store: SessionStore) => void;
-export declare const createSession: (userId: string, token: string) => Promise<void>;
-export declare const getSession: (userId: string) => Promise<any>;
-export declare const deleteSession: (userId: string) => Promise<void>;
+export declare const createSession: (userId: string, token: string, sessionId: string, metadata?: SessionMetadata) => Promise<void>;
+export declare const getSession: (sessionId: string) => Promise<string | null>;
+export declare const deleteSession: (sessionId: string) => Promise<void>;
+export declare const getUserSessions: (userId: string) => Promise<SessionInfo[]>;
+export declare const getActiveSessionCount: (userId: string) => Promise<number>;
+export declare const evictOldestSession: (userId: string) => Promise<void>;
+export declare const updateSessionLastActive: (sessionId: string) => Promise<void>;
 export {};

package/dist/lib/session.js

@@ -1,17 +1,28 @@
 import { getRedis } from "./redis";
 import { appConnection } from "./mongo";
-import { getAppName } from "./appConfig";
+import { getAppName, getPersistSessionMetadata, getIncludeInactiveSessions } from "./appConfig";
 import { Schema } from "mongoose";
-import { sqliteCreateSession, sqliteGetSession, sqliteDeleteSession } from "../adapters/sqliteAuth";
-import { memoryCreateSession, memoryGetSession, memoryDeleteSession } from "../adapters/memoryAuth";
+import { sqliteCreateSession, sqliteGetSession, sqliteDeleteSession, sqliteGetUserSessions, sqliteGetActiveSessionCount, sqliteEvictOldestSession, sqliteUpdateSessionLastActive, } from "../adapters/sqliteAuth";
+import { memoryCreateSession, memoryGetSession, memoryDeleteSession, memoryGetUserSessions, memoryGetActiveSessionCount, memoryEvictOldestSession, memoryUpdateSessionLastActive, } from "../adapters/memoryAuth";
 const sessionSchema = new Schema({
-    userId: { type: String, required: true, unique: true },
-    token: { type: String, required: true },
-    expiresAt: { type: Date, required: true, index: { expireAfterSeconds: 0 } },
-}, { collection: "sessions" });
+    sessionId: { type: String, required: true, unique: true },
+    userId: { type: String, required: true, index: true },
+    token: { type: String, default: null },
+    createdAt: { type: Date, required: true },
+    lastActiveAt: { type: Date, required: true },
+    expiresAt: { type: Date, required: true },
+    ipAddress: { type: String },
+    userAgent: { type: String },
+}, { collection: "sessions", timestamps: false });
 function getSessionModel() {
-    return appConnection.models["Session"] ??
-        appConnection.model("Session", sessionSchema);
+    if (appConnection.models["Session"])
+        return appConnection.models["Session"];
+    // Add TTL index only when metadata is not persisted — docs auto-delete at expiresAt.
+    // When persisting, token is nulled (soft-delete) but the row is kept indefinitely.
+    if (!getPersistSessionMetadata()) {
+        sessionSchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+    }
+    return appConnection.model("Session", sessionSchema);
 }
 let _store = "redis";
 export const setSessionStore = (store) => { _store = store; };
@@ -19,50 +30,292 @@ export const setSessionStore = (store) => { _store = store; };
 // TTL
 // ---------------------------------------------------------------------------
 const TTL_SECONDS = 60 * 60 * 24 * 7; // 7 days
+const TTL_MS = TTL_SECONDS * 1000;
+// ---------------------------------------------------------------------------
+// Redis helpers
+// ---------------------------------------------------------------------------
+function redisSessionKey(sessionId) {
+    return `session:${getAppName()}:${sessionId}`;
+}
+function redisUserSessionsKey(userId) {
+    return `usersessions:${getAppName()}:${userId}`;
+}
+async function redisCreateSession(userId, token, sessionId, metadata) {
+    const now = Date.now();
+    const expiresAt = now + TTL_MS;
+    const record = JSON.stringify({
+        sessionId, userId, token,
+        createdAt: now, lastActiveAt: now, expiresAt,
+        ipAddress: metadata?.ipAddress,
+        userAgent: metadata?.userAgent,
+    });
+    const redis = getRedis();
+    const persist = getPersistSessionMetadata();
+    if (persist) {
+        await redis.set(redisSessionKey(sessionId), record);
+    }
+    else {
+        await redis.set(redisSessionKey(sessionId), record, "EX", TTL_SECONDS);
+    }
+    // Sorted set: score = createdAt (oldest first)
+    await redis.zadd(redisUserSessionsKey(userId), now, sessionId);
+}
+async function redisGetSession(sessionId) {
+    const raw = await getRedis().get(redisSessionKey(sessionId));
+    if (!raw)
+        return null;
+    const rec = JSON.parse(raw);
+    if (!rec.token)
+        return null;
+    if (rec.expiresAt <= Date.now())
+        return null;
+    return rec.token;
+}
+async function redisDeleteSession(sessionId) {
+    const redis = getRedis();
+    const raw = await redis.get(redisSessionKey(sessionId));
+    if (!raw)
+        return;
+    const rec = JSON.parse(raw);
+    const persist = getPersistSessionMetadata();
+    if (persist) {
+        const updated = { ...JSON.parse(raw), token: null };
+        await redis.set(redisSessionKey(sessionId), JSON.stringify(updated));
+    }
+    else {
+        await redis.del(redisSessionKey(sessionId));
+    }
+    if (!persist) {
+        await redis.zrem(redisUserSessionsKey(rec.userId), sessionId);
+    }
+}
+async function redisGetUserSessions(userId) {
+    const redis = getRedis();
+    const sessionIds = await redis.zrange(redisUserSessionsKey(userId), 0, -1);
+    if (!sessionIds.length)
+        return [];
+    const now = Date.now();
+    const raws = await redis.mget(...sessionIds.map(redisSessionKey));
+    const results = [];
+    const toRemove = [];
+    for (let i = 0; i < sessionIds.length; i++) {
+        const raw = raws[i];
+        if (!raw) {
+            toRemove.push(sessionIds[i]);
+            continue;
+        }
+        const rec = JSON.parse(raw);
+        const isActive = !!rec.token && rec.expiresAt > now;
+        if (!isActive && !getPersistSessionMetadata()) {
+            toRemove.push(sessionIds[i]);
+            continue;
+        }
+        if (!isActive && !getIncludeInactiveSessions())
+            continue;
+        results.push({
+            sessionId: rec.sessionId,
+            createdAt: Number(rec.createdAt),
+            lastActiveAt: Number(rec.lastActiveAt),
+            expiresAt: Number(rec.expiresAt),
+            ipAddress: rec.ipAddress,
+            userAgent: rec.userAgent,
+            isActive,
+        });
+    }
+    if (toRemove.length) {
+        await redis.zrem(redisUserSessionsKey(userId), ...toRemove);
+    }
+    return results;
+}
+async function redisGetActiveSessionCount(userId) {
+    const sessions = await redisGetUserSessions(userId);
+    return sessions.filter((s) => s.isActive).length;
+}
+async function redisEvictOldestSession(userId) {
+    const redis = getRedis();
+    // Sorted set is ordered oldest-first (score = createdAt)
+    const sessionIds = await redis.zrange(redisUserSessionsKey(userId), 0, -1);
+    const now = Date.now();
+    for (const sessionId of sessionIds) {
+        const raw = await redis.get(redisSessionKey(sessionId));
+        if (!raw) {
+            await redis.zrem(redisUserSessionsKey(userId), sessionId);
+            continue;
+        }
+        const rec = JSON.parse(raw);
+        if (rec.token && rec.expiresAt > now) {
+            await redisDeleteSession(sessionId);
+            return;
+        }
+    }
+}
+async function redisUpdateSessionLastActive(sessionId) {
+    const redis = getRedis();
+    const raw = await redis.get(redisSessionKey(sessionId));
+    if (!raw)
+        return;
+    const rec = JSON.parse(raw);
+    rec.lastActiveAt = Date.now();
+    if (getPersistSessionMetadata()) {
+        await redis.set(redisSessionKey(sessionId), JSON.stringify(rec));
+    }
+    else {
+        const now = Date.now();
+        if (rec.expiresAt <= now) {
+            await redisDeleteSession(sessionId);
+            return;
+        }
+        const ttlRemaining = Math.max(1, Math.ceil((rec.expiresAt - now) / 1000));
+        await redis.set(redisSessionKey(sessionId), JSON.stringify(rec), "EX", ttlRemaining);
+    }
+}
+// ---------------------------------------------------------------------------
+// Mongo helpers
+// ---------------------------------------------------------------------------
+async function mongoGetUserSessions(userId) {
+    const now = new Date();
+    const includeInactive = getIncludeInactiveSessions();
+    const persist = getPersistSessionMetadata();
+    const query = { userId };
+    if (!includeInactive) {
+        query.token = { $ne: null };
+        query.expiresAt = { $gt: now };
+    }
+    const docs = await getSessionModel().find(query).lean();
+    const results = [];
+    for (const doc of docs) {
+        const isActive = !!doc.token && doc.expiresAt > now;
+        if (!isActive && !persist)
+            continue;
+        if (!isActive && !includeInactive)
+            continue;
+        results.push({
+            sessionId: doc.sessionId,
+            createdAt: doc.createdAt.getTime(),
+            lastActiveAt: doc.lastActiveAt.getTime(),
+            expiresAt: doc.expiresAt.getTime(),
+            ipAddress: doc.ipAddress,
+            userAgent: doc.userAgent,
+            isActive,
+        });
+    }
+    return results;
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
-export const createSession = async (userId, token) => {
+export const createSession = async (userId, token, sessionId, metadata) => {
     if (_store === "memory") {
-        memoryCreateSession(userId, token);
+        memoryCreateSession(userId, token, sessionId, metadata);
         return;
     }
     if (_store === "sqlite") {
-        sqliteCreateSession(userId, token);
+        sqliteCreateSession(userId, token, sessionId, metadata);
         return;
     }
-    if (_store === "mongo") {
-        const expiresAt = new Date(Date.now() + TTL_SECONDS * 1000);
-        await getSessionModel().updateOne({ userId }, { $set: { token, expiresAt } }, { upsert: true });
+    if (_store === "redis") {
+        await redisCreateSession(userId, token, sessionId, metadata);
         return;
     }
-    await getRedis().set(`session:${getAppName()}:${userId}`, token, "EX", TTL_SECONDS);
+    // mongo
+    const now = new Date();
+    const expiresAt = new Date(Date.now() + TTL_MS);
+    await getSessionModel().create({
+        sessionId, userId, token,
+        createdAt: now, lastActiveAt: now, expiresAt,
+        ipAddress: metadata?.ipAddress,
+        userAgent: metadata?.userAgent,
+    });
 };
-export const getSession = async (userId) => {
+export const getSession = async (sessionId) => {
     if (_store === "memory")
-        return memoryGetSession(userId);
+        return memoryGetSession(sessionId);
     if (_store === "sqlite")
-        return sqliteGetSession(userId);
-    if (_store === "mongo") {
-        const doc = await getSessionModel()
-            .findOne({ userId, expiresAt: { $gt: new Date() } }, "token")
-            .lean();
-        return doc ? doc.token : null;
-    }
-    return getRedis().get(`session:${getAppName()}:${userId}`);
+        return sqliteGetSession(sessionId);
+    if (_store === "redis")
+        return redisGetSession(sessionId);
+    // mongo
+    const doc = await getSessionModel()
+        .findOne({ sessionId, expiresAt: { $gt: new Date() } }, "token")
+        .lean();
+    return doc?.token ?? null;
+};
+export const deleteSession = async (sessionId) => {
+    if (_store === "memory") {
+        memoryDeleteSession(sessionId);
+        return;
+    }
+    if (_store === "sqlite") {
+        sqliteDeleteSession(sessionId);
+        return;
+    }
+    if (_store === "redis") {
+        await redisDeleteSession(sessionId);
+        return;
+    }
+    // mongo
+    if (getPersistSessionMetadata()) {
+        await getSessionModel().updateOne({ sessionId }, { $set: { token: null } });
+    }
+    else {
+        await getSessionModel().deleteOne({ sessionId });
+    }
+};
+export const getUserSessions = async (userId) => {
+    if (_store === "memory")
+        return memoryGetUserSessions(userId);
+    if (_store === "sqlite")
+        return sqliteGetUserSessions(userId);
+    if (_store === "redis")
+        return redisGetUserSessions(userId);
+    return mongoGetUserSessions(userId);
+};
+export const getActiveSessionCount = async (userId) => {
+    if (_store === "memory")
+        return memoryGetActiveSessionCount(userId);
+    if (_store === "sqlite")
+        return sqliteGetActiveSessionCount(userId);
+    if (_store === "redis")
+        return redisGetActiveSessionCount(userId);
+    // mongo
+    const now = new Date();
+    return getSessionModel().countDocuments({ userId, token: { $ne: null }, expiresAt: { $gt: now } });
+};
+export const evictOldestSession = async (userId) => {
+    if (_store === "memory") {
+        memoryEvictOldestSession(userId);
+        return;
+    }
+    if (_store === "sqlite") {
+        sqliteEvictOldestSession(userId);
+        return;
+    }
+    if (_store === "redis") {
+        await redisEvictOldestSession(userId);
+        return;
+    }
+    // mongo — oldest active session by createdAt
+    const now = new Date();
+    const oldest = await getSessionModel()
+        .findOne({ userId, token: { $ne: null }, expiresAt: { $gt: now } }, "sessionId")
+        .sort({ createdAt: 1 })
+        .lean();
+    if (oldest)
+        await deleteSession(oldest.sessionId);
 };
-export const deleteSession = async (userId) => {
+export const updateSessionLastActive = async (sessionId) => {
     if (_store === "memory") {
-        memoryDeleteSession(userId);
+        memoryUpdateSessionLastActive(sessionId);
         return;
     }
     if (_store === "sqlite") {
-        sqliteDeleteSession(userId);
+        sqliteUpdateSessionLastActive(sessionId);
         return;
     }
-    if (_store === "mongo") {
-        await getSessionModel().deleteOne({ userId });
+    if (_store === "redis") {
+        await redisUpdateSessionLastActive(sessionId);
         return;
     }
-    await getRedis().del(`session:${getAppName()}:${userId}`);
+    // mongo
+    await getSessionModel().updateOne({ sessionId }, { $set: { lastActiveAt: new Date() } });
 };

package/dist/middleware/identify.js

@@ -1,25 +1,39 @@
 import { getCookie } from "hono/cookie";
 import { verifyToken } from "../lib/jwt";
-import { getSession } from "../lib/session";
+import { getSession, updateSessionLastActive } from "../lib/session";
 import { COOKIE_TOKEN, HEADER_USER_TOKEN } from "../lib/constants";
 import { log } from "../lib/logger";
+import { getTrackLastActive } from "../lib/appConfig";
 export const identify = async (c, next) => {
     c.set("authUserId", null);
     c.set("roles", null);
+    c.set("sessionId", null);
     // cookie for browsers, x-user-token header for non-browser clients
     const token = getCookie(c, COOKIE_TOKEN) ?? c.req.header(HEADER_USER_TOKEN) ?? null;
     log(`[identify] token=${token ? "present" : "absent"}`);
     if (token) {
         try {
             const payload = await verifyToken(token);
-            const stored = await getSession(payload.sub);
-            log(`[identify] token for authUserId=${payload.sub} verified, checking session...`);
-            if (stored === token) {
-                c.set("authUserId", payload.sub);
-                log(`[identify] authUserId=${payload.sub}`);
+            const sessionId = payload.sid;
+            if (!sessionId) {
+                log("[identify] token missing sid claim — unauthenticated");
             }
             else {
-                log("[identify] token/session mismatch — unauthenticated");
+                const stored = await getSession(sessionId);
+                log(`[identify] token for authUserId=${payload.sub} verified, checking session...`);
+                if (stored === token) {
+                    c.set("authUserId", payload.sub);
+                    c.set("sessionId", sessionId);
+                    log(`[identify] authUserId=${payload.sub} sessionId=${sessionId}`);
+                    if (getTrackLastActive()) {
+                        updateSessionLastActive(sessionId).catch(() => {
+                            log(`[identify] failed to update lastActiveAt for sessionId=${sessionId}`);
+                        });
+                    }
+                }
+                else {
+                    log("[identify] token/session mismatch — unauthenticated");
+                }
             }
         }
         catch {

package/dist/routes/auth.js

@@ -9,9 +9,11 @@ import { isLimited, trackAttempt, bustAuthLimit } from "../lib/authRateLimit";
 import { getAuthAdapter } from "../lib/authAdapter";
 import { createRouter } from "../lib/context";
 import { getVerificationToken, deleteVerificationToken, createVerificationToken } from "../lib/emailVerification";
+import { getUserSessions, deleteSession } from "../lib/session";
 const isProd = process.env.NODE_ENV === "production";
 const TokenResponse = z.object({ token: z.string(), emailVerified: z.boolean().optional() });
 const ErrorResponse = z.object({ error: z.string() });
+const tags = ["Auth"];
 const cookieOptions = {
     httpOnly: true,
     secure: isProd,
@@ -19,6 +21,7 @@ const cookieOptions = {
     path: "/",
     maxAge: 60 * 60 * 24 * 7, // 7 days
 };
+const clientIp = (xff, xri) => (xff ? xff.split(",")[0]?.trim() : undefined) ?? xri ?? undefined;
 export const createAuthRouter = ({ primaryField, emailVerification, rateLimit }) => {
     const router = createRouter();
     const RegisterSchema = makeRegisterSchema(primaryField);
@@ -33,7 +36,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
     router.openapi(createRoute({
         method: "post",
         path: "/auth/register",
-        tags: ["Core"],
+        tags,
         request: { body: { content: { "application/json": { schema: RegisterSchema } } } },
         responses: {
             201: { content: { "application/json": { schema: TokenResponse } }, description: "Registered" },
@@ -42,20 +45,24 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
             429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
         },
     }), async (c) => {
-        const ip = c.req.header("x-forwarded-for") ?? "unknown";
+        const ip = clientIp(c.req.header("x-forwarded-for"), c.req.header("x-real-ip")) ?? "unknown";
         if (await trackAttempt(`register:${ip}`, registerOpts)) {
             return c.json({ error: "Too many registration attempts. Try again later." }, 429);
         }
         const body = c.req.valid("json");
         const identifier = body[primaryField];
-        const token = await AuthService.register(identifier, body.password);
+        const metadata = {
+            ipAddress: ip !== "unknown" ? ip : undefined,
+            userAgent: c.req.header("user-agent") ?? undefined,
+        };
+        const token = await AuthService.register(identifier, body.password, metadata);
         setCookie(c, COOKIE_TOKEN, token, cookieOptions);
         return c.json({ token }, 201);
     });
     router.openapi(createRoute({
         method: "post",
         path: "/auth/login",
-        tags: ["Core"],
+        tags,
         request: { body: { content: { "application/json": { schema: LoginSchema } } } },
         responses: {
             200: { content: { "application/json": { schema: TokenResponse } }, description: "Logged in" },
@@ -70,8 +77,12 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
         if (await isLimited(limitKey, loginOpts)) {
             return c.json({ error: "Too many failed login attempts. Try again later." }, 429);
         }
+        const metadata = {
+            ipAddress: clientIp(c.req.header("x-forwarded-for"), c.req.header("x-real-ip")),
+            userAgent: c.req.header("user-agent") ?? undefined,
+        };
         try {
-            const result = await AuthService.login(identifier, body.password);
+            const result = await AuthService.login(identifier, body.password, metadata);
             await bustAuthLimit(limitKey); // success — clear failure count
             setCookie(c, COOKIE_TOKEN, result.token, cookieOptions);
             return c.json(result, 200);
@@ -85,7 +96,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
     router.openapi(createRoute({
         method: "get",
         path: "/auth/me",
-        tags: ["Core"],
+        tags,
         responses: {
             200: {
                 content: {
@@ -113,7 +124,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
     router.openapi(createRoute({
         method: "post",
         path: "/auth/set-password",
-        tags: ["Core"],
+        tags,
         request: { body: { content: { "application/json": { schema: z.object({ password: z.string().min(8) }) } } } },
         responses: {
             200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Password set" },
@@ -134,7 +145,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
     router.openapi(createRoute({
         method: "post",
         path: "/auth/logout",
-        tags: ["Core"],
+        tags,
         responses: {
             200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Logged out" },
         },
@@ -149,7 +160,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
         router.openapi(createRoute({
             method: "post",
             path: "/auth/verify-email",
-            tags: ["Core"],
+            tags,
             request: { body: { content: { "application/json": { schema: z.object({ token: z.string() }) } } } },
             responses: {
                 200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Email verified" },
@@ -175,7 +186,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
         router.openapi(createRoute({
             method: "post",
             path: "/auth/resend-verification",
-            tags: ["Core"],
+            tags,
             responses: {
                 200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Verification email sent" },
                 400: { content: { "application/json": { schema: ErrorResponse } }, description: "Already verified" },
@@ -202,5 +213,55 @@ export const createAuthRouter = ({ primaryField, emailVerification, rateLimit })
             return c.json({ message: "Verification email sent" }, 200);
         });
     }
+    // ---------------------------------------------------------------------------
+    // Session management
+    // ---------------------------------------------------------------------------
+    const SessionInfoSchema = z.object({
+        sessionId: z.string(),
+        createdAt: z.number(),
+        lastActiveAt: z.number(),
+        expiresAt: z.number(),
+        ipAddress: z.string().optional(),
+        userAgent: z.string().optional(),
+        isActive: z.boolean(),
+    });
+    router.use("/auth/sessions", userAuth);
+    router.use("/auth/sessions/*", userAuth);
+    router.openapi(createRoute({
+        method: "get",
+        path: "/auth/sessions",
+        tags,
+        responses: {
+            200: {
+                content: { "application/json": { schema: z.object({ sessions: z.array(SessionInfoSchema) }) } },
+                description: "List of sessions for the current user",
+            },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Unauthorized" },
+        },
+    }), async (c) => {
+        const userId = c.get("authUserId");
+        const sessions = await getUserSessions(userId);
+        return c.json({ sessions }, 200);
+    });
+    router.openapi(createRoute({
+        method: "delete",
+        path: "/auth/sessions/{sessionId}",
+        tags,
+        request: { params: z.object({ sessionId: z.string() }) },
+        responses: {
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Session revoked" },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Unauthorized" },
+            404: { content: { "application/json": { schema: ErrorResponse } }, description: "Session not found" },
+        },
+    }), async (c) => {
+        const userId = c.get("authUserId");
+        const { sessionId } = c.req.valid("param");
+        const sessions = await getUserSessions(userId);
+        const session = sessions.find((s) => s.sessionId === sessionId);
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        await deleteSession(sessionId);
+        return c.json({ message: "Session revoked" }, 200);
+    });
     return router;
 };

package/dist/routes/oauth.js

@@ -5,10 +5,10 @@ import { getGoogle, getApple, storeOAuthState, consumeOAuthState, generateState,
 import { getAuthAdapter } from "../lib/authAdapter";
 import { HttpError } from "../lib/HttpError";
 import { signToken } from "../lib/jwt";
-import { createSession } from "../lib/session";
+import { createSession, getActiveSessionCount, evictOldestSession } from "../lib/session";
 import { COOKIE_TOKEN } from "../lib/constants";
 import { userAuth } from "../middleware/userAuth";
-import { getDefaultRole } from "../lib/appConfig";
+import { getDefaultRole, getMaxSessions } from "../lib/appConfig";
 const isProd = process.env.NODE_ENV === "production";
 const cookieOptions = {
     httpOnly: true,
@@ -36,8 +36,17 @@ const finishOAuth = async (c, provider, providerId, profile, postLoginRedirect)
         if (role && adapter.setRoles)
             await adapter.setRoles(user.id, [role]);
     }
-    const token = await signToken(user.id);
-    await createSession(user.id, token);
+    const sessionId = crypto.randomUUID();
+    const token = await signToken(user.id, sessionId);
+    const xff = c.req.header("x-forwarded-for");
+    const metadata = {
+        ipAddress: (xff ? xff.split(",")[0]?.trim() : undefined) ?? c.req.header("x-real-ip") ?? undefined,
+        userAgent: c.req.header("user-agent") ?? undefined,
+    };
+    while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
+        await evictOldestSession(user.id);
+    }
+    await createSession(user.id, token, sessionId, metadata);
     setCookie(c, COOKIE_TOKEN, token, cookieOptions);
     // Append token to redirect so non-browser clients (mobile deep links) can extract it.
     // Browser apps can safely ignore the query param.

package/dist/services/auth.d.ts

@@ -1,5 +1,6 @@
-export declare const register: (identifier: string, password: string) => Promise<string>;
-export declare const login: (identifier: string, password: string) => Promise<{
+import type { SessionMetadata } from "../lib/session";
+export declare const register: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<string>;
+export declare const login: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<{
     token: string;
     emailVerified?: boolean;
 }>;

package/dist/services/auth.js

@@ -1,18 +1,22 @@
 import { getAuthAdapter } from "../lib/authAdapter";
 import { HttpError } from "../lib/HttpError";
 import { signToken, verifyToken } from "../lib/jwt";
-import { createSession, deleteSession } from "../lib/session";
-import { getDefaultRole, getPrimaryField, getEmailVerificationConfig } from "../lib/appConfig";
+import { createSession, deleteSession, getActiveSessionCount, evictOldestSession } from "../lib/session";
+import { getDefaultRole, getPrimaryField, getEmailVerificationConfig, getMaxSessions } from "../lib/appConfig";
 import { createVerificationToken } from "../lib/emailVerification";
-export const register = async (identifier, password) => {
+export const register = async (identifier, password, metadata) => {
     const hashed = await Bun.password.hash(password);
     const adapter = getAuthAdapter();
     const user = await adapter.create(identifier, hashed);
     const role = getDefaultRole();
     if (role)
         await adapter.setRoles(user.id, [role]);
-    const token = await signToken(user.id);
-    await createSession(user.id, token);
+    const sessionId = crypto.randomUUID();
+    const token = await signToken(user.id, sessionId);
+    while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
+        await evictOldestSession(user.id);
+    }
+    await createSession(user.id, token, sessionId, metadata);
     const evConfig = getEmailVerificationConfig();
     if (evConfig && getPrimaryField() === "email") {
         try {
@@ -25,30 +29,35 @@ export const register = async (identifier, password) => {
     }
     return token;
 };
-export const login = async (identifier, password) => {
+export const login = async (identifier, password, metadata) => {
     const adapter = getAuthAdapter();
     const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
     const user = await findFn(identifier);
     if (!user || !(await Bun.password.verify(password, user.passwordHash))) {
         throw new HttpError(401, "Invalid credentials");
     }
+    const sessionId = crypto.randomUUID();
+    const token = await signToken(user.id, sessionId);
+    while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
+        await evictOldestSession(user.id);
+    }
     const evConfig = getEmailVerificationConfig();
     if (evConfig && getPrimaryField() === "email" && adapter.getEmailVerified) {
         const verified = await adapter.getEmailVerified(user.id);
         if (evConfig.required && !verified) {
             throw new HttpError(403, "Email not verified");
         }
-        const token = await signToken(user.id);
-        await createSession(user.id, token);
+        await createSession(user.id, token, sessionId, metadata);
         return { token, emailVerified: verified };
     }
-    const token = await signToken(user.id);
-    await createSession(user.id, token);
+    await createSession(user.id, token, sessionId, metadata);
     return { token };
 };
 export const logout = async (token) => {
     if (token) {
         const payload = await verifyToken(token);
-        await deleteSession(payload.sub);
+        const sessionId = payload.sid;
+        if (sessionId)
+            await deleteSession(sessionId);
     }
 };

package/dist/ws/index.js

@@ -8,9 +8,12 @@ export const createWsUpgradeHandler = (server) => async (req) => {
             ?.match(new RegExp(`(?:^|;\\s*)${COOKIE_TOKEN}=([^;]+)`))?.[1] ?? null;
         if (token) {
             const payload = await verifyToken(token);
-            const stored = await getSession(payload.sub);
-            if (stored === token)
-                userId = payload.sub;
+            const sessionId = payload.sid;
+            if (sessionId) {
+                const stored = await getSession(sessionId);
+                if (stored === token)
+                    userId = payload.sub;
+            }
         }
     }
     catch { /* unauthenticated — userId stays null */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastshotlabs/bunshot",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Batteries-included Bun + Hono API framework — auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
     "@scalar/hono-api-reference": "0.10.0",
     "arctic": "^3.7.0",
     "bullmq": "^5.70.4",
-    "hono": "4.12.5",
+    "hono": "4.12.7",
     "ioredis": "5.10.0",
     "jose": "6.2.0",
     "mongoose": "9.2.4",
@@ -56,4 +56,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}