@harshankur/viewcounter 3.0.1 → 3.2.0

package/db/rejectionCounter.js

@@ -0,0 +1,117 @@
+/**
+ * Counts tracking requests that were not stored (bots and rejections) and
+ * writes the counts to the tracking log in batches.
+ *
+ * A rejected request must cost less than an accepted one, or the tracking log
+ * would turn every flood the rate limiter turns away into database writes. So
+ * nothing is written per request: counts accumulate in memory, keyed by
+ * minute, endpoint, reason, app, detail, and hostname, and one upsert every
+ * TRACKING.REJECTION_FLUSH_MS adds them to what is stored.
+ *
+ * The key space is bounded as well, and so are the rows written. App IDs,
+ * details, and hostnames can be made up by whoever sends the request, so only
+ * TRACKING.REJECTION_MAX_KEYS_PER_MINUTE distinct keys a minute, and
+ * TRACKING.REJECTION_MAX_KEYS_PER_HOUR an hour, keep them. The budgets hold
+ * across flushes: writing the counts does not start a new allowance. Beyond
+ * them a key keeps only its minute, endpoint, and reason. The count stays
+ * exact; the made-up values are dropped.
+ */
+
+const { TRACKING } = require('../constants');
+
+/** The shape an app ID must have to be kept; anything else is counted as blank. */
+const APP_ID_SHAPE = /^[A-Za-z0-9_-]{1,64}$/;
+/** Details are our own short labels (a field name, a bot's name), but are bounded anyway. */
+const DETAIL_MAX = 64;
+
+const cleanAppId = (value) => (typeof value === 'string' && APP_ID_SHAPE.test(value) ? value : '');
+const cleanDetail = (value) => (typeof value === 'string' ? value.replace(/[^\x20-\x7e]/g, '').slice(0, DETAIL_MAX) : '');
+const cleanHostname = (value) => (typeof value === 'string' ? value : '');
+
+const HOUR_MS = 60 * 60 * 1000;
+
+/**
+ * @param {{ write: (rows: object[]) => Promise<unknown>, now?: () => number,
+ *   flushMs?: number, maxKeysPerMinute?: number, maxKeysPerHour?: number }} options
+ */
+function createRejectionCounter({
+    write,
+    now = Date.now,
+    flushMs = TRACKING.REJECTION_FLUSH_MS,
+    maxKeysPerMinute = TRACKING.REJECTION_MAX_KEYS_PER_MINUTE,
+    maxKeysPerHour = TRACKING.REJECTION_MAX_KEYS_PER_HOUR,
+}) {
+    const pending = new Map();
+    /** Keys already kept whole, by minute: this minute's and the one before. */
+    const keptByMinute = new Map();
+    /** How many keys were kept whole, by hour: this hour's. */
+    const keptByHour = new Map();
+    let timer = null;
+
+    /** Whether a key may keep its app, detail, and hostname, spending the budgets if new. */
+    function keepWhole(minute, key) {
+        for (const old of keptByMinute.keys()) if (old < minute - TRACKING.REJECTION_BUCKET_MS) keptByMinute.delete(old);
+        const hour = Math.floor(minute / HOUR_MS) * HOUR_MS;
+        for (const old of keptByHour.keys()) if (old < hour) keptByHour.delete(old);
+
+        const kept = keptByMinute.get(minute) || new Set();
+        keptByMinute.set(minute, kept);
+        if (kept.has(key)) return true;
+        const hourCount = keptByHour.get(hour) || 0;
+        if (kept.size >= maxKeysPerMinute || hourCount >= maxKeysPerHour) return false;
+        kept.add(key);
+        keptByHour.set(hour, hourCount + 1);
+        return true;
+    }
+
+    function schedule() {
+        if (timer) return;
+        timer = setTimeout(() => {
+            timer = null;
+            flush();
+        }, flushMs);
+        if (typeof timer.unref === 'function') timer.unref();
+    }
+
+    /**
+     * Count one request.
+     * @param {{ source: string, reason: string, appId?: string, detail?: string, hostname?: string }} rejection
+     */
+    function count({ source, reason, appId, detail, hostname }) {
+        const minute = Math.floor(now() / TRACKING.REJECTION_BUCKET_MS) * TRACKING.REJECTION_BUCKET_MS;
+        let entry = { source, reason, appId: cleanAppId(appId), detail: cleanDetail(detail), hostname: cleanHostname(hostname) };
+        let key = [minute, entry.source, entry.reason, entry.appId, entry.detail, entry.hostname].join('\u0000');
+        const plain = !entry.appId && !entry.detail && !entry.hostname;
+        if (!plain && !keepWhole(minute, key)) {
+            entry = { source, reason, appId: '', detail: '', hostname: '' };
+            key = [minute, source, reason, '', '', ''].join('\u0000');
+        }
+
+        const row = pending.get(key) || { minute: new Date(minute), ...entry, requests: 0 };
+        row.requests += 1;
+        pending.set(key, row);
+        schedule();
+    }
+
+    /** Write everything pending now; also used on shutdown. */
+    async function flush() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (pending.size === 0) return;
+        const rows = [...pending.values()];
+        pending.clear();
+        await write(rows);
+    }
+
+    return {
+        count,
+        flush,
+        get pendingKeys() {
+            return pending.size;
+        },
+    };
+}
+
+module.exports = { createRejectionCounter };

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,26 @@ 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, PAYLOAD_LIMITS, REJECTION_REASON, 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 { buildCorsOptions, countRefusedPreflights } = require('./middleware/security');
+const { createAnalyticsRouter, trackingSourceFor } = require('./routes/analytics');
+const { createAdminRouter } = require('./routes/admin');
+const { startRetention } = require('./db/retention');
+const { createDbSessionStore } = require('./db/adminSessionStore');
+const { openCityLookup } = require('./utils/geoCity');
 
 logger.configure({ level: config.server.logLevel });
 
 const dbManager = new DatabaseManager(config.dbInfo);
 let isServerReady = false;
 let httpServer = null;
