@lastshotlabs/bunshot 0.0.27 → 0.0.28

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

@@ -0,0 +1,1366 @@
+import { Database } from 'bun:sqlite';
+import { HttpError } from '../../../bunshot-core/src/index.js';
+import { hashToken } from '../../../bunshot-core/src/index.js';
+const MIGRATIONS = [
+    // v1: initial schema
+    db => {
+        db.run(`CREATE TABLE IF NOT EXISTS users (
+      id              TEXT PRIMARY KEY,
+      email           TEXT UNIQUE,
+      identifier      TEXT UNIQUE,
+      passwordHash    TEXT,
+      providerIds     TEXT NOT NULL DEFAULT '[]',
+      roles           TEXT NOT NULL DEFAULT '[]',
+      emailVerified   INTEGER NOT NULL DEFAULT 0,
+      displayName     TEXT,
+      firstName       TEXT,
+      lastName        TEXT,
+      externalId      TEXT,
+      suspended       INTEGER NOT NULL DEFAULT 0,
+      suspendedAt     TEXT,
+      suspendedReason TEXT,
+      mfaSecret       TEXT,
+      mfaEnabled      INTEGER NOT NULL DEFAULT 0,
+      recoveryCodes   TEXT NOT NULL DEFAULT '[]',
+      mfaMethods      TEXT NOT NULL DEFAULT '[]',
+      passwordHistory TEXT NOT NULL DEFAULT '[]',
+      user_metadata   TEXT NOT NULL DEFAULT '{}',
+      app_metadata    TEXT NOT NULL DEFAULT '{}'
+    )`);
+        db.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_users_identifier ON users(identifier) WHERE identifier IS NOT NULL');
+        db.run(`CREATE TABLE IF NOT EXISTS sessions (
+      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,
+      refreshToken      TEXT,
+      prevRefreshToken   TEXT,
+      prevTokenExpiresAt INTEGER,
+      fingerprint       TEXT,
+      mfaVerifiedAt     INTEGER,
+      refreshTokenPlain  TEXT
+    )`);
+        db.run('CREATE INDEX IF NOT EXISTS idx_sessions_userId ON sessions(userId)');
+        db.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_refreshToken ON sessions(refreshToken) WHERE refreshToken IS NOT NULL');
+        db.run(`CREATE TABLE IF NOT EXISTS oauth_states (
+      state        TEXT PRIMARY KEY,
+      codeVerifier TEXT,
+      linkUserId   TEXT,
+      expiresAt    INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS cache_entries (
+      key       TEXT PRIMARY KEY,
+      value     TEXT NOT NULL,
+      expiresAt INTEGER  -- NULL = indefinite
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS email_verifications (
+      token     TEXT PRIMARY KEY,
+      userId    TEXT NOT NULL,
+      email     TEXT NOT NULL,
+      expiresAt INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS password_resets (
+      token     TEXT PRIMARY KEY,
+      userId    TEXT NOT NULL,
+      email     TEXT NOT NULL,
+      expiresAt INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS tenant_roles (
+      userId    TEXT NOT NULL,
+      tenantId  TEXT NOT NULL,
+      role      TEXT NOT NULL,
+      PRIMARY KEY (userId, tenantId, role)
+    )`);
+        db.run('CREATE INDEX IF NOT EXISTS idx_tenant_roles_tenant ON tenant_roles(tenantId)');
+        db.run(`CREATE TABLE IF NOT EXISTS webauthn_credentials (
+      credentialId TEXT PRIMARY KEY,
+      userId       TEXT NOT NULL,
+      publicKey    TEXT NOT NULL,
+      signCount    INTEGER NOT NULL DEFAULT 0,
+      transports   TEXT NOT NULL DEFAULT '[]',
+      name         TEXT,
+      createdAt    INTEGER NOT NULL
+    )`);
+        db.run('CREATE INDEX IF NOT EXISTS idx_webauthn_userId ON webauthn_credentials(userId)');
+        db.run(`CREATE TABLE IF NOT EXISTS groups (
+      id          TEXT    PRIMARY KEY,
+      name        TEXT    NOT NULL,
+      displayName TEXT,
+      description TEXT,
+      roles       TEXT    NOT NULL DEFAULT '[]',
+      tenantId    TEXT,
+      createdAt   INTEGER NOT NULL,
+      updatedAt   INTEGER NOT NULL
+    )`);
+        // SQLite UNIQUE treats each NULL as distinct, so we use partial indexes instead of
+        // a simple UNIQUE constraint on (name, tenantId). This correctly enforces name
+        // uniqueness within app-wide scope and within each tenant scope separately.
+        db.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_groups_name_appwide ON groups(name) WHERE tenantId IS NULL');
+        db.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_groups_name_tenant ON groups(name, tenantId) WHERE tenantId IS NOT NULL');
+        db.run('CREATE INDEX IF NOT EXISTS idx_groups_tenantId ON groups(tenantId)');
+        db.run(`CREATE TABLE IF NOT EXISTS group_memberships (
+      userId    TEXT    NOT NULL,
+      groupId   TEXT    NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
+      roles     TEXT    NOT NULL DEFAULT '[]',
+      tenantId  TEXT,
+      createdAt INTEGER NOT NULL,
+      PRIMARY KEY (userId, groupId)
+    )`);
+        // NOTE: PRAGMA foreign_keys = ON must run per-connection.
+        db.run('CREATE INDEX IF NOT EXISTS idx_gm_groupId ON group_memberships(groupId)');
+        db.run('CREATE INDEX IF NOT EXISTS idx_gm_userId_tenantId ON group_memberships(userId, tenantId)');
+        db.run(`CREATE TABLE IF NOT EXISTS oauth_codes (
+      codeHash     TEXT PRIMARY KEY,
+      token        TEXT NOT NULL,
+      userId       TEXT NOT NULL,
+      email        TEXT,
+      refreshToken TEXT,
+      expiresAt    INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS deletion_cancel_tokens (
+      token     TEXT PRIMARY KEY,
+      userId    TEXT NOT NULL,
+      jobId     TEXT NOT NULL,
+      expiresAt INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS magic_link_tokens (
+      token     TEXT PRIMARY KEY,
+      userId    TEXT NOT NULL,
+      expiresAt INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS oauth_reauth_states (
+      tokenHash TEXT PRIMARY KEY,
+      userId    TEXT NOT NULL,
+      sessionId TEXT NOT NULL,
+      provider  TEXT NOT NULL,
+      purpose   TEXT NOT NULL,
+      returnUrl TEXT,
+      expiresAt INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS oauth_reauth_confirmations (
+      codeHash  TEXT PRIMARY KEY,
+      userId    TEXT NOT NULL,
+      purpose   TEXT NOT NULL,
+      expiresAt INTEGER NOT NULL
+    )`);
+        db.run(`CREATE TABLE IF NOT EXISTS upload_registry (
+      key           TEXT PRIMARY KEY,
+      ownerUserId   TEXT,
+      tenantId      TEXT,
+      mimeType      TEXT,
+      bucket        TEXT,
+      createdAt     INTEGER NOT NULL
+    )`);
+    },
+    // v2: M2M clients table
+    db => {
+        db.run(`CREATE TABLE IF NOT EXISTS m2m_clients (
+      id               TEXT    PRIMARY KEY,
+      clientId         TEXT    NOT NULL UNIQUE,
+      clientSecretHash TEXT    NOT NULL,
+      name             TEXT    NOT NULL,
+      scopes           TEXT    NOT NULL DEFAULT '[]',
+      active           INTEGER NOT NULL DEFAULT 1,
+      createdAt        INTEGER NOT NULL
+    )`);
+        db.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_m2m_clients_clientId ON m2m_clients(clientId)');
+    },
+    // Add future migrations here. Each entry is applied exactly once to any
+    // database whose user_version is less than the entry's 1-based index.
+    // Example:
+    //   (db) => { db.run('ALTER TABLE users ADD COLUMN phoneNumber TEXT'); },
+];
+function runMigrations(db) {
+    const { user_version: currentVersion } = db
+        .query('PRAGMA user_version')
+        .get();
+    for (let i = currentVersion; i < MIGRATIONS.length; i++) {
+        MIGRATIONS[i](db);
+        // PRAGMA user_version cannot use parameter binding — i+1 is always a
+        // literal integer from our own code, never user input.
+        db.run(`PRAGMA user_version = ${i + 1}`);
+    }
+}
+function encodeSqliteCursor(createdAt, id) {
+    return btoa(JSON.stringify({ createdAt, id }));
+}
+function decodeSqliteCursor(cursor) {
+    try {
+        return JSON.parse(atob(cursor));
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_SESSION_TTL_MS = 60 * 60 * 24 * 7 * 1000; // 7 days
+export function createSqliteAuthAdapter(path) {
+    const db = new Database(path, { create: true });
+    db.run('PRAGMA journal_mode = WAL');
+    db.run('PRAGMA foreign_keys = ON');
+    runMigrations(db);
+    let _cleanupInterval = null;
+    function runCleanup(getConfig) {
+        const now = Date.now();
+        if (getConfig().persistSessionMetadata) {
+            // Null out tokens for expired sessions but keep the metadata row
+            db.run('UPDATE sessions SET token = NULL WHERE expiresAt <= ? AND token IS NOT NULL', [now]);
+        }
+        else {
+            db.run('DELETE FROM sessions WHERE expiresAt <= ?', [now]);
+        }
+        db.run('DELETE FROM oauth_states WHERE expiresAt <= ?', [now]);
+        db.run('DELETE FROM cache_entries WHERE expiresAt IS NOT NULL AND expiresAt <= ?', [now]);
+        db.run('DELETE FROM email_verifications WHERE expiresAt <= ?', [now]);
+        db.run('DELETE FROM password_resets WHERE expiresAt <= ?', [now]);
+        db.run('DELETE FROM oauth_codes WHERE expiresAt <= ?', [now]);
+        db.run('DELETE FROM oauth_reauth_states WHERE expiresAt <= ?', [now]);
+        db.run('DELETE FROM oauth_reauth_confirmations WHERE expiresAt <= ?', [now]);
+    }
+    function getSessionTtlMs(getConfig) {
+        const abs = getConfig().sessionPolicy.absoluteTimeout;
+        return abs ? abs * 1000 : DEFAULT_SESSION_TTL_MS;
+    }
+    // ---------------------------------------------------------------------------
+    // Auth adapter
+    // ---------------------------------------------------------------------------
+    const adapter = {
+        async findByEmail(email) {
+            const row = db
+                .query('SELECT id, passwordHash FROM users WHERE email = ?')
+                .get(email);
+            return row ?? null;
+        },
+        verifyPassword(userId, password) {
+            const row = db
+                .query('SELECT passwordHash FROM users WHERE id = ?')
+                .get(userId);
+            if (!row?.passwordHash)
+                return Promise.resolve(false);
+            return Bun.password.verify(password, row.passwordHash);
+        },
+        getIdentifier(userId) {
+            const row = db
+                .query('SELECT identifier, email FROM users WHERE id = ?')
+                .get(userId);
+            return Promise.resolve(row?.identifier ?? row?.email ?? '');
+        },
+        async create(email, passwordHash) {
+            const id = crypto.randomUUID();
+            const normalized = email.toLowerCase();
+            try {
+                db.run('INSERT INTO users (id, email, identifier, passwordHash) VALUES (?, ?, ?, ?)', [
+                    id,
+                    normalized,
+                    normalized,
+                    passwordHash,
+                ]);
+                return { id };
+            }
+            catch (err) {
+                if (err?.code === 'SQLITE_CONSTRAINT_UNIQUE')
+                    throw new HttpError(409, 'Email already registered');
+                throw err;
+            }
+        },
+        async setPassword(userId, passwordHash) {
+            db.run('UPDATE users SET passwordHash = ? WHERE id = ?', [passwordHash, userId]);
+        },
+        async getPasswordHistory(userId) {
+            const row = db
+                .query('SELECT passwordHistory FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return [];
+            try {
+                return JSON.parse(row.passwordHistory);
+            }
+            catch {
+                return [];
+            }
+        },
+        async addPasswordToHistory(userId, hash, maxCount) {
+            const row = db
+                .query('SELECT passwordHistory FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return;
+            let history = [];
+            try {
+                history = JSON.parse(row.passwordHistory);
+            }
+            catch {
+                history = [];
+            }
+            history.push(hash);
+            // Keep only the most recent maxCount entries
+            if (history.length > maxCount)
+                history = history.slice(-maxCount);
+            db.run('UPDATE users SET passwordHistory = ? WHERE id = ?', [
+                JSON.stringify(history),
+                userId,
+            ]);
+        },
+        async findOrCreateByProvider(provider, providerId, profile) {
+            const key = `${provider}:${providerId}`;
+            // Find by provider key using json_each
+            const existing = db
+                .query('SELECT u.id FROM users u, json_each(u.providerIds) p WHERE p.value = ?')
+                .get(key);
+            if (existing)
+                return { id: existing.id, created: false };
+            // Reject if email belongs to a credential account
+            if (profile.email) {
+                const emailUser = db
+                    .query('SELECT id FROM users WHERE email = ?')
+                    .get(profile.email);
+                if (emailUser)
+                    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 normalizedEmail = profile.email ? profile.email.toLowerCase() : null;
+            db.run('INSERT INTO users (id, email, identifier, providerIds) VALUES (?, ?, ?, ?)', [
+                id,
+                normalizedEmail,
+                normalizedEmail,
+                JSON.stringify([key]),
+            ]);
+            return { id, created: true };
+        },
+        async linkProvider(userId, provider, providerId) {
+            const key = `${provider}:${providerId}`;
+            const row = db
+                .query('SELECT id, providerIds FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                throw new HttpError(404, 'User not found');
+            const ids = JSON.parse(row.providerIds);
+            if (!ids.includes(key)) {
+                db.run('UPDATE users SET providerIds = ? WHERE id = ?', [
+                    JSON.stringify([...ids, key]),
+                    userId,
+                ]);
+            }
+        },
+        async getRoles(userId) {
+            const row = db
+                .query('SELECT roles FROM users WHERE id = ?')
+                .get(userId);
+            return row ? JSON.parse(row.roles) : [];
+        },
+        async setRoles(userId, roles) {
+            db.run('UPDATE users SET roles = ? WHERE id = ?', [JSON.stringify(roles), userId]);
+        },
+        async addRole(userId, role) {
+            const row = db
+                .query('SELECT roles FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return;
+            const roles = JSON.parse(row.roles);
+            if (!roles.includes(role)) {
+                db.run('UPDATE users SET roles = ? WHERE id = ?', [
+                    JSON.stringify([...roles, role]),
+                    userId,
+                ]);
+            }
+        },
+        async removeRole(userId, role) {
+            const row = db
+                .query('SELECT roles FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return;
+            const roles = JSON.parse(row.roles);
+            db.run('UPDATE users SET roles = ? WHERE id = ?', [
+                JSON.stringify(roles.filter(r => r !== role)),
+                userId,
+            ]);
+        },
+        async getUser(userId) {
+            const row = db
+                .query('SELECT email, providerIds, emailVerified, displayName, firstName, lastName, externalId, suspended, suspendedReason, user_metadata, app_metadata FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return null;
+            const userMeta = JSON.parse(row.user_metadata || '{}');
+            const appMeta = JSON.parse(row.app_metadata || '{}');
+            return {
+                email: row.email ?? undefined,
+                providerIds: JSON.parse(row.providerIds),
+                emailVerified: row.emailVerified === 1,
+                displayName: row.displayName ?? undefined,
+                firstName: row.firstName ?? undefined,
+                lastName: row.lastName ?? undefined,
+                externalId: row.externalId ?? undefined,
+                suspended: row.suspended === 1,
+                suspendedReason: row.suspendedReason ?? undefined,
+                userMetadata: Object.keys(userMeta).length > 0 ? userMeta : undefined,
+                appMetadata: Object.keys(appMeta).length > 0 ? appMeta : undefined,
+            };
+        },
+        async unlinkProvider(userId, provider) {
+            const row = db
+                .query('SELECT providerIds FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                throw new HttpError(404, 'User not found');
+            const ids = JSON.parse(row.providerIds);
+            db.run('UPDATE users SET providerIds = ? WHERE id = ?', [
+                JSON.stringify(ids.filter(id => !id.startsWith(`${provider}:`))),
+                userId,
+            ]);
+        },
+        async findByIdentifier(value) {
+            const normalized = value.toLowerCase();
+            const row = db
+                .query('SELECT id, passwordHash FROM users WHERE identifier = ? OR email = ? LIMIT 1')
+                .get(normalized, normalized);
+            if (!row)
+                return null;
+            return { id: row.id, passwordHash: row.passwordHash ?? '' };
+        },
+        async setEmailVerified(userId, verified) {
+            db.run('UPDATE users SET emailVerified = ? WHERE id = ?', [verified ? 1 : 0, userId]);
+        },
+        async getEmailVerified(userId) {
+            const row = db
+                .query('SELECT emailVerified FROM users WHERE id = ?')
+                .get(userId);
+            return row?.emailVerified === 1;
+        },
+        async deleteUser(userId) {
+            db.transaction(() => {
+                db.run('DELETE FROM sessions WHERE userId = ?', [userId]);
+                db.run('DELETE FROM tenant_roles WHERE userId = ?', [userId]);
+                db.run('DELETE FROM group_memberships WHERE userId = ?', [userId]);
+                db.run('DELETE FROM webauthn_credentials WHERE userId = ?', [userId]);
+                db.run('DELETE FROM users WHERE id = ?', [userId]);
+            })();
+        },
+        async hasPassword(userId) {
+            const row = db
+                .query('SELECT passwordHash FROM users WHERE id = ?')
+                .get(userId);
+            return !!row?.passwordHash;
+        },
+        async setMfaSecret(userId, secret) {
+            db.run('UPDATE users SET mfaSecret = ? WHERE id = ?', [secret, userId]);
+        },
+        async getMfaSecret(userId) {
+            const row = db
+                .query('SELECT mfaSecret FROM users WHERE id = ?')
+                .get(userId);
+            return row?.mfaSecret ?? null;
+        },
+        async isMfaEnabled(userId) {
+            const row = db
+                .query('SELECT mfaEnabled FROM users WHERE id = ?')
+                .get(userId);
+            return row?.mfaEnabled === 1;
+        },
+        async setMfaEnabled(userId, enabled) {
+            db.run('UPDATE users SET mfaEnabled = ? WHERE id = ?', [enabled ? 1 : 0, userId]);
+        },
+        async setRecoveryCodes(userId, codes) {
+            db.run('UPDATE users SET recoveryCodes = ? WHERE id = ?', [JSON.stringify(codes), userId]);
+        },
+        async getRecoveryCodes(userId) {
+            const row = db
+                .query('SELECT recoveryCodes FROM users WHERE id = ?')
+                .get(userId);
+            return row?.recoveryCodes ? JSON.parse(row.recoveryCodes) : [];
+        },
+        async removeRecoveryCode(userId, code) {
+            db.transaction(() => {
+                const row = db
+                    .query('SELECT recoveryCodes FROM users WHERE id = ?')
+                    .get(userId);
+                if (!row)
+                    return;
+                let codes = [];
+                try {
+                    codes = JSON.parse(row.recoveryCodes || '[]');
+                }
+                catch {
+                    return;
+                }
+                const idx = codes.indexOf(code);
+                if (idx !== -1) {
+                    codes.splice(idx, 1);
+                    db.run('UPDATE users SET recoveryCodes = ? WHERE id = ?', [
+                        JSON.stringify(codes),
+                        userId,
+                    ]);
+                }
+            })();
+        },
+        consumeRecoveryCode(userId, hashedCode) {
+            // Wrap the read-splice-write in a SQLite transaction so it is atomic.
+            const result = db.transaction(() => {
+                const row = db
+                    .query('SELECT recoveryCodes FROM users WHERE id = ?')
+                    .get(userId);
+                if (!row)
+                    return false;
+                let codes = [];
+                try {
+                    codes = JSON.parse(row.recoveryCodes || '[]');
+                }
+                catch {
+                    return false;
+                }
+                const idx = codes.indexOf(hashedCode);
+                if (idx === -1)
+                    return false;
+                codes.splice(idx, 1);
+                db.run('UPDATE users SET recoveryCodes = ? WHERE id = ?', [JSON.stringify(codes), userId]);
+                return true;
+            })();
+            return Promise.resolve(result);
+        },
+        async getMfaMethods(userId) {
+            const row = db
+                .query('SELECT mfaMethods FROM users WHERE id = ?')
+                .get(userId);
+            return row?.mfaMethods ? JSON.parse(row.mfaMethods) : [];
+        },
+        async setMfaMethods(userId, methods) {
+            db.run('UPDATE users SET mfaMethods = ? WHERE id = ?', [JSON.stringify(methods), userId]);
+        },
+        async getWebAuthnCredentials(userId) {
+            const rows = db
+                .query('SELECT credentialId, publicKey, signCount, transports, name, createdAt FROM webauthn_credentials WHERE userId = ?')
+                .all(userId);
+            return rows.map(r => ({
+                credentialId: r.credentialId,
+                publicKey: r.publicKey,
+                signCount: r.signCount,
+                transports: JSON.parse(r.transports),
+                name: r.name ?? undefined,
+                createdAt: r.createdAt,
+            }));
+        },
+        async addWebAuthnCredential(userId, credential) {
+            db.run('INSERT INTO webauthn_credentials (credentialId, userId, publicKey, signCount, transports, name, createdAt) VALUES (?, ?, ?, ?, ?, ?, ?)', [
+                credential.credentialId,
+                userId,
+                credential.publicKey,
+                credential.signCount,
+                JSON.stringify(credential.transports ?? []),
+                credential.name ?? null,
+                credential.createdAt,
+            ]);
+        },
+        async removeWebAuthnCredential(userId, credentialId) {
+            db.run('DELETE FROM webauthn_credentials WHERE credentialId = ? AND userId = ?', [
+                credentialId,
+                userId,
+            ]);
+        },
+        async updateWebAuthnCredentialSignCount(userId, credentialId, signCount) {
+            db.run('UPDATE webauthn_credentials SET signCount = ? WHERE credentialId = ? AND userId = ?', [signCount, credentialId, userId]);
+        },
+        async findUserByWebAuthnCredentialId(credentialId) {
+            const row = db
+                .query('SELECT userId FROM webauthn_credentials WHERE credentialId = ?')
+                .get(credentialId);
+            return row?.userId ?? null;
+        },
+        async getTenantRoles(userId, tenantId) {
+            const rows = db
+                .query('SELECT role FROM tenant_roles WHERE userId = ? AND tenantId = ?')
+                .all(userId, tenantId);
+            return rows.map(r => r.role);
+        },
+        async setTenantRoles(userId, tenantId, roles) {
+            db.run('DELETE FROM tenant_roles WHERE userId = ? AND tenantId = ?', [userId, tenantId]);
+            const stmt = db.prepare('INSERT INTO tenant_roles (userId, tenantId, role) VALUES (?, ?, ?)');
+            for (const role of roles) {
+                stmt.run(userId, tenantId, role);
+            }
+        },
+        async addTenantRole(userId, tenantId, role) {
+            try {
+                db.run('INSERT INTO tenant_roles (userId, tenantId, role) VALUES (?, ?, ?)', [
+                    userId,
+                    tenantId,
+                    role,
+                ]);
+            }
+            catch {
+                /* already exists */
+            }
+        },
+        async removeTenantRole(userId, tenantId, role) {
+            db.run('DELETE FROM tenant_roles WHERE userId = ? AND tenantId = ? AND role = ?', [
+                userId,
+                tenantId,
+                role,
+            ]);
+        },
+        async setSuspended(userId, suspended, reason) {
+            if (suspended) {
+                db.run('UPDATE users SET suspended = 1, suspendedAt = ?, suspendedReason = ? WHERE id = ?', [new Date().toISOString(), reason ?? null, userId]);
+            }
+            else {
+                db.run('UPDATE users SET suspended = 0, suspendedAt = NULL, suspendedReason = NULL WHERE id = ?', [userId]);
+            }
+        },
+        async getSuspended(userId) {
+            const row = db
+                .query('SELECT suspended, suspendedReason FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return null;
+            return { suspended: row.suspended === 1, suspendedReason: row.suspendedReason ?? undefined };
+        },
+        async updateProfile(userId, fields) {
+            const sets = [];
+            const params = [];
+            if ('displayName' in fields) {
+                sets.push('displayName = ?');
+                params.push(fields.displayName ?? null);
+            }
+            if ('firstName' in fields) {
+                sets.push('firstName = ?');
+                params.push(fields.firstName ?? null);
+            }
+            if ('lastName' in fields) {
+                sets.push('lastName = ?');
+                params.push(fields.lastName ?? null);
+            }
+            if ('externalId' in fields) {
+                sets.push('externalId = ?');
+                params.push(fields.externalId ?? null);
+            }
+            if ('userMetadata' in fields) {
+                sets.push('user_metadata = ?');
+                params.push(JSON.stringify(fields.userMetadata ?? {}));
+            }
+            if (sets.length === 0)
+                return;
+            params.push(userId);
+            db.run(`UPDATE users SET ${sets.join(', ')} WHERE id = ?`, params);
+        },
+        async getUserMetadata(userId) {
+            const row = db
+                .query('SELECT user_metadata, app_metadata FROM users WHERE id = ?')
+                .get(userId);
+            if (!row)
+                return {};
+            const userMeta = JSON.parse(row.user_metadata || '{}');
+            const appMeta = JSON.parse(row.app_metadata || '{}');
+            return {
+                userMetadata: Object.keys(userMeta).length > 0 ? userMeta : undefined,
+                appMetadata: Object.keys(appMeta).length > 0 ? appMeta : undefined,
+            };
+        },
+        async setUserMetadata(userId, data) {
+            db.run('UPDATE users SET user_metadata = ? WHERE id = ?', [JSON.stringify(data), userId]);
+        },
+        async setAppMetadata(userId, data) {
+            db.run('UPDATE users SET app_metadata = ? WHERE id = ?', [JSON.stringify(data), userId]);
+        },
+        async listUsers(query) {
+            const conditions = [];
+            const params = [];
+            if (query.email !== undefined) {
+                conditions.push('email = ?');
+                params.push(query.email);
+            }
+            if (query.externalId !== undefined) {
+                conditions.push('externalId = ?');
+                params.push(query.externalId);
+            }
+            if (query.suspended !== undefined) {
+                conditions.push('suspended = ?');
+                params.push(query.suspended ? 1 : 0);
+            }
+            const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+            const startIndex = query.startIndex ?? 0;
+            const count = query.count ?? 100;
+            const queryParams = [...params, count, startIndex];
+            const countParams = params;
+            const rows = db
+                .prepare(`SELECT id, email, displayName, firstName, lastName, externalId, suspended, suspendedAt, suspendedReason, emailVerified, providerIds FROM users ${where} LIMIT ? OFFSET ?`)
+                .all(...queryParams);
+            const totalRow = db
+                .prepare(`SELECT COUNT(*) as c FROM users ${where}`)
+                .get(...countParams);
+            const totalResults = totalRow?.c ?? 0;
+            return {
+                users: rows.map(r => ({
+                    id: r.id,
+                    email: r.email ?? undefined,
+                    displayName: r.displayName ?? undefined,
+                    firstName: r.firstName ?? undefined,
+                    lastName: r.lastName ?? undefined,
+                    externalId: r.externalId ?? undefined,
+                    suspended: r.suspended === 1,
+                    suspendedAt: r.suspendedAt ? new Date(r.suspendedAt) : undefined,
+                    suspendedReason: r.suspendedReason ?? undefined,
+                    emailVerified: r.emailVerified === 1,
+                    providerIds: JSON.parse(r.providerIds),
+                })),
+                totalResults,
+            };
+        },
+        // ---------------------------------------------------------------------------
+        // Groups
+        // ---------------------------------------------------------------------------
+        async createGroup(group) {
+            const id = crypto.randomUUID();
+            const now = Date.now();
+            try {
+                db.run('INSERT INTO groups (id, name, displayName, description, roles, tenantId, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [
+                    id,
+                    group.name,
+                    group.displayName ?? null,
+                    group.description ?? null,
+                    JSON.stringify(group.roles ?? []),
+                    group.tenantId ?? null,
+                    now,
+                    now,
+                ]);
+            }
+            catch (err) {
+                if (err?.code === 'SQLITE_CONSTRAINT_UNIQUE' ||
+                    err?.code === 'SQLITE_CONSTRAINT_PRIMARYKEY') {
+                    throw new HttpError(409, 'A group with this name already exists in this scope');
+                }
+                throw err;
+            }
+            return { id };
+        },
+        async deleteGroup(groupId) {
+            // group_memberships are cascade-deleted via ON DELETE CASCADE (requires PRAGMA foreign_keys = ON)
+            db.run('DELETE FROM groups WHERE id = ?', [groupId]);
+        },
+        async getGroup(groupId) {
+            const row = db
+                .query('SELECT id, name, displayName, description, roles, tenantId, createdAt, updatedAt FROM groups WHERE id = ?')
+                .get(groupId);
+            if (!row)
+                return null;
+            return {
+                ...row,
+                displayName: row.displayName ?? undefined,
+                description: row.description ?? undefined,
+                roles: JSON.parse(row.roles),
+            };
+        },
+        async listGroups(tenantId, opts) {
+            const limit = Math.min(opts?.limit ?? 50, 200);
+            const cols = 'id, name, displayName, description, roles, tenantId, createdAt, updatedAt';
+            const conditions = [];
+            const params = [];
+            if (tenantId === null) {
+                conditions.push('tenantId IS NULL');
+            }
+            else {
+                conditions.push('tenantId = ?');
+                params.push(tenantId);
+            }
+            if (opts?.cursor) {
+                const c = decodeSqliteCursor(opts.cursor);
+                if (c) {
+                    conditions.push('(createdAt > ? OR (createdAt = ? AND id > ?))');
+                    params.push(c.createdAt, c.createdAt, c.id);
+                }
+            }
+            const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+            params.push(limit + 1);
+            const rows = db
+                .query(`SELECT ${cols} FROM groups ${where} ORDER BY createdAt ASC, id ASC LIMIT ?`)
+                .all(...params);
+            const hasMore = rows.length > limit;
+            const page = hasMore ? rows.slice(0, limit) : rows;
+            const nextCursor = hasMore
+                ? encodeSqliteCursor(page[page.length - 1].createdAt, page[page.length - 1].id)
+                : undefined;
+            const items = page.map(r => ({
+                ...r,
+                displayName: r.displayName ?? undefined,
+                description: r.description ?? undefined,
+                roles: JSON.parse(r.roles),
+            }));
+            return { items, nextCursor };
+        },
+        async updateGroup(groupId, updates) {
+            const now = Date.now();
+            const sets = ['updatedAt = ?'];
+            const params = [now];
+            if (updates.name !== undefined) {
+                sets.push('name = ?');
+                params.push(updates.name);
+            }
+            if ('displayName' in updates) {
+                sets.push('displayName = ?');
+                params.push(updates.displayName ?? null);
+            }
+            if ('description' in updates) {
+                sets.push('description = ?');
+                params.push(updates.description ?? null);
+            }
+            if (updates.roles !== undefined) {
+                sets.push('roles = ?');
+                params.push(JSON.stringify(updates.roles));
+            }
+            params.push(groupId);
+            db.run(`UPDATE groups SET ${sets.join(', ')} WHERE id = ?`, params);
+        },
+        async addGroupMember(groupId, userId, roles = []) {
+            const group = db
+                .query('SELECT tenantId FROM groups WHERE id = ?')
+                .get(groupId);
+            if (!group)
+                throw new HttpError(404, 'Group not found');
+            try {
+                db.run('INSERT INTO group_memberships (userId, groupId, roles, tenantId, createdAt) VALUES (?, ?, ?, ?, ?)', [userId, groupId, JSON.stringify(roles), group.tenantId ?? null, Date.now()]);
+            }
+            catch (err) {
+                if (err?.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' ||
+                    err?.code === 'SQLITE_CONSTRAINT_UNIQUE') {
+                    throw new HttpError(409, 'User is already a member of this group');
+                }
+                throw err;
+            }
+        },
+        async updateGroupMembership(groupId, userId, roles) {
+            db.run('UPDATE group_memberships SET roles = ? WHERE userId = ? AND groupId = ?', [
+                JSON.stringify(roles),
+                userId,
+                groupId,
+            ]);
+        },
+        async removeGroupMember(groupId, userId) {
+            db.run('DELETE FROM group_memberships WHERE userId = ? AND groupId = ?', [userId, groupId]);
+        },
+        async getGroupMembers(groupId, opts) {
+            const limit = Math.min(opts?.limit ?? 50, 200);
+            const conditions = ['groupId = ?'];
+            const params = [groupId];
+            if (opts?.cursor) {
+                const c = decodeSqliteCursor(opts.cursor);
+                if (c) {
+                    conditions.push('(createdAt > ? OR (createdAt = ? AND userId > ?))');
+                    params.push(c.createdAt, c.createdAt, c.id);
+                }
+            }
+            const where = conditions.join(' AND ');
+            params.push(limit + 1);
+            const rows = db
+                .query(`SELECT userId, roles, createdAt FROM group_memberships WHERE ${where} ORDER BY createdAt ASC, userId ASC LIMIT ?`)
+                .all(...params);
+            const hasMore = rows.length > limit;
+            const page = hasMore ? rows.slice(0, limit) : rows;
+            const nextCursor = hasMore
+                ? encodeSqliteCursor(page[page.length - 1].createdAt, page[page.length - 1].userId)
+                : undefined;
+            return {
+                items: page.map(r => ({ userId: r.userId, roles: JSON.parse(r.roles) })),
+                nextCursor,
+            };
+        },
+        async getUserGroups(userId, tenantId) {
+            let memberRows;
+            if (tenantId === null) {
+                memberRows = db
+                    .query('SELECT groupId, roles as memberRoles FROM group_memberships WHERE userId = ? AND tenantId IS NULL')
+                    .all(userId);
+            }
+            else {
+                memberRows = db
+                    .query('SELECT groupId, roles as memberRoles FROM group_memberships WHERE userId = ? AND tenantId = ?')
+                    .all(userId, tenantId);
+            }
+            if (memberRows.length === 0)
+                return [];
+            const result = [];
+            for (const m of memberRows) {
+                const row = db
+                    .query('SELECT id, name, displayName, description, roles, tenantId, createdAt, updatedAt FROM groups WHERE id = ?')
+                    .get(m.groupId);
+                if (row) {
+                    result.push({
+                        group: {
+                            ...row,
+                            displayName: row.displayName ?? undefined,
+                            description: row.description ?? undefined,
+                            roles: JSON.parse(row.roles),
+                        },
+                        membershipRoles: JSON.parse(m.memberRoles),
+                    });
+                }
+            }
+            return result;
+        },
+        async getEffectiveRoles(userId, tenantId) {
+            // Direct roles
+            let direct = [];
+            if (tenantId) {
+                const rows = db
+                    .query('SELECT role FROM tenant_roles WHERE userId = ? AND tenantId = ?')
+                    .all(userId, tenantId);
+                direct = rows.map(r => r.role);
+            }
+            else {
+                const row = db
+                    .query('SELECT roles FROM users WHERE id = ?')
+                    .get(userId);
+                direct = row ? JSON.parse(row.roles) : [];
+            }
+            let memberRows;
+            if (tenantId === null) {
+                memberRows = db
+                    .query('SELECT g.roles as groupRoles, gm.roles as memberRoles FROM group_memberships gm JOIN groups g ON g.id = gm.groupId WHERE gm.userId = ? AND gm.tenantId IS NULL')
+                    .all(userId);
+            }
+            else {
+                memberRows = db
+                    .query('SELECT g.roles as groupRoles, gm.roles as memberRoles FROM group_memberships gm JOIN groups g ON g.id = gm.groupId WHERE gm.userId = ? AND gm.tenantId = ?')
+                    .all(userId, tenantId);
+            }
+            const groupRoles = memberRows.flatMap(r => [
+                ...JSON.parse(r.groupRoles),
+                ...JSON.parse(r.memberRoles),
+            ]);
+            return [...new Set([...direct, ...groupRoles])];
+        },
+        async getM2MClient(clientId) {
+            const row = db
+                .query('SELECT id, clientId, clientSecretHash, name, scopes, active FROM m2m_clients WHERE clientId = ? AND active = 1')
+                .get(clientId);
+            if (!row)
+                return null;
+            return {
+                id: row.id,
+                clientId: row.clientId,
+                clientSecretHash: row.clientSecretHash,
+                name: row.name,
+                scopes: JSON.parse(row.scopes),
+                active: row.active === 1,
+            };
+        },
+        async createM2MClient(data) {
+            const id = crypto.randomUUID();
+            db.run('INSERT INTO m2m_clients (id, clientId, clientSecretHash, name, scopes, active, createdAt) VALUES (?, ?, ?, ?, ?, 1, ?)', [
+                id,
+                data.clientId,
+                data.clientSecretHash,
+                data.name,
+                JSON.stringify(data.scopes),
+                Date.now(),
+            ]);
+            return { id };
+        },
+        async deleteM2MClient(clientId) {
+            db.run('DELETE FROM m2m_clients WHERE clientId = ?', [clientId]);
+        },
+        async listM2MClients() {
+            const rows = db
+                .query('SELECT id, clientId, name, scopes, active FROM m2m_clients')
+                .all();
+            return rows.map(row => ({
+                id: row.id,
+                clientId: row.clientId,
+                name: row.name,
+                scopes: JSON.parse(row.scopes),
+                active: row.active === 1,
+            }));
+        },
+    };
+    // ---------------------------------------------------------------------------
+    // Session helpers
+    // ---------------------------------------------------------------------------
+    function deleteSessionImpl(sessionId, getConfig) {
+        if (getConfig().persistSessionMetadata) {
+            db.run('UPDATE sessions SET token = NULL, refreshToken = NULL, prevRefreshToken = NULL, prevTokenExpiresAt = NULL WHERE sessionId = ?', [sessionId]);
+        }
+        else {
+            db.run('DELETE FROM sessions WHERE sessionId = ?', [sessionId]);
+        }
+    }
+    const OAUTH_STATE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    const result = {
+        db,
+        adapter,
+        cleanupInterval: null,
+        atomicCreateSession(userId, token, sessionId, maxSessions, getConfig, metadata) {
+            const now = Date.now();
+            const ttlMs = getSessionTtlMs(getConfig);
+            const expiresAt = now + ttlMs;
+            db.transaction(() => {
+                const countRow = db
+                    .query('SELECT COUNT(*) AS count FROM sessions WHERE userId = ? AND token IS NOT NULL AND expiresAt > ?')
+                    .get(userId, now);
+                let activeCount = countRow?.count ?? 0;
+                while (activeCount >= maxSessions) {
+                    const oldest = db
+                        .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)
+                        break;
+                    if (getConfig().persistSessionMetadata) {
+                        db.run('UPDATE sessions SET token = NULL, refreshToken = NULL, prevRefreshToken = NULL, prevTokenExpiresAt = NULL WHERE sessionId = ?', [oldest.sessionId]);
+                    }
+                    else {
+                        db.run('DELETE FROM sessions WHERE sessionId = ?', [oldest.sessionId]);
+                    }
+                    activeCount--;
+                }
+                db.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,
+                ]);
+            })();
+        },
+        createSession(userId, token, sessionId, getConfig, metadata) {
+            const now = Date.now();
+            const expiresAt = now + getSessionTtlMs(getConfig);
+            db.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,
+            ]);
+        },
+        getSession(sessionId) {
+            const row = db
+                .query('SELECT token FROM sessions WHERE sessionId = ? AND expiresAt > ?')
+                .get(sessionId, Date.now());
+            if (!row || !row.token)
+                return null;
+            return row.token;
+        },
+        getSessionRecord(sessionId) {
+            const row = db
+                .query('SELECT token, lastActiveAt FROM sessions WHERE sessionId = ? AND expiresAt > ?')
+                .get(sessionId, Date.now());
+            if (!row || !row.token)
+                return null;
+            return { token: row.token, lastActiveAt: row.lastActiveAt };
+        },
+        deleteSession: deleteSessionImpl,
+        getUserSessions(userId, getConfig) {
+            const now = Date.now();
+            const rows = db
+                .query('SELECT sessionId, token, createdAt, lastActiveAt, expiresAt, ipAddress, userAgent FROM sessions WHERE userId = ? ORDER BY createdAt ASC')
+                .all(userId);
+            const cfg = getConfig();
+            const includeInactive = cfg.includeInactiveSessions;
+            const persist = cfg.persistSessionMetadata;
+            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;
+        },
+        getActiveSessionCount(userId) {
+            const row = db
+                .query('SELECT COUNT(*) AS count FROM sessions WHERE userId = ? AND token IS NOT NULL AND expiresAt > ?')
+                .get(userId, Date.now());
+            return row?.count ?? 0;
+        },
+        evictOldestSession(userId, getConfig) {
+            const now = Date.now();
+            const oldest = db
+                .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)
+                deleteSessionImpl(oldest.sessionId, getConfig);
+        },
+        updateSessionLastActive(sessionId) {
+            db.run('UPDATE sessions SET lastActiveAt = ? WHERE sessionId = ?', [Date.now(), sessionId]);
+        },
+        setRefreshToken(sessionId, refreshToken) {
+            const tokenHash = hashToken(refreshToken);
+            db.run('UPDATE sessions SET refreshToken = ? WHERE sessionId = ?', [tokenHash, sessionId]);
+        },
+        getSessionByRefreshToken(refreshToken, getConfig) {
+            const tokenHash = hashToken(refreshToken);
+            // Check current refresh token (stored as hash)
+            let row = db
+                .query('SELECT sessionId, userId, refreshToken FROM sessions WHERE refreshToken = ?')
+                .get(tokenHash);
+            if (row) {
+                return { sessionId: row.sessionId, userId: row.userId, newRefreshToken: refreshToken };
+            }
+            const graceRow = db
+                .query('SELECT sessionId, userId, refreshToken, refreshTokenPlain, prevTokenExpiresAt FROM sessions WHERE prevRefreshToken = ?')
+                .get(tokenHash);
+            if (!graceRow)
+                return null;
+            if (graceRow.prevTokenExpiresAt && graceRow.prevTokenExpiresAt > Date.now()) {
+                // Within grace window — return current plain refresh token so caller can re-issue it directly
+                return {
+                    sessionId: graceRow.sessionId,
+                    userId: graceRow.userId,
+                    newRefreshToken: graceRow.refreshTokenPlain ?? graceRow.refreshToken,
+                };
+            }
+            // Grace window expired — theft detected, invalidate session
+            deleteSessionImpl(graceRow.sessionId, getConfig);
+            return null;
+        },
+        rotateRefreshToken(sessionId, newRefreshToken, newAccessToken, getConfig) {
+            const graceSeconds = getConfig().refreshToken?.rotationGraceSeconds ?? 30;
+            const prevTokenExpiresAt = Date.now() + graceSeconds * 1000;
+            const newHash = hashToken(newRefreshToken);
+            db.run('UPDATE sessions SET prevRefreshToken = refreshToken, prevTokenExpiresAt = ?, refreshToken = ?, refreshTokenPlain = ?, token = ? WHERE sessionId = ?', [prevTokenExpiresAt, newHash, newRefreshToken, newAccessToken, sessionId]);
+        },
+        getSessionFingerprint(sessionId) {
+            const row = db
+                .query('SELECT fingerprint FROM sessions WHERE sessionId = ?')
+                .get(sessionId);
+            return row?.fingerprint ?? null;
+        },
+        setSessionFingerprint(sessionId, fingerprint) {
+            db.run('UPDATE sessions SET fingerprint = ? WHERE sessionId = ?', [fingerprint, sessionId]);
+        },
+        getMfaVerifiedAt(sessionId) {
+            const row = db
+                .query('SELECT mfaVerifiedAt FROM sessions WHERE sessionId = ?')
+                .get(sessionId);
+            return row?.mfaVerifiedAt ?? null;
+        },
+        setMfaVerifiedAt(sessionId, ts) {
+            db.run('UPDATE sessions SET mfaVerifiedAt = ? WHERE sessionId = ?', [ts, sessionId]);
+        },
+        storeOAuthState(state, codeVerifier, linkUserId) {
+            const expiresAt = Date.now() + OAUTH_STATE_TTL_MS;
+            db.run('INSERT INTO oauth_states (state, codeVerifier, linkUserId, expiresAt) VALUES (?, ?, ?, ?)', [state, codeVerifier ?? null, linkUserId ?? null, expiresAt]);
+        },
+        consumeOAuthState(state) {
+            const row = db
+                .query('DELETE FROM oauth_states WHERE state = ? AND expiresAt > ? RETURNING codeVerifier, linkUserId')
+                .get(state, Date.now());
+            if (!row)
+                return null;
+            return {
+                codeVerifier: row.codeVerifier ?? undefined,
+                linkUserId: row.linkUserId ?? undefined,
+            };
+        },
+        getCache(key) {
+            const row = db
+                .query('SELECT value FROM cache_entries WHERE key = ? AND (expiresAt IS NULL OR expiresAt > ?)')
+                .get(key, Date.now());
+            return row?.value ?? null;
+        },
+        setCache(key, value, ttlSeconds) {
+            const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1000 : null;
+            db.run('INSERT INTO cache_entries (key, value, expiresAt) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expiresAt = excluded.expiresAt', [key, value, expiresAt]);
+        },
+        delCache(key) {
+            db.run('DELETE FROM cache_entries WHERE key = ?', [key]);
+        },
+        delCachePattern(pattern) {
+            // Convert glob pattern (* wildcard) to a SQL LIKE pattern (% wildcard)
+            const likePattern = pattern.replace(/%/g, '\\%').replace(/_/g, '\\_').replace(/\*/g, '%');
+            db.run("DELETE FROM cache_entries WHERE key LIKE ? ESCAPE '\\'", [likePattern]);
+        },
+        createVerificationToken(token, userId, email, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO email_verifications (token, userId, email, expiresAt) VALUES (?, ?, ?, ?)', [token, userId, email, expiresAt]);
+        },
+        getVerificationToken(token) {
+            const row = db
+                .query('SELECT userId, email FROM email_verifications WHERE token = ? AND expiresAt > ?')
+                .get(token, Date.now());
+            return row ?? null;
+        },
+        deleteVerificationToken(token) {
+            db.run('DELETE FROM email_verifications WHERE token = ?', [token]);
+        },
+        consumeVerificationToken(token) {
+            const row = db
+                .query('DELETE FROM email_verifications WHERE token = ? AND expiresAt > ? RETURNING userId, email')
+                .get(token, Date.now());
+            return row ?? null;
+        },
+        createResetToken(token, userId, email, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO password_resets (token, userId, email, expiresAt) VALUES (?, ?, ?, ?)', [
+                token,
+                userId,
+                email,
+                expiresAt,
+            ]);
+        },
+        consumeResetToken(hash) {
+            const row = db
+                .query('DELETE FROM password_resets WHERE token = ? AND expiresAt > ? RETURNING userId, email')
+                .get(hash, Date.now());
+            return row ?? null;
+        },
+        createDeletionCancelToken(token, userId, jobId, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO deletion_cancel_tokens (token, userId, jobId, expiresAt) VALUES (?, ?, ?, ?)', [token, userId, jobId, expiresAt]);
+        },
+        consumeDeletionCancelToken(hash) {
+            const row = db
+                .query('DELETE FROM deletion_cancel_tokens WHERE token = ? AND expiresAt > ? RETURNING userId, jobId')
+                .get(hash, Date.now());
+            return row ?? null;
+        },
+        storeOAuthCode(hash, payload, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO oauth_codes (codeHash, token, userId, email, refreshToken, expiresAt) VALUES (?, ?, ?, ?, ?, ?)', [
+                hash,
+                payload.token,
+                payload.userId,
+                payload.email ?? null,
+                payload.refreshToken ?? null,
+                expiresAt,
+            ]);
+        },
+        consumeOAuthCode(hash) {
+            const row = db
+                .query('DELETE FROM oauth_codes WHERE codeHash = ? AND expiresAt > ? RETURNING token, userId, email, refreshToken')
+                .get(hash, Date.now());
+            if (!row)
+                return null;
+            return {
+                token: row.token,
+                userId: row.userId,
+                email: row.email ?? undefined,
+                refreshToken: row.refreshToken ?? undefined,
+            };
+        },
+        storeOAuthReauth(hash, data, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO oauth_reauth_states (tokenHash, userId, sessionId, provider, purpose, returnUrl, expiresAt) VALUES (?, ?, ?, ?, ?, ?, ?)', [
+                hash,
+                data.userId,
+                data.sessionId,
+                data.provider,
+                data.purpose,
+                data.returnUrl ?? null,
+                expiresAt,
+            ]);
+        },
+        consumeOAuthReauth(hash) {
+            const row = db
+                .query('DELETE FROM oauth_reauth_states WHERE tokenHash = ? AND expiresAt > ? RETURNING userId, sessionId, provider, purpose, returnUrl, expiresAt')
+                .get(hash, Date.now());
+            if (!row)
+                return null;
+            return {
+                userId: row.userId,
+                sessionId: row.sessionId,
+                provider: row.provider,
+                purpose: row.purpose,
+                expiresAt: row.expiresAt,
+                returnUrl: row.returnUrl ?? undefined,
+            };
+        },
+        storeOAuthReauthConfirmation(hash, data, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO oauth_reauth_confirmations (codeHash, userId, purpose, expiresAt) VALUES (?, ?, ?, ?)', [hash, data.userId, data.purpose, expiresAt]);
+        },
+        consumeOAuthReauthConfirmation(hash) {
+            const row = db
+                .query('DELETE FROM oauth_reauth_confirmations WHERE codeHash = ? AND expiresAt > ? RETURNING userId, purpose')
+                .get(hash, Date.now());
+            if (!row)
+                return null;
+            return { userId: row.userId, purpose: row.purpose };
+        },
+        registerUpload(record) {
+            db.run(`INSERT OR REPLACE INTO upload_registry (key, ownerUserId, tenantId, mimeType, bucket, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?)`, [
+                record.key,
+                record.ownerUserId ?? null,
+                record.tenantId ?? null,
+                record.mimeType ?? null,
+                record.bucket ?? null,
+                record.createdAt,
+            ]);
+        },
+        getUploadRecord(key) {
+            const row = db
+                .query('SELECT key, ownerUserId, tenantId, mimeType, bucket, createdAt FROM upload_registry WHERE key = ?')
+                .get(key);
+            if (!row)
+                return null;
+            return {
+                key: row.key,
+                ...(row.ownerUserId !== null ? { ownerUserId: row.ownerUserId } : {}),
+                ...(row.tenantId !== null ? { tenantId: row.tenantId } : {}),
+                ...(row.mimeType !== null ? { mimeType: row.mimeType } : {}),
+                ...(row.bucket !== null ? { bucket: row.bucket } : {}),
+                createdAt: row.createdAt,
+            };
+        },
+        deleteUploadRecord(key) {
+            const r = db.run('DELETE FROM upload_registry WHERE key = ?', [key]);
+            return r.changes > 0;
+        },
+        createMagicLinkToken(token, userId, ttlSeconds) {
+            const expiresAt = Date.now() + ttlSeconds * 1000;
+            db.run('INSERT INTO magic_link_tokens (token, userId, expiresAt) VALUES (?, ?, ?)', [
+                token,
+                userId,
+                expiresAt,
+            ]);
+        },
+        consumeMagicLinkToken(hash) {
+            const row = db
+                .query('DELETE FROM magic_link_tokens WHERE token = ? AND expiresAt > ? RETURNING userId')
+                .get(hash, Date.now());
+            return row?.userId ?? null;
+        },
+        startCleanup(getConfig, intervalMs = 3_600_000) {
+            // Clear any existing interval to prevent duplicates
+            if (_cleanupInterval !== null) {
+                clearInterval(_cleanupInterval);
+            }
+            runCleanup(getConfig);
+            const handle = setInterval(() => {
+                runCleanup(getConfig);
+            }, intervalMs);
+            _cleanupInterval = handle;
+            result.cleanupInterval = handle;
+            return handle;
+        },
+        stopCleanup() {
+            if (_cleanupInterval !== null) {
+                clearInterval(_cleanupInterval);
+                _cleanupInterval = null;
+                result.cleanupInterval = null;
+            }
+        },
+    };
+    return result;
+}