build: assert DEBUG is off in every emitted bundle (closes #170)

PR #169 made DEBUG a build-time flag defaulting off, but nothing guarded
the wiring. The tests load src/shared/constants.js outside a bundle and
take the jest fallback branch, so deleting the __BUILD_DEBUG__ define
from build.js left all tests passing and make check green while silently
restoring the drainable-wallet vulnerability in every shipped artifact.
The property only exists in the emitted output, so it is now asserted
against the emitted output.

script/verify-build reads two independent facts per bundle. Which
bundles must be inspected comes from esbuild's metafile: build.js writes
dist/constants-bundles.txt naming every emitted JS output whose input
set includes constants.js, so the set is derived from the real
dependency graph rather than a hardcoded count or filenames. What each
bundle's DEBUG state is comes from BUILD_DEBUG_MARKER, a new constant
derived from DEBUG itself that the bundler folds to exactly one of two
string literals. Deriving the bundle set from the marker would be the
silent-pass hole: a bundle with no marker would be indistinguishable
from content/index.js, which legitimately contains none.

The marker is a plain string rather than a match on minified `DEBUG:!1`,
because minifier output is not a contract across esbuild versions. When
DEBUG is not known at build time the fold cannot happen and both
literals survive, which is exactly the shape of the regression this
guards against. Every way of failing to determine a bundle's state is a
hard failure: missing manifest, empty manifest, a listed file that does
not exist, both markers, neither marker, the wrong marker, or a bundle
carrying a marker while absent from the manifest. There is no path on
which the script exits 0 without positively identifying the expected
marker in at least one bundle.

It runs on the build path only. make build and make build-debug both
invoke it, the latter asserting the inverse, and Dockerfile:17 runs a
bare make build, so CI fails on a release build with a live debug
branch. It is deliberately not in script/check: that would make check
depend on dist/ existing and pull a full build into its time budget, and
the obvious workaround -- skip when dist/ is absent -- is precisely the
silently-green behaviour this exists to prevent.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap setup install test test-e2e lint fmt fmt-check check docker hooks build build-debug clean dev
+.PHONY: bootstrap setup install test test-e2e lint fmt fmt-check check docker hooks build build-debug verify-build clean dev
 
 # Standard targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -41,6 +41,7 @@ hooks:
 build:
 	@echo "Building extension..."
 	@yarn run build 2>&1
+	@script/verify-build
 
 # Development-only build: enables the red DEBUG / INSECURE banner and makes
 # the hardcoded test recovery phrase the output of wallet creation. Never
@@ -48,6 +49,12 @@ build:
 build-debug:
 	@echo "Building extension (DEBUG)..."
 	@AUTISTMASK_DEBUG=1 yarn run build 2>&1
+	@AUTISTMASK_DEBUG=1 script/verify-build
+
+# Assert the compiled DEBUG state of the bundles already in dist/. Runs at
+# the end of build and build-debug; separate target for re-running it alone.
+verify-build:
+	@script/verify-build
 
 clean:
 	@rm -rf dist/

README.md

@@ -59,6 +59,13 @@ behavior. The build prints which mode it used. See the
 distribute a debug build** — every wallet it creates gets the same publicly
 known test recovery phrase.
 
+Both builds end by running `script/verify-build`, which reads the compiled
+`DEBUG` state back out of the emitted bundles and fails the build if it is not
+the one that was asked for. The test suite cannot check this: it loads
+`src/shared/constants.js` outside a bundle, so it only ever sees the fallback
+value. The assertion is on the artifacts because that is where the property
+lives.
+
 ## Entrypoints
 
 This repository adheres to the
@@ -79,6 +86,12 @@ provide:
 - `script/fmt` — format all files (writes)
 - `script/fmt-check` — check formatting (read-only)
 - `script/check` — run test, lint, and fmt-check
+- `script/verify-build` — assert the compiled `DEBUG` state of the bundles in
+  `dist/`: every bundle containing `src/shared/constants.js` must have `DEBUG`
+  off, or on when `AUTISTMASK_DEBUG=1`. Run automatically at the end of
+  `make build` and `make build-debug`; fails loudly rather than passing if it
+  cannot determine a bundle's state. Not part of `make check`, which does not
+  depend on build artifacts existing.
 - `script/docker` — build the Docker image tagged via `script/projectname`
 - `script/cibuild` — CI entrypoint: plain `docker build .`
 - `script/precommit` — run by the git pre-commit hook; runs `script/check`

TODO.md

@@ -32,6 +32,9 @@ review.
   longer crosses the extension messaging boundary; the background broadcasts and
   resolves approvals only, and verifies the signed artifact against the approval
   it holds (#157).
+- 2026-08-09: Post-build assertion that every emitted bundle containing
+  `constants.js` has `DEBUG` compiled off, via `script/verify-build` on the
+  `make build` path (#170).
 - 2026-08-09: Containerized Chrome end-to-end harness (`make test-e2e` /
   `script/test-e2e`) driving the real popup with all network intercepted, plus
   the two used-but-not-imported crashes it caught: AddToken unreachable (#150)

build.js

@@ -3,14 +3,43 @@ const path = require("path");
 const { execSync } = require("child_process");
 const esbuild = require("esbuild");
 
-const DIST_CHROME = path.join(__dirname, "dist", "chrome");
+const DIST = path.join(__dirname, "dist");
-const DIST_FIREFOX = path.join(__dirname, "dist", "firefox");
+const DIST_CHROME = path.join(DIST, "chrome");
+const DIST_FIREFOX = path.join(DIST, "firefox");
 const SRC = path.join(__dirname, "src");
 
+// The module whose compiled DEBUG state script/verify-build asserts, and the
+// manifest naming every emitted bundle that ends up containing it. The
+// manifest is derived from esbuild's own dependency graph rather than from a
+// hardcoded list, so it tracks the bundle layout instead of rotting with it.
+const AUDITED_MODULE = "src/shared/constants.js";
+const BUNDLE_MANIFEST = path.join(DIST, "constants-bundles.txt");
+
 function ensureDir(dir) {
     fs.mkdirSync(dir, { recursive: true });
 }
 
+// Repo-relative, forward-slashed, so the manifest reads the same on every
+// platform and can be consumed by a POSIX shell script without further work.
+function repoRelative(p) {
+    return path.relative(__dirname, p).split(path.sep).join("/");
+}
+
+// Collect the outputs of one esbuild run that bundle AUDITED_MODULE. esbuild
+// reports every input that contributed to an output in the metafile, which is
+// the authoritative answer to "is constants.js in this bundle" — unlike
+// searching the minified text, it does not depend on what survived minification.
+function outputsContainingAuditedModule(metafile) {
+    return Object.entries(metafile.outputs)
+        .filter(([outFile, info]) => {
+            if (!outFile.endsWith(".js")) return false;
+            return Object.keys(info.inputs).some(
+                (input) => repoRelative(input) === AUDITED_MODULE,
+            );
+        })
+        .map(([outFile]) => repoRelative(outFile));
+}
+
 // DEBUG is a build-time flag, off unless explicitly requested. It is the only
 // thing that makes the hardcoded test mnemonic reachable, so the opt-in must be
 // exact: anything other than the literal "1" (unset, empty, "true", a typo)
@@ -72,68 +101,70 @@ async function build() {
         __BUILD_DATE__: JSON.stringify(buildInfo.buildDate),
     };
 
+    // Emitted bundles that contain constants.js, accumulated across every
+    // esbuild run below and written out for script/verify-build.
+    const auditedBundles = [];
+
     // compile tailwind CSS
     console.log("Compiling Tailwind CSS...");
     const tailwindInput = path.join(SRC, "popup", "styles", "main.css");
-    const tailwindOutput = path.join(__dirname, "dist", "styles.css");
+    const tailwindOutput = path.join(DIST, "styles.css");
-    ensureDir(path.join(__dirname, "dist"));
+    ensureDir(DIST);
+
+    // Drop any manifest from a previous build before emitting anything, so a
+    // build that never gets around to writing one cannot be verified against
+    // a stale list.
+    fs.rmSync(BUNDLE_MANIFEST, { force: true });
     execSync(
         `npx @tailwindcss/cli -i ${tailwindInput} -o ${tailwindOutput} --minify`,
         { stdio: "inherit" },
     );
 
+    // Every bundle goes through here, so metafile collection cannot be
+    // forgotten when a new entry point is added.
+    async function bundle(entryPoint, outfile) {
+        const result = await esbuild.build({
+            entryPoints: [entryPoint],
+            bundle: true,
+            format: "iife",
+            outfile,
+            platform: "browser",
+            target: ["chrome110", "firefox110"],
+            minify: true,
+            metafile: true,
+            define,
+        });
+        auditedBundles.push(...outputsContainingAuditedModule(result.metafile));
+    }
+
     for (const distDir of [DIST_CHROME, DIST_FIREFOX]) {
         ensureDir(path.join(distDir, "src", "popup"));
         ensureDir(path.join(distDir, "src", "background"));
         ensureDir(path.join(distDir, "src", "content"));
 
         // bundle popup JS with esbuild (inlines ethers, libsodium, etc.)
-        await esbuild.build({
+        await bundle(
-            entryPoints: [path.join(SRC, "popup", "index.js")],
+            path.join(SRC, "popup", "index.js"),
-            bundle: true,
+            path.join(distDir, "src", "popup", "index.js"),
-            format: "iife",
+        );
-            outfile: path.join(distDir, "src", "popup", "index.js"),
-            platform: "browser",
-            target: ["chrome110", "firefox110"],
-            minify: true,
-            define,
-        });
 
         // bundle background script
-        await esbuild.build({
+        await bundle(
-            entryPoints: [path.join(SRC, "background", "index.js")],
+            path.join(SRC, "background", "index.js"),
-            bundle: true,
+            path.join(distDir, "src", "background", "index.js"),
-            format: "iife",
+        );
-            outfile: path.join(distDir, "src", "background", "index.js"),
-            platform: "browser",
-            target: ["chrome110", "firefox110"],
-            minify: true,
-            define,
-        });
 
         // bundle content script
-        await esbuild.build({
+        await bundle(
-            entryPoints: [path.join(SRC, "content", "index.js")],
+            path.join(SRC, "content", "index.js"),
-            bundle: true,
+            path.join(distDir, "src", "content", "index.js"),
-            format: "iife",
+        );
-            outfile: path.join(distDir, "src", "content", "index.js"),
-            platform: "browser",
-            target: ["chrome110", "firefox110"],
-            minify: true,
-            define,
-        });
 
         // bundle inpage script (injected into page context, separate file)
-        await esbuild.build({
+        await bundle(
-            entryPoints: [path.join(SRC, "content", "inpage.js")],
+            path.join(SRC, "content", "inpage.js"),
-            bundle: true,
+            path.join(distDir, "src", "content", "inpage.js"),
-            format: "iife",
+        );
-            outfile: path.join(distDir, "src", "content", "inpage.js"),
-            platform: "browser",
-            target: ["chrome110", "firefox110"],
-            minify: true,
-            define,
-        });
 
         // copy popup HTML
         fs.copyFileSync(
@@ -158,6 +189,16 @@ async function build() {
         path.join(DIST_FIREFOX, "manifest.json"),
     );
 
+    // Written last so a build that died partway through leaves no manifest
+    // at all, which script/verify-build treats as a hard failure rather than
+    // as "nothing to check".
+    const manifest = [...new Set(auditedBundles)].sort();
+    fs.writeFileSync(BUNDLE_MANIFEST, manifest.map((p) => `${p}\n`).join(""));
+    console.log(
+        `Bundles containing ${AUDITED_MODULE}: ${manifest.length} ` +
+            `(listed in ${repoRelative(BUNDLE_MANIFEST)})`,
+    );
+
     console.log("Build complete: dist/chrome/ and dist/firefox/");
 }
 

script/verify-build

@@ -0,0 +1,136 @@
+#!/bin/sh
+# script/verify-build: assert the compiled DEBUG state of the emitted
+# bundles. Our own extension to scripts-to-rule-them-all, run at the end of
+# make build / make build-debug.
+#
+# Why this exists: DEBUG makes the publicly committed test recovery phrase the
+# output of wallet creation, so a release artifact built with it live hands
+# every new wallet to anyone who reads the repo. The test suite cannot see
+# this, because it loads src/shared/constants.js outside a bundle and takes
+# the fallback branch; the property only exists in the emitted output, so it
+# has to be asserted against the emitted output.
+#
+# What it reads: dist/constants-bundles.txt, written by build.js from
+# esbuild's metafile, naming every emitted bundle that contains
+# src/shared/constants.js. Each of those must carry exactly one of the two
+# BUILD_DEBUG_MARKER literals that constants.js folds down to.
+#
+# It fails rather than passes whenever it cannot determine a bundle's state.
+# Minified output is not a stable contract, so "matched neither form" is not
+# evidence of anything and must never read as green.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+MANIFEST="dist/constants-bundles.txt"
+MARKER_ON="autistmask-build-debug=on"
+MARKER_OFF="autistmask-build-debug=off"
+
+# Set by read_marker.
+MARKER=""
+
+fail() {
+    echo "verify-build: FAIL: $*" >&2
+    exit 1
+}
+
+has_marker() {
+    grep -q -F "$1" "$2" 2>/dev/null
+}
+
+# Read one bundle's DEBUG state into MARKER. Exactly one marker must be
+# present. Both means the ternary in constants.js was never folded, which is
+# what happens when the __BUILD_DEBUG__ define goes missing from build.js:
+# DEBUG stops being known at build time and the debug branch is live again.
+# Neither means we are reading output we do not understand. Both are hard
+# failures; neither is ever treated as absence of a problem.
+read_marker() {
+    _file="$1"
+    _on=no
+    _off=no
+    if has_marker "$MARKER_ON" "$_file"; then _on=yes; fi
+    if has_marker "$MARKER_OFF" "$_file"; then _off=yes; fi
+
+    if [ "$_on" = yes ] && [ "$_off" = yes ]; then
+        fail "$_file carries both debug markers, so the build-time DEBUG value
+    was never resolved and the debug branch is still live. Check that build.js
+    still defines __BUILD_DEBUG__."
+    fi
+    if [ "$_on" = no ] && [ "$_off" = no ]; then
+        fail "$_file carries no debug marker, so its DEBUG state cannot be
+    determined. Either BUILD_DEBUG_MARKER is gone from src/shared/constants.js
+    or the emitted output changed shape. Refusing to report success."
+    fi
+
+    if [ "$_on" = yes ]; then
+        MARKER="$MARKER_ON"
+    else
+        MARKER="$MARKER_OFF"
+    fi
+}
+
+# The manifest says which bundles must carry a marker. This says no other
+# emitted bundle may carry one, which catches a manifest that has gone stale
+# or short rather than trusting whatever it happens to list.
+check_unlisted_bundles() {
+    _listing="$(find dist -type f -name '*.js' | sort)"
+    while read -r _file; do
+        [ -n "$_file" ] || continue
+        if grep -q -x -F "$_file" "$MANIFEST"; then
+            continue
+        fi
+        if has_marker "$MARKER_ON" "$_file" ||
+            has_marker "$MARKER_OFF" "$_file"; then
+            fail "$_file carries a debug marker but is absent from $MANIFEST,
+    so the manifest no longer describes the emitted bundles."
+        fi
+    done <<EOF
+$_listing
+EOF
+}
+
+# The requested mode, read from our own environment using build.js's exact
+# rule: only the literal 1 opts in. Deliberately not taken from anything
+# build.js records about itself, so build.js cannot vouch for build.js.
+expected_marker() {
+    if [ "${AUTISTMASK_DEBUG-}" = "1" ]; then
+        echo "$MARKER_ON"
+    else
+        echo "$MARKER_OFF"
+    fi
+}
+
+main() {
+    cd "$ROOT"
+
+    expected="$(expected_marker)"
+    echo "Verifying emitted bundles (expecting $expected)..."
+
+    [ -f "$MANIFEST" ] ||
+        fail "$MANIFEST is missing. build.js writes it at the end of a
+    successful build; run make build first."
+    [ -s "$MANIFEST" ] ||
+        fail "$MANIFEST is empty, so no emitted bundle was found to contain
+    src/shared/constants.js. That is never correct, so it is a failure and not
+    a pass."
+
+    count=0
+    while read -r file; do
+        [ -n "$file" ] || continue
+        [ -f "$file" ] ||
+            fail "$MANIFEST lists $file, which does not exist."
+        read_marker "$file"
+        [ "$MARKER" = "$expected" ] ||
+            fail "$file is $MARKER but this build expects $expected."
+        echo "  ok: $file ($MARKER)"
+        count=$((count + 1))
+    done <"$MANIFEST"
+
+    [ "$count" -gt 0 ] || fail "no bundles were inspected."
+
+    check_unlisted_bundles
+
+    echo "verify-build: $count bundle(s) verified $expected"
+}
+
+main "$@"

src/shared/constants.js

@@ -7,6 +7,21 @@
 /* global __BUILD_DEBUG__ */
 const DEBUG = typeof __BUILD_DEBUG__ !== "undefined" ? __BUILD_DEBUG__ : false;
 
+// Machine-readable record of the compiled DEBUG state, read out of the emitted
+// bundles by script/verify-build. It is derived from DEBUG itself so the two
+// cannot disagree, and it is a plain string literal rather than a minifier
+// artifact like `DEBUG:!1`, so the check does not depend on esbuild's output
+// staying byte-stable across versions.
+//
+// The ambiguity is the point. When DEBUG is known at build time the bundler
+// folds this to exactly one of the two literals. When it is not — which is
+// exactly what happens if the __BUILD_DEBUG__ define goes missing from
+// build.js — the ternary survives, both literals appear in the bundle, and
+// verify-build fails rather than guessing.
+const BUILD_DEBUG_MARKER = DEBUG
+    ? "autistmask-build-debug=on"
+    : "autistmask-build-debug=off";
+
 const DEBUG_MNEMONIC =
     "cube evolve unfold result inch risk jealous skill hotel bulb night wreck";
 
@@ -44,6 +59,7 @@ function isBurnAddress(address) {
 
 module.exports = {
     DEBUG,
+    BUILD_DEBUG_MARKER,
     DEBUG_MNEMONIC,
     ETHEREUM_MAINNET_CHAIN_ID,
     ETHEREUM_SEPOLIA_CHAIN_ID,

tests/constants.test.js

@@ -1,4 +1,6 @@
 const {
+    DEBUG,
+    BUILD_DEBUG_MARKER,
     ETHEREUM_MAINNET_CHAIN_ID,
     DEFAULT_RPC_URL,
     BIP44_ETH_PATH,
@@ -19,6 +21,24 @@ describe("constants", () => {
         expect(BIP44_ETH_PATH).toBe("m/44'/60'/0'/0");
     });
 
+    // This does not replace script/verify-build, which is the only thing that
+    // can see the compiled DEBUG state of a real bundle. It pins the source
+    // invariant that the marker tracks DEBUG, so the two cannot be edited
+    // apart and leave verify-build asserting something that is no longer the
+    // flag the code branches on.
+    test("build debug marker is derived from DEBUG", () => {
+        expect(BUILD_DEBUG_MARKER).toBe(
+            DEBUG ? "autistmask-build-debug=on" : "autistmask-build-debug=off",
+        );
+    });
+
+    // Outside a bundle there is no __BUILD_DEBUG__ define, and the fallback
+    // must be the safe one.
+    test("DEBUG is off when loaded outside a bundle", () => {
+        expect(DEBUG).toBe(false);
+        expect(BUILD_DEBUG_MARKER).toBe("autistmask-build-debug=off");
+    });
+
     test("exports ERC-20 ABI with expected functions", () => {
         expect(Array.isArray(ERC20_ABI)).toBe(true);
         expect(ERC20_ABI.length).toBeGreaterThan(0);