Let the deployed guard name the build it runs (#456)

The guard's live report sends `_patchstack.manifest_checksum` from its rules
file, but nothing wrote that field, so a live report could only say that some
build was serving. The `prebuild` scan now records the checksum of the package
list being built there, beside the map stamp, before the bundler reads the
file. A server-rendered deployment with no marker on its pages can then say
which build it is.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: mariojgt

AGENT-INSTALL.md

@@ -464,7 +464,7 @@ PATCHSTACK_ENVIRONMENT=sandbox npx @patchstack/connect setup
 
 The generated `prebuild` scan deliberately carries no hard-coded environment. A production build with no override reports `production` only because the platform's own variables — its tier, or its branch name — say it is one; a preview or pull request on those platforms reports `sandbox` by itself, and a hosted builder's *workspace* reports `sandbox` for anything but a build lifecycle script, and must receive `PATCHSTACK_ENVIRONMENT=sandbox` from its host only if it runs builds (the Replit workspace reports `sandbox` on its own) — its published build needs no override, because a build in such a project is the publish step. Runtime protection itself is not environment-specific: `PATCHSTACK_ENVIRONMENT` labels manifests only. Use `PATCHSTACK_MODE=dry-run` when protection should observe rather than block.
 
-During a build, the `prebuild` scan removes any previous map stamp. A later `map --upload` in the same pre-bundle lifecycle hashes the map's policy content (excluding analyser timing and memory observations) and records that identity in the guard's existing rules file. The guard presents it on the rules request it already makes; only an explicit Patchstack confirmation naming the same map lets a rule scoped to one of your app's parameter names block. A build with no confirmed identity still enforces every ordinary rule — only scoped rules drop to detect-only, with the reason reported. Outside a pre-bundle hook, `map --upload` changes no file and sends no identity. In any project whose guard has a rules file, unless `.patchstackrc.json` sets `"bundleRules": false`, a `scan` that holds the key also uploads the map, writes its identity and the site's current rules into the guard's rules file (keeping the starter signatures, only when something changed), so a keyless build of the same source — a hosted builder's publish, or any deploy without the key — ships those rules and is recognised. The same runs store a read-only rules credential in that file (`_patchstack.rules_reader`, from `monitor/pulse/rules-reader/<uuid>`), with which the published app fetches live rules and reports detections — it can read this site's rules and report detections for this site, and nothing else. Detections reported on it are stored **unverified** (set `PATCHSTACK_API_KEY` in the deployment to report as verified). See "Which build a rule belongs to" in `AGENT-INSTALL.md`.
+During a build, the `prebuild` scan removes any previous map stamp and records the checksum of the package list being built as `_patchstack.manifest_checksum` in the guard's rules file; the deployed guard sends it when it reports the deployment live, so Patchstack knows which build is serving. A later `map --upload` in the same pre-bundle lifecycle hashes the map's policy content (excluding analyser timing and memory observations) and records that identity in the guard's existing rules file. The guard presents it on the rules request it already makes; only an explicit Patchstack confirmation naming the same map lets a rule scoped to one of your app's parameter names block. A build with no confirmed identity still enforces every ordinary rule — only scoped rules drop to detect-only, with the reason reported. Outside a pre-bundle hook, `map --upload` changes no file and sends no identity. In any project whose guard has a rules file, unless `.patchstackrc.json` sets `"bundleRules": false`, a `scan` that holds the key also uploads the map, writes its identity and the site's current rules into the guard's rules file (keeping the starter signatures, only when something changed), so a keyless build of the same source — a hosted builder's publish, or any deploy without the key — ships those rules and is recognised. The same runs store a read-only rules credential in that file (`_patchstack.rules_reader`, from `monitor/pulse/rules-reader/<uuid>`), with which the published app fetches live rules and reports detections — it can read this site's rules and report detections for this site, and nothing else. Detections reported on it are stored **unverified** (set `PATCHSTACK_API_KEY` in the deployment to report as verified). See "Which build a rule belongs to" in `AGENT-INSTALL.md`.
 
 ### `scan` as a build hook
 

README.md

@@ -299,17 +299,23 @@ function detectIndent(text: string): string | number {
   return whitespace.includes('\t') ? '\t' : whitespace.length;
 }
 
+interface LoadedRulesFile {
+  kind: 'loaded';
+  path: string;
+  file: string;
+  text: string;
+  parsed: unknown;
+  bundle: Record<string, unknown>;
+}
+
 /**
- * Write `id` into the guard's rules file, or remove any stamp when `id` is null.
+ * The guard's rules file, read and parsed, or why nothing may be written into it.
  *
  * Corrupt JSON is left exactly as it is. Replacing it with a fresh bundle would discard whatever the
- * app had — possibly rules it is relying on — to fix a field that only affects whether pinned rules may
- * enforce. Reporting that stamping was unavailable is the proportionate answer.
- *
- * Idempotent: a build whose identity has not changed rewrites nothing, so a committed file does not
- * churn on every local build.
+ * app had — possibly rules it is relying on — to fix metadata the rules themselves do not depend on.
+ * Reporting that stamping was unavailable is the proportionate answer.
  */
-export function applyBuildStamp(cwd: string, id: string | null): StampOutcome {
+function loadRulesFile(cwd: string): LoadedRulesFile | { kind: 'skipped'; reason: string } {
   const location = findRulesFile(cwd);
   if (location.kind === 'none') return { kind: 'skipped', reason: 'no guard rules file in this project' };
   if (location.kind === 'unreadable') {
@@ -338,6 +344,33 @@ export function applyBuildStamp(cwd: string, id: string | null): StampOutcome {
   }
   const bundle = ruleBundleOf(parsed);
   if (bundle === null) return { kind: 'skipped', reason: `${file} is not a guard rules bundle` };
+
+  return { kind: 'loaded', path: location.path, file, text, parsed, bundle };
+}
+
+/** Write the bundle back in the file's own indentation, or say why it could not be. */
+function saveRulesFile(cwd: string, loaded: LoadedRulesFile): { kind: 'skipped'; reason: string } | null {
+  const { text, bundle } = loaded;
+  const serialised = JSON.stringify(bundle, null, detectIndent(text)) + (text.endsWith('\n') ? '\n' : '');
+  try {
+    writeProjectFileSync(cwd, loaded.path, serialised, { encoding: 'utf8' });
+  } catch (err) {
+    return { kind: 'skipped', reason: `${loaded.file} could not be written (${(err as Error).message})` };
+  }
+
+  return null;
+}
+
+/**
+ * Write `id` into the guard's rules file, or remove any stamp when `id` is null.
+ *
+ * Idempotent: a build whose identity has not changed rewrites nothing, so a committed file does not
+ * churn on every local build.
+ */
+export function applyBuildStamp(cwd: string, id: string | null): StampOutcome {
+  const loaded = loadRulesFile(cwd);
+  if (loaded.kind === 'skipped') return loaded;
+  const { file, parsed, bundle } = loaded;
   const current = readBuildStamp(bundle);
   // Clearing keys off the RAW property, not the canonical reading of it. A malformed `build_id` reads as
   // null, so comparing canonical values would call a file that still carries `"deadbee"` unchanged and
@@ -351,12 +384,35 @@ export function applyBuildStamp(cwd: string, id: string | null): StampOutcome {
   if (Object.keys(namespace).length === 0) delete bundle[BUILD_STAMP_KEY];
   else bundle[BUILD_STAMP_KEY] = namespace;
 
-  const serialised = JSON.stringify(bundle, null, detectIndent(text)) + (text.endsWith('\n') ? '\n' : '');
-  try {
-    writeProjectFileSync(cwd, location.path, serialised, { encoding: 'utf8' });
-  } catch (err) {
-    return { kind: 'skipped', reason: `${file} could not be written (${(err as Error).message})` };
-  }
+  const failed = saveRulesFile(cwd, loaded);
+  if (failed !== null) return failed;
 
   return id === null ? { kind: 'cleared', file } : { kind: 'stamped', file, id };
 }
+
+/** A manifest checksum as `scan` computes it: twelve lowercase hex characters. */
+const MANIFEST_CHECKSUM = /^[0-9a-f]{12}$/;
+
+/**
+ * Write the checksum of the build about to be compiled into the guard's rules file.
+ *
+ * The guard sends it when it reports the deployment live, which names the build that deployment runs.
+ * Without it, a live report says only that some build is serving. Idempotent like the build stamp.
+ */
+export function applyManifestChecksum(cwd: string, checksum: string): StampOutcome {
+  if (!MANIFEST_CHECKSUM.test(checksum)) return { kind: 'skipped', reason: 'not a manifest checksum' };
+
+  const loaded = loadRulesFile(cwd);
+  if (loaded.kind === 'skipped') return loaded;
+  const { file, parsed, bundle } = loaded;
+  const namespace = { ...((bundle[BUILD_STAMP_KEY] ?? {}) as Record<string, unknown>) };
+  if (bundle === parsed && namespace.manifest_checksum === checksum) return { kind: 'unchanged', file };
+
+  namespace.manifest_checksum = checksum;
+  bundle[BUILD_STAMP_KEY] = namespace;
+
+  const failed = saveRulesFile(cwd, loaded);
+  if (failed !== null) return failed;
+
+  return { kind: 'stamped', file, id: checksum };
+}

src/build-stamp.ts

@@ -121,7 +121,7 @@ import { runDevelopment } from './dev-command.js';
 import { checkActivation } from './activation-check.js';
 import { syncSetupProtection } from './setup-sync.js';
 import { isInstallOrBuildHook, isPreBundleBuildHook, undeliveredReportLines } from './build-hook.js';
-import { applyBuildStamp } from './build-stamp.js';
+import { applyBuildStamp, applyManifestChecksum } from './build-stamp.js';
 import { detectStack, type StackDescriptor } from './stack.js';
 import { PatchstackError, type StoreManifestResponse } from './types.js';
 import { buildWidgetTag, ensureSourceWidget, ensureWidgetInHtml, removeSourceWidget } from './widget.js';
@@ -873,7 +873,15 @@ async function runScan(
   // Independent of the widget: the marker is how Patchstack recognises the live build, with or without
   // the widget on the page. The checksum is the manifest this run is posting — on a pre-build hook the
   // build about to be compiled — so the page says which build is live, the question the dashboard grades on.
-  reportSourceMarker(shellFramework, computeManifestChecksum(payload.packages), report);
+  const buildChecksum = computeManifestChecksum(payload.packages);
+  reportSourceMarker(shellFramework, buildChecksum, report);
+
+  // The same checksum goes into the guard's rules file before the bundler reads it, so the deployed
+  // guard can name its build when it reports the deployment live, page or no page.
+  if (isPreBundleBuildHook()) {
+    const named = applyManifestChecksum(process.cwd(), buildChecksum);
+    if (named.kind === 'stamped') say(`Named this build (${buildChecksum}) in ${named.file} for the guard's live report.`);
+  }
 
   const provisioning = config.siteUuid === null;
   if (provisioning) {

src/cli.ts

@@ -838,6 +838,28 @@ describe.skipIf(!built)('the packaged bin, invoked as npm invokes it', () => {
         }
       });
 
+      it('names the build in the guard rules file on a pre-bundle build, and only then', async () => {
+        const server = await acceptingServer();
+        const dir = freshProject();
+        try {
+          const rules = path.join(dir, 'patchstack.rules.json');
+          writeFileSync(rules, `${JSON.stringify({ firewall: [], whitelists: [], whitelist_keys: {} }, null, 2)}\n`);
+          writeFileSync(
+            path.join(dir, 'guard.ts'),
+            'import { createProtection } from "@patchstack/connect/protect";\nimport rules from "./patchstack.rules.json";\nvoid createProtection({ rules });\n',
+          );
+
+          await scan(dir, server.endpoint, { npm_lifecycle_event: 'postinstall', npm_lifecycle_script: 'patchstack-connect scan' });
+          expect(JSON.parse(readFileSync(rules, 'utf8'))._patchstack?.manifest_checksum).toBeUndefined();
+
+          await scan(dir, server.endpoint, { npm_lifecycle_event: 'prebuild', npm_lifecycle_script: 'patchstack-connect scan' });
+          expect(JSON.parse(readFileSync(rules, 'utf8'))._patchstack?.manifest_checksum).toMatch(/^[0-9a-f]{12}$/);
+        } finally {
+          await server.close();
+          rmSync(dir, { recursive: true, force: true });
+        }
+      });
+
       it('says a network failure plainly, with the code for support', async () => {
         const dir = freshProject();
         try {

tests/bin-invocation.test.ts

@@ -11,7 +11,7 @@ import { basename, dirname, join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 
 import { hasRawBuildStamp, readBuildStamp } from '../src/build-id.js';
-import { applyBuildStamp, findRulesFile } from '../src/build-stamp.js';
+import { applyBuildStamp, applyManifestChecksum, findRulesFile } from '../src/build-stamp.js';
 import { isPreBundleBuildHook } from '../src/build-hook.js';
 
 const A = 'a'.repeat(64);
@@ -295,6 +295,42 @@ describe('writing the stamp', () => {
   });
 });
 
+describe('naming the build for the guard’s live report', () => {
+  const CHECKSUM = 'a1b2c3d4e5f6';
+
+  it('writes the checksum where the guard reads it, beside the other reserved fields', () => {
+    const dir = protectedProject('patchstack.rules.json', bundleText({ _patchstack: { build_id: A, rules_reader: 'reader' } }));
+    expect(applyManifestChecksum(dir, CHECKSUM)).toEqual({ kind: 'stamped', file: 'patchstack.rules.json', id: CHECKSUM });
+
+    const after = JSON.parse(read(dir, 'patchstack.rules.json'));
+    expect(after._patchstack).toEqual({ build_id: A, rules_reader: 'reader', manifest_checksum: CHECKSUM });
+    expect(after.firewall).toEqual(BUNDLE.firewall);
+  });
+
+  it('rewrites nothing for the same build, and replaces a previous one', () => {
+    const dir = protectedProject('patchstack.rules.json', bundleText());
+    applyManifestChecksum(dir, CHECKSUM);
+    const first = read(dir, 'patchstack.rules.json');
+
+    expect(applyManifestChecksum(dir, CHECKSUM)).toEqual({ kind: 'unchanged', file: 'patchstack.rules.json' });
+    expect(read(dir, 'patchstack.rules.json')).toBe(first);
+
+    expect(applyManifestChecksum(dir, 'ffffffffffff')).toMatchObject({ kind: 'stamped', id: 'ffffffffffff' });
+    expect(JSON.parse(read(dir, 'patchstack.rules.json'))._patchstack.manifest_checksum).toBe('ffffffffffff');
+  });
+
+  it('writes nothing that is not a checksum, and nothing into a project with no guard', () => {
+    const dir = protectedProject('patchstack.rules.json', bundleText());
+    const before = read(dir, 'patchstack.rules.json');
+    expect(applyManifestChecksum(dir, 'not-a-checksum').kind).toBe('skipped');
+    expect(read(dir, 'patchstack.rules.json')).toBe(before);
+
+    const bare = project({ 'rules.json': bundleText() });
+    expect(applyManifestChecksum(bare, CHECKSUM).kind).toBe('skipped');
+    expect(read(bare, 'rules.json')).toBe(bundleText());
+  });
+});
+
 describe('when a build may write to the project', () => {
   it('is a pre-bundle build lifecycle, and nothing else', () => {
     const before = project({'package.json':JSON.stringify({scripts:{build:'patchstack-connect scan && vite build && patchstack-connect mark-build'}})});

tests/build-stamp.test.ts

@@ -172,6 +172,16 @@ describe('a guard without the site credential, shipped with a rules reader', ()
     await protection.stop();
   });
 
+  it('names the build it runs in the live report when its rules file carries the checksum', async () => {
+    const { protection, calls } = await guard({ rules_reader: READER, manifest_checksum: 'a1b2c3d4e5f6' });
+
+    await protection.fetchGuard()(new Request('https://my-live-app.example.com/'));
+
+    const live = calls.find((c) => c.url.includes('/live/'));
+    expect(JSON.parse(String(live?.init.body))).toEqual({ origin: 'https://my-live-app.example.com', checksum: 'a1b2c3d4e5f6' });
+    await protection.stop();
+  });
+
   it('reports the forwarded public host, not the internal one, behind a reverse proxy', async () => {
     const { protection, calls } = await guard({ rules_reader: READER });