tacilytics 2.3.0 → 2.4.0

package/README.md

@@ -5,7 +5,7 @@
 # Tacilytics
 
 **Privacy-first, cookieless analytics for websites and apps — self-hosted in minutes.**
-*Tacit* (adj.): understood without being said. Tacilytics counts what matters and keeps quiet about who did it — one tiny script, one Node process, one SQLite file. No cookies, no consent banner, no creepy tracking. (And in Italian, *taci* simply means "be quiet".)
+*Tacit* (adj.): understood without being said. Tacilytics counts what matters and keeps quiet about who did it — one tiny script, one Node process, one SQLite file. No cookies, no IDs, no creepy tracking. (And in Italian, *taci* simply means "be quiet".)
 
 > Formerly **Nyx Analytics**. Existing installs keep working: `/nyx.js`, `window.nyx()` and the old Flutter class names are still supported as aliases.
 
@@ -22,7 +22,7 @@
 
 ## Why Tacilytics
 
-- 🍪 **Cookieless & banner-free.** No cookies, no `localStorage`, no fingerprinting — nothing to consent to.
+- 🍪 **Cookieless.** No cookies, no IDs, nothing written to the visitor's device, no fingerprinting. **Strict mode** (`data-strict`) also reduces what the tracker reads on the device to what every page request carries anyway — see [Strict mode](#strict-mode).
 - 🛡️ **IPs are never stored.** Unique visitors are counted with a *daily, salted, one-way hash* that’s irreversible and rotated every day.
 - 🌍 **Region from the browser timezone**, never from IP geolocation.
 - 🔍 **Segment everything.** Click any country, page, source, browser or campaign to filter the whole dashboard — stacked, with one-click chips.
@@ -72,7 +72,7 @@ Open the dashboard, log in, click **+ Add site**, and drop the snippet into your
 <script defer data-domain="example.com" src="https://analytics.example.com/tacilytics.js"></script>
 ```
 
-That’s it. Pageviews start flowing in — no cookie banner required.
+That’s it. Pageviews start flowing in, without cookies. (Want the tracker to read less on the device as well? Add `data-strict`, see [Strict mode](#strict-mode).)
 
 ## Custom events, goals & properties
 
@@ -110,11 +110,59 @@ Opt-in flags on the `<script>` tag:
 ```html
 <script defer data-domain="example.com"
         data-honor-dnt          <!-- skip tracking if DNT / Global Privacy Control is on -->
