tacilytics 2.4.0 → 2.4.1

package/README.md

@@ -136,7 +136,7 @@ Server mode runs no script and reads or stores nothing on the visitor's device.
 
 ```http
 POST /api/v1/hit
-Authorization: Bearer tk_…            # a key created with write access (Settings → API keys), not read-only
+Authorization: Bearer tk_…            # a "server mode (count only)" key (Settings → API keys)
 Content-Type: application/json
 
 { "domain": "example.com", "path": "/shop?utm_source=news", "ip": "203.0.113.7",
@@ -144,21 +144,33 @@ Content-Type: application/json
   "purpose": "<Sec-Purpose or Purpose header>" }
 ```
 
-Node / Express, after your static files and before your pages:
+Node / Express, after your static files and before your pages. It reports only page loads that ended with `200` (no 404s, no redirects) and only for clients that asked for HTML:
 
 ```js
 app.use((req, res, next) => {
-  if (req.method === 'GET' && req.accepts('html')) fetch('https://analytics.example.com/api/v1/hit', {
-    method: 'POST', headers: { Authorization: 'Bearer ' + process.env.TACILYTICS_KEY, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ domain: 'example.com', path: req.originalUrl, ip: req.ip, ua: req.get('user-agent'),
-      referrer: req.get('referer'), lang: req.get('accept-language'), purpose: req.get('sec-purpose') || req.get('purpose') }),
-  }).catch(() => {});
+  if (req.method !== 'GET' || req.accepts(['html', 'json']) !== 'html') return next();
+  res.on('finish', () => {
+    if (res.statusCode !== 200) return;
+    fetch('https://analytics.example.com/api/v1/hit', {
+      method: 'POST', headers: { Authorization: 'Bearer ' + process.env.TACILYTICS_KEY, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ domain: 'example.com', path: req.originalUrl, ip: req.ip, ua: req.get('user-agent'),
+        referrer: req.get('referer'), lang: req.get('accept-language'), purpose: req.get('sec-purpose') || req.get('purpose') }),
+    }).then((r) => { if (r.status === 429) console.warn('tacilytics: rate limited'); }).catch(() => {});
+  });
   next();
 });
 ```
 
-- **The visitor IP** is only accepted here, with a write key, never on the public `/api/collect`. It is hashed like a tracker hit (daily salt) and never stored. Behind a proxy or load balancer, send the real visitor IP (e.g. `req.ip` with Express `trust proxy` set right), not your proxy's. Without an IP the hit is refused (`400`), because all visitors would fall onto one hash.
-- **Filtered on our side:** bots and monitors (same list as the tracker), requests without a user agent, prefetch / prerender (`purpose`), and `dnt: true` / `gpc: true` if you choose to forward those headers. A site-limited key can only report for its own sites.
+**Which key goes on the web server.** Web servers are where sites get broken into, so the key there should be able to do as little as possible:
+
+- Create a **server mode (count only)** key under Settings → API keys (admin or owner) and tick the site(s) it reports for. It can call `POST /api/v1/hit` for those sites and nothing else (`403` everywhere else, reads included), and it never reaches more than the account that created it.
+- **Never** put the `API_KEY` from `.env` on a web server. It is the owner key for every site on the instance.
+- Don't use a read + write key either. It still works on `/api/v1/hit` (as in 2.4.0), but a stolen one can also create public share links, point alert webhooks at any URL, upload or delete imports, and change notes, funnels and the time zone of its sites.
+- If several sites run on different servers, give each server its own key, so one break-in can be revoked without touching the others.
+- Server-mode keys arrived in 2.4.1. Before downgrading to 2.4.0, delete them: 2.4.0 does not know the scope and would treat them as ordinary read-only keys.
+
+- **The visitor IP** is only accepted here, with a server-mode or write key, never on the public `/api/collect`. It is hashed like a tracker hit (daily salt) and never stored. Behind a proxy or load balancer, send the real visitor IP (e.g. `req.ip` with Express `trust proxy` set right), not your proxy's. Without an IP the hit is refused (`400`), because all visitors would fall onto one hash.
+- **Filtered on our side:** bots and monitors (same list as the tracker), requests without a user agent, prefetch / prerender (`purpose`), and `dnt: true` / `gpc: true` if you choose to forward those headers. A key can only report for its own sites. The rate limit (6,000 page views a minute) applies per key, so sites on one shared-hosting IP don't block each other; above it the API answers `429` and the hit is not counted.
 - **Page caches and CDNs:** if a cache plugin or a CDN (e.g. Cloudflare) answers the request, your server code never runs and the visit is not reported. Report from somewhere every request passes, or exclude HTML from the cache.
 - **What you give up compared with the script:** no time on page, no scroll depth, no click / outbound / download events, no country, and no `?tacilytics=off`. Server-side goals work: add `"name": "Purchase", "props": { "value": 49.9 }`.
 - **Data protection:** the IP and user agent are personal data while they are hashed. That needs a legal basis (typically legitimate interest, GDPR Art. 6(1)(f)) and a sentence in your privacy policy. If someone else runs Tacilytics for you (for example Tacilytics Cloud), your server passes visitor IPs to them, so you need a data processing agreement (DPA). Server mode does not decide whether you need consent for the rest of your website. This is not legal advice.
