@patchstack/connect 0.5.2 → 0.5.3

package/dist/protect.d.cts

@@ -290,6 +290,32 @@ export interface CreateProtectionOptions {
   responseRules?: unknown[];
   /** Override the default egress-phase (SSRF) rule set. */
   egressRules?: unknown[];
+  /**
+   * The mapped coordinate identity this guard carries, as a complete 64-hex SHA-256 value. It is
+   * trimmed and compared in lowercase.
+   *
+   * Only needed when wiring `createProtection` by hand. A scaffolded guard carries this in the rules
+   * file its build stamped, and passing it here overrides that.
+   *
+   * What it authorises is narrow: a rule carrying `build_scope` may block only when the platform
+   * confirms the coordinates it served belong to THIS mapped document. Presenting an id is not that
+   * confirmation — the server answers it through response metadata, including on a `304` — so a wrong
+   * or invented value withholds enforcement rather than granting it. Any other format is ignored, with
+   * the same effect as passing nothing.
+   */
+  buildId?: string;
+  /**
+   * Take responsibility for `rules` you supply yourself, including any `build_scope` they carry.
+   *
+   * Off by default, and the default is the safe one. A rule scoped to a build addresses a route and a
+   * field name read from one particular source; supplying it locally establishes that you intend it,
+   * not that it still describes the code now running. Left alone, such a rule detects without blocking
+   * unless it names the map identity this guard reports.
+   *
+   * Set this only where the caller genuinely knows the rules match the running source — a test that
+   * vendors a rule against a fixed fixture, or a build that generates both together.
+   */
+  trustLocalRuleScope?: boolean;
   /** Opt in to wrapping global fetch to screen the app's outbound calls (SSRF). */
   egress?: boolean;
   /** Hosts exempt from egress screening. */

package/dist/protect.d.ts

@@ -290,6 +290,32 @@ export interface CreateProtectionOptions {
   responseRules?: unknown[];
   /** Override the default egress-phase (SSRF) rule set. */
   egressRules?: unknown[];
+  /**
+   * The mapped coordinate identity this guard carries, as a complete 64-hex SHA-256 value. It is
+   * trimmed and compared in lowercase.
+   *
+   * Only needed when wiring `createProtection` by hand. A scaffolded guard carries this in the rules
+   * file its build stamped, and passing it here overrides that.
+   *
+   * What it authorises is narrow: a rule carrying `build_scope` may block only when the platform
+   * confirms the coordinates it served belong to THIS mapped document. Presenting an id is not that
+   * confirmation — the server answers it through response metadata, including on a `304` — so a wrong
+   * or invented value withholds enforcement rather than granting it. Any other format is ignored, with
+   * the same effect as passing nothing.
+   */
+  buildId?: string;
+  /**
+   * Take responsibility for `rules` you supply yourself, including any `build_scope` they carry.
+   *
+   * Off by default, and the default is the safe one. A rule scoped to a build addresses a route and a
+   * field name read from one particular source; supplying it locally establishes that you intend it,
+   * not that it still describes the code now running. Left alone, such a rule detects without blocking
+   * unless it names the map identity this guard reports.
+   *
+   * Set this only where the caller genuinely knows the rules match the running source — a test that
+   * vendors a rule against a fixed fixture, or a build that generates both together.
+   */
+  trustLocalRuleScope?: boolean;
   /** Opt in to wrapping global fetch to screen the app's outbound calls (SSRF). */
   egress?: boolean;
   /** Hosts exempt from egress screening. */

package/dist/protect.edge.js

@@ -1867,6 +1867,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",
@@ -1886,12 +1898,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";
@@ -2132,6 +2145,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);
@@ -2482,9 +2499,26 @@ async function pulseFetch(config, url, init, fetchImpl = fetch) {
   return first.response;
 }
 
+// src/build-id.ts
+var BUILD_ID = /^[0-9a-f]{64}$/i;
+function canonicalBuildId(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return BUILD_ID.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+var BUILD_STAMP_KEY = "_patchstack";
+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);
+}
+
 // src/protect/engine/pulse-client.js
 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;
@@ -2497,7 +2531,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");
@@ -2505,6 +2540,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.");
     }
@@ -2524,11 +2560,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: {} };
@@ -2544,7 +2592,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;
@@ -2570,6 +2621,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 stated = get(BUILD_VERDICT_HEADER);
+  const verdict = stated === "match" || stated === "missing" || stated === "mismatch" ? stated : "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;
@@ -3412,10 +3470,19 @@ 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;
 }
@@ -3447,62 +3514,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");
 }