statswhatshesaid 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,151 @@
+# statswhatshesaid
+
+## 0.3.0
+
+### Minor Changes
+
+- a404924: **Library — opt-in shared-salt mode + raw HLL sketch export**
+
+  Add a new `saltSecret` option (env: `STATS_SALT_SECRET`). When set, the
+  daily HLL salt is derived as `HMAC-SHA-256(saltSecret, utcDate)` instead of
+  random per-process bytes. Replicas configured with the same secret then
+  produce identical daily salts — the mathematical precondition for an
+  external tool to merge HLL sketches across replicas. Cross-day
+  unlinkability is preserved (the salt still rotates daily).
+
+  When shared-salt mode is on, `GET /stats?format=raw` additionally returns
+  the raw 16,384-byte HLL register array (base64) plus an 8-byte
+  `saltFingerprint` so a collector can verify replicas are using the same
+  salt before merging. When the secret is unset, behavior is unchanged.
+
+  This is fully backwards-compatible: existing deployments need no changes.
+
+  **New package — `statswhatshesaid-collector`**
+
+  External one-shot CLI (`swhsd-collect`) that polls one or more deployed
+  `statswhatshesaid` apps and persists their results to a local SQLite
+  database. Solves what the in-memory library deliberately does not:
+
+  - multi-app aggregation
+  - best-effort persistence across app restarts
+  - long-term retention beyond the library's in-memory window
+  - multi-replica merging (opt-in, requires `STATS_SALT_SECRET`)
+
+  Schedule it however you like — cron, systemd timer, launchd, GitHub
+  Actions. See `packages/collector/README.md` for examples.
+
+## 0.2.0
+
+### Minor Changes
+
+- c5437a3: **One-line drop-in.** statswhatshesaid is now truly one line:
+
+  ```ts
+  // middleware.ts
+  export { default } from "statswhatshesaid";
+  ```
+
+  No `runtime: 'nodejs'` config, no `matcher`, no `experimental` flags, no Next.js 15.2+ requirement. It just works.
+
+  ## Breaking changes
+
+  This is a major architectural change disguised as a `minor` bump because we're still in `0.x`. The headline change: **all persistence is gone**. Counts and history live in process memory only and reset on every restart. This is intentional — see "Why" below.
+
+  - **Removed** `node:fs` entirely. No more snapshot file. No more `.statswhatshesaid.json`. No more atomic-rename writes.
+  - **Removed** `node:crypto`. All hashing now uses Web Crypto (`crypto.subtle.digest`, `crypto.getRandomValues`).
+  - **Removed** the `runtime: 'nodejs'` middleware-config requirement. The library runs in **both** Edge and Node runtimes since it only uses Web APIs.
+  - **Removed** the `PersistAdapter` interface, `FileSnapshotAdapter`, `SnapshotV1` type, and the `persist`, `snapshotPath`, `flushIntervalMs` options.
+  - **Removed** `process.on('SIGTERM' | 'SIGINT' | 'beforeExit')` handlers. There's nothing to flush.
+  - **Removed** the periodic flush timer.
+  - **Removed** the Node-runtime guard (`assertNodeRuntime`). The library no longer cares which runtime you use.
+  - **Lowered** the Next.js peer dependency from `>=15.2.0` to `>=13.0.0`.
+  - **Default export** of the main package is now a pre-instantiated middleware function (was previously the `stats` object). To customize options, import `createMiddleware`:
+    ```ts
+    import { createMiddleware } from "statswhatshesaid";
+    export default createMiddleware({ filterBots: false });
+    ```
+  - **`createMiddleware` now returns an `async` function** since `crypto.subtle.digest` is async. Next.js middleware natively supports async.
+  - **`trackRequest` is now async** for the same reason.
+
+  ## New features
+
+  - **Self-filters common static paths** before tracking (`/_next/static/*`, `/_next/image/*`, `/favicon.ico`, `/robots.txt`, `/sitemap.xml`, `/manifest.json`, etc.) so users don't need a custom `matcher` to skip static assets.
+  - **One-line integration**: `export { default } from 'statswhatshesaid'` is the entire `middleware.ts`.
+
+  ## Why (the short version)
+
+  The previous version's promise of "drop in" was undermined by the four lines of `export const config = { matcher, runtime: 'nodejs' }` boilerplate users had to write, plus the Next.js 15.2+ requirement and the directory of snapshot/WAL/SHM-equivalent file artifacts. The user explicitly wanted a true drop-in for monitoring freshly launched apps and accepted the trade-off of in-memory-only state.
+
+  Edge runtime is now a first-class target. You can deploy this on Vercel Edge Middleware, on a Docker scratch image, on Cloudflare Pages — anywhere modern JS runs.
+
+  ## Bundle size
+
+  ESM bundle: 18.7 KB → **12.2 KB** (smaller because `snapshot.ts`, `FileSnapshotAdapter`, the persist abstraction, and the lifecycle plumbing are all gone).
+
+  ## Tests
+
+  89 unit and integration tests, all passing. The 5-test snapshot suite was deleted along with the file adapter. Persistence-restart and corruption-recovery tests were dropped (no persistence to test). New tests cover the static-path filter, the Web Crypto hash path, and the async constant-time compare.
+
+  End-to-end smoke tested via the `examples/basic` Next.js app: 2 distinct visitors counted, dedup correct, bot filtered, favicon skipped, both query and `Authorization` token paths working, wrong token rejected.
+
+## 0.1.0
+
+### Minor Changes
+
+- 7880aa7: Initial release of `statswhatshesaid` — a super minimal drop-in unique-visitors-per-day stats library for self-hosted Next.js.
+
+  **Features:**
+
+  - One-line integration via Next.js middleware (`export default stats.middleware()`).
+  - Single `/stats?t=<token>` endpoint returning JSON (today's estimate + history).
+  - Cookieless visitor identification: `SHA-256(ip + ua + dailySalt)`, salt rotates at UTC midnight.
+  - HyperLogLog (p=14) cardinality estimation — fixed 16 KB per day, ~0.8% standard error.
+  - Single JSON snapshot file (~22 KB) with atomic `.tmp` + rename writes. Default `./.statswhatshesaid.json`.
+  - Pluggable `PersistAdapter` for bring-your-own backends (Redis, KV, S3).
+  - Edge-runtime guard with a clear, actionable error message.
+  - **Zero runtime dependencies.** No native modules, no Docker volume gymnastics. Works on Alpine, slim, distroless.
+  - Requires Next.js ≥ 15.2 for the `nodejs` middleware runtime.
+
+- 3b295d6: Second-pass hardening found via a targeted re-audit. These fixes all sit inside the existing v0.1.0 window (still unreleased), so they roll into the first published release.
+
+  **Length-prefixed visitor hash construction.** `computeVisitorHash` now prepends a big-endian length header for each variable-length component (ip, ua) before feeding them into SHA-256. The previous `ip + ":" + ua + ":" + salt` encoding was input-ambiguous: with IPv6 addresses containing colons, two distinct `(ip, ua)` pairs could produce the same pre-image and therefore the same hash. Length-prefixing makes the pre-image unambiguous.
+
+  **Snapshot load is now crash-proof.** `VisitorStore.fromSnapshot` wraps both the same-day and cross-day branches in try/catch and degrades gracefully:
+
+  - Decoded salt length is validated (must be exactly 32 bytes) before use.
+  - Decoded HLL register length is validated (must be exactly `HLL_REGISTER_COUNT` bytes) before use. `Buffer.from(x, 'base64')` silently ignores malformed characters, so the base64 string-length check in `isValidSnapshot` alone was insufficient.
+  - On any decode/validation failure, the store starts fresh for the current day rather than throwing out of init. Up to a few minutes of same-day dedupe state is lost; the process stays up.
+
+  **Strict history validation.** `sanitizeHistory` drops any entry that isn't a real `YYYY-MM-DD` calendar date (validated via `Date.UTC` round-trip, rejecting `2026-02-30` and `2025-02-29`) mapped to a non-negative integer count. Entries for `currentDate` itself are dropped (today's count is owned by the live HLL). Protects against snapshot files poisoned by whoever has write access.
+
+  **Snapshot validator rejects arrays.** `isValidSnapshot` now explicitly rejects arrays for the `history` field. Previously `typeof [] === 'object'` let arrays through, which would then be iterated with numeric-string keys.
+
+  **Config sanity checks.** `resolveConfig` now validates:
+
+  - `flushIntervalMs` must be a positive integer ≥ 1000 ms (prevents `setInterval(tick, 0)` hot loops from a bad config).
+  - `historyDays` and `maxHistoryDays` must be non-negative integers.
+  - `endpointPath` must match `^/[A-Za-z0-9\-._~/]*$` — no whitespace, CR/LF, or shell metacharacters.
+
+  All throw loud, clear errors at config resolution time.
+
+  **New `isValidUtcDate` helper.** Shared between snapshot validation and history sanitization. Rejects calendrically-impossible dates like `2026-02-30` via `Date.UTC` round-trip, not just via regex.
+
+  **Tests.** 23 new hardening tests across four describe blocks covering the hash input-ambiguity fix, date validation, config validation, and graceful snapshot-load degradation. Total test count: 76 → 99, all green.
+
+- 64b583f: Security hardening pass before the first public release.
+
+  **New `trustProxy` option** (default: `1`). Determines how many reverse-proxy hops to skip when resolving the client IP from `X-Forwarded-For`. The library now walks the XFF chain from the RIGHT (instead of blindly taking the leftmost entry), which defeats the standard client-side XFF spoofing attack when at least one trusted proxy sits in front of the process. Set to `0` to ignore forwarding headers entirely, or to `N > 1` for chained proxies (e.g. Cloudflare → nginx → app = `2`). Configurable via `STATS_TRUST_PROXY` env var. See the README Security section for recipes.
+
+  **`/stats` now accepts `Authorization: Bearer <token>`** in addition to the `?t=<token>` query string. The header is preferred in production because it does not leak into access logs, browser history, or Referer headers. If both are provided, the header wins.
+
+  **Weak-token warning.** The library emits a one-time `console.warn` at init time if the token is shorter than 32 characters, with guidance to run `openssl rand -hex 32`. The library does NOT reject short tokens — you may deliberately pick a memorable one for ad-hoc browser access.
+
+  **Snapshot file is now written with mode `0o600`** (owner read/write only). The snapshot contains the current day's visitor-hashing salt and should not be world-readable.
+
+  **User-Agent truncation.** Incoming `User-Agent` headers are truncated to 512 bytes before hashing and bot filtering, bounding per-request CPU cost regardless of the upstream header-size limit.
+
+  **Constant-time token comparison.** Token validation now prehashes both sides with SHA-256 before `timingSafeEqual`, so the comparison no longer branches on token length.
+
+  **Process signal handler leak fix.** `shutdown()` now calls `process.removeListener` for its own handlers, fixing a `MaxListenersExceededWarning` that appeared when many init/shutdown cycles ran in the same process (e.g. dev-mode HMR, test suites).
+
+  **README: new Security section** covering the threat model, `trustProxy` semantics with nginx/Caddy/Cloudflare recipes, token handling, flooding limitations, snapshot file contents, and privacy properties.

