@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/packages/bunshot-auth/src/adapters/memoryAuth.js

@@ -0,0 +1,1063 @@
+import { DEFAULT_MAX_ENTRIES, HttpError, evictExpired, evictOldest, } from '../../../bunshot-core/src/index.js';
+import { hashToken, timingSafeEqual } from '../../../bunshot-core/src/index.js';
+function encodeCursor(createdAt, id) {
+    return btoa(JSON.stringify({ createdAt, id }));
+}
+function decodeCursor(cursor) {
+    try {
+        return JSON.parse(atob(cursor));
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_SESSION_TTL_MS = 60 * 60 * 24 * 7 * 1000; // 7 days
+const OAUTH_STATE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+export function createMemoryAuthAdapter(getConfig) {
+    function getSessionTtlMs() {
+        const abs = getConfig?.()?.sessionPolicy.absoluteTimeout;
+        return abs ? abs * 1000 : DEFAULT_SESSION_TTL_MS;
+    }
+    // -------------------------------------------------------------------------
+    // Instance state — all Maps live inside the closure
+    // -------------------------------------------------------------------------
+    const _users = new Map();
+    const _byEmail = new Map();
+    const _sessions = new Map(); // sessionId → session
+    const _userSessionIds = new Map(); // userId → Set<sessionId>
+    const _refreshTokenIndex = new Map(); // refreshToken → sessionId
+    const _oauthStates = new Map();
+    const _cache = new Map();
+    const _verificationTokens = new Map();
+    const _resetTokens = new Map();
+    const _cancelTokens = new Map();
+    const _oauthCodes = new Map();
+    const _oauthReauthStates = new Map();
+    const _oauthReauthConfirmations = new Map();
+    const _tenantRoles = new Map(); // "userId:tenantId" → roles
+    const _groups = new Map(); // groupId → GroupRecord
+    const _groupMemberships = new Map();
+    const _m2mClients = new Map();
+    const _magicLinkTokens = new Map();
+    let _memoryWarned = false;
+    function warnMemoryAdapter() {
+        if (!_memoryWarned) {
+            _memoryWarned = true;
+            console.warn('[bunshot] Memory adapter for auth has no eviction — for development/testing only');
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Session store methods (forward-declared so they can reference each other)
+    // -------------------------------------------------------------------------
+    const memoryDeleteSession = (sessionId) => {
+        const entry = _sessions.get(sessionId);
+        if (!entry)
+            return;
+        // Clean up refresh token reverse-lookup keys
+        if (entry.refreshToken)
+            _refreshTokenIndex.delete(entry.refreshToken);
+        if (entry.prevRefreshToken)
+            _refreshTokenIndex.delete(entry.prevRefreshToken);
+        if (getConfig().persistSessionMetadata) {
+            entry.token = null;
+            entry.refreshToken = null;
+            entry.prevRefreshToken = null;
+            entry.prevTokenExpiresAt = null;
+        }
+        else {
+            _sessions.delete(sessionId);
+            _userSessionIds.get(entry.userId)?.delete(sessionId);
+        }
+    };
+    const memoryCreateSession = (userId, token, sessionId, metadata) => {
+        const now = Date.now();
+        const session = {
+            sessionId,
+            userId,
+            token,
+            createdAt: now,
+            lastActiveAt: now,
+            expiresAt: now + getSessionTtlMs(),
+            ipAddress: metadata?.ipAddress,
+            userAgent: metadata?.userAgent,
+        };
+        evictOldest(_sessions, DEFAULT_MAX_ENTRIES);
+        _sessions.set(sessionId, session);
+        if (!_userSessionIds.has(userId))
+            _userSessionIds.set(userId, new Set());
+        _userSessionIds.get(userId).add(sessionId);
+    };
+    // -------------------------------------------------------------------------
+    // Return the combined AuthAdapter + MemoryAuthStores object
+    // -------------------------------------------------------------------------
+    return {
+        // -----------------------------------------------------------------------
+        // AuthAdapter methods
+        // -----------------------------------------------------------------------
+        async findByEmail(email) {
+            warnMemoryAdapter();
+            const id = _byEmail.get(email.toLowerCase());
+            if (!id)
+                return null;
+            const user = _users.get(id);
+            if (!user || !user.passwordHash)
+                return null;
+            return { id: user.id, passwordHash: user.passwordHash };
+        },
+        async create(email, passwordHash) {
+            const normalised = email.toLowerCase();
+            if (_byEmail.has(normalised))
+                throw new HttpError(409, 'Email already registered');
+            const id = crypto.randomUUID();
+            const user = {
+                id,
+                email: normalised,
+                identifier: normalised,
+                passwordHash,
+                providerIds: [],
+                roles: [],
+                emailVerified: false,
+                mfaSecret: null,
+                mfaEnabled: false,
+                recoveryCodes: [],
+                mfaMethods: [],
+                webauthnCredentials: [],
+                suspended: false,
+                passwordHistory: [],
+            };
+            evictOldest(_users, DEFAULT_MAX_ENTRIES);
+            _users.set(id, user);
+            _byEmail.set(normalised, id);
+            return { id };
+        },
+        async verifyPassword(userId, password) {
+            const user = _users.get(userId);
+            if (!user?.passwordHash)
+                return false;
+            return Bun.password.verify(password, user.passwordHash);
+        },
+        async getIdentifier(userId) {
+            const user = _users.get(userId);
+            return user?.identifier ?? user?.email ?? '';
+        },
+        async setPassword(userId, passwordHash) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            user.passwordHash = passwordHash;
+        },
+        async findOrCreateByProvider(provider, providerId, profile) {
+            const key = `${provider}:${providerId}`;
+            // Find by provider key
+            for (const user of _users.values()) {
+                if (user.providerIds.includes(key))
+                    return { id: user.id, created: false };
+            }
+            // Reject if email belongs to a credential account
+            if (profile.email) {
+                const existingId = _byEmail.get(profile.email.toLowerCase());
+                if (existingId)
+                    throw new HttpError(409, 'An account with this email already exists. Sign in with your credentials, then link Google from your account settings.');
+            }
+            const id = crypto.randomUUID();
+            const email = profile.email ? profile.email.toLowerCase() : null;
+            const user = {
+                id,
+                email,
+                identifier: email,
+                passwordHash: null,
+                providerIds: [key],
+                roles: [],
+                emailVerified: false,
+                mfaSecret: null,
+                mfaEnabled: false,
+                recoveryCodes: [],
+                mfaMethods: [],
+                webauthnCredentials: [],
+                suspended: false,
+                passwordHistory: [],
+            };
+            evictOldest(_users, DEFAULT_MAX_ENTRIES);
+            _users.set(id, user);
+            if (email)
+                _byEmail.set(email, id);
+            return { id, created: true };
+        },
+        async linkProvider(userId, provider, providerId) {
+            const user = _users.get(userId);
+            if (!user)
+                throw new HttpError(404, 'User not found');
+            const key = `${provider}:${providerId}`;
+            if (!user.providerIds.includes(key))
+                user.providerIds.push(key);
+        },
+        async getRoles(userId) {
+            return _users.get(userId)?.roles ?? [];
+        },
+        async setRoles(userId, roles) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            user.roles = [...roles];
+        },
+        async addRole(userId, role) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            if (!user.roles.includes(role))
+                user.roles.push(role);
+        },
+        async removeRole(userId, role) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            user.roles = user.roles.filter(r => r !== role);
+        },
+        async getUser(userId) {
+            const user = _users.get(userId);
+            if (!user)
+                return null;
+            return {
+                email: user.email ?? undefined,
+                providerIds: [...user.providerIds],
+                emailVerified: user.emailVerified,
+                displayName: user.displayName,
+                firstName: user.firstName,
+                lastName: user.lastName,
+                externalId: user.externalId,
+                suspended: user.suspended,
+                suspendedReason: user.suspendedReason,
+                userMetadata: user.userMetadata ? { ...user.userMetadata } : undefined,
+                appMetadata: user.appMetadata ? { ...user.appMetadata } : undefined,
+            };
+        },
+        async unlinkProvider(userId, provider) {
+            const user = _users.get(userId);
+            if (!user)
+                throw new HttpError(404, 'User not found');
+            user.providerIds = user.providerIds.filter(id => !id.startsWith(`${provider}:`));
+        },
+        async findByIdentifier(value) {
+            const normalized = value.toLowerCase();
+            // First try _byEmail index (covers email primaryField)
+            const idFromEmail = _byEmail.get(normalized);
+            if (idFromEmail) {
+                const user = _users.get(idFromEmail);
+                if (user)
+                    return { id: user.id, passwordHash: user.passwordHash ?? '' };
+            }
+            // Fallback: linear scan for identifier field (non-email primaryField)
+            for (const user of _users.values()) {
+                if (user.identifier === normalized) {
+                    return { id: user.id, passwordHash: user.passwordHash ?? '' };
+                }
+            }
+            return null;
+        },
+        async setEmailVerified(userId, verified) {
+            const user = _users.get(userId);
+            if (user)
+                user.emailVerified = verified;
+        },
+        async getEmailVerified(userId) {
+            return _users.get(userId)?.emailVerified ?? false;
+        },
+        async deleteUser(userId) {
+            const user = _users.get(userId);
+            if (user?.email)
+                _byEmail.delete(user.email);
+            _users.delete(userId);
+            // Cascade: clean up sessions (mirrors deleteUserSessions logic)
+            const sessionIds = _userSessionIds.get(userId);
+            if (sessionIds) {
+                for (const sessionId of sessionIds) {
+                    const session = _sessions.get(sessionId);
+                    if (session) {
+                        if (session.refreshToken)
+                            _refreshTokenIndex.delete(session.refreshToken);
+                        if (session.prevRefreshToken)
+                            _refreshTokenIndex.delete(session.prevRefreshToken);
+                        _sessions.delete(sessionId);
+                    }
+                }
+                _userSessionIds.delete(userId);
+            }
+            // Cascade: clean up tenant roles
+            for (const key of _tenantRoles.keys()) {
+                if (key.startsWith(`${userId}:`))
+                    _tenantRoles.delete(key);
+            }
+            // Cascade: clean up group memberships
+            _groupMemberships.delete(userId);
+        },
+        async hasPassword(userId) {
+            return !!_users.get(userId)?.passwordHash;
+        },
+        async setMfaSecret(userId, secret) {
+            const user = _users.get(userId);
+            if (user)
+                user.mfaSecret = secret;
+        },
+        async getMfaSecret(userId) {
+            return _users.get(userId)?.mfaSecret ?? null;
+        },
+        async isMfaEnabled(userId) {
+            return _users.get(userId)?.mfaEnabled ?? false;
+        },
+        async setMfaEnabled(userId, enabled) {
+            const user = _users.get(userId);
+            if (user)
+                user.mfaEnabled = enabled;
+        },
+        async setRecoveryCodes(userId, codes) {
+            const user = _users.get(userId);
+            if (user)
+                user.recoveryCodes = [...codes];
+        },
+        async getRecoveryCodes(userId) {
+            return _users.get(userId)?.recoveryCodes ?? [];
+        },
+        async removeRecoveryCode(userId, code) {
+            const user = _users.get(userId);
+            if (user)
+                user.recoveryCodes = user.recoveryCodes.filter(c => c !== code);
+        },
+        async consumeRecoveryCode(userId, hashedCode) {
+            // Synchronous find-and-splice — safe in single-threaded Bun (no await between read and write).
+            const user = _users.get(userId);
+            if (!user)
+                return false;
+            const codes = user.recoveryCodes;
+            const idx = codes.indexOf(hashedCode);
+            if (idx === -1)
+                return false;
+            codes.splice(idx, 1);
+            return true;
+        },
+        async getMfaMethods(userId) {
+            const user = _users.get(userId);
+            if (!user)
+                return [];
+            return [...user.mfaMethods];
+        },
+        async setMfaMethods(userId, methods) {
+            const user = _users.get(userId);
+            if (user)
+                user.mfaMethods = [...methods];
+        },
+        async getWebAuthnCredentials(userId) {
+            return [...(_users.get(userId)?.webauthnCredentials ?? [])];
+        },
+        async addWebAuthnCredential(userId, credential) {
+            const user = _users.get(userId);
+            if (user)
+                user.webauthnCredentials.push({ ...credential });
+        },
+        async removeWebAuthnCredential(userId, credentialId) {
+            const user = _users.get(userId);
+            if (user)
+                user.webauthnCredentials = user.webauthnCredentials.filter(c => c.credentialId !== credentialId);
+        },
+        async updateWebAuthnCredentialSignCount(userId, credentialId, signCount) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            const cred = user.webauthnCredentials.find(c => c.credentialId === credentialId);
+            if (cred)
+                cred.signCount = signCount;
+        },
+        async findUserByWebAuthnCredentialId(credentialId) {
+            for (const user of _users.values()) {
+                if (user.webauthnCredentials.some(c => c.credentialId === credentialId))
+                    return user.id;
+            }
+            return null;
+        },
+        async getTenantRoles(userId, tenantId) {
+            return _tenantRoles.get(`${userId}:${tenantId}`) ?? [];
+        },
+        async setTenantRoles(userId, tenantId, roles) {
+            _tenantRoles.set(`${userId}:${tenantId}`, [...roles]);
+        },
+        async addTenantRole(userId, tenantId, role) {
+            const key = `${userId}:${tenantId}`;
+            const current = _tenantRoles.get(key) ?? [];
+            if (!current.includes(role)) {
+                _tenantRoles.set(key, [...current, role]);
+            }
+        },
+        async removeTenantRole(userId, tenantId, role) {
+            const key = `${userId}:${tenantId}`;
+            const current = _tenantRoles.get(key);
+            if (current) {
+                _tenantRoles.set(key, current.filter(r => r !== role));
+            }
+        },
+        async setSuspended(userId, suspended, reason) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            user.suspended = suspended;
+            if (suspended) {
+                user.suspendedAt = new Date();
+                user.suspendedReason = reason;
+            }
+            else {
+                user.suspendedAt = undefined;
+                user.suspendedReason = undefined;
+            }
+        },
+        async getSuspended(userId) {
+            const user = _users.get(userId);
+            if (!user)
+                return null;
+            return { suspended: user.suspended, suspendedReason: user.suspendedReason };
+        },
+        async updateProfile(userId, fields) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            if ('displayName' in fields)
+                user.displayName = fields.displayName;
+            if ('firstName' in fields)
+                user.firstName = fields.firstName;
+            if ('lastName' in fields)
+                user.lastName = fields.lastName;
+            if ('externalId' in fields)
+                user.externalId = fields.externalId;
+            if ('userMetadata' in fields)
+                user.userMetadata = fields.userMetadata;
+        },
+        async getUserMetadata(userId) {
+            const user = _users.get(userId);
+            if (!user)
+                return {};
+            return {
+                userMetadata: user.userMetadata ? { ...user.userMetadata } : undefined,
+                appMetadata: user.appMetadata ? { ...user.appMetadata } : undefined,
+            };
+        },
+        async setUserMetadata(userId, data) {
+            const user = _users.get(userId);
+            if (user)
+                user.userMetadata = { ...data };
+        },
+        async setAppMetadata(userId, data) {
+            const user = _users.get(userId);
+            if (user)
+                user.appMetadata = { ...data };
+        },
+        async listUsers(query) {
+            let users = [..._users.values()];
+            if (query.email !== undefined)
+                users = users.filter(u => u.email === query.email);
+            if (query.externalId !== undefined)
+                users = users.filter(u => u.externalId === query.externalId);
+            if (query.suspended !== undefined)
+                users = users.filter(u => u.suspended === query.suspended);
+            const totalResults = users.length;
+            const startIndex = query.startIndex ?? 0;
+            const count = query.count ?? 100;
+            const page = users.slice(startIndex, startIndex + count);
+            return {
+                users: page.map(u => ({
+                    id: u.id,
+                    email: u.email ?? undefined,
+                    displayName: u.displayName,
+                    firstName: u.firstName,
+                    lastName: u.lastName,
+                    externalId: u.externalId,
+                    suspended: u.suspended,
+                    suspendedAt: u.suspendedAt,
+                    suspendedReason: u.suspendedReason,
+                    emailVerified: u.emailVerified,
+                    providerIds: [...u.providerIds],
+                })),
+                totalResults,
+            };
+        },
+        // -----------------------------------------------------------------------
+        // Groups
+        // -----------------------------------------------------------------------
+        async createGroup(group) {
+            // Enforce name uniqueness within scope (null = app-wide, string = tenant-scoped)
+            for (const g of _groups.values()) {
+                if (g.name === group.name && g.tenantId === group.tenantId) {
+                    throw new HttpError(409, 'A group with this name already exists in this scope');
+                }
+            }
+            const id = crypto.randomUUID();
+            const now = Date.now();
+            evictOldest(_groups, DEFAULT_MAX_ENTRIES);
+            _groups.set(id, { ...group, id, createdAt: now, updatedAt: now });
+            return { id };
+        },
+        async deleteGroup(groupId) {
+            _groups.delete(groupId);
+            // Cascade: remove all memberships for this group
+            for (const [userId, memberships] of _groupMemberships) {
+                const filtered = memberships.filter(m => m.groupId !== groupId);
+                if (filtered.length !== memberships.length) {
+                    _groupMemberships.set(userId, filtered);
+                }
+            }
+        },
+        async getGroup(groupId) {
+            return _groups.get(groupId) ?? null;
+        },
+        async listGroups(tenantId, opts) {
+            const limit = Math.min(opts?.limit ?? 50, 200);
+            const all = [..._groups.values()]
+                .filter(g => g.tenantId === tenantId)
+                .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+            let filtered = all;
+            if (opts?.cursor) {
+                const c = decodeCursor(opts.cursor);
+                if (c) {
+                    filtered = all.filter(g => g.createdAt > c.createdAt || (g.createdAt === c.createdAt && g.id > c.id));
+                }
+            }
+            const page = filtered.slice(0, limit);
+            const nextCursor = filtered.length > limit
+                ? encodeCursor(page[page.length - 1].createdAt, page[page.length - 1].id)
+                : undefined;
+            return { items: page, nextCursor };
+        },
+        async updateGroup(groupId, updates) {
+            const group = _groups.get(groupId);
+            if (!group)
+                return;
+            const now = Date.now();
+            _groups.set(groupId, {
+                ...group,
+                ...updates,
+                id: group.id,
+                tenantId: group.tenantId,
+                createdAt: group.createdAt,
+                updatedAt: now,
+            });
+        },
+        async addGroupMember(groupId, userId, roles = []) {
+            const group = _groups.get(groupId);
+            if (!group)
+                throw new HttpError(404, 'Group not found');
+            const existing = _groupMemberships.get(userId) ?? [];
+            if (existing.some(m => m.groupId === groupId)) {
+                throw new HttpError(409, 'User is already a member of this group');
+            }
+            _groupMemberships.set(userId, [
+                ...existing,
+                {
+                    groupId,
+                    roles: [...roles],
+                    tenantId: group.tenantId,
+                    createdAt: Date.now(),
+                },
+            ]);
+        },
+        async updateGroupMembership(groupId, userId, roles) {
+            const memberships = _groupMemberships.get(userId);
+            if (!memberships)
+                return;
+            const idx = memberships.findIndex(m => m.groupId === groupId);
+            if (idx === -1)
+                return;
+            memberships[idx] = { ...memberships[idx], roles: [...roles] };
+        },
+        async removeGroupMember(groupId, userId) {
+            const memberships = _groupMemberships.get(userId);
+            if (!memberships)
+                return;
+            _groupMemberships.set(userId, memberships.filter(m => m.groupId !== groupId));
+        },
+        async getGroupMembers(groupId, opts) {
+            const limit = Math.min(opts?.limit ?? 50, 200);
+            const all = [];
+            for (const [userId, memberships] of _groupMemberships) {
+                const m = memberships.find(m => m.groupId === groupId);
+                if (m)
+                    all.push({ userId, roles: [...m.roles], createdAt: m.createdAt });
+            }
+            all.sort((a, b) => a.createdAt - b.createdAt || a.userId.localeCompare(b.userId));
+            let filtered = all;
+            if (opts?.cursor) {
+                const c = decodeCursor(opts.cursor);
+                if (c) {
+                    filtered = all.filter(m => m.createdAt > c.createdAt || (m.createdAt === c.createdAt && m.userId > c.id));
+                }
+            }
+            const page = filtered.slice(0, limit);
+            const nextCursor = filtered.length > limit
+                ? encodeCursor(page[page.length - 1].createdAt, page[page.length - 1].userId)
+                : undefined;
+            return {
+                items: page.map(({ userId, roles }) => ({ userId, roles })),
+                nextCursor,
+            };
+        },
+        async getUserGroups(userId, tenantId) {
+            const memberships = (_groupMemberships.get(userId) ?? []).filter(m => m.tenantId === tenantId);
+            const result = [];
+            for (const m of memberships) {
+                const group = _groups.get(m.groupId);
+                if (group)
+                    result.push({ group: { ...group }, membershipRoles: [...m.roles] });
+            }
+            return result;
+        },
+        async getEffectiveRoles(userId, tenantId) {
+            const direct = tenantId
+                ? (_tenantRoles.get(`${userId}:${tenantId}`) ?? [])
+                : (_users.get(userId)?.roles ?? []);
+            const memberships = (_groupMemberships.get(userId) ?? []).filter(m => m.tenantId === tenantId);
+            const groupRoles = memberships.flatMap(m => [
+                ...(_groups.get(m.groupId)?.roles ?? []),
+                ...m.roles,
+            ]);
+            return [...new Set([...direct, ...groupRoles])];
+        },
+        async getPasswordHistory(userId) {
+            return [...(_users.get(userId)?.passwordHistory ?? [])];
+        },
+        async addPasswordToHistory(userId, hash, maxCount) {
+            const user = _users.get(userId);
+            if (!user)
+                return;
+            user.passwordHistory.push(hash);
+            if (user.passwordHistory.length > maxCount) {
+                user.passwordHistory = user.passwordHistory.slice(-maxCount);
+            }
+        },
+        // -----------------------------------------------------------------------
+        // M2M client credentials
+        // -----------------------------------------------------------------------
+        async getM2MClient(clientId) {
+            for (const c of _m2mClients.values()) {
+                if (c.clientId === clientId && c.active)
+                    return { ...c };
+            }
+            return null;
+        },
+        async createM2MClient(data) {
+            const id = crypto.randomUUID();
+            evictOldest(_m2mClients, DEFAULT_MAX_ENTRIES);
+            _m2mClients.set(id, { id, ...data, active: true });
+            return { id };
+        },
+        async deleteM2MClient(clientId) {
+            for (const [key, c] of _m2mClients.entries()) {
+                if (c.clientId === clientId) {
+                    _m2mClients.delete(key);
+                    return;
+                }
+            }
+        },
+        async listM2MClients() {
+            return Array.from(_m2mClients.values()).map(({ clientSecretHash: _, ...rest }) => rest);
+        },
+        // -----------------------------------------------------------------------
+        // Session store methods
+        // -----------------------------------------------------------------------
+        memoryAtomicCreateSession(userId, token, sessionId, maxSessions, metadata) {
+            const now = Date.now();
+            const ids = _userSessionIds.get(userId);
+            if (ids) {
+                // Count active sessions and find oldest in a single pass
+                let activeCount = 0;
+                let oldest = null;
+                for (const sid of ids) {
+                    const s = _sessions.get(sid);
+                    if (s && s.token && s.expiresAt > now) {
+                        activeCount++;
+                        if (!oldest || s.createdAt < oldest.createdAt)
+                            oldest = s;
+                    }
+                }
+                // Evict oldest sessions until we have room for the new one
+                while (activeCount >= maxSessions && oldest) {
+                    memoryDeleteSession(oldest.sessionId);
+                    activeCount--;
+                    // Find next oldest
+                    oldest = null;
+                    for (const sid of ids) {
+                        const s = _sessions.get(sid);
+                        if (s && s.token && s.expiresAt > now) {
+                            if (!oldest || s.createdAt < oldest.createdAt)
+                                oldest = s;
+                        }
+                    }
+                }
+            }
+            // Create the new session
+            memoryCreateSession(userId, token, sessionId, metadata);
+        },
+        memoryCreateSession,
+        memoryGetSession(sessionId) {
+            const entry = _sessions.get(sessionId);
+            if (!entry || !entry.token || entry.expiresAt <= Date.now())
+                return null;
+            return entry.token;
+        },
+        memoryGetSessionRecord(sessionId) {
+            const entry = _sessions.get(sessionId);
+            if (!entry || !entry.token || entry.expiresAt <= Date.now())
+                return null;
+            return { token: entry.token, lastActiveAt: entry.lastActiveAt };
+        },
+        memoryDeleteSession,
+        memoryGetUserSessions(userId) {
+            const ids = _userSessionIds.get(userId);
+            if (!ids)
+                return [];
+            const now = Date.now();
+            const config = getConfig();
+            const includeInactive = config.includeInactiveSessions;
+            const persist = config.persistSessionMetadata;
+            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;
+        },
+        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;
+        },
+        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);
+        },
+        memoryUpdateSessionLastActive(sessionId) {
+            const entry = _sessions.get(sessionId);
+            if (entry)
+                entry.lastActiveAt = Date.now();
+        },
+        /** Test-only helper: set lastActiveAt to a specific timestamp for idle timeout testing. */
+        memorySetSessionLastActive(sessionId, ts) {
+            const entry = _sessions.get(sessionId);
+            if (entry)
+                entry.lastActiveAt = ts;
+        },
+        memoryGetSessionFingerprint(sessionId) {
+            return _sessions.get(sessionId)?.fingerprint ?? null;
+        },
+        memorySetSessionFingerprint(sessionId, fingerprint) {
+            const entry = _sessions.get(sessionId);
+            if (entry)
+                entry.fingerprint = fingerprint;
+        },
+        memoryGetMfaVerifiedAt(sessionId) {
+            return _sessions.get(sessionId)?.mfaVerifiedAt ?? null;
+        },
+        memorySetMfaVerifiedAt(sessionId, ts) {
+            const entry = _sessions.get(sessionId);
+            if (entry)
+                entry.mfaVerifiedAt = ts;
+        },
+        memorySetRefreshToken(sessionId, refreshToken) {
+            const entry = _sessions.get(sessionId);
+            if (!entry)
+                return;
+            const tokenHash = hashToken(refreshToken);
+            entry.refreshToken = tokenHash;
+            _refreshTokenIndex.set(tokenHash, sessionId);
+        },
+        memoryGetSessionByRefreshToken(refreshToken) {
+            const tokenHash = hashToken(refreshToken);
+            const sessionId = _refreshTokenIndex.get(tokenHash);
+            if (!sessionId)
+                return null;
+            const entry = _sessions.get(sessionId);
+            if (!entry)
+                return null;
+            // Current refresh token matches (compare hashes — timing-safe)
+            if (entry.refreshToken && timingSafeEqual(entry.refreshToken, tokenHash)) {
+                return { sessionId: entry.sessionId, userId: entry.userId, newRefreshToken: refreshToken };
+            }
+            // Check grace window (prevRefreshToken is stored as hash too — timing-safe)
+            if (entry.prevRefreshToken &&
+                timingSafeEqual(entry.prevRefreshToken, tokenHash) &&
+                entry.prevTokenExpiresAt &&
+                entry.prevTokenExpiresAt > Date.now()) {
+                // Return current plain refresh token so caller can re-issue it directly
+                return {
+                    sessionId: entry.sessionId,
+                    userId: entry.userId,
+                    newRefreshToken: entry.refreshTokenPlain ?? entry.refreshToken,
+                };
+            }
+            // Grace window expired — theft detected, invalidate session
+            if (entry.prevRefreshToken && timingSafeEqual(entry.prevRefreshToken, tokenHash)) {
+                memoryDeleteSession(sessionId);
+                return null;
+            }
+            return null;
+        },
+        memoryRotateRefreshToken(sessionId, newRefreshToken, newAccessToken) {
+            const entry = _sessions.get(sessionId);
+            if (!entry)
+                return;
+            const graceSeconds = getConfig().refreshToken?.rotationGraceSeconds ?? 30;
+            const newHash = hashToken(newRefreshToken);
+            // Move current hash to prev; store new hash and plain token as current
+            const oldHash = entry.refreshToken;
+            entry.prevRefreshToken = oldHash;
+            entry.prevTokenExpiresAt = Date.now() + graceSeconds * 1000;
+            entry.refreshToken = newHash;
+            entry.refreshTokenPlain = newRefreshToken;
+            entry.token = newAccessToken;
+            // Update reverse-lookup index
+            _refreshTokenIndex.set(newHash, sessionId);
+            // Old hash stays in index during grace window — cleaned up on next lookup or session delete
+        },
+        memoryDeleteUserSessions(userId) {
+            const sessionIds = _userSessionIds.get(userId);
+            if (!sessionIds)
+                return;
+            for (const sessionId of sessionIds) {
+                const session = _sessions.get(sessionId);
+                if (session) {
+                    if (session.refreshToken)
+                        _refreshTokenIndex.delete(session.refreshToken);
+                    if (session.prevRefreshToken)
+                        _refreshTokenIndex.delete(session.prevRefreshToken);
+                    _sessions.delete(sessionId);
+                }
+            }
+            _userSessionIds.delete(userId);
+        },
+        // -----------------------------------------------------------------------
+        // OAuth state helpers
+        // -----------------------------------------------------------------------
+        memoryStoreOAuthState(state, codeVerifier, linkUserId) {
+            evictExpired(_oauthStates);
+            evictOldest(_oauthStates, DEFAULT_MAX_ENTRIES);
+            _oauthStates.set(state, {
+                codeVerifier,
+                linkUserId,
+                expiresAt: Date.now() + OAUTH_STATE_TTL_MS,
+            });
+        },
+        memoryConsumeOAuthState(state) {
+            const entry = _oauthStates.get(state);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _oauthStates.delete(state);
+                return null;
+            }
+            _oauthStates.delete(state);
+            return { codeVerifier: entry.codeVerifier, linkUserId: entry.linkUserId };
+        },
+        // -----------------------------------------------------------------------
+        // Cache helpers
+        // -----------------------------------------------------------------------
+        memoryGetCache(key) {
+            const entry = _cache.get(key);
+            if (!entry)
+                return null;
+            if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+                _cache.delete(key);
+                return null;
+            }
+            return entry.value;
+        },
+        memorySetCache(key, value, ttlSeconds) {
+            const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1000 : undefined;
+            evictExpired(_cache);
+            evictOldest(_cache, DEFAULT_MAX_ENTRIES);
+            _cache.set(key, { value, expiresAt });
+        },
+        memoryDelCache(key) {
+            _cache.delete(key);
+        },
+        memoryDelCachePattern(pattern) {
+            // Convert glob * to a regex
+            const regex = new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$');
+            for (const key of _cache.keys()) {
+                if (regex.test(key))
+                    _cache.delete(key);
+            }
+        },
+        // -----------------------------------------------------------------------
+        // Email verification token helpers
+        // -----------------------------------------------------------------------
+        memoryCreateVerificationToken(token, userId, email, ttlSeconds) {
+            evictExpired(_verificationTokens);
+            evictOldest(_verificationTokens, DEFAULT_MAX_ENTRIES);
+            _verificationTokens.set(token, { userId, email, expiresAt: Date.now() + ttlSeconds * 1000 });
+        },
+        memoryGetVerificationToken(token) {
+            const entry = _verificationTokens.get(token);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _verificationTokens.delete(token);
+                return null;
+            }
+            return { userId: entry.userId, email: entry.email };
+        },
+        memoryDeleteVerificationToken(token) {
+            _verificationTokens.delete(token);
+        },
+        memoryConsumeVerificationToken(token) {
+            const entry = _verificationTokens.get(token);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _verificationTokens.delete(token);
+                return null;
+            }
+            _verificationTokens.delete(token);
+            return { userId: entry.userId, email: entry.email };
+        },
+        // -----------------------------------------------------------------------
+        // Password reset token helpers
+        // -----------------------------------------------------------------------
+        memoryCreateResetToken(token, userId, email, ttlSeconds) {
+            const now = Date.now();
+            evictExpired(_resetTokens);
+            evictOldest(_resetTokens, DEFAULT_MAX_ENTRIES);
+            _resetTokens.set(token, { userId, email, expiresAt: now + ttlSeconds * 1000 });
+        },
+        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 };
+        },
+        // -----------------------------------------------------------------------
+        // OAuth code helpers
+        // -----------------------------------------------------------------------
+        memoryStoreOAuthCode(hash, payload, ttlSeconds) {
+            evictExpired(_oauthCodes);
+            evictOldest(_oauthCodes, DEFAULT_MAX_ENTRIES);
+            _oauthCodes.set(hash, { ...payload, expiresAt: Date.now() + ttlSeconds * 1000 });
+        },
+        memoryConsumeOAuthCode(hash) {
+            const entry = _oauthCodes.get(hash);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _oauthCodes.delete(hash);
+                return null;
+            }
+            _oauthCodes.delete(hash);
+            return {
+                token: entry.token,
+                userId: entry.userId,
+                email: entry.email,
+                refreshToken: entry.refreshToken,
+            };
+        },
+        // -----------------------------------------------------------------------
+        // Account deletion cancel token helpers
+        // -----------------------------------------------------------------------
+        memoryCreateDeletionCancelToken(token, userId, jobId, ttlSeconds) {
+            const now = Date.now();
+            evictExpired(_cancelTokens);
+            evictOldest(_cancelTokens, DEFAULT_MAX_ENTRIES);
+            _cancelTokens.set(token, { userId, jobId, expiresAt: now + ttlSeconds * 1000 });
+        },
+        memoryConsumeDeletionCancelToken(hash) {
+            const entry = _cancelTokens.get(hash);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _cancelTokens.delete(hash);
+                return null;
+            }
+            _cancelTokens.delete(hash);
+            return { userId: entry.userId, jobId: entry.jobId };
+        },
+        // -----------------------------------------------------------------------
+        // Magic link token helpers
+        // -----------------------------------------------------------------------
+        memoryCreateMagicLinkToken(token, userId, ttlSeconds) {
+            const now = Date.now();
+            evictExpired(_magicLinkTokens);
+            evictOldest(_magicLinkTokens, DEFAULT_MAX_ENTRIES);
+            _magicLinkTokens.set(token, { userId, expiresAt: now + ttlSeconds * 1000 });
+        },
+        memoryConsumeMagicLinkToken(hash) {
+            const entry = _magicLinkTokens.get(hash);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _magicLinkTokens.delete(hash);
+                return null;
+            }
+            _magicLinkTokens.delete(hash);
+            return entry.userId;
+        },
+        // -----------------------------------------------------------------------
+        // OAuth re-auth state helpers
+        // -----------------------------------------------------------------------
+        memoryStoreOAuthReauth(hash, data, ttlSeconds) {
+            evictExpired(_oauthReauthStates);
+            evictOldest(_oauthReauthStates, DEFAULT_MAX_ENTRIES);
+            _oauthReauthStates.set(hash, { ...data, expiresAt: Date.now() + ttlSeconds * 1000 });
+        },
+        memoryConsumeOAuthReauth(hash) {
+            const entry = _oauthReauthStates.get(hash);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _oauthReauthStates.delete(hash);
+                return null;
+            }
+            _oauthReauthStates.delete(hash);
+            return {
+                userId: entry.userId,
+                sessionId: entry.sessionId,
+                provider: entry.provider,
+                purpose: entry.purpose,
+                expiresAt: entry.expiresAt,
+                returnUrl: entry.returnUrl,
+            };
+        },
+        memoryStoreOAuthReauthConfirmation(hash, data, ttlSeconds) {
+            evictExpired(_oauthReauthConfirmations);
+            evictOldest(_oauthReauthConfirmations, DEFAULT_MAX_ENTRIES);
+            _oauthReauthConfirmations.set(hash, { ...data, expiresAt: Date.now() + ttlSeconds * 1000 });
+        },
+        memoryConsumeOAuthReauthConfirmation(hash) {
+            const entry = _oauthReauthConfirmations.get(hash);
+            if (!entry || entry.expiresAt <= Date.now()) {
+                _oauthReauthConfirmations.delete(hash);
+                return null;
+            }
+            _oauthReauthConfirmations.delete(hash);
+            return { userId: entry.userId, purpose: entry.purpose };
+        },
+    };
+}