Skip to content

Add opt-in pinning of bundled analytics scripts - #61

Open
jdevalk wants to merge 16 commits into
simpleanalytics:mainfrom
jdevalk:codex/script-pinning
Open

jdevalk wants to merge 16 commits into
simpleanalytics:mainfrom
jdevalk:codex/script-pinning

Conversation

@jdevalk

@jdevalk jdevalk commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

The plugin currently executes mutable third-party analytics scripts. This adds an opt-in Pin analytics scripts setting so browsers reject unexpected script changes instead of executing them.

  • Load the versioned v12 analytics script with a fixed SHA-384 integrity hash and anonymous CORS.
  • Bundle a reviewed, commit-pinned automated-events script with its MIT license and fixed integrity hash.
  • Require separate custom-domain hash approval by a user with unfiltered_html; bind approval to the site, domain, version, and hash. Domain changes clear approval, and missing or expired approval pauses tracking with a visible notice.
  • Keep pinning disabled by default. Never refresh hashes automatically or fall back to unpinned scripts. Document cache clearing, script-optimization exclusions, and release maintenance.

Dependency: depends on #58 for the existing custom-domain authorization controls. This branch includes that prerequisite commit; merge #58 first, then rebase this PR to leave only the pinning change. The branch also includes the latest main-branch fix from #60.

Validation: all 31 local Playwright/WordPress regression tests pass after rebasing onto current main, including rejection of altered main and bundled scripts, automated-event collection, custom-domain changes, invalid hashes, and permission checks. PHP/JavaScript syntax and whitespace checks pass. The official CDN script matches its published SHA-384 hash and serves CORS headers; custom-domain browser responses were mocked, so actual domain availability and CORS still require verification before enabling pinning there.

Update

Changes pushed on top of this PR, after merging the updated #58:

  • Every pinned script is bundled. resources/js/pinned/v12/ holds dist/v12/app.js, dist/v12/custom/app.js and dist/v12/auto-events.js from the scripts v12 release, unmodified, with fixed hashes. The automated-events copy came from an unreleased scripts commit. Pinned scripts now follow release versions, and their directory is built from VERSION, so v13 means three new files and three new hashes.
  • Custom domains need no hash approval. The custom-domain build sends data to the domain it is served from. The plugin fills in the saved domain, as the custom-domain server does, and saves the script in wp-content/uploads/simpleanalytics/. The hash field, its approval and the paused state are removed. If uploads isn't writable, visitors get the bundled default script and administrators see a warning. Uninstalling removes the written scripts.
  • Links added after load. The v12 automated-events script only tracks links present when the page loads. Tracking links added later arrives with v13.

The dependency on #58 still applies.

Validation: all 32 browser and WordPress regression tests pass locally on WordPress 7.1.4 with PHP 8.5, plus the regression scripts on multisite. They cover altered bundled and written scripts, data going to the custom domain, and event collection. In a browser against the live CDN, the bundled v12 scripts send pageviews and events.

Update 2

After review:

  • No integrity hashes. The site serves the bundled scripts itself, so a hash in the tag only guarded against changes by whoever can also change the PHP that prints it, while script optimizers and CDNs without CORS headers could stop tracking. The tags carry neither integrity nor crossorigin. The fixed hashes now live in tests/Regression/script-pinning.php, which checks every bundled release byte for byte.
  • Earlier releases stay. A plugin release that pins v13 adds resources/js/pinned/v13/ next to v12/, so pages cached before the update keep loading their scripts. Custom-domain scripts written for earlier releases stay until the domain changes.
  • Source maps. app.js.map and auto-events.js.map are bundled from the release, so developer tools no longer log 404s. The custom-domain copy drops its source map comment, because that map is valid only once its server fills in the hostname.

Validation: all 33 browser and WordPress regression tests pass locally on WordPress 7.1.4 with PHP 8.5, plus the regression scripts on multisite.

@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: QUIET
  • Plan: Advanced
  • Run ID: b25c3d48-07b2-476e-bf78-350db6359bbf
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

… optional

Custom domains saved before this release, set with WP-CLI, or saved before a
salt rotation now keep loading scripts. Changing the domain still requires
unfiltered_html, which is the check that stops site administrators on
multisite from choosing a script origin, so the approval hash is removed.
Pasted URLs are reduced to their hostname, and a rejected change or an
unusable saved value is explained beside the field, where the settings page
shows it.

Network administrators are excluded only when "Network administrator (Super
Admin)" is selected among the roles, so existing sites keep collecting their
visits. With no roles selected, every logged-in user stays excluded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in the custom-domain, network administrator and release schedule
changes. Custom-domain changes still clear the script approval, and the
integrity field's errors now use the inline messages every input shows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pinned main script is the v12 release, but the bundled events script was
taken from an unreleased scripts commit. Bundle src/auto-events.js from the
v12 tag instead, in a directory named after the release, and derive its path
from VERSION so v13 updates the version, both hashes and the directory
together.

v12 binds the links present when the page has loaded, so the browser test now
adds its links before load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pinned mode loaded the main script from the CDN or the custom domain and, for
a custom domain, waited until an administrator pasted an approved hash. It
now runs dist/v12/app.js, dist/v12/custom/app.js and dist/v12/auto-events.js
from the scripts v12 release archive, bundled unmodified with fixed hashes.

