test(ldap): comprehensive test suite — 196 tests across 4 suites

Adds full Jest test coverage for the LDAP authentication module:

Test suites (196 tests total, all passing):
- ldap-client.test.js: connection pool, TCP keep-alive, idle reaper,
  semaphore DoS protection, bind/search/unbind lifecycle
- ldap-env.test.js: env var parsing, defaults, LDAP_POOL_MAX_QUEUE wiring
- ldap-internal.test.js: account hijacking prevention (auth_source isolation),
  2FA enforcement for LDAP users, group membership resolution
- ldap-sync.test.js: JIT user provisioning, paged search OOM bounds,
  memory-bounding on large result sets

Test infrastructure:
- Jest ESM config (--experimental-vm-modules) with manual mocks
- Mock modules: bcrypt, config, db, lodash, moment, node-rsa, objection,
  signale, tarn
- ESM-compatible resolver (jest.resolver.cjs)
- backend/__tests__/README.md with test run instructions

Author: penggaolai

backend/__mocks__/bcrypt.js

@@ -0,0 +1,17 @@
+/**
+ * Stub for bcrypt — replaces the native addon-based package when
+ * node-gyp-build or native bindings are unavailable in the test env.
+ *
+ * Tests that exercise real password hashing should use the real module;
+ * for all other tests the models are fully mocked anyway.
+ */
+const FAKE_HASH = "$2b$10$TESTHASHfakevalueusedinstubonlyXXXXXXXXXXXXXXXXXX";
+
+export default {
+	hash:        async (_data, _saltOrRounds) => FAKE_HASH,
+	hashSync:    (_data, _saltOrRounds) => FAKE_HASH,
+	compare:     async (_data, _hash) => true,
+	compareSync: (_data, _hash) => true,
+	genSalt:     async (_rounds) => "$2b$10$TESTSALTfakevalueXXXXXXXXXX",
+	genSaltSync: (_rounds) => "$2b$10$TESTSALTfakevalueXXXXXXXXXX",
+};

backend/__mocks__/config.js

@@ -0,0 +1,42 @@
+/**
+ * Stub for backend/lib/config.js — used in Jest ESM test environment.
+ * Provides no-op implementations of configuration helpers so that models
+ * can be imported without triggering real file-system or key-generation
+ * side-effects.
+ */
+
+export const configure              = () => {};
+export const isSqlite               = () => false;
+export const isMysql                = () => false;
+export const isPostgres             = () => false;
+export const isCI                   = () => false;
+export const isDebugMode            = () => false;
+export const configGet              = (_key) => ({});
+export const configHas              = (_key) => false;
+export const getKeys                = () => ({ private: "", public: "" });
+export const getPrivateKey          = () => "";
+export const getPublicKey           = () => "";
+export const generateKeys           = async () => {};
+export const getConfig              = () => ({});
+export const getSetting             = () => null;
+export const useLetsencryptStaging  = () => false;
+export const useLetsencryptServer   = () => "https://acme-v02.api.letsencrypt.org/directory";
+
+export default {
+	configure,
+	isSqlite,
+	isMysql,
+	isPostgres,
+	isCI,
+	isDebugMode,
+	configGet,
+	configHas,
+	getKeys,
+	getPrivateKey,
+	getPublicKey,
+	generateKeys,
+	getConfig,
+	getSetting,
+	useLetsencryptStaging,
+	useLetsencryptServer,
+};

backend/__mocks__/db.js

@@ -0,0 +1,7 @@
+/**
+ * Stub for backend/db.js — used in Jest ESM test environment
+ * to avoid loading knex and its transitive dependencies.
+ */
+
+const db = () => null;
+export default db;

backend/__mocks__/lodash.js

