tacilytics 2.1.0 → 2.2.0

package/.env.example

@@ -27,3 +27,8 @@ API_KEY=change-me
 
 # Data minimisation: auto-purge raw events older than N days (0 = keep forever)
 DATA_RETENTION_DAYS=0
+
+# Weekly report by e-mail (optional). smtps://…:465 or smtp://…:587 (STARTTLS)
+# SMTP_URL=smtps://user:password@mail.example.com:465
+# REPORT_FROM=Tacilytics <reports@example.com>
+# REPORT_HOUR_UTC=6

package/README.md

@@ -111,9 +111,12 @@ Opt-in flags on the `<script>` tag:
 <script defer data-domain="example.com"
         data-honor-dnt          <!-- skip tracking if DNT / Global Privacy Control is on -->
         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>
 ```
 
+**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
 
 Track your **native app in the same dashboard as your website**. Every row gets a platform
@@ -152,6 +155,52 @@ The server hashes the launch id with a random daily salt that is deleted when th
 Without `sid`, the usual IP + user-agent daily hash is used. Region comes from the timezone or
 device locale, never from IP geolocation.
 
+## Import from Google Analytics or Plausible
+
+**Import** (toolbar) brings your history along, so switching doesn't mean starting at zero.
+
+- **Plausible:** Site settings → Imports & Exports → *Export data*. Upload the ZIP (or the CSVs in it).
+- **Google Analytics 4:** open a report (*Pages and screens*, *Traffic acquisition*, *Demographic details*, *Tech*), add **Date** as a secondary dimension, *Share → Download file → CSV*. One file per report; English or German column names.
+
+Imported numbers are daily totals per dimension (pages, sources, countries, browsers, OS, devices, events) and count **only for days before your own data starts** — never twice. They appear in the chart, the totals and the panels; while a filter is active they are left out (they can't be combined), and the dashboard says so. Every import can be removed again. No visitor-level data is imported or stored.
+
+## Notes in the chart
+
+Click **Notes** in the chart legend to mark a day — a newsletter, a release, a sale. A coral line and a diamond appear on that day, the note shows in the tooltip, and everyone with access to the site (including share links) sees it. Admins and owners add and remove notes. `GET /api/annotations?site=…` lists them; `/stats` returns the ones in its range as `annotations`.
+
+## Time zone per site
+
+Every site has its own time zone (any IANA name, e.g. `Europe/Berlin`; the browser's zone is preselected when you add a site, existing sites stay on `UTC`). Click the clock next to the site picker to change it. Days, the hourly view, date ranges, notes, the weekly report, the daily digest and the alert baseline all follow it, with daylight-saving days as 23 or 25 hours and offsets like +5:45 kept exact. Stored data is not touched, so switching back and forth is safe.
+
+One limit: the anonymous visitor ID rotates at midnight **UTC** (that is what keeps it unlinkable across days). Outside UTC a local day therefore spans two IDs, and *unique visitors per day* are an approximation — pageviews, goals and revenue are exact.
+
+`PATCH /api/sites/:id {"timezone":"Europe/Berlin"}` (admin) changes it via the API; unknown names are rejected with 400.
+
+## Weekly report by e-mail
+
+Settings → Security → **Weekly report**: enter an address and tick *every Monday*. Each person gets one mail per week for **the sites they can see** — visitors and pageviews vs. the week before, top pages, sources, goals and a link to the dashboard. *Send one now* sends a sample.
+
+Needs mail settings in `.env`:
+
+```env
+SMTP_URL=smtps://user:password@mail.example.com:465     # or smtp://…:587 (STARTTLS)
+REPORT_FROM=Tacilytics <reports@example.com>
+REPORT_HOUR_UTC=6                                         # Monday, this hour (UTC)
+TACILYTICS_ORIGIN=https://analytics.example.com           # for the dashboard link in the mail
+```
+
+## Alerts
+
+**Alerts** (toolbar) sends a message to a webhook — Discord, Slack, or anything that takes JSON — when:
+
+- **Traffic spike:** about 3× the usual for this hour of the day,
+- **Traffic drop:** under 20 % of usual (often: the tracker fell off the site),
+- **Goal reached:** e.g. 10× `Purchase` within 1 hour, 24 hours or 7 days.
+
+"Usual" is the median of the same hour over the last 14 days, so quiet nights don't look like incidents. Checked every 10 minutes, with a cooldown so one long spike is one message. **Test** sends a sample message. Admins and owners manage alerts.
+
+Webhooks entered in the dashboard must be public `https://` addresses — no localhost, private ranges or redirects, so nobody on the team can use alerts to reach internal services. `DIGEST_WEBHOOK_URL` from `.env` is the default target (and may be internal); sites without own alerts keep the default spike/drop alerts there.
+
 ## Live visitors
 
 Click **“● online now”** for a realtime view: a 30-minute pulse and a live feed of
