@harshankur/viewcounter 3.0.0

package/routes/analytics.js

@@ -0,0 +1,456 @@
+const crypto = require('crypto');
+const express = require('express');
+const rateLimit = require('express-rate-limit');
+const geoip = require('geoip-country');
+
+const {
+    EVENT_TYPE,
+    HTTP_STATUS,
+    QUERY_LIMITS,
+    TREND_PERIOD,
+} = require('../constants');
+const UserAgentParser = require('../utils/userAgentParser');
+const ReferrerParser = require('../utils/referrerParser');
+const PrivacyUtils = require('../utils/privacyUtils');
+const logger = require('../utils/logger');
+const { getClientIp, isValidIP, normalizeIp } = require('../utils/ipUtils');
+const { requireReadApiKey, requireAppScope, requireAdminApiKey, appsInScope } = require('../middleware/auth');
+const { requireRegisteredOrigin, noStore } = require('../middleware/security');
+const {
+    validateAppRegistration,
+    validateRegisterView,
+    validateEvent,
+    validateStatsRequest,
+    validateTrendsRequest,
+    validateListRequest,
+    validateViewsRequest,
+    validateSessionRequest,
+    handleValidationErrors,
+} = require('../middleware/validation');
+
+/**
+ * Analytics routes.
+ *
+ * Exported as a factory returning an Express Router so the same code can run
+ * as a standalone server (index.js) or be mounted into an existing Express
+ * application as middleware.
+ *
+ * Trust model:
+ *  - WRITE endpoints (/registerView, /event) are public, because the whole
+ *    point is that a browser on someone else's site can reach them. They are
+ *    bounded by validation, rate limiting, and per-appId origin binding.
+ *  - READ endpoints are authenticated. They return another party's analytics
+ *    and must never have been open.
+ */
+
+/**
+ * Read an integer query parameter.
+ *
+ * Validation has already rejected anything non-integer or out of range with a
+ * 422, so this only ever coerces a known-good value or applies the default for
+ * an absent one. Done here rather than with an express-validator `.toInt()`
+ * sanitizer because Express 5 exposes `req.query` as a getter-only property,
+ * so sanitizers cannot write the coerced value back.
+ *
+ * @param {import('express').Request} req
+ * @param {string} name
+ * @param {number} fallback
+ * @returns {number}
+ */
+function intQuery(req, name, fallback) {
+    const raw = req.query[name];
+    if (raw === undefined || raw === '') return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/**
+ * Per-app write limiter.
+ *
+ * Sits alongside the per-IP limiter rather than replacing it. The per-IP limit
+ * stops one abusive visitor; this stops one *tenant* consuming the budget every
+ * other tenant on the instance depends on, which is the failure mode that
+ * matters once the apps belong to different people.
+ *
+ * Keyed on appId only — never on IP — so it is unaffected by how the client's
+ * address is derived, and cannot be rotated away by a caller changing address.
+ *
+ * @param {{ perAppMax: number, windowMs: number }} rateLimitConfig
+ * @returns {import('express').RequestHandler}
+ */
+function buildPerAppLimiter(rateLimitConfig) {
+    const { perAppMax, windowMs } = rateLimitConfig || {};
+    // Zero disables it, for single-tenant deployments where the per-IP limit
+    // is the only bound that means anything.
+    if (!perAppMax || perAppMax <= 0) return (req, res, next) => next();
+
+    return rateLimit({
+        windowMs,
+        limit: perAppMax,
+        standardHeaders: true,
+        legacyHeaders: false,
+        message: { message: 'This app has exceeded its request budget, please try again later.' },
+        // A request with no appId lands in one shared bucket rather than
+        // falling back to the IP, which would reintroduce the address-rotation
+        // bypass this limiter exists to be immune to.
+        keyGenerator: (req) => String(req.query?.appId || req.body?.appId || '__unattributed__'),
+        validate: { keyGeneratorIpFallback: false },
+    });
+}
+
+/**
+ * Attach a request id used for correlating a client-visible error with the
+ * server-side log line that has the real detail.
+ */
+function withRequestId(req, res, next) {
+    req.id = crypto.randomUUID();
+    res.set('X-Request-Id', req.id);
+    next();
+}
+
+/**
+ * Build the correlation context for a log line.
+ *
+ * Logs the MASKED address, never the raw one. `logRequest` previously wrote
+ * the unmasked IP on every view, event, and error — and on any normal
+ * deployment stdout is persisted to disk, so the raw addresses the privacy
+ * design goes to lengths to keep out of the database were being written beside
+ * it anyway.
+ */
+function logContext(req) {
+    const ip = getClientIp(req);
+    return { ip: ip ? PrivacyUtils.maskIP(normalizeIp(ip)) : '-', requestId: req.id };
+}
+
+/**
+ * Report a handler failure.
+ *
+ * The client gets a stable message plus the request id; the detail goes to the
+ * server log only. Previously the raw database error text was returned to the
+ * caller whenever NODE_ENV was not exactly "development" — which was the
+ * default, and which the setup wizard wrote into .env.
+ */
+function handleRouteError(req, res, error, operation) {
+    logger.error(`${operation} failed: ${error.message}`, logContext(req));
+    return res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+        message: `Failed to ${operation}`,
+        requestId: req.id,
+    });
+}
+
+/**
+ * @param {{ config: object, dbManager: object, isReady: () => boolean }} deps
+ * @returns {import('express').Router}
+ */
+function createAnalyticsRouter({ config, dbManager, isReady = () => true }) {
+    const router = express.Router();
+    // Authentication and authorization are separate steps: `requireKey` proves
+    // the caller holds a key we issued, `requireScope` proves that key is
+    // entitled to the specific appId in the path. Read routes need both.
+    const requireKey = requireReadApiKey(config.auth);
+    const requireScope = requireAppScope();
+    const requireAdmin = requireAdminApiKey(config.auth);
+    const requireOrigin = requireRegisteredOrigin(config.allowed);
+    const limitPerApp = buildPerAppLimiter(config.server?.rateLimit);
+
+    router.use(withRequestId);
+
+    /**
+     * Health check. Public, and deliberately reveals nothing but liveness.
+     */
+    router.get('/health', noStore, async (req, res) => {
+        const dbHealth = await dbManager.healthCheck();
+
+        if (!isReady() || !dbHealth.healthy) {
+            return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({ status: 'unhealthy' });
+        }
+
+        return res.json({ status: 'healthy', uptime: process.uptime() });
+    });
+
+    /**
+     * Register a page view.
+     */
+    router.get('/registerView',
+        limitPerApp,
+        requireOrigin,
+        validateRegisterView(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const { appId, deviceSize, page, title, referrer, sessionId } = req.query;
+                const ip = normalizeIp(getClientIp(req));
+
+                if (!isValidIP(ip)) {
+                    logger.warn(`Rejected request with unparseable client IP`, logContext(req));
+                    return res.status(HTTP_STATUS.BAD_REQUEST).json({ message: 'Invalid IP address format' });
+                }
+
+                const ipInfo = geoip.lookup(ip);
+                const userAgent = req.get('user-agent') || '';
+                const uaData = UserAgentParser.parse(userAgent);
+
+                const referrerHeader = referrer || req.get('referer') || req.get('referrer');
+                const referrerData = ReferrerParser.parse(referrerHeader);
+
+                const result = await dbManager.registerEvent(appId, {
+                    ip,
+                    country: ipInfo?.country || null,
+                    deviceSize,
+                    pagePath: page,
+                    pageTitle: title,
+                    referrer: referrerData.referrer,
+                    referrerDomain: referrerData.referrerDomain,
+                    sourceType: referrerData.sourceType,
+                    browser: uaData.browser,
+                    browserVersion: uaData.browserVersion,
+                    os: uaData.os,
+                    osVersion: uaData.osVersion,
+                    deviceType: uaData.deviceType,
+                    sessionId,
+                    eventType: EVENT_TYPE.PAGEVIEW,
+                    userAgent,
+                    visitorSecret: config.privacy.visitorSecret,
+                    uniqueWindowHours: config.server.uniqueVisitorWindowHours,
+                });
+
+                logger.audit('registerView', { ...logContext(req), appId, duplicate: result.duplicate });
+
+                if (result.duplicate) {
+                    return res.status(HTTP_STATUS.OK).json({
+                        message: 'View already registered recently',
+                        duplicate: true,
+                    });
+                }
+
+                return res.status(HTTP_STATUS.OK).json({ message: 'Success!', duplicate: false });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'register view');
+            }
+        }
+    );
+
+    /**
+     * Track a custom event.
+     */
+    router.post('/event',
+        limitPerApp,
+        requireOrigin,
+        validateEvent(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const { appId, eventType, eventData, sessionId, page, title } = req.body;
+                const ip = normalizeIp(getClientIp(req));
+
+                if (!isValidIP(ip)) {
+                    return res.status(HTTP_STATUS.BAD_REQUEST).json({ message: 'Invalid IP address format' });
+                }
+
+                const ipInfo = geoip.lookup(ip);
+                const userAgent = req.get('user-agent') || '';
+                const uaData = UserAgentParser.parse(userAgent);
+
+                const result = await dbManager.registerEvent(appId, {
+                    ip,
+                    country: ipInfo?.country || null,
+                    deviceSize: UserAgentParser.getDeviceSize(userAgent),
+                    pagePath: page,
+                    pageTitle: title,
+                    browser: uaData.browser,
+                    browserVersion: uaData.browserVersion,
+                    os: uaData.os,
+                    osVersion: uaData.osVersion,
+                    deviceType: uaData.deviceType,
+                    sessionId,
+                    eventType,
+                    eventData,
+                    userAgent,
+                    visitorSecret: config.privacy.visitorSecret,
+                    // Custom events are never deduplicated.
+                    uniqueWindowHours: 0,
+                });
+
+                logger.audit('trackEvent', { ...logContext(req), appId, eventType });
+
+                return res.status(HTTP_STATUS.OK).json({
+                    message: 'Event tracked successfully',
+                    insertId: result.insertId,
+                });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'track event');
+            }
+        }
+    );
+
+    // ---- Read API. Everything below requires a valid key. -------------------
+
+    router.use(noStore);
+
+    router.get('/stats/:appId',
+        requireKey,
+        requireScope,
+        validateStatsRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const stats = await dbManager.getStats(req.params.appId);
+                return res.json({ appId: req.params.appId, stats });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch statistics');
+            }
+        }
+    );
+
+    router.get('/trends/:appId',
+        requireKey,
+        requireScope,
+        validateTrendsRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const period = req.query.period || TREND_PERIOD.DAILY;
+                const days = intQuery(req, 'days', QUERY_LIMITS.TREND_DAYS_DEFAULT);
+                const trends = await dbManager.getTrends(req.params.appId, period, days);
+                return res.json({ appId: req.params.appId, period, days, trends });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch trends');
+            }
+        }
+    );
+
+    router.get('/referrers/:appId',
+        requireKey,
+        requireScope,
+        validateListRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const limit = intQuery(req, 'limit', QUERY_LIMITS.LIST_LIMIT_DEFAULT);
+                const stats = await dbManager.getReferrerStats(req.params.appId, limit);
+                return res.json({ appId: req.params.appId, ...stats });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch referrer statistics');
+            }
+        }
+    );
+
+    router.get('/browsers/:appId',
+        requireKey,
+        requireScope,
+        validateStatsRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const stats = await dbManager.getBrowserStats(req.params.appId);
+                return res.json({ appId: req.params.appId, ...stats });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch browser statistics');
+            }
+        }
+    );
+
+    router.get('/pages/:appId',
+        requireKey,
+        requireScope,
+        validateListRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const limit = intQuery(req, 'limit', QUERY_LIMITS.LIST_LIMIT_DEFAULT);
+                const pages = await dbManager.getPageStats(req.params.appId, limit);
+                return res.json({ appId: req.params.appId, pages });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch page statistics');
+            }
+        }
+    );
+
+    router.get('/sessions/:appId/:sessionId',
+        requireKey,
+        requireScope,
+        validateSessionRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const { appId, sessionId } = req.params;
+                const events = await dbManager.getSessionDetails(appId, sessionId);
+                return res.json({ appId, sessionId, events, count: events.length });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch session details');
+            }
+        }
+    );
+
+    router.get('/views/:appId',
+        requireKey,
+        requireScope,
+        validateViewsRequest(config.allowed),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const limit = intQuery(req, 'limit', QUERY_LIMITS.VIEWS_LIMIT_DEFAULT);
+                const offset = intQuery(req, 'offset', QUERY_LIMITS.OFFSET_DEFAULT);
+                const result = await dbManager.getViews(req.params.appId, limit, offset);
+                return res.json({ appId: req.params.appId, ...result });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'fetch views');
+            }
+        }
+    );
+
+    /**
+     * List apps visible to the presented key.
+     *
+     * Filtered by scope, not just authenticated: returning the full list to a
+     * tenant-scoped key would disclose every other tenant's existence, which is
+     * the same enumeration problem this endpoint had when it was public.
+     */
+    router.get('/apps', requireKey, (req, res) => {
+        const apps = appsInScope(req.auth.scope, config.allowed.appId);
+        res.json({ apps, count: apps.length });
+    });
+
+    /**
+     * Provision a new app. Admin tier only.
+     *
+     * Creates the app's table and records it in the registry, then adds it to
+     * the live allowlist so it accepts traffic immediately — no restart. The
+     * appId becomes a table identifier, so it is validated against a strict
+     * pattern before it reaches any DDL.
+     */
+    router.post('/apps',
+        requireAdmin,
+        validateAppRegistration(),
+        handleValidationErrors,
+        async (req, res) => {
+            try {
+                const { appId, origins = [] } = req.body;
+                const result = await dbManager.registerApp(appId, origins);
+
+                // Reassigning (not mutating) is fine: the validators read
+                // `config.allowed.appId` per request via a custom validator.
+                if (!config.allowed.appId.includes(appId)) {
+                    config.allowed.appId = [...config.allowed.appId, appId];
+                }
+                if (origins.length) {
+                    config.allowed.origins[appId] = origins;
+                }
+
+                logger.audit('registerApp', { ...logContext(req), appId, created: result.created });
+
+                return res.status(HTTP_STATUS.OK).json({
+                    appId,
+                    created: result.created,
+                    message: result.created ? 'App registered' : 'App already registered',
+                });
+            } catch (error) {
+                return handleRouteError(req, res, error, 'register app');
+            }
+        }
+    );
+
+    return router;
+}
+
+module.exports = { createAnalyticsRouter, handleRouteError, logContext, withRequestId };