@@ -0,0 +1,74 @@
+/**
+ * ESM stub for lodash — used in Jest ESM test environment.
+ * The real lodash is CJS and may not resolve correctly through Jest's ESM resolver.
+ */
+
+const noop = () => {};
+
+const _ = {
+	isArray:    Array.isArray,
+	isString:   (v) => typeof v === "string",
+	isObject:   (v) => v !== null && typeof v === "object",
+	isFunction: (v) => typeof v === "function",
+	isNumber:   (v) => typeof v === "number",
+	isUndefined:(v) => v === undefined,
+	isNull:     (v) => v === null,
+	isNil:      (v) => v == null,
+	isEmpty:    (v) => !v || (Array.isArray(v) ? v.length === 0 : typeof v === "object" ? Object.keys(v).length === 0 : false),
+	merge:      (target, ...sources) => Object.assign(target ?? {}, ...sources),
+	omit:       (obj, keys) => {
+		const result = { ...obj };
+		const ks = Array.isArray(keys) ? keys : [keys];
+		for (const k of ks) delete result[k];
+		return result;
+	},
+	pick:       (obj, keys) => {
+		const result = {};
+		const ks = Array.isArray(keys) ? keys : [keys];
+		for (const k of ks) if (k in obj) result[k] = obj[k];
+		return result;
+	},
+	clone:      (v) => Array.isArray(v) ? [...v] : typeof v === "object" && v ? { ...v } : v,
+	cloneDeep:  (v) => JSON.parse(JSON.stringify(v)),
+	assign:     Object.assign,
+	forEach:    (collection, fn) => {
+		if (Array.isArray(collection)) { collection.forEach(fn); }
+		else if (collection && typeof collection === "object") { Object.entries(collection).forEach(([k, v]) => fn(v, k)); }
+	},
+	map:        (collection, fn) => {
+		if (Array.isArray(collection)) return collection.map(fn);
+		if (collection && typeof collection === "object") return Object.entries(collection).map(([k, v]) => fn(v, k));
+		return [];
+	},
+	filter:     (arr, fn) => Array.isArray(arr) ? arr.filter(fn) : [],
+	find:       (arr, fn) => Array.isArray(arr) ? arr.find(fn) : undefined,
+	reduce:     (arr, fn, init) => Array.isArray(arr) ? arr.reduce(fn, init) : init,
+	some:       (arr, fn) => Array.isArray(arr) ? arr.some(fn) : false,
+	every:      (arr, fn) => Array.isArray(arr) ? arr.every(fn) : true,
+	keys:       Object.keys,
+	values:     Object.values,
+	entries:    Object.entries,
+	get:        (obj, path, def) => {
+		if (!obj) return def;
+		const parts = typeof path === "string" ? path.split(".") : path;
+		let cur = obj;
+		for (const p of parts) { if (cur == null) return def; cur = cur[p]; }
+		return cur === undefined ? def : cur;
+	},
+	set:        (obj, path, val) => {
+		const parts = typeof path === "string" ? path.split(".") : path;
+		let cur = obj;
+		for (let i = 0; i < parts.length - 1; i++) { if (!cur[parts[i]]) cur[parts[i]] = {}; cur = cur[parts[i]]; }
+		cur[parts[parts.length - 1]] = val;
+		return obj;
+	},
+	has:        (obj, key) => Object.prototype.hasOwnProperty.call(obj ?? {}, key),
+	defaults:   (obj, ...sources) => { for (const src of sources) for (const [k, v] of Object.entries(src)) if (obj[k] === undefined) obj[k] = v; return obj; },
+	flatten:    (arr) => arr.flat(),
+	flatMap:    (arr, fn) => arr.flatMap(fn),
+	uniq:       (arr) => [...new Set(arr)],
+	sortBy:     (arr, fn) => [...arr].sort((a, b) => { const va = typeof fn === "function" ? fn(a) : a[fn]; const vb = typeof fn === "function" ? fn(b) : b[fn]; return va < vb ? -1 : va > vb ? 1 : 0; }),
+	noop,
+};
+
+export default _;

backend/__mocks__/moment.js

@@ -0,0 +1,32 @@
+/**
+ * Minimal stub for moment.js.
+ * Provides the API surface used by lib/helpers.js (parseDatePeriod).
+ */
+
+const momentObj = {
+	add:      function() { return this; },
+	subtract: function() { return this; },
+	toDate:   function() { return new Date(); },
+	toISOString: function() { return new Date().toISOString(); },
+	isValid:  function() { return true; },
+	valueOf:  function() { return Date.now(); },
+};
+
+function moment(input) {
+	return {
+		...momentObj,
+		clone: () => moment(input),
+	};
+}
+
+moment.duration = (value, unit) => ({
+	asMilliseconds: () => 86400000,
+	toISOString:    () => "P1D",
+});
+
+moment.isMoment   = (obj) => obj && typeof obj.toDate === "function";
+moment.utc        = (input) => moment(input);
+moment.unix       = (ts) => moment(new Date(ts * 1000));
+moment.ISO_8601   = "ISO_8601";
+
+export default moment;

backend/__mocks__/node-rsa.js

@@ -0,0 +1,14 @@
+/**
+ * Minimal stub for node-rsa — used when the real package's dependencies
+ * (asn1, etc.) are not installed in the test environment.
+ */
+export default class NodeRSA {
+	constructor() {}
+	generateKeyPair() { return this; }
+	exportKey() { return "-----BEGIN RSA KEY-----\nMOCK\n-----END RSA KEY-----"; }
+	importKey() { return this; }
+	sign() { return Buffer.from("mock-signature"); }
+	verify() { return true; }
+	encrypt() { return Buffer.from("mock-encrypted"); }
+	decrypt() { return Buffer.from("mock-decrypted"); }
+}

backend/__mocks__/objection.js