The custom-domain build sends data to the domain it is served from, so the
plugin fills in the saved domain, as the custom-domain server does, and saves
the result in uploads/simpleanalytics/. If uploads is not writable, visitors
get the bundled default script and administrators see a warning. This removes
the hash field, its approval, and the paused state. Uninstalling removes the
written scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@simpleanalytics-agent simpleanalytics-agent added the change: needs review Significant or emergency change affecting security, data protection, or stability label Nov 18, 2026
Co-authored-by: Simple Analytics Agent <github-agent@adriaan.simpleanalytics.com>
main's tree is identical to the final security hardening branch merged
above, because simpleanalytics#58 was squash-merged. Recording main as a parent with
the already-merged tree avoids replaying the same changes as conflicts.
Browsers with developer tools open request the source map each script
names, and the missing maps logged 404 errors. Bundle app.js.map and
auto-events.js.map unmodified from the v12 release, so the scripts and
their hashes stay unchanged.

The custom-domain map is valid JSON only after its server fills in the
hostname, so the script written for a custom domain drops its source
map comment instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread src/Scripts/AnalyticsScript.php Outdated
'data-hostname' => Setting::get(SettingName::HOSTNAME),
]);
]), ScriptPinning::enabled() ? [
'integrity' => ScriptPinning::analyticsScript()['integrity'],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why do you need integrity for embedded scripts? or is this only external scripts? we don't have those, right?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, pinned mode no longer loads anything from another host. The integrity hash comes from the first version of this PR, which loaded v12 from scripts.simpleanalyticscdn.com. Since the scripts are bundled, the site serves them itself: …/plugins/simple-analytics/resources/js/pinned/v12/app.js, or wp-content/uploads/simpleanalytics/v12-DOMAIN.js with a custom domain.

For the plugin files the hash adds almost nothing: whoever can change app.js can also change the PHP that prints its hash. It only helps when a site serves wp-content from a separate CDN that alters files. It does cost compatibility. Script optimizers that minify or combine the file make browsers block it, which is why the README asks admins to exclude it. And with crossorigin="anonymous", a CDN on another domain must send CORS headers or the script doesn't load.

The one place it helps is the custom-domain copy in the writable uploads folder. If something overwrites that file while visitors get pages from a page cache, the hash in the cached HTML still makes browsers refuse it. That needs a hole that can write a .js file there, and on most hosts such a hole can write PHP too.

My suggestion: drop integrity and crossorigin from the script tags, and keep the fixed hashes only in the regression test, to prove the bundled files are the unmodified release. That also makes upgrades simpler (see the ScriptPinning.php thread). I'll wait for your call before changing it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped in b13e39a. Pinned script tags no longer carry integrity or crossorigin. The fixed hashes moved to tests/Regression/script-pinning.php, which checks every bundled release byte for byte and fails when a release directory has no hashes. The setting text, the readme FAQ and the README no longer mention Subresource Integrity or excluding the files from optimizers, and the setting no longer links to the SRI docs page.

Comment thread src/Scripts/AutomatedEventsScript.php Outdated
'data-sa-global' => Setting::get(SettingName::EVENT_SA_GLOBAL),
]);
]), ScriptPinning::enabled() ? [
'integrity' => ScriptPinning::eventsScript()['integrity'],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as for the analytics script: auto-events.js is served from the plugin folder, so the hash only helps when wp-content goes through a separate CDN. If we drop it there, it goes here too.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped here too, in b13e39a.

// The scripts release tag. DIRECTORY holds dist/v12/app.js, dist/v12/custom/app.js,
// dist/v12/auto-events.js and the source maps of app.js and auto-events.js from that
// release's scripts-v12.tar.gz, unmodified.
const VERSION = 'v12';

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what happens if we upgrade to v13? are users on v12 still running v12 etc? how does it work when upgrading the plugin?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plugin bundles one scripts release at a time. Moving to v13 is a plugin release that adds resources/js/pinned/v13/, removes v12/, and changes VERSION and the three hashes.

  • Sites with pinning on keep running v12 until they install that plugin release, then load v13 from the next page view. They can't stay on v12 while updating the plugin. Sites without pinning keep loading latest.js from the CDN.
  • The version is part of each URL (…/pinned/v13/app.js, uploads/simpleanalytics/v13-DOMAIN.js), so browsers never run a cached v12 file. The v12 custom-domain file is deleted on the first page view after the update that isn't served from a page cache.
  • The gap: a page cache that still holds HTML pointing at the v12 files gets 404s, because v12/ is gone. Pinned sites stop tracking until that cache is cleared or expires. The README asks admins to clear page caches after updating, but many won't.
  • Sites that never update keep sending v12 events, so the backend has to keep accepting v12. That's the same commitment as the CDN's versioned sri/v12.js.

Two ways to close the gap: keep the previous version's files for one plugin release, or, if we drop the integrity hashes, serve fixed paths with ?ver=v13 so cached pages load the new script. I prefer the second, because it removes the gap entirely.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in b13e39a, as you suggested: every release stays in the plugin, with its version in the path. The README's update steps now say to add v13/ next to v12/, change VERSION, and add the new hashes to the regression test. With a custom domain, scripts written for earlier releases of that domain stay in uploads and are removed when the domain changes. Each release adds about 85 KB to the plugin, uncompressed, mostly the source map.

The site serves the bundled scripts itself, so an integrity hash only
guarded against changes by whoever can also change the PHP that prints
it, while script optimizers and CDNs without CORS headers could stop
tracking. The fixed hashes move to the regression test, which checks
every bundled release byte for byte.

Directories of earlier releases, and scripts written for earlier
releases of the current custom domain, now stay, so pages cached
before a plugin update keep loading their scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@simpleanalytics-agent simpleanalytics-agent changed the title Add opt-in integrity pinning for analytics scripts Add opt-in pinning of bundled analytics scripts Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

change: needs review Significant or emergency change affecting security, data protection, or stability

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants