@harshankur/viewcounter 3.3.0 → 3.5.0

package/.env.example

@@ -127,6 +127,17 @@ RATE_LIMIT_MAX=100
 # Set 0 to disable (sensible for a single-tenant deployment).
 APP_RATE_LIMIT_MAX=1000
 
+# An app's own figures, where the general ones above do not fit it: a list of
+# appId:number. A site that records far more per visitor than the others (every
+# step inside a single-page app, say) gets the room it needs without loosening
+# the limits for every other app. An app listed in RATE_LIMIT_MAX_BY_APP is
+# counted on its own per address, so its traffic does not use up the address's
+# budget for other apps. Zero means no limit, here as in the general figures
+# above. A malformed entry, or an app listed twice, stops the server from
+# starting; a figure for an app that is not configured is warned about.
+#RATE_LIMIT_MAX_BY_APP=homepage:600
+#APP_RATE_LIMIT_MAX_BY_APP=homepage:5000
+
 # How long a visitor counts as "the same visitor" for deduplication, in hours.
 # Also the rotation period for the visitor hash: after this window the same
 # person hashes differently, so their visits cannot be linked across windows.

package/README.md

@@ -3,7 +3,7 @@
 [![Documentation](https://img.shields.io/badge/docs-viewcounter.harshankur.com-blueviolet)](https://viewcounter.harshankur.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Test Suite](https://github.com/harshankur/viewcounter/actions/workflows/test.yml/badge.svg)](https://github.com/harshankur/viewcounter/actions/workflows/test.yml)
-[![Tests](https://img.shields.io/badge/tests-1109%20passing-success)](TEST_REPORT.md)
+[![Tests](https://img.shields.io/badge/tests-1164%20passing-success)](TEST_REPORT.md)
 [![npm](https://img.shields.io/npm/v/@harshankur/viewcounter?logo=npm)](https://www.npmjs.com/package/@harshankur/viewcounter)
 [![provenance](https://img.shields.io/badge/provenance-signed-brightgreen?logo=github)](https://www.npmjs.com/package/@harshankur/viewcounter#provenance)
 
@@ -12,13 +12,48 @@ A comprehensive Node.js/Express analytics server for tracking website views with
 ## 📖 Documentation
 Visit our [Interactive Documentation](https://viewcounter.harshankur.com) for detailed API specifications, debugging tips, and integration guides.
 
-## 🛡️ GDPR Compliant & Privacy-First
-**100% GDPR Compliant By Design.** This project is built from the ground up to respect user privacy and adhere to modern ethical standards:
+## 🛡️ Built for GDPR Compliance, Privacy-First
+**Built for GDPR compliance, by design.** This project is built from the ground up to respect user privacy and adhere to modern ethical standards:
 - **Nothing on the visitor's device**: no cookie, no localStorage, no sessionStorage, and no identifier sent with a view, so the tracker needs no consent banner under the ePrivacy rules on device storage. (The optional admin UI signs its operator in with a session cookie; tracking never sets one.)
 - **Data Sovereignty**: You own your data. Analytics never leave your private infrastructure.
-- **Minimal Collection**: records what analytics needs, each in a form that does not identify a person. [What Gets Tracked?](#what-gets-tracked) lists every field, where it comes from, and how it is stored; the raw IP address, the user agent, and the query string are never stored.
+- **Minimal Collection**: records what analytics needs, each in a form that does not identify a person directly. [What Gets Tracked?](#what-gets-tracked) lists every field, where it comes from, and how it is stored; the raw IP address, the user agent, and the query string are never stored.
 - **Bots left out**: crawlers, link previewers, and automated browsers are recognised and never stored, only counted per minute by name.
 
+### What is still yours to do
+
+ViewCounter does its part, and that is what "built for GDPR compliance" means.
+Compliance itself belongs to whoever runs it, and a few things no software can
+do for you:
+
+- **Say so.** Mention in your privacy notice that visits are counted, what is
+  recorded ([What Gets Tracked?](#what-gets-tracked)), and for how long.
+- **Have a legal basis.** For plain visit counting this is normally legitimate
+  interest; that judgement is yours to make and record.
+- **Keep personal details out.** ViewCounter stores what you send in custom
+  event data and the optional `sessionId` as given. Do not put names, email
+  addresses, or account IDs there.
+- **Answer requests.** During its window (a day by default) a visitor hash is
+  pseudonymous: whoever holds both the server secret and that window's salt
+  could tie it to a known address and browser. A few minutes after the window
+  ends the salt is deleted and, as long as no copy of it survives (next point),
+  nobody can, you included. What remains is a masked address
+  and coarse details. Treat it as personal data all the same: a visitor may
+  ask what is held or ask for erasure, which the admin UI does
+  ([Deleting, and GDPR](#deleting-and-gdpr)).
+- **Keep no copies of the salts.** The `_visitor_salts` table holds the salts
+  of the windows now running and nothing else. A copy of an old salt, wherever
+  it is, keeps the one thing whose deletion makes old hashes untraceable:
+  - **Backups**: exclude the table
+    (`mysqldump --ignore-table=<database>._visitor_salts`). Restoring without
+    it is harmless: a new salt is made on the next view.
+  - **The binary log**: MySQL 8 has it on by default and keeps 30 days, salts
+    included. If you do not replicate, turn it off (`skip-log-bin`) or leave
+    this database out of it (`binlog-ignore-db`); otherwise shorten
+    `binlog_expire_logs_seconds` to what you can accept. MariaDB has it off
+    unless you turned it on.
+
+This is a description of the software, not legal advice.
+
 ### 🔄 Data Privacy Lifecycle
 ```mermaid
 graph LR
@@ -39,7 +74,8 @@ We believe in total transparency regarding your visitors' data:
 2. **Immediate Masking**: Before being saved, the IP is masked (IPv4 last octet zeroed; IPv6 interface identifier zeroed).
 3. **Keyed, Not Just Hashed**: The visitor identifier is an HMAC-SHA-256 keyed with a 32-byte server secret generated on first run and stored at mode `0600`. This matters: an *unkeyed* hash of an IP is reversible by exhausting the 2^32 IPv4 space, which takes about an hour on one CPU core. Without the secret, that search is infeasible.
 4. **Rotating**: The hash also mixes in a time window (`UNIQUE_VISITOR_WINDOW_HOURS`), so the same visitor hashes differently after each window and their visits cannot be linked over time.
-5. **Automated Guards**: [`tests/privacyFailSafe.test.js`](tests/privacyFailSafe.test.js) asserts that no raw IP or User-Agent reaches either the bound parameters *or* the SQL text of any statement, and that the hash is genuinely keyed. CI runs it on every push, so a change that started storing raw IPs would fail the build.
+5. **Salted, and the salt is thrown away**: each window has its own random salt, kept in the `_visitor_salts` table only while the window lasts and deleted a few minutes after it ends, by a timer, whether or not anyone visits. From then on the hashes of that window cannot be recomputed from a known address and browser by anyone, the secret's holder included. The salt is useless without the server secret, which is never in the database.
+6. **Automated Guards**: [`tests/privacyFailSafe.test.js`](tests/privacyFailSafe.test.js) asserts that no raw IP or User-Agent reaches either the bound parameters *or* the SQL text of any statement, and that the hash is genuinely keyed. CI runs it on every push, so a change that started storing raw IPs would fail the build.
 
 ## ✨ Features
 
@@ -154,7 +190,7 @@ than running on a guessable default:
 - `ADMIN_PASSWORD`: turns on the [admin UI](#admin-ui) at `/admin`. At least 16 characters. Unset means the admin UI does not exist.
 
 **Optional**: `DB_MODE`, `PORT`, `LOG_LEVEL`, `RATE_LIMIT_WINDOW_MS`,
-`RATE_LIMIT_MAX`, `UNIQUE_VISITOR_WINDOW_HOURS`, `ALLOWED_DEVICE_SIZES`,
+`RATE_LIMIT_MAX`, `RATE_LIMIT_MAX_BY_APP`, `APP_RATE_LIMIT_MAX_BY_APP`, `UNIQUE_VISITOR_WINDOW_HOURS`, `ALLOWED_DEVICE_SIZES`,
 `TRASH_RETENTION_DAYS`, `VIEW_LOG_RETENTION_DAYS`, `ADMIN_SESSION_IDLE_TIMEOUT`,
 `ADMIN_SESSION_MAX_AGE`, `GEOIP_CITY_DB`.
 
@@ -393,7 +429,10 @@ Content-Type: text/plain   # or application/json
 {"appId": "blog", "id": "<the id /registerView returned>", "ms": 42000, "scroll": 80}
 ```
 How long the page was visible (`ms`, up to 6 hours) and how much of it had been
-on screen (`scroll`, 0 to 100). A later report can only raise either. Each
+on screen (`scroll`, 0 to 100). `scroll` is optional: leave it out for a page
+that fits its window, where there is nothing to scroll, and the view keeps no
+depth and stays out of the scroll averages. The tracker script does this
+itself. A later report can only raise either. Each
 report also marks the view as seen just now, which keeps its visitor in the
 admin's **Right now** for the next few minutes; the tracker script sends one
 every half minute while the page is being read. A report
@@ -622,7 +661,7 @@ returned by any API.
 |-------|-----------|-----------|-----|
 | **Timestamp** | Server | When the view was recorded | Everything over time |
 | **Masked IP** | Request | IPv4 with the last octet zeroed, IPv6 with the interface identifier zeroed | Abuse investigation at network level, never a person |
-| **Visitor hash** | IP and User-Agent, with a secret | HMAC-SHA-256, keyed with a server secret, rotating every window | Unique views, visitors, and visits; never returned |
+| **Visitor hash** | IP and User-Agent, with a secret | HMAC-SHA-256, keyed with a server secret and the window's salt, rotating every window; the salt is deleted when the window ends | Unique views, visitors, and visits; never returned |
 | **Country** | IP, looked up in memory | Two-letter code | Where visitors are |
 | **Region, City** | IP, with an optional [city database](#location-data) | Names, such as Bavaria and Munich | Where visitors are, more finely |
 | **Language** | `Accept-Language` | Primary subtag only, such as `de` (never `de-CH`, never a list) | Which languages to write in |
@@ -635,7 +674,7 @@ returned by any API.
 | **Device Size** | `deviceSize` | small, medium, large | Layout decisions |
 | **Browser, OS, and versions** | User-Agent, parsed in memory | Names and versions, such as Chrome 140 on macOS 15 | Compatibility |
 | **Device Type** | User-Agent | desktop, mobile, tablet, tv, console, wearable | Compatibility |
-| **Time on page, Scroll depth, Last seen** | The tracker script's `/engage` report | Milliseconds visible (at most 6 hours); percent of the page seen; when the page last reported | Whether pages are read |
+| **Time on page, Scroll depth, Last seen** | The tracker script's `/engage` report | Milliseconds visible (at most 6 hours); percent of the page seen, empty for a page that fits its window; when the page last reported | Whether pages are read |
 | **Event Type, Event Data** | `/event` | Type name; JSON up to 4 kB, as your site sends it | Custom events |
 | **Session ID** | `sessionId` (optional) | As your site sends it | Your own grouping; the tracker never sends one |
 
@@ -666,7 +705,10 @@ This setting prevents counting the same visitor multiple times within a time win
 - If no: it is stored as a unique view
 
 The window is also how often the visitor hash rotates, so it bounds how long
-the same person counts as one visitor.
+the same person counts as one visitor. It is the lifetime of the window's salt
+as well: the longer the window, the longer a hash stays traceable by whoever
+holds the secret and the salt. A day is what privacy-first analytics commonly
+uses; lengthen it knowingly.
 
 **Examples:**
 - `24` (default): the same visitor counts once per day
@@ -692,7 +734,7 @@ because a browser on your site must be able to reach them. Everything that
 - ✅ **Authenticated, scoped read API**: every analytics endpoint requires `x-api-key`, compared in constant time, and each key is authorized against the specific `appId` requested. Fails closed when unconfigured.
 - ✅ **Separate admin tier**: provisioning apps uses its own credential; a read key cannot provision and an admin key cannot read.
 - ✅ **Per-tenant rate limits**: an `appId`-keyed budget alongside the per-IP limit.
-- ✅ **Keyed visitor hashing**: HMAC-SHA-256 with a persisted 32-byte server secret, rotating per window, so stored hashes are not reversible to an IP.
+- ✅ **Keyed visitor hashing**: HMAC-SHA-256 with a persisted 32-byte server secret and a per-window salt that is deleted when the window ends, so stored hashes are not reversible to an IP, and after their window not even recomputable.
 - ✅ **SQL injection prevention**: every value is a bound parameter; the only interpolated identifier is `appId`, gated by the allowlist.
 - ✅ **Explicit CORS allowlist**: no wildcard, and writes can be bound to registered origins per app.
 - ✅ **Proxy-aware IP derivation**: client-supplied forwarding headers are not trusted unless `TRUST_PROXY` says so.
@@ -825,6 +867,26 @@ Two independent limits apply to writes:
   everyone else on the instance depends on. Keyed on `appId` alone, so it cannot
   be bypassed by rotating addresses. Set `0` to disable for single-tenant use.
 
+Either can be set for one app where the general figure does not fit it, as a
+list of `appId:number`:
+
+- `RATE_LIMIT_MAX_BY_APP=homepage:600`: tracking requests a minute from one
+  address to that app. Such an app is counted on its own, so its traffic does
+  not use up the address's budget for your other apps, nor the other way round.
+- `APP_RATE_LIMIT_MAX_BY_APP=homepage:5000`: that app's whole budget.
+
+Use these for a site that records far more per visitor than the others, such
+as a single-page app that counts every step inside it.
+
+- **Zero means no limit**, in all four settings: as a general figure it
+  switches that limit off, as an app's own figure it lifts it for that app.
+- **Only tracking requests** (`/registerView`, `/event`, `/engage`) are limited
+  as an app, and always as the app they are stored under. A read or admin call
+  is limited by the general figure whatever it names.
+- **Mistakes are not silent.** A malformed entry, or an app listed twice, stops
+  the server from starting. A figure for an app that is not configured is
+  logged as a warning at start, since it would otherwise never apply.
+
 Each limit is applied twice, as two separate budgets of that size: one for
 engagement reports (`/engage`) and one for everything else. A page being read
 reports every half minute, so each open, active tab costs two reports a minute;
@@ -888,7 +950,10 @@ app.use('/analytics', createAnalyticsRouter({
     privacy: { visitorSecret: process.env.VISITOR_SECRET },
     server: {
       uniqueVisitorWindowHours: 24,
-      // omit to disable the per-app write budget
+      // perAppMax: the per-app write budget (omit to disable it).
+      // max: per address, applied by the router to engagement reports only;
+      //   every other request is yours to limit, as below.
+      // perAppMaxByApp / maxByApp: { appId: number } for apps with their own figures.
       rateLimit: { windowMs: 60000, perAppMax: 1000 },
     },
   },
@@ -898,8 +963,10 @@ app.use('/analytics', createAnalyticsRouter({
 Endpoints then live under the prefix: `POST /analytics/event`,
 `GET /analytics/stats/blog`, and so on.
 
-Two things the host application owns in this mode, because the router does not
-install them itself: `helmet()` and the CORS allowlist, and `trust proxy`. Set
+Three things the host application owns in this mode, because the router does
+not install them itself: `helmet()` and the CORS allowlist, a per-address rate
+limit (the router limits only engagement reports per address, and only when
+`rateLimit.max` is given), and `trust proxy`. Set
 `app.set('trust proxy', <hop count>)`, never `true`, or callers can forge
 their own IP through `X-Forwarded-For`.
 
@@ -969,6 +1036,7 @@ automated browsers.
 | `data-spa` | `true` | Treat history changes as page views |
 | `data-hash` | none | Fragment prefixes, comma-separated (`#docs/,#spec/`), that count as their own page, for pages that route by fragment. Any other fragment stays part of the same page. A matching fragment is stored whole as part of the page, so list only prefixes whose fragments carry nothing private. As a referrer, such a page is its path alone |
 | `data-heartbeat` | `true` | Report time on page every half minute while the page is visible and in use, not only when it is hidden or left. It keeps the visitor in the admin's **Right now** while they read one page, and saves the time of a tab the browser closes without warning. It stops after half an hour without any input |
+| `data-campaigns` | `true` | Send the landing URL's `utm_*` tags with the view |
 | `data-outbound` | `true` | Record clicks on links to other sites, as `outbound` events |
 | `data-downloads` | `true` | Record clicks on downloads (pdf, zip, dmg, docx, and so on), as `download` events |
 | `data-respect-dnt` | `false` | Send nothing when the browser's Do Not Track is on |

package/config/index.js

@@ -12,7 +12,7 @@ const {
     SCOPE_ALL,
     SERVER,
 } = require('../constants');
-const { filterValidAppIds } = require('../utils/appIdUtils');
+const { filterValidAppIds, isValidAppId } = require('../utils/appIdUtils');
 const { parseDuration, formatDuration } = require('../utils/durationUtils');
 const { getError, logWarning, ErrorType, WarningType } = require('../utils/errorUtils');
 const { LogLevel } = require('../utils/logger');
@@ -47,6 +47,30 @@ function parseList(raw) {
         .filter(Boolean);
 }
 
+/**
+ * Parse per-app figures, `appId:number` separated by commas
+ * (`homepage:600,shop:0`), into a map. A malformed entry is an error: a
+ * limit silently not applied is worse than a refusal to start.
+ * @param {string|undefined} raw
+ * @param {string} field the setting's name, for the error
+ * @returns {Record<string, number>}
+ */
+function parseAppNumbers(raw, field) {
+    const figures = {};
+    for (const entry of parseList(raw)) {
+        const [appId, value, ...rest] = entry.split(':').map((part) => part.trim());
+        if (rest.length || !isValidAppId(appId) || !/^\d+$/.test(value || '')) {
+            throw getError(ErrorType.CONFIG_INVALID_VALUE, { field, reason: `'${entry}' is not appId:number, such as homepage:600` });
+        }
+        // Two figures for one app is a mistake, and guessing which was meant is not ours to do.
+        if (Object.hasOwn(figures, appId)) {
+            throw getError(ErrorType.CONFIG_INVALID_VALUE, { field, reason: `'${appId}' is listed twice` });
+        }
+        figures[appId] = Number(value);
+    }
+    return figures;
+}
+
 /** Parse an integer env var, falling back when absent or unparseable. */
 function parseIntOr(raw, fallback) {
     const parsed = Number.parseInt(raw, 10);
@@ -130,6 +154,9 @@ class Config {
                 // Per-app ceiling on writes, so one tenant cannot exhaust the
                 // budget the others depend on.
                 perAppMax: parseIntOr(this.env.APP_RATE_LIMIT_MAX, SERVER.DEFAULT_APP_RATE_LIMIT_MAX),
+                // An app's own figures, where the general ones do not fit it.
+                maxByApp: parseAppNumbers(this.env.RATE_LIMIT_MAX_BY_APP, 'RATE_LIMIT_MAX_BY_APP'),
+                perAppMaxByApp: parseAppNumbers(this.env.APP_RATE_LIMIT_MAX_BY_APP, 'APP_RATE_LIMIT_MAX_BY_APP'),
             },
             uniqueVisitorWindowHours: parseIntOr(
                 this.env.UNIQUE_VISITOR_WINDOW_HOURS,
@@ -391,6 +418,7 @@ class Config {
         void this.privacy.visitorSecret;
 
         this.validateAdmin();
+        this.warnAboutUnknownRateLimitApps();
 
         if (!this.server.isProduction) {
             this.warnAboutDevelopmentDefaults();
@@ -457,6 +485,21 @@ class Config {
     }
 
     /** Surface the same problems as warnings outside production. */
+    /**
+     * A per-app rate limit figure for an app this configuration does not
+     * list is most likely a typo, and would otherwise never apply without a
+     * word. It is a warning, not an error: an app may also be registered
+     * while the server runs.
+     */
+    warnAboutUnknownRateLimitApps() {
+        const { maxByApp = {}, perAppMaxByApp = {} } = this.server.rateLimit;
+        for (const [field, figures] of [['RATE_LIMIT_MAX_BY_APP', maxByApp], ['APP_RATE_LIMIT_MAX_BY_APP', perAppMaxByApp]]) {
+            for (const appId of Object.keys(figures)) {
+                if (!this.allowed.appId.includes(appId)) logWarning(WarningType.RATE_LIMIT_UNKNOWN_APP, { field, appId });
+            }
+        }
+    }
+
     warnAboutDevelopmentDefaults() {
         if (Object.keys(this.auth.readKeyScopes).length === 0) {
             logWarning(WarningType.READ_API_UNPROTECTED);

package/constants.js

@@ -97,7 +97,7 @@ const DATABASE = {
     QUERY_TIMEOUT_MS: 5_000,
     CONNECT_TIMEOUT_MS: 10_000,
     DEFAULT_PORT: 3306,
-    SCHEMA_VERSION: 'schema_v6',
+    SCHEMA_VERSION: 'schema_v7',
     /** Rows given a public_id per statement when backfilling an old table. */
     BACKFILL_BATCH_SIZE: 500,
 };
@@ -123,6 +123,14 @@ const PRIVACY = {
     /** Owner-only. The secret is what makes visitor hashes irreversible. */
     SECRET_FILE_MODE: 0o600,
     SECRET_FILENAME: '.visitor-secret',
+    /**
+     * How long after its window ended a visitor salt may still exist, so that
+     * instances whose clocks differ by a little agree on the window's salt
+     * right up to its end.
+     */
+    SALT_GRACE_MS: 5 * 60 * 1000,
+    /** How often ended windows' salts are looked for and deleted. */
+    SALT_PRUNE_INTERVAL_MS: 5 * 60 * 1000,
     /** Rejects a key short enough to be guessable. */
     MIN_API_KEY_LENGTH: 32,
     /**
@@ -371,6 +379,8 @@ const ADMIN_SESSIONS_TABLE = '_admin_sessions';
 const VIEW_LOG_TABLE = '_view_log';
 /** Tracking requests that were not stored, counted per minute. */
 const TRACKING_REJECTIONS_TABLE = '_tracking_rejections';
+/** The salt of the current visitor-hash window, deleted when the window ends. */
+const VISITOR_SALTS_TABLE = '_visitor_salts';
 
 /** The tracking pipeline's own bounds. */
 const TRACKING = {
@@ -540,6 +550,7 @@ module.exports = {
     ADMIN_SESSIONS_TABLE,
     VIEW_LOG_TABLE,
     TRACKING_REJECTIONS_TABLE,
+    VISITOR_SALTS_TABLE,
     TRACKING,
     TRACKING_OUTCOME,
     REJECTION_REASON,

package/db/DatabaseManager.js

@@ -33,6 +33,7 @@ const {
 } = require('./adminSchema');
 const LogRepository = require('./LogRepository');
 const AdminRepository = require('./AdminRepository');
+const { createVisitorSaltStore } = require('./visitorSalt');
 
 /**
  * Columns returned for a session lookup.
@@ -182,6 +183,7 @@ class DatabaseManager {
         this.mode = config.mode || 'connect';
         this.logs = new LogRepository(this);
         this.admin = new AdminRepository(this);
+        this.visitorSalts = createVisitorSaltStore(() => this.pool);
     }
 
     /**
@@ -203,6 +205,10 @@ class DatabaseManager {
                 logger.info(`Assigned public IDs to ${result.backfilled} existing row(s) in '${appId}'`);
             }
         }
+
+        // From here on the salts of ended visitor-hash windows are deleted on
+        // the clock, whether or not anyone visits.
+        this.visitorSalts.start();
     }
 
     /** @throws {Error} when a query is attempted before initialize() */
@@ -457,12 +463,19 @@ class DatabaseManager {
 
         // Privacy boundary. Neither the raw IP nor the raw User-Agent is bound
         // into any statement below; only the masked address and the keyed,
-        // rotating hash derived from them.
+        // rotating hash derived from them. The hash is also salted with a
+        // value that is deleted when its window ends, so that afterwards not
+        // even the secret's holder can recompute it.
+        if (!visitorSecret) throw getError(ErrorType.SECRET_UNAVAILABLE);
+        const now = Date.now();
+        const salt = await this.visitorSalts.current(uniqueWindowHours, now);
         const hashedVisitor = PrivacyUtils.generateVisitorHash(
             ip,
             userAgent,
             visitorSecret,
             uniqueWindowHours,
+            now,
+            salt,
         );
         const maskedIp = PrivacyUtils.maskIP(ip);
 
@@ -556,7 +569,8 @@ class DatabaseManager {
      * what it had.
      *
      * @param {string} appId already validated
-     * @param {{ viewId: string, engagedMs: number, scrollDepth: number }} engagement
+     * @param {{ viewId: string, engagedMs: number, scrollDepth: number|null }} engagement
+     *     `scrollDepth` is null for a page that did not scroll, which leaves the stored depth as it was
      * @returns {Promise<boolean>} whether a view was updated
      */
     async addEngagement(appId, { viewId, engagedMs, scrollDepth }) {
@@ -564,11 +578,12 @@ class DatabaseManager {
         const [result] = await this.pool.query(
             `UPDATE \`${appId}\`
              SET engaged_ms = GREATEST(COALESCE(engaged_ms, 0), ?),
-                 scroll_depth = GREATEST(COALESCE(scroll_depth, 0), ?),
+                 scroll_depth = CASE WHEN ? IS NULL THEN scroll_depth
+                                     ELSE GREATEST(COALESCE(scroll_depth, 0), ?) END,
                  last_seen_at = NOW()
              WHERE public_id = ? AND ${LIVE_ROW}
                AND timestamp > DATE_SUB(NOW(), INTERVAL ? HOUR)`,
-            [engagedMs, scrollDepth, viewId, TRACKING.ENGAGE_WINDOW_HOURS]
+            [engagedMs, scrollDepth, scrollDepth, viewId, TRACKING.ENGAGE_WINDOW_HOURS]
         );
         return result.affectedRows > 0;
     }
@@ -813,6 +828,7 @@ class DatabaseManager {
      * Gracefully close all connections
      */
     async close() {
+        this.visitorSalts.stop();
         if (this.pool) {
             await this.pool.end();
             this.pool = null;

package/db/adminSchema.js

@@ -14,6 +14,7 @@ const {
     DATABASE,
     FIELD_MAX_LENGTH,
     TRACKING_REJECTIONS_TABLE,
+    VISITOR_SALTS_TABLE,
     VIEW_LOG_TABLE,
 } = require('../constants');
 const { getError, logWarning, ErrorType, WarningType } = require('../utils/errorUtils');
@@ -61,6 +62,20 @@ const TRACKING_COLUMNS = [
     { name: 'last_seen_at', ddl: 'DATETIME DEFAULT NULL' },
 ];
 
+/**
+ * The salt of the current visitor-hash window (db/visitorSalt.js). One row at
+ * a time: the rows of windows that have ended are deleted, which is the point.
+ */
+const VISITOR_SALTS_DDL = `
+    CREATE TABLE IF NOT EXISTS \`${VISITOR_SALTS_TABLE}\` (
+        \`rotation_hours\` INT UNSIGNED NOT NULL,
+        \`window_id\` BIGINT UNSIGNED NOT NULL,
+        \`salt\` CHAR(64) NOT NULL,
+        \`created_at\` DATETIME NOT NULL,
+        PRIMARY KEY (\`rotation_hours\`, \`window_id\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+`;
+
 /** Indexes the admin columns need, keyed by index name. */
 const ADMIN_INDEXES = {
     uq_public_id: 'UNIQUE INDEX `uq_public_id` (`public_id`)',
@@ -307,6 +322,7 @@ async function ensureLogTables(pool) {
     await pool.query(VIEW_LOG_DDL);
     await pool.query(TRACKING_REJECTIONS_DDL);
     await pool.query(ADMIN_SESSIONS_DDL);
+    await pool.query(VISITOR_SALTS_DDL);
 
     const viewLogColumns = await readColumns(pool, VIEW_LOG_TABLE);
     for (const column of VIEW_LOG_ADDED_COLUMNS) {
@@ -325,6 +341,7 @@ module.exports = {
     VIEW_LOG_ADDED_COLUMNS,
     TRACKING_REJECTIONS_DDL,
     ADMIN_SESSIONS_DDL,
+    VISITOR_SALTS_DDL,
     NEW_TABLE_ADMIN_COLUMNS,
     NEW_TABLE_ADMIN_INDEXES,
     backfillPublicIds,

package/db/visitorSalt.js

@@ -0,0 +1,137 @@
+/**
+ * The salt of each visitor-hash window.
+ *
+ * A visitor hash is keyed with the server secret and with a random salt that
+ * exists only for the window it belongs to. Once the window is over the salt
+ * is deleted, and from then on nobody, the operator included, can recompute a
+ * hash of that window from a known address and browser: the records it left
+ * can no longer be tied to anyone.
+ *
+ * The salt lives in the database so that a restart, or a second instance,
+ * within the window keeps telling the same visitors apart. It is useless
+ * without the server secret, which is never in the database.
+ *
+ * Deletion goes by the clock, not by traffic: a salt is removed a few minutes
+ * after its window ended (the grace covers instances whose clocks differ),
+ * by a timer and by every read, whether or not another view ever arrives.
+ */
+
+const crypto = require('crypto');
+
+const { PRIVACY, VISITOR_SALTS_TABLE } = require('../constants');
+const PrivacyUtils = require('../utils/privacyUtils');
+const { getError, logWarning, ErrorType, WarningType } = require('../utils/errorUtils');
+
+const TABLE = `\`${VISITOR_SALTS_TABLE}\``;
+const SALT_PATTERN = new RegExp(`^[0-9a-f]{${PRIVACY.SECRET_BYTES * 2}}$`);
+const MS_PER_HOUR = 60 * 60 * 1000;
+
+/** When the window `windowId` of length `hours` is over, in epoch millis. */
+const windowEnd = (hours, windowId) => (windowId + 1) * hours * MS_PER_HOUR;
+
+/**
+ * @param {() => { query: Function }} getPool the manager's pool, read on each use
+ * @returns {{
+ *   current: (rotationHours: number, now?: number) => Promise<string>,
+ *   prune: (now?: number) => Promise<number>,
+ *   start: (intervalMs?: number) => void,
+ *   stop: () => void,
+ * }}
+ */
+function createVisitorSaltStore(getPool) {
+    /**
+     * The salts in use, and the reads under way, by `hours:windowId`. The
+     * service hashes page views and custom events over different window
+     * lengths, so there is one entry per length in use: a handful at most.
+     * @type {Map<string, { salt?: string, promise?: Promise<string>, end: number }>}
+     */
+    const windows = new Map();
+    let timer = null;
+
+    /** Forget, in memory too, every window that is over. */
+    function forgetEnded(now) {
+        for (const [key, entry] of windows) {
+            if (entry.end + PRIVACY.SALT_GRACE_MS <= now) windows.delete(key);
+        }
+    }
+
+    /**
+     * Delete the salt of every window that ended more than the grace ago.
+     * @param {number} [now] epoch millis
+     * @returns {Promise<number>} salts deleted
+     */
+    async function prune(now = Date.now()) {
+        forgetEnded(now);
+        const [result] = await getPool().query(
+            `DELETE FROM ${TABLE} WHERE (window_id + 1) * rotation_hours * ${MS_PER_HOUR} + ? <= ?`,
+            [PRIVACY.SALT_GRACE_MS, now]);
+        return (result && result.affectedRows) || 0;
+    }
+
+    async function read(hours, windowId, now) {
+        const pool = getPool();
+        // Whoever gets there first decides the window's salt; everyone reads that one.
+        await pool.query(
+            `INSERT IGNORE INTO ${TABLE} (rotation_hours, window_id, salt, created_at) VALUES (?, ?, ?, NOW())`,
+            [hours, windowId, crypto.randomBytes(PRIVACY.SECRET_BYTES).toString('hex')]);
+        const [rows] = await pool.query(
+            `SELECT salt FROM ${TABLE} WHERE rotation_hours = ? AND window_id = ?`, [hours, windowId]);
+        const salt = Array.isArray(rows) && rows[0] ? rows[0].salt : null;
+        // Failing closed is deliberate: a hash made without the salt would
+        // stay recomputable for ever while looking like the others.
+        if (typeof salt !== 'string' || !SALT_PATTERN.test(salt)) throw getError(ErrorType.SECRET_UNAVAILABLE);
+        // A new window is the moment the one before it ended.
+        await prune(now);
+        return salt;
+    }
+
+    return {
+        /**
+         * @param {number} rotationHours the unique-visitor window
+         * @param {number} [now] epoch millis; pass the same value to the hash
+         * @returns {Promise<string>} hex salt of the window `now` falls in
+         */
+        async current(rotationHours, now = Date.now()) {
+            const hours = PrivacyUtils.rotationHours(rotationHours);
+            const windowId = PrivacyUtils.currentWindowId(hours, now);
+            const key = `${hours}:${windowId}`;
+            const known = windows.get(key);
+            if (known) return known.salt || known.promise;
+
+            const entry = { end: windowEnd(hours, windowId) };
+            entry.promise = read(hours, windowId, now).then((salt) => {
+                entry.salt = salt;
+                return salt;
+            }, (error) => {
+                // Nothing is remembered of a failed read: the next view tries again.
+                if (windows.get(key) === entry) windows.delete(key);
+                throw error;
+            });
+            windows.set(key, entry);
+            return entry.promise;
+        },
+
+        prune,
+
+        /**
+         * Prune now and then on an interval, so a salt goes when its window
+         * ends even on a site nobody visits for days. The timer is unref'd:
+         * it never keeps the process alive on its own.
+         * @param {number} [intervalMs]
+         */
+        start(intervalMs = PRIVACY.SALT_PRUNE_INTERVAL_MS) {
+            if (timer) return;
+            const run = () => prune().catch((cause) => logWarning(WarningType.SALT_PRUNE_FAILED, { cause: cause.message }));
+            run();
+            timer = setInterval(run, intervalMs);
+            timer.unref();
+        },
+
+        stop() {
+            clearInterval(timer);
+            timer = null;
+        },
+    };
+}
+
+module.exports = { createVisitorSaltStore };

package/index.js

@@ -7,7 +7,7 @@ const config = require('./config');
 const DatabaseManager = require('./db/DatabaseManager');
 const logger = require('./utils/logger');
 const { buildCorsOptions, countRefusedPreflights } = require('./middleware/security');
-const { createAnalyticsRouter, buildPerIpLimiters, trackingSourceFor } = require('./routes/analytics');
+const { createAnalyticsRouter, buildPerIpLimiter, trackingSourceFor } = require('./routes/analytics');
 const { createAdminRouter } = require('./routes/admin');
 const { startRetention } = require('./db/retention');
 const { createDbSessionStore } = require('./db/adminSessionStore');
@@ -80,7 +80,8 @@ function createApp() {
 
     // A tracking request turned away here is counted in the tracking log like
     // any other refusal (in memory, written in batches).
-    app.use(buildPerIpLimiters(config.server.rateLimit, (req) => {
+    // (Engagement reports have a limiter of their own, on their route.)
+    app.use(buildPerIpLimiter(config.server.rateLimit, (req) => {
         if (trackingSourceFor(req.path)) router.countRejection(req, REJECTION_REASON.RATE_LIMITED, { detail: 'ip' });
     }));
 

package/middleware/security.js

@@ -70,6 +70,23 @@ function requestOrigin(req) {
     }
 }
 
+/**
+ * The app a tracking request is for, read from the one place its route
+ * validates and stores: the query of a GET, the body of anything else.
+ *
+ * Everything that decides by app before validation (the origin check, the
+ * rate limits) must read it here. Reading "query, or else body" let a POST
+ * name one app in its query, be checked and limited as that app, and then be
+ * stored under the other app named in its body.
+ *
+ * @param {import('express').Request} req
+ * @returns {string} the appId, or '' when absent or not a string
+ */
+function requestedAppId(req) {
+    const appId = req.method === 'GET' ? req.query?.appId : req.body?.appId;
+    return typeof appId === 'string' ? appId : '';
+}
+
 /**
  * Bind writes for an appId to the site origins registered for it.
  *
@@ -92,8 +109,8 @@ function requireRegisteredOrigin(allowed, { onReject = () => {} } = {}) {
     const origins = allowed?.origins || {};
 
     return (req, res, next) => {
-        const appId = req.query.appId || req.body?.appId;
-        const registered = origins[appId];
+        const appId = requestedAppId(req);
+        const registered = Object.hasOwn(origins, appId) ? origins[appId] : undefined;
 
         if (!Array.isArray(registered) || registered.length === 0) {
             return next();
@@ -128,6 +145,7 @@ module.exports = {
     buildCorsOptions,
     countRefusedPreflights,
     requireRegisteredOrigin,
+    requestedAppId,
     requestOrigin,
     noStore,
 };

package/middleware/validation.js

@@ -103,7 +103,9 @@ const validateEngage = (allowedValues) => [
         .matches(UUID_PATTERN).withMessage('id must be a view ID'),
     body('ms')
         .isInt({ min: 0, max: TRACKING.MAX_ENGAGED_MS }).withMessage(`ms must be an integer between 0 and ${TRACKING.MAX_ENGAGED_MS}`),
+    // Absent for a page that fits its window: there was nothing to scroll.
     body('scroll')
+        .optional({ values: 'null' })
         .isInt({ min: 0, max: 100 }).withMessage('scroll must be an integer between 0 and 100'),
 ];
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@harshankur/viewcounter",
   "description": "A middleware backend server that registers views to my db server when requested to register a view from my other projects.",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "main": "index.js",
   "engines": {
     "node": ">=24"
@@ -49,7 +49,7 @@
     "i18n-iso-countries": "^7.14.0",
     "jest": "^30.4.2",
     "jest-html-reporter": "^4.4.0",
-    "supertest": "^7.2.2",
+    "supertest": "^7.3.1",
     "topojson-client": "^3.1.0",
     "world-atlas": "^2.0.2"
   },

package/routes/analytics.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const express = require('express');
 const rateLimit = require('express-rate-limit');
+const { ipKeyGenerator } = rateLimit;
 const geoip = require('geoip-country');
 
 const {
@@ -21,7 +22,7 @@ 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, requestOrigin, noStore } = require('../middleware/security');
+const { requireRegisteredOrigin, requestedAppId, requestOrigin, noStore } = require('../middleware/security');
 const { createRejectionCounter } = require('../db/rejectionCounter');
 const { hostnameOf, primaryLanguage, utmTags } = require('../utils/visitorContext');
 const {
@@ -132,21 +133,24 @@ function intQuery(req, name, fallback) {
  * @returns {import('express').RequestHandler}
  */
 function buildPerAppLimiter(rateLimitConfig, onLimit = () => {}) {
-    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();
+    const { perAppMax, windowMs, perAppMaxByApp = {} } = rateLimitConfig || {};
+    // An app's own figure wins over the general one; zero means no ceiling.
+    const limitOf = (req) => (Object.hasOwn(perAppMaxByApp, appOf(req)) ? perAppMaxByApp[appOf(req)] : perAppMax) || 0;
+    // Nothing set anywhere disables it, for single-tenant deployments where
+    // the per-IP limit is the only bound that means anything.
+    if (!(perAppMax > 0) && !Object.values(perAppMaxByApp).some((value) => value > 0)) return (req, res, next) => next();
 
     return rateLimit({
         windowMs,
-        limit: perAppMax,
+        limit: limitOf,
+        skip: (req) => limitOf(req) <= 0,
         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__'),
+        keyGenerator: (req) => appOf(req) || '__unattributed__',
         validate: { keyGeneratorIpFallback: false },
         handler: (req, res, next, options) => {
             onLimit(req);
@@ -159,34 +163,71 @@ function buildPerAppLimiter(rateLimitConfig, onLimit = () => {}) {
 const isEngagement = (req) => trackingSourceFor(req.path) === VIEW_LOG_SOURCE.ENGAGE;
 
 /**
- * The per-IP limiters: one budget for engagement reports, one for everything
- * else, each of `max` requests per window.
+ * The app a request is limited as: for a tracking request, the app its route
+ * goes on to validate and store under; for anything else, none. A read or
+ * admin call cannot name an app to borrow that app's figures.
+ */
+const appOf = (req) => (trackingSourceFor(req.path) ? requestedAppId(req) : '');
+
+/**
+ * A per-IP limiter: `max` requests per window from one address, or the app's
+ * own figure (`maxByApp`) for tracking requests to an app that has one. Zero
+ * means no limit, as the general figure or as an app's own.
  *
- * They are separate because a page being read reports its engagement every
+ * There are two of these, with separate budgets: one for engagement reports
+ * and one for everything else. A page being read reports its engagement every
  * half minute. On one shared budget, a few dozen readers behind one address
  * (an office, a campus) would use it up with those reports alone, and the page
  * views of everyone at that address would be refused. Apart, reports can only
  * ever crowd out other reports.
  *
- * @param {{ max: number, windowMs: number }} rateLimitConfig
+ * An app with its own figure is counted on its own, per address: a site that
+ * records far more per visitor than the others (every step inside a
+ * single-page app, say) gets the room it needs without loosening the limit
+ * for every other app, and without using up the address's budget for them.
+ *
+ * @param {{ max: number, windowMs: number, maxByApp?: Record<string, number> }} rateLimitConfig
  * @param {(req: import('express').Request) => void} [onLimit] called for a refused request
- * @returns {import('express').RequestHandler[]}
+ * @param {{ engagement?: boolean }} [options] true for the limiter of engagement
+ *     reports, which is mounted on that route so it can know the app; false
+ *     (the default) for the limiter of everything else, mounted app-wide
+ * @returns {import('express').RequestHandler}
  */
-function buildPerIpLimiters(rateLimitConfig, onLimit = () => {}) {
-    const { max, windowMs } = rateLimitConfig || {};
-    const limiter = (skip) => rateLimit({
+function buildPerIpLimiter(rateLimitConfig, onLimit = () => {}, { engagement = false } = {}) {
+    const { max = 0, windowMs, maxByApp = {} } = rateLimitConfig || {};
+    const ownFigure = (req) => (Object.hasOwn(maxByApp, appOf(req)) ? maxByApp[appOf(req)] : null);
+    const pass = (req, res, next) => next();
+    const shared = {
         windowMs,
-        limit: max,
         message: { message: 'Too many requests, please try again later.' },
         standardHeaders: true,
         legacyHeaders: false,
-        skip,
         handler: (req, res, next, options) => {
             onLimit(req);
             res.status(options.statusCode).json(options.message);
         },
-    });
-    return [limiter(isEngagement), limiter((req) => !isEngagement(req))];
+    };
+
+    // The general budget keeps the library's own key (the address) and, with
+    // it, the library's checks for a misconfigured proxy.
+    const general = max > 0 ? rateLimit({ ...shared, limit: max }) : pass;
+    // Apps with a figure of their own: one counter per address and app.
+    const own = Object.values(maxByApp).some((value) => value > 0)
+        ? rateLimit({
+            ...shared,
+            limit: (req) => ownFigure(req),
+            keyGenerator: (req) => `${ipKeyGenerator(req.ip)}|${appOf(req)}`,
+        })
+        : pass;
+
+    return (req, res, next) => {
+        // The reports' limiter is the one on their route: POST /engage.
+        const isReport = isEngagement(req) && req.method === 'POST';
+        if (isReport !== engagement) return next();
+        const figure = ownFigure(req);
+        if (figure === null) return general(req, res, next);
+        return figure > 0 ? own(req, res, next) : next();
+    };
 }
 
 /**
@@ -271,6 +312,11 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true, geo =
     // views refused because of the reports those readers' pages send.
     const limitEngagePerApp = buildPerAppLimiter(config.server?.rateLimit,
         (req) => reject(req, REJECTION_REASON.RATE_LIMITED, { detail: 'app' }));
+    // Per address too. This one sits on the route, not app-wide with the
+    // other, so it runs after the beacon's body is read and knows the app.
+    const readBeacon = express.text({ type: () => true, limit: TRACKING.ENGAGE_BODY_BYTES });
+    const limitEngagePerIp = buildPerIpLimiter(config.server?.rateLimit,
+        (req) => reject(req, REJECTION_REASON.RATE_LIMITED, { detail: 'ip' }), { engagement: true });
     const trackingValidation = handleTrackingValidation(reject);
 
     /** Views from these are counted in the tracking log and never stored. */
@@ -466,8 +512,12 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true, geo =
      * far it was scrolled, sent by the tracker when the page is hidden or left.
      */
     router.post('/engage',
-        express.text({ type: () => true, limit: TRACKING.ENGAGE_BODY_BYTES }),
+        // A body that cannot be read (too large, say) still counts against
+        // the address before it is refused: the app is unknown, so by the
+        // general figure.
+        (req, res, next) => readBeacon(req, res, (error) => (error ? limitEngagePerIp(req, res, () => next(error)) : next())),
         parseBeaconBody,
+        limitEngagePerIp,
         limitEngagePerApp,
         requireOrigin,
         validateEngage(config.allowed),
@@ -480,7 +530,7 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true, geo =
                 const updated = await dbManager.addEngagement(appId, {
                     viewId: id,
                     engagedMs: Number(ms),
-                    scrollDepth: Number(scroll),
+                    scrollDepth: scroll === undefined || scroll === null ? null : Number(scroll),
                 });
                 if (!updated) reject(req, REJECTION_REASON.UNKNOWN_VIEW);
                 return res.status(HTTP_STATUS.NO_CONTENT).end();
@@ -680,4 +730,4 @@ function createAnalyticsRouter({ config, dbManager, isReady = () => true, geo =
     return router;
 }
 
-module.exports = { createAnalyticsRouter, buildPerIpLimiters, handleRouteError, logContext, withRequestId, trackingSourceFor };
+module.exports = { createAnalyticsRouter, buildPerIpLimiter, handleRouteError, logContext, withRequestId, trackingSourceFor };

package/tracker/tracker.js

@@ -1,17 +1,31 @@
 /*!
- * viewcounter tracker, https://viewcounter.harshankur.com
+ * viewcounter tracker
+ *
+ * If you found this on a site you were visiting: this is viewcounter, a
+ * privacy-first view counter that the site runs on its own server. It is built
+ * for GDPR compliance:
+ *   - it sets no cookie and stores nothing on your device;
+ *   - it sends nothing that identifies you or your device;
+ *   - the server never stores your IP address or your browser's user agent.
+ *     It keeps a masked address, a visitor hash that changes every day by
+ *     default, and coarse details such as your country, browser and system,
+ *     so nothing it keeps identifies you directly.
+ * Check it yourself: the source is at https://github.com/harshankur/viewcounter
+ * and the homepage at https://viewcounter.harshankur.com.
+ *
+ * For site owners:
  *
  *   <script defer src="https://your-server/tracker.js" data-app="blog"></script>
  *
  * Records a view of each page (including page changes in single-page apps),
- * how long it was visible and how far it was scrolled (reported when the page
+ * how long it was visible and, on a page that scrolls, how far (reported when the page
  * is hidden or left, and every half minute while it is being read), clicks on links to
  * other sites and on downloads, and the campaign tags of the landing URL.
  * The page before is sent as its origin and path only.
  *
  * It stores nothing on the visitor's device (no cookie, no localStorage, no
  * sessionStorage), so it needs no consent banner, and it sends no identifier:
- * the server tells repeat visits apart with a hash it rotates every day.
+ * the server tells repeat visits apart with a hash it rotates every day by default.
  *
  * Options, as attributes on the script tag:
  *   data-app="blog"                 required: the app ID the views belong to
@@ -23,6 +37,7 @@
  *                                   these as its own page (hash-routed pages)
  *   data-heartbeat="false"          report time on page only when the page is
  *                                   hidden or left, not while it is being read
+ *   data-campaigns="false"          do not send the landing URL's utm_* tags
  *   data-outbound="false"           do not record clicks on links to other sites
  *   data-downloads="false"          do not record clicks on downloads
  *   data-respect-dnt="true"         send nothing when Do Not Track is on
@@ -53,10 +68,19 @@
     const IDLE_MS = 30 * 60 * 1000;
 
     const deviceSize = () => (innerWidth < 768 ? 'small' : innerWidth < 1200 ? 'medium' : 'large');
-    /** How much of the page has been on screen, from 0 to 100. */
+    /**
+     * How much of the page has been on screen, from 0 to 100, or null for a
+     * page that fits the window: there is nothing to scroll, so "all of it"
+     * would say nothing about the reader.
+     */
     const seen = () => {
         const height = Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0);
-        return height <= 0 ? 100 : Math.min(100, Math.round(((scrollY + innerHeight) / height) * 100));
+        return height <= innerHeight + 1 ? null : Math.min(100, Math.round(((scrollY + innerHeight) / height) * 100));
+    };
+    /** Note how far the page on screen has been scrolled, if it scrolls at all (it may have grown since it loaded). */
+    const measure = () => {
+        const depth = view ? seen() : null;
+        if (depth !== null) view.scroll = Math.max(view.scroll === null ? 0 : view.scroll, depth);
     };
 
     /** A URL's origin and path: its query and fragment can carry tokens or emails. */
@@ -85,10 +109,12 @@
     function reportEngagement(of = view, alive = false) {
         if (!of || !of.id) return;
         const ms = Math.min(MAX_ENGAGED_MS, Math.round(of.visibleMs + (of.visibleSince === null ? 0 : performance.now() - of.visibleSince)));
-        if (!alive && ms <= of.sentMs && of.scroll <= of.sentScroll) return;
+        const scroll = of.scroll === null ? -1 : of.scroll;
+        if (!alive && ms <= of.sentMs && scroll <= of.sentScroll) return;
         of.sentMs = ms;
-        of.sentScroll = of.scroll;
-        const body = JSON.stringify({ appId: app, id: of.id, ms, scroll: of.scroll });
+        of.sentScroll = scroll;
+        // A page that never scrolled reports its time alone.
+        const body = JSON.stringify({ appId: app, id: of.id, ms, scroll: of.scroll === null ? undefined : of.scroll });
         // text/plain needs no CORS preflight, so the beacon survives the page closing.
         if (!(navigator.sendBeacon && navigator.sendBeacon(`${base}engage`, new Blob([body], { type: 'text/plain' })))) {
             fetch(`${base}engage`, { method: 'POST', body, keepalive: true, credentials: 'omit', headers: { 'Content-Type': 'text/plain' } })
@@ -98,11 +124,15 @@
 
     function pageview() {
         // The page being left stops counting here, and reports what it has.
+        // It is still the one on screen (a single-page app draws the next
+        // only after changing the address), so this is its last measure.
         if (view) {
             if (view.visibleSince !== null) view.visibleMs += performance.now() - view.visibleSince;
             view.visibleSince = null;
+            measure();
             reportEngagement();
         }
+        const first = !view;
         const params = new URLSearchParams({
             appId: app,
             deviceSize: deviceSize(),
@@ -112,10 +142,12 @@
         });
         // Only the campaign tags: the rest of a query string can carry
         // emails, tokens, or IDs, and never leaves the page.
-        const query = new URLSearchParams(location.search);
-        for (const key of UTM) {
-            const value = query.get(key);
-            if (value) params.set(key, value.slice(0, 100));
+        if (option('campaigns', true)) {
+            const query = new URLSearchParams(location.search);
+            for (const key of UTM) {
+                const value = query.get(key);
+                if (value) params.set(key, value.slice(0, 100));
+            }
         }
 
         const current = {
@@ -123,11 +155,15 @@
             startedAt: Date.now(),
             visibleMs: 0,
             visibleSince: document.visibilityState === 'visible' ? performance.now() : null,
-            scroll: seen(),
+            scroll: null,
             sentMs: 0,
-            sentScroll: 0,
+            sentScroll: -1,
         };
         view = current;
+        // A page that has just loaded can be measured. After a navigation the
+        // old page is still on screen, and its depth is not the new one's:
+        // the new page is measured when it is scrolled, hidden, or reports.
+        if (first) measure();
         fetch(`${base}registerView?${params}`, { keepalive: true, credentials: 'omit', referrerPolicy: 'no-referrer' })
             .then((response) => (response.ok ? response.json() : null))
             .then((result) => {
@@ -186,7 +222,7 @@
         scrollQueued = true;
         requestAnimationFrame(() => {
             scrollQueued = false;
-            if (view) view.scroll = Math.max(view.scroll, seen());
+            measure();
         });
     }, { passive: true });
 
@@ -195,12 +231,13 @@
         if (document.visibilityState === 'hidden') {
             if (view.visibleSince !== null) view.visibleMs += performance.now() - view.visibleSince;
             view.visibleSince = null;
+            measure();
             reportEngagement();
         } else if (view.visibleSince === null) {
             view.visibleSince = performance.now();
         }
     });
-    addEventListener('pagehide', () => reportEngagement());
+    addEventListener('pagehide', () => { measure(); reportEngagement(); });
 
     // While the page is being read, report as it goes: the server then knows the
     // visitor is still there, and a tab the browser kills without warning (common
@@ -215,6 +252,7 @@
             if (!view || document.visibilityState !== 'visible' || performance.now() - lastInput > IDLE_MS) return;
             // The server takes reports for a view for a day. A page open longer says no more.
             if (Date.now() - view.startedAt > ENGAGE_WINDOW_MS) return;
+            measure();
             reportEngagement(view, true);
         }, HEARTBEAT_MS);
     }

package/utils/errorUtils.js

@@ -48,6 +48,8 @@ const WarningType = {
     TRACKING_LOG_WRITE_FAILED: 'TRACKING_LOG_WRITE_FAILED',
     ADMIN_LOG_WRITE_FAILED: 'ADMIN_LOG_WRITE_FAILED',
     TRASH_PURGE_FAILED: 'TRASH_PURGE_FAILED',
+    SALT_PRUNE_FAILED: 'SALT_PRUNE_FAILED',
+    RATE_LIMIT_UNKNOWN_APP: 'RATE_LIMIT_UNKNOWN_APP',
 };
 
 /**
@@ -124,6 +126,10 @@ const WARNING_MESSAGES = {
         `Automatic view log pruning failed: ${info?.cause}`,
     [WarningType.TRASH_PURGE_FAILED]: (info) =>
         `Automatic trash purge failed for '${info?.appId}': ${info?.cause}`,
+    [WarningType.RATE_LIMIT_UNKNOWN_APP]: (info) =>
+        `${info?.field} names '${info?.appId}', which is not one of the configured apps: its figure applies only if an app of that name is registered later`,
+    [WarningType.SALT_PRUNE_FAILED]: (info) =>
+        `Could not delete the visitor salts of ended windows (it is tried again shortly): ${info?.cause}`,
 };
 
 /**

package/utils/privacyUtils.js

@@ -61,8 +61,17 @@ class PrivacyUtils {
      * @returns {number}
      */
     static currentWindowId(rotationHours, now = Date.now()) {
-        const hours = Math.max(Number(rotationHours) || 0, MIN_ROTATION_HOURS);
-        return Math.floor(now / (hours * MS_PER_HOUR));
+        return Math.floor(now / (this.rotationHours(rotationHours) * MS_PER_HOUR));
+    }
+
+    /**
+     * The length of a rotation window, in hours: the unique-visitor window,
+     * and never less than MIN_ROTATION_HOURS.
+     * @param {number} rotationHours
+     * @returns {number}
+     */
+    static rotationHours(rotationHours) {
+        return Math.max(Number(rotationHours) || 0, MIN_ROTATION_HOURS);
     }
 
     /**
@@ -80,6 +89,10 @@ class PrivacyUtils {
      * @param {string} secret Server secret from utils/secretStore.js
      * @param {number} [rotationHours] Window length, defaults to the unique-visitor window
      * @param {number} [now] epoch millis, injectable for tests
+     * @param {string} [salt] The window's own salt (db/visitorSalt.js), which
+     *     is deleted when the window ends. With it, a hash cannot be recomputed
+     *     afterwards even by whoever holds the secret. Without it, the window
+     *     id alone separates the windows, and the secret holder still can.
      * @returns {string} HMAC-SHA-256 hex digest
      * @throws {Error} ErrorType.SECRET_UNAVAILABLE when no secret is supplied
      */
@@ -89,6 +102,7 @@ class PrivacyUtils {
         secret,
         rotationHours = SERVER.DEFAULT_UNIQUE_VISITOR_WINDOW_HOURS,
         now = Date.now(),
+        salt = '',
     ) {
         if (!secret) {
             // Failing closed is deliberate: silently hashing without the key
@@ -98,7 +112,8 @@ class PrivacyUtils {
         }
 
         const windowId = this.currentWindowId(rotationHours, now);
-        const input = `${ip}|${userAgent}|${windowId}`;
+        // The unsalted form is kept byte for byte, for callers that use this helper on its own.
+        const input = salt ? `${salt}|${ip}|${userAgent}|${windowId}` : `${ip}|${userAgent}|${windowId}`;
 
         return crypto.createHmac('sha256', secret).update(input).digest('hex');
     }