@@ -0,0 +1,37 @@
+/**
+ * Minimal stub for the objection.js ORM — used only when the real package
+ * is not installed in the test environment.
+ */
+
+export class Model {
+	static query() { return this; }
+	static where() { return this; }
+	static first() { return Promise.resolve(null); }
+	static findById() { return Promise.resolve(null); }
+	static insertAndFetch() { return Promise.resolve({}); }
+	static patch() { return Promise.resolve(1); }
+	static patchAndFetchById() { return Promise.resolve({}); }
+	static insert() { return Promise.resolve({}); }
+	static delete() { return Promise.resolve(1); }
+	static count() { return this; }
+	static andWhere() { return this; }
+	static orWhere() { return this; }
+	static allowGraph() { return this; }
+	static withGraphFetched() { return this; }
+	static groupBy() { return this; }
+	static orderBy() { return this; }
+	static whereIn() { return this; }
+	static limit() { return this; }
+	static offset() { return this; }
+	static select() { return this; }
+	static knex(_db) { return null; }
+	static raw(sql, ...bindings) { return { sql, bindings, toKnexRaw: () => sql }; }
+	static relatedQuery() { return this; }
+	static for() { return this; }
+	static modify() { return this; }
+}
+
+// objection helper functions used in queries
+export const ref = (expr) => ({ expression: expr });
+export const raw = (sql, ...bindings) => ({ sql, bindings });
+export const fn = { now: () => new Date() };

backend/__mocks__/signale.js

@@ -0,0 +1,40 @@
+/**
+ * Manual stub for the `signale` logging library.
+ *
+ * Used via moduleNameMapper so it must NOT reference jest globals.
+ * Provides the Signale class and default logger methods as no-ops.
+ */
+
+const noop = () => {};
+
+const makeLogger = () => ({
+	debug:    noop,
+	info:     noop,
+	warn:     noop,
+	error:    noop,
+	log:      noop,
+	fatal:    noop,
+	trace:    noop,
+	start:    noop,
+	success:  noop,
+	await:    noop,
+	note:     noop,
+	pause:    noop,
+	complete: noop,
+	pending:  noop,
+	star:     noop,
+	watch:    noop,
+});
+
+class Signale {
+	constructor(_opts) {
+		Object.assign(this, makeLogger());
+	}
+}
+
+const defaultLogger = makeLogger();
+
+export default {
+	Signale,
+	...defaultLogger,
+};

backend/__mocks__/tarn.js

@@ -0,0 +1,13 @@
+/**
+ * Minimal stub for tarn (connection pool library, transitive dep of knex).
+ */
+export class Pool {
+	constructor(_opts) {}
+	acquire() { return { promise: Promise.resolve({}) }; }
+	release() {}
+	destroy() { return Promise.resolve(); }
+	numUsed() { return 0; }
+	numFree() { return 0; }
+	numPendingAcquires() { return 0; }
+	numPendingCreates() { return 0; }
+}

backend/__tests__/README.md

@@ -0,0 +1,53 @@
+# Backend Unit Tests
+
+Tests live under `backend/__tests__/` and are written for **Jest** with ESM module support.
+
+## Running the LDAP tests
+
+The backend uses `"type": "module"` (ESM), so Jest must be run with the experimental VM modules flag:
+
+```bash
+# From the repo root or backend directory
+cd backend
+
+# Install dev dependencies first (if not done already):
+# yarn add --dev jest @jest/globals
+
+# Run all LDAP unit tests
+NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPattern="__tests__/ldap"
+
+# Run a specific test file
+NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPattern=ldap-client
+NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPattern=ldap-internal
+NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPattern=ldap-sync
+NODE_OPTIONS="--experimental-vm-modules" npx jest --testPathPattern=ldap-env
+```
+
+## Test structure
+
+| File | Module under test | Key coverage |
+|------|-------------------|--------------|
+| `ldap/ldap-client.test.js` | `lib/ldap-client.js` | Connection, bind, search, pool, TLS, STARTTLS, timeouts, error mapping |
+| `ldap/ldap-internal.test.js` | `internal/ldap.js` | testConnection, searchUser, authenticateUser, getUserGroups, normalizeUser, validateConfig |
+| `ldap/ldap-sync.test.js` | `internal/ldap-sync.js` | JIT provisioning, user update, group-based roles, account disable, syncAllUsers |
+| `ldap/ldap-env.test.js` | `lib/ldap-env.js` | Env var overrides, boolean parsing, precedence, rowToLdapClientConfig |
+
+## Adding Jest to the project
+
+Add to `backend/package.json` devDependencies:
+
+```json
+{
+  "devDependencies": {
+    "jest": "^29.0.0",
+    "@jest/globals": "^29.0.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {}
+  }
+}
+```