Document bundled Boomerang provenance

Author: Tsvetan Stoychev

Makefile

@@ -92,6 +92,7 @@ composer-audit:
 conventions:
 	sh tools/verify-ascii-hyphens.sh
 	sh tools/verify-version-consistency.sh
+	sh tools/verify-boomerang-provenance.sh
 
 translations:
 	$(COMPOSE) run --rm --no-deps --user "$$(id -u):$$(id -g)" -e HOME=/tmp -w $(WPCLI_PLUGIN_WORKDIR) $(WPCLI_SERVICE) sh /tools/update-translations.sh .

README.md

@@ -61,7 +61,7 @@ The plugin header version, `BASICRUM_VERSION`, WordPress `Stable tag`, top chang
 
 Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Report suspected vulnerabilities privately according to [SECURITY.md](SECURITY.md), not through a public issue.
 
-Basicrum-owned code is available under the [MIT License](LICENSE). Bundled third-party software retains its upstream license; see the plugin's [third-party notices](plugins/basicrum/THIRD-PARTY-NOTICES.md).
+Basicrum-owned code is available under the [MIT License](LICENSE). Bundled third-party software retains its upstream license; see the plugin's [third-party notices](plugins/basicrum/THIRD-PARTY-NOTICES.txt).
 
 ## Contributors
 

plugins/basicrum/README.md

@@ -9,7 +9,7 @@ This directory contains the installable Basicrum WordPress plugin. Runtime PHP,
 - `src/Assets.php` controls frontend monitoring injection.
 - `src/Admin/Settings/` contains settings rendering and validation.
 - `readme.txt` is the canonical WordPress.org user documentation and changelog.
-- `THIRD-PARTY-NOTICES.md` records bundled software with separate licenses.
+- `THIRD-PARTY-NOTICES.txt` records bundled software with separate licenses.
 - `.distignore` defines development files excluded from releases.
 
 ## Development

