mbkauthe 5.1.1 → 5.2.1

package/README.md

@@ -10,14 +10,14 @@
   <img height="64px" src="./public/logo.png" alt="MBKAuthe" />
 </p>
 
-**MBKAuthe** is an open source authentication package for Node.js, Express, and PostgreSQL. It handles login, session validation, role/app access checks, optional TOTP 2FA, OAuth login, API token authentication, and multi-session management.
+**MBKAuthe** is an open source authentication package for Node.js and Express, backed by PostgreSQL or SQLite. It handles login, session validation, role/app access checks, optional TOTP 2FA, OAuth login, API token authentication, and multi-session management.
 
 > **Note:** MBKAuthe is intentionally focused on authentication and session validation. The broader user, permission, and dashboard management system is a separate MBKTech product named **MBKCore**(closed source for now).
 
 ## Features
 
 - Express middleware for session validation and role checks
-- PostgreSQL-backed user, session, 2FA, trusted-device, and API-token storage
+- PostgreSQL or SQLite storage for users, sessions, 2FA, trusted devices, and API tokens
 - Secure password authentication with PBKDF2
 - Optional TOTP 2FA with trusted devices
 - GitHub App and Google OAuth login flows
@@ -46,17 +46,24 @@ Copy-Item .env.example .env
 
 See the [configuration guide](docs/guides/configuration.md) for `mbkautheVar`, `mbkauthShared`, OAuth settings, session settings, and deployment flags.
 
-3. Create database tables.
+3. Choose a database backend.
 
