@patchstack/connect 0.5.2 → 0.5.3

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";
@@ -3685,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",
@@ -3704,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";
@@ -3950,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);
@@ -4220,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;
@@ -4234,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");
@@ -4242,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.");
     }
@@ -4261,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: {} };
@@ -4281,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;
@@ -4307,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;
@@ -5069,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;
@@ -5149,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(
@@ -5184,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");
 }