@harshankur/viewcounter 3.0.1 → 3.1.0

package/db/adminSchema.js

@@ -0,0 +1,244 @@
+/**
+ * Schema for the admin feature: per-app admin columns, the two log tables, and
+ * the idempotent migration that brings an existing deployment up to date.
+ *
+ * Every statement here is additive. Nothing is dropped or rewritten, so a
+ * deployment can move to this version and back without losing a row.
+ */
+
+const crypto = require('crypto');
+
+const {
+    ADMIN_LOG_TABLE,
+    DATABASE,
+    FIELD_MAX_LENGTH,
+    VIEW_LOG_TABLE,
+} = require('../constants');
+const { getError, logWarning, ErrorType, WarningType } = require('../utils/errorUtils');
+const { isValidAppId } = require('../utils/appIdUtils');
+
+/**
+ * Columns added to every app table.
+ *
+ * `public_id` is the identity the admin API and UI use (CODE_STANDARDS.md §8):
+ * the auto-increment `id` is enumerable and reveals how many rows exist, so it
+ * never leaves the server. It starts nullable only so an existing table can be
+ * backfilled; the migration then makes it NOT NULL and unique.
+ *
+ * `admin_modified_at` is the "modified by an admin" marker: NULL means the row
+ * is exactly as observed, a timestamp says when an admin last changed its
+ * content. `deleted_at` is the soft-delete marker.
+ */
+const ADMIN_COLUMNS = [
+    { name: 'public_id', ddl: `CHAR(${FIELD_MAX_LENGTH.UUID}) DEFAULT NULL` },
+    { name: 'note', ddl: `VARCHAR(${FIELD_MAX_LENGTH.NOTE}) DEFAULT NULL` },
+    { name: 'admin_modified_at', ddl: 'DATETIME DEFAULT NULL' },
+    { name: 'deleted_at', ddl: 'DATETIME DEFAULT NULL' },
+];
+
+/** Indexes the admin columns need, keyed by index name. */
+const ADMIN_INDEXES = {
+    uq_public_id: 'UNIQUE INDEX `uq_public_id` (`public_id`)',
+    idx_deleted_at: 'INDEX `idx_deleted_at` (`deleted_at`)',
+    idx_admin_modified_at: 'INDEX `idx_admin_modified_at` (`admin_modified_at`)',
+};
+
+/**
+ * The admin operation log: who did what, when, to which rows.
+ *
+ * Deliberately records WHICH fields an edit touched, never their values, and
+ * never an IP beyond its masked form. A log that kept copies of row content
+ * would survive the row's permanent erasure and defeat it (GDPR Art. 17).
+ */
+const ADMIN_LOG_DDL = `
+    CREATE TABLE IF NOT EXISTS \`${ADMIN_LOG_TABLE}\` (
+        \`id\` CHAR(${FIELD_MAX_LENGTH.UUID}) PRIMARY KEY,
+        \`created_at\` DATETIME(3) NOT NULL,
+        \`action\` VARCHAR(32) NOT NULL,
+        \`session_id\` CHAR(${FIELD_MAX_LENGTH.UUID}) DEFAULT NULL,
+        \`masked_ip\` VARCHAR(${FIELD_MAX_LENGTH.MASKED_IP}) DEFAULT NULL,
+        \`app_id\` VARCHAR(64) DEFAULT NULL,
+        \`target_count\` INT NOT NULL DEFAULT 0,
+        \`target_ids\` JSON DEFAULT NULL,
+        \`fields\` JSON DEFAULT NULL,
+        INDEX \`idx_created_at\` (\`created_at\`),
+        INDEX \`idx_action\` (\`action\`),
+        INDEX \`idx_app_id\` (\`app_id\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+`;
+
+/**
+ * The view register log: one entry per accepted view or event.
+ *
+ * Independent of the app tables on purpose, so it still says a view was
+ * reported, and when, after an admin edits, deletes, or erases that view. It
+ * holds no IP, hash, or User-Agent, so it contains no personal data to erase.
+ */
+const VIEW_LOG_DDL = `
+    CREATE TABLE IF NOT EXISTS \`${VIEW_LOG_TABLE}\` (
+        \`id\` CHAR(${FIELD_MAX_LENGTH.UUID}) PRIMARY KEY,
+        \`created_at\` DATETIME(3) NOT NULL,
+        \`app_id\` VARCHAR(64) NOT NULL,
+        \`source\` VARCHAR(16) NOT NULL,
+        \`view_id\` CHAR(${FIELD_MAX_LENGTH.UUID}) NOT NULL,
+        \`event_type\` VARCHAR(${FIELD_MAX_LENGTH.EVENT_TYPE}) DEFAULT NULL,
+        \`is_unique\` TINYINT(1) NOT NULL,
+        INDEX \`idx_created_at\` (\`created_at\`),
+        INDEX \`idx_app_created\` (\`app_id\`, \`created_at\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+`;
+
+/**
+ * Column and index definitions for a brand-new app table, spliced into
+ * `appTableDDL` so a fresh table is born in the migrated shape.
+ */
+const NEW_TABLE_ADMIN_COLUMNS = [
+    `\`public_id\` CHAR(${FIELD_MAX_LENGTH.UUID}) NOT NULL`,
+    `\`note\` VARCHAR(${FIELD_MAX_LENGTH.NOTE}) DEFAULT NULL`,
+    '`admin_modified_at` DATETIME DEFAULT NULL',
+    '`deleted_at` DATETIME DEFAULT NULL',
+];
+
+const NEW_TABLE_ADMIN_INDEXES = Object.values(ADMIN_INDEXES);
+
+/**
+ * @param {object} pool mysql2 promise pool
+ * @param {string} table
+ * @returns {Promise<Map<string, {nullable: boolean}>>} existing columns
+ */
+async function readColumns(pool, table) {
+    const [rows] = await pool.query(
+        `SELECT COLUMN_NAME AS name, IS_NULLABLE AS nullable
+         FROM information_schema.COLUMNS
+         WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`,
+        [table]
+    );
+    return new Map(rows.map((row) => [row.name, { nullable: row.nullable === 'YES' }]));
+}
+
+/**
+ * @param {object} pool
+ * @param {string} table
+ * @returns {Promise<Set<string>>} existing index names
+ */
+async function readIndexes(pool, table) {
+    const [rows] = await pool.query(
+        `SELECT DISTINCT INDEX_NAME AS name
+         FROM information_schema.STATISTICS
+         WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`,
+        [table]
+    );
+    return new Set(rows.map((row) => row.name));
+}
+
+/**
+ * Give every row without a public_id a fresh UUID, a batch at a time.
+ *
+ * Generated in Node with a CSPRNG rather than MySQL's UUID(), which is a
+ * time-and-host based v1 value (CODE_STANDARDS.md §8), and batched so a large
+ * table is not rewritten in one giant statement. Each batch resumes after the
+ * last id it saw (keyset pagination on the primary key), so the whole backfill
+ * reads every row once: restarting from the top each time would rescan all
+ * rows already done, quadratic in table size, and on a large table a single
+ * scan would outlast the pool's statement timeout and fail the migration.
+ *
+ * @param {object} pool
+ * @param {string} table already validated
+ * @returns {Promise<number>} rows backfilled
+ */
+async function backfillPublicIds(pool, table) {
+    let total = 0;
+    let lastId = 0;
+
+    for (;;) {
+        const [rows] = await pool.query(
+            `SELECT id FROM \`${table}\` WHERE id > ? AND public_id IS NULL ORDER BY id LIMIT ?`,
+            [lastId, DATABASE.BACKFILL_BATCH_SIZE]
+        );
+        if (rows.length === 0) return total;
+
+        const ids = rows.map((row) => row.id);
+        lastId = ids[ids.length - 1];
+        const cases = ids.map(() => 'WHEN ? THEN ?').join(' ');
+        const params = ids.flatMap((id) => [id, crypto.randomUUID()]);
+
+        await pool.query(
+            `UPDATE \`${table}\` SET public_id = CASE id ${cases} END WHERE id IN (?)`,
+            [...params, ids]
+        );
+        total += ids.length;
+    }
+}
+
+/**
+ * Bring one app table up to the admin schema. Idempotent: a table already in
+ * shape is read and left alone.
+ *
+ * @param {object} pool
+ * @param {string} appId
+ * @returns {Promise<{migrated: boolean, backfilled: number}>}
+ * @throws {Error} ErrorType.MIGRATION_FAILED, so startup fails loudly rather
+ *   than serving an admin UI over a half-migrated table
+ */
+async function migrateAppTable(pool, appId) {
+    if (!isValidAppId(appId)) {
+        throw getError(ErrorType.INVALID_APP_ID, { appId });
+    }
+
+    try {
+        const columns = await readColumns(pool, appId);
+        if (columns.size === 0) {
+            logWarning(WarningType.MIGRATION_TABLE_MISSING, { table: appId });
+            return { migrated: false, backfilled: 0 };
+        }
+
+        for (const column of ADMIN_COLUMNS) {
+            if (!columns.has(column.name)) {
+                await pool.query(`ALTER TABLE \`${appId}\` ADD COLUMN \`${column.name}\` ${column.ddl}`);
+            }
+        }
+
+        const backfilled = await backfillPublicIds(pool, appId);
+
+        const publicId = columns.get('public_id');
+        if (!publicId || publicId.nullable) {
+            await pool.query(
+                `ALTER TABLE \`${appId}\` MODIFY \`public_id\` CHAR(${FIELD_MAX_LENGTH.UUID}) NOT NULL`
+            );
+        }
+
+        const indexes = await readIndexes(pool, appId);
+        for (const [name, definition] of Object.entries(ADMIN_INDEXES)) {
+            if (!indexes.has(name)) {
+                await pool.query(`ALTER TABLE \`${appId}\` ADD ${definition}`);
+            }
+        }
+
+        return { migrated: true, backfilled };
+    } catch (cause) {
+        throw getError(ErrorType.MIGRATION_FAILED, { table: appId, cause: cause.message });
+    }
+}
+
+/**
+ * Create the log tables. Safe in `connect` mode for the same reason the app
+ * registry is: they are the service's own bookkeeping, not the operator's
+ * schema.
+ * @param {object} pool
+ */
+async function ensureLogTables(pool) {
+    await pool.query(ADMIN_LOG_DDL);
+    await pool.query(VIEW_LOG_DDL);
+}
+
+module.exports = {
+    ADMIN_COLUMNS,
+    ADMIN_INDEXES,
+    ADMIN_LOG_DDL,
+    VIEW_LOG_DDL,
+    NEW_TABLE_ADMIN_COLUMNS,
+    NEW_TABLE_ADMIN_INDEXES,
+    backfillPublicIds,
+    ensureLogTables,
+    migrateAppTable,
+};