-Run [docs/schema/db.sql](docs/schema/db.sql) against PostgreSQL, or use the package script:
+MBKAuthe supports two backends, selected with `DB_TYPE` in `mbkautheVar`:
+
+- **PostgreSQL** (default) - set `LOGIN_DB` to a connection string. Recommended for production and multi-instance deployments.
+- **SQLite** - set `DB_TYPE` to `sqlite` and `SQLITE_PATH` to a file path (created if missing). No database server required - convenient for development, tests, and small single-instance deployments. Uses `better-sqlite3` with WAL mode; expect `-wal`/`-shm` side files next to the database file. See the [SQLite backend notes](docs/guides/database.md#sqlite-backend-notes) in the database guide.
+
+4. Create database tables.
 
 ```bash
 npm run create-tables
 ```
 
+The script applies [docs/schema/db.sql](docs/schema/db.sql) (PostgreSQL) or [docs/schema/db.sqlite.sql](docs/schema/db.sqlite.sql) (SQLite) to the configured backend. You can also run the matching SQL file yourself.
+
 The schema includes a default SuperAdmin user (`support` / `12345678`). Change that password immediately. See the [database guide](docs/guides/database.md).
 
-4. Mount MBKAuthe in Express.
+5. Mount MBKAuthe in Express.
 
 ```javascript
 import express from "express";
@@ -93,7 +100,8 @@ app.listen(3000);
 - `strictValidateSession` - require cookie session authentication only.
 - `strictValidateSessionAndRole` - strict cookie session plus role check.
 - `authenticate(token)` - protect server-to-server routes with a static bearer token.
-- `dblogin` - access the configured PostgreSQL pool.
+- `dblogin` - access the configured database pool (`pg.Pool` or the SQLite adapter, per `DB_TYPE`).
+- `dbType` - the active backend: `"postgres"` or `"sqlite"`.
 
 See the [API reference](docs/reference/api.md) for endpoints, middleware, examples, security notes, and rate limits.
 
@@ -149,6 +157,7 @@ Development-only diagnostics are mounted when `process.env.env === "dev"`:
 - Set an appropriate `COOKIE_EXPIRE_TIME`
 - Store secrets in environment variables
 - Configure OAuth credentials only when the matching provider is enabled
+- If using the SQLite backend, put `SQLITE_PATH` on persistent disk (not ephemeral/serverless storage) and back up the database together with its `-wal`/`-shm` side files
 
 Vercel deployments can use shared OAuth credentials through `mbkauthShared`.
 

package/docs/README.md

@@ -27,7 +27,8 @@ This directory is organized by how the documentation is used:
 
 ## Assets
 
-- [Database schema SQL](schema/db.sql)
+- [Database schema SQL - PostgreSQL](schema/db.sql)
+- [Database schema SQL - SQLite](schema/db.sqlite.sql)
 - [Authentication flow Mermaid source](diagrams/auth-flows.mmd)
 - [Authentication process Mermaid source](diagrams/auth-processes.mmd)
 - [Rendered diagram images](images/)

package/docs/guides/configuration.md

@@ -39,12 +39,25 @@ This document describes the environment variables MBKAuth expects and keeps brie
   - Example: `"DOMAIN":"localhost"`
   - Required: Yes
 
+- DB_TYPE
+  - Description: Which database backend to use.
+  - Values: `postgres` (default) / `sqlite`
+  - Example: `"DB_TYPE":"sqlite"`
+  - Required: No (defaults to `postgres`)
+
 - LOGIN_DB
   - Description: PostgreSQL connection string for auth (must start with `postgresql://` or `postgres://`).
   - Example: `"LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth"`
-  - Required: Yes
+  - Required: Yes, when `DB_TYPE` is `postgres` (the default)
   - Create free postgres db: https://neon.com/
 
+- SQLITE_PATH
+  - Description: Path to the SQLite database file (created if missing). Uses `better-sqlite3` under the hood.
+  - Example: `"SQLITE_PATH":"./data/mbkauthe.sqlite"`
+  - Required: Yes, when `DB_TYPE` is `sqlite`
+  - Default: `./mbkauthe.sqlite`
+  - Run `npm run create-tables` after setting this to create the schema (loads `docs/schema/db.sqlite.sql` instead of the Postgres `db.sql`).
+
 - MBKAUTH_TWO_FA_ENABLE
   - Description: Enable Two-Factor Authentication.
   - Values: `true` / `false` / `f`
@@ -123,6 +136,14 @@ Production (short):
 mbkautheVar={"APP_NAME":"mbkauthe","Main_SECRET_TOKEN":"prod-token","SESSION_SECRET_KEY":"prod-secret","IS_DEPLOYED":"true","DOMAIN":"yourdomain.com","LOGIN_DB":"postgresql://dbuser:secure@db:5432/mbkauth_prod","MBKAUTH_TWO_FA_ENABLE":"true"}
 ```
 
+SQLite (no external database required):
+
+```env
+mbkautheVar={"APP_NAME":"mbkauthe","Main_SECRET_TOKEN":"dev-token","SESSION_SECRET_KEY":"dev-secret","IS_DEPLOYED":"false","DOMAIN":"localhost","DB_TYPE":"sqlite","SQLITE_PATH":"./data/mbkauthe.sqlite","MBKAUTH_TWO_FA_ENABLE":"false"}
+```
+
+Then run `npm run create-tables` to create `./data/mbkauthe.sqlite` with the schema in `docs/schema/db.sqlite.sql`.
+
 ---
 
 ## Rules & best practices

package/docs/guides/database.md

@@ -2,7 +2,7 @@
 
 [Back to docs index](../README.md) | [Back to project README](../../README.md)
 
-**Executable DDL lives only in [`docs/schema/db.sql`](../schema/db.sql).** This file explains what that script creates and how the app uses it. Run the script against Postgres when bootstrapping or aligning a database (for example `psql $DATABASE_URL -f docs/schema/db.sql`). The app can also apply it via `lib/createTable.js`, which reads `docs/schema/db.sql`.
+**Executable DDL lives only in [`docs/schema/db.sql`](../schema/db.sql) (Postgres) and [`docs/schema/db.sqlite.sql`](../schema/db.sqlite.sql) (SQLite).** This file explains what those scripts create and how the app uses them. Run the Postgres script when bootstrapping or aligning a database (for example `psql $DATABASE_URL -f docs/schema/db.sql`). The app can also apply the right script for the configured backend via `lib/createTable.js`.
 
 ---
 
@@ -91,3 +91,34 @@ const encryptedPassword = hashPassword("your-password", "newusername");
 ```
 
 Replace usernames, roles (`SuperAdmin`, `NormalUser`, `Guest`, `member`), and flags (`Active`, `HaveMailAccount`) to match your needs.
+
+---
+
+## SQLite backend notes
+
+When `DB_TYPE` is `sqlite` (see the [configuration guide](configuration.md)), the app uses one `better-sqlite3` connection wrapped by `lib/db/sqlitePool.js`. The schema comes from [`docs/schema/db.sqlite.sql`](../schema/db.sqlite.sql) instead of `db.sql`.
+
+- The database runs in WAL journal mode with foreign keys enabled. Expect `-wal` and `-shm` side files next to the database file; do not delete them while the app is running, and include them when copying a live database (or checkpoint first with `PRAGMA wal_checkpoint(TRUNCATE)`).
+- Concurrent requests are safe: an internal FIFO mutex serializes statements so a plain query can never run inside another request's open transaction.
+
+### Warning: inside a transaction, only use `txRepo`
+
+The mutex is not re-entrant. `pool.query()` waits for the mutex, and an open transaction holds it — so a `pool.query()` call from inside a `withTransaction` callback waits on the transaction it is part of and **deadlocks the request** (it hangs with no error). This includes indirect calls through a repository bound to the pool.
+
+```javascript
+await authRepo.withTransaction(async (txRepo) => {
+  // Correct: txRepo wraps the client that holds the lock.
+  await txRepo.insertAppSession(username, expiresAt, meta);
+
+  // WRONG - deadlocks: authRepo is bound to the pool, which
+  // waits for the lock this transaction is holding.
+  // await authRepo.getUserProfileByUsername(username);
+
+  // WRONG for the same reason:
+  // await pool.query('SELECT 1');
+});
+```
+
+Rule of thumb: inside the `withTransaction` callback, only touch the `txRepo` parameter — never `authRepo`, the pool, or anything else that reaches the pool. Queries against the pool are fine again once the callback returns.
+
+(The Postgres backend has the same rule with a different failure mode: a `pool.query()` inside a transaction runs on a different pooled connection, silently outside the transaction.)

package/docs/reference/api/authentication.md

@@ -98,7 +98,7 @@ When a user logs in, MBKAuthe creates a session and sets the following cookies:
 ### Session Lifetime
 
 - Default: 2 days (configurable via `COOKIE_EXPIRE_TIME`)
-- Application sessions are stored in the `Sessions` table in PostgreSQL
+- Application sessions are stored in the `Sessions` table in the configured database (PostgreSQL or SQLite, per `DB_TYPE`)
 - Sessions persist across subdomains in production
 
 ---

package/docs/schema/db.sqlite.sql

@@ -0,0 +1,155 @@
+-- SQLite schema for mbkauthe.
+--
+-- This mirrors the auth-relevant subset of docs/schema/db.sql (Postgres).
+-- Tables belonging to the wider MBKTech platform rather than mbkauthe
+-- itself (todos, notifications, categories, etc.) are intentionally not
+-- included here — add those separately in your own app schema if needed.
+--
+-- Notes on the Postgres -> SQLite translation:
+--   * "integer GENERATED ... AS IDENTITY"   -> INTEGER PRIMARY KEY AUTOINCREMENT
+--   * "boolean"                             -> INTEGER (0/1)
+--   * "jsonb"/"json"                        -> TEXT (store JSON as text)
+--   * "timestamp with time zone"            -> TEXT (CURRENT_TIMESTAMP format)
+--   * "uuid DEFAULT gen_random_uuid()"      -> TEXT DEFAULT (uuid v4 expression)
+--   * GIN indexes / COMMENT ON TABLE        -> omitted (no SQLite equivalent)
+
+PRAGMA foreign_keys = ON;
+
+-- Table: Users
+CREATE TABLE IF NOT EXISTS "Users" (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    "UserName" TEXT UNIQUE,
+    "Password" TEXT DEFAULT '12345670',
+    "Active" INTEGER DEFAULT 0,
+    "Role" TEXT DEFAULT 'NormalUser',
+    "HaveMailAccount" INTEGER DEFAULT 0,
+    "AllowedApps" TEXT DEFAULT '["Portal", "mbkauthe"]',
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    last_login TEXT,
+    "PasswordEnc" TEXT,
+    "FullName" TEXT,
+    "UserId" TEXT UNIQUE CHECK ("UserId" IS NULL OR length("UserId") = 9),
+    email TEXT DEFAULT 'support@mbktech.org',
+    "Image" TEXT DEFAULT 'https://portal.mbktech.org/icon.svg',
+    "Bio" TEXT DEFAULT 'I am ....',
+    "SocialAccounts" TEXT DEFAULT '{}',
+    "Positions" TEXT DEFAULT '{"Not_Permanent": "Member Is Not Permanent"}'
+);
+CREATE INDEX IF NOT EXISTS idx_users_active ON "Users" ("Active");
+CREATE INDEX IF NOT EXISTS idx_users_email ON "Users" (email);
+CREATE INDEX IF NOT EXISTS idx_users_last_login ON "Users" (last_login);
+CREATE INDEX IF NOT EXISTS idx_users_role ON "Users" ("Role");
+CREATE INDEX IF NOT EXISTS idx_users_username ON "Users" ("UserName");
+CREATE INDEX IF NOT EXISTS idx_users_userid ON "Users" ("UserId");
+
+-- Table: ApiTokens
+CREATE TABLE IF NOT EXISTS "ApiTokens" (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    "UserName" TEXT NOT NULL REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    "Name" TEXT NOT NULL CHECK (length(trim("Name")) > 0),
+    "TokenHash" TEXT NOT NULL UNIQUE,
+    "Prefix" TEXT NOT NULL,
+    "Permissions" TEXT DEFAULT '{"scope": "read-only", "allowedApps": null}' NOT NULL,
+    "LastUsed" TEXT,
+    "CreatedAt" TEXT DEFAULT CURRENT_TIMESTAMP,
+    "ExpiresAt" TEXT,
+    CHECK ("ExpiresAt" IS NULL OR "ExpiresAt" > "CreatedAt")
+);
+CREATE INDEX IF NOT EXISTS idx_apitokens_expires ON "ApiTokens" ("ExpiresAt") WHERE "ExpiresAt" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_apitokens_username_created ON "ApiTokens" ("UserName", "CreatedAt" DESC);
+
+-- Table: PasswordResets
+CREATE TABLE IF NOT EXISTS "PasswordResets" (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    "UserName" TEXT NOT NULL REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    "resetToken" TEXT,
+    "resetTokenExpires" TEXT,
+    "resetAttempts" INTEGER DEFAULT 0,
+    "lastResetAttempt" TEXT,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_password_resets_token ON "PasswordResets" ("resetToken");
+
+-- Table: Sessions (mbkauthe's own app-session table — distinct from the
+-- express-session store table below, which is just "session")
+CREATE TABLE IF NOT EXISTS "Sessions" (
+    id TEXT PRIMARY KEY DEFAULT (
+        lower(hex(randomblob(4))) || '-' || lower(hex(randomblob(2))) || '-4' ||
+        substr(lower(hex(randomblob(2))), 2) || '-' ||
+        substr('89ab', (abs(random()) % 4) + 1, 1) || substr(lower(hex(randomblob(2))), 2) || '-' ||
+        lower(hex(randomblob(6)))
+    ),
+    "UserName" TEXT NOT NULL REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    expires_at TEXT,
+    meta TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_expires ON "Sessions" (expires_at) WHERE expires_at IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_sessions_user_created ON "Sessions" ("UserName", created_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_username_expires ON "Sessions" ("UserName", expires_at);
+
+-- Table: TrustedDevices
+CREATE TABLE IF NOT EXISTS "TrustedDevices" (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    "UserName" TEXT NOT NULL REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    "DeviceToken" TEXT NOT NULL UNIQUE,
+    "DeviceName" TEXT,
+    "UserAgent" TEXT,
+    "IpAddress" TEXT,
+    "CreatedAt" TEXT DEFAULT CURRENT_TIMESTAMP,
+    "ExpiresAt" TEXT NOT NULL,
+    "LastUsed" TEXT DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_trusted_devices_expires ON "TrustedDevices" ("ExpiresAt");
+CREATE INDEX IF NOT EXISTS idx_trusted_devices_username_expires ON "TrustedDevices" ("UserName", "ExpiresAt");
+CREATE INDEX IF NOT EXISTS idx_trusted_devices_token_user_expires ON "TrustedDevices" ("DeviceToken", "UserName", "ExpiresAt");
+
+-- Table: TwoFA
+CREATE TABLE IF NOT EXISTS "TwoFA" (
+    "UserName" TEXT NOT NULL PRIMARY KEY REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    "TwoFAStatus" INTEGER DEFAULT 0 NOT NULL,
+    "TwoFASecret" TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_twofa_username_status ON "TwoFA" ("UserName", "TwoFAStatus");
+
+-- Table: session (express-session store; see lib/session/SqliteSessionStore.js)
+CREATE TABLE IF NOT EXISTS "session" (
+    sid TEXT PRIMARY KEY,
+    sess TEXT NOT NULL,
+    expire TEXT NOT NULL,
+    username TEXT REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    last_activity TEXT DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_session_expire ON "session" (expire);
+
+-- Table: user_github
+CREATE TABLE IF NOT EXISTS user_github (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_name TEXT REFERENCES "Users"("UserName") ON DELETE CASCADE,
+    github_id TEXT UNIQUE,
+    github_username TEXT,
+    access_token TEXT,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    installation_id INTEGER,
+    installation_target_type TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_user_github_user_name ON user_github (user_name);
+
+-- Table: user_google
+CREATE TABLE IF NOT EXISTS user_google (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_name TEXT REFERENCES "Users"("UserName"),
+    google_id TEXT UNIQUE,
+    google_email TEXT,
+    access_token TEXT,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Seed user (hash-only). Default password is "12345678" for this sample account.
+-- Hash was generated using mbkauthe's "hashPassword(password, username)" function.
+INSERT INTO "Users" ("UserName", "PasswordEnc", "Role", "Active", "HaveMailAccount", "FullName")
+VALUES ('support', 'b8b10c1c9006d8c30ab81c412463c65ff6dae3293d9bfbaf5fd8e275081d0947f000a828004e2fbd3a8f6ef5a35ae3eddd4c57b00ecab376b12e607a16a57459', 'SuperAdmin', 1, 0, 'Support User')
+ON CONFLICT("UserName") DO NOTHING;

package/index.d.ts

@@ -50,7 +50,12 @@ declare module 'mbkauthe' {
     Main_SECRET_TOKEN: string;
     IS_DEPLOYED: 'true' | 'false' | 'f';
     DOMAIN: string;
-    LOGIN_DB: string;
+    /** Defaults to 'postgres'. Set to 'sqlite' to use the SQLite backend instead. */
+    DB_TYPE?: 'postgres' | 'sqlite';
+    /** Required when DB_TYPE is 'postgres' (default). */
+    LOGIN_DB?: string;
+    /** Required when DB_TYPE is 'sqlite'. Path to the SQLite database file. */
+    SQLITE_PATH?: string;
     MBKAUTH_TWO_FA_ENABLE: 'true' | 'false' | 'f';
     COOKIE_EXPIRE_TIME?: number;
     DEVICE_TRUST_DURATION_DAYS?: number;
@@ -339,7 +344,26 @@ declare module 'mbkauthe' {
   export function getLatestVersion(): Promise<string>;
 
   // Exports
-  export const dblogin: Pool;
+  /** A `pg.Pool` when DB_TYPE is 'postgres' (default), or a SqlitePool-shaped adapter when DB_TYPE is 'sqlite'. */
+  export const dblogin: Pool | {
+    query(text: string | { text: string; values?: any[]; name?: string }, values?: any[]): Promise<{ rows: any[]; rowCount: number }>;
+    connect(): Promise<{ query: Function; release: () => void }>;
+    end(): Promise<void>;
+  };
+  export const dbType: 'postgres' | 'sqlite';
+  /** SQL dialect helpers for the active backend (see lib/db/dialects/). */
+  export const dialect: {
+    name: 'postgres' | 'sqlite';
+    quoteIdentifier(name: string): string;
+    param(index: number): string;
+    now(): string;
+    boolean(value: any): string;
+    supportsReturning: boolean;
+    returningClause(columns: string): string;
+    limitOffset(options?: { limit?: number; offset?: number }): string;
+    /** `null` on SQLite, which has no table-level lock statement. */
+    lockTable: ((tableSql: string, mode?: string) => string) | null;
+  };
   export const mbkautheVar: MBKAuthConfig;
   export const cachedCookieOptions: ReturnType<typeof getCookieOptions>;
   export const cachedClearCookieOptions: ReturnType<typeof getClearCookieOptions>;

package/index.js

@@ -94,7 +94,7 @@ export * from "./lib/middleware/auth.js";
 export * from "./lib/middleware/index.js";
 export { validateTokenScope } from "./lib/middleware/scopeValidator.js";
 export * from "#response.js";
-export { dblogin } from "#pool.js";
+export { dblogin, dbType, dialect } from "#pool.js";
 export { getLatestVersion } from "./lib/routes/misc.js";
 export * from "./lib/routes/auth.js";
 export * from "./lib/utils/errors.js";

package/lib/config/index.js

@@ -7,7 +7,7 @@ const logConfig = createLogger("config");
 
 const CONFIG_KEYS = [
     "APP_NAME", "DEVICE_TRUST_DURATION_DAYS", "Main_SECRET_TOKEN", "SESSION_SECRET_KEY",
-    "IS_DEPLOYED", "LOGIN_DB", "MBKAUTH_TWO_FA_ENABLE", "COOKIE_EXPIRE_TIME", "DOMAIN", "loginRedirectURL",
+    "IS_DEPLOYED", "DB_TYPE", "LOGIN_DB", "SQLITE_PATH", "MBKAUTH_TWO_FA_ENABLE", "COOKIE_EXPIRE_TIME", "DOMAIN", "loginRedirectURL",
     "GITHUB_LOGIN_ENABLED", "GITHUB_APP_CLIENT_ID", "GITHUB_APP_CLIENT_SECRET", "GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET", "GOOGLE_LOGIN_ENABLED", "GOOGLE_CLIENT_ID",
     "GOOGLE_CLIENT_SECRET", "MAX_SESSIONS_PER_USER"
 ];
@@ -15,6 +15,8 @@ const CONFIG_KEYS = [
 const DEFAULT_CONFIG = {
     DEVICE_TRUST_DURATION_DAYS: 7,
     IS_DEPLOYED: 'false',
+    DB_TYPE: 'postgres',
+    SQLITE_PATH: './mbkauthe.sqlite',
     MBKAUTH_TWO_FA_ENABLE: 'false',
     COOKIE_EXPIRE_TIME: 2,
     loginRedirectURL: '/dashboard',
@@ -25,11 +27,13 @@ const DEFAULT_CONFIG = {
 
 const BOOLEAN_KEYS = ['GITHUB_LOGIN_ENABLED', 'GOOGLE_LOGIN_ENABLED', 'MBKAUTH_TWO_FA_ENABLE', 'IS_DEPLOYED'];
 const STRING_KEYS = [
-    "APP_NAME", "Main_SECRET_TOKEN", "SESSION_SECRET_KEY", "LOGIN_DB", "DOMAIN", "loginRedirectURL",
+    "APP_NAME", "Main_SECRET_TOKEN", "SESSION_SECRET_KEY", "DB_TYPE", "LOGIN_DB", "SQLITE_PATH", "DOMAIN", "loginRedirectURL",
     "GITHUB_APP_CLIENT_ID", "GITHUB_APP_CLIENT_SECRET", "GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET",
     "GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"
 ];
-const REQUIRED_KEYS = ["APP_NAME", "Main_SECRET_TOKEN", "SESSION_SECRET_KEY", "IS_DEPLOYED", "LOGIN_DB",
+// LOGIN_DB is required for postgres but not for sqlite (SQLITE_PATH is used instead);
+// enforced conditionally inside validateConfiguration below.
+const REQUIRED_KEYS = ["APP_NAME", "Main_SECRET_TOKEN", "SESSION_SECRET_KEY", "IS_DEPLOYED",
     "MBKAUTH_TWO_FA_ENABLE", "DOMAIN"];
 
 const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -137,6 +141,13 @@ function normalizeAndValidateConfig(config, errors) {
         config.APP_NAME = config.APP_NAME.toLowerCase();
     }
 
+    if (hasValue(config.DB_TYPE)) {
+        config.DB_TYPE = config.DB_TYPE.toLowerCase();
+        if (!["postgres", "sqlite"].includes(config.DB_TYPE)) {
+            errors.push("mbkautheVar.DB_TYPE must be either 'postgres' or 'sqlite'");
+        }
+    }
+
     if (hasValue(config.DOMAIN)) {
         const domain = config.DOMAIN.toLowerCase().replace(/^\.+/, '');
         config.DOMAIN = domain;
@@ -203,9 +214,17 @@ function validateConfiguration() {
         }
     }
 
-    // Validate LOGIN_DB connection string format
-    if (mbkautheVar.LOGIN_DB && !mbkautheVar.LOGIN_DB.startsWith('postgresql://') && !mbkautheVar.LOGIN_DB.startsWith('postgres://')) {
-        errors.push("mbkautheVar.LOGIN_DB must be a valid PostgreSQL connection string");
+    // Validate the DB connection setting for the selected DB_TYPE
+    if (mbkautheVar.DB_TYPE === "sqlite") {
+        if (isBlank(mbkautheVar.SQLITE_PATH)) {
+            errors.push("mbkautheVar.SQLITE_PATH is required and cannot be empty when DB_TYPE is 'sqlite'");
+        }
+    } else {
+        if (isBlank(mbkautheVar.LOGIN_DB)) {
+            errors.push("mbkautheVar.LOGIN_DB is required and cannot be empty when DB_TYPE is 'postgres'");
+        } else if (!mbkautheVar.LOGIN_DB.startsWith('postgresql://') && !mbkautheVar.LOGIN_DB.startsWith('postgres://')) {
+            errors.push("mbkautheVar.LOGIN_DB must be a valid PostgreSQL connection string");
+        }
     }
 
     // If there are validation errors, throw them all at once

package/lib/createTable.js

@@ -1,4 +1,4 @@
-import { dblogin } from "./pool.js";
+import { dblogin, dbType } from "./pool.js";
 import { readFile } from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -11,8 +11,10 @@ async function main() {
   const startTime = performance.now();
 
   console.log("[mbkauthe] Starting schema creation...");
+  console.log(`[mbkauthe] Database type: ${dbType}`);
 
-  const schemaPath = path.resolve(__dirname, "../docs/schema/db.sql");
+  const schemaFile = dbType === "sqlite" ? "db.sqlite.sql" : "db.sql";
+  const schemaPath = path.resolve(__dirname, "../docs/schema", schemaFile);
 
   console.log(`[mbkauthe] Schema file: ${schemaPath}`);
 
@@ -31,6 +33,28 @@ async function main() {
     `[mbkauthe] Detected approximately ${statementCount} SQL statements`
   );
 
+  if (dbType === "sqlite") {
+    try {
+      console.log("[mbkauthe] Applying SQLite schema...");
+      const queryStart = performance.now();
+
+      dblogin.execScript(schemaSql);
+
+      const queryDuration = (performance.now() - queryStart).toFixed(2);
+      console.log(`[mbkauthe] Schema applied successfully in ${queryDuration} ms`);
+    } catch (err) {
+      console.error("[mbkauthe] Failed to apply schema");
+      console.error("Message:", err.message);
+      process.exitCode = 1;
+    } finally {
+      console.log("[mbkauthe] Closing database connection...");
+      await dblogin.end();
+      const totalDuration = (performance.now() - startTime).toFixed(2);
+      console.log(`[mbkauthe] Finished in ${totalDuration} ms`);
+    }
+    return;
+  }
+
   try {
     console.log("[mbkauthe] Testing database connection...");
 

package/lib/db/AuthRepository.js

@@ -76,6 +76,38 @@ export class AuthRepository extends BaseRepository {
   }
 
   async touchTrustedDevice(deviceTokenHash, username) {
+    // SQLite's RETURNING clause can only reference columns of the table
+    // being updated, not columns joined in via FROM — so do the UPDATE and
+    // the follow-up SELECT as two statements for that dialect.
+    if (this.dialect.name === "sqlite") {
+      const updated = await this.executeRaw({
+        name: "check-trusted-device-update",
+        text: `
+          UPDATE "TrustedDevices"
+          SET "LastUsed" = CURRENT_TIMESTAMP
+          WHERE "DeviceToken" = $1
+            AND "UserName" = $2
+            AND "ExpiresAt" > CURRENT_TIMESTAMP
+          RETURNING "UserName", "ExpiresAt"
+        `,
+        values: [deviceTokenHash, username]
+      });
+
+      const row = updated.rows?.[0];
+      if (!row) return null;
+
+      const userResult = await this.executeRaw({
+        name: "check-trusted-device-user",
+        text: `SELECT "UserId", "Active", "Role", "AllowedApps" FROM "Users" WHERE "UserName" = $1 AND "Active" = TRUE`,
+        values: [row.UserName]
+      });
+
+      const userRow = userResult.rows?.[0];
+      if (!userRow) return null;
+
+      return { ...row, ...userRow };
+    }
+
     const query = `
       UPDATE "TrustedDevices" td
       SET "LastUsed" = NOW()
@@ -97,6 +129,22 @@ export class AuthRepository extends BaseRepository {
   }
 
   async cleanupAndCountUserSessions(username, queryName = "cleanup-and-count-user-sessions") {
+    // SQLite has no writable CTEs (WITH ... AS (DELETE ...) SELECT), so split
+    // this into two statements for that dialect instead.
+    if (this.dialect.name === "sqlite") {
+      await this.executeRaw({
+        name: `${queryName}-delete`,
+        text: `DELETE FROM "Sessions" WHERE "UserName" = $1 AND expires_at IS NOT NULL AND expires_at <= NOW()`,
+        values: [username]
+      });
+      const result = await this.executeRaw({
+        name: `${queryName}-count`,
+        text: `SELECT COUNT(*) AS count FROM "Sessions" WHERE "UserName" = $1`,
+        values: [username]
+      });
+      return Number(result.rows?.[0]?.count ?? 0);
+    }
+
     const query = `
           WITH deleted AS (
             DELETE FROM "Sessions"
@@ -245,7 +293,17 @@ export class AuthRepository extends BaseRepository {
   }
 
   async updateApiTokenLastUsed(tokenId, queryName = null, minIntervalMinutes = 15) {
-    const query = `
+    const query = this.dialect.name === "sqlite"
+      ? `
+      UPDATE "ApiTokens"
+      SET "LastUsed" = CURRENT_TIMESTAMP
+      WHERE id = ?
+        AND (
+          "LastUsed" IS NULL
+          OR "LastUsed" < datetime('now', '-' || ? || ' minutes')
+        )
+    `
+      : `
       UPDATE "ApiTokens"
       SET "LastUsed" = NOW()
       WHERE id = $1

package/lib/db/BaseRepository.js

@@ -152,6 +152,14 @@ export class BaseRepository {
     return new this.constructor({ db, dialect: this.dialect });
   }
 
+  /**
+   * Runs `fn(txRepo)` inside BEGIN..COMMIT on a dedicated client.
+   * Inside the callback, use ONLY the provided txRepo. Calling the outer
+   * repository or the pool from within the callback breaks transactional
+   * semantics on Postgres (runs on a different pooled connection) and
+   * DEADLOCKS on SQLite (the pool waits for the mutex this transaction
+   * holds). See docs/guides/database.md, "SQLite backend notes".
+   */
   async withTransaction(fn) {
     if (!this.db || typeof this.db.connect !== "function") {
       return fn(this);
@@ -184,6 +192,11 @@ export class BaseRepository {
   }
 
   async advisoryTransactionLock(lockKey, queryName = "advisory-transaction-lock") {
+    // pg_advisory_xact_lock is Postgres-only. SQLite (via better-sqlite3) has
+    // no separate connections to contend over: a write transaction already
+    // holds an exclusive file-level lock for its duration, so this is a safe no-op.
+    if (this.dialect.name !== "postgres") return null;
+
     return this.executeRaw({
       name: queryName,
       text: "SELECT pg_advisory_xact_lock(hashtext($1))",

package/lib/db/dialects/sqlite.js

@@ -0,0 +1,25 @@
+const quoteIdentifier = (name) => `"${String(name).replace(/"/g, '""')}"`;
+
+export const sqliteDialect = {
+  name: "sqlite",
+  quoteIdentifier,
+  param: () => "?",
+  now: () => "CURRENT_TIMESTAMP",
+  boolean: (value) => (value ? "1" : "0"),
+  // better-sqlite3 bundles SQLite >= 3.35, which supports RETURNING.
+  supportsReturning: true,
+  returningClause: (columns) => ` RETURNING ${columns}`,
+  limitOffset: ({ limit, offset } = {}) => {
+    const parts = [];
+    if (typeof limit === "number") parts.push(`LIMIT ${limit}`);
+    // SQLite requires a LIMIT clause before OFFSET; -1 means "no limit".
+    if (typeof offset === "number") {
+      if (!parts.length) parts.push("LIMIT -1");
+      parts.push(`OFFSET ${offset}`);
+    }
+    return parts.length ? ` ${parts.join(" ")}` : "";
+  },
+  // SQLite has no table-level lock statement: writers are already serialized
+  // by the file-level lock taken for the duration of a write transaction.
+  lockTable: null
+};