+let stopRetention = () => {};
+let analyticsRouter = null;
+/** The optional city database, opened at startup; both routers read it per request. */
+const geo = { city: null };
 
 /**
  * Build the Express application.
@@ -27,39 +35,71 @@ 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,
+            // In the database, so a restart or deploy signs nobody out.
+            sessionStore: createDbSessionStore(dbManager, {
+                idleMs: config.admin.sessionIdleMs,
+                absoluteMs: config.admin.sessionMaxAgeMs,
+            }),
+            isReady: () => isServerReady,
+            geo,
+        }));
+    }
+
+    const router = createAnalyticsRouter({
+        config,
+        dbManager,
+        isReady: () => isServerReady,
+        geo,
+    });
+    analyticsRouter = router;
+
+    // A site missing from CORS_ORIGINS is refused at the browser's preflight;
+    // counted, so the tracking log shows it.
+    app.use(countRefusedPreflights(config.server.corsOrigins, {
+        isTrackingPath: (path) => Boolean(trackingSourceFor(path)),
+        onRefused: (req) => router.countRejection(req, REJECTION_REASON.ORIGIN_NOT_ALLOWED, { detail: 'CORS_ORIGINS' }),
+    }));
     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,
         message: { message: 'Too many requests, please try again later.' },
         standardHeaders: true,
         legacyHeaders: false,
+        // A tracking request turned away here is counted in the tracking log
+        // like any other refusal (in memory, written in batches).
+        handler: (req, res, next, options) => {
+            if (trackingSourceFor(req.path)) {
+                router.countRejection(req, REJECTION_REASON.RATE_LIMITED, { detail: 'ip' });
+            }
+            res.status(options.statusCode).json(options.message);
+        },
     }));
 
-    app.use(createAnalyticsRouter({
-        config,
-        dbManager,
-        isReady: () => isServerReady,
-    }));
+    app.use(router);
 
-    // Malformed JSON and payloads over the limit surface here.
-    // eslint-disable-next-line no-unused-vars
-    app.use((err, req, res, next) => {
-        const status = err.status || err.statusCode || HTTP_STATUS.INTERNAL_SERVER_ERROR;
-        logger.warn(`Request rejected: ${err.message}`, { requestId: req.id });
-        res.status(status === HTTP_STATUS.INTERNAL_SERVER_ERROR ? HTTP_STATUS.BAD_REQUEST : status)
-            .json({ message: 'Malformed or oversized request' });
-    });
+    // Malformed JSON and payloads over the limit surface here, and are
+    // counted in the tracking log when they were sent to a tracking endpoint.
+    app.use(router.bodyErrorHandler);
 
     return app;
 }
@@ -72,7 +112,7 @@ const app = createApp();
  * Config-declared apps and registry-declared apps are unioned: the file stays
  * authoritative for a fixed single-operator deployment, while the registry
  * carries tenants provisioned at runtime. A registry that cannot be read is a
- * warning rather than a startup failure — config-declared apps still work.
+ * warning rather than a startup failure: config-declared apps still work.
  */
 async function mergeRegisteredApps() {
     try {
@@ -101,6 +141,14 @@ async function mergeRegisteredApps() {
 const initializeServer = async () => {
     try {
         config.validate();
+
+        // A configured city database that cannot be opened stops startup: the
+        // operator asked for it, and running without it would hide that.
+        if (config.geo?.cityDatabase) {
+            geo.city = await openCityLookup(config.geo.cityDatabase);
+            logger.info(`City database loaded (${geo.city.databaseType})`);
+        }
+
         await dbManager.initialize(config.allowed.appId);
 
         // Merge dynamically registered tenants into the live allowlist, so
@@ -108,6 +156,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) {
@@ -123,8 +185,8 @@ const initializeServer = async () => {
     }
 };
 
-// Only when run directly. Requiring this module as a library — to mount
-// createAnalyticsRouter into an existing app — must not validate config,
+// Only when run directly. Requiring this module as a library (to mount
+// createAnalyticsRouter into an existing app) must not validate config,
 // connect to a database, or bind a port as a side effect of the import.
 if (require.main === module) {
     initializeServer();
@@ -147,6 +209,8 @@ const shutdown = async (signal, exitCode = 0) => {
     forceExit.unref();
 
     try {
+        stopRetention();
+        await analyticsRouter?.flushRejections();
         if (httpServer) {
             await new Promise((resolve) => httpServer.close(resolve));
         }
@@ -179,6 +243,9 @@ 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.createDbSessionStore = createDbSessionStore;
 module.exports.DatabaseManager = DatabaseManager;
 module.exports.dbManager = dbManager;
 module.exports.initializeServer = initializeServer;

package/middleware/adminAuth.js

@@ -0,0 +1,244 @@
+/**
+ * Admin UI authentication: password login, server-side sessions, CSRF, and a
+ * fresh password for the actions that cannot be undone.
+ *
+ * The browser holds only an opaque random token in an HttpOnly cookie. Stores
+ * are keyed by that token's SHA-256, so reading a store (the in-memory one
+ * here, or the database table the server uses so a restart signs nobody out)
+ * yields no usable session.
+ *
+ * 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. The CSRF token is an HMAC of the session
+ * token, so it is never stored and cannot be computed without the cookie.
+ */
+
+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');
+}
+
+/** @returns {string} a new session token, 256 random bits */
+function newToken() {
+    return crypto.randomBytes(ADMIN.SESSION_TOKEN_BYTES).toString('base64url');
+}
+
+/**
+ * The CSRF token for a session: an HMAC of its token, so it is the same for
+ * the life of the session, is never stored, and needs the cookie to compute.
+ * @param {string} token
+ * @returns {string}
+ */
+function sessionCsrfToken(token) {
+    return crypto.createHmac('sha256', token).update('viewcounter-admin-csrf').digest('base64url');
+}
+
+/**
+ * The in-memory session store: used by tests and by an embedding app that
+ * passes no store of its own. A restart signs everyone out.
+ *
+ * Every store has the same async interface:
+ *   create()               -> { token, session }
+ *   get(token)             -> session or null; extends the idle window
+ *   destroy(token)         -> whether a session was ended
+ *   confirmPassword(token) -> records that the password was just entered
+ * where a session is { id, passwordAgeMs }.
+ *
+ * @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, createdAt: number, lastSeenAt: number, passwordAt: number}>} */
+    const sessions = new Map();
+
+    const view = (session, at) => ({ id: session.id, passwordAgeMs: at - session.passwordAt });
+
+    return {
+        idleMs,
+        absoluteMs,
+
+        async create() {
+            const at = now();
+            const token = newToken();
+            const session = { id: crypto.randomUUID(), createdAt: at, lastSeenAt: at, passwordAt: 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: view(session, at) };
+        },
+
+        async 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 (at - session.lastSeenAt > idleMs || at - session.createdAt > absoluteMs) {
+                sessions.delete(key);
+                return null;
+            }
+            session.lastSeenAt = at;
+            return view(session, at);
+        },
+
+        async destroy(token) {
+            if (typeof token !== 'string' || token.length === 0) return false;
+            return sessions.delete(hashToken(token));
+        },
+
+        async confirmPassword(token) {
+            const session = typeof token === 'string' ? sessions.get(hashToken(token)) : null;
+            if (session) session.passwordAt = now();
+        },
+
+        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, maxAge = ADMIN.SESSION_ABSOLUTE_TIMEOUT_MS) {
+    return {
+        httpOnly: true,
+        sameSite: 'strict',
+        secure: req.secure,
+        path: req.adminBasePath || ADMIN.PATH_PREFIX,
+        maxAge,
+    };
+}
+
+/** @returns {import('express').RequestHandler} */
+function requireAdminSession(store) {
+    return async (req, res, next) => {
+        try {
+            const token = readToken(req);
+            const session = await 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();
+        } catch (error) {
+            return next(error);
+        }
+    };
+}
+
+/**
+ * For actions that cannot be undone: the password must have been entered in
+ * the last `windowMs`, at sign-in or through POST /reauth. Otherwise the UI is
+ * told to ask for it and retry.
+ * @returns {import('express').RequestHandler}
+ */
+function requireRecentPassword(windowMs = ADMIN.REAUTH_WINDOW_MS) {
+    return (req, res, next) => {
+        if (req.adminSession && req.adminSession.passwordAgeMs <= windowMs) return next();
+        return res.status(HTTP_STATUS.FORBIDDEN).json({ code: ADMIN_ERROR_CODE.REAUTH_REQUIRED });
+    };
+}
+
+/**
+ * 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) && typeof req.adminToken === 'string'
+            && safeEqual(presented, sessionCsrfToken(req.adminToken));
+
+        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,
+    requireRecentPassword,
+    requireCsrf,
+    sessionCsrfToken,
+    newToken,
+    verifyPassword,
+    cookieOptions,
+    expectedOrigin,
+    originAllowed,
+    readToken,
+    hashToken,
+    SAFE_METHODS,
+};