@@ -210,6 +259,10 @@ counts unique visitors *per day* and can’t follow the same person across days
 devices. You get the 95 % that matters (how many, which pages, from where) with 0 %
 cookie banner — the same approach as Plausible/Fathom.
 
+## Light mode & German
+
+Settings → Security → **Appearance**: *Theme* (System / Light / Dark) and *Language* (Automatic / English / Deutsch), saved per browser. *System* follows the device's light/dark setting live; *Automatic* picks German when the browser is German. Your data (paths, sources, event names) is never translated.
+
 ## Team, 2FA & passkeys
 
 Out of the box the dashboard opens with one shared passphrase (`WEB_PASSWORD`). When you want more:
@@ -228,9 +281,15 @@ Everyone can turn on, **optionally**:
 - **Passkeys** (Face ID, Touch ID, Windows Hello, security keys). A passkey replaces password *and* code and cannot be phished.
 - **One-time codes (TOTP)** from any authenticator app, with 10 single-use **recovery codes**. Codes cannot be reused.
 
+**Forgot the password?** An owner clicks **Password link** next to the person in Settings → Team: a one-time link (24 h) to set a new one. Their 2FA stays on and all their sessions end.
+
+**Activity log:** owners see every change in Settings → Activity — who added a site, invited someone, changed a role, created an API key, turned 2FA off … with time and address. Failed attempts and sign-ins are not logged, secrets never. Kept for a year (`AUDIT_RETENTION_DAYS`, minimum 30).
+
 **Locked out?** On the server: `tacilytics users` lists accounts, `tacilytics reset-login <username>` prints a new password, turns 2FA off and ends that person's sessions. An owner can also reset a teammate's 2FA in Settings → Team.
 
