@patchstack/connect 0.5.2 → 0.5.4

package/dist/protect.js

@@ -1,7 +1,9 @@
 import {
+  canonicalBuildId,
   pulseAuthHeader,
-  pulseFetch
-} from "./chunk-3G2I6QL6.js";
+  pulseFetch,
+  readBuildStamp
+} from "./chunk-IOODP4ZB.js";
 
 // src/protect/client-ip.js
 var ZONE = /^[A-Za-z0-9._-]{1,64}$/;
@@ -1835,6 +1837,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",
@@ -1854,12 +1868,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";
@@ -2100,6 +2115,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);
@@ -2371,6 +2390,8 @@ function asText(value) {
 // 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;
@@ -2383,7 +2404,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");
@@ -2391,6 +2413,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.");
     }
@@ -2410,11 +2433,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: {} };
@@ -2430,7 +2465,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;
@@ -2456,6 +2494,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;
@@ -3298,10 +3343,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;
 }
@@ -3333,62 +3387,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");
 }
@@ -5317,7 +5455,7 @@ async function createProtection(options = {}) {
   let reporter = null;
   if (refreshable && options.siteUuid && options.reportManifest !== false && cwd) {
     try {
-      ({ reportManifest: reporter } = await import("./refresh-manifest-2MMPQN2A.js"));
+      ({ reportManifest: reporter } = await import("./refresh-manifest-K3RT4XNH.js"));
     } catch (err) {
       notify(onError, err, "onError");
     }