package/README.md

@@ -1,14 +1,14 @@
 # statswhatshesaid
 
-A super minimal drop-in stats library for **self-hosted Next.js**. One metric, one line of integration, **zero runtime dependencies**.
+A super minimal **one-line** drop-in stats library for Next.js. One metric, one line of integration, **zero runtime dependencies**, in-memory only, runs in **both** the Edge and Node runtimes.
 
 - Tracks **unique visitors per day** — that's it.
 - No tracking pixel, no client JS, no cookies.
-- **Zero dependencies.** No native modules, no SQLite, no Docker volume gymnastics.
-- Single ~22KB JSON file for persistence. Atomic writes. Put it anywhere or nowhere.
+- **Zero dependencies.** No native modules, no filesystem, no SQLite, no Docker volume gymnastics.
+- **Works anywhere.** Edge runtime, Node runtime, Vercel, self-hosted, Docker, scratch images. The library uses only Web APIs (`crypto.subtle`, `crypto.getRandomValues`, `globalThis.fetch`).
 - Read your stats by visiting `myapp.com/stats?t=<your-secret>` — JSON response.
 
-> **Designed for freshly launched apps.** Once traffic gets serious you should graduate to a proper analytics suite (Plausible, Umami, PostHog, ...). This library is the thing you drop in on day one so you can tell whether anyone's visiting yet, with absolutely no setup ceremony.
+> **Designed for freshly launched apps.** Counts and history live in process memory. They survive across requests within a single worker but reset on every deploy / restart. That's the trade-off for "drop in and forget." Once your traffic warrants real analytics, graduate to Plausible / Umami / PostHog.
 
 ## Install
 