-The API key (`API_KEY`, Bearer) keeps owner rights for agents and the CLI.
+**API keys per person:** Settings → Security → API keys creates a personal key (`tk_…`) for scripts, agents and the CLI. It acts as you and never more: it sees only your sites, is **read-only unless you untick it** (a viewer's key always is), and cannot manage the team or change security settings. Keys are stored as SHA-256, shown once, and can be revoked; removing a member revokes theirs.
+
+The server-wide `API_KEY` from `.env` keeps owner rights for agents and the CLI on your own box.
 
 ## Configuration
 
@@ -239,10 +298,15 @@ The API key (`API_KEY`, Bearer) keeps owner rights for agents and the CLI.
 | `PORT` | `3920` | Port (bound to 127.0.0.1) |
 | `WEB_PASSWORD` | `tacilytics` | Dashboard passphrase — **only until the first account exists** |
 | `TACILYTICS_ORIGIN` | request host | Public URL of the dashboard, e.g. `https://analytics.example.com`. Pins the passkey domain; recommended behind a proxy |
-| `TRUST_PROXY` | `1` | Number of reverse proxies in front of Tacilytics (e.g. Cloudflare + Caddy = `2`). Rate limits **and visitor hashes** use the address the outermost trusted proxy saw, never the client-written first `X-Forwarded-For` entry. Too low: with two proxies and `1`, every visitor looks like the Cloudflare address and unique visitors collapse. Too high: clients can pick their own address and bypass the limits. Tacilytics binds to 127.0.0.1, so a proxy is always in front and `0` is almost always wrong (everyone becomes 127.0.0.1) |
+| `TRUST_PROXY` | `1` | Number of HTTP reverse proxies in front of Tacilytics that append `X-Forwarded-For` (e.g. Cloudflare + Caddy = `2`; a plain TCP forwarder like socat or `ssh -L` does not count). Rate limits **and visitor hashes** use the address the outermost trusted proxy saw, never the client-written first `X-Forwarded-For` entry. Too low: with two proxies and `1`, every visitor looks like the Cloudflare address and unique visitors collapse. Too high: clients can pick their own address and bypass the limits. Tacilytics binds to 127.0.0.1, so a proxy is always in front and `0` is almost always wrong (everyone becomes 127.0.0.1). A request without `X-Forwarded-For` logs a one-time warning |
 | `INGEST_SALT` | fixed | Extra server-side secret mixed into the visitor hash (on top of the random daily salt) |
 | `API_KEY` | — | Bearer key for the API / CLI |
 | `DB_PATH` | `./data/analytics.db` | SQLite path |
+| `DIGEST_WEBHOOK_URL` | — | Daily digest + default alert target (Discord/Slack-compatible). `off` disables it |
+| `WATCH_MIN_VISITORS` | `10` | Spike/drop alerts stay silent below this many visitors per hour |
+| `SMTP_URL` / `REPORT_FROM` | — | Mail server + sender for the weekly report |
+| `REPORT_HOUR_UTC` | `6` | Monday hour (UTC) the weekly report goes out; it covers the last 7 full days in each site's time zone |
+| `AUDIT_RETENTION_DAYS` | `365` | How long the team activity log is kept (min. 30) |
 | `DATA_RETENTION_DAYS` | `0` | `0` = keep forever; `>0` purges raw events older than N days, daily (data minimisation) |
 
 ## Privacy & security

package/auth.js

@@ -15,10 +15,12 @@
  * TOTP secrets are stored as-is (they must be readable to verify codes).
  */
 const crypto = require('crypto');
+const PKG_VERSION = require('./package.json').version;
 
 const ROLES = { viewer: 1, admin: 2, owner: 3 };
 const SESSION_DAYS = 30;
 const INVITE_DAYS = 7;
+const RESET_HOURS = 24;
 const MIN_PW = 10;
 
 // ── small crypto helpers ───────────────────────────────────────────────────
@@ -138,6 +140,33 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
       created INTEGER NOT NULL,
       expires INTEGER NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS audit_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts INTEGER NOT NULL,
+      actor TEXT,                 -- username, 'API key', 'passphrase', or NULL (public: invite / reset link)
+      action TEXT NOT NULL,       -- e.g. 'site.add', 'team.invite', 'me.totp.enable'
+      target TEXT,                -- what it was about (domain, username, …) — never a secret
+      ip TEXT                     -- address as seen through the proxy; for "was that me?"
+    );
+    CREATE INDEX IF NOT EXISTS idx_audit_ts ON audit_log(ts);
+    CREATE TABLE IF NOT EXISTS api_keys (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      key_hash TEXT NOT NULL UNIQUE,
+      prefix TEXT NOT NULL,       -- first characters, shown in the list so people can tell keys apart
+      user_id INTEGER NOT NULL,
+      name TEXT,
+      read_only INTEGER NOT NULL DEFAULT 1,
+      created INTEGER NOT NULL,
+      last_used INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS password_resets (
+      token_hash TEXT PRIMARY KEY,
+      user_id INTEGER NOT NULL,
+      created_by INTEGER,
+      created INTEGER NOT NULL,
+      expires INTEGER NOT NULL,
+      used_at INTEGER
+    );
     CREATE TABLE IF NOT EXISTS invites (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       token_hash TEXT NOT NULL UNIQUE,
@@ -169,6 +198,39 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     pkGet: db.prepare('SELECT * FROM passkeys WHERE id = ?'),
   };
   const hasUsers = () => q.userCount.get().n > 0;
+
+  // ── audit log ──────────────────────────────────────────────────────────────
+  // Every successful state change (POST/PATCH/DELETE answered with 2xx) gets one row, written
+  // 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_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 === 'apikey') return 'API key';
+    if (p.kind === 'legacy') return 'passphrase';
+    return null;
+  }
+  app.use((req, res, next) => {
+    if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS' || AUDIT_SKIP.has(req.path)) return next();
+    res.on('finish', () => {
+      if (res.statusCode < 200 || res.statusCode >= 300) return;
+      try {
+        const a = res.locals.audit || {};
+        const route = req.route ? req.route.path : req.path;
+        const action = a.action || `${req.method} ${route}`;
+        const actor = a.actor !== undefined ? a.actor : actorOf(req.principal);
+        insAudit.run(Date.now(), actor, action, a.target == null ? null : String(a.target).slice(0, 200), clientIp(req));
+      } catch (e) { console.error('audit log:', e.message); }
+    });
+    next();
+  });
+  setInterval(() => db.prepare('DELETE FROM audit_log WHERE ts < ?').run(Date.now() - AUDIT_DAYS * 864e5), 6 * 3600e3).unref();
+  const audit = (res, action, target, actor) => { res.locals.audit = { action, target, ...(actor !== undefined ? { actor } : {}) }; };
   if (hasUsers() && !process.env.TACILYTICS_ORIGIN) {
     console.warn('⚠️  TACILYTICS_ORIGIN is not set. Passkeys use the request host, so they break if the dashboard is reached under another host/port or behind a proxy without X-Forwarded-Proto. Set it to the public dashboard URL.');
   }
