@harshankur/viewcounter 3.0.1 → 3.2.0

package/db/LogRepository.js

@@ -0,0 +1,354 @@
+/**
+ * The two service logs: the admin operation log and the view register log.
+ *
+ * Both are append-only from the application's point of view. Nothing here
+ * updates or deletes an entry.
+ */
+
+const crypto = require('crypto');
+
+const {
+    ADMIN,
+    ADMIN_LOG_TABLE,
+    REJECTION_REASON,
+    TRACKING_OUTCOME,
+    TRACKING_REJECTIONS_TABLE,
+    VIEW_LOG_TABLE,
+} = require('../constants');
+const { logWarning, WarningType } = require('../utils/errorUtils');
+
+/**
+ * Columns returned by an admin-log listing. `session_id` identifies which
+ * admin session acted without revealing its token.
+ */
+const ADMIN_LOG_COLUMNS = [
+    'id', 'created_at', 'action', 'session_id', 'masked_ip',
+    'app_id', 'target_count', 'target_ids', 'fields',
+].join(', ');
+
+const VIEW_LOG_COLUMNS = [
+    'id', 'created_at', 'app_id', 'source', 'view_id', 'event_type', 'is_unique', 'hostname',
+].join(', ');
+
+/**
+ * The tracking log is two streams read as one: accepted views, one row each
+ * in the view log, and requests that were not stored, counted per minute.
+ * Both branches select the same columns so they can be merged and paged
+ * together, newest first.
+ */
+const ACCEPTED_BRANCH = `
+    SELECT created_at AS at, id AS entry_id, app_id, source,
+        IF(is_unique = 1, '${TRACKING_OUTCOME.RECORDED}', '${TRACKING_OUTCOME.REPEAT}') AS outcome,
+        CAST(NULL AS CHAR) AS reason, CAST(NULL AS CHAR) AS detail, hostname,
+        view_id, event_type, 1 AS requests
+    FROM \`${VIEW_LOG_TABLE}\``;
+const REJECTED_BRANCH = `
+    SELECT minute AS at, CONCAT_WS('|', minute, source, reason, app_id, detail, hostname) AS entry_id,
+        NULLIF(app_id, '') AS app_id, source,
+        IF(reason = '${REJECTION_REASON.BOT}', '${TRACKING_OUTCOME.BOT}', '${TRACKING_OUTCOME.REJECTED}') AS outcome,
+        reason, NULLIF(detail, '') AS detail, NULLIF(hostname, '') AS hostname,
+        CAST(NULL AS CHAR) AS view_id, CAST(NULL AS CHAR) AS event_type, requests
+    FROM \`${TRACKING_REJECTIONS_TABLE}\``;
+
+/** mysql2 returns JSON columns parsed; tolerate a string from other drivers. */
+function parseJson(value) {
+    if (value === null || value === undefined) return null;
+    if (typeof value !== 'string') return value;
+    try {
+        return JSON.parse(value);
+    } catch {
+        return null;
+    }
+}
+
+class LogRepository {
+    /**
+     * @param {{ pool: object, assertReady: () => void }} db a DatabaseManager
+     */
+    constructor(db) {
+        this.db = db;
+    }
+
+    get pool() {
+        this.db.assertReady();
+        return this.db.pool;
+    }
+
+    /**
+     * Record an admin operation. Never throws: an operation that succeeded must
+     * not be reported as failed because its log line could not be written
+     * (LOGGING.md §4). The failure is surfaced as a warning instead.
+     *
+     * `targetCount` defaults to the number of IDs; the automatic trash purge
+     * passes a count with no IDs, since it erases by age rather than by ID.
+     *
+     * @param {{ action: string, sessionId?: string|null, maskedIp?: string|null,
+     *   appId?: string|null, targetIds?: string[], targetCount?: number,
+     *   fields?: string[] }} entry
+     * @returns {Promise<boolean>} whether the entry was written
+     */
+    async writeAdminLog({
+        action,
+        sessionId = null,
+        maskedIp = null,
+        appId = null,
+        targetIds = [],
+        targetCount = targetIds.length,
+        fields = [],
+    }) {
+        try {
+            await this.pool.query(
+                `INSERT INTO \`${ADMIN_LOG_TABLE}\`
+                    (id, created_at, action, session_id, masked_ip, app_id, target_count, target_ids, fields)
+                 VALUES (?, NOW(3), ?, ?, ?, ?, ?, ?, ?)`,
+                [
+                    crypto.randomUUID(),
+                    action,
+                    sessionId,
+                    maskedIp,
+                    appId,
+                    targetCount,
+                    targetIds.length ? JSON.stringify(targetIds) : null,
+                    fields.length ? JSON.stringify(fields) : null,
+                ]
+            );
+            return true;
+        } catch (cause) {
+            logWarning(WarningType.ADMIN_LOG_WRITE_FAILED, { action, cause: cause.message });
+            return false;
+        }
+    }
+
+    /**
+     * Record one accepted view or event. Never throws, for the same reason as
+     * writeAdminLog: the view itself was stored, so the visitor's request
+     * succeeded.
+     *
+     * @param {{ appId: string, source: string, viewId: string, eventType: string,
+     *   isUnique: boolean }} entry
+     * @returns {Promise<boolean>}
+     */
+    async writeViewLog({ appId, source, viewId, eventType, isUnique, hostname = null }) {
+        try {
+            await this.pool.query(
+                `INSERT INTO \`${VIEW_LOG_TABLE}\`
+                    (id, created_at, app_id, source, view_id, event_type, is_unique, hostname)
+                 VALUES (?, NOW(3), ?, ?, ?, ?, ?, ?)`,
+                [crypto.randomUUID(), appId, source, viewId, eventType, isUnique ? 1 : 0, hostname]
+            );
+            return true;
+        } catch (cause) {
+            logWarning(WarningType.VIEW_LOG_WRITE_FAILED, { appId, cause: cause.message });
+            return false;
+        }
+    }
+
+    /**
+     * Remove view-log entries older than `days`, a batch at a time so no single
+     * statement holds its locks for long. Ordered by the indexed `created_at`,
+     * so each batch reads only what it deletes.
+     *
+     * @param {number} days
+     * @returns {Promise<number>} entries removed
+     */
+    async pruneViewLog(days) {
+        const prune = async (table, column) => {
+            let total = 0;
+            for (;;) {
+                const [result] = await this.pool.query(
+                    `DELETE FROM \`${table}\` WHERE \`${column}\` < DATE_SUB(NOW(3), INTERVAL ? DAY)
+                     ORDER BY \`${column}\` LIMIT ?`,
+                    [days, ADMIN.VIEW_LOG_PRUNE_BATCH_SIZE]
+                );
+                const removed = Number(result?.affectedRows || 0);
+                total += removed;
+                if (removed < ADMIN.VIEW_LOG_PRUNE_BATCH_SIZE) return total;
+            }
+        };
+        return await prune(VIEW_LOG_TABLE, 'created_at') + await prune(TRACKING_REJECTIONS_TABLE, 'minute');
+    }
+
+    /**
+     * Add counted rejections, merging into any count already stored for the
+     * same minute and key. Never throws: losing a count must not fail the
+     * request that produced it, or the flush that carries many.
+     *
+     * @param {{ minute: Date, source: string, reason: string, appId?: string,
+     *   detail?: string, hostname?: string, requests: number }[]} rows
+     * @returns {Promise<boolean>}
+     */
+    async recordRejections(rows) {
+        if (rows.length === 0) return true;
+        try {
+            await this.pool.query(
+                `INSERT INTO \`${TRACKING_REJECTIONS_TABLE}\`
+                    (minute, source, reason, app_id, detail, hostname, requests)
+                 VALUES ${rows.map(() => '(FROM_UNIXTIME(?), ?, ?, ?, ?, ?, ?)').join(', ')}
+                 ON DUPLICATE KEY UPDATE requests = requests + VALUES(requests)`,
+                // The minute as seconds since the epoch, placed in the database's
+                // own time zone like every NOW() it is compared with, whatever
+                // zone this process runs in.
+                rows.flatMap((row) => [
+                    Math.floor(new Date(row.minute).getTime() / 1000), row.source, row.reason,
+                    row.appId || '', row.detail || '', row.hostname || '', row.requests,
+                ])
+            );
+            return true;
+        } catch (cause) {
+            logWarning(WarningType.TRACKING_LOG_WRITE_FAILED, { cause: cause.message });
+            return false;
+        }
+    }
+
+    /**
+     * @param {{ page: number, pageSize: number, action?: string, appId?: string }} query
+     * @returns {Promise<{ entries: object[], total: number }>}
+     */
+    async listAdminLog({ page, pageSize, action, appId }) {
+        const where = [];
+        const params = [];
+        if (action) { where.push('action = ?'); params.push(action); }
+        if (appId) { where.push('app_id = ?'); params.push(appId); }
+        const clause = where.length ? `WHERE ${where.join(' AND ')}` : '';
+
+        const [rows] = await this.pool.query(
+            `SELECT ${ADMIN_LOG_COLUMNS} FROM \`${ADMIN_LOG_TABLE}\` ${clause}
+             ORDER BY created_at DESC, id ASC LIMIT ? OFFSET ?`,
+            [...params, pageSize, (page - 1) * pageSize]
+        );
+        const [count] = await this.pool.query(
+            `SELECT COUNT(*) AS count FROM \`${ADMIN_LOG_TABLE}\` ${clause}`,
+            params
+        );
+
+        return {
+            entries: rows.map((row) => ({
+                id: row.id,
+                createdAt: row.created_at,
+                action: row.action,
+                sessionId: row.session_id,
+                maskedIp: row.masked_ip,
+                appId: row.app_id,
+                targetCount: row.target_count,
+                targetIds: parseJson(row.target_ids) || [],
+                fields: parseJson(row.fields) || [],
+            })),
+            total: Number(count[0]?.count || 0),
+        };
+    }
+
+    /**
+     * The tracking log: every tracking request and what became of it, newest
+     * first. Accepted views are listed one by one; bots and rejections as one
+     * entry per minute and key, with how many requests it stands for.
+     *
+     * @param {{ page: number, pageSize: number, appId?: string, source?: string, outcome?: string }} query
+     * @returns {Promise<{ entries: object[], total: number }>}
+     */
+    async listTrackingLog({ page, pageSize, appId, source, outcome }) {
+        const accepted = { where: [], params: [] };
+        const rejected = { where: [], params: [] };
+        for (const branch of [accepted, rejected]) {
+            if (appId) { branch.where.push('app_id = ?'); branch.params.push(appId); }
+            if (source) { branch.where.push('source = ?'); branch.params.push(source); }
+        }
+        if (outcome === TRACKING_OUTCOME.RECORDED) accepted.where.push('is_unique = 1');
+        if (outcome === TRACKING_OUTCOME.REPEAT) accepted.where.push('is_unique = 0');
+        if (outcome === TRACKING_OUTCOME.BOT) { rejected.where.push('reason = ?'); rejected.params.push(REJECTION_REASON.BOT); }
+        if (outcome === TRACKING_OUTCOME.REJECTED) { rejected.where.push('reason <> ?'); rejected.params.push(REJECTION_REASON.BOT); }
+
+        const wantAccepted = !outcome || outcome === TRACKING_OUTCOME.RECORDED || outcome === TRACKING_OUTCOME.REPEAT;
+        const wantRejected = !outcome || outcome === TRACKING_OUTCOME.BOT || outcome === TRACKING_OUTCOME.REJECTED;
+        const clause = (branch) => (branch.where.length ? ` WHERE ${branch.where.join(' AND ')}` : '');
+
+        // Each table gives at most the rows the page could need, in the same
+        // order as the whole, so a page never sorts either table in full; the
+        // view log reads its created_at index backwards to do it.
+        const offset = (page - 1) * pageSize;
+        const ORDER = 'ORDER BY at DESC, entry_id DESC';
+        const branches = [];
+        const params = [];
+        for (const [want, branch, sql] of [[wantAccepted, accepted, ACCEPTED_BRANCH], [wantRejected, rejected, REJECTED_BRANCH]]) {
+            if (!want) continue;
+            branches.push(`(${sql}${clause(branch)} ${ORDER} LIMIT ?)`);
+            params.push(...branch.params, offset + pageSize);
+        }
+
+        const [rows] = await this.pool.query(
+            `SELECT * FROM (${branches.join(' UNION ALL ')}) AS entries
+             ${ORDER} LIMIT ? OFFSET ?`,
+            [...params, pageSize, offset]
+        );
+
+        let total = 0;
+        if (wantAccepted) {
+            const [count] = await this.pool.query(
+                `SELECT COUNT(*) AS count FROM \`${VIEW_LOG_TABLE}\`${clause(accepted)}`, accepted.params);
+            total += Number(count[0]?.count || 0);
+        }
+        if (wantRejected) {
+            const [count] = await this.pool.query(
+                `SELECT COUNT(*) AS count FROM \`${TRACKING_REJECTIONS_TABLE}\`${clause(rejected)}`, rejected.params);
+            total += Number(count[0]?.count || 0);
+        }
+
+        return {
+            entries: rows.map((row) => ({
+                id: row.entry_id,
+                at: row.at,
+                appId: row.app_id ?? null,
+                source: row.source,
+                outcome: row.outcome,
+                reason: row.reason ?? null,
+                detail: row.detail ?? null,
+                hostname: row.hostname ?? null,
+                viewId: row.view_id ?? null,
+                eventType: row.event_type ?? null,
+                requests: Number(row.requests),
+            })),
+            total,
+        };
+    }
+
+    /**
+     * How the last `hours` of tracking requests turned out: requests per
+     * outcome, and per reason for the ones not stored.
+     *
+     * @param {{ hours: number, appId?: string }} query
+     * @returns {Promise<{ hours: number, outcomes: Record<string, number>, reasons: Record<string, number> }>}
+     */
+    async trackingSummary({ hours, appId }) {
+        const appClause = appId ? ' AND app_id = ?' : '';
+        const appParams = appId ? [appId] : [];
+        const [acceptedRows] = await this.pool.query(
+            `SELECT COALESCE(SUM(is_unique = 1), 0) AS recorded, COALESCE(SUM(is_unique = 0), 0) AS repeats
+             FROM \`${VIEW_LOG_TABLE}\` WHERE created_at >= DATE_SUB(NOW(3), INTERVAL ? HOUR)${appClause}`,
+            [hours, ...appParams]
+        );
+        const [reasonRows] = await this.pool.query(
+            `SELECT reason, SUM(requests) AS requests FROM \`${TRACKING_REJECTIONS_TABLE}\`
+             WHERE minute >= DATE_SUB(NOW(), INTERVAL ? HOUR)${appClause}
+             GROUP BY reason ORDER BY reason`,
+            [hours, ...appParams]
+        );
+
+        const reasons = Object.fromEntries(reasonRows.map((row) => [row.reason, Number(row.requests)]));
+        const bots = reasons[REJECTION_REASON.BOT] || 0;
+        const rejectedTotal = Object.values(reasons).reduce((sum, value) => sum + value, 0) - bots;
+        return {
+            hours,
+            outcomes: {
+                [TRACKING_OUTCOME.RECORDED]: Number(acceptedRows[0]?.recorded || 0),
+                [TRACKING_OUTCOME.REPEAT]: Number(acceptedRows[0]?.repeats || 0),
+                [TRACKING_OUTCOME.BOT]: bots,
+                [TRACKING_OUTCOME.REJECTED]: rejectedTotal,
+            },
+            reasons,
+        };
+    }
+}
+
+module.exports = LogRepository;
+module.exports.ADMIN_LOG_COLUMNS = ADMIN_LOG_COLUMNS;
+module.exports.VIEW_LOG_COLUMNS = VIEW_LOG_COLUMNS;
+module.exports.parseJson = parseJson;