@@ -273,7 +285,7 @@ curl -H "Authorization: Bearer $TACILYTICS_API_KEY" \
 | `POST /api/v1/sites` | add a site `{ domain }` |
 | `GET /api/v1/stats?site=&period=` | aggregated stats — `today \| 7d \| 30d \| 90d \| 12mo`, or `from=YYYY-MM-DD&to=YYYY-MM-DD` |
 | `GET /api/v1/realtime?site=` | online count, 30-min pulse + recent events |
-| `POST /api/v1/hit` | server mode: report a page view from your web server (write key), see [Server mode](#server-mode-no-script-at-all) |
+| `POST /api/v1/hit` | server mode: report a page view from your web server (server-mode key), see [Server mode](#server-mode-no-script-at-all) |
 
 Add any of `country, source, page, browser, os, device, lang, medium, campaign, goal` to `/stats` to segment, e.g. `…/stats?site=example.com&period=30d&country=DE&medium=email`.
 

package/auth.js

@@ -180,6 +180,11 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     );
   `);
 
+  // 2.4.1: key scopes. '' = the old behaviour (read-only or the account's own rights); 'hit' = server mode only,
+  // usable for POST /api/v1/hit on the listed sites and nothing else. Existing keys keep scope '' (unchanged).
+  for (const [col, decl] of [['scope', "TEXT NOT NULL DEFAULT ''"], ['sites', 'TEXT']]) {
+    if (!db.prepare('PRAGMA table_info(api_keys)').all().some((c) => c.name === col)) db.exec(`ALTER TABLE api_keys ADD COLUMN ${col} ${decl}`);
+  }
   const q = {
     userCount: db.prepare('SELECT COUNT(*) n FROM users'),
     ownerCount: db.prepare("SELECT COUNT(*) n FROM users WHERE role = 'owner'"),
@@ -204,13 +209,14 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
   // after the response is sent. Handlers can name the action/target via res.locals.audit;
   // otherwise method + route are recorded. New endpoints are covered without remembering to.
   // Not logged: tracking beacons, sign-in steps, WebAuthn option requests (no state change).
-  const AUDIT_SKIP = new Set(['/api/collect', '/auth/login', '/auth/login/totp', '/auth/passkey/options', '/auth/passkey/verify', '/auth/logout', '/api/me/passkeys/options', '/api/me/totp/setup']);
+  const AUDIT_SKIP = new Set(['/api/collect', '/auth/login', '/auth/login/totp', '/auth/passkey/options', '/auth/passkey/verify', '/auth/logout', '/api/me/passkeys/options', '/api/me/totp/setup', '/api/v1/hit']);
   const AUDIT_DAYS = Math.max(30, parseInt(process.env.AUDIT_RETENTION_DAYS, 10) || 365);
   const insAudit = db.prepare('INSERT INTO audit_log (ts, actor, action, target, ip) VALUES (?, ?, ?, ?, ?)');
   function actorOf(p) {
     if (!p) return null;
     if (p.kind === 'user') return p.user.username;
     if (p.kind === 'userkey') return p.user.username + ' (API key)';
+    if (p.kind === 'hitkey') return p.user.username + ' (server-mode key)';
     if (p.kind === 'apikey') return 'API key';
     if (p.kind === 'legacy') return 'passphrase';
     return null;
@@ -256,8 +262,14 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
         const u = k && q.userById.get(k.user_id);
         if (!u) return null;
         if (!k.last_used || Date.now() - k.last_used > 60000) db.prepare('UPDATE api_keys SET last_used = ? WHERE id = ?').run(Date.now(), k.id);
+        const userSites = u.sites ? JSON.parse(u.sites) : null;
+        if (k.scope === 'hit') {
+          // never more than the account itself may see today (an account limited later narrows its old keys too)
+          const ks = JSON.parse(k.sites || '[]').filter((id) => userSites == null || userSites.includes(id));
+          return { kind: 'hitkey', role: 'viewer', sites: ks, user: u, keyId: k.id };
+        }
         const role = k.read_only ? 'viewer' : u.role;
-        return { kind: 'userkey', role, sites: u.sites ? JSON.parse(u.sites) : null, user: u, keyId: k.id };
+        return { kind: 'userkey', role, sites: userSites, user: u, keyId: k.id };
       }
       return null; // a wrong key is a failed sign-in, not an anonymous request
     }
@@ -278,6 +290,8 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
   function auth(req, res, next) {
     const p = principal(req);
     if (!p) return res.status(401).json({ error: 'Not authenticated' });
+    // a server-mode key reports page views and does nothing else — not even read stats
+    if (p.kind === 'hitkey' && !(req.method === 'POST' && req.path === '/api/v1/hit')) return res.status(403).json({ error: 'This key can only report page views (POST /api/v1/hit)' });
     req.principal = p;
     next();
   }
@@ -498,7 +512,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     res.json(out);
   });
   const userOnly = (req, res, next) => {
-    if (req.principal.kind === 'userkey') return res.status(403).json({ error: 'API keys cannot change account settings — sign in' });
+    if (req.principal.kind === 'userkey' || req.principal.kind === 'hitkey') return res.status(403).json({ error: 'API keys cannot change account settings — sign in' });
     return req.principal.user ? next() : res.status(400).json({ error: 'Create an account first' });
   };
   async function needPassword(req, res) {
@@ -599,7 +613,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
   });
 
   app.get('/api/audit', requireRole('owner'), (req, res) => {
-    if (req.principal.kind === 'userkey') return res.status(403).json({ error: 'API keys cannot read the audit log — sign in' });
+    if (req.principal.kind === 'userkey' || req.principal.kind === 'hitkey') return res.status(403).json({ error: 'API keys cannot read the audit log — sign in' });
     const before = Number(req.query.before) || Date.now() + 1;
     const limit = Math.min(500, Math.max(1, Number(req.query.limit) || 100));
     res.json(db.prepare('SELECT id, ts, actor, action, target, ip FROM audit_log WHERE ts < ? ORDER BY ts DESC, id DESC LIMIT ?').all(before, limit));
@@ -607,21 +621,33 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
 
   // ── personal API keys ──
   app.get('/api/me/keys', auth, userOnly, (req, res) => {
-    res.json(db.prepare('SELECT id, prefix, name, read_only, created, last_used FROM api_keys WHERE user_id = ? ORDER BY created').all(req.principal.user.id)
-      .map((k) => ({ ...k, read_only: !!k.read_only })));
+    res.json(db.prepare('SELECT id, prefix, name, read_only, scope, sites, created, last_used FROM api_keys WHERE user_id = ? ORDER BY created').all(req.principal.user.id)
+      .map((k) => ({ ...k, read_only: !!k.read_only, scope: k.scope || '', sites: k.sites ? JSON.parse(k.sites) : null })));
   });
   app.post('/api/me/keys', auth, userOnly, (req, res) => {
     const b = req.body || {};
     const n = db.prepare('SELECT COUNT(*) n FROM api_keys WHERE user_id = ?').get(req.principal.user.id).n;
     if (n >= 20) return res.status(400).json({ error: 'At most 20 keys per account' });
-    // a viewer can only ever get a read-only key
-    const readOnly = req.principal.role === 'viewer' ? true : b.readOnly !== false;
     const key = 'tk_' + crypto.randomBytes(24).toString('base64url');
     const name = String(b.name || '').trim().slice(0, 60) || 'API key';
+    if (b.scope === 'hit') {
+      // server mode: bound to explicit sites, never more than the account may see. Admin or owner only: reporting
+      // page views is writing data (it can add visitors), and a viewer may not write — same rule as /api/v1/hit in 2.4.0.
+      if (req.principal.role === 'viewer') return res.status(403).json({ error: 'Viewers cannot create server-mode keys' });
+      if (!Array.isArray(b.sites) || !b.sites.length) return res.status(400).json({ error: 'Pick the site(s) this server reports for' });
+      const ids = [...new Set(b.sites.map(Number))];
+      if (ids.some((id) => !allSiteIds().includes(id) || !siteAllowed(req, id))) return res.status(403).json({ error: 'You have no access to one of these sites' });
+      const info = db.prepare("INSERT INTO api_keys (key_hash, prefix, user_id, name, read_only, scope, sites, created) VALUES (?, ?, ?, ?, 1, 'hit', ?, ?)")
+        .run(sha256(key), key.slice(0, 10), req.principal.user.id, name, JSON.stringify(ids), Date.now());
+      audit(res, 'me.apikey.add', `${name} (${key.slice(0, 10)}…, server mode: sites ${ids.join(',')})`);
+      return res.json({ id: info.lastInsertRowid, key, name, read_only: true, scope: 'hit', sites: ids });
+    }
+    // a viewer can only ever get a read-only key
+    const readOnly = req.principal.role === 'viewer' ? true : b.readOnly !== false;
     const info = db.prepare('INSERT INTO api_keys (key_hash, prefix, user_id, name, read_only, created) VALUES (?, ?, ?, ?, ?, ?)')
       .run(sha256(key), key.slice(0, 10), req.principal.user.id, name, readOnly ? 1 : 0, Date.now());
     audit(res, 'me.apikey.add', `${name} (${key.slice(0, 10)}…, ${readOnly ? 'read-only' : 'read + write'})`);
-    res.json({ id: info.lastInsertRowid, key, name, read_only: readOnly }); // the key is shown exactly once
+    res.json({ id: info.lastInsertRowid, key, name, read_only: readOnly, scope: '' }); // the key is shown exactly once
   });
   app.delete('/api/me/keys/:id', auth, userOnly, (req, res) => {
     const k = db.prepare('SELECT name, prefix FROM api_keys WHERE id = ? AND user_id = ?').get(Number(req.params.id), req.principal.user.id);
@@ -633,7 +659,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
   // ── team (owner) ───────────────────────────────────────────────────────────
   // team management needs a real sign-in (or the server API_KEY): a personal key that leaks must not
   // be able to invite, promote or remove people
-  const ownerOnly = (req, res, next) => requireRole('owner')(req, res, () => (req.principal.kind === 'userkey'
+  const ownerOnly = (req, res, next) => requireRole('owner')(req, res, () => (req.principal.kind === 'userkey' || req.principal.kind === 'hitkey'
     ? res.status(403).json({ error: 'API keys cannot manage the team — sign in' }) : next()));
 
   // first account: only from a legacy (WEB_PASSWORD) or API-key session, only while there are none

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tacilytics",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Privacy-first, cookieless analytics for websites and apps. Self-hosted: one Node process, one SQLite file.",
   "main": "server.js",
   "type": "commonjs",

package/public/account.js

@@ -277,11 +277,13 @@
       '<p class="muted">Every Monday morning, for each of your sites: key figures, a day-by-day chart, highlights, top pages, sources, countries, devices, goals, shop numbers and your notes — compared with the week before.</p>' +
       '<div id="repBox"><p class="muted small">Loading…</p></div></div>' +
       '<div class="set-card"><h3>' + ico('i-code') + 'API keys</h3>' +
-      '<p class="muted">For scripts, agents and the CLI (<code>TACILYTICS_API_KEY</code>). A key acts as you, sees only your sites, and cannot touch the team or your security settings. Read-only unless you untick it.</p>' +
+      '<p class="muted">For scripts, agents and the CLI (<code>TACILYTICS_API_KEY</code>). A key acts as you, sees only your sites, and cannot touch the team or your security settings.</p>' +
+      '<p class="muted small">For server mode, create a “server mode (count only)” key: it can only report page views for the sites you tick, nothing else. Never put a read + write key on a web server.</p>' +
       '<div id="keyList"><p class="muted small">Loading…</p></div>' +
       '<div class="set-inline"><input id="keyName" type="text" placeholder="Name, e.g. reporting script" maxlength="60">' +
-      (me.role !== 'viewer' ? '<label class="small muted" style="display:inline-flex;gap:6px;align-items:center;flex:0 0 auto"><input type="checkbox" id="keyRo" checked style="width:auto;margin:0"> read-only</label>' : '') +
-      '<button class="btn" id="keyAdd">Create key</button></div><div id="keyOut"></div></div>' +
+      '<select id="keyKind" style="flex:0 0 auto;width:auto"><option value="ro">read-only</option>' + (me.role !== 'viewer' ? '<option value="rw">read + write</option><option value="hit">server mode (count only)</option>' : '') + '</select>' +
+      '<button class="btn" id="keyAdd">Create key</button></div>' +
+      '<div id="keySites" class="hide small muted" style="margin-top:8px"></div><div id="keyOut"></div></div>' +
       '<div class="set-card"><h3>' + ico('i-shield') + 'Password</h3>' +
       '<div class="set-inline"><input id="pwOld" type="password" placeholder="Current password" autocomplete="current-password"><input id="pwNew" type="password" placeholder="New password (10+)" autocomplete="new-password"><button class="btn ghost" id="pwSave">Change</button></div>' +
       '<p class="muted small">Changing it signs you out on all other devices.</p></div>' +
@@ -343,7 +345,7 @@
     function loadKeys() {
       call('GET', '/api/me/keys').then(function (keys) {
         $('keyList').innerHTML = keys.length ? keys.map(function (k) {
-          return '<div class="set-row"><span>' + ico('i-code') + esc(k.name) + ' <code class="muted small">' + esc(k.prefix) + '…</code>' + (k.read_only ? ' <span class="pill">read-only</span>' : ' <span class="pill">read + write</span>') + '</span>' +
+          return '<div class="set-row"><span>' + ico('i-code') + esc(k.name) + ' <code class="muted small">' + esc(k.prefix) + '…</code>' + (k.scope === 'hit' ? ' <span class="pill"><span>server mode</span> · <span data-no-i18n>' + esc(siteNames(k.sites)) + '</span></span>' : k.read_only ? ' <span class="pill">read-only</span>' : ' <span class="pill">read + write</span>') + '</span>' +
             '<span class="muted small">' + (k.last_used ? 'used ' + date(k.last_used) : 'never used') + '</span><button class="btn ghost danger mini" data-delkey="' + k.id + '">Revoke</button></div>';
         }).join('') : '<p class="muted small">No keys yet.</p>';
         $('keyList').querySelectorAll('[data-delkey]').forEach(function (b) {
@@ -352,9 +354,21 @@
       }).catch(function (e) { setErr(e.message); });
     }
     loadKeys();
+    var siteList = (window.Taci && window.Taci.sites && window.Taci.sites()) || [];
+    $('keyKind').onchange = function () {
+      var hit = this.value === 'hit';
+      $('keySites').classList.toggle('hide', !hit);
+      if (hit && !$('keySites').innerHTML) $('keySites').innerHTML = 'Reports for: ' + siteList.map(function (st) {
+        return '<label style="display:inline-flex;gap:4px;align-items:center;margin-right:10px"><input type="checkbox" class="keySite" value="' + st.id + '" style="width:auto;margin:0"' + (siteList.length === 1 ? ' checked' : '') + '>' + esc(st.domain) + '</label>';
+      }).join('');
+    };
     $('keyAdd').onclick = function () {
       setErr('');
-      call('POST', '/api/me/keys', { name: $('keyName').value.trim(), readOnly: $('keyRo') ? $('keyRo').checked : true }).then(function (k) {
+      var kind = $('keyKind').value;
+      var body = { name: $('keyName').value.trim() };
+      if (kind === 'hit') { body.scope = 'hit'; body.sites = Array.prototype.map.call(document.querySelectorAll('.keySite:checked'), function (c) { return Number(c.value); }); }
+      else body.readOnly = kind !== 'rw';
+      call('POST', '/api/me/keys', body).then(function (k) {
         $('keyName').value = '';
         $('keyOut').innerHTML = '<p class="muted small" style="margin:10px 0 4px">Copy it now — it is shown only once.</p><div class="snippet">' + esc(k.key) + '</div><button class="btn ghost mini" id="keyCopy">Copy key</button>';
         $('keyCopy').onclick = function () { navigator.clipboard.writeText(k.key); this.textContent = 'Copied ✓'; };

package/public/i18n.js

@@ -141,6 +141,9 @@
     'Direct / none': 'Direkt / keine', 'Android app': 'Android-App', 'iOS app': 'iOS-App', 'Web': 'Web',
     'For scripts, agents and the CLI (': 'Für Skripte, Agents und die CLI (',
     '). A key acts as you, sees only your sites, and cannot touch the team or your security settings. Read-only unless you untick it.': '). Ein Key handelt als du, sieht nur deine Seiten und kann weder das Team noch deine Sicherheitseinstellungen ändern. Nur lesen, außer du nimmst den Haken raus.',
+    '). A key acts as you, sees only your sites, and cannot touch the team or your security settings.': '). Ein Key handelt als du, sieht nur deine Seiten und kann weder das Team noch deine Sicherheitseinstellungen ändern.',
+    'For server mode, create a “server mode (count only)” key: it can only report page views for the sites you tick, nothing else. Never put a read + write key on a web server.': 'Für den Server-Modus legst du einen Key „Server-Modus (nur zählen)“ an: Er kann nur Seitenaufrufe für die angehakten Seiten melden, sonst nichts. Leg nie einen Key mit Schreibrechten auf einen Webserver.',
+    'server mode (count only)': 'Server-Modus (nur zählen)', 'server mode': 'Server-Modus', 'Reports for:': 'Meldet für:',
     'Signed in as': 'Angemeldet als',
     'Viewer — read only': 'Viewer: nur lesen', 'Admin — sites, share links and funnels (all or picked sites)': 'Admin: Seiten, Share-Links und Funnels (alle oder ausgewählte Seiten)', 'Owner — everything, including the team': 'Owner: alles, auch das Team',
     'In Plausible:': 'In Plausible:', 'Site settings → Imports & Exports → Export data': 'Website-Einstellungen → Imports & Exports → Export data',

package/public/index.html

@@ -389,8 +389,8 @@
 </div>
 
 <div class="tip" id="tip"></div>
-<script src="/i18n.js?v=2.2.3"></script>
-<script src="/account.js?v=2.5.6"></script>
+<script src="/i18n.js?v=2.2.5"></script>
+<script src="/account.js?v=2.5.9"></script>
 <script src="/app.js?v=2.7.2"></script>
 </body>
 </html>

package/server.js

@@ -402,6 +402,7 @@ const { auth, requireRole, siteAllowed, audit, grantSite, isLimited } = setupAut
   allSiteIds: () => db.prepare('SELECT id FROM sites').all().map((r) => r.id),
 });
 const adminOnly = requireRole('admin');
+const ROLE_RANK = { viewer: 1, admin: 2, owner: 3 };
 
 // share-token auth: read-only stats access scoped to exactly one site.
 // Accepted as ?share=<token>; the handler must check siteOk(req, site).
@@ -501,7 +502,7 @@ app.get('/api/v1', (_req, res) => res.json({
     'GET /api/v1/stats?site=&period=': 'aggregated stats (period: today|7d|30d|90d|12mo, or from=YYYY-MM-DD&to=YYYY-MM-DD)',
     'GET /api/v1/realtime?site=': 'online count, last-30-min pulse + recent events',
     'GET /api/v1/usage?month=YYYY-MM': 'page views per site in a calendar month (UTC), owner / server key only',
-    'POST /api/v1/hit': 'server mode: report a page view from your web server { domain, path, ip, ua, referrer?, lang?, purpose?, name? } (write key)',
+    'POST /api/v1/hit': 'server mode: report a page view from your web server { domain, path, ip, ua, referrer?, lang?, purpose?, name? } (server-mode key)',
   },
   filters: 'add any of country,source,page,browser,os,device,lang,medium,campaign,goal to /stats to segment',
 }));
@@ -524,9 +525,13 @@ app.post('/api/v1/sites', adminOnly, sitesCreateHandler);
 // exactly like a tracker hit and never stored.
 const net = require('net');
 const PREFETCH_RE = /prefetch|prerender/i;
-// write access needed (admin role or a non-read-only key); a read-only key is a viewer and gets 403
-app.post('/api/v1/hit', adminOnly, (req, res) => {
-  if (rateLimited('h:' + clientIp(req), 6000, 60000)) return res.status(429).json({ error: 'Too many hits' });
+// Who may report: a server-mode key (scope 'hit', recommended, bound to its sites and good for nothing else), or —
+// as in 2.4.0 — a key / sign-in with write access (admin role). A read-only key is a viewer and gets 403.
+app.post('/api/v1/hit', auth, (req, res) => {
+  const p = req.principal;
+  if (p.kind !== 'hitkey' && ROLE_RANK[p.role] < ROLE_RANK.admin) return res.status(403).json({ error: 'Use a server-mode key (Settings → API keys)' });
+  // per key, not per web-server IP: many sites behind one shared-hosting IP must not starve each other
+  if (rateLimited('h:' + (p.keyId != null ? 'k' + p.keyId : p.kind + ':' + (p.user ? p.user.id : '')), 6000, 60000)) return res.status(429).json({ error: 'Too many hits' });
   const b = req.body || {};
   const domain = norm(b.domain || b.d);
   const site = domain && getSiteByDomain.get(domain);