package/db/retention.js

@@ -0,0 +1,97 @@
+/**
+ * Scheduled retention: expired trash, and old view-log entries.
+ *
+ * Trash (GDPR Art. 5(1)(e), storage limitation): a soft-deleted view is kept
+ * for TRASH_RETENTION_DAYS so a mistaken delete can be undone, then erased for
+ * good.
+ *
+ * View log: the register of accepted views gains a row per view. It holds no
+ * personal data, but unbounded it grows as large as every app table together,
+ * so entries older than VIEW_LOG_RETENTION_DAYS are removed.
+ *
+ * Every run that removes anything leaves an entry in the admin operation log,
+ * attributed to the system rather than a session, so nothing is removed
+ * silently. The admin log itself is never pruned.
+ */
+
+const { ADMIN, ADMIN_ACTION } = require('../constants');
+const { logWarning, WarningType } = require('../utils/errorUtils');
+
+/**
+ * Erase expired trash in every app once.
+ *
+ * One app failing does not stop the others; the failure is reported and the
+ * next run tries again.
+ *
+ * @param {{ adminRepo: object, logRepo: object, appIds: string[], days: number }} deps
+ * @returns {Promise<Record<string, number>>} rows erased per app
+ */
+async function purgeExpiredTrash({ adminRepo, logRepo, appIds, days }) {
+    const erased = {};
+    if (!(days > 0)) return erased;
+
+    for (const appId of appIds) {
+        try {
+            const count = await adminRepo.purgeExpired(appId, days);
+            erased[appId] = count;
+            if (count > 0) {
+                await logRepo.writeAdminLog({
+                    action: ADMIN_ACTION.TRASH_AUTO_PURGED,
+                    appId,
+                    targetCount: count,
+                });
+            }
+        } catch (cause) {
+            logWarning(WarningType.TRASH_PURGE_FAILED, { appId, cause: cause.message });
+        }
+    }
+    return erased;
+}
+
+/**
+ * Remove view-log entries older than `days` once. A failure is reported and
+ * the next run tries again.
+ *
+ * @param {{ logRepo: object, days: number }} deps
+ * @returns {Promise<number>} entries removed
+ */
+async function pruneViewLog({ logRepo, days }) {
+    if (!(days > 0)) return 0;
+    try {
+        const count = await logRepo.pruneViewLog(days);
+        if (count > 0) {
+            await logRepo.writeAdminLog({ action: ADMIN_ACTION.VIEW_LOG_PRUNED, targetCount: count });
+        }
+        return count;
+    } catch (cause) {
+        logWarning(WarningType.VIEW_LOG_PRUNE_FAILED, { cause: cause.message });
+        return 0;
+    }
+}
+
+/**
+ * Run both jobs now and then on an interval. A job whose retention is zero
+ * (keep forever) is skipped; when both are, nothing is scheduled.
+ *
+ * `getAppIds` is called on every run, so apps provisioned at runtime are
+ * covered without a restart. The timer is unref'd so it never keeps the
+ * process alive on its own.
+ *
+ * @param {{ adminRepo: object, logRepo: object, getAppIds: () => string[],
+ *   trashDays: number, viewLogDays: number, intervalMs?: number }} deps
+ * @returns {() => void} stops the schedule
+ */
+function startRetention({ adminRepo, logRepo, getAppIds, trashDays, viewLogDays, intervalMs = ADMIN.RETENTION_INTERVAL_MS }) {
+    if (!(trashDays > 0) && !(viewLogDays > 0)) return () => {};
+
+    const run = async () => {
+        await purgeExpiredTrash({ adminRepo, logRepo, appIds: getAppIds(), days: trashDays });
+        await pruneViewLog({ logRepo, days: viewLogDays });
+    };
+    run();
+    const timer = setInterval(run, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+    return () => clearInterval(timer);
+}
+
+module.exports = { purgeExpiredTrash, pruneViewLog, startRetention };

package/index.js

@@ -3,18 +3,21 @@ const cors = require('cors');
 const helmet = require('helmet');
 const rateLimit = require('express-rate-limit');
 
-const { APP_NAME, HTTP_STATUS, PAYLOAD_LIMITS, SERVER } = require('./constants');
+const { ADMIN, APP_NAME, HTTP_STATUS, PAYLOAD_LIMITS, SERVER } = require('./constants');
 const config = require('./config');
 const DatabaseManager = require('./db/DatabaseManager');
 const logger = require('./utils/logger');
 const { buildCorsOptions } = require('./middleware/security');
 const { createAnalyticsRouter } = require('./routes/analytics');
+const { createAdminRouter } = require('./routes/admin');
+const { startRetention } = require('./db/retention');
 
 logger.configure({ level: config.server.logLevel });
 
 const dbManager = new DatabaseManager(config.dbInfo);
 let isServerReady = false;
 let httpServer = null;
+let stopRetention = () => {};
 
 /**
  * Build the Express application.
@@ -27,17 +30,30 @@ function createApp() {
 
     app.disable('x-powered-by');
     app.use(helmet());
+
+    // Trusting the proxy is needed before the admin router sees a request: it
+    // decides whether the session cookie is marked Secure from req.secure.
+    app.set('trust proxy', config.server.trustProxy);
+
+    // The admin surface exists only when a password is configured, and is
+    // mounted ahead of CORS and the public rate limit: it is same-origin only,
+    // must never carry the analytics sites' CORS headers, and has its own
+    // limits.
+    if (config.admin.enabled) {
+        app.use(ADMIN.PATH_PREFIX, createAdminRouter({
+            config,
+            adminRepo: dbManager.admin,
+            logRepo: dbManager.logs,
+            isReady: () => isServerReady,
+        }));
+    }
+
     app.use(cors(buildCorsOptions(config.server.corsOrigins)));
 
     // Bounded well below body-parser's 100kb default; /event is the only
     // endpoint taking a body and its payload is small.
     app.use(express.json({ limit: PAYLOAD_LIMITS.MAX_BODY_BYTES }));
 
-    // Never bare `true`. Trusting every hop lets any caller set
-    // X-Forwarded-For and be believed, which forges geolocation and rotates
-    // the rate-limiter key at will.
-    app.set('trust proxy', config.server.trustProxy);
-
     app.use(rateLimit({
         windowMs: config.server.rateLimit.windowMs,
         limit: config.server.rateLimit.max,
@@ -108,6 +124,20 @@ const initializeServer = async () => {
         // anyone editing allowed.json.
         await mergeRegisteredApps();
 
+        // initialize() migrated the configured apps; this also covers the ones
+        // registered at runtime and merged in above. Idempotent, so apps
+        // already in shape cost one information_schema read. Fails startup
+        // rather than serving over a half-migrated table.
+        await dbManager.migrate(config.allowed.appId);
+
+        stopRetention = startRetention({
+            adminRepo: dbManager.admin,
+            logRepo: dbManager.logs,
+            getAppIds: () => config.allowed.appId,
+            trashDays: config.admin.trashRetentionDays,
+            viewLogDays: config.admin.viewLogRetentionDays,
+        });
+
         isServerReady = true;
 
         if (require.main === module) {
@@ -147,6 +177,7 @@ const shutdown = async (signal, exitCode = 0) => {
     forceExit.unref();
 
     try {
+        stopRetention();
         if (httpServer) {
             await new Promise((resolve) => httpServer.close(resolve));
         }
@@ -179,6 +210,8 @@ process.on('uncaughtException', (error) => {
 module.exports = app;
 module.exports.createApp = createApp;
 module.exports.createAnalyticsRouter = createAnalyticsRouter;
+module.exports.createAdminRouter = createAdminRouter;
+module.exports.startRetention = startRetention;
 module.exports.DatabaseManager = DatabaseManager;
 module.exports.dbManager = dbManager;
 module.exports.initializeServer = initializeServer;

package/middleware/adminAuth.js

@@ -0,0 +1,204 @@
+/**
+ * Admin UI authentication: password login, server-side sessions, and CSRF.
+ *
+ * Sessions live in memory. A restart signs every admin out, which is the safe
+ * direction to fail in and costs one login. The browser holds only an opaque
+ * random token in an HttpOnly cookie; the store is keyed by that token's
+ * SHA-256, so a memory dump of the store does not yield usable cookies.
+ *
+ * CSRF is defeated three ways, each sufficient on its own in a modern browser:
+ * the cookie is SameSite=Strict, every mutating request must echo a per-session
+ * token in a header that a cross-site form cannot set, and a present Origin
+ * header must match this server.
+ */
+
+const crypto = require('crypto');
+
+const { ADMIN, ADMIN_ERROR_CODE, HTTP_STATUS } = require('../constants');
+const { safeEqual } = require('./auth');
+const { parseCookies } = require('../utils/cookieUtils');
+const { WarningType, logWarning } = require('../utils/errorUtils');
+
+/** Methods that never change state and so need no CSRF token. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/** @param {string} token @returns {string} */
+function hashToken(token) {
+    return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+/**
+ * @param {{ idleMs?: number, absoluteMs?: number, maxSessions?: number,
+ *   now?: () => number }} [options]
+ */
+function createSessionStore({
+    idleMs = ADMIN.SESSION_IDLE_TIMEOUT_MS,
+    absoluteMs = ADMIN.SESSION_ABSOLUTE_TIMEOUT_MS,
+    maxSessions = ADMIN.MAX_SESSIONS,
+    now = Date.now,
+} = {}) {
+    /** @type {Map<string, {id: string, csrfToken: string, createdAt: number, lastSeenAt: number}>} */
+    const sessions = new Map();
+
+    function isExpired(session, at) {
+        return at - session.lastSeenAt > idleMs || at - session.createdAt > absoluteMs;
+    }
+
+    return {
+        /**
+         * Start a session.
+         * @returns {{ token: string, session: {id: string, csrfToken: string, createdAt: number, lastSeenAt: number} }}
+         */
+        create() {
+            const at = now();
+            const token = crypto.randomBytes(ADMIN.SESSION_TOKEN_BYTES).toString('base64url');
+            const session = {
+                id: crypto.randomUUID(),
+                csrfToken: crypto.randomBytes(ADMIN.CSRF_TOKEN_BYTES).toString('base64url'),
+                createdAt: at,
+                lastSeenAt: at,
+            };
+
+            // Bounded: the oldest session goes first. Map preserves insertion
+            // order, so the first key is always the oldest.
+            while (sessions.size >= maxSessions) {
+                sessions.delete(sessions.keys().next().value);
+            }
+            sessions.set(hashToken(token), session);
+            return { token, session };
+        },
+
+        /**
+         * Look up a live session and extend its idle window.
+         * @param {string|undefined} token
+         */
+        get(token) {
+            if (typeof token !== 'string' || token.length === 0) return null;
+            const key = hashToken(token);
+            const session = sessions.get(key);
+            if (!session) return null;
+
+            const at = now();
+            if (isExpired(session, at)) {
+                sessions.delete(key);
+                return null;
+            }
+            session.lastSeenAt = at;
+            return session;
+        },
+
+        /** @param {string|undefined} token */
+        destroy(token) {
+            if (typeof token !== 'string' || token.length === 0) return false;
+            return sessions.delete(hashToken(token));
+        },
+
+        get size() {
+            return sessions.size;
+        },
+    };
+}
+
+/** Read the session token from the request's cookies. */
+function readToken(req) {
+    return parseCookies(req.headers.cookie)[ADMIN.SESSION_COOKIE];
+}
+
+/**
+ * Cookie attributes. `Secure` follows the connection: a deployment behind a
+ * TLS-terminating proxy gets it through `trust proxy`, and plain-HTTP local
+ * development still works. Scoped to wherever the admin router is mounted
+ * (`req.adminBasePath`), so the cookie never travels to the public analytics
+ * endpoints and still works when another app mounts the router elsewhere.
+ */
+function cookieOptions(req) {
+    return {
+        httpOnly: true,
+        sameSite: 'strict',
+        secure: req.secure,
+        path: req.adminBasePath || ADMIN.PATH_PREFIX,
+        maxAge: ADMIN.SESSION_ABSOLUTE_TIMEOUT_MS,
+    };
+}
+
+/** @returns {import('express').RequestHandler} */
+function requireAdminSession(store) {
+    return (req, res, next) => {
+        const token = readToken(req);
+        const session = store.get(token);
+        if (!session) {
+            return res.status(HTTP_STATUS.UNAUTHORIZED).json({ code: ADMIN_ERROR_CODE.UNAUTHENTICATED });
+        }
+        req.adminSession = session;
+        req.adminToken = token;
+        return next();
+    };
+}
+
+/**
+ * The origin this request was addressed to, as the browser would write it.
+ * @param {import('express').Request} req
+ */
+function expectedOrigin(req) {
+    return `${req.protocol}://${req.get('host')}`;
+}
+
+/**
+ * Whether a browser-supplied Origin (absent for same-origin GETs and non-browser
+ * clients) matches this server. A mismatch is logged with both values: behind a
+ * misconfigured proxy every admin request is refused, and the log is the only
+ * place that says why.
+ * @param {import('express').Request} req
+ */
+function originAllowed(req) {
+    const presented = req.get('origin');
+    if (!presented) return true;
+    const expected = expectedOrigin(req);
+    if (presented === expected) return true;
+    logWarning(WarningType.ADMIN_ORIGIN_REJECTED, { presented, expected });
+    return false;
+}
+
+/**
+ * Reject a state-changing request that does not carry this session's CSRF
+ * token, or that a browser says came from another origin.
+ * @returns {import('express').RequestHandler}
+ */
+function requireCsrf() {
+    return (req, res, next) => {
+        if (SAFE_METHODS.has(req.method)) return next();
+
+        const presented = req.get(ADMIN.CSRF_HEADER) || '';
+        const session = req.adminSession;
+
+        const originOk = originAllowed(req);
+        const tokenOk = Boolean(session) && safeEqual(presented, session.csrfToken);
+
+        if (!originOk || !tokenOk) {
+            return res.status(HTTP_STATUS.FORBIDDEN).json({ code: ADMIN_ERROR_CODE.CSRF_REJECTED });
+        }
+        return next();
+    };
+}
+
+/**
+ * Constant-time password check. An unset password never matches anything,
+ * including an empty submission.
+ */
+function verifyPassword(presented, configured) {
+    if (!configured) return false;
+    return safeEqual(String(presented ?? ''), configured);
+}
+
+module.exports = {
+    createSessionStore,
+    requireAdminSession,
+    requireCsrf,
+    verifyPassword,
+    cookieOptions,
+    expectedOrigin,
+    originAllowed,
+    readToken,
+    hashToken,
+    SAFE_METHODS,
+};