package/db/adminSchema.js

@@ -0,0 +1,329 @@
+/**
+ * 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,
+    ADMIN_SESSIONS_TABLE,
+    DATABASE,
+    FIELD_MAX_LENGTH,
+    TRACKING_REJECTIONS_TABLE,
+    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' },
+];
+
+/**
+ * Columns 3.2 added for richer, still identifier-free analysis: which of the
+ * app's sites and which language, the campaign tags of the landing URL, an
+ * optional region and city (only with a city database configured), and how
+ * long the page was visible and how far it was scrolled.
+ */
+const TRACKING_COLUMNS = [
+    { name: 'hostname', ddl: `VARCHAR(${FIELD_MAX_LENGTH.HOSTNAME}) DEFAULT NULL` },
+    { name: 'language', ddl: `VARCHAR(${FIELD_MAX_LENGTH.LANGUAGE}) DEFAULT NULL` },
+    { name: 'utm_source', ddl: `VARCHAR(${FIELD_MAX_LENGTH.UTM}) DEFAULT NULL` },
+    { name: 'utm_medium', ddl: `VARCHAR(${FIELD_MAX_LENGTH.UTM}) DEFAULT NULL` },
+    { name: 'utm_campaign', ddl: `VARCHAR(${FIELD_MAX_LENGTH.UTM}) DEFAULT NULL` },
+    { name: 'utm_term', ddl: `VARCHAR(${FIELD_MAX_LENGTH.UTM}) DEFAULT NULL` },
+    { name: 'utm_content', ddl: `VARCHAR(${FIELD_MAX_LENGTH.UTM}) DEFAULT NULL` },
+    { name: 'region', ddl: `VARCHAR(${FIELD_MAX_LENGTH.REGION}) DEFAULT NULL` },
+    { name: 'city', ddl: `VARCHAR(${FIELD_MAX_LENGTH.CITY}) DEFAULT NULL` },
+    { name: 'engaged_ms', ddl: 'INT UNSIGNED DEFAULT NULL' },
+    { name: 'scroll_depth', ddl: 'TINYINT UNSIGNED 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,
+        \`hostname\` VARCHAR(${FIELD_MAX_LENGTH.HOSTNAME}) DEFAULT NULL,
+        INDEX \`idx_created_at\` (\`created_at\`),
+        INDEX \`idx_app_created\` (\`app_id\`, \`created_at\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+`;
+
+/**
+ * Admin sign-ins, so a restart or deploy does not sign anyone out.
+ *
+ * Holds only the SHA-256 of each session's token (the browser has the token
+ * itself, in an HttpOnly cookie), so reading this table yields no usable
+ * session. The CSRF token is derived from the session token, not stored.
+ * `password_at` is when the password was last entered, for actions that ask
+ * for it again.
+ */
+const ADMIN_SESSIONS_DDL = `
+    CREATE TABLE IF NOT EXISTS \`${ADMIN_SESSIONS_TABLE}\` (
+        \`token_hash\` CHAR(64) PRIMARY KEY,
+        \`id\` CHAR(${FIELD_MAX_LENGTH.UUID}) NOT NULL,
+        \`created_at\` DATETIME(3) NOT NULL,
+        \`last_seen_at\` DATETIME(3) NOT NULL,
+        \`password_at\` DATETIME(3) NOT NULL,
+        INDEX \`idx_last_seen_at\` (\`last_seen_at\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+`;
+
+/** Columns the view log gained after it first shipped, for tables created by 3.1. */
+const VIEW_LOG_ADDED_COLUMNS = [
+    { name: 'hostname', ddl: `VARCHAR(${FIELD_MAX_LENGTH.HOSTNAME}) DEFAULT NULL` },
+];
+
+/**
+ * Tracking requests that were not stored: bots and rejections, with why.
+ *
+ * Counted per minute rather than kept one by one, so a flood of bad requests
+ * adds to a counter instead of a row each, and nothing about the requester
+ * (no IP, hash, or User-Agent) is kept. The key columns use '' rather than
+ * NULL for "none", because NULL never matches itself in a unique key and every
+ * NULL would start a new row.
+ */
+const TRACKING_REJECTIONS_DDL = `
+    CREATE TABLE IF NOT EXISTS \`${TRACKING_REJECTIONS_TABLE}\` (
+        \`minute\` DATETIME NOT NULL,
+        \`source\` VARCHAR(16) NOT NULL,
+        \`reason\` VARCHAR(32) NOT NULL,
+        \`app_id\` VARCHAR(64) NOT NULL DEFAULT '',
+        \`detail\` VARCHAR(64) NOT NULL DEFAULT '',
+        \`hostname\` VARCHAR(${FIELD_MAX_LENGTH.HOSTNAME}) NOT NULL DEFAULT '',
+        \`requests\` INT UNSIGNED NOT NULL,
+        PRIMARY KEY (\`minute\`, \`source\`, \`reason\`, \`app_id\`, \`detail\`, \`hostname\`),
+        INDEX \`idx_app_minute\` (\`app_id\`, \`minute\`)
+    ) 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',
+    ...TRACKING_COLUMNS.map((column) => `\`${column.name}\` ${column.ddl}`),
+];
+
+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, ...TRACKING_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 service's own tables: the logs and the admin sessions. 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);
+    await pool.query(TRACKING_REJECTIONS_DDL);
+    await pool.query(ADMIN_SESSIONS_DDL);
+
+    const viewLogColumns = await readColumns(pool, VIEW_LOG_TABLE);
+    for (const column of VIEW_LOG_ADDED_COLUMNS) {
+        if (!viewLogColumns.has(column.name)) {
+            await pool.query(`ALTER TABLE \`${VIEW_LOG_TABLE}\` ADD COLUMN \`${column.name}\` ${column.ddl}`);
+        }
+    }
+}
+
+module.exports = {
+    ADMIN_COLUMNS,
+    TRACKING_COLUMNS,
+    ADMIN_INDEXES,
+    ADMIN_LOG_DDL,
+    VIEW_LOG_DDL,
+    VIEW_LOG_ADDED_COLUMNS,
+    TRACKING_REJECTIONS_DDL,
+    ADMIN_SESSIONS_DDL,
+    NEW_TABLE_ADMIN_COLUMNS,
+    NEW_TABLE_ADMIN_INDEXES,
+    backfillPublicIds,
+    ensureLogTables,
+    migrateAppTable,
+};