feat(sdk): first-party collection, fetch-first transport, optional payload encryption

[tashviks]

Releases 0.1.14. Three related changes, all from the same finding: ad blockers match a request by its domain, so the /web/ingest rename bought time but cannot outrun a rule written against api.linkrunner.io.

What the measurement showed

On a live Playo page with a mainstream blocker installed:

Destination	Transport	Cleartext	Encrypted
api.linkrunner.io	sendBeacon	cancelled	cancelled
app.playo.co (CNAME to the same server)	sendBeacon	went through	went through
api.linkrunner.io	fetch	went through	went through

Two things fall out of that, and they're the first two changes below.

1. Fetch-first transport

sendBeacon is demoted to a fallback. The beacon was cancelled while a fetch carrying the same bytes to the same URL in the same second went through and got a real response — filter lists match the beacon/ping resource type separately, and ours is matched. Every event sent by beacon on those browsers was being dropped.

The usual argument for beacon-first is surviving page unload. It doesn't apply here: keepalive gives fetch the same guarantee, and this SDK has no unload handler — events fire on page view and explicit track() calls, during normal page life. fetch also reports a status, which is what makes a misconfigured first-party proxy visible instead of silent.

This is the fix that needs no infrastructure. It recovers blocked events on the current domain today.

2. First-party collection

New scriptSrc prop on LinkrunnerScript so the bundle can be served from the customer's own origin too — an endpoint on their domain fed by a script on ours only moves the failure one step earlier.

README documents both routes: a reverse proxy on their own origin (strongest — a same-origin path has nothing to uncloak) and a CNAME'd subdomain (one DNS record, but uBO on Firefox and Brave resolve the chain and would find us at the end of it). Includes Next.js / nginx / Cloudflare Worker snippets, the visitor-IP contract, and how to verify.

3. Payload encryption (off by default)

ECIES over P-256: ephemeral key pair per page load, ECDH to our public key, HKDF-SHA256, AES-256-GCM with a fresh IV per event. Only a public key ships in the bundle.

Both key constants are empty, and empty means cleartext exactly as before — there is deliberately no placeholder, since a wrong key would produce envelopes nothing can decrypt and lose events silently.

It is documented as what it is — payload confidentiality from TLS-terminating hops — and explicitly not as an anti-blocking measure. Cleartext and encrypted were indistinguishable in every cell above, because the request is cancelled before a body exists.

Costs, measured on a real 3.2 KB page view: +1.8 KB bundle, one ECDH per page load (not per event), payload grows ~39% (3,195 B → 4,430 B), and your own devtools show an opaque envelope.

Also

npm run dev:collector — a zero-dependency local harness serving the demo page, the SDK unbuilt from src/core.js, and a decrypting endpoint, so the whole loop runs without a backend. Includes an on-page "On the wire" panel showing the exact bytes sent.

Testing

npm test → 22 passing, verified over 8 consecutive runs.

test/payload-encryption.test.js loads the real shipped core.js, lets it seal a genuine page view, and decrypts it with the same primitives the Node collector uses — proving the two implementations interoperate rather than each agreeing with itself. Also fixed a flake: async waits were bounded by a fixed iteration count, which loses races against ECDH keygen under load; they're deadline-based now.

Merge order — please read

Merging this to main fires deploy-cdn.yml and browsers pick up the new bundle. The transport change is safe on its own. If you also intend to point a customer at their own subdomain, the Caddy route must be live first or those requests 405:

1. https://github.com/linkrunner-labs/ops/pull/468 — Caddy route for customer domains
2. https://github.com/linkrunner-labs/linkrunner-backend/pull/977 — envelope + visitor IP
3. This PR

🤖 Generated with Claude Code