@harshankur/viewcounter 3.0.1 → 3.2.0

package/routes/admin.js

@@ -0,0 +1,546 @@
+/**
+ * Admin UI and its JSON API.
+ *
+ * Mounted at ADMIN.PATH_PREFIX, and only when ADMIN_PASSWORD is configured:
+ * with no password there is no route, so the surface does not exist rather
+ * than existing behind a check that could be got wrong.
+ *
+ *   /admin/            the UI: static, build-free, no data of its own
+ *   /admin/api/...     session-authenticated JSON API
+ *
+ * Trust model: the static shell is public because it contains nothing; every
+ * API route except /session and /login requires a session, and every
+ * state-changing route also requires the session's CSRF token. Every mutation
+ * is recorded in the admin operation log.
+ */
+
+const path = require('path');
+const express = require('express');
+const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+
+const {
+    ADMIN,
+    ADMIN_ACTION,
+    ADMIN_ERROR_CODE,
+    ADMIN_RANGE,
+    ADMIN_SORT_COLUMNS,
+    ANALYSIS,
+    EDITABLE_FIELDS,
+    FIELD_MAX_LENGTH,
+    HTTP_STATUS,
+    MODIFIED_FILTER,
+    REJECTION_REASON,
+    SORT_ORDER,
+    TRACKING_OUTCOME,
+    VIEW_LOG_SOURCE,
+    VIEW_STATUS,
+} = require('../constants');
+const logger = require('../utils/logger');
+const { ErrorType, getError, logWarning, WarningType } = require('../utils/errorUtils');
+const { noStore } = require('../middleware/security');
+const {
+    createSessionStore,
+    requireAdminSession,
+    requireCsrf,
+    verifyPassword,
+    requireRecentPassword,
+    sessionCsrfToken,
+    cookieOptions,
+    originAllowed,
+    readToken,
+} = require('../middleware/adminAuth');
+const {
+    parseWhere,
+    validateLogin,
+    validateViewListing,
+    validateAnalysis,
+    validateEventTypes,
+    validateRealtime,
+    validateEdit,
+    validateNote,
+    validateBatch,
+    validateAdminLogListing,
+    validateTrackingLogListing,
+    validateTrackingSummary,
+    handleAdminValidation,
+} = require('../middleware/adminValidation');
+const { logContext, withRequestId } = require('./analytics');
+const { attributions } = require('../utils/geoCity');
+const { ACQUISITION_DIMENSIONS } = require('../db/analysis');
+
+/** The UI's static files, shipped in the package. */
+const ADMIN_UI_DIR = path.join(__dirname, '..', 'admin');
+/** Shown in the UI's header and footer, so an admin knows what they are running. */
+const PACKAGE_VERSION = require('../package.json').version;
+
+/**
+ * Content Security Policy for the admin surface. Stricter than helmet's
+ * default: no inline script or style anywhere, no third-party origin at all
+ * (including fonts, which would disclose every admin's IP to the font host),
+ * and no framing.
+ */
+const ADMIN_CSP = {
+    defaultSrc: ["'self'"],
+    scriptSrc: ["'self'"],
+    styleSrc: ["'self'"],
+    imgSrc: ["'self'", 'data:'],
+    fontSrc: ["'self'"],
+    connectSrc: ["'self'"],
+    objectSrc: ["'none'"],
+    baseUri: ["'none'"],
+    formAction: ["'self'"],
+    frameAncestors: ["'none'"],
+};
+
+/** Read a validated integer query parameter, or its default. */
+function intParam(req, name, fallback) {
+    const parsed = Number.parseInt(req.query[name], 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/** The filters a listing and its analysis share, with defaults applied. */
+function filterQuery(req) {
+    return {
+        status: req.query.status || VIEW_STATUS.ACTIVE,
+        modified: req.query.modified || MODIFIED_FILTER.ANY,
+        range: req.query.range || ADMIN_RANGE.ALL,
+        search: req.query.search || '',
+        eventType: req.query.eventType || '',
+        // Validated already; parsed again here since Express 5 recomputes req.query.
+        where: parseWhere(req.query.where),
+    };
+}
+
+/** Stable failure response; the detail stays in the server log. */
+function adminError(req, res, error, operation) {
+    logger.error(`admin ${operation} failed: ${error.message}`, logContext(req));
+    return res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+        code: ADMIN_ERROR_CODE.SERVER_ERROR,
+        requestId: req.id,
+    });
+}
+
+/**
+ * @param {{ config: object, adminRepo: object, logRepo: object,
+ *   sessionStore?: object, isReady?: () => boolean, uiDir?: string,
+ *   geo?: { city: object|null } }} deps
+ *   `geo.city` is the optional city database, whose credit the UI shows
+ * @returns {import('express').Router}
+ */
+function createAdminRouter({
+    config,
+    adminRepo,
+    logRepo,
+    sessionStore = createSessionStore({ idleMs: config.admin.sessionIdleMs, absoluteMs: config.admin.sessionMaxAgeMs }),
+    isReady = () => true,
+    uiDir = ADMIN_UI_DIR,
+    geo = { city: null },
+}) {
+    // The standalone server checks this when it loads its config; an app
+    // embedding the router gets the same floor, not a weaker admin surface.
+    const password = config?.admin?.password;
+    if (typeof password !== 'string' || password.length < ADMIN.MIN_PASSWORD_LENGTH) {
+        throw getError(ErrorType.CONFIG_INVALID_VALUE, {
+            field: 'admin.password',
+            reason: `must be at least ${ADMIN.MIN_PASSWORD_LENGTH} characters`,
+        });
+    }
+
+    const router = express.Router();
+
+    router.use(withRequestId);
+    // Where this router is mounted ('/admin' in the server, anything when
+    // another app embeds it): the session cookie is scoped to it.
+    router.use((req, res, next) => {
+        req.adminBasePath = req.baseUrl || '/';
+        next();
+    });
+    router.use(helmet.contentSecurityPolicy({ useDefaults: false, directives: ADMIN_CSP }));
+    router.use((req, res, next) => {
+        res.set('X-Robots-Tag', 'noindex, nofollow');
+        res.set('Referrer-Policy', 'no-referrer');
+        next();
+    });
+    router.use(rateLimit({
+        windowMs: ADMIN.RATE_LIMIT_WINDOW_MS,
+        limit: ADMIN.RATE_LIMIT_MAX,
+        standardHeaders: true,
+        legacyHeaders: false,
+        handler: (req, res) => res.status(HTTP_STATUS.TOO_MANY_REQUESTS).json({ code: ADMIN_ERROR_CODE.RATE_LIMITED }),
+    }));
+
+    router.use(ADMIN.API_PATH, createAdminApi({ config, adminRepo, logRepo, sessionStore, isReady, geo }));
+
+    // Relative asset URLs in the UI only resolve under a trailing slash.
+    router.get('/', (req, res, next) => {
+        const [pathname, search = ''] = req.originalUrl.split('?');
+        if (pathname.endsWith('/')) return next();
+        return res.redirect(`${pathname}/${search ? `?${search}` : ''}`);
+    });
+    router.use(express.static(uiDir, { index: 'index.html', dotfiles: 'ignore', redirect: false }));
+
+    return router;
+}
+
+/**
+ * The JSON API behind the UI.
+ */
+function createAdminApi({ config, adminRepo, logRepo, sessionStore, isReady, geo }) {
+    const api = express.Router();
+    const allowed = config.allowed;
+
+    api.use(express.json({ limit: ADMIN.MAX_BODY_BYTES }));
+    api.use(noStore);
+    api.use((req, res, next) => {
+        if (isReady()) return next();
+        return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({ code: ADMIN_ERROR_CODE.SERVER_ERROR });
+    });
+
+    const requireSession = requireAdminSession(sessionStore);
+    const csrf = requireCsrf();
+    const authed = [requireSession, csrf];
+
+    /** Everything an admin log entry needs from the request. */
+    const actor = (req) => ({
+        sessionId: req.adminSession?.id ?? null,
+        maskedIp: logContext(req).ip,
+    });
+
+    const record = async (req, action, fields = {}) => {
+        logger.audit(`admin:${action}`, { ...logContext(req), actor: req.adminSession?.id, appId: fields.appId });
+        await logRepo.writeAdminLog({ action, ...actor(req), ...fields });
+    };
+
+    // ---- Session ----------------------------------------------------------
+
+    api.get('/session', async (req, res) => {
+        try {
+            const token = readToken(req);
+            const session = await sessionStore.get(token);
+            if (!session) return res.json({ authenticated: false });
+            return res.json({ authenticated: true, csrfToken: sessionCsrfToken(token) });
+        } catch (error) {
+            return adminError(req, res, error, 'read session');
+        }
+    });
+
+    const loginLimiter = rateLimit({
+        windowMs: ADMIN.LOGIN_RATE_LIMIT_WINDOW_MS,
+        limit: ADMIN.LOGIN_RATE_LIMIT_MAX,
+        // Only a wrong password is a guess. A refused origin or a malformed
+        // body never reaches the password check, so it must not lock the
+        // admin out (a misconfigured proxy would otherwise do exactly that).
+        skipSuccessfulRequests: true,
+        requestWasSuccessful: (req, res) => res.statusCode !== HTTP_STATUS.UNAUTHORIZED,
+        standardHeaders: true,
+        legacyHeaders: false,
+        handler: (req, res) => res.status(HTTP_STATUS.TOO_MANY_REQUESTS).json({ code: ADMIN_ERROR_CODE.TOO_MANY_ATTEMPTS }),
+    });
+
+    api.post('/login', loginLimiter, validateLogin(), handleAdminValidation, async (req, res) => {
+        try {
+            if (!originAllowed(req)) {
+                return res.status(HTTP_STATUS.FORBIDDEN).json({ code: ADMIN_ERROR_CODE.CSRF_REJECTED });
+            }
+
+            if (!verifyPassword(req.body.password, config.admin.password)) {
+                await record(req, ADMIN_ACTION.LOGIN_FAILED);
+                return res.status(HTTP_STATUS.UNAUTHORIZED).json({ code: ADMIN_ERROR_CODE.INVALID_PASSWORD });
+            }
+
+            if (!req.secure && config.server?.isProduction) {
+                logWarning(WarningType.ADMIN_INSECURE_TRANSPORT);
+            }
+
+            // A fresh token on every login; any previous session in this
+            // browser is ended rather than left valid alongside the new one.
+            await sessionStore.destroy(readToken(req));
+            const { token, session } = await sessionStore.create();
+            res.cookie(ADMIN.SESSION_COOKIE, token, cookieOptions(req, sessionStore.absoluteMs));
+
+            req.adminSession = session;
+            await record(req, ADMIN_ACTION.LOGIN_SUCCEEDED);
+            return res.json({ authenticated: true, csrfToken: sessionCsrfToken(token) });
+        } catch (error) {
+            return adminError(req, res, error, 'login');
+        }
+    });
+
+    // The password again, for actions that cannot be undone. Rate limited
+    // with sign-in, since it is the same guess.
+    api.post('/reauth', authed, loginLimiter, validateLogin(), handleAdminValidation, async (req, res) => {
+        try {
+            if (!verifyPassword(req.body.password, config.admin.password)) {
+                await record(req, ADMIN_ACTION.LOGIN_FAILED);
+                return res.status(HTTP_STATUS.UNAUTHORIZED).json({ code: ADMIN_ERROR_CODE.INVALID_PASSWORD });
+            }
+            await sessionStore.confirmPassword(req.adminToken);
+            await record(req, ADMIN_ACTION.PASSWORD_CONFIRMED);
+            return res.status(HTTP_STATUS.NO_CONTENT).end();
+        } catch (error) {
+            return adminError(req, res, error, 'confirm password');
+        }
+    });
+
+    api.post('/logout', authed, async (req, res) => {
+        try {
+            await record(req, ADMIN_ACTION.LOGOUT);
+            await sessionStore.destroy(req.adminToken);
+            res.clearCookie(ADMIN.SESSION_COOKIE, { ...cookieOptions(req), maxAge: undefined });
+            return res.status(HTTP_STATUS.NO_CONTENT).end();
+        } catch (error) {
+            return adminError(req, res, error, 'logout');
+        }
+    });
+
+    // ---- Reference data ---------------------------------------------------
+
+    api.get('/meta', requireSession, (req, res) => {
+        res.json({
+            version: PACKAGE_VERSION,
+            deviceSizes: allowed.deviceSize,
+            editableFields: Object.keys(EDITABLE_FIELDS),
+            sortFields: Object.keys(ADMIN_SORT_COLUMNS),
+            statuses: Object.values(VIEW_STATUS),
+            ranges: Object.values(ADMIN_RANGE),
+            modifiedFilters: Object.values(MODIFIED_FILTER),
+            actions: Object.values(ADMIN_ACTION),
+            sources: Object.values(VIEW_LOG_SOURCE),
+            outcomes: Object.values(TRACKING_OUTCOME),
+            rejectionReasons: Object.values(REJECTION_REASON),
+            maxBatchIds: ADMIN.MAX_BATCH_IDS,
+            pageSizes: ADMIN.PAGE_SIZES,
+            pageSizeDefault: ADMIN.PAGE_SIZE_DEFAULT,
+            searchMaxLength: ADMIN.SEARCH_MAX_LENGTH,
+            trashRetentionDays: config.admin.trashRetentionDays,
+            reauthWindowMs: ADMIN.REAUTH_WINDOW_MS,
+            // "Right now" counts visitors seen within this many minutes.
+            realtimeVisitorMinutes: ANALYSIS.REALTIME_VISITOR_MINUTES,
+            // Breakdowns of how visits arrived, which count page views only.
+            acquisitionDimensions: [...ACQUISITION_DIMENSIONS],
+            // Credits the location data's licences ask for, shown in the UI.
+            attributions: attributions(geo.city),
+            hasCityData: Boolean(geo.city),
+            viewLogRetentionDays: config.admin.viewLogRetentionDays,
+            maxLength: {
+                note: FIELD_MAX_LENGTH.NOTE,
+                pagePath: FIELD_MAX_LENGTH.PAGE_PATH,
+                pageTitle: FIELD_MAX_LENGTH.PAGE_TITLE,
+                referrer: FIELD_MAX_LENGTH.REFERRER,
+                eventType: FIELD_MAX_LENGTH.EVENT_TYPE,
+            },
+        });
+    });
+
+    api.get('/apps', requireSession, async (req, res) => {
+        try {
+            const apps = await adminRepo.summarizeApps(allowed.appId);
+            return res.json({ apps });
+        } catch (error) {
+            return adminError(req, res, error, 'list apps');
+        }
+    });
+
+    // ---- Views ------------------------------------------------------------
+
+    const listingQuery = (req) => ({
+        ...filterQuery(req),
+        sort: req.query.sort || 'timestamp',
+        order: req.query.order || SORT_ORDER.DESC,
+        page: intParam(req, 'page', 1),
+        pageSize: intParam(req, 'pageSize', ADMIN.PAGE_SIZE_DEFAULT),
+    });
+
+    api.get('/apps/:appId/views', requireSession, validateViewListing(allowed), handleAdminValidation,
+        async (req, res) => {
+            try {
+                const query = listingQuery(req);
+                const result = await adminRepo.listViews([req.params.appId], query);
+                return res.json({ appId: req.params.appId, ...query, ...result });
+            } catch (error) {
+                return adminError(req, res, error, 'list views');
+            }
+        });
+
+    /** Every app at once. An app whose table is missing is left out, not fatal. */
+    api.get('/views', requireSession, validateViewListing(), handleAdminValidation, async (req, res) => {
+        try {
+            const query = listingQuery(req);
+            const apps = await adminRepo.existingTables(allowed.appId);
+            const result = await adminRepo.listViews(apps, query);
+            return res.json({ apps, ...query, ...result });
+        } catch (error) {
+            return adminError(req, res, error, 'list all views');
+        }
+    });
+
+    api.get('/apps/:appId/analytics', requireSession, validateAnalysis(allowed), handleAdminValidation,
+        async (req, res) => {
+            try {
+                const query = filterQuery(req);
+                const result = await adminRepo.analyze([req.params.appId], query);
+                return res.json({ apps: [req.params.appId], ...query, ...result });
+            } catch (error) {
+                return adminError(req, res, error, 'analyse views');
+            }
+        });
+
+    api.get('/analytics', requireSession, validateAnalysis(), handleAdminValidation, async (req, res) => {
+        try {
+            const query = filterQuery(req);
+            const apps = await adminRepo.existingTables(allowed.appId);
+            const result = await adminRepo.analyze(apps, query);
+            return res.json({ apps, ...query, ...result });
+        } catch (error) {
+            return adminError(req, res, error, 'analyse all views');
+        }
+    });
+
+    // Every event type the apps hold in a status, whatever other filter is
+    // set, for the event-type filter above a listing.
+    api.get('/apps/:appId/event-types', requireSession, validateEventTypes(allowed), handleAdminValidation,
+        async (req, res) => {
+            try {
+                const status = req.query.status || VIEW_STATUS.ACTIVE;
+                return res.json({ eventTypes: await adminRepo.eventTypes([req.params.appId], status) });
+            } catch (error) {
+                return adminError(req, res, error, 'list event types');
+            }
+        });
+
+    api.get('/event-types', requireSession, validateEventTypes(), handleAdminValidation, async (req, res) => {
+        try {
+            const apps = await adminRepo.existingTables(allowed.appId);
+            const status = req.query.status || VIEW_STATUS.ACTIVE;
+            return res.json({ eventTypes: apps.length ? await adminRepo.eventTypes(apps, status) : [] });
+        } catch (error) {
+            return adminError(req, res, error, 'list all event types');
+        }
+    });
+
+    // Right now: visitors in the last few minutes and views per minute.
+    api.get('/apps/:appId/realtime', requireSession, validateRealtime(allowed), handleAdminValidation, async (req, res) => {
+        try {
+            return res.json({ apps: [req.params.appId], ...await adminRepo.realtime([req.params.appId]) });
+        } catch (error) {
+            return adminError(req, res, error, 'read realtime');
+        }
+    });
+
+    api.get('/realtime', requireSession, async (req, res) => {
+        try {
+            const apps = await adminRepo.existingTables(allowed.appId);
+            return res.json({ apps, ...await adminRepo.realtime(apps) });
+        } catch (error) {
+            return adminError(req, res, error, 'read realtime');
+        }
+    });
+
+    api.patch('/apps/:appId/views', authed, validateEdit(allowed), handleAdminValidation, async (req, res) => {
+        try {
+            const { appId } = req.params;
+            const { columns, fields } = req.resolvedChanges;
+            const changed = await adminRepo.updateContent(appId, req.body.ids, columns);
+            if (changed.length) await record(req, ADMIN_ACTION.VIEWS_EDITED, { appId, targetIds: changed, fields });
+            return res.json({ affected: changed.length, ids: changed });
+        } catch (error) {
+            return adminError(req, res, error, 'edit views');
+        }
+    });
+
+    api.put('/apps/:appId/views/note', authed, validateNote(allowed), handleAdminValidation, async (req, res) => {
+        try {
+            const { appId } = req.params;
+            const note = req.body.note && req.body.note.trim() ? req.body.note : null;
+            const changed = await adminRepo.setNote(appId, req.body.ids, note);
+            const action = note ? ADMIN_ACTION.NOTE_SET : ADMIN_ACTION.NOTE_CLEARED;
+            if (changed.length) await record(req, action, { appId, targetIds: changed });
+            return res.json({ affected: changed.length, ids: changed });
+        } catch (error) {
+            return adminError(req, res, error, 'set note');
+        }
+    });
+
+    /** delete / restore / purge share one shape: IDs in, changed IDs out. */
+    const batchRoute = (suffix, operation, action, guards = []) => {
+        api.post(`/apps/:appId/views/${suffix}`, authed, ...guards, validateBatch(allowed), handleAdminValidation,
+            async (req, res) => {
+                try {
+                    const { appId } = req.params;
+                    const changed = await adminRepo[operation](appId, req.body.ids);
+                    if (changed.length) await record(req, action, { appId, targetIds: changed });
+                    return res.json({ affected: changed.length, ids: changed });
+                } catch (error) {
+                    return adminError(req, res, error, operation);
+                }
+            });
+    };
+
+    batchRoute('delete', 'softDelete', ADMIN_ACTION.VIEWS_DELETED);
+    batchRoute('restore', 'restore', ADMIN_ACTION.VIEWS_RESTORED);
+    // Erasing for good cannot be undone, so it wants the password from the
+    // last few minutes, not just a session that may be weeks old.
+    batchRoute('purge', 'purge', ADMIN_ACTION.VIEWS_PURGED, [requireRecentPassword()]);
+
+    // ---- Logs -------------------------------------------------------------
+
+    api.get('/logs/admin', requireSession, validateAdminLogListing(allowed), handleAdminValidation,
+        async (req, res) => {
+            try {
+                const result = await logRepo.listAdminLog({
+                    page: intParam(req, 'page', 1),
+                    pageSize: intParam(req, 'pageSize', ADMIN.PAGE_SIZE_DEFAULT),
+                    action: req.query.action,
+                    appId: req.query.appId,
+                });
+                return res.json(result);
+            } catch (error) {
+                return adminError(req, res, error, 'list admin log');
+            }
+        });
+
+    // The tracking log: every tracking request and what became of it.
+    api.get('/logs/tracking', requireSession, validateTrackingLogListing(allowed), handleAdminValidation,
+        async (req, res) => {
+            try {
+                const result = await logRepo.listTrackingLog({
+                    page: intParam(req, 'page', 1),
+                    pageSize: intParam(req, 'pageSize', ADMIN.PAGE_SIZE_DEFAULT),
+                    appId: req.query.appId,
+                    source: req.query.source,
+                    outcome: req.query.outcome,
+                });
+                return res.json(result);
+            } catch (error) {
+                return adminError(req, res, error, 'list tracking log');
+            }
+        });
+
+    api.get('/logs/tracking/summary', requireSession, validateTrackingSummary(allowed), handleAdminValidation,
+        async (req, res) => {
+            try {
+                return res.json(await logRepo.trackingSummary({ hours: ADMIN.TRACKING_SUMMARY_HOURS, appId: req.query.appId }));
+            } catch (error) {
+                return adminError(req, res, error, 'summarize tracking log');
+            }
+        });
+
+    api.use((req, res) => res.status(HTTP_STATUS.NOT_FOUND).json({ code: ADMIN_ERROR_CODE.NOT_FOUND }));
+
+    // Malformed or oversized JSON bodies, in the admin error shape.
+    // eslint-disable-next-line no-unused-vars
+    api.use((err, req, res, next) => {
+        const status = err.status || err.statusCode;
+        if (status >= 400 && status < 500) {
+            logger.warn(`admin request rejected: ${err.message}`, logContext(req));
+            return res.status(HTTP_STATUS.BAD_REQUEST).json({ code: ADMIN_ERROR_CODE.VALIDATION_FAILED });
+        }
+        // Anything else is ours (a session store that cannot be read, say).
+        return adminError(req, res, err, 'handle request');
+    });
+
+    return api;
+}
+
+module.exports = { createAdminRouter, ADMIN_UI_DIR, ADMIN_CSP };