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 lint fmt fmt-check check docker hooks build clean dev
+.PHONY: bootstrap setup install test 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
@@ -37,6 +37,20 @@ 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
+# distribute the artifacts this produces.
+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

@@ -42,6 +42,30 @@ Load the extension:
 - **Firefox**: Navigate to `about:debugging#/runtime/this-firefox`, click "Load
   Temporary Add-on", and select `dist/firefox/manifest.json`.
 
+### Debug Builds
+
+`make build` always produces a release build: the build-time `DEBUG` constant is
+`false`, so wallet creation uses real entropy and the red banner is off. To
+produce a debug build instead, set `AUTISTMASK_DEBUG=1` in the environment:
+
+```bash
+make build-debug          # or: AUTISTMASK_DEBUG=1 make build
+```
+
+Only the exact value `1` enables it; any other value (including unset, empty, or
+`true`) yields a release build, so a typo cannot accidentally ship the debug
+behavior. The build prints which mode it used. See the
+[DEBUG Mode Policy](#debug-mode-policy) for what the flag changes. **Never
+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
@@ -60,6 +84,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`
@@ -668,6 +698,19 @@ flows, or alter program behavior beyond the banner and the hardcoded mnemonic.
 Adding new DEBUG-conditional branches requires explicit approval from the
 project owner.
 
+`DEBUG` is a build-time constant, not a runtime setting. `build.js` injects it
+into the bundle as the `__BUILD_DEBUG__` define — `false` unless the build was
+run with `AUTISTMASK_DEBUG=1` (see [Debug Builds](#debug-builds)) — and
+`src/shared/constants.js` reads it. It cannot be changed after the bundle is
+produced.
+
+The debug-mode toggle in settings is a separate, runtime-only flag. It raises
+the log level and turns the banner on, and that is all it may ever do: it feeds
+`isDebug()` in `src/shared/log.js`, which is deliberately not what
+`generateMnemonic()` consults. Mnemonic generation reads the build-time `DEBUG`
+constant directly, so no runtime toggle in a release build can reach the
+hardcoded test phrase.
+
 ### Key Decisions
 
 - **No framework**: The popup UI is vanilla JS and HTML. The extension is small

TODO.md

@@ -10,24 +10,35 @@
 
 # Status
 
-pre-1.0. Tagged v0.1.0 on 2026-02-27. Active development on branch
+pre-1.0, working towards the 1.0.0 milestone. Tagged v0.1.0 on 2026-02-27. No
-feat/issue-144-settings-about (another agent working as of 2026-07-06). Full
+other branch is in flight: the settings About well landed as #145 on 2026-07-26
-policy file set present; make check on main not verified.
+and scripts-to-rule-them-all landed as #148, so the `scripts/` directory
+question is resolved. Full policy file set present. `make check` verified
+passing on `main` at `23aeae4` on 2026-08-09. The 1.0.0 backlog is filed as
+#149-#168.
 
 # Next Step
 
-Land feat/issue-144-settings-about: finish the settings About well (build info,
+Land #149: make `DEBUG` a build-time constant that defaults to off, injected as
-app name and repo link, release date, version click easter egg, git info derived
+the `__BUILD_DEBUG__` esbuild define from `AUTISTMASK_DEBUG=1`, so a plain
-inside Docker), resolve the untracked scripts/ directory (commit or gitignore),
+`make build` stops handing every newly created wallet the publicly committed
-get review, merge to main.
+test recovery phrase. Branch `fix/issue-149-debug-build-flag`; PR open, awaiting
+review.
 
 # Completed Steps
 
+- 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). Branched from `fix/issue-149-debug-build-flag`;
+  merge after #169.
+- 2026-08-09: Reviewed the repo end to end and filed the 1.0.0 backlog
+  (#149-#168).
+- 2026-07-26: About well in settings with build info, repo link and the version
+  click easter egg (#145); proper view navigation stack (#146).
 - 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
-  shims, README Entrypoints section
+  shims, README Entrypoints section (#148)
-- 2026-03-01: About well in settings with build info and easter egg (in flight
+- 2026-03-01: USD display suppressed on testnets (#142); estimated USD for ETH
-  on feature branch); USD display suppressed on testnets (#142); estimated USD
+  in approve-tx view (#141).
-  for ETH in approve-tx view (#141).
 - Sepolia testnet support (#137); etherscan links go to token-specific URLs
   (#136).
 - Transaction detail improvements: Type field and on-chain details (#130),
@@ -45,12 +56,32 @@ get review, merge to main.
 
 # Future Steps
 
-- Verify main passes make check after the feature branch merges (not verified
+- Fix the two `ReferenceError` crashes that make whole screens unreachable:
-  2026-07-06 because an agent was active in the tree); fix anything red. main
+  AddToken (#150) and TransactionDetail for every ERC-20 transfer (#151).
-  must always be green.
+- Add ESLint to `script/lint` (#152). `make check` is `prettier --check` only
-- Prune stale branches: dozens of merged local and remote feature branches
+  and cannot catch undefined identifiers, which is how #150 and #151 shipped.
-  remain (fix/_, feature/_, tx-\*); delete merged ones locally and on origin.
+- Make the Firefox target functional: Chrome callback APIs are used against the
-- Continue the issue backlog toward a feature-complete wallet, then cut further
+  promise-only `browser` namespace (#153).
-  tags as milestones land.
+- Send and transaction-flow correctness: gas fee excluded from the
+  insufficient-balance check (#154), WaitTx 60s timeout overwriting a rendered
+  success screen (#155), last-wallet deletion leaving inconsistent state (#156).
+- Security: plaintext password crossing the extension messaging boundary during
+  dApp approvals (#157); MV3 service worker termination killing the background
+  refresh and the 24h phishing list update (#158).
+- Test the crypto core — `wallet.js` derivation and `vault.js` encryption (#159)
+  — and the address-poisoning defense in `transactions.js` (#160).
+- Wallet features for 1.0: show a wallet's recovery phrase behind the password
+  (#161), delete an address from an HD wallet (#162).
+- Docs: `docs/README.md` contradicts the code on external services and names
+  competitors (#163); README Screen Map omits three shipped screens (#164).
+- Owner decisions: Sepolia support versus "Non-Goals for 1.0", and `isMetaMask`
+  naming a competitor in shipped code (#165).
+- Repo policy compliance sweep: test rerun pattern, `yarn`/`npx`, frozen
+  lockfile, undocumented Makefile targets (#166).
+- Prune the 24 stale remote feature branches (#167).
+- Remove dead exports and de-duplicate copy-pasted view helpers (#168).
 - Pre-1.0 security review of the extension (key handling, DEBUG mode policy, RPC
-  input validation) before any 1.0rc tag.
+  input validation) before any 1.0rc tag; #149 and #157 are parts of it, but the
+  review is broader than either.
+- Cut 1.0.0 once the milestone is empty, then continue tagging as milestones
+  land.

build.js

@@ -3,14 +3,51 @@ 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)
+// produces a release build. Failing towards the safe mode is deliberate.
+function isDebugBuild() {
+    return process.env.AUTISTMASK_DEBUG === "1";
+}
+
 function getBuildInfo() {
     const pkg = JSON.parse(
         fs.readFileSync(path.join(__dirname, "package.json"), "utf8"),
@@ -47,7 +84,15 @@ async function build() {
     const buildInfo = getBuildInfo();
     console.log("Build info:", buildInfo);
 
+    const debugBuild = isDebugBuild();
+    console.log(
+        debugBuild
+            ? "Build mode: DEBUG (INSECURE - hardcoded test mnemonic, do not ship)"
+            : "Build mode: release (DEBUG off)",
+    );
+
     const define = {
+        __BUILD_DEBUG__: JSON.stringify(debugBuild),
         __BUILD_VERSION__: JSON.stringify(buildInfo.version),
         __BUILD_LICENSE__: JSON.stringify(buildInfo.license),
         __BUILD_AUTHOR__: JSON.stringify(buildInfo.author),
@@ -56,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(
@@ -142,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

@@ -1,4 +1,27 @@
-const DEBUG = true;
+// DEBUG is a build-time constant injected by esbuild's define in build.js
+// (see src/shared/buildInfo.js for the same pattern). It is false unless the
+// bundle was produced with AUTISTMASK_DEBUG=1, and it is false whenever the
+// module is loaded outside a bundle (tests, plain require). It must never be
+// derived from anything the user can change at runtime: it is what gates the
+// hardcoded test mnemonic below.
+/* 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";
 
@@ -36,6 +59,7 @@ function isBurnAddress(address) {
 
 module.exports = {
     DEBUG,
+    BUILD_DEBUG_MARKER,
     DEBUG_MNEMONIC,
     ETHEREUM_MAINNET_CHAIN_ID,
     ETHEREUM_SEPOLIA_CHAIN_ID,

src/shared/wallet.js

@@ -5,6 +5,10 @@ const { Mnemonic, HDNodeWallet, Wallet } = require("ethers");
 const { DEBUG, DEBUG_MNEMONIC, BIP44_ETH_PATH } = require("./constants");
 
 function generateMnemonic() {
+    // This must stay the compile-time DEBUG constant. Do NOT switch it to
+    // isDebug() from log.js: that also ORs in the runtime debugMode flag the
+    // settings toggle drives, which would let a user of a release build turn
+    // the hardcoded, publicly known test phrase back on for real wallets.
     if (DEBUG) return DEBUG_MNEMONIC;
     const m = Mnemonic.fromEntropy(
         globalThis.crypto.getRandomValues(new Uint8Array(16)),

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);

tests/wallet.test.js

@@ -0,0 +1,94 @@
+// Tests for the DEBUG build flag as it gates mnemonic generation.
+//
+// The modules read the __BUILD_DEBUG__ global that esbuild replaces at bundle
+// time. Under jest the global is absent, which is exactly the release-build
+// case; the debug-build case is exercised by defining the global and
+// re-requiring the modules with a fresh registry.
+
+const WORDS_IN_12_WORD_PHRASE = 12;
+
+function loadWallet() {
+    const constants = require("../src/shared/constants");
+    const wallet = require("../src/shared/wallet");
+    const log = require("../src/shared/log");
+    return { constants, wallet, log };
+}
+
+describe("generateMnemonic in a release build", () => {
+    beforeEach(() => {
+        jest.resetModules();
+        delete globalThis.__BUILD_DEBUG__;
+    });
+
+    test("DEBUG defaults to false when the build define is absent", () => {
+        const { constants } = loadWallet();
+        expect(constants.DEBUG).toBe(false);
+    });
+
+    test("returns fresh, valid 12-word phrases that are not the test phrase", () => {
+        const { constants, wallet } = loadWallet();
+
+        const first = wallet.generateMnemonic();
+        const second = wallet.generateMnemonic();
+
+        expect(first).not.toBe(second);
+        for (const phrase of [first, second]) {
+            expect(wallet.isValidMnemonic(phrase)).toBe(true);
+            expect(phrase.split(" ")).toHaveLength(WORDS_IN_12_WORD_PHRASE);
+            expect(phrase).not.toBe(constants.DEBUG_MNEMONIC);
+        }
+    });
+
+    test("derives a usable HD wallet from the generated phrase", () => {
+        const { wallet } = loadWallet();
+
+        const { xpub, firstAddress } = wallet.hdWalletFromMnemonic(
+            wallet.generateMnemonic(),
+        );
+
+        expect(xpub.startsWith("xpub")).toBe(true);
+        expect(firstAddress).toMatch(/^0x[0-9a-fA-F]{40}$/);
+    });
+
+    test("the runtime debug toggle cannot re-enable the test phrase", () => {
+        const { constants, wallet, log } = loadWallet();
+
+        // What the settings easter-egg toggle does at runtime.
+        log.setRuntimeDebug(true);
+        expect(log.isDebug()).toBe(true);
+
+        const phrase = wallet.generateMnemonic();
+        expect(phrase).not.toBe(constants.DEBUG_MNEMONIC);
+        expect(wallet.isValidMnemonic(phrase)).toBe(true);
+        expect(phrase).not.toBe(wallet.generateMnemonic());
+
+        log.setRuntimeDebug(false);
+    });
+});
+
+describe("generateMnemonic in a debug build", () => {
+    beforeEach(() => {
+        jest.resetModules();
+        globalThis.__BUILD_DEBUG__ = true;
+    });
+
+    afterEach(() => {
+        delete globalThis.__BUILD_DEBUG__;
+    });
+
+    test("DEBUG is true and the test phrase is returned", () => {
+        const { constants, wallet } = loadWallet();
+
+        expect(constants.DEBUG).toBe(true);
+        expect(wallet.generateMnemonic()).toBe(constants.DEBUG_MNEMONIC);
+    });
+
+    test("the test phrase is itself a valid 12-word BIP-39 phrase", () => {
+        const { constants, wallet } = loadWallet();
+
+        expect(wallet.isValidMnemonic(constants.DEBUG_MNEMONIC)).toBe(true);
+        expect(constants.DEBUG_MNEMONIC.split(" ")).toHaveLength(
+            WORDS_IN_12_WORD_PHRASE,
+        );
+    });
+});