+        data-strict             <!-- reduce device reads (see Strict mode) -->
         data-track-outbound     <!-- auto-record clicks to other domains as events -->
         data-track-downloads    <!-- auto-record file downloads (pdf, zip, docx …) as "File Download"; or ="pdf,epub" -->
         src="https://analytics.example.com/tacilytics.js"></script>
 ```
 
+### Strict mode
+
+The default tracker writes nothing to the visitor's device, but it does **read** a few things there: one `localStorage` flag (your own visits, below), the time zone (→ country), the browser language, the window size (→ scroll depth) and, with `data-honor-dnt`, the DNT/GPC setting. EU device-access rules (ePrivacy Art. 5(3), in Germany § 25 TDDDG) cover reading as well as storing, and the EDPB reads "access" broadly (Guidelines 2/2023 also count information a script makes the browser send). Strict mode reduces device access to what every page request carries anyway:
+
+```html
+<script defer data-domain="example.com" data-strict data-honor-dnt src="https://analytics.example.com/tacilytics.js"></script>
+```
+
+In strict mode the tracker does not read local storage, the time zone, the language, the window or screen size, or the DNT/GPC setting. It sends what the page knows: domain, path, referrer, UTM parameters and time on page; the browser adds its usual request headers. To get there it still uses page state, not device properties: `location` and the query string (UTM), `document.referrer`, the DOM for the optional 404 and site-search detection, and a check that `navigator.sendBeacon` exists. Some authorities (EDPB Guidelines 2/2023) read the rules more broadly than "device properties", so do not take "strict" as "nothing at all". The server takes the language from `Accept-Language`, and with `data-honor-dnt` it checks the `DNT` / `Sec-GPC` request headers. Two things are still used for timing and never sent: the page's visibility state (`document.visibilityState`) and the device clock (`Date.now()`, only differences, for time on page). A test runs the tracker with every other device API booby-trapped and fails if strict mode touches one.
+
+**WordPress plugin:** its role exclusion (don't count logged-in admins, editors …) uses a `localStorage` marker in a small inline script before the tracker. Turn the role exclusion off when you use strict mode; a later plugin release will handle it on the server.
+
+What you give up: **no country** (it came from the time zone), **no scroll depth** (time on page stays), and `?tacilytics=off` does not work (the console says so) — exclude your own visits another way (e.g. a test browser you don't count, or filter yourself out in the dashboard). Strict mode does not decide whether you need consent; that depends on your jurisdiction and the rest of your website. This is not legal advice.
+
+### Server mode (no script at all)
+
+Server mode runs no script and reads or stores nothing on the visitor's device. Your web server reports each page view itself, from the request the visitor sent to your page anyway: path, `Referer`, `Accept-Language`, `User-Agent` and the visitor IP. Don't add the `<script>` tag on pages that use server mode; mixing both on one page would bring the script back.
+
+```http
+POST /api/v1/hit
+Authorization: Bearer tk_…            # a key created with write access (Settings → API keys), not read-only
+Content-Type: application/json
+
+{ "domain": "example.com", "path": "/shop?utm_source=news", "ip": "203.0.113.7",
+  "ua": "<User-Agent header>", "referrer": "<Referer header>", "lang": "<Accept-Language header>",
+  "purpose": "<Sec-Purpose or Purpose header>" }
+```
+
+Node / Express, after your static files and before your pages:
+
+```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(() => {});
+  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.
+- **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.
+
 **Your own visits:** open your site once with `?tacilytics=off` (e.g. `https://example.com/?tacilytics=off`) and that browser is no longer counted on that site. `?tacilytics=on` undoes it. It is stored in the browser's localStorage, nothing is sent; repeat it on every browser and phone you use. Settings → Security has the links for all your sites.
 
 ## Mobile & desktop apps
