@harshankur/viewcounter 3.0.1 → 3.2.0

package/utils/durationUtils.js

@@ -0,0 +1,33 @@
+/**
+ * Human-readable durations for configuration: "30m", "12h", "7d".
+ *
+ * Deliberately small: whole numbers of minutes, hours, or days, nothing else,
+ * so a value like "30 min" or "1.5h" is refused rather than read as something
+ * the operator did not mean. For a session timeout that difference matters.
+ */
+
+const UNIT_MS = { m: 60 * 1000, h: 60 * 60 * 1000, d: 24 * 60 * 60 * 1000 };
+const DURATION = /^(\d{1,6})([mhd])$/;
+
+/**
+ * @param {string} raw e.g. "7d"
+ * @returns {number|null} milliseconds, or null when the value is not a duration
+ */
+function parseDuration(raw) {
+    const match = DURATION.exec(String(raw ?? '').trim().toLowerCase());
+    return match ? Number(match[1]) * UNIT_MS[match[2]] : null;
+}
+
+/**
+ * The largest whole unit that expresses `ms` exactly: 604800000 -> "7d".
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDuration(ms) {
+    for (const unit of ['d', 'h', 'm']) {
+        if (ms % UNIT_MS[unit] === 0) return `${ms / UNIT_MS[unit]}${unit}`;
+    }
+    return `${ms}ms`;
+}
+
+module.exports = { parseDuration, formatDuration };

package/utils/errorUtils.js

@@ -6,7 +6,7 @@
  * identified by an enum member, its message text lives in exactly one table
  * here, and callers branch on `err.code` rather than parsing message strings.
  *
- * `getError` builds and reports but deliberately does NOT throw — the `throw`
+ * `getError` builds and reports but deliberately does NOT throw: the `throw`
  * stays visible at the call site and under the caller's control.
  */
 
@@ -23,6 +23,8 @@ const ErrorType = {
     INVALID_APP_ID: 'INVALID_APP_ID',
     SECRET_PERSIST_FAILED: 'SECRET_PERSIST_FAILED',
     SECRET_UNAVAILABLE: 'SECRET_UNAVAILABLE',
+    MIGRATION_FAILED: 'MIGRATION_FAILED',
+    FIELD_NOT_WRITABLE: 'FIELD_NOT_WRITABLE',
 };
 
 /** Non-fatal conditions worth surfacing but not worth stopping for. */
@@ -36,6 +38,16 @@ const WarningType = {
     API_KEY_EMPTY_SCOPE: 'API_KEY_EMPTY_SCOPE',
     APP_ALREADY_REGISTERED: 'APP_ALREADY_REGISTERED',
     FIELD_TRUNCATED: 'FIELD_TRUNCATED',
+    ADMIN_UI_DISABLED: 'ADMIN_UI_DISABLED',
+    ADMIN_PASSWORD_REUSED: 'ADMIN_PASSWORD_REUSED',
+    ADMIN_INSECURE_TRANSPORT: 'ADMIN_INSECURE_TRANSPORT',
+    ADMIN_ORIGIN_REJECTED: 'ADMIN_ORIGIN_REJECTED',
+    VIEW_LOG_PRUNE_FAILED: 'VIEW_LOG_PRUNE_FAILED',
+    MIGRATION_TABLE_MISSING: 'MIGRATION_TABLE_MISSING',
+    VIEW_LOG_WRITE_FAILED: 'VIEW_LOG_WRITE_FAILED',
+    TRACKING_LOG_WRITE_FAILED: 'TRACKING_LOG_WRITE_FAILED',
+    ADMIN_LOG_WRITE_FAILED: 'ADMIN_LOG_WRITE_FAILED',
+    TRASH_PURGE_FAILED: 'TRASH_PURGE_FAILED',
 };
 
 /**
@@ -62,6 +74,10 @@ const ERROR_MESSAGES = {
         `Could not persist the visitor-hash secret to ${info?.path}. ` +
         'Without a stable secret, visitor hashes are not reversible-resistant across restarts.',
     [ErrorType.SECRET_UNAVAILABLE]: 'Visitor-hash secret has not been initialized',
+    [ErrorType.MIGRATION_FAILED]: (info) =>
+        `Schema migration failed for table '${info?.table}': ${info?.cause}`,
+    [ErrorType.FIELD_NOT_WRITABLE]: (info) =>
+        `Refusing to write column '${info?.column}': it is not an admin-editable field.`,
 };
 
 /** @type {Record<string, string | ((info: any) => string)>} */