@@ -18,21 +18,14 @@ npm install statswhatshesaid
 
 ## Use it
 
-Add **one line** to your `middleware.ts`:
+**One line.** That's it.
 
 ```ts
 // middleware.ts
-import stats from 'statswhatshesaid'
-
-export default stats.middleware()
-
-export const config = {
-  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
-  runtime: 'nodejs', // REQUIRED — see "Edge Runtime" below
-}
+export { default } from 'statswhatshesaid'
 ```
 
-Set your secret in the environment:
+Set your secret:
 
 ```bash
 STATS_TOKEN=pick-a-long-random-string
@@ -57,34 +50,50 @@ You'll get JSON back:
 }
 ```
 
-That's the whole library.
+That's the whole library. No `runtime: 'nodejs'` config, no `matcher`, no `experimental`, no `next.config` flags. Just one re-export line.
 
-## Edge Runtime — read this first
+## Customizing options
 
-Next.js middleware defaults to the **Edge runtime**, which can't run `node:crypto` or `node:fs`. You **must** opt into the Node runtime:
+If you need to change defaults — bot filter, endpoint path, history retention, trustProxy hops — import `createMiddleware` instead:
 
 ```ts
+// middleware.ts
+import { createMiddleware } from 'statswhatshesaid'
+
+export default createMiddleware({
+  endpointPath: '/_internal/stats',
+  filterBots: false,
+  trustProxy: 2,
+})
+```
+
+You can also set a custom `matcher` if you want the middleware to run on a narrower path set than "everything":
+
+```ts
+import { createMiddleware } from 'statswhatshesaid'
+
+export default createMiddleware()
+
 export const config = {
-  matcher: [...],
-  runtime: 'nodejs',
+  matcher: ['/((?!api).*)'],
 }
 ```
 