@@ -225,6 +273,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) |
 
 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`.
 
@@ -256,8 +305,9 @@ row per pageview. The dashboard aggregates it with plain SQL.
 
 **The cookieless trade-off, honestly:** because there’s no persistent identifier, Tacilytics
 counts unique visitors *per day* and can’t follow the same person across days or
-devices. You get the 95 % that matters (how many, which pages, from where) with 0 %
-cookie banner — the same approach as Plausible/Fathom.
+devices. You get the 95 % that matters (how many, which pages, from where) without cookies,
+the same approach as Plausible/Fathom. Whether you still need consent depends on your
+jurisdiction and setup; strict mode (`data-strict`) reduces the device reads further.
 
 ## Light mode & German
 
@@ -320,6 +370,8 @@ The server-wide `API_KEY` from `.env` keeps owner rights for agents and the CLI
   - **One process only.** The salt is drawn by the single Node process. Running several processes against the same `data/` would let each draw its own salt at midnight.
 - **Data minimisation:** set `DATA_RETENTION_DAYS` to auto-purge raw events after your chosen window.
 - **Respects DNT / Global Privacy Control** when you add `data-honor-dnt` to the tag.
+- **Strict mode** (`data-strict`) skips the device reads (no localStorage, time zone, language or window size). See [Strict mode](#strict-mode).
+- **Server mode** (`POST /api/v1/hit`) runs no script on the visitor's device at all; your server reports the page view. See [Server mode](#server-mode-no-script-at-all).
 - Engagement time adds **no new identifier** — it’s matched to the visitor’s own daily hash server-side.
 - Custom event properties are capped (scalars only, size-limited) so they can’t become a PII dumping ground.
 - Passwords hashed with scrypt; session tokens, invite links and recovery codes are stored only as SHA-256. Sessions live in the database (survive restarts, expire after 30 days).
@@ -332,7 +384,9 @@ The server-wide `API_KEY` from `.env` keeps owner rights for agents and the CLI
 
 | | Tacilytics | Google Analytics |
 |---|---|---|
-| Cookies / consent banner | ❌ none | ✅ required |
+| Cookies | ❌ none | ✅ yes |
+| Reads from the device | a few (time zone, language, window size, one localStorage flag); none in strict mode | ✅ a lot |
+| Works without any script on the visitor's device | ✅ server mode | ❌ |
 | Stores IPs / personal data | ❌ never | ✅ yes |
 | Self-hosted, you own the data | ✅ | ❌ |
 | Weight | ~2 KB | ~45 KB+ |

package/package.json

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

package/public/tacilytics.js

@@ -4,6 +4,11 @@
 
    Optional data-* flags on the <script> tag:
      data-honor-dnt        respect Do-Not-Track / Global Privacy Control (skip all tracking)
+     data-strict           strict mode: no localStorage, no timezone, no language, no window/screen size,
+                           no DNT lookup in JS (only document.visibilityState and Date.now() differences for
+                           time on page, never sent). Language comes from the Accept-Language header,
+                           DNT/GPC from the request headers (with data-honor-dnt). Costs: no country, no scroll
+                           depth, ?tacilytics=off does not work (exclude own visits another way).
      data-track-outbound   auto-record clicks on links to other domains as events
      data-track-downloads  auto-record file downloads as "File Download" events (optional value: "pdf,zip,…")
      data-track-404        record a "404" event when the page is an error page
@@ -20,15 +25,19 @@
     var domain = s && s.getAttribute('data-domain');
     if (!s || !domain) return;
 
+    var strict = s.hasAttribute('data-strict');
+    var honorDnt = s.hasAttribute('data-honor-dnt');
+
     // Privacy signals (opt-in): if the visitor asked not to be tracked, honour it and do nothing.
-    if (s.hasAttribute('data-honor-dnt')) {
+    // In strict mode the server checks the DNT / Sec-GPC request headers instead (nothing is read here).
+    if (honorDnt && !strict) {
       var dnt = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
       if (navigator.globalPrivacyControl === true || dnt === '1' || dnt === 'yes') return;
     }
 
     // "Don't count this browser" (your own visits): open the site once with ?tacilytics=off
     // (?tacilytics=on counts it again). Remembered per browser in localStorage, nothing is sent.
-    try {
+    if (!strict) try {
       var optParam = new URLSearchParams(location.search).get('tacilytics');
       if (optParam === 'off') { localStorage.setItem('tacilytics_ignore', '1'); console.info('Tacilytics: this browser is no longer counted on ' + location.hostname + ' (undo: ?tacilytics=on)'); }
       else if (optParam === 'on') { localStorage.removeItem('tacilytics_ignore'); console.info('Tacilytics: this browser is counted again on ' + location.hostname); }
@@ -37,11 +46,17 @@
         return;
       }
     } catch (e) {} // storage blocked → just count normally
+    else if (/[?&]tacilytics=(off|on)(&|$)/.test(location.search)) {
+      // the query string is part of the page address, not the device
+      try { console.info('Tacilytics: strict mode, ?tacilytics=off/on is not supported (it needs localStorage)'); } catch (e) {}
+    }
 
     var endpoint = new URL(s.src).origin + '/api/collect';
-    var tz = '';
-    try { tz = Intl.DateTimeFormat().resolvedOptions().timeZone || ''; } catch (e) {}
-    var lang = (navigator.language || '').slice(0, 12);
+    var tz = '', lang = '';
+    if (!strict) {
+      try { tz = Intl.DateTimeFormat().resolvedOptions().timeZone || ''; } catch (e) {}
+      lang = (navigator.language || '').slice(0, 12);
+    }
     var qs = new URLSearchParams(location.search);
     var first = true;
 
@@ -68,6 +83,7 @@
         um: qs.get('utm_medium') || '',
         uc: qs.get('utm_campaign') || '',
       };
+      if (strict) { payload.st = 1; if (honorDnt) payload.hd = 1; }
       if (name) { payload.n = name; if (props && typeof props === 'object') payload.pr = props; }
       else first = false;
       post(payload);
@@ -77,6 +93,7 @@
     var acc = 0, since = (document.visibilityState === 'visible') ? Date.now() : 0, engPath = location.pathname;
     var maxScroll = 0;
     function measureScroll() {
+      if (strict) return; // window and screen size are device information
       var de = document.documentElement, b = document.body || de;
       var h = Math.max(de.scrollHeight, b.scrollHeight), vh = window.innerHeight || de.clientHeight;
       var y = window.pageYOffset || de.scrollTop || 0;
@@ -91,7 +108,11 @@
     function flushEngagement() {
       var secs = engaged();
       measureScroll();
-      if (secs >= 1 || maxScroll > 0) post({ d: domain, p: engPath, e: 'engagement', dur: secs, sc: maxScroll });
+      if (secs >= 1 || maxScroll > 0) {
+        var eb = { d: domain, p: engPath, e: 'engagement', dur: secs };
+        if (strict) { eb.st = 1; if (honorDnt) eb.hd = 1; } else eb.sc = maxScroll;
+        post(eb);
+      }
     }
     function resetEngagement() { acc = 0; since = Date.now(); engPath = location.pathname; maxScroll = 0; }
     document.addEventListener('visibilitychange', function () {

package/server.js

@@ -239,6 +239,11 @@ function parseUA(ua) {
 
 // Rough timezone → ISO country (privacy-preserving alternative to IP geo).
 const TZ_COUNTRY = require('./tz-country.js');
+// first language of an Accept-Language header ("de-DE,de;q=0.9,en;q=0.8" → "de-DE"), or null
+function acceptLang(h) {
+  const m = String(h || '').split(',')[0].split(';')[0].trim().match(/^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})?$/);
+  return m ? m[0].slice(0, 12) : null;
+}
 function countryFromTz(tz) { return (tz && TZ_COUNTRY[tz]) || null; }
 
 const { createDaySalt, dayStr } = require('./day-salt.js');
@@ -330,6 +335,10 @@ function collect(req, res) {
     ua = { browser: 'App', os: APP_PLATFORMS[platform], device: dv === 'tablet' ? 'Tablet' : dv === 'desktop' ? 'Desktop' : (platform === 'android' || platform === 'ios') ? 'Mobile' : 'Desktop' };
   }
   if (!ua) return res.status(204).end(); // bot
+  // strict mode (data-strict): the tracker read nothing on the device. Privacy signals and language come
+  // from headers the browser sends with every request anyway.
+  const strict = String(b.st || '') === '1';
+  if (strict && String(b.hd || '') === '1' && (req.headers['dnt'] === '1' || req.headers['sec-gpc'] === '1')) return res.status(204).end();
 
   const ts = Date.now();
   const day = dayStr(ts);
@@ -352,7 +361,7 @@ function collect(req, res) {
   // engagement beacon: attach a visit duration (+ max scroll depth) to the visitor's latest pageview (no new row).
   if (b.e === 'engagement') {
     const dur = Math.max(0, Math.min(7200, parseInt(b.dur, 10) || 0)); // cap at 2h
-    const sc = b.sc == null || b.sc === '' ? null : Math.max(0, Math.min(100, parseInt(b.sc, 10) || 0));
+    const sc = strict || b.sc == null || b.sc === '' ? null : Math.max(0, Math.min(100, parseInt(b.sc, 10) || 0));
     if (dur > 0 || sc != null) updDur.run({ site_id: site.id, vh, path: pth, dur, scroll: sc, since: ts - 6 * 3600000 });
     return res.status(204).end();
   }
@@ -367,8 +376,8 @@ function collect(req, res) {
   }
   const utmMedium = String(b.um || b.utm_medium || '').slice(0, 60).trim() || null;
   const utmCampaign = String(b.uc || b.utm_campaign || '').slice(0, 80).trim() || null;
-  const tz = String(b.tz || '').slice(0, 60) || null;
-  const lang = String(b.l || b.lang || '').slice(0, 12).split(',')[0] || null;
+  const tz = strict ? null : (String(b.tz || '').slice(0, 60) || null);
+  const lang = strict ? acceptLang(req.headers['accept-language']) : (String(b.l || b.lang || '').slice(0, 12).split(',')[0] || null);
   const name = String(b.n || b.name || '').slice(0, 80).trim() || null; // custom event / goal
   const props = name ? sanitizeProps(b.pr) : null; // properties only attach to named events
   let country = countryFromTz(tz);
@@ -492,6 +501,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)',
   },
   filters: 'add any of country,source,page,browser,os,device,lang,medium,campaign,goal to /stats to segment',
 }));
@@ -507,6 +517,61 @@ app.get('/api/v1/usage', requireRole('owner'), (req, res) => {
 });
 app.post('/api/v1/sites', adminOnly, sitesCreateHandler);
 
+// ── server mode (2.4): the website's own server reports a page view, no script on the visitor's device ──
+// The site's backend forwards what the visitor's request carried anyway: path, Referer, Accept-Language,
+// User-Agent and the visitor IP. The IP is only taken from an authenticated write key (never from the
+// public /api/collect), otherwise anyone could feed arbitrary IPs into the visitor hash. It is hashed
+// 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' });
+  const b = req.body || {};
+  const domain = norm(b.domain || b.d);
+  const site = domain && getSiteByDomain.get(domain);
+  if (!site || !siteAllowed(req, site.id)) return res.status(404).json({ error: 'Unknown site' });
+  if (site.paused) return res.status(202).end();
+  const ip = String(b.ip || '').trim();
+  // without the visitor IP every visitor would fall onto one hash: refuse instead of counting wrong
+  if (!net.isIP(ip)) return res.status(400).json({ error: 'ip (the visitor IP) is required for server mode' });
+  // prefetch / prerender requests are not visits (Sec-Purpose / Purpose header of the visitor request)
+  if (PREFETCH_RE.test(String(b.purpose || ''))) return res.status(204).end();
+  const rawUa = String(b.ua || '').slice(0, 512);
+  const ua = parseUA(rawUa);
+  if (!ua) return res.status(204).end(); // bot, crawler, monitor or no user agent
+  if (b.dnt === true || b.dnt === '1' || b.gpc === true || b.gpc === '1') return res.status(204).end(); // forwarded DNT / GPC (opt-in on the sending side)
+
+  const ts = Date.now();
+  const day = dayStr(ts);
+  let url;
+  try { url = new URL(String(b.path || b.p || '/').slice(0, 1024), 'http://x'); } catch { return res.status(400).json({ error: 'invalid path' }); }
+  let pth = url.pathname.slice(0, 512);
+  try { pth = decodeURI(pth); } catch {}
+  if (pth.length > 1) pth = pth.replace(/\/+$/, '') || '/';
+  const vh = visitorHash(site.id, ip, rawUa, day);
+  const intern = INTERNAL_PATHS[domain] || [];
+  if (intern.some((pre) => pth.startsWith(pre))) { insInternal.run(site.id, vh, day); return res.status(204).end(); }
+  if (isInternal.get(site.id, vh, day)) return res.status(204).end();
+
+  const referrer = String(b.referrer || b.r || '').slice(0, 512);
+  const q = url.searchParams;
+  let source = 'Direct';
+  const utm = String(q.get('utm_source') || q.get('ref') || '').slice(0, 60).trim();
+  if (utm) source = utm;
+  else if (referrer) { try { const h = norm(new URL(referrer).hostname); if (h && h !== domain) source = h; } catch {} }
+  const name = String(b.name || b.n || '').slice(0, 80).trim() || null; // optional server-side goal (e.g. Purchase)
+  insEvent.run({
+    site_id: site.id, ts, day, path: pth, source, referrer: referrer || null,
+    country: null, tz: null, browser: ua.browser, os: ua.os, device: ua.device,
+    lang: acceptLang(b.lang), name,
+    utm_medium: String(q.get('utm_medium') || '').slice(0, 60).trim() || null,
+    utm_campaign: String(q.get('utm_campaign') || '').slice(0, 80).trim() || null,
+    dur: null, props: name ? sanitizeProps(b.props) : null, vh, platform: null, app_version: null,
+  });
+  res.status(204).end();
+});
+
 // ── stats ────────────────────────────────────────────────────────────────────
 const TZ = require('./tz');
 const PERIODS = { today: 1, '7d': 7, '30d': 30, '90d': 90, '12mo': 365 };