package/scripts/setup.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+const readline = require('readline');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { CONFIG_FILE_MODE, PRIVACY } = require('../constants');
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+});
+
+const question = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+const dbInfoPath = path.join(__dirname, '..', 'dbInfo.json');
+const allowedPath = path.join(__dirname, '..', 'allowed.json');
+const envPath = path.join(__dirname, '..', '.env');
+
+async function setup() {
+    console.log('\n🚀 View Counter Backend Setup\n');
+
+    // Check for existing configuration
+    const hasDbInfo = fs.existsSync(dbInfoPath);
+    const hasAllowed = fs.existsSync(allowedPath);
+    const hasEnv = fs.existsSync(envPath);
+
+    if (hasDbInfo || hasAllowed || hasEnv) {
+        console.log('⚠️  Existing configuration detected:');
+        if (hasDbInfo) console.log('   - dbInfo.json');
+        if (hasAllowed) console.log('   - allowed.json');
+        if (hasEnv) console.log('   - .env');
+        console.log('');
+
+        const action = await question('What would you like to do?\n  1) Overwrite existing config\n  2) Keep existing and exit\n  3) Edit specific files\nChoice (1-3): ');
+
+        if (action === '2') {
+            console.log('✓ Keeping existing configuration. Exiting...');
+            rl.close();
+            return;
+        }
+
+        if (action === '3') {
+            await editSpecificFiles(hasDbInfo, hasAllowed, hasEnv);
+            rl.close();
+            return;
+        }
+
+        // action === '1' continues to full setup
+        console.log('\n⚠️  This will overwrite your existing configuration!\n');
+    }
+
+    // Database Configuration
+    console.log('--- Database Configuration ---\n');
+
+    const mode = await question('Database mode?\n  1) Connect to existing database\n  2) Auto-create database and tables\nChoice (1-2): ');
+    const dbMode = mode === '2' ? 'create' : 'connect';
+
+    const host = await question('Database host (default: 127.0.0.1): ') || '127.0.0.1';
+    const port = await question('Database port (default: 3306): ') || '3306';
+    const database = await question('Database name (default: viewcounterdb): ') || 'viewcounterdb';
+    const user = await question('Database user (default: root): ') || 'root';
+    const password = await question('Database password: ');
+
+    const dbConfig = {
+        mode: dbMode,
+        host,
+        port: parseInt(port, 10),
+        database,
+        user,
+        password
+    };
+
+    fs.writeFileSync(dbInfoPath, JSON.stringify(dbConfig, null, 4), { mode: CONFIG_FILE_MODE });
+    fs.chmodSync(dbInfoPath, CONFIG_FILE_MODE);
+    console.log('✓ Created dbInfo.json\n');
+
+    // Allowed Values Configuration
+    console.log('--- Allowed Values Configuration ---\n');
+
+    const appIds = await question('Enter allowed app IDs (comma-separated, e.g., blog,portfolio): ');
+    const deviceSizes = await question('Enter allowed device sizes (comma-separated, default: small,medium,large): ') || 'small,medium,large';
+
+    const allowedConfig = {
+        appId: appIds.split(',').map(s => s.trim()).filter(Boolean),
+        deviceSize: deviceSizes.split(',').map(s => s.trim()).filter(Boolean)
+    };
+
+    fs.writeFileSync(allowedPath, JSON.stringify(allowedConfig, null, 4), { mode: CONFIG_FILE_MODE });
+    fs.chmodSync(allowedPath, CONFIG_FILE_MODE);
+    console.log('✓ Created allowed.json\n');
+
+    // Optional .env file
+    const createEnv = await question('Create .env file for additional config? (y/n, default: n): ');
+    if (createEnv.toLowerCase() === 'y') {
+        const serverPort = await question('Server port (default: 3030): ') || '3030';
+        const rateLimitMax = await question('Rate limit max requests per minute (default: 100): ') || '100';
+        const uniqueWindow = await question('Unique visitor window in hours (default: 24, 0 to disable): ') || '24';
+        const corsOrigins = await question('Allowed browser origins (comma-separated, e.g. https://example.com): ');
+        const generatedApiKey = crypto.randomBytes(PRIVACY.MIN_API_KEY_LENGTH).toString('hex');
+        console.log(`\n  Generated read API key: ${generatedApiKey}`);
+        console.log('  Save it now; send it as the x-api-key header on read endpoints.\n');
+
+        const envContent = `# Database Mode
+DB_MODE=${dbMode}
+
+# Database Connection
+DB_HOST=${host}
+DB_PORT=${port}
+DB_NAME=${database}
+DB_USER=${user}
+DB_PASSWORD=${password}
+
+# Server Configuration
+PORT=${serverPort}
+NODE_ENV=production
+
+# Rate Limiting
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=${rateLimitMax}
+
+# Unique Visitor Tracking (hours)
+UNIQUE_VISITOR_WINDOW_HOURS=${uniqueWindow}
+
+# Origins permitted to call the write endpoints from a browser.
+CORS_ORIGINS=${corsOrigins}
+
+# Credential for the analytics read endpoints. Generated here; rotate by
+# replacing it. Several may be listed comma-separated so one consumer's key
+# can be revoked without disturbing the others.
+READ_API_KEYS=${generatedApiKey}
+`;
+
+        fs.writeFileSync(envPath, envContent, { mode: CONFIG_FILE_MODE });
+        fs.chmodSync(envPath, CONFIG_FILE_MODE);
+        console.log('✓ Created .env\n');
+    }
+
+    console.log('✅ Setup complete!\n');
+    console.log('Next steps:');
+    console.log('  1. Install dependencies: npm install');
+    console.log('  2. Start the server: npm start');
+    console.log('');
+
+    rl.close();
+}
+
+async function editSpecificFiles(hasDbInfo, hasAllowed, _hasEnv) {
+    console.log('\nWhich files would you like to reconfigure?');
+
+    if (hasDbInfo) {
+        const editDb = await question('  - Reconfigure dbInfo.json? (y/n): ');
+        if (editDb.toLowerCase() === 'y') {
+            // Simplified re-config for dbInfo
+            const mode = await question('Database mode (connect/create): ') || 'connect';
+            const host = await question('Database host: ') || '127.0.0.1';
+            const port = await question('Database port: ') || '3306';
+            const database = await question('Database name: ') || 'viewcounterdb';
+            const user = await question('Database user: ') || 'root';
+            const password = await question('Database password: ');
+
+            fs.writeFileSync(dbInfoPath, JSON.stringify({ mode, host, port: parseInt(port), database, user, password }, null, 4), { mode: CONFIG_FILE_MODE });
+            fs.chmodSync(dbInfoPath, CONFIG_FILE_MODE);
+            console.log('✓ Updated dbInfo.json');
+        }
+    }
+
+    if (hasAllowed) {
+        const editAllowed = await question('  - Reconfigure allowed.json? (y/n): ');
+        if (editAllowed.toLowerCase() === 'y') {
+            const appIds = await question('Allowed app IDs (comma-separated): ');
+            const deviceSizes = await question('Allowed device sizes (comma-separated): ');
+
+            fs.writeFileSync(allowedPath, JSON.stringify({
+                appId: appIds.split(',').map(s => s.trim()).filter(Boolean),
+                deviceSize: deviceSizes.split(',').map(s => s.trim()).filter(Boolean)
+            }, null, 4), { mode: CONFIG_FILE_MODE });
+            fs.chmodSync(allowedPath, CONFIG_FILE_MODE);
+            console.log('✓ Updated allowed.json');
+        }
+    }
+
+    console.log('\n✅ Configuration updated!');
+}
+
+setup().catch(error => {
+    console.error('Setup failed:', error);
+    rl.close();
+    process.exit(1);
+});