@@ -86,6 +102,28 @@ const WARNING_MESSAGES = {
         `App '${info?.appId}' is already registered; leaving it as-is.`,
     [WarningType.FIELD_TRUNCATED]: (info) =>
         `Field '${info?.field}' exceeded ${info?.max} characters and was truncated before storage.`,
+    [WarningType.ADMIN_UI_DISABLED]: 'ADMIN_PASSWORD is not set; the admin UI and its API are disabled.',
+    [WarningType.ADMIN_PASSWORD_REUSED]:
+        'ADMIN_PASSWORD is identical to a configured API key. Use an independent secret so ' +
+        'leaking one credential tier never unlocks another.',
+    [WarningType.ADMIN_INSECURE_TRANSPORT]:
+        'An admin login arrived over plain HTTP. The session cookie is not marked Secure on ' +
+        'such a request; serve the admin UI over HTTPS.',
+    [WarningType.ADMIN_ORIGIN_REJECTED]: (info) =>
+        `Refused an admin request from origin '${info?.presented}'; this server expected '${info?.expected}'. ` +
+        'Behind a TLS-terminating proxy, set TRUST_PROXY and have the proxy pass X-Forwarded-Proto and the original Host.',
+    [WarningType.MIGRATION_TABLE_MISSING]: (info) =>
+        `Table '${info?.table}' does not exist; skipping its schema migration.`,
+    [WarningType.TRACKING_LOG_WRITE_FAILED]: (info) =>
+        `Could not write counted tracking rejections: ${info?.cause}`,
+    [WarningType.VIEW_LOG_WRITE_FAILED]: (info) =>
+        `Could not write the view register log entry for '${info?.appId}': ${info?.cause}`,
+    [WarningType.ADMIN_LOG_WRITE_FAILED]: (info) =>
+        `Could not write the admin operation log entry '${info?.action}': ${info?.cause}`,
+    [WarningType.VIEW_LOG_PRUNE_FAILED]: (info) =>
+        `Automatic view log pruning failed: ${info?.cause}`,
+    [WarningType.TRASH_PURGE_FAILED]: (info) =>
+        `Automatic trash purge failed for '${info?.appId}': ${info?.cause}`,
 };
 
 /**

package/utils/geoCity.js

@@ -0,0 +1,87 @@
+/**
+ * Optional region and city for a view, from a city database the operator
+ * provides (GEOIP_CITY_DB, an .mmdb file).
+ *
+ * Off unless configured. The IP is looked up and discarded exactly as for the
+ * country: only the region and city names are kept, never the address or any
+ * coordinates. Both common free databases are understood, and each carries a
+ * licence that asks for a credit, which the admin UI shows:
+ *   - DB-IP IP to City Lite (CC BY 4.0), https://db-ip.com/db/lite.php
+ *   - MaxMind GeoLite2 City, https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
+ *
+ * The file is re-read when it is replaced, so a monthly update needs no restart.
+ */
+
+const maxmind = require('maxmind');
+
+const { FIELD_MAX_LENGTH } = require('../constants');
+
+/**
+ * The country of every view comes from geoip-country, which bundles MaxMind's
+ * GeoLite2 Country data; its licence asks for this credit.
+ */
+const COUNTRY_ATTRIBUTION = Object.freeze({
+    text: 'This product includes GeoLite2 data created by MaxMind',
+    url: 'https://www.maxmind.com',
+});
+
+/** The credit each database's licence asks for, by its metadata type. */
+const ATTRIBUTIONS = [
+    { match: /dbip|db-ip/i, text: 'IP geolocation by DB-IP', url: 'https://db-ip.com' },
+    { match: /geolite2|geoip2/i, text: 'This product includes GeoLite2 data created by MaxMind', url: 'https://www.maxmind.com' },
+];
+
+const englishName = (record) => {
+    const name = record?.names?.en;
+    return typeof name === 'string' && name.trim() ? name.trim().slice(0, FIELD_MAX_LENGTH.CITY) : null;
+};
+
+/**
+ * @param {{ get: (ip: string) => object|null, metadata?: { databaseType?: string } }} reader an opened .mmdb reader
+ * @returns {{ lookup: (ip: string) => ({ region: string|null, city: string|null }), attribution: object|null, databaseType: string }}
+ */
+function createCityLookup(reader) {
+    const databaseType = String(reader.metadata?.databaseType || 'unknown');
+    const credit = ATTRIBUTIONS.find((candidate) => candidate.match.test(databaseType));
+
+    return {
+        databaseType,
+        attribution: credit ? { text: credit.text, url: credit.url } : { text: `Location data: ${databaseType}`, url: null },
+
+        lookup(ip) {
+            let record = null;
+            try {
+                record = reader.get(ip);
+            } catch {
+                return { region: null, city: null };
+            }
+            return {
+                region: englishName(record?.subdivisions?.[0]),
+                city: englishName(record?.city),
+            };
+        },
+    };
+}
+
+/**
+ * Open the configured city database, or return null when none is configured.
+ * @param {string|undefined} file
+ * @returns {Promise<ReturnType<typeof createCityLookup>|null>}
+ */
+async function openCityLookup(file) {
+    if (!file) return null;
+    const reader = await maxmind.open(file, { watchForUpdates: true, watchForUpdatesNonPersistent: true });
+    return createCityLookup(reader);
+}
+
+/**
+ * Every credit the location data in use asks for, each once.
+ * @param {{ attribution: object }|null} cityLookup
+ * @returns {{ text: string, url: string|null }[]}
+ */
+function attributions(cityLookup) {
+    const all = [COUNTRY_ATTRIBUTION, ...(cityLookup ? [cityLookup.attribution] : [])];
+    return all.filter((credit, index) => all.findIndex((other) => other.text === credit.text) === index);
+}
+
+module.exports = { createCityLookup, openCityLookup, attributions, ATTRIBUTIONS, COUNTRY_ATTRIBUTION };