@@ -183,10 +245,21 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
   }
   function principal(req) {
     // agents / CLI: API key = owner over everything
-    if (API_KEY) {
-      const hdr = String(req.headers['authorization'] || '');
-      const key = hdr.startsWith('Bearer ') ? hdr.slice(7) : String(req.headers['x-api-key'] || '');
-      if (key && safeEq(key, API_KEY)) return { kind: 'apikey', role: 'owner', sites: null, user: null };
+    const hdr = String(req.headers['authorization'] || '');
+    const key = hdr.startsWith('Bearer ') ? hdr.slice(7) : String(req.headers['x-api-key'] || '');
+    if (key) {
+      // the server-wide API_KEY from .env: owner over everything (agents / CLI on your own box)
+      if (API_KEY && safeEq(key, API_KEY)) return { kind: 'apikey', role: 'owner', sites: null, user: null };
+      // personal keys (tk_…): act as their owner, never more — and read-only unless created otherwise
+      if (key.startsWith('tk_')) {
+        const k = db.prepare('SELECT * FROM api_keys WHERE key_hash = ?').get(sha256(key));
+        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 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 null; // a wrong key is a failed sign-in, not an anonymous request
     }
     const t = String(req.headers['x-session-token'] || '');
     if (!t) return null;
@@ -405,13 +478,16 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     const uid = tx();
     if (uid === 'taken') return res.status(409).json({ error: 'This username is taken' });
     if (!uid) return res.status(404).json({ error: 'This invite link is invalid, used or expired' });
+    audit(res, 'team.join', name, name);
     res.json({ token: createSession(uid) });
   });
 
   // ── me ─────────────────────────────────────────────────────────────────────
   app.get('/api/me', auth, (req, res) => {
     const p = req.principal;
-    const out = { kind: p.kind, role: p.role, accounts: hasUsers() };
+    // version only behind auth: a public number would tell scanners which instances still run a release
+    // with a known hole (Tyto). Never in /auth/status, the login screen or share links.
+    const out = { kind: p.kind, role: p.role, accounts: hasUsers(), version: PKG_VERSION };
     if (p.user) {
       const u = q.userById.get(p.user.id);
       Object.assign(out, publicUser(u), {
@@ -421,7 +497,10 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     }
     res.json(out);
   });
-  const userOnly = (req, res, next) => (req.principal.user ? next() : res.status(400).json({ error: 'Create an account first' }));
+  const userOnly = (req, res, next) => {
+    if (req.principal.kind === 'userkey') 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) {
     if (rateLimited('reauth:' + req.principal.user.id, 10, 15 * 60000)) { res.status(429).json({ error: 'Too many attempts — wait 15 minutes' }); return false; }
     const u = q.userById.get(req.principal.user.id);
@@ -435,6 +514,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     if (npw.length < MIN_PW) return res.status(400).json({ error: `Password needs at least ${MIN_PW} characters` });
     db.prepare('UPDATE users SET pw_hash = ? WHERE id = ?').run(await hashPassword(npw), req.principal.user.id);
     q.sessDelUserExcept.run(req.principal.user.id, req.principal.tokenHash); // sign out other devices
+    audit(res, 'me.password');
     res.json({ ok: true });
   });
 
@@ -460,11 +540,13 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     db.prepare('UPDATE users SET totp_secret = totp_pending, totp_pending = NULL, totp_last_step = ?, recovery = ? WHERE id = ?')
       .run(step, JSON.stringify(codes.map((c) => sha256(normRecovery(c)))), u.id);
     q.sessDelUserExcept.run(u.id, req.principal.tokenHash);
+    audit(res, 'me.2fa.on');
     res.json({ ok: true, recoveryCodes: codes });
   });
   app.post('/api/me/totp/disable', auth, userOnly, async (req, res) => {
     if (!(await needPassword(req, res))) return;
     db.prepare('UPDATE users SET totp_secret = NULL, totp_pending = NULL, totp_last_step = NULL, recovery = NULL WHERE id = ?').run(req.principal.user.id);
+    audit(res, 'me.2fa.off');
     res.json({ ok: true });
   });
   app.post('/api/me/recovery', auth, userOnly, async (req, res) => {
@@ -473,6 +555,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     if (!u.totp_secret) return res.status(400).json({ error: '2FA is off' });
     const codes = newRecoveryCodes();
     db.prepare('UPDATE users SET recovery = ? WHERE id = ?').run(JSON.stringify(codes.map((c) => sha256(normRecovery(c)))), u.id);
+    audit(res, 'me.recovery.new');
     res.json({ recoveryCodes: codes });
   });
 