package/utils/appIdUtils.js

@@ -0,0 +1,38 @@
+/**
+ * App ID validation.
+ *
+ * An app ID becomes a MySQL table name. Identifiers cannot be bound as query
+ * parameters, so they are interpolated — which is safe only because the value
+ * is checked here first. App IDs used to come exclusively from local config;
+ * the admin API now accepts them over HTTP, so this is a live injection
+ * boundary, not a formatting preference.
+ */
+
+const { APP_ID_PATTERN, RESERVED_TABLE_PREFIX } = require('../constants');
+
+/**
+ * @param {unknown} appId
+ * @returns {boolean} true when safe to use as a table identifier
+ */
+function isValidAppId(appId) {
+    if (typeof appId !== 'string') return false;
+    // Reserved for the service's own tables (`_migrations`, `_apps`); allowing
+    // one would let a caller collide with or shadow internal state.
+    if (appId.startsWith(RESERVED_TABLE_PREFIX)) return false;
+    return APP_ID_PATTERN.test(appId);
+}
+
+/**
+ * Filter a list down to app IDs safe to use.
+ * Applied to config-sourced lists too: a typo in `allowed.json` should not be
+ * able to produce a malformed CREATE TABLE.
+ *
+ * @param {unknown[]} appIds
+ * @returns {string[]}
+ */
+function filterValidAppIds(appIds) {
+    if (!Array.isArray(appIds)) return [];
+    return appIds.filter(isValidAppId);
+}
+
+module.exports = { isValidAppId, filterValidAppIds };