@harshankur/viewcounter 3.1.0 → 3.3.0

package/index.js

@@ -1,16 +1,17 @@
 const express = require('express');
 const cors = require('cors');
 const helmet = require('helmet');
-const rateLimit = require('express-rate-limit');
 
-const { ADMIN, 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, buildPerIpLimiters, 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 });
 
@@ -18,6 +19,9 @@ 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.
@@ -44,38 +48,47 @@ function createApp() {
             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 }));
 
-    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).
+    app.use(buildPerIpLimiters(config.server.rateLimit, (req) => {
+        if (trackingSourceFor(req.path)) router.countRejection(req, REJECTION_REASON.RATE_LIMITED, { detail: 'ip' });
     }));
 
-    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;
 }
@@ -88,7 +101,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 {
@@ -117,6 +130,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
@@ -153,8 +174,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();
@@ -178,6 +199,7 @@ const shutdown = async (signal, exitCode = 0) => {
 
     try {
         stopRetention();
+        await analyticsRouter?.flushRejections();
         if (httpServer) {
             await new Promise((resolve) => httpServer.close(resolve));
         }
@@ -212,6 +234,7 @@ 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

@@ -1,15 +1,17 @@
 /**
- * Admin UI authentication: password login, server-side sessions, and CSRF.
+ * Admin UI authentication: password login, server-side sessions, CSRF, and a
+ * fresh password for the actions that cannot be undone.
  *
- * 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.
+ * 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.
+ * 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');
@@ -27,7 +29,32 @@ 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]
  */
@@ -37,27 +64,19 @@ function createSessionStore({
     maxSessions = ADMIN.MAX_SESSIONS,
     now = Date.now,
 } = {}) {
-    /** @type {Map<string, {id: string, csrfToken: string, createdAt: number, lastSeenAt: number}>} */
+    /** @type {Map<string, {id: string, createdAt: number, lastSeenAt: number, passwordAt: number}>} */
     const sessions = new Map();
 
-    function isExpired(session, at) {
-        return at - session.lastSeenAt > idleMs || at - session.createdAt > absoluteMs;
-    }
+    const view = (session, at) => ({ id: session.id, passwordAgeMs: at - session.passwordAt });
 
     return {
-        /**
-         * Start a session.
-         * @returns {{ token: string, session: {id: string, csrfToken: string, createdAt: number, lastSeenAt: number} }}
-         */
-        create() {
+        idleMs,
+        absoluteMs,
+
+        async 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,
-            };
+            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.
@@ -65,34 +84,34 @@ function createSessionStore({
                 sessions.delete(sessions.keys().next().value);
             }
             sessions.set(hashToken(token), session);
-            return { token, session };
+            return { token, session: view(session, at) };
         },
 
-        /**
-         * Look up a live session and extend its idle window.
-         * @param {string|undefined} token
-         */
-        get(token) {
+        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 (isExpired(session, at)) {
+            if (at - session.lastSeenAt > idleMs || at - session.createdAt > absoluteMs) {
                 sessions.delete(key);
                 return null;
             }
             session.lastSeenAt = at;
-            return session;
+            return view(session, at);
         },
 
-        /** @param {string|undefined} token */
-        destroy(token) {
+        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;
         },
@@ -111,27 +130,44 @@ function readToken(req) {
  * (`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) {
+function cookieOptions(req, maxAge = ADMIN.SESSION_ABSOLUTE_TIMEOUT_MS) {
     return {
         httpOnly: true,
         sameSite: 'strict',
         secure: req.secure,
         path: req.adminBasePath || ADMIN.PATH_PREFIX,
-        maxAge: ADMIN.SESSION_ABSOLUTE_TIMEOUT_MS,
+        maxAge,
     };
 }
 
 /** @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 });
+    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);
         }
-        req.adminSession = session;
-        req.adminToken = token;
-        return next();
+    };
+}
+
+/**
+ * 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 });
     };
 }
 
@@ -172,7 +208,8 @@ function requireCsrf() {
         const session = req.adminSession;
 
         const originOk = originAllowed(req);
-        const tokenOk = Boolean(session) && safeEqual(presented, session.csrfToken);
+        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 });
@@ -193,7 +230,10 @@ function verifyPassword(presented, configured) {
 module.exports = {
     createSessionStore,
     requireAdminSession,
+    requireRecentPassword,
     requireCsrf,
+    sessionCsrfToken,
+    newToken,
     verifyPassword,
     cookieOptions,
     expectedOrigin,

package/middleware/adminValidation.js

@@ -23,9 +23,11 @@ const {
     SORT_ORDER,
     UUID_PATTERN,
     VIEW_LOG_SOURCE,
+    TRACKING_OUTCOME,
     VIEW_STATUS,
 } = require('../constants');
 const ReferrerParser = require('../utils/referrerParser');
+const { FILTER_COLUMNS } = require('../db/analysis');
 const { jsonByteLength } = require('../utils/stringUtils');
 
 const within = (values) => (value) => Object.values(values).includes(value);
@@ -75,6 +77,48 @@ const validateLogin = () => [
         .withMessage('password is required'),
 ];
 
+/** The longest breakdown value a `where` filter can hold: a referrer or page path. */
+const WHERE_VALUE_MAX_LENGTH = Math.max(FIELD_MAX_LENGTH.REFERRER, FIELD_MAX_LENGTH.PAGE_PATH);
+/** Every dimension at its longest, as JSON, with room for escaping. */
+const WHERE_MAX_LENGTH = Object.keys(FILTER_COLUMNS).length * (WHERE_VALUE_MAX_LENGTH + 32) * 2;
+
+/**
+ * Read `where`: breakdown filters as a JSON object of dimension name to
+ * value, with null for rows that have none, such as {"country":"DE"}.
+ * @param {unknown} raw
+ * @returns {{ ok: true, filters: Record<string, string|null> } | { ok: false, error: string }}
+ */
+function readWhere(raw) {
+    if (raw === undefined || raw === '') return { ok: true, filters: {} };
+    if (typeof raw !== 'string' || raw.length > WHERE_MAX_LENGTH) return { ok: false, error: 'where must be a short JSON object' };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return { ok: false, error: 'where must be a JSON object' };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return { ok: false, error: 'where must be a JSON object' };
+    const filters = {};
+    for (const [dim, value] of Object.entries(parsed)) {
+        if (!Object.hasOwn(FILTER_COLUMNS, dim)) return { ok: false, error: 'where names a dimension that cannot be filtered' };
+        if (value !== null && (typeof value !== 'string' || value.length > WHERE_VALUE_MAX_LENGTH)) {
+            return { ok: false, error: `each where value must be null or a string of at most ${WHERE_VALUE_MAX_LENGTH} characters` };
+        }
+        filters[dim] = value;
+    }
+    return { ok: true, filters };
+}
+
+/**
+ * The breakdown filters of a request that passed validation.
+ * @param {unknown} raw
+ * @returns {Record<string, string|null>}
+ */
+function parseWhere(raw) {
+    const result = readWhere(raw);
+    return result.ok ? result.filters : {};
+}
+
 /** Filters shared by a listing and its analysis, for one app or all. */
 const filterQueries = () => [
     query('status').optional().custom(within(VIEW_STATUS)).withMessage('Invalid status'),
@@ -90,6 +134,10 @@ const filterQueries = () => [
         .isString().withMessage('search must be a string')
         .isLength({ max: ADMIN.SEARCH_MAX_LENGTH })
         .withMessage(`search must be at most ${ADMIN.SEARCH_MAX_LENGTH} characters`),
+    query('where')
+        .optional()
+        .custom((value) => readWhere(value).ok)
+        .withMessage((value) => readWhere(value).error),
 ];
 
 /** A listing of one app (with `allowed`) or of every app (without). */
@@ -108,6 +156,15 @@ const validateAnalysis = (allowed) => [
     ...filterQueries(),
 ];
 
+/** The event types of one app (with `allowed`) or of every app, in a status. */
+const validateEventTypes = (allowed) => [
+    ...(allowed ? [adminAppIdParam(allowed)] : []),
+    query('status').optional().custom(within(VIEW_STATUS)).withMessage('Invalid status'),
+];
+
+/** Right now takes no filters, only the app for the per-app route. */
+const validateRealtime = (allowed) => (allowed ? [adminAppIdParam(allowed)] : []);
+
 
 /**
  * Validate one field of an edit and return the column value to store.
@@ -157,7 +214,9 @@ function checkField(field, value, deviceSizes) {
  *
  * Only EDITABLE_FIELDS may appear. A change to `referrer` also re-derives
  * `referrer_domain` and `source_type` with the same parser the write path
- * uses, so the three can never disagree.
+ * uses, and stores the referrer the same way (origin and path only). Whether
+ * it is on the row's own site, and so internal, depends on each row's site,
+ * which the repository applies per row (AdminRepository.updateContent).
  *
  * @param {unknown} changes
  * @param {string[]} deviceSizes
@@ -221,13 +280,16 @@ const validateAdminLogListing = (allowed) => [
     query('action').optional().custom(within(ADMIN_ACTION)).withMessage('Invalid action'),
 ];
 
-const validateViewLogListing = (allowed) => [
+const validateTrackingLogListing = (allowed) => [
     pageQuery(),
     pageSizeQuery(),
     adminAppIdFilter(allowed),
     query('source').optional().custom(within(VIEW_LOG_SOURCE)).withMessage('Invalid source'),
+    query('outcome').optional().custom(within(TRACKING_OUTCOME)).withMessage('Invalid outcome'),
 ];
 
+const validateTrackingSummary = (allowed) => [adminAppIdFilter(allowed)];
+
 /** Admin-shaped validation failure: a stable code plus per-field detail. */
 function handleAdminValidation(req, res, next) {
     const errors = validationResult(req);
@@ -239,14 +301,18 @@ function handleAdminValidation(req, res, next) {
 }
 
 module.exports = {
+    parseWhere,
     validateLogin,
     validateViewListing,
     validateAnalysis,
+    validateEventTypes,
+    validateRealtime,
     validateEdit,
     validateNote,
     validateBatch,
     validateAdminLogListing,
-    validateViewLogListing,
+    validateTrackingLogListing,
+    validateTrackingSummary,
     handleAdminValidation,
     resolveChanges,
     checkField,

package/middleware/auth.js

@@ -3,8 +3,8 @@
  *
  * Two distinct steps, deliberately separate:
  *
- *   requireReadApiKey  — *authentication*: is this a key we issued?
- *   requireAppScope    — *authorization*: may THIS key read THIS app?
+ *   requireReadApiKey   *authentication*: is this a key we issued?
+ *   requireAppScope     *authorization*: may THIS key read THIS app?
  *
  * The second step is what makes the service multi-tenant. Without it a valid
  * key read every tenant's analytics, because the appId allowlist only ever

package/middleware/security.js

@@ -10,7 +10,7 @@ const { HTTP_STATUS } = require('../constants');
  * agent-instructions SECURITY.md §9: `cors()` with no options is never the
  * default. The wildcard mattered more here than the usual "no credentials, so
  * it's harmless" reasoning suggests, because the read endpoints served real
- * data — `*` made them script-readable from any origin, not merely reachable.
+ * data: `*` made them script-readable from any origin, not merely reachable.
  *
  * @param {string[]} allowedOrigins
  * @returns {import('cors').CorsOptions}
@@ -32,6 +32,26 @@ function buildCorsOptions(allowedOrigins) {
     };
 }
 
+/**
+ * Before a browser sends JSON to another site, it asks (a CORS preflight). A
+ * site missing from CORS_ORIGINS is refused there, and the request itself
+ * never arrives, so nothing else could count it. This counts the refusal, for
+ * the tracking-log paths `isTrackingPath` names, so a misconfigured
+ * CORS_ORIGINS shows up in the tracking log. Place it before `cors()`.
+ *
+ * @param {string[]} allowedOrigins as given to buildCorsOptions
+ * @param {{ isTrackingPath: (path: string) => boolean, onRefused: (req: import('express').Request) => void }} hooks
+ * @returns {import('express').RequestHandler}
+ */
+function countRefusedPreflights(allowedOrigins, { isTrackingPath, onRefused }) {
+    const allowlist = new Set(allowedOrigins);
+    return (req, res, next) => {
+        const origin = req.get('origin');
+        if (req.method === 'OPTIONS' && origin && !allowlist.has(origin) && isTrackingPath(req.path)) onRefused(req);
+        next();
+    };
+}
+
 /**
  * Extract the requesting origin, falling back to the referrer's origin.
  * @returns {string|null}
@@ -64,9 +84,11 @@ function requestOrigin(req) {
  * every appId still in that state.
  *
  * @param {{ origins: Record<string, string[]> }} allowed
+ * @param {{ onReject?: (req: import('express').Request, appId: string) => void }} [options]
+ *   told about each refusal, so the tracking log can count it
  * @returns {import('express').RequestHandler}
  */
-function requireRegisteredOrigin(allowed) {
+function requireRegisteredOrigin(allowed, { onReject = () => {} } = {}) {
     const origins = allowed?.origins || {};
 
     return (req, res, next) => {
@@ -82,6 +104,7 @@ function requireRegisteredOrigin(allowed) {
             return next();
         }
 
+        onReject(req, appId);
         return res.status(HTTP_STATUS.FORBIDDEN).json({
             message: 'Request origin is not registered for this appId',
         });
@@ -103,6 +126,7 @@ function noStore(req, res, next) {
 
 module.exports = {
     buildCorsOptions,
+    countRefusedPreflights,
     requireRegisteredOrigin,
     requestOrigin,
     noStore,

package/middleware/validation.js

@@ -5,8 +5,12 @@ const {
     HTTP_STATUS,
     PAYLOAD_LIMITS,
     QUERY_LIMITS,
+    REJECTION_REASON,
+    TRACKING,
     TREND_PERIODS,
+    UUID_PATTERN,
 } = require('../constants');
+const { UTM_PARAMETERS } = require('../utils/visitorContext');
 const { jsonByteLength } = require('../utils/stringUtils');
 const { isValidAppId } = require('../utils/appIdUtils');
 
@@ -60,7 +64,7 @@ const boundedBody = (name, max) =>
  *
  * Deliberately no `.toInt()` sanitizer: under Express 5 `req.query` is a
  * getter-only property, so a sanitizer appears to work but never writes the
- * coerced value back — the handler would still receive a string and bind it
+ * coerced value back: the handler would still receive a string and bind it
  * into `LIMIT ?`, which MySQL rejects. Handlers coerce explicitly instead,
  * after this validator has established the value is a valid integer in range.
  */
@@ -83,6 +87,24 @@ const validateRegisterView = (allowedValues) => [
     boundedQuery('title', FIELD_MAX_LENGTH.PAGE_TITLE),
     boundedQuery('referrer', FIELD_MAX_LENGTH.REFERRER),
     boundedQuery('sessionId', FIELD_MAX_LENGTH.SESSION_ID),
+    ...UTM_PARAMETERS.map((name) => boundedQuery(name, FIELD_MAX_LENGTH.UTM)),
+];
+
+/**
+ * Validate an engagement beacon: how long a recorded view's page was visible
+ * and how far it was scrolled.
+ */
+const validateEngage = (allowedValues) => [
+    body('appId')
+        .notEmpty().withMessage('appId is required')
+        .custom((value) => allowedValues.appId.includes(value)).withMessage('Invalid appId'),
+    body('id')
+        .isString().withMessage('id must be a string')
+        .matches(UUID_PATTERN).withMessage('id must be a view ID'),
+    body('ms')
+        .isInt({ min: 0, max: TRACKING.MAX_ENGAGED_MS }).withMessage(`ms must be an integer between 0 and ${TRACKING.MAX_ENGAGED_MS}`),
+    body('scroll')
+        .isInt({ min: 0, max: 100 }).withMessage('scroll must be an integer between 0 and 100'),
 ];
 
 /**
@@ -165,7 +187,7 @@ const validateSessionRequest = (allowedValues) => [
  * Validate an app-provisioning request.
  *
  * `appId` here becomes a table identifier, so it is checked against the strict
- * pattern rather than an allowlist — there is no allowlist yet, that is the
+ * pattern rather than an allowlist: there is no allowlist yet, that is the
  * point of the call.
  */
 const validateAppRegistration = () => [
@@ -199,14 +221,40 @@ const handleValidationErrors = (req, res, next) => {
     return next();
 };
 
+/**
+ * The same 422 as handleValidationErrors, for a tracking endpoint: the refusal
+ * is also reported, so the tracking log can say why a site's views are not
+ * arriving. An appId that was given but is not allowed is its own reason,
+ * since a misspelled one is the commonest cause; anything else, including a
+ * missing appId, names the first field that failed.
+ *
+ * @param {(req: import('express').Request, reason: string, details: { appId?: string, detail?: string }) => void} onReject
+ * @returns {import('express').RequestHandler}
+ */
+const handleTrackingValidation = (onReject) => (req, res, next) => {
+    const errors = validationResult(req);
+    if (errors.isEmpty()) return next();
+
+    const failed = errors.array();
+    const appIdError = failed.find((error) => error.path === 'appId');
+    if (appIdError && typeof appIdError.value === 'string' && appIdError.value !== '') {
+        onReject(req, REJECTION_REASON.UNKNOWN_APP, { appId: appIdError.value });
+    } else {
+        onReject(req, REJECTION_REASON.INVALID_REQUEST, { detail: (appIdError || failed[0]).path });
+    }
+    return handleValidationErrors(req, res, next);
+};
+
 module.exports = {
     validateAppRegistration,
     validateRegisterView,
     validateEvent,
+    validateEngage,
     validateStatsRequest,
     validateTrendsRequest,
     validateListRequest,
     validateViewsRequest,
     validateSessionRequest,
     handleValidationErrors,
+    handleTrackingValidation,
 };