@harshankur/viewcounter 3.0.0

package/db/schema.sql

@@ -0,0 +1,71 @@
+-- Schema for view counter database
+-- This file is used when DB_MODE=create to auto-initialize the database
+
+-- Create database if it doesn't exist
+CREATE DATABASE IF NOT EXISTS `{{DB_NAME}}` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+USE `{{DB_NAME}}`;
+
+-- Migration tracking table
+CREATE TABLE IF NOT EXISTS `_migrations` (
+    `id` INT AUTO_INCREMENT PRIMARY KEY,
+    `version` VARCHAR(50) NOT NULL UNIQUE,
+    `applied_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    INDEX `idx_version` (`version`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Template for app-specific view tables
+-- Actual tables will be created dynamically based on allowed.json appIds
+-- Table name format: {{APP_ID}}
+CREATE TABLE IF NOT EXISTS `{{APP_ID}}` (
+    `id` BIGINT AUTO_INCREMENT PRIMARY KEY,
+    
+    -- Identifiers (Anonymized)
+    `masked_ip` VARCHAR(45) NOT NULL,
+    `visitor_hash` VARCHAR(64) NOT NULL,
+    `country` VARCHAR(2) DEFAULT NULL,
+    `timestamp` DATETIME NOT NULL,
+    `devicesize` VARCHAR(20) NOT NULL,
+    
+    -- Page tracking
+    `page_path` VARCHAR(500) DEFAULT NULL,
+    `page_title` VARCHAR(200) DEFAULT NULL,
+    
+    -- Referrer tracking
+    `referrer` VARCHAR(500) DEFAULT NULL,
+    `referrer_domain` VARCHAR(200) DEFAULT NULL,
+    `source_type` VARCHAR(20) DEFAULT NULL,  -- direct, search, social, email, campaign, referral
+
+    -- User agent parsing
+    `browser` VARCHAR(50) DEFAULT NULL,
+    `browser_version` VARCHAR(20) DEFAULT NULL,
+    `os` VARCHAR(50) DEFAULT NULL,
+    `os_version` VARCHAR(20) DEFAULT NULL,
+    `device_type` VARCHAR(20) DEFAULT NULL,  -- mobile, tablet, desktop
+    
+    -- Session tracking
+    `session_id` VARCHAR(64) DEFAULT NULL,
+    
+    -- Custom events
+    `event_type` VARCHAR(50) DEFAULT 'pageview',  -- pageview, click, submit, etc.
+    `event_data` JSON DEFAULT NULL,
+    
+    -- Uniqueness tracking
+    `is_unique` TINYINT(1) DEFAULT 1,  -- 1 if first view in window, 0 otherwise
+    
+    -- Indexes
+    INDEX `idx_timestamp` (`timestamp`),
+    INDEX `idx_visitor_timestamp` (`visitor_hash`, `timestamp`),
+    INDEX `idx_masked_ip` (`masked_ip`),
+    INDEX `idx_country` (`country`),
+    INDEX `idx_devicesize` (`devicesize`),
+    INDEX `idx_page_path` (`page_path`(255)),
+    INDEX `idx_referrer_domain` (`referrer_domain`),
+    INDEX `idx_source_type` (`source_type`),
+    INDEX `idx_browser` (`browser`),
+    INDEX `idx_os` (`os`),
+    INDEX `idx_device_type` (`device_type`),
+    INDEX `idx_session_id` (`session_id`),
+    INDEX `idx_event_type` (`event_type`),
+    INDEX `idx_is_unique` (`is_unique`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

package/dbInfo.sample.json

@@ -0,0 +1,8 @@
+{
+    "mode": "connect",
+    "host": "127.0.0.1",
+    "port": 3306,
+    "database": "viewcounterdb",
+    "user": "root",
+    "password": ""
+}

package/index.js

@@ -0,0 +1,184 @@
+const express = require('express');
+const cors = require('cors');
+const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+
+const { APP_NAME, HTTP_STATUS, PAYLOAD_LIMITS, SERVER } = require('./constants');
+const config = require('./config');
+const DatabaseManager = require('./db/DatabaseManager');
+const logger = require('./utils/logger');
+const { buildCorsOptions } = require('./middleware/security');
+const { createAnalyticsRouter } = require('./routes/analytics');
+
+logger.configure({ level: config.server.logLevel });
+
+const dbManager = new DatabaseManager(config.dbInfo);
+let isServerReady = false;
+let httpServer = null;
+
+/**
+ * Build the Express application.
+ *
+ * Kept separate from the bootstrap below so the same wiring can be exercised
+ * by tests and reused by embedders.
+ */
+function createApp() {
+    const app = express();
+
+    app.disable('x-powered-by');
+    app.use(helmet());
+    app.use(cors(buildCorsOptions(config.server.corsOrigins)));
+
+    // Bounded well below body-parser's 100kb default; /event is the only
+    // endpoint taking a body and its payload is small.
+    app.use(express.json({ limit: PAYLOAD_LIMITS.MAX_BODY_BYTES }));
+
+    // Never bare `true`. Trusting every hop lets any caller set
+    // X-Forwarded-For and be believed, which forges geolocation and rotates
+    // the rate-limiter key at will.
+    app.set('trust proxy', config.server.trustProxy);
+
+    app.use(rateLimit({
+        windowMs: config.server.rateLimit.windowMs,
+        limit: config.server.rateLimit.max,
+        message: { message: 'Too many requests, please try again later.' },
+        standardHeaders: true,
+        legacyHeaders: false,
+    }));
+
+    app.use(createAnalyticsRouter({
+        config,
+        dbManager,
+        isReady: () => isServerReady,
+    }));
+
+    // 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' });
+    });
+
+    return app;
+}
+
+const app = createApp();
+
+/**
+ * Fold the database-backed app registry into the in-memory allowlist.
+ *
+ * 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.
+ */
+async function mergeRegisteredApps() {
+    try {
+        const registered = await dbManager.listRegisteredApps();
+        const merged = new Set([...config.allowed.appId, ...registered]);
+        config.allowed.appId = [...merged];
+
+        const origins = await dbManager.loadRegisteredOrigins();
+        for (const [appId, list] of Object.entries(origins)) {
+            // allowed.json wins, so an operator can override a tenant's own
+            // origin list without editing the database.
+            if (!config.allowed.origins[appId]) config.allowed.origins[appId] = list;
+        }
+
+        if (registered.length) {
+            logger.info(`Loaded ${registered.length} registered app(s) from the database`);
+        }
+    } catch (error) {
+        logger.warn(`Could not read the app registry: ${error.message}`);
+    }
+}
+
+/**
+ * Validate config, connect the database, and start listening.
+ */
+const initializeServer = async () => {
+    try {
+        config.validate();
+        await dbManager.initialize(config.allowed.appId);
+
+        // Merge dynamically registered tenants into the live allowlist, so
+        // apps provisioned through the admin API survive a restart without
+        // anyone editing allowed.json.
+        await mergeRegisteredApps();
+
+        isServerReady = true;
+
+        if (require.main === module) {
+            httpServer = app.listen(config.server.port, () => {
+                logger.info(`${APP_NAME} listening on port ${config.server.port}`);
+                logger.info(`Database mode: ${config.dbInfo.mode}`);
+                logger.info(`Allowed apps: ${config.allowed.appId.join(', ')}`);
+            });
+        }
+    } catch (error) {
+        logger.error(`Failed to start: ${error.message}`);
+        if (require.main === module) process.exit(1);
+    }
+};
+
+// 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();
+}
+
+/**
+ * Graceful shutdown.
+ *
+ * Closes the HTTP listener first so in-flight requests can finish; previously
+ * the listener was never closed at all, so "graceful" covered only the
+ * database pool while active requests were severed.
+ */
+const shutdown = async (signal, exitCode = 0) => {
+    logger.info(`${signal} received, shutting down gracefully...`);
+
+    const forceExit = setTimeout(() => {
+        logger.error('Shutdown timed out, exiting');
+        process.exit(1);
+    }, SERVER.SHUTDOWN_TIMEOUT_MS);
+    forceExit.unref();
+
+    try {
+        if (httpServer) {
+            await new Promise((resolve) => httpServer.close(resolve));
+        }
+        await dbManager.close();
+        // Preserve the caller's code: a crash-triggered shutdown must not
+        // report success, or a process manager sees a clean exit and may
+        // decline to restart the service.
+        process.exit(exitCode);
+    } catch (error) {
+        logger.error(`Error during shutdown: ${error.message}`);
+        process.exit(1);
+    }
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+// A rejected promise with no handler would otherwise terminate the process on
+// modern Node with no log line explaining why.
+process.on('unhandledRejection', (reason) => {
+    logger.error(`Unhandled promise rejection: ${reason instanceof Error ? reason.message : reason}`);
+});
+
+process.on('uncaughtException', (error) => {
+    logger.error(`Uncaught exception: ${error.message}`);
+    logger.error(error.stack || '(no stack)');
+    shutdown('uncaughtException', 1);
+});
+
+module.exports = app;
+module.exports.createApp = createApp;
+module.exports.createAnalyticsRouter = createAnalyticsRouter;
+module.exports.DatabaseManager = DatabaseManager;
+module.exports.dbManager = dbManager;
+module.exports.initializeServer = initializeServer;

package/middleware/auth.js

@@ -0,0 +1,194 @@
+/**
+ * Authentication and authorization for the analytics API.
+ *
+ * Two distinct steps, deliberately separate:
+ *
+ *   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
+ * constrained which table was queried, never who was entitled to query it.
+ */
+
+const crypto = require('crypto');
+
+const { API_KEY_HEADER, HTTP_STATUS, SCOPE_ALL } = require('../constants');
+
+/**
+ * Constant-time string comparison (agent-instructions SECURITY.md §2).
+ *
+ * A plain `===` returns as soon as two bytes differ, so response timing leaks
+ * how many leading characters were correct. The mismatched-length path still
+ * performs an equal-cost dummy comparison so "wrong length" and "right length,
+ * wrong value" are not distinguishable by timing either.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function safeEqual(a, b) {
+    const ab = Buffer.from(String(a));
+    const bb = Buffer.from(String(b));
+    if (ab.length !== bb.length) {
+        crypto.timingSafeEqual(ab, ab);
+        return false;
+    }
+    return crypto.timingSafeEqual(ab, bb);
+}
+
+/**
+ * Check a presented key against every configured key.
+ *
+ * Deliberately does not short-circuit on the first match: returning early
+ * would make the response time depend on the key's position in the list.
+ *
+ * @param {string} presented
+ * @param {string[]} configured
+ * @returns {boolean}
+ */
+function matchesAnyKey(presented, configured) {
+    let matched = false;
+    for (const key of configured) {
+        if (safeEqual(presented, key)) matched = true;
+    }
+    return matched;
+}
+
+/**
+ * Resolve a presented key to its scope, without short-circuiting.
+ *
+ * @param {string} presented
+ * @param {Record<string, string|string[]>} keyScopes  key -> '*' | [appId]
+ * @returns {string|string[]|null} the scope, or null when no key matched
+ */
+function resolveScope(presented, keyScopes) {
+    let scope = null;
+    for (const [key, keyScope] of Object.entries(keyScopes)) {
+        if (safeEqual(presented, key)) scope = keyScope;
+    }
+    return scope;
+}
+
+/**
+ * Does a resolved scope permit this app?
+ * @param {string|string[]} scope
+ * @param {string} appId
+ * @returns {boolean}
+ */
+function scopeAllows(scope, appId) {
+    if (scope === SCOPE_ALL) return true;
+    return Array.isArray(scope) && scope.includes(appId);
+}
+
+/**
+ * Expand a scope into the concrete list of apps it can see.
+ * @param {string|string[]} scope
+ * @param {string[]} allApps
+ * @returns {string[]}
+ */
+function appsInScope(scope, allApps) {
+    if (scope === SCOPE_ALL) return [...allApps];
+    if (!Array.isArray(scope)) return [];
+    return allApps.filter((appId) => scope.includes(appId));
+}
+
+/**
+ * Authenticate a read request and attach its scope as `req.auth`.
+ *
+ * Fails closed: with no keys configured the read API is unavailable rather
+ * than unprotected, so a deployment that forgets to set them cannot silently
+ * serve another party's analytics to the internet.
+ *
+ * @param {{ readKeyScopes: Record<string, string|string[]> }} authConfig
+ * @returns {import('express').RequestHandler}
+ */
+function requireReadApiKey(authConfig) {
+    const keyScopes = authConfig?.readKeyScopes || {};
+
+    return (req, res, next) => {
+        if (Object.keys(keyScopes).length === 0) {
+            return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({
+                message: 'Read API is not configured on this server',
+            });
+        }
+
+        const presented = req.get(API_KEY_HEADER);
+        const scope = presented ? resolveScope(presented, keyScopes) : null;
+
+        if (scope === null) {
+            return res.status(HTTP_STATUS.UNAUTHORIZED).json({
+                message: 'Missing or invalid API key',
+            });
+        }
+
+        req.auth = { scope };
+        return next();
+    };
+}
+
+/**
+ * Authorize the requested `:appId` against the authenticated key's scope.
+ *
+ * Runs after requireReadApiKey. Returns 403 rather than 404 for an app that
+ * exists but is out of scope, and the same 403 for one that does not exist, so
+ * the response does not disclose which tenants are registered.
+ *
+ * @returns {import('express').RequestHandler}
+ */
+function requireAppScope() {
+    return (req, res, next) => {
+        const { appId } = req.params;
+        if (!appId) return next();
+
+        if (!req.auth || !scopeAllows(req.auth.scope, appId)) {
+            return res.status(HTTP_STATUS.FORBIDDEN).json({
+                message: 'This API key is not authorized for that appId',
+            });
+        }
+
+        return next();
+    };
+}
+
+/**
+ * Require an admin credential.
+ *
+ * A separate tier from read keys (SECURITY.md §3): provisioning apps is a
+ * different privilege from reading them, so leaking a tenant's read key must
+ * not confer it, and revoking one tier must not force rotating the other.
+ *
+ * @param {{ adminApiKeys: string[] }} authConfig
+ * @returns {import('express').RequestHandler}
+ */
+function requireAdminApiKey(authConfig) {
+    const keys = Array.isArray(authConfig?.adminApiKeys) ? authConfig.adminApiKeys : [];
+
+    return (req, res, next) => {
+        if (keys.length === 0) {
+            return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({
+                message: 'Admin API is not configured on this server',
+            });
+        }
+
+        const presented = req.get(API_KEY_HEADER);
+        if (!presented || !matchesAnyKey(presented, keys)) {
+            return res.status(HTTP_STATUS.UNAUTHORIZED).json({
+                message: 'Missing or invalid admin key',
+            });
+        }
+
+        return next();
+    };
+}
+
+module.exports = {
+    requireReadApiKey,
+    requireAppScope,
+    requireAdminApiKey,
+    safeEqual,
+    matchesAnyKey,
+    resolveScope,
+    scopeAllows,
+    appsInScope,
+};

package/middleware/security.js

@@ -0,0 +1,109 @@
+/**
+ * Transport-level security middleware: CORS, origin binding, cache policy.
+ */
+
+const { HTTP_STATUS } = require('../constants');
+
+/**
+ * Build CORS options from an explicit allowlist.
+ *
+ * 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.
+ *
+ * @param {string[]} allowedOrigins
+ * @returns {import('cors').CorsOptions}
+ */
+function buildCorsOptions(allowedOrigins) {
+    const allowlist = new Set(allowedOrigins);
+
+    return {
+        origin(origin, callback) {
+            // No Origin header: a same-origin request, a server-side caller, or
+            // curl. There is no browser to protect in that case.
+            if (!origin) return callback(null, true);
+            return callback(null, allowlist.has(origin));
+        },
+        methods: ['GET', 'POST'],
+        allowedHeaders: ['Content-Type', 'x-api-key'],
+        credentials: false,
+        maxAge: 600,
+    };
+}
+
+/**
+ * Extract the requesting origin, falling back to the referrer's origin.
+ * @returns {string|null}
+ */
+function requestOrigin(req) {
+    const origin = req.get('origin');
+    if (origin) return origin;
+
+    const referer = req.get('referer') || req.get('referrer');
+    if (!referer) return null;
+
+    try {
+        return new URL(referer).origin;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Bind writes for an appId to the site origins registered for it.
+ *
+ * Without this, any page anywhere could embed
+ * `<img src="…/registerView?appId=victim&deviceSize=large">` and inject
+ * traffic into someone else's analytics. Being a GET, no CORS preflight is
+ * involved, so the browser's same-origin policy never came into it.
+ *
+ * Enforced only for appIds that declare an `origins` list in allowed.json; an
+ * appId with no list keeps accepting writes from anywhere, so adding this
+ * cannot silently break a running deployment. Startup validation warns about
+ * every appId still in that state.
+ *
+ * @param {{ origins: Record<string, string[]> }} allowed
+ * @returns {import('express').RequestHandler}
+ */
+function requireRegisteredOrigin(allowed) {
+    const origins = allowed?.origins || {};
+
+    return (req, res, next) => {
+        const appId = req.query.appId || req.body?.appId;
+        const registered = origins[appId];
+
+        if (!Array.isArray(registered) || registered.length === 0) {
+            return next();
+        }
+
+        const origin = requestOrigin(req);
+        if (origin && registered.includes(origin)) {
+            return next();
+        }
+
+        return res.status(HTTP_STATUS.FORBIDDEN).json({
+            message: 'Request origin is not registered for this appId',
+        });
+    };
+}
+
+/**
+ * Mark a response as uncacheable.
+ *
+ * Analytics responses are per-caller and must never be served from a shared
+ * proxy cache to a different caller. Neither express nor helmet sets this.
+ *
+ * @type {import('express').RequestHandler}
+ */
+function noStore(req, res, next) {
+    res.set('Cache-Control', 'no-store, max-age=0');
+    next();
+}
+
+module.exports = {
+    buildCorsOptions,
+    requireRegisteredOrigin,
+    requestOrigin,
+    noStore,
+};