plugins/basicrum/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,16 @@
+# Third-Party Notices
+
+Basicrum-owned code is licensed under the MIT License in `LICENSE.md`. The plugin also distributes the following third-party software under its own license.
+
+## Boomerang 1.815.60
+
+- Project: [Akamai Boomerang](https://github.com/akamai/boomerang)
+- Bundled file: `assets/js/boomr/boomerang-1.815.60.cutting-edge.min.js`
+- License: BSD License
+- License text: `assets/js/boomr/LICENSE.txt`
+- Source: commit `ead2783a33a2ce91205fe34f8fc992433faba9a2` in the `master` branch of [github.com/basicrum/boomerang](https://github.com/basicrum/boomerang), a fork of upstream [github.com/akamai/boomerang](https://github.com/akamai/boomerang)
+- Reproducible build: Node 12 (`.nvmrc`), `npm ci` against the committed lockfile (uglify-js 3.19.3), then `grunt clean build --build-flavor=cutting-edge --build-number=815` reproduces the bundled file byte for byte (SHA-256 `90e8a1c85949b10d43e441efc3f0545f95e4384e26ee3042344a8b2b4110589c`)
+- Version banner note: the banner inside the bundled file stamps the parent commit `564759ed70de7801bb64de5e2025fb6ac049ff5f` because the final source change was uncommitted when the shipped file was generated; the code content matches `ead2783a` exactly
+- Fork changes vs upstream: maintained commits that remove Long Tasks monitoring, remove the deprecated FID metric and rework Time to First Interaction, drop unused utility functions, and add the Basicrum configuration bootstrap
+
+The Boomerang copyright notice and license remain applicable to the bundled Boomerang file. Basicrum does not relicense that file under the Basicrum MIT License.

plugins/basicrum/THIRD-PARTY-NOTICES.txt

@@ -86,7 +86,9 @@ Yes. Enable HTTP Strictness under Basicrum's Developer Settings to preserve HTTP
 
 == Third-party software ==
 
-Basicrum-owned code is licensed under the MIT License. The bundled Boomerang 1.815.60 library retains its upstream BSD license and copyright notices. See `THIRD-PARTY-NOTICES.md` and `assets/js/boomr/LICENSE.txt` in the plugin package.
+Basicrum-owned code is licensed under the MIT License. The bundled Boomerang 1.815.60 library retains its upstream BSD license and copyright notices. See `THIRD-PARTY-NOTICES.txt` and `assets/js/boomr/LICENSE.txt` in the plugin package.
+
+The bundled file `assets/js/boomr/boomerang-1.815.60.cutting-edge.min.js` is a minified build of the open source Boomerang project by Akamai ([github.com/akamai/boomerang](https://github.com/akamai/boomerang)). It is byte-for-byte reproducible from public source: commit `ead2783a33a2ce91205fe34f8fc992433faba9a2` on the `master` branch of [github.com/basicrum/boomerang](https://github.com/basicrum/boomerang), built with Node 12 and the repository's Grunt tooling (`grunt clean build --build-flavor=cutting-edge --build-number=815`). The version banner inside the file stamps the parent commit `564759ed70de7801bb64de5e2025fb6ac049ff5f` because the final source change was uncommitted when the shipped file was generated; the code content matches `ead2783a` exactly. The Basicrum fork differs from upstream Boomerang by a small set of maintained commits that remove Long Tasks monitoring, remove the deprecated FID metric and rework Time to First Interaction, drop unused utility functions, and add the Basicrum configuration bootstrap.
 
 == Changelog ==
 

plugins/basicrum/readme.txt

@@ -0,0 +1,45 @@
+#!/bin/sh
+# Verify that the source commit stamped inside the bundled Boomerang build
+# matches the commit documented for reviewers in THIRD-PARTY-NOTICES.txt and
+# readme.txt, and that the version in the bundle header matches the bundled
+# file name. Keeps the guideline-4 source-access statement from drifting when
+# the bundle is upgraded.
+set -eu
+
+PLUGIN_DIR="plugins/basicrum"
+BUNDLE=$(find "$PLUGIN_DIR/assets/js/boomr" -name 'boomerang-*.min.js' | head -n 1)
+
+if [ -z "$BUNDLE" ]; then
+	printf '%s\n' 'No bundled Boomerang build found.' >&2
+	exit 1
+fi
+
+HEADER_LINE=$(grep -m 1 'Boomerang Version:' "$BUNDLE" || true)
+HEADER_VERSION=$(printf '%s\n' "$HEADER_LINE" | sed -n 's/.*Boomerang Version: \([0-9.]*\) .*/\1/p')
+HEADER_COMMIT=$(printf '%s\n' "$HEADER_LINE" | grep -oE '[0-9a-f]{40}' | head -n 1)
+
+if [ -z "$HEADER_VERSION" ] || [ -z "$HEADER_COMMIT" ]; then
+	printf '%s\n' 'Bundled Boomerang header does not carry a version and source commit.' >&2
+	exit 1
+fi
+
+FILE_VERSION=$(basename "$BUNDLE" | sed -n 's/^boomerang-\([0-9.]*\)\..*/\1/p')
+
+if [ "$HEADER_VERSION" != "$FILE_VERSION" ]; then
+	printf 'Bundled Boomerang version mismatch: header %s, file name %s.\n' "$HEADER_VERSION" "$FILE_VERSION" >&2
+	exit 1
+fi
+
+for DOC in "$PLUGIN_DIR/THIRD-PARTY-NOTICES.txt" "$PLUGIN_DIR/readme.txt"; do
+	if ! grep -q "$HEADER_COMMIT" "$DOC"; then
+		printf 'Documented Boomerang source commit is stale: %s does not mention %s.\n' "$DOC" "$HEADER_COMMIT" >&2
+		exit 1
+	fi
+done
+
+if [ ! -f "$PLUGIN_DIR/assets/js/boomr/LICENSE.txt" ]; then
+	printf '%s\n' 'Boomerang LICENSE.txt is missing next to the bundled build.' >&2
+	exit 1
+fi
+
+printf 'Boomerang provenance check passed: %s %s.\n' "$HEADER_VERSION" "$HEADER_COMMIT"

tools/verify-boomerang-provenance.sh

@@ -37,7 +37,7 @@ require_entry 'basicrum/basicrum.php'
 require_entry 'basicrum/uninstall.php'
 require_entry 'basicrum/readme.txt'
 require_entry 'basicrum/LICENSE.md'
-require_entry 'basicrum/THIRD-PARTY-NOTICES.md'
+require_entry 'basicrum/THIRD-PARTY-NOTICES.txt'
 require_entry 'basicrum/src/Plugin.php'
 require_entry 'basicrum/src/Assets.php'
 require_entry 'basicrum/src/ConsentIntegration.php'
@@ -107,7 +107,7 @@ if ! unzip -p "$ARCHIVE_PATH" basicrum/assets/js/boomr/LICENSE.txt | grep -Fq 'C
 	exit 1
 fi
 
-if ! unzip -p "$ARCHIVE_PATH" basicrum/THIRD-PARTY-NOTICES.md | grep -Fq 'Boomerang 1.815.60'; then
+if ! unzip -p "$ARCHIVE_PATH" basicrum/THIRD-PARTY-NOTICES.txt | grep -Fq 'Boomerang 1.815.60'; then
 	printf '%s\n' 'Bundled software notice is incomplete.' >&2
 	exit 1
 fi