@@ -505,15 +588,53 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     const name = String(b.name || '').trim().slice(0, 60) || 'Passkey';
     db.prepare('INSERT INTO passkeys (id, user_id, public_key, counter, transports, name, created) VALUES (?, ?, ?, ?, ?, ?, ?)')
       .run(c.id, t.userId, Buffer.from(c.publicKey), c.counter || 0, c.transports ? JSON.stringify(c.transports) : null, name, Date.now());
+    audit(res, 'me.passkey.add', name);
     res.json({ ok: true });
   });
   app.delete('/api/me/passkeys/:id', auth, userOnly, (req, res) => {
+    const pk = db.prepare('SELECT name FROM passkeys WHERE id = ? AND user_id = ?').get(String(req.params.id), req.principal.user.id);
     db.prepare('DELETE FROM passkeys WHERE id = ? AND user_id = ?').run(String(req.params.id), req.principal.user.id);
+    audit(res, 'me.passkey.remove', pk ? pk.name : null);
+    res.json({ ok: true });
+  });
+
+  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' });
+    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));
+  });
+
+  // ── 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 })));
+  });
+  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';
+    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
+  });
+  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);
+    db.prepare('DELETE FROM api_keys WHERE id = ? AND user_id = ?').run(Number(req.params.id), req.principal.user.id);
+    audit(res, 'me.apikey.revoke', k ? `${k.name} (${k.prefix}…)` : null);
     res.json({ ok: true });
   });
 
   // ── team (owner) ───────────────────────────────────────────────────────────
-  const ownerOnly = requireRole('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'
+    ? 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
   app.post('/api/team/bootstrap', ownerOnly, async (req, res) => {
@@ -524,6 +645,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     if (pw.length < MIN_PW) return res.status(400).json({ error: `Password needs at least ${MIN_PW} characters` });
     const info = q.insUser.run(name, await hashPassword(pw), 'owner', null, b64u(crypto.randomBytes(16)), Date.now());
     q.sessDelLegacy.run(); // WEB_PASSWORD sessions end here
+    audit(res, 'team.first-owner', name);
     res.json({ token: createSession(info.lastInsertRowid) });
   });
 
@@ -545,10 +667,12 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     const expires = Date.now() + INVITE_DAYS * 864e5;
     db.prepare('INSERT INTO invites (token_hash, role, sites, created_by, created, expires) VALUES (?, ?, ?, ?, ?, ?)')
       .run(sha256(token), role, sites ? JSON.stringify(sites) : null, req.principal.user ? req.principal.user.id : null, Date.now(), expires);
+    audit(res, 'team.invite', role + (sites ? ' · sites ' + sites.join(',') : ''));
     res.json({ url: '/invite/' + token, role, expires });
   });
   app.delete('/api/team/invites/:id', ownerOnly, (req, res) => {
     db.prepare('DELETE FROM invites WHERE id = ? AND used_at IS NULL').run(Number(req.params.id));
+    audit(res, 'team.invite.revoke', '#' + Number(req.params.id));
     res.json({ ok: true });
   });
   app.patch('/api/team/users/:id', ownerOnly, (req, res) => {
@@ -562,6 +686,7 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     if (sites === undefined) return res.status(400).json({ error: 'sites must be a list of site ids or null' });
     if (Array.isArray(sites) && !sites.length) return res.status(400).json({ error: 'Pick at least one site' });
     db.prepare('UPDATE users SET role = ?, sites = ? WHERE id = ?').run(role, sites ? JSON.stringify(sites) : null, u.id);
+    audit(res, 'team.change', `${u.username}: ${u.role} → ${role}` + (sites ? ' · sites ' + sites.join(',') : ''));
     res.json(publicUser(q.userById.get(u.id)));
   });
   app.delete('/api/team/users/:id', ownerOnly, (req, res) => {
@@ -570,9 +695,12 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     if (u.role === 'owner' && q.ownerCount.get().n <= 1) return res.status(400).json({ error: 'There must be at least one owner' });
     db.transaction(() => {
       db.prepare('DELETE FROM passkeys WHERE user_id = ?').run(u.id);
+      db.prepare('DELETE FROM password_resets WHERE user_id = ?').run(u.id);
+      db.prepare('DELETE FROM api_keys WHERE user_id = ?').run(u.id);
       q.sessDelUser.run(u.id);
       db.prepare('DELETE FROM users WHERE id = ?').run(u.id);
     })();
+    audit(res, 'team.remove', u.username);
     res.json({ ok: true });
   });
   // owner can reset 2FA of a teammate who lost their phone (the teammate then sets it up again)
@@ -581,10 +709,59 @@ function setupAuth({ app, db, WEB_PASSWORD, API_KEY, rateLimited, clientIp, site
     if (!u) return res.status(404).json({ error: 'Unknown user' });
     db.prepare('UPDATE users SET totp_secret = NULL, totp_pending = NULL, totp_last_step = NULL, recovery = NULL WHERE id = ?').run(u.id);
     q.sessDelUser.run(u.id);
+    audit(res, 'team.2fa.reset', u.username);
     res.json({ ok: true });
   });
 