-This is stable in **Next.js 15.2 and newer**.
-
 ## How a "unique visitor" is counted
 
 Cookieless, Plausible-style:
 
 ```
-visitorHash = SHA-256( ip + ":" + userAgent + ":" + dailySalt )
+visitorHash = SHA-256( length-prefixed( ip ) + length-prefixed( userAgent ) + dailySalt )
 ```
 
-- `dailySalt` is generated in process memory and rotates at every UTC midnight.
+- `dailySalt` is generated in process memory at startup and rotated lazily at every UTC midnight.
 - The hash is fed into a [**HyperLogLog** sketch](https://en.wikipedia.org/wiki/HyperLogLog) with 16384 one-byte registers (16 KB fixed per day, forever).
-- At UTC midnight the day's estimate is written to a historical map and the sketch is reset with a fresh salt.
+- At UTC midnight the day's estimate is moved to an in-memory historical map and the sketch is reset with a fresh salt.
 - Cross-day unlinkability: because the salt is regenerated, hashes from different days can't be correlated back to the same visitor.
+- The hash inputs are length-prefixed so two distinct `(ip, ua)` pairs can never collide via separator ambiguity.
 - Common bot User-Agents are filtered out by default.
+- Common static asset paths (`/_next/static/*`, `/_next/image/*`, `/favicon.ico`, `/robots.txt`, `/sitemap.xml`, `/manifest.json`, etc.) are filtered out before tracking, so you don't need a custom `matcher`.
 
 ### About accuracy
 
@@ -94,122 +103,57 @@ If you need exact counts down to the last human, don't use this library — grad
 
 ## Storage
 
-A single JSON file. Default location: `./.statswhatshesaid.json`.
-
-```jsonc
-{
-  "version": 1,
-  "today": "2026-04-07",
-  "salt": "<base64 32 bytes>",
-  "hllRegisters": "<base64 16 KB>",
-  "history": { "2026-04-06": 388, "2026-04-05": 401 }
-}
-```
-
-- **One file.** Not a directory, not a DB, no WAL/SHM sidecars.
-- **~22 KB today + 20 bytes per historical day.** Never grows beyond a few hundred KB, ever.
-- **Atomic writes** via write-to-`.tmp` + `rename`. Crash-safe.
-- **Flushed every hour** (tunable) and on `SIGTERM`/`SIGINT`/`beforeExit`.
-- **Nothing on the hot path touches disk.** Tracking a visit is: one SHA-256, one HLL register update. Sub-millisecond.
-
-### Docker / containers
-
-Because it's one small file, you have options:
-
-```dockerfile
-# Option A: persist it on a volume
-VOLUME /data
-ENV STATS_SNAPSHOT_PATH=/data/stats.json
-```
-
-```dockerfile
-# Option B: bind-mount a single file from the host
-# docker run -v $(pwd)/stats.json:/app/stats.json \
-#            -e STATS_SNAPSHOT_PATH=/app/stats.json ...
-```
-
-```dockerfile
-# Option C: accept ephemerality. Losing "today" on a redeploy is often fine
-# for a small app. The snapshot is flushed on SIGTERM when Node is PID 1,
-# so graceful stops keep the latest data.
-ENV STATS_SNAPSHOT_PATH=/tmp/statswhatshesaid.json
-```
-
-Works fine on `node:20-alpine`, `node:20-slim`, distroless — there are no native modules to compile.
+**There is none.** Counts and history live in module-level memory inside whichever Next.js worker is running your middleware.
 
-### Bring your own backend
+- ✅ State **survives across requests** within a single worker / Edge isolate (which is what makes the counter actually count).
+- ❌ State is **lost on every deploy**, process restart, or worker recycle.
+- ❌ State is **per-instance**: if you're running multiple replicas behind a load balancer, each replica has its own counter and they don't sync. Run a single instance, or use a real analytics tool.
 
-If you want to stash the snapshot in Redis, Vercel KV, S3, or anything else, pass a `persist` adapter:
-
-```ts
-import stats from 'statswhatshesaid'
-import type { PersistAdapter, SnapshotV1 } from 'statswhatshesaid'
-
-const redisPersist: PersistAdapter = {
-  load: () => {
-    const raw = redisClient.get('statswhatshesaid:snap') // your sync/blocking client
-    return raw ? (JSON.parse(raw) as SnapshotV1) : null
-  },
-  save: (snap) => {
-    redisClient.set('statswhatshesaid:snap', JSON.stringify(snap))
-  },
-}
-
-export default stats.middleware({ persist: redisPersist })
-```
-
-The adapter interface is synchronous on purpose so the shutdown handler can flush deterministically.
+This is intentional. The library exists to give freshly launched apps an "is anybody home?" signal in 30 seconds with zero infrastructure. Persistence and replication are a different problem class — graduate when you need them.
 
 ## Configuration
 
-Configure via env vars (preferred) or by passing options to `stats.middleware({...})`. Options override env.
+Configure via env vars (preferred for `STATS_TOKEN`) or by passing options to `createMiddleware({...})`. Options override env.
 
 | Option | Env var | Default |
 | --- | --- | --- |
 | `token` | `STATS_TOKEN` | **required** |
-| `snapshotPath` | `STATS_SNAPSHOT_PATH` | `./.statswhatshesaid.json` |
-| `persist` | — | file adapter at `snapshotPath` |
-| `flushIntervalMs` | `STATS_FLUSH_INTERVAL_MS` | `3600000` (1 hour) |
 | `endpointPath` | `STATS_ENDPOINT_PATH` | `/stats` |
 | `historyDays` | — | `90` (returned from `/stats`) |
-| `maxHistoryDays` | — | `365` (kept in snapshot) |
+| `maxHistoryDays` | — | `365` (kept in memory) |
 | `filterBots` | — | `true` |
 | `trustProxy` | `STATS_TRUST_PROXY` | `1` (see [Security](#security) below) |
+| `saltSecret` | `STATS_SALT_SECRET` | unset (see [Multi-replica deployments](#multi-replica-deployments) below) |
 
-```ts
-export default stats.middleware({
-  endpointPath: '/_internal/stats',
-  flushIntervalMs: 5 * 60 * 1000,
-  historyDays: 30,
-  trustProxy: 1,
-})
-```
+## Multi-replica deployments
+
+The default in-memory design is single-instance: each Next.js worker has its own HyperLogLog sketch. If you run multiple replicas, each replica counts the visitors it serves, with no awareness of the others — visitor numbers across `/stats` will differ from replica to replica.
+
+If you want a single consolidated number across replicas, you can opt in to **shared-salt mode** and pair it with an external collector that merges sketches:
+
+1. Set `STATS_SALT_SECRET` (any long random string — `openssl rand -hex 32`) to the **same value** on every replica. The daily HLL salt then becomes `HMAC-SHA-256(saltSecret, utcDate)` — deterministic across replicas, still rotating daily, so cross-day unlinkability is preserved.
+2. Run [`statswhatshesaid-collector`](../collector) — an external CLI — on a machine you control. Configure it with the per-replica URLs and the `STATS_TOKEN`. The collector polls `/stats?format=raw` from each replica, fetches the raw HLL register array plus a salt fingerprint, verifies the fingerprints match, merges the sketches register-wise (element-wise max), and stores the merged daily number in a local SQLite database.
+
+If you don't set `STATS_SALT_SECRET`, the library behaves exactly as before — random per-process salts, `/stats?format=raw` simply ignored — and you can run a single-replica deployment without any of this.
 
 ## Security
 
-This is a minimal library, but it runs inside your app's request path and writes to your filesystem, so its defaults matter. Read this section before deploying.
+This is a minimal library, but it runs inside your app's request path, so its defaults matter. Read this section before deploying.
 
 ### Threat model
 
 - **In scope:** preventing trivial forging of visitor counts, protecting the `/stats` endpoint from unauthorized reads, keeping the process alive under abuse, making visitor hashes cross-day unlinkable.
-- **Out of scope:** preventing a determined attacker with unlimited resources from skewing the numbers. statswhatshesaid is for day-one visibility on small, self-hosted apps. Once your traffic is big enough that someone would bother flooding your stats, you should be on Plausible / Umami / PostHog anyway.
+- **Out of scope:** preventing a determined attacker with unlimited resources from skewing the numbers. statswhatshesaid is for day-one visibility on small apps. Once your traffic is big enough that someone would bother flooding your stats, you should be on Plausible / Umami / PostHog anyway.
 
 ### 1. `trustProxy` — who decides the client IP?
 
 Unique-visitor dedup hashes the client IP alongside the User-Agent. If the attacker controls the IP you hash with, they control the count.
 
-**The problem:** `X-Forwarded-For` is a list of IPs separated by commas. Each reverse proxy in the chain **appends** the IP of *its own peer* (the thing that spoke TCP to it). The *leftmost* entry is whatever the original client claimed — i.e. attacker-controlled. The *rightmost N entries* are what trusted proxies added, so they're authentic.
-
-To pick the real client IP safely you must **walk the chain from the right, skipping one entry per trusted proxy**.
-
-**Configuration:**
-
-- `trustProxy: 0` — Never read forwarding headers. Every request hashes to a single constant peer. `uniqueVisitors` will under-count dramatically (ideally it collapses to 1), but **nothing an attacker sends can forge it**. Use this only if (a) your process is directly exposed to untrusted clients, or (b) you're OK with a "did anybody visit today?" binary signal.
-
-- `trustProxy: 1` **(default)** — One trusted reverse proxy sits in front of this Node process. The library takes the **rightmost** entry of `X-Forwarded-For`. This is correct for the single most common self-hosted shape: `client → nginx → next`, or `client → Caddy → next`, or `client → Traefik → next`.
-
-- `trustProxy: 2` — Two trusted hops. The library takes the **second-from-right** entry of `X-Forwarded-For`. Use this for setups like `client → Cloudflare → nginx → next` where Cloudflare is ALSO adding to XFF.
+`X-Forwarded-For` is a list of IPs separated by commas. Each reverse proxy in the chain **appends** the IP of *its own peer*. The *leftmost* entry is whatever the original client claimed — i.e. attacker-controlled. The *rightmost N entries* are what trusted proxies added, so they're authentic. To pick the real client IP safely you must **walk the chain from the right, skipping one entry per trusted proxy**.
 
+- `trustProxy: 0` — Never read forwarding headers. Every request hashes to a single constant peer. `uniqueVisitors` will under-count, but **nothing an attacker sends can forge it**.
+- `trustProxy: 1` **(default)** — One trusted reverse proxy in front of this process (`client → nginx → next`). Library takes the **rightmost** entry of `X-Forwarded-For`.
+- `trustProxy: 2` — Two trusted hops (`client → Cloudflare → nginx → next`). Library takes the **second-from-right** entry.
 - `trustProxy: N` — Generalizes to N trusted hops.
 
 **nginx recipe (trustProxy = 1):**
@@ -222,93 +166,64 @@ location / {
 }
 ```
 
-`$proxy_add_x_forwarded_for` appends the client's socket IP to whatever XFF the client sent. With `trustProxy: 1`, statswhatshesaid ignores whatever the client sent and takes the rightmost entry (which is what nginx appended). The client's spoofed values sit uselessly to the left.
-
-**Caddy recipe (trustProxy = 1):**
-
-```caddyfile
-example.com {
-  reverse_proxy 127.0.0.1:3000
-}
-```
-
-Caddy automatically appends the client IP to `X-Forwarded-For` by default.
-
-**Cloudflare + nginx recipe (trustProxy = 2):**
-
-```nginx
-# nginx behind Cloudflare
-location / {
-  proxy_pass http://127.0.0.1:3000;
-  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-}
-```
-
-With `trustProxy: 2`, the second-from-right entry is the real client: `attacker-spoof, real-client, cloudflare-edge`.
+`$proxy_add_x_forwarded_for` appends the client's socket IP to whatever XFF the client sent. With `trustProxy: 1`, statswhatshesaid takes the rightmost entry (nginx's appended value), and the client's spoofed values sit uselessly to the left.
 
-**Direct-exposed (no proxy) warning:** If you're running `next start` straight on `0.0.0.0:3000` with no proxy, **any header you see is attacker-controlled**. Set `trustProxy: 0` and accept that visitor dedup won't work, OR put any reverse proxy in front.
+**Direct-exposed (no proxy) warning:** If you're running Next.js straight on `0.0.0.0:3000` with no proxy in front, **any header you see is attacker-controlled**. Set `trustProxy: 0` and accept that visitor dedup won't work, OR put any reverse proxy in front.
 
 ### 2. Token strength and rate limiting
 
-`/stats` is protected by a single static token. A short token is brute-forceable if an attacker hammers the endpoint.
+`/stats` is protected by a single static token. A short token is brute-forceable.
 
-- statswhatshesaid **warns** at startup if your token is shorter than 32 characters. It does not reject — you might deliberately pick a memorable token for ad-hoc browser access from anywhere.
+- statswhatshesaid **warns** at startup if your token is shorter than 32 characters. It does not reject — you might pick a memorable token for ad-hoc browser access.
 - A safer choice: `openssl rand -hex 32` → a 64-char hex string.
-- The library does **not** rate-limit `/stats`. That's your CDN / reverse-proxy / application middleware's job. For nginx: [`limit_req`](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html). For Cloudflare: [rate limiting rules](https://developers.cloudflare.com/waf/rate-limiting-rules/). For Next.js middleware chains: [`@upstash/ratelimit`](https://github.com/upstash/ratelimit-js).
+- The library does **not** rate-limit `/stats`. That's your CDN / reverse-proxy / application middleware's job ([nginx `limit_req`](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html), [Cloudflare rate limiting](https://developers.cloudflare.com/waf/rate-limiting-rules/), [`@upstash/ratelimit`](https://github.com/upstash/ratelimit-js)).
 
 ### 3. Passing the token: `Authorization` header vs query string
 
-You can pass the token two ways:
+Two ways to pass the token:
 
 | Method | Use when |
 | --- | --- |
 | `Authorization: Bearer <token>` header | **Production** — doesn't leak to access logs, browser history, or Referer |
-| `?t=<token>` query string | Ad-hoc browser checks where typing a header is annoying |
+| `?t=<token>` query string | Ad-hoc browser checks |
 
-Both are accepted. If both are present, the `Authorization` header wins. Example production check:
+Both are accepted. If both are present, the `Authorization` header wins.
 
 ```bash
 curl -H "Authorization: Bearer $STATS_TOKEN" https://myapp.com/stats
 ```
 
-The query string is convenient but ends up in **nginx/CDN access logs, browser history, and Referer headers**. Don't link to `/stats?t=...` from any page.
-
 ### 4. Count inflation by flooding
 
-An attacker who can send arbitrary (IP, User-Agent) pairs — even behind a correctly configured `trustProxy` — can insert arbitrarily many distinct "visitors" into the HLL sketch. Memory doesn't blow up (HLL is fixed 16 KB/day), but the reported `uniqueVisitors` becomes meaningless during the attack. The library cannot prevent this at the middleware layer. **Defense:** rate-limit tracked routes at the same layer that protects the rest of your app. Don't treat the number as authoritative during a suspected abuse event.
+An attacker who can send arbitrary `(IP, User-Agent)` pairs can insert arbitrarily many distinct "visitors" into the HLL sketch. Memory doesn't blow up (HLL is fixed 16 KB/day), but the reported count becomes meaningless during the attack. The library can't prevent this at the middleware layer — rate-limit at your CDN / reverse proxy.
 
-### 5. Snapshot file permissions and contents
+### 5. Privacy properties
 
-- The snapshot file is written with mode `0o600` (owner read/write only). It contains the current day's salt, which would make visitor hashes linkable back to their `(ip, ua)` tuples if disclosed alongside an independent request log.
-- Write is atomic via `.tmp` + `rename`. A crash mid-write leaves the previous snapshot intact.
-- The snapshot file contains **no personal data** — just the HLL registers, the salt, and per-day visitor counts. No IPs or User-Agents are stored.
+- **Cookieless.** The library never sets or reads cookies.
+- **No personal data persisted.** Hashes go into the HLL (which discards them) and are never written anywhere. No filesystem, no remote calls.
+- **Cross-day unlinkability.** The salt rotates at every UTC midnight. Yesterday's hash of `(ip, ua)` is unrelated to today's hash of the same tuple.
+- **No telemetry.** The library makes zero outbound network requests.
 
 ### 6. User-Agent length cap
 
-Incoming User-Agent headers are truncated to **512 bytes** before hashing and bot-filter checks. Node already caps total header size at ~16 KB, but this bounds per-request CPU regardless.
-
-### 7. Privacy properties
-
-- **Cookieless.** The library never sets or reads cookies.
-- **No personal data persisted.** Hashes go into the HLL (which discards them) and are never written to disk.
-- **Cross-day unlinkability.** The salt rotates at every UTC midnight. Yesterday's hash of `(ip, ua)` is unrelated to today's hash of the same tuple.
-- **Mid-day restart caveat.** If the process restarts within the same UTC day, the restored salt (from the snapshot file) is the same, so the same visitor returning after the restart doesn't get double-counted. This means the salt IS on disk for the current day. Rotate `STATS_TOKEN` and delete the snapshot file if you think the file was exposed.
+Incoming User-Agent headers are truncated to **512 bytes** before hashing and bot-filter checks. Bounds per-request CPU regardless of upstream limits.
 
 ## Where it works
 
-- ✅ **Self-hosted Next.js** — `next start` on a VPS, Docker, Fly.io, Railway, etc. Single long-running Node process.
-- ❌ **Vercel / Netlify / serverless by default** — ephemeral filesystem and per-request lambdas mean the in-memory HLL doesn't survive. You *could* make this work with a custom `persist` adapter pointing at Vercel KV or Upstash Redis, but at that point you're probably better off with a hosted analytics service.
+- ✅ **Self-hosted Next.js** (`next start` on a VPS, Docker, Fly.io, Railway, etc.) — single instance.
+- ✅ **Vercel** and other serverless platforms — works in Edge middleware. Counts persist for the lifetime of each isolate; expect them to reset more often than on a long-running self-hosted process.
+- ❌ **Multi-instance deployments** — each replica has its own in-memory counter and they don't sync. The library is single-process by design.
 
 ## Escape hatch (non-middleware integration)
 
-If you can't use `runtime: 'nodejs'` in middleware, call the tracker manually from a route handler or `instrumentation.ts`:
+If you need to call from a route handler or `instrumentation.ts`:
 
 ```ts
-import stats from 'statswhatshesaid'
+import { trackRequest } from 'statswhatshesaid'
 import type { NextRequest } from 'next/server'
 
-export function GET(req: NextRequest) {
-  stats.track(req)
+export async function GET(req: NextRequest) {
+  await trackRequest(req)
   return new Response('ok')
 }
 ```
@@ -328,7 +243,7 @@ The example app under `examples/basic` is the simplest way to smoke-test changes
 
 ## Releasing
 
-Versioning and publishing are managed with [Changesets](https://github.com/changesets/changesets) and automated via GitHub Actions.
+Versioning and publishing are managed with [Changesets](https://github.com/changesets/changesets) and automated via the GitHub Actions Release workflow using **npm trusted publishing** (OIDC). No long-lived npm tokens live in the repo.
 
 **Day-to-day flow:**
 
@@ -337,26 +252,8 @@ Versioning and publishing are managed with [Changesets](https://github.com/chang
    ```bash
    npx changeset
    ```
-   Pick the bump type (patch / minor / major) and write a short summary. Commit the generated `.changeset/*.md` file.
-3. Merge the PR into `main`. The `Release` workflow will open (or update) a **"chore(release): version packages"** PR that bumps `package.json` and updates `CHANGELOG.md`.
-4. When you merge the release PR, the workflow publishes the new version to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) attached.
-
-**One-time setup:**
-
-- The unscoped package name `statswhatshesaid` must be available on npm (`npm view statswhatshesaid` — a 404 means it's yours for the taking on first publish).
-- Add an automation token to the GitHub repo as the `NPM_TOKEN` secret (`Settings → Secrets and variables → Actions`). Use a **granular** token scoped to publish the `statswhatshesaid` package.
-- In `Settings → Actions → General`, under *Workflow permissions*, allow GitHub Actions to **create and approve pull requests** so the release bot can open the version PR.
-
-**Manual publishing (escape hatch):**
-
-If you ever need to cut a release locally:
-
-```bash
-npx changeset version   # bumps package.json + updates CHANGELOG
-git commit -am "chore(release): version packages"
-git push
-npm run release         # verify + changeset publish
-```
+3. Merge the PR into `main`. The Release workflow opens (or updates) a "chore(release): version packages" PR that bumps `package.json` and updates `CHANGELOG.md`.
+4. When you merge the release PR, the workflow publishes the new version to npm with provenance attached.
 
 ## License