package/utils/ipUtils.js

@@ -29,7 +29,7 @@ function isValidIP(ip) {
  * Deliberately reads ONLY `req.ip`, which Express derives according to the
  * app's `trust proxy` setting. The previous implementation read `x-real-ip`
  * and `x-forwarded-for` straight off the request, so any caller could name
- * their own address — forging geolocation, inflating unique-visitor counts,
+ * their own address: forging geolocation, inflating unique-visitor counts,
  * and rotating the rate-limiter key to bypass it entirely.
  *
  * If a reverse proxy in front of this service sets only `X-Real-IP`, configure

package/utils/privacyUtils.js

@@ -69,8 +69,8 @@ class PrivacyUtils {
      * Generate the transient visitor identifier.
      *
      * This is a keyed HMAC, not a bare digest. Every non-secret input is
-     * public or guessable — the date is known, user agents come from a small
-     * population, and IPv4 is only 2^32 — so an unkeyed SHA-256 of them is
+     * public or guessable (the date is known, user agents come from a small
+     * population, and IPv4 is only 2^32), so an unkeyed SHA-256 of them is
      * reversible by exhaustive search in about an hour on one CPU core. The
      * server secret is what makes that search infeasible; the window id is
      * what stops hashes being linkable over time.

package/utils/referrerParser.js

@@ -7,12 +7,27 @@ const { truncate } = require('./stringUtils');
  * Parse referrer URLs to extract domain and source type
  */
 class ReferrerParser {
+    /**
+     * A referrer as it may be stored: without its query string or fragment,
+     * which can carry tokens, email addresses, or IDs from the page before
+     * (a password-reset link, say). The source is read from the whole URL,
+     * in memory, before this.
+     * @param {string} referrer
+     * @returns {string}
+     */
+    static withoutQuery(referrer) {
+        return String(referrer).split(/[?#]/, 1)[0];
+    }
+
     /**
      * Parse referrer URL
-     * @param {string} referrer - Referrer URL from request headers
+     * @param {string} referrer - the referrer the page reported (never the request's Referer header)
+     * @param {string|null} [siteHostname] - the hostname of the page viewed; a
+     *   referrer on the same site (www. or not) is internal navigation, which
+     *   would otherwise count every click within a site as a referral from it
      * @returns {object} Parsed referrer data
      */
-    static parse(referrer) {
+    static parse(referrer, siteHostname = null) {
         if (!referrer || referrer === '') {
             return {
                 referrer: null,
@@ -24,16 +39,19 @@ class ReferrerParser {
         try {
             const url = new URL(referrer);
             const domain = url.hostname || null;
-            const sourceType = this.getSourceType(domain, referrer);
+            const sameSite = (host) => String(host || '').toLowerCase().replace(/^www\./, '');
+            const sourceType = domain && siteHostname && sameSite(domain) === sameSite(siteHostname)
+                ? SOURCE_TYPE.INTERNAL
+                : this.getSourceType(domain, referrer);
 
             return {
-                referrer: truncate(referrer, FIELD_MAX_LENGTH.REFERRER),
+                referrer: truncate(this.withoutQuery(referrer), FIELD_MAX_LENGTH.REFERRER),
                 referrerDomain: truncate(domain, FIELD_MAX_LENGTH.REFERRER_DOMAIN),
                 sourceType
             };
         } catch (error) {
             return {
-                referrer: truncate(referrer, FIELD_MAX_LENGTH.REFERRER),
+                referrer: truncate(this.withoutQuery(referrer), FIELD_MAX_LENGTH.REFERRER),
                 referrerDomain: null,
                 sourceType: SOURCE_TYPE.UNKNOWN
             };

package/utils/secretStore.js

@@ -2,7 +2,7 @@
  * Persisted server secret for visitor hashing.
  *
  * agent-instructions SECURITY.md §1: never fall back to a weak, guessable
- * default for a security-relevant value — generate one cryptographically and
+ * default for a security-relevant value: generate one cryptographically and
  * persist it. This module is that generator.
  */
 

package/utils/userAgentParser.js

@@ -1,4 +1,16 @@
 const UAParser = require('ua-parser-js');
+const { isbot, isbotMatch } = require('isbot');
+
+/**
+ * ua-parser-js 1.x is used because 2.x is licensed AGPL-3.0, which an MIT
+ * package cannot pass on to the people who install it. 1.x names a few things
+ * differently from the 2.x that recorded the data before 3.2, so its output is
+ * mapped to the 2.x names: otherwise one browser would split into two rows of
+ * every breakdown, depending on when a view was recorded.
+ */
+const OS_NAMES = { 'Mac OS': 'macOS', 'Chromium OS': 'Chrome OS' };
+/** 2.x prefixes these with "Mobile " on phones (not on tablets). */
+const MOBILE_PREFIXED_BROWSERS = new Set(['Chrome', 'Firefox']);
 
 /**
  * Parse user agent string to extract browser, OS, and device information
@@ -23,15 +35,52 @@ class UserAgentParser {
         const parser = new UAParser(userAgent);
         const result = parser.getResult();
 
+        // 2.x also recognises a bare "iPad" token that 1.x needs more of the string for.
+        const deviceType = result.device.type || (/\biPad\b/.test(userAgent) ? 'tablet' : undefined);
+        const onPhone = deviceType === 'mobile';
+        const browser = result.browser.name && onPhone && MOBILE_PREFIXED_BROWSERS.has(result.browser.name)
+            ? `Mobile ${result.browser.name}`
+            : result.browser.name;
+
         return {
-            browser: result.browser.name || null,
+            browser: browser || null,
             browserVersion: result.browser.version || null,
-            os: result.os.name || null,
+            os: OS_NAMES[result.os.name] || result.os.name || null,
             osVersion: result.os.version || null,
-            deviceType: this.getDeviceType(result.device.type)
+            deviceType: this.getDeviceType(deviceType)
         };
     }
 
+    /**
+     * Whether the user agent is a crawler, link previewer, headless browser, or
+     * command-line client rather than a person. Such requests are counted in
+     * the tracking log but never stored as views.
+     * @param {string} userAgent
+     * @returns {boolean}
+     */
+    static isBot(userAgent) {
+        return Boolean(userAgent) && isbot(userAgent);
+    }
+
+    /**
+     * A short name for the bot, for the tracking log: the part of the user
+     * agent that identified it, without its version ("Googlebot", "curl").
+     * @param {string} userAgent
+     * @returns {string}
+     */
+    static botName(userAgent) {
+        if (!userAgent) return '';
+        // Where bots conventionally name themselves: "compatible; Googlebot/2.1",
+        // Chrome's headless build, or a leading product token ("curl/8.4.0").
+        const compatible = /compatible;\s*([A-Za-z][\w.-]*)/i.exec(userAgent);
+        if (compatible) return compatible[1].slice(0, 64);
+        if (/HeadlessChrome/.test(userAgent)) return 'HeadlessChrome';
+        const product = /^([A-Za-z][\w.-]*)/.exec(userAgent);
+        if (product && product[1] !== 'Mozilla') return product[1].slice(0, 64);
+        const match = isbotMatch(userAgent);
+        return match ? match.trim().split(/[\s/;(]/)[0].slice(0, 64) : '';
+    }
+
     /**
      * Normalize device type
      * @param {string} type - Device type from ua-parser-js

package/utils/visitorContext.js

@@ -0,0 +1,70 @@
+/**
+ * Coarse, identifier-free context about a view, read from what the request
+ * already carries. Each value is reduced to the least that answers an
+ * analytics question, so none of them narrows a visitor down on its own:
+ *
+ *   - language: the primary subtag of the first Accept-Language entry ("en",
+ *     never "en-GB;q=0.9,de;q=0.8", whose full list is a fingerprinting signal);
+ *   - hostname: which of the app's registered sites was visited;
+ *   - UTM tags: the five campaign parameters, and only those. The rest of a
+ *     landing URL's query string can carry emails, tokens, or IDs, so the
+ *     tracker never sends it and the server never reads it.
+ */
+
+const { FIELD_MAX_LENGTH } = require('../constants');
+
+/** The query parameters a campaign link carries, in the order they are shown. */
+const UTM_PARAMETERS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];
+
+const LANGUAGE_SUBTAG = /^[a-z]{2,8}$/;
+
+/**
+ * @param {string|undefined} acceptLanguage the Accept-Language header
+ * @returns {string|null} e.g. "en"
+ */
+function primaryLanguage(acceptLanguage) {
+    if (typeof acceptLanguage !== 'string') return null;
+    const first = acceptLanguage.split(',')[0].split(';')[0].trim();
+    const subtag = first.split('-')[0].toLowerCase();
+    return LANGUAGE_SUBTAG.test(subtag) && subtag.length <= FIELD_MAX_LENGTH.LANGUAGE ? subtag : null;
+}
+
+/**
+ * @param {string|null|undefined} origin e.g. "https://www.example.com"
+ * @returns {string|null} e.g. "www.example.com"
+ */
+function hostnameOf(origin) {
+    if (typeof origin !== 'string' || origin === '') return null;
+    try {
+        const hostname = new URL(origin).hostname.toLowerCase().replace(/\.$/, '');
+        return hostname && hostname.length <= FIELD_MAX_LENGTH.HOSTNAME ? hostname : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The UTM tags of a request, trimmed; absent or blank ones are null.
+ * Validation has already bounded each to FIELD_MAX_LENGTH.UTM.
+ *
+ * @param {Record<string, unknown>} params the query string or body
+ * @returns {{ utmSource: string|null, utmMedium: string|null, utmCampaign: string|null,
+ *   utmTerm: string|null, utmContent: string|null }}
+ */
+function utmTags(params = {}) {
+    const read = (name) => {
+        const value = params[name];
+        if (typeof value !== 'string') return null;
+        const trimmed = value.trim();
+        return trimmed === '' ? null : trimmed.slice(0, FIELD_MAX_LENGTH.UTM);
+    };
+    return {
+        utmSource: read('utm_source'),
+        utmMedium: read('utm_medium'),
+        utmCampaign: read('utm_campaign'),
+        utmTerm: read('utm_term'),
+        utmContent: read('utm_content'),
+    };
+}
+
+module.exports = { UTM_PARAMETERS, primaryLanguage, hostnameOf, utmTags };