-  return { auth, requireRole, siteAllowed, principal };
+  // owner creates a one-time password-reset link for a teammate (24 h). Only the password changes:
+  // 2FA stays on (a reset link must not be a way around it) and all their sessions end.
+  app.post('/api/team/users/:id/reset-link', ownerOnly, (req, res) => {
+    const u = q.userById.get(Number(req.params.id));
+    if (!u) return res.status(404).json({ error: 'Unknown user' });
+    const token = randToken();
+    const expires = Date.now() + RESET_HOURS * 3600e3;
+    db.transaction(() => {
+      db.prepare('DELETE FROM password_resets WHERE user_id = ?').run(u.id); // only the newest link works
+      db.prepare('INSERT INTO password_resets (token_hash, user_id, created_by, created, expires) VALUES (?, ?, ?, ?, ?)')
+        .run(sha256(token), u.id, req.principal.user ? req.principal.user.id : null, Date.now(), expires);
+    })();
+    audit(res, 'team.reset-link', u.username);
+    res.json({ url: '/reset/' + token, username: u.username, expires });
+  });
+  function resetByToken(token) {
+    const r = db.prepare('SELECT * FROM password_resets WHERE token_hash = ?').get(sha256(String(token || '')));
+    if (!r || r.used_at || r.expires < Date.now()) return null;
+    return r;
+  }
+  app.get('/api/reset/:token', (req, res) => {
+    if (rateLimited('inv:' + clientIp(req), 30, 15 * 60000)) return res.status(429).json({ error: 'Too many attempts — wait 15 minutes' });
+    const r = resetByToken(req.params.token);
+    const u = r && q.userById.get(r.user_id);
+    if (!u) return res.status(404).json({ error: 'This reset link is invalid, used or expired' });
+    res.json({ username: u.username, totp: !!u.totp_secret, expires: r.expires });
+  });
+  app.post('/api/reset/:token', async (req, res) => {
+    if (rateLimited('inv:' + clientIp(req), 30, 15 * 60000)) return res.status(429).json({ error: 'Too many attempts — wait 15 minutes' });
+    const pw = String((req.body || {}).password || '');
+    if (pw.length < MIN_PW) return res.status(400).json({ error: `Password needs at least ${MIN_PW} characters` });
+    if (!resetByToken(req.params.token)) return res.status(404).json({ error: 'This reset link is invalid, used or expired' });
+    const pwHash = await hashPassword(pw); // async scrypt, outside the (synchronous) transaction
+    const uid = db.transaction(() => {
+      const r = resetByToken(req.params.token); // checked again: used/expired while hashing?
+      if (!r || !q.userById.get(r.user_id)) return null;
+      db.prepare('UPDATE password_resets SET used_at = ? WHERE token_hash = ?').run(Date.now(), r.token_hash);
+      db.prepare('UPDATE users SET pw_hash = ? WHERE id = ?').run(pwHash, r.user_id);
+      q.sessDelUser.run(r.user_id);
+      return r.user_id;
+    })();
+    if (!uid) return res.status(404).json({ error: 'This reset link is invalid, used or expired' });
+    // no session here: the person signs in normally (with 2FA, if they have it)
+    const who = q.userById.get(uid).username;
+    audit(res, 'me.password.reset-link', who, who);
+    res.json({ ok: true, username: who });
+  });
+
+  return { auth, requireRole, siteAllowed, principal, audit };
 }
 
 // ── offline admin (CLI on the server, for lock-outs) ─────────────────────────
@@ -600,6 +777,9 @@ function adminOps(db) {
       const pw = crypto.randomBytes(12).toString('base64url');
       db.prepare('UPDATE users SET pw_hash = ?, totp_secret = NULL, totp_pending = NULL, totp_last_step = NULL, recovery = NULL WHERE id = ?').run(hashPasswordSync(pw), u.id);
       db.prepare('DELETE FROM sessions WHERE user_id = ?').run(u.id);
+      // the dashboard's activity log should show this too (the CLI bypasses the HTTP audit middleware)
+      if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='audit_log'").get())
+        db.prepare('INSERT INTO audit_log (ts, actor, action, target, ip) VALUES (?, ?, ?, ?, ?)').run(Date.now(), 'CLI', 'cli.reset', u.username, null);
       return pw;
     },
   };