@patchstack/connect 0.5.1 → 0.5.3

package/dist/protect/templates/generic-guard.cjs

@@ -1,6 +1,6 @@
 // Patchstack runtime protection — GENERIC guard (CommonJS). Managed by `patchstack-connect protect`.
 // Wire whichever helper fits your server into your request path, then run `protect --check`.
-const { createProtection } = require("@patchstack/connect/protect");
+const { createProtection, sentinelAnswer, VERIFY_HEADER } = require("@patchstack/connect/protect");
 // The fallback bundle is optional at RUNTIME. This file is imported on the app's own module path, so a
 // throw here is the app failing to boot rather than protection failing open — and a rules file can be
 // absent for ordinary reasons: a bundler that copied no JSON, a partial deploy, a half-written edit.
@@ -66,6 +66,12 @@ function psStepAside(err) {
 }
 function protectFetch(handler) {
   return async (request, ...rest) => {
+    // `protect --check --runtime` asks whether a request actually reaches this seam. The answer is
+    // derived from a challenge the verifying process mints per run, which rules out an app matching it
+    // by accident, and there is nothing to answer unless that process started this one. Without a
+    // challenge in the environment this is a header read.
+    const answered = await sentinelAnswer(request.headers.get(VERIFY_HEADER));
+    if (answered) return new Response(answered, { status: 200, headers: { "content-type": "text/plain" } });
     const active = await getProtection().catch(psStepAside);
     // The handler, and nothing around it: an exception the app throws is the app's, not a protection
     // failure, and must not be read as one or answered twice.
@@ -92,19 +98,37 @@ function patchstackMiddleware(req, res, next) {
     passedOn = true;
     next(err);
   };
-  getProtection().then(
-    (active) => active.node()(req, res, carryOn),
-    (err) => {
+  // `protect --check --runtime` asks whether a request actually reaches this seam. Answered here,
+  // before the protection is asked for and before the request is passed on, so no handler of the app's
+  // ever sees a verification request. The answer is derived from a challenge the verifying process mints
+  // per run, which rules out an app matching it by accident; without a challenge in the environment
+  // there is nothing to answer and the request is screened as normal.
+  const screen = () => {
+    getProtection().then(
+      (active) => active.node()(req, res, carryOn),
+      (err) => {
+        psStepAside(err);
+        carryOn();
+      },
+    ).catch((err) => {
+      // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+      // request is carried on only if it never was — an error here must not take the process down and
+      // must not answer twice.
       psStepAside(err);
       carryOn();
-    },
-  ).catch((err) => {
-    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
-    // request is carried on only if it never was — an error here must not take the process down and
-    // must not answer twice.
-    psStepAside(err);
-    carryOn();
-  });
+    });
+  };
+
+  sentinelAnswer(req.headers?.[VERIFY_HEADER]).then((answered) => {
+    if (answered) {
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/plain");
+      res.end(answered);
+
+      return;
+    }
+    screen();
+  }, screen);
 }
 
 module.exports = { getProtection, protectFetch, patchstackMiddleware };

package/dist/protect/templates/generic-guard.js

@@ -1,7 +1,7 @@
 // Patchstack runtime protection — GENERIC guard (ESM). Managed by `patchstack-connect protect`.
 // Wire whichever helper fits your server into your request path, then run `protect --check`.
 import { readFileSync } from "node:fs";
-import { createProtection } from "@patchstack/connect/protect";
+import { createProtection, sentinelAnswer, VERIFY_HEADER } from "@patchstack/connect/protect";
 
 // The fallback bundle is optional at RUNTIME. This file is imported on the app's own module path, so a
 // throw here is the app failing to boot rather than protection failing open — and a rules file can be
@@ -68,6 +68,12 @@ function psStepAside(err) {
 // Web-Fetch: export default { fetch: protectFetch(originalFetch) }
 export function protectFetch(handler) {
   return async (request, ...rest) => {
+    // `protect --check --runtime` asks whether a request actually reaches this seam. The answer is
+    // derived from a challenge the verifying process mints per run, which rules out an app matching it
+    // by accident, and there is nothing to answer unless that process started this one. Without a
+    // challenge in the environment this is a header read.
+    const answered = await sentinelAnswer(request.headers.get(VERIFY_HEADER));
+    if (answered) return new Response(answered, { status: 200, headers: { "content-type": "text/plain" } });
     const active = await getProtection().catch(psStepAside);
     // The handler, and nothing around it: an exception the app throws is the app's, not a protection
     // failure, and must not be read as one or answered twice.
@@ -94,17 +100,35 @@ export function patchstackMiddleware(req, res, next) {
     passedOn = true;
     next(err);
   };
-  getProtection().then(
-    (active) => active.node()(req, res, carryOn),
-    (err) => {
+  // `protect --check --runtime` asks whether a request actually reaches this seam. Answered here,
+  // before the protection is asked for and before the request is passed on, so no handler of the app's
+  // ever sees a verification request. The answer is derived from a challenge the verifying process mints
+  // per run, which rules out an app matching it by accident; without a challenge in the environment
+  // there is nothing to answer and the request is screened as normal.
+  const screen = () => {
+    getProtection().then(
+      (active) => active.node()(req, res, carryOn),
+      (err) => {
+        psStepAside(err);
+        carryOn();
+      },
+    ).catch((err) => {
+      // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+      // request is carried on only if it never was — an error here must not take the process down and
+      // must not answer twice.
       psStepAside(err);
       carryOn();
-    },
-  ).catch((err) => {
-    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
-    // request is carried on only if it never was — an error here must not take the process down and
-    // must not answer twice.
-    psStepAside(err);
-    carryOn();
-  });
+    });
+  };
+
+  sentinelAnswer(req.headers?.[VERIFY_HEADER]).then((answered) => {
+    if (answered) {
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/plain");
+      res.end(answered);
+
+      return;
+    }
+    screen();
+  }, screen);
 }

package/dist/protect/templates/generic-guard.ts

@@ -4,7 +4,7 @@
 // whichever helper below fits your server into your request path (see the plan the CLI printed),
 // then run `patchstack-connect protect --check` to confirm it's hooked up. The engine ships inside
 // @patchstack/connect — nothing else to install.
-import { createProtection } from "@patchstack/connect/protect";
+import { createProtection, sentinelAnswer, VERIFY_HEADER } from "@patchstack/connect/protect";
 import fallbackRules from "./rules.json";
 
 // Baked by `patchstack-connect protect` from .patchstackrc.json when available.
@@ -76,6 +76,12 @@ function psStepAside(err: unknown) {
 // Wrap your fetch handler:  export default { fetch: protectFetch(originalFetch) }
 export function protectFetch<H extends (request: Request, ...rest: unknown[]) => unknown>(handler: H): H {
   return (async (request: Request, ...rest: unknown[]) => {
+    // `protect --check --runtime` asks whether a request actually reaches this seam. The answer is
+    // derived from a challenge the verifying process mints per run, which rules out an app matching it
+    // by accident, and there is nothing to answer unless that process started this one. Without a
+    // challenge in the environment this is a header read.
+    const answered = await sentinelAnswer(request.headers.get(VERIFY_HEADER));
+    if (answered) return new Response(answered, { status: 200, headers: { "content-type": "text/plain" } });
     const protection = await getProtection().catch(psStepAside);
     // The handler, and nothing around it: an exception the app throws is the app's, not a protection
     // failure, and must not be read as one or answered twice.
@@ -103,17 +109,40 @@ export function patchstackMiddleware(req: unknown, res: unknown, next: (err?: un
     passedOn = true;
     next(err);
   };
-  getProtection().then(
-    (protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, carryOn),
-    (err) => {
+  // `protect --check --runtime` asks whether a request actually reaches this seam. Answered here,
+  // before the protection is asked for and before the request is passed on, so no handler of the app's
+  // ever sees a verification request. The answer is derived from a challenge the verifying process mints
+  // per run, which rules out an app matching it by accident; without a challenge in the environment
+  // there is nothing to answer and the request is screened as normal.
+  const screen = () => {
+    getProtection().then(
+      (protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, carryOn),
+      (err) => {
+        psStepAside(err);
+        carryOn();
+      },
+    ).catch((err) => {
+      // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+      // request is carried on only if it never was — an error here must not take the process down and
+      // must not answer twice.
       psStepAside(err);
       carryOn();
-    },
-  ).catch((err) => {
-    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
-    // request is carried on only if it never was — an error here must not take the process down and
-    // must not answer twice.
-    psStepAside(err);
-    carryOn();
-  });
+    });
+  };
+
+  // The two shapes this seam touches, named rather than asserted wholesale: a request whose headers it
+  // reads, and a response it answers on.
+  const inbound = req as { headers?: Record<string, unknown> };
+  const outbound = res as { statusCode: number; setHeader(name: string, value: string): void; end(body?: string): void };
+
+  sentinelAnswer(inbound.headers?.[VERIFY_HEADER]).then((answered) => {
+    if (answered) {
+      outbound.statusCode = 200;
+      outbound.setHeader("content-type", "text/plain");
+      outbound.end(answered);
+
+      return;
+    }
+    screen();
+  }, screen);
 }

package/dist/protect.cjs

@@ -123,6 +123,27 @@ var init_pulse_token = __esm({
   }
 });
 
+// src/build-id.ts
+function canonicalBuildId(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return BUILD_ID.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+function readBuildStamp(bundle) {
+  if (bundle === null || typeof bundle !== "object") return null;
+  const namespace = bundle[BUILD_STAMP_KEY];
+  if (namespace === null || typeof namespace !== "object") return null;
+  return canonicalBuildId(namespace.build_id);
+}
+var BUILD_ID, BUILD_STAMP_KEY;
+var init_build_id = __esm({
+  "src/build-id.ts"() {
+    "use strict";
+    BUILD_ID = /^[0-9a-f]{64}$/i;
+    BUILD_STAMP_KEY = "_patchstack";
+  }
+});
+
 // src/types.ts
 var PatchstackError;
 var init_types = __esm({
@@ -246,6 +267,7 @@ var init_client = __esm({
     "use strict";
     init_types();
     init_pulse_token();
+    init_build_id();
     DEFAULT_ENDPOINT = "https://api.patchstack.com/monitor/pulse/manifest";
     DEFAULT_TIMEOUT_MS = 3e4;
     CLAIM_TOKEN_HEADER = "X-Patchstack-Claim-Token";
@@ -1845,9 +1867,11 @@ var runtime_exports = {};
 __export(runtime_exports, {
   GUARD_PATH: () => GUARD_PATH,
   PulseRuleClient: () => PulseRuleClient,
+  VERIFY_HEADER: () => VERIFY_HEADER,
   createProtection: () => createProtection,
   createServerFnGuard: () => createServerFnGuard,
-  createSupabaseGuard: () => createSupabaseGuard
+  createSupabaseGuard: () => createSupabaseGuard,
+  sentinelAnswer: () => sentinelAnswer
 });
 module.exports = __toCommonJS(runtime_exports);
 
@@ -3683,6 +3707,18 @@ var RULE_PROPERTY_SHAPES = Object.freeze({
 });
 var ENFORCEMENT_VALUES = Object.freeze(["dry-run"]);
 var WHEN_KEYS = Object.freeze(["path", "method"]);
+var BUILD_SCOPE_PROPERTY = "build_scope";
+var BUILD_SCOPE = Object.freeze({
+  applies_to: Object.freeze(["firewall"]),
+  usable: Object.freeze({
+    type: "string",
+    trim: true,
+    pattern: "^[0-9a-fA-F]{64}$",
+    canonical: "lowercase"
+  }),
+  unreadable: "the rule remains accepted and detects only by default",
+  local_override: "trustLocalRuleScope may explicitly enforce a caller-supplied rule"
+});
 var RULE_PROPERTIES = Object.freeze([
   "id",
   "rule_id",
@@ -3702,12 +3738,13 @@ var RULE_PROPERTIES = Object.freeze([
   "remove_headers",
   "cookie_flags",
   "ensure",
-  "capture"
+  "capture",
+  BUILD_SCOPE_PROPERTY
 ]);
 var CAPTURE_VERSION = 1;
 var CAPTURE_KEYS = Object.freeze(["version", "raw_chars"]);
 var CAPTURE_RAW_CHARS_MAX = 512;
-var NULL_EXEMPT_PROPERTIES = Object.freeze(["capture"]);
+var NULL_EXEMPT_PROPERTIES = Object.freeze(["capture", BUILD_SCOPE_PROPERTY]);
 function captureProblem(capture) {
   if (capture === void 0 || capture === null) return null;
   if (typeof capture !== "object" || Array.isArray(capture)) return "capture must be an object";
@@ -3948,6 +3985,10 @@ function validateBundle(bundle, opts = {}) {
       rejected.push({ id: idOf(wl), reason: "whitelist has no rule_id (would suppress every rule); set allowGlobalWhitelists to permit" });
       continue;
     }
+    if (wl && typeof wl === "object" && BUILD_SCOPE_PROPERTY in wl) {
+      rejected.push({ id: idOf(wl), reason: `whitelist may not carry ${BUILD_SCOPE_PROPERTY}` });
+      continue;
+    }
     const reason = conditionsProblem(wl?.rule_v2);
     if (reason) rejected.push({ id: idOf(wl), reason: `whitelist: ${reason}` });
     else whitelists.push(wl);
@@ -4218,8 +4259,11 @@ function asText(value) {
 
 // src/protect/engine/pulse-client.js
 init_pulse_token();
+init_build_id();
 var DEFAULT_BASE_URL2 = "https://api.patchstack.com/monitor/pulse";
 var DEFAULT_CACHE_TTL2 = 3e5;
+var BUILD_VERDICT_HEADER = "X-Patchstack-Build-Match";
+var BUILD_IDENTITY_HEADER = "X-Patchstack-Build-ID";
 var JITTER_FRACTION2 = 0.1;
 var PulseRuleClient = class {
   #siteUuid;
@@ -4232,7 +4276,8 @@ var PulseRuleClient = class {
   #etag;
   #pulseAuth;
   #detectionState;
-  constructor({ siteUuid, baseUrl, cacheTtl, etag, timeoutMs, pulseAuth, detectionState } = {}) {
+  #buildId;
+  constructor({ siteUuid, baseUrl, cacheTtl, etag, timeoutMs, pulseAuth, detectionState, buildId } = {}) {
     this.#timeoutMs = Number(timeoutMs) > 0 ? Number(timeoutMs) : 3e4;
     this.#siteUuid = siteUuid ?? process.env.PATCHSTACK_SITE_UUID;
     this.#baseUrl = safeBaseUrl(baseUrl ?? process.env.PATCHSTACK_PULSE_RULES_URL, DEFAULT_BASE_URL2, "rule endpoint");
@@ -4240,6 +4285,7 @@ var PulseRuleClient = class {
     this.#etag = etag ?? null;
     this.#pulseAuth = pulseAuth ?? null;
     this.#detectionState = typeof detectionState === "string" ? detectionState : null;
+    this.#buildId = canonicalBuildId(buildId);
     if (!this.#siteUuid) {
       throw new Error("Patchstack site UUID is required. Pass { siteUuid } or set PATCHSTACK_SITE_UUID.");
     }
@@ -4259,11 +4305,23 @@ var PulseRuleClient = class {
       if (this.#detectionState !== null && typeof auth.Authorization === "string") {
         headers["X-Patchstack-Detections"] = this.#detectionState;
       }
+      if (this.#buildId !== null && typeof auth.Authorization === "string") {
+        headers["X-Patchstack-Build"] = this.#buildId;
+      }
       if (this.#etag) headers["If-None-Match"] = this.#etag;
       const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(this.#timeoutMs) });
       if (response.status === 304) {
         this.#touch(now);
-        return this.#cache ?? { success: true, notModified: true, etag: this.#etag, firewall: [], whitelists: [], whitelist_keys: {} };
+        const result2 = {
+          ...this.#cache ?? { firewall: [], whitelists: [], whitelist_keys: {} },
+          success: true,
+          notModified: true,
+          etag: response.headers?.get?.("etag") ?? this.#etag,
+          build: buildVerdictOf(response.headers)
+        };
+        this.#cache = result2;
+        this.#etag = result2.etag;
+        return result2;
       }
       if (!response.ok) {
         return { success: false, error: `API returned ${response.status}`, firewall: [], whitelists: [], whitelist_keys: {} };
@@ -4279,7 +4337,10 @@ var PulseRuleClient = class {
         firewall: data.firewall,
         whitelists: Array.isArray(data.whitelists) ? data.whitelists : [],
         whitelist_keys: data.whitelist_keys ?? {},
-        ...enforcementField(data)
+        ...enforcementField(data),
+        // Carried through so the caller can decide what a build-scoped rule may do. Response metadata,
+        // rather than bundle content, because it varies with the build asking and is also present on 304.
+        build: buildVerdictOf(response.headers)
       };
       this.#cache = result;
       this.#etag = result.etag;
@@ -4305,6 +4366,13 @@ var PulseRuleClient = class {
     this.#etag = null;
   }
 };
+function buildVerdictOf(headers) {
+  const get = headers !== null && typeof headers === "object" && typeof headers.get === "function" ? (name) => headers.get(name) : () => null;
+  const stated2 = get(BUILD_VERDICT_HEADER);
+  const verdict = stated2 === "match" || stated2 === "missing" || stated2 === "mismatch" ? stated2 : "unknown";
+  const matched = get(BUILD_IDENTITY_HEADER);
+  return { verdict, matchedBuildId: typeof matched === "string" ? matched : null };
+}
 function enforcementField(data) {
   if (!data || typeof data !== "object") return {};
   const v = data.enforcement ?? data.mode;
@@ -5067,6 +5135,7 @@ function renderBlockPage({ url = "", code = "patchstack" } = {}) {
 }
 
 // src/protect/rules/store.js
+init_build_id();
 var fsMod;
 async function loadFs() {
   if (fsMod !== void 0) return fsMod;
@@ -5147,15 +5216,25 @@ async function cacheRead(dir) {
 function toEnvelope(value) {
   if (!value || typeof value !== "object") return null;
   if (value.bundle && typeof value.bundle === "object") {
-    return { bundle: value.bundle, etag: value.etag ?? null };
+    const buildId = canonicalBuildId(value.buildId);
+    const matched = canonicalBuildId(value.matchedBuildId);
+    return {
+      bundle: value.bundle,
+      etag: value.etag ?? null,
+      buildId,
+      // A confirmation belongs to the presentation stored beside it. A crossed or partially written
+      // envelope confirms nothing, even when one of its fields happens to name the current map.
+      matchedBuildId: buildId !== null && matched === buildId ? matched : null
+    };
   }
   if (Array.isArray(value.firewall) || Array.isArray(value.whitelists)) {
-    return { bundle: value, etag: null };
+    return { bundle: value, etag: null, buildId: null, matchedBuildId: null };
   }
   return null;
 }
 
 // src/protect/rules/source.js
+init_build_id();
 function liveUpdateRejections(res, options) {
   if (options.acceptPartialBundle) return [];
   const { rejected } = validateBundle(
@@ -5182,62 +5261,146 @@ function fromSource(bundle, origin, reason) {
     source: reason === void 0 ? { ok: true, origin } : { ok: false, origin, reason }
   };
 }
+function buildIdentity(options) {
+  if (options.buildId !== void 0 && options.buildId !== null) {
+    const explicit = canonicalBuildId(options.buildId);
+    return explicit === null ? { id: null, reason: "the buildId option is not a complete 64-hex SHA-256 identity" } : { id: explicit };
+  }
+  const stamped = readBuildStamp(options.rules);
+  if (stamped !== null) return { id: stamped };
+  return {
+    id: null,
+    reason: options.rules ? "the guard rules file carries no build identity \u2014 the build did not stamp one" : "this guard was configured without bundled rules, so it carries no build identity"
+  };
+}
+function withScopedDryRun(bundle, confirmed, reason, options = {}) {
+  let held = 0;
+  let unusable = 0;
+  const firewall = bundle.firewall.map((rule) => {
+    if (rule === null || typeof rule !== "object") return rule;
+    if (!(BUILD_SCOPE_PROPERTY in rule)) return rule;
+    const scope = rule[BUILD_SCOPE_PROPERTY];
+    const target = canonicalBuildId(scope);
+    if (target !== null && confirmed !== null && target === confirmed) return rule;
+    if (rule.enforcement === "dry-run") return rule;
+    held += 1;
+    if (target === null) unusable += 1;
+    return { ...rule, enforcement: "dry-run" };
+  });
+  if (held === 0) return bundle;
+  const explanations = [
+    ...unusable > 0 ? [`${unusable} rule(s) carry an unusable ${BUILD_SCOPE_PROPERTY}`] : [],
+    ...held > unusable ? [reason] : []
+  ];
+  notify(
+    options.onError,
+    new Error(`${held} build-scoped rule(s) are detecting only, not blocking: ${explanations.join("; ")}`),
+    "onError"
+  );
+  return { ...bundle, firewall };
+}
+function confirmedBy(res, presented) {
+  if (presented === null) return null;
+  const verdict = res?.build;
+  if (verdict?.verdict !== "match") return null;
+  return canonicalBuildId(verdict.matchedBuildId) === presented ? presented : null;
+}
 async function resolveRules(options, store, ctx = {}) {
   const timeoutMs = ctx.timeoutMs;
   if (options.siteUuid) {
     const prior = await store.read();
-    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl, etag: prior?.etag, timeoutMs, pulseAuth: ctx.pulseAuth, detectionState: ctx.detectionState });
+    const identity = buildIdentity(options);
+    const sameBuild = prior?.buildId === identity.id;
+    const cacheConfirmed = identity.id !== null && sameBuild && prior?.matchedBuildId === identity.id ? identity.id : null;
+    const unconfirmed = identity.reason ?? "the platform did not confirm that these coordinates belong to this map";
+    const served = (bundle, confirmed) => withScopedDryRun(bundle, confirmed, unconfirmed, options);
+    const local = (bundle) => options.trustLocalRuleScope === true ? bundle : withScopedDryRun(bundle, identity.id, identity.reason ?? "these rules name a different map", options);
+    const client = new PulseRuleClient({
+      siteUuid: options.siteUuid,
+      baseUrl: options.pulseRulesUrl,
+      etag: sameBuild ? prior?.etag : null,
+      timeoutMs,
+      pulseAuth: ctx.pulseAuth,
+      detectionState: ctx.detectionState,
+      buildId: identity.id
+    });
     const res = await client.getRules();
-    if (res.success && res.notModified && prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options), "cache");
+    if (res.success && res.notModified && prior?.bundle) {
+      const confirmed = confirmedBy(res, identity.id);
+      await store.write({
+        bundle: prior.bundle,
+        etag: res.etag ?? prior.etag ?? null,
+        buildId: identity.id,
+        matchedBuildId: confirmed
+      });
+      return fromSource(served(normalizeBundle(prior.bundle, options), confirmed), "cache");
+    }
     if (res.success && !res.notModified) {
+      const confirmed = confirmedBy(res, identity.id);
       const rejected = liveUpdateRejections(res, options);
       if (rejected.length > 0) {
         reportRejections(rejected, options, "rule update rejected");
-        if (prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options), "cache", "update rejected");
-        if (options.rules) return fromSource(normalizeBundle(options.rules, options), "bundled", "update rejected");
+        if (prior?.bundle) return fromSource(served(normalizeBundle(prior.bundle, options), cacheConfirmed), "cache", "update rejected");
+        if (options.rules) return fromSource(local(normalizeBundle(options.rules, options)), "bundled", "update rejected");
         return fromSource(emptyBundle(), "empty", "update rejected");
       }
       const bundle = normalizeBundle(res, options);
-      await store.write({ bundle, etag: res.etag ?? null });
-      return fromSource(bundle, "api");
+      await store.write({ bundle, etag: res.etag ?? null, buildId: identity.id, matchedBuildId: confirmed });
+      return fromSource(served(bundle, confirmed), "api");
     }
     if (prior?.bundle) {
       notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`), "onError");
-      return fromSource(normalizeBundle(prior.bundle, options), "cache", res.error ?? "no usable response");
+      return fromSource(served(normalizeBundle(prior.bundle, options), cacheConfirmed), "cache", res.error ?? "no usable response");
     }
     if (options.rules) {
       notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using bundled fallback`), "onError");
-      return fromSource(normalizeBundle(options.rules, options), "bundled", res.error ?? "no usable response");
+      return fromSource(local(normalizeBundle(options.rules, options)), "bundled", res.error ?? "no usable response");
     }
     notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`), "onError");
     return fromSource(emptyBundle(), "empty", res.error ?? "no usable response");
   }
   if (options.token) {
+    const identity = buildIdentity(options);
+    const remote = (bundle) => withScopedDryRun(
+      bundle,
+      null,
+      "the token-authenticated rules service did not corroborate this map",
+      options
+    );
+    const local = (bundle) => options.trustLocalRuleScope === true ? bundle : withScopedDryRun(bundle, identity.id, identity.reason ?? "these rules name a different map", options);
     const prior = await store.read();
     const client = new PatchstackRuleClient({ token: options.token, baseUrl: options.baseUrl, etag: prior?.etag, timeoutMs });
     const res = await client.getRules();
-    if (res.success && res.notModified && prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options), "cache");
+    if (res.success && res.notModified && prior?.bundle) {
+      return fromSource(remote(normalizeBundle(prior.bundle, options)), "cache");
+    }
     if (res.success && !res.notModified) {
       const rejected = liveUpdateRejections(res, options);
       if (rejected.length > 0) {
         reportRejections(rejected, options, "rule update rejected");
-        if (prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options), "cache", "update rejected");
-        if (options.rules) return fromSource(normalizeBundle(options.rules, options), "bundled", "update rejected");
+        if (prior?.bundle) return fromSource(remote(normalizeBundle(prior.bundle, options)), "cache", "update rejected");
+        if (options.rules) return fromSource(local(normalizeBundle(options.rules, options)), "bundled", "update rejected");
         return fromSource(emptyBundle(), "empty", "update rejected");
       }
       const bundle = normalizeBundle(res, options);
       await store.write({ bundle, etag: res.etag ?? null });
-      return fromSource(bundle, "api");
+      return fromSource(remote(bundle), "api");
     }
     if (prior?.bundle) {
       notify(options.onError, new Error(`rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`), "onError");
-      return fromSource(normalizeBundle(prior.bundle, options), "cache", res.error ?? "no usable response");
+      return fromSource(remote(normalizeBundle(prior.bundle, options)), "cache", res.error ?? "no usable response");
     }
     notify(options.onError, new Error(`rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`), "onError");
     return fromSource(emptyBundle(), "empty", res.error ?? "no usable response");
   }
   if (options.rules) {
-    return fromSource(normalizeBundle(options.rules, options), "bundled");
+    const identity = buildIdentity(options);
+    const bundle = normalizeBundle(options.rules, options);
+    if (options.trustLocalRuleScope === true) return fromSource(bundle, "bundled");
+    return fromSource(
+      withScopedDryRun(bundle, identity.id, identity.reason ?? "these rules name a different map", options),
+      "bundled"
+    );
   }
   return fromSource(emptyBundle(), "empty");
 }
@@ -6330,6 +6493,33 @@ function createSupabaseGuard({ protection, supabaseUrl, fetchImpl = fetch }) {
   };
 }
 
+// src/protect/verify-sentinel.js
+var VERIFY_HEADER = "x-patchstack-verify";
+var CHALLENGE = "PATCHSTACK_VERIFY_CHALLENGE";
+function configuredChallenge() {
+  const value = typeof process !== "undefined" ? process.env?.[CHALLENGE] : void 0;
+  return typeof value === "string" && value.length >= 32 ? value : null;
+}
+function sameValue(a, b) {
+  if (typeof a !== "string" || typeof b !== "string" || a.length !== b.length) return false;
+  let differs = 0;
+  for (let i = 0; i < a.length; i += 1) differs |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return differs === 0;
+}
+async function sentinelAnswer(offered) {
+  const challenge = configuredChallenge();
+  if (challenge === null || !sameValue(challenge, typeof offered === "string" ? offered : null)) return null;
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle || typeof subtle.digest !== "function" || typeof TextEncoder === "undefined") return null;
+  try {
+    const bytes = new TextEncoder().encode(`patchstack-verify:${challenge}`);
+    const digest = await subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+  } catch {
+    return null;
+  }
+}
+
 // src/protect/runtime.js
 function createServerFnGuard({ protection }) {
   const guard = protection.fetchGuard();
@@ -7667,8 +7857,10 @@ function nodeRequestMeta(req, client) {
 0 && (module.exports = {
   GUARD_PATH,
   PulseRuleClient,
+  VERIFY_HEADER,
   createProtection,
   createServerFnGuard,
-  createSupabaseGuard
+  createSupabaseGuard,
+  sentinelAnswer
 });
 //# sourceMappingURL=protect.cjs.map