@patchstack/connect 0.3.28 → 0.3.30

package/dist/protect.edge.js

@@ -160,6 +160,45 @@ function base64DecodeUtf8(value) {
   const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
   return new TextDecoder().decode(bytes);
 }
+var NAMED_ENTITIES = {
+  lt: "<",
+  gt: ">",
+  amp: "&",
+  quot: '"',
+  apos: "'",
+  "#39": "'",
+  nbsp: "\xA0",
+  sol: "/",
+  bsol: "\\",
+  colon: ":",
+  lpar: "(",
+  rpar: ")",
+  equals: "=",
+  grave: "`",
+  Tab: "	",
+  NewLine: "\n",
+  semi: ";",
+  excl: "!",
+  num: "#",
+  dollar: "$",
+  percnt: "%",
+  ast: "*"
+};
+function decodeHtmlEntities(input) {
+  return input.replace(/&(#[xX]?[0-9a-fA-F]+|[A-Za-z][A-Za-z0-9]*);?/g, (whole, body) => {
+    if (body[0] === "#") {
+      const hex = body[1] === "x" || body[1] === "X";
+      const code = Number.parseInt(hex ? body.slice(2) : body.slice(1), hex ? 16 : 10);
+      if (!Number.isFinite(code) || code < 0 || code > 1114111) return whole;
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return whole;
+      }
+    }
+    return Object.prototype.hasOwnProperty.call(NAMED_ENTITIES, body) ? NAMED_ENTITIES[body] : whole;
+  });
+}
 var RequestResolver = class {
   #req;
   #cookies;
@@ -282,6 +321,8 @@ var RequestResolver = class {
         } catch {
           return value;
         }
+      case "htmlentitydecode":
+        return decodeHtmlEntities(String(value));
       case "intval":
         return parseInt(String(value), 10) || 0;
       case "getArrayValues":
@@ -2198,25 +2239,428 @@ function toEnvelope(value) {
   return null;
 }
 
-// src/protect/rules/validate.js
-var LIMITS = {
+// src/protect/rules/contract.js
+var SOURCES = Object.freeze({
+  raw: Object.freeze({ keyed: false }),
+  all: Object.freeze({ keyed: false }),
+  false: Object.freeze({ keyed: false }),
+  rules: Object.freeze({ keyed: false, group: true }),
+  get: Object.freeze({ keyed: true, keys: "any", wildcard: true }),
+  post: Object.freeze({ keyed: true, keys: "any", wildcard: true }),
+  request: Object.freeze({ keyed: true, keys: "any", wildcard: true }),
+  cookie: Object.freeze({ keyed: true, keys: "any", wildcard: true }),
+  // A bare `files.<name>` resolves to the filename; an optional trailing attribute selects another part
+  // of the upload. Optional, not required — filename-scoped rules use the bare form.
+  files: Object.freeze({
+    keyed: true,
+    keys: "any",
+    wildcard: true,
+    optional_key_suffixes: Object.freeze(["content", "filename", "type"])
+  }),
+  server: Object.freeze({
+    keyed: true,
+    keys: Object.freeze([
+      "REQUEST_URI",
+      "REQUEST_METHOD",
+      "HTTP_USER_AGENT",
+      "HTTP_REFERER",
+      "HTTP_HOST",
+      "REMOTE_ADDR",
+      "ip",
+      "CONTENT_TYPE",
+      "CONTENT_LENGTH"
+    ]),
+    key_prefixes: Object.freeze(["HTTP_"])
+  }),
+  response: Object.freeze({
+    keyed: true,
+    keys: Object.freeze(["status", "body", "headers"]),
+    key_prefixes: Object.freeze(["header."])
+  }),
+  egress: Object.freeze({ keyed: true, keys: Object.freeze(["url", "host", "method"]) })
+});
+var MATCH_TYPES = Object.freeze([
+  "array_in_array",
+  "array_key_value",
+  "contains",
+  "cors_reflected",
+  "cross_origin",
+  "ctype_alnum",
+  "ctype_digit",
+  "ctype_special",
+  "equals",
+  "equals_strict",
+  "hostname",
+  "in_array",
+  "inline_js_xss",
+  "inline_xss",
+  "internal_host",
+  "is_numeric",
+  "isset",
+  "less_than",
+  "more_than",
+  "not_contains",
+  "not_in_array",
+  "off_origin",
+  "quotes",
+  "regex",
+  "stripos"
+]);
+var PARAMETERLESS_MATCH_TYPES = Object.freeze(["cross_origin", "off_origin", "cors_reflected"]);
+var OPERANDLESS_MATCH_TYPES = Object.freeze([
+  "isset",
+  "quotes",
+  "is_numeric",
+  "ctype_alnum",
+  "ctype_digit",
+  "ctype_special",
+  "inline_xss",
+  "inline_js_xss",
+  "internal_host",
+  "cross_origin",
+  "off_origin",
+  "cors_reflected"
+]);
+var OPERAND_SHAPES = Object.freeze([
+  "non-empty-string",
+  "regex-literal",
+  "string-or-string-list",
+  "scalar",
+  "string",
+  "numeric",
+  "scalar-or-non-empty-list",
+  "non-empty-list",
+  "object",
+  "non-empty-object",
+  "non-empty-string-list",
+  "header-name-map",
+  "header-name-list",
+  "cookie-flags"
+]);
+var COOKIE_FLAGS = Object.freeze(["httpOnly", "secure", "sameSite"]);
+var SAME_SITE_VALUES = Object.freeze(["Strict", "Lax", "None"]);
+var HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var REGEX_LITERAL = /^\/(.+?)\/([gimsuy]*)$/s;
+var MATCH_OPERANDS = Object.freeze({
+  array_key_value: Object.freeze({
+    required: Object.freeze(["key", "match"]),
+    shapes: Object.freeze({ key: "string-or-string-list", match: "object" })
+  }),
+  regex: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "regex-literal" }) }),
+  contains: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "non-empty-string" }) }),
+  stripos: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "non-empty-string" }) }),
+  not_contains: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "non-empty-string" }) }),
+  // A hostname is compared to `new URL(value).hostname`, so an empty one only ever equals the empty
+  // hostname of an opaque-scheme URL (`file:`, `mailto:`, `data:`) — never a host, and a false positive
+  // on those. The other three are the list-membership family: an empty list makes `in_array` and
+  // `array_in_array` inert and `not_in_array` true for every value.
+  hostname: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "non-empty-string" }) }),
+  in_array: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "scalar-or-non-empty-list" }) }),
+  not_in_array: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "scalar-or-non-empty-list" }) }),
+  array_in_array: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "non-empty-list" }) }),
+  // The comparison family. `equals` coerces, so any scalar can match. `equals_strict` does not, and its
+  // subject is always a string by the time it is compared — so a number operand is unconditionally
+  // inert, which is the trap the engine's own note about `'1' !== 1` describes.
+  equals: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "scalar" }) }),
+  equals_strict: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "string" }) }),
+  less_than: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "numeric" }) }),
+  more_than: Object.freeze({ required: Object.freeze(["value"]), shapes: Object.freeze({ value: "numeric" }) })
+});
+function operandShapeProblem(shape, value) {
+  const isFilledString = (v) => typeof v === "string" && v.trim() !== "";
+  const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+  const isHeaderName = (v) => typeof v === "string" && HEADER_NAME.test(v);
+  switch (shape) {
+    case "non-empty-string":
+      return isFilledString(value) ? null : "must be a non-empty string";
+    case "regex-literal":
+      if (!isFilledString(value)) return "must be a non-empty string";
+      return REGEX_LITERAL.test(value) ? null : "must be a delimited pattern, as in /pattern/i";
+    case "string-or-string-list":
+      if (isFilledString(value)) return null;
+      if (Array.isArray(value) && value.length > 0 && value.every(isFilledString)) return null;
+      return "must be a non-empty string, or a non-empty list of them";
+    case "scalar":
+      return isScalar(value) ? null : "must be a string, number or boolean";
+    case "string":
+      return typeof value === "string" ? null : "must be a string (this comparison is type-strict)";
+    case "numeric":
+      return isScalar(value) && Number.isFinite(Number(value)) ? null : "must be a number";
+    case "scalar-or-non-empty-list":
+      if (isScalar(value)) return null;
+      if (Array.isArray(value) && value.length > 0 && value.every(isScalar)) return null;
+      return "must be a scalar, or a non-empty list of them";
+    case "non-empty-list":
+      return Array.isArray(value) && value.length > 0 && value.every(isScalar) ? null : "must be a non-empty list of scalars";
+    case "header-name-map": {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) return "must be an object";
+      const names = Object.keys(value);
+      if (names.length === 0) return "must be an object with at least one entry";
+      const bad = names.find((name) => !isHeaderName(name));
+      return bad === void 0 ? null : `names an invalid HTTP header, ${JSON.stringify(bad)}`;
+    }
+    case "header-name-list": {
+      if (!Array.isArray(value) || value.length === 0) return "must be a non-empty list of HTTP header names";
+      const bad = value.find((name) => !isHeaderName(name));
+      return bad === void 0 ? null : `names an invalid HTTP header, ${JSON.stringify(bad)}`;
+    }
+    case "cookie-flags": {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) return "must be an object";
+      const unknown = Object.keys(value).filter((key) => !COOKIE_FLAGS.includes(key));
+      if (unknown.length > 0) return `has no flag named ${unknown.map((k) => JSON.stringify(k)).join(", ")}`;
+      for (const flag of ["httpOnly", "secure"]) {
+        if (value[flag] !== void 0 && typeof value[flag] !== "boolean") {
+          return `flag "${flag}" must be true or false`;
+        }
+      }
+      const sameSite = value.sameSite;
+      const sameSiteOff = sameSite === false;
+      if (sameSite !== void 0 && !sameSiteOff) {
+        if (typeof sameSite !== "string" || !SAME_SITE_VALUES.some((v) => v.toLowerCase() === sameSite.toLowerCase())) {
+          return `flag "sameSite" must be false, or one of ${SAME_SITE_VALUES.join(", ")}`;
+        }
+      }
+      if (value.httpOnly === false && value.secure === false && sameSiteOff) {
+        return "turns off every flag, so it would harden nothing";
+      }
+      return null;
+    }
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value) ? null : "must be an object";
+    case "non-empty-object":
+      return value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0 ? null : "must be an object with at least one entry";
+    case "non-empty-string-list":
+      return Array.isArray(value) && value.length > 0 && value.every(isFilledString) ? null : "must be a non-empty list of non-empty strings";
+    default:
+      return null;
+  }
+}
+var MUTATIONS = Object.freeze([
+  "base64_decode",
+  "getArrayValues",
+  "htmlentitydecode",
+  "intval",
+  "json_decode",
+  "json_encode",
+  "urldecode"
+]);
+var PHASES = Object.freeze(["request", "response", "egress"]);
+var ACTIONS = Object.freeze([
+  "block",
+  "redact",
+  "encode",
+  "set-header",
+  "remove-header",
+  "harden-cookie"
+]);
+var WHEN_KEYS = Object.freeze(["path", "method"]);
+var RULE_PROPERTIES = Object.freeze([
+  "id",
+  "rule_id",
+  "title",
+  "category",
+  "phase",
+  "action",
+  "rule_v2",
+  "when",
+  "message",
+  "enforcement",
+  "source_revision",
+  "prefilter",
+  "max_bytes",
+  "bypass_limit",
+  "set_headers",
+  "remove_headers",
+  "cookie_flags",
+  "ensure"
+]);
+var ACTION_PROPERTIES = Object.freeze({
+  block: Object.freeze({ required: Object.freeze([]), defaulted: Object.freeze([]), phases: Object.freeze(["request", "response", "egress"]) }),
+  redact: Object.freeze({ required: Object.freeze([]), defaulted: Object.freeze([]), phases: Object.freeze(["response"]) }),
+  encode: Object.freeze({ required: Object.freeze([]), defaulted: Object.freeze([]), phases: Object.freeze(["response"]) }),
+  "set-header": Object.freeze({
+    required: Object.freeze(["set_headers"]),
+    defaulted: Object.freeze(["ensure"]),
+    phases: Object.freeze(["response"]),
+    shapes: Object.freeze({ set_headers: "header-name-map" })
+  }),
+  "remove-header": Object.freeze({
+    required: Object.freeze(["remove_headers"]),
+    defaulted: Object.freeze([]),
+    phases: Object.freeze(["response"]),
+    shapes: Object.freeze({ remove_headers: "header-name-list" })
+  }),
+  "harden-cookie": Object.freeze({
+    required: Object.freeze([]),
+    defaulted: Object.freeze(["cookie_flags"]),
+    phases: Object.freeze(["response"]),
+    shapes: Object.freeze({ cookie_flags: "cookie-flags" })
+  })
+});
+var LIMITS = Object.freeze({
   maxRules: 5e3,
   maxWhitelists: 2e3,
   maxConditionsPerRule: 250,
   maxNestingDepth: 12,
   maxRegexLength: 1e3,
   maxValueLength: 8192
-};
-var PHASES = /* @__PURE__ */ new Set(["request", "response", "egress"]);
-var ACTIONS = /* @__PURE__ */ new Set(["block", "redact", "encode", "set-header", "remove-header", "harden-cookie"]);
+});
+var GROUP_PARAMETER = "rules";
+function isGroup(condition) {
+  return condition?.parameter === GROUP_PARAMETER && Array.isArray(condition?.rules);
+}
+function conditionShapeProblem(condition) {
+  if (!condition || typeof condition !== "object") return "condition is not an object";
+  const named = condition.parameter === GROUP_PARAMETER;
+  const nested = Array.isArray(condition.rules);
+  if (named && !nested) {
+    return `parameter "${GROUP_PARAMETER}" is a group and needs a "rules" array`;
+  }
+  if (nested && !named) {
+    return `condition carries nested rules but its parameter is ${JSON.stringify(condition.parameter)}; a group must be {"parameter":"${GROUP_PARAMETER}"}`;
+  }
+  if (named && nested) {
+    if (condition.match !== void 0) return "a group carries no match of its own; the engine ignores it";
+    if (condition.mutations !== void 0) return "a group carries no mutations of its own; the engine ignores them";
+    if (condition.rules.length === 0) return "group has no conditions (would never match)";
+  }
+  return null;
+}
+function parameterProblem(parameter) {
+  if (parameter === void 0 || parameter === null) return null;
+  if (Array.isArray(parameter)) {
+    if (parameter.length === 0) return "parameter list is empty";
+    for (const member of parameter) {
+      const problem = parameterProblem(member);
+      if (problem !== null) return problem;
+    }
+    return null;
+  }
+  if (typeof parameter !== "string" || parameter === "") return "parameter must be a non-empty string";
+  if (parameter === GROUP_PARAMETER) {
+    return `"${GROUP_PARAMETER}" is the group source and is only valid as a whole group, not as a parameter`;
+  }
+  const dot = parameter.indexOf(".");
+  const name = dot === -1 ? parameter : parameter.slice(0, dot);
+  const source = SOURCES[name];
+  if (source === void 0) return `unknown parameter source "${name}"`;
+  if (dot === -1) {
+    return source.keyed === true ? `source "${name}" needs a key, e.g. "${name}.fieldname"` : null;
+  }
+  if (source.keyed !== true) return `source "${name}" takes no key`;
+  const key = parameter.slice(dot + 1);
+  if (key === "") return `source "${name}" needs a key after the dot`;
+  return keyProblem(name, source, key);
+}
+function keyProblem(name, source, key) {
+  if (key.endsWith("*") && source.wildcard !== true) {
+    return `"${name}" does not fan out over a wildcard key`;
+  }
+  const bare = key.endsWith("*") ? key.slice(0, -1) : key;
+  if (source.keys === "any") return null;
+  if (Array.isArray(source.keys) && source.keys.includes(bare)) return null;
+  for (const prefix of source.key_prefixes ?? []) {
+    if (bare.startsWith(prefix) && bare.length > prefix.length) return null;
+  }
+  const accepted = [
+    ...Array.isArray(source.keys) ? source.keys : [],
+    ...(source.key_prefixes ?? []).map((p) => `${p}\u2026`)
+  ].join(", ");
+  return `"${name}" has no key "${key}" (expected one of: ${accepted})`;
+}
+function matchProblem(match, parameter) {
+  if (!match || typeof match !== "object") return "condition has no match object";
+  if (typeof match.type !== "string" || match.type === "") return "match.type must be a non-empty string";
+  if (!MATCH_TYPES.includes(match.type)) return `unknown match type "${match.type}"`;
+  const parameterless = PARAMETERLESS_MATCH_TYPES.includes(match.type);
+  if (!parameterless && (parameter === void 0 || parameter === null)) {
+    return `match type "${match.type}" needs a parameter`;
+  }
+  if (parameterless && parameter !== void 0 && parameter !== null) {
+    return `match type "${match.type}" reads the whole request and takes no parameter`;
+  }
+  const operands = MATCH_OPERANDS[match.type];
+  if (operands) {
+    for (const required of operands.required) {
+      if (match[required] === void 0 || match[required] === null) {
+        return `match type "${match.type}" needs "${required}"`;
+      }
+    }
+    for (const [operand, shape] of Object.entries(operands.shapes ?? {})) {
+      if (match[operand] === void 0) continue;
+      const problem = operandShapeProblem(shape, match[operand]);
+      if (problem) return `match type "${match.type}" operand "${operand}" ${problem}`;
+    }
+  } else if (!OPERANDLESS_MATCH_TYPES.includes(match.type) && match.value === void 0) {
+    return `match type "${match.type}" needs a value`;
+  }
+  return null;
+}
+function mutationsProblem(mutations) {
+  if (mutations === void 0 || mutations === null) return null;
+  if (!Array.isArray(mutations)) return "mutations must be an array";
+  for (const mutation of mutations) {
+    if (typeof mutation !== "string" || !MUTATIONS.includes(mutation)) {
+      return `unknown mutation "${String(mutation)}" \u2014 applied as a no-op, so the condition would test the untransformed value`;
+    }
+  }
+  return null;
+}
+function whenProblem(when) {
+  if (when === void 0 || when === null) return null;
+  if (typeof when !== "object" || Array.isArray(when)) return "when must be an object";
+  const keys = Object.keys(when);
+  if (keys.length === 0) return "when is empty \u2014 remove it, or name a path or method";
+  const unknown = keys.filter((key) => !WHEN_KEYS.includes(key));
+  if (unknown.length > 0) {
+    return `when names no supported key (${unknown.join(", ")}) \u2014 the engine understands ${WHEN_KEYS.join(" and ")}, and an unrecognised scope is ignored, so the rule would apply to every request`;
+  }
+  if ("path" in when && !isNonEmptyString(when.path)) {
+    return "when.path must be a non-empty string";
+  }
+  if ("method" in when) {
+    const methods = Array.isArray(when.method) ? when.method : [when.method];
+    if (methods.length === 0) return "when.method is an empty list, so the rule would match no method";
+    if (!methods.every(isNonEmptyString)) return "when.method must be a non-empty string, or a list of them";
+  }
+  return null;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function actionProblem(action, rule) {
+  if (action === void 0 || action === null) return null;
+  if (!ACTIONS.includes(action)) return `unknown action "${action}"`;
+  const spec = ACTION_PROPERTIES[action];
+  for (const required of spec?.required ?? []) {
+    if (rule?.[required] === void 0 || rule?.[required] === null) {
+      return `action "${action}" needs "${required}"`;
+    }
+  }
+  for (const [property, shape] of Object.entries(spec?.shapes ?? {})) {
+    if (rule?.[property] === void 0 || rule?.[property] === null) continue;
+    const problem = operandShapeProblem(shape, rule[property]);
+    if (problem) return `action "${action}" property "${property}" ${problem}`;
+  }
+  const phase = rule?.phase ?? "request";
+  if (spec !== void 0 && !spec.phases.includes(phase)) {
+    return `action "${action}" is carried out on the ${spec.phases.join("/")} phase; on "${phase}" the rule blocks instead`;
+  }
+  return null;
+}
+
+// src/protect/rules/validate.js
+var LIMITS2 = LIMITS;
+var PHASES2 = new Set(PHASES);
+var ACTIONS2 = new Set(ACTIONS);
 function validateBundle(bundle, opts = {}) {
   const rejected = [];
   const inFirewall = Array.isArray(bundle?.firewall) ? bundle.firewall : [];
   const inWhitelists = Array.isArray(bundle?.whitelists) ? bundle.whitelists : [];
   const firewall = [];
   for (const rule of inFirewall) {
-    if (firewall.length >= LIMITS.maxRules) {
-      rejected.push({ id: idOf(rule), reason: `bundle exceeds maxRules (${LIMITS.maxRules})` });
+    if (firewall.length >= LIMITS2.maxRules) {
+      rejected.push({ id: idOf(rule), reason: `bundle exceeds maxRules (${LIMITS2.maxRules})` });
       continue;
     }
     const reason = ruleProblem(rule);
@@ -2225,8 +2669,8 @@ function validateBundle(bundle, opts = {}) {
   }
   const whitelists = [];
   for (const wl of inWhitelists) {
-    if (whitelists.length >= LIMITS.maxWhitelists) {
-      rejected.push({ id: idOf(wl), reason: `bundle exceeds maxWhitelists (${LIMITS.maxWhitelists})` });
+    if (whitelists.length >= LIMITS2.maxWhitelists) {
+      rejected.push({ id: idOf(wl), reason: `bundle exceeds maxWhitelists (${LIMITS2.maxWhitelists})` });
       continue;
     }
     if (!opts.allowGlobalWhitelists && wl && Array.isArray(wl.rule_v2) && !wl.rule_id) {
@@ -2248,8 +2692,11 @@ function idOf(rule) {
 }
 function ruleProblem(rule) {
   if (!rule || typeof rule !== "object") return "not an object";
-  if (rule.phase !== void 0 && !PHASES.has(rule.phase)) return `unknown phase "${rule.phase}"`;
-  if (rule.action !== void 0 && !ACTIONS.has(rule.action)) return `unknown action "${rule.action}"`;
+  if (rule.phase !== void 0 && !PHASES2.has(rule.phase)) return `unknown phase "${rule.phase}"`;
+  const actionReason = actionProblem(rule.action, rule);
+  if (actionReason) return actionReason;
+  const scopeReason = whenProblem(rule.when);
+  if (scopeReason) return scopeReason;
   const capOverride = rule.max_bytes;
   if (capOverride !== void 0 && !(Number(capOverride) > 0)) return "max_bytes must be a positive number";
   return conditionsProblem(rule.rule_v2);
@@ -2257,28 +2704,33 @@ function ruleProblem(rule) {
 function conditionsProblem(conditions, depth = 0) {
   if (!Array.isArray(conditions)) return "rule_v2 must be an array of conditions";
   if (conditions.length === 0) return "rule_v2 is empty (would never match)";
-  if (depth > LIMITS.maxNestingDepth) return `nesting deeper than ${LIMITS.maxNestingDepth}`;
-  if (conditions.length > LIMITS.maxConditionsPerRule) {
-    return `more than ${LIMITS.maxConditionsPerRule} conditions`;
+  if (depth > LIMITS2.maxNestingDepth) return `nesting deeper than ${LIMITS2.maxNestingDepth}`;
+  if (conditions.length > LIMITS2.maxConditionsPerRule) {
+    return `more than ${LIMITS2.maxConditionsPerRule} conditions`;
   }
   for (const c of conditions) {
-    if (!c || typeof c !== "object") return "condition is not an object";
-    if (Array.isArray(c.rules)) {
+    const shapeReason = conditionShapeProblem(c);
+    if (shapeReason) return shapeReason;
+    if (isGroup(c)) {
       const nested = conditionsProblem(c.rules, depth + 1);
       if (nested) return nested;
       continue;
     }
+    const parameterReason = parameterProblem(c.parameter);
+    if (parameterReason) return parameterReason;
+    const mutationReason = mutationsProblem(c.mutations);
+    if (mutationReason) return mutationReason;
+    const matchReason = matchProblem(c.match, c.parameter);
+    if (matchReason) return matchReason;
     const m = c.match;
-    if (!m || typeof m !== "object") return "condition has no match object";
-    if (typeof m.type !== "string" || m.type === "") return "match.type must be a non-empty string";
     if (m.type === "regex") {
       if (typeof m.value !== "string") return "regex match.value must be a string";
-      if (m.value.length > LIMITS.maxRegexLength) return `regex longer than ${LIMITS.maxRegexLength} chars`;
-    } else if (typeof m.value === "string" && m.value.length > LIMITS.maxValueLength) {
-      return `match.value longer than ${LIMITS.maxValueLength} chars`;
+      if (m.value.length > LIMITS2.maxRegexLength) return `regex longer than ${LIMITS2.maxRegexLength} chars`;
+    } else if (typeof m.value === "string" && m.value.length > LIMITS2.maxValueLength) {
+      return `match.value longer than ${LIMITS2.maxValueLength} chars`;
     }
     if (m.match) {
-      const nested = conditionsProblem([{ match: m.match }], depth + 1);
+      const nested = conditionsProblem([{ parameter: c.parameter, match: m.match }], depth + 1);
       if (nested) return nested;
     }
   }
@@ -2306,64 +2758,67 @@ function reportRejections(rejected, options, label) {
     `${label}: rejected the entire update because ${rejected.length} rule(s) failed validation \u2014 keeping the previous ruleset and NOT caching this response: ${sample}${rejected.length > 3 ? ", \u2026" : ""}`
   ), "onError");
 }
+function fromSource(bundle, reason) {
+  return reason === void 0 ? { ...bundle, source: { ok: true } } : { ...bundle, source: { ok: false, reason } };
+}
 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, reportsDetections: options.reportDetections === true });
     const res = await client.getRules();
-    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle, options);
+    if (res.success && res.notModified && prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options));
     if (res.success && !res.notModified) {
       const rejected = liveUpdateRejections(res, options);
       if (rejected.length > 0) {
         reportRejections(rejected, options, "rule update rejected");
-        if (prior?.bundle) return normalizeBundle(prior.bundle, options);
-        if (options.rules) return normalizeBundle(options.rules, options);
-        return emptyBundle();
+        if (prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options), "update rejected");
+        if (options.rules) return fromSource(normalizeBundle(options.rules, options), "update rejected");
+        return fromSource(emptyBundle(), "update rejected");
       }
       const bundle = normalizeBundle(res, options);
       await store.write({ bundle, etag: res.etag ?? null });
-      return bundle;
+      return fromSource(bundle);
     }
     if (prior?.bundle) {
       notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`), "onError");
-      return normalizeBundle(prior.bundle, options);
+      return fromSource(normalizeBundle(prior.bundle, options), 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 normalizeBundle(options.rules, options);
+      return fromSource(normalizeBundle(options.rules, options), 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 emptyBundle();
+    return fromSource(emptyBundle(), res.error ?? "no usable response");
   }
   if (options.token) {
     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 normalizeBundle(prior.bundle, options);
+    if (res.success && res.notModified && prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options));
     if (res.success && !res.notModified) {
       const rejected = liveUpdateRejections(res, options);
       if (rejected.length > 0) {
         reportRejections(rejected, options, "rule update rejected");
-        if (prior?.bundle) return normalizeBundle(prior.bundle, options);
-        if (options.rules) return normalizeBundle(options.rules, options);
-        return emptyBundle();
+        if (prior?.bundle) return fromSource(normalizeBundle(prior.bundle, options), "update rejected");
+        if (options.rules) return fromSource(normalizeBundle(options.rules, options), "update rejected");
+        return fromSource(emptyBundle(), "update rejected");
       }
       const bundle = normalizeBundle(res, options);
       await store.write({ bundle, etag: res.etag ?? null });
-      return bundle;
+      return fromSource(bundle);
     }
     if (prior?.bundle) {
       notify(options.onError, new Error(`rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`), "onError");
-      return normalizeBundle(prior.bundle, options);
+      return fromSource(normalizeBundle(prior.bundle, options), 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 emptyBundle();
+    return fromSource(emptyBundle(), res.error ?? "no usable response");
   }
   if (options.rules) {
-    return normalizeBundle(options.rules, options);
+    return fromSource(normalizeBundle(options.rules, options));
   }
-  return emptyBundle();
+  return fromSource(emptyBundle());
 }
 function normalizeBundle(b, options = {}) {
   const enforcement = b?.enforcement ?? b?.mode;
@@ -2416,8 +2871,9 @@ function startRefresh(tick, { refreshMs, onError } = {}) {
   const run = async () => {
     if (stopped) return;
     try {
-      await tick();
-      failures = 0;
+      const status = await tick();
+      if (status && status.ok === false) failures++;
+      else failures = 0;
     } catch (err) {
       failures++;
       notify(onError, err, "onError");
@@ -2444,7 +2900,8 @@ function makeRefreshHandler(tick, secret) {
     if (provided !== secret) return new Response("forbidden", { status: 403 });
     let refreshed = true;
     try {
-      await tick();
+      const status = await tick();
+      if (status && status.ok === false) refreshed = false;
     } catch {
       refreshed = false;
     }
@@ -2472,6 +2929,12 @@ function ruleParameters(rule) {
   walk(rule?.rule_v2);
   return [...out];
 }
+function revisionOf(rule) {
+  const revision = rule?.source_revision;
+  if (typeof revision === "string" && revision !== "") return revision;
+  if (typeof revision === "number" && Number.isFinite(revision)) return String(revision);
+  return null;
+}
 function routeOf(path) {
   if (typeof path !== "string" || path === "") return null;
   const cut = path.search(/[?#]/);
@@ -2480,16 +2943,30 @@ function routeOf(path) {
 function createDetectionReporter(opts) {
   const siteUuid = opts.siteUuid ?? process.env?.PATCHSTACK_SITE_UUID;
   if (!siteUuid) {
-    return { record() {
-    }, flush() {
-    }, stop() {
-    }, dropped: () => 0 };
+    return {
+      record() {
+      },
+      flush() {
+      },
+      stop() {
+      },
+      setRulesEtag() {
+      },
+      dropped: () => 0,
+      health: () => ({ sent: 0, delivered: 0, failed: 0, dropped: 0, lastDeliveredAt: null })
+    };
   }
   const configured = opts.baseUrl ?? process.env?.PATCHSTACK_PULSE_RULES_URL;
   const baseUrl = typeof configured === "string" && isSafeOrigin(configured) ? configured.replace(/\/$/, "") : DEFAULT_BASE_URL3;
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   const flushMs = Number.isFinite(opts.flushMs) && opts.flushMs > 0 ? opts.flushMs : DEFAULT_FLUSH_MS;
   const maxQueue = Number.isFinite(opts.maxQueue) && opts.maxQueue > 0 ? opts.maxQueue : MAX_QUEUE;
+  let rulesEtag = opts.rulesEtag ?? null;
+  let sent = 0;
+  let delivered = 0;
+  let failed = 0;
+  let droppedTotal = 0;
+  let lastDeliveredAt = null;
   let queue = [];
   let timer = null;
   let stopped = false;
@@ -2503,6 +2980,8 @@ function createDetectionReporter(opts) {
     const batch = queue.splice(0, MAX_BATCH);
     const droppedWith = dropped;
     dropped = 0;
+    droppedTotal += droppedWith;
+    sent += batch.length;
     void (async () => {
       try {
         const res = await fetchImpl(`${baseUrl}/detections/${encodeURIComponent(siteUuid)}`, {
@@ -2511,15 +2990,22 @@ function createDetectionReporter(opts) {
             "Content-Type": "application/json",
             Accept: "application/json",
             "User-Agent": "@patchstack/connect",
-            // Same credential path as the rules fetch, and unauthenticated when none resolves: the
-            // server accepts the UUID, and reporting must never hinge on getting a token.
+            // Same credential path as the rules fetch. The detections endpoint is site-addressed and
+            // requires a verified, site-bound token, so a batch sent without one is refused — which is
+            // why the runtime does not build a reporter when no credential resolves, rather than
+            // posting into a 401.
             ...await pulseAuthHeader({ pulseAuth: opts.pulseAuth, endpoint: baseUrl }, fetchImpl)
           },
           body: JSON.stringify({ detections: batch, dropped: droppedWith })
         });
-        if (res && typeof res.then === "function") res.catch(() => {
-        });
+        if (res && res.ok) {
+          delivered += batch.length;
+          lastDeliveredAt = (/* @__PURE__ */ new Date()).toISOString();
+        } else {
+          failed += batch.length;
+        }
       } catch {
+        failed += batch.length;
       }
     })();
   };
@@ -2548,7 +3034,12 @@ function createDetectionReporter(opts) {
         // The state this detection was handled under, which is the whole point: `false` is a rule that
         // saw traffic it would have stopped.
         enforced: detection.mode === "block",
-        rules_etag: opts.rulesEtag ?? null,
+        rules_etag: rulesEtag,
+        // The revision of THIS rule, as the bundle delivered it. The bundle identity above answers "which
+        // bundle", which changes whenever anything in it changes — so it cannot say whether the counts for
+        // one rule describe the document that rule has now. Passed through untouched, and null when the
+        // bundle carried none.
+        rule_revision: revisionOf(detection.rule),
         detected_at: (/* @__PURE__ */ new Date()).toISOString()
       });
       if (queue.length >= MAX_BATCH) {
@@ -2562,7 +3053,24 @@ function createDetectionReporter(opts) {
       stopped = true;
       flush();
     },
-    dropped: () => dropped
+    /**
+     * Point later events at the bundle now running. Called after an ACCEPTED swap only — a rejected
+     * or failed refresh keeps the previous rules, so it must keep the previous identity too.
+     *
+     * Already-queued events are not rewritten: the stamp is taken when an event is recorded, which is
+     * the only moment the two are known to agree.
+     *
+     * @param {string | null | undefined} next
+     */
+    setRulesEtag(next) {
+      rulesEtag = next ?? null;
+    },
+    dropped: () => dropped,
+    /**
+     * Delivery health, counted in events: attempted, acknowledged, refused or unreachable, and dropped
+     * for queue pressure — plus when a batch was last acknowledged. No request data of any kind.
+     */
+    health: () => ({ sent, delivered, failed, dropped: droppedTotal + dropped, lastDeliveredAt })
   };
 }
 
@@ -2827,22 +3335,32 @@ async function createProtection(options = {}) {
   const bootTimeoutMs = Number(options.bootTimeoutMs) > 0 ? Number(options.bootTimeoutMs) : 5e3;
   const pulseAuth = await resolvePulseAuth(options);
   if (options.siteUuid && !pulseAuth) {
-    const message = "Patchstack: no API credential resolved for site " + options.siteUuid + ". Rule updates may be rejected and this guard would keep running on its cached rules. Set PATCHSTACK_API_KEY (or pass { pulseAuth }) \u2014 required on runtimes without a filesystem.";
+    const message = "Patchstack: no API credential resolved for site " + options.siteUuid + ". Rule updates will be rejected and this guard would keep running on its cached rules. Set PATCHSTACK_API_KEY (or pass { pulseAuth }) \u2014 required on runtimes without a filesystem.";
     notify(onError, new Error(message), "onError");
     console.warn(message);
   }
   const bundle = await resolveRules(options, store, { timeoutMs: bootTimeoutMs, pulseAuth });
+  let detectionReporting = "off";
   if (options.reportDetections === true && options.siteUuid && telemetryEnabled()) {
-    detections = createDetectionReporter({
-      siteUuid: options.siteUuid,
-      baseUrl: options.pulseRulesUrl,
-      pulseAuth,
-      // The bundle the guard is actually running, so a hit can be attributed to the rules that produced
-      // it rather than to whatever is current when the report is read.
-      rulesEtag: (await store.read())?.etag ?? null,
-      fetchImpl: options.fetchImpl,
-      flushMs: options.detectionFlushMs
-    });
+    if (!pulseAuth) {
+      detectionReporting = "unavailable-no-credential";
+      const message = "Patchstack: detection reporting is enabled for site " + options.siteUuid + " but no API credential resolved, so no report could be delivered. Reporting is off.";
+      notify(onError, new Error(message), "onError");
+      console.warn(message);
+    } else {
+      detectionReporting = "on";
+      detections = createDetectionReporter({
+        siteUuid: options.siteUuid,
+        baseUrl: options.pulseRulesUrl,
+        pulseAuth,
+        // The bundle the guard is actually running, so a hit can be attributed to the rules that produced
+        // it rather than to whatever is current when the report is read. Kept current across refreshes —
+        // see the refresh tick below.
+        rulesEtag: (await store.read())?.etag ?? null,
+        fetchImpl: options.fetchImpl,
+        flushMs: options.detectionFlushMs
+      });
+    }
   }
   let mode = resolveMode(options, bundle);
   let requestRules;
@@ -3176,11 +3694,17 @@ async function createProtection(options = {}) {
         );
       };
     },
-    // Node / Connect middleware — buffers the body itself (request phase).
+    // Node / Connect middleware — buffers the body itself (request phase). Register it BEFORE any body
+    // parser: it reads the request stream, and exposes what it read as `req.body` so a parser is not
+    // also needed. (`.express()` is the other way round — it reads a body somebody else parsed.)
     // Pass { screenResponses: true } to also screen the outgoing response (buffers it).
     node(nodeOptions = {}) {
       const maxBytes = nodeOptions.maxBodyBytes ?? 1024 * 1024;
       return (req, res, next) => {
+        if (req.readableEnded || req.body !== void 0) {
+          screenNodeRequest(req, res, next, "", req.body);
+          return;
+        }
         const chunks = [];
         let size = 0;
         let overflow = false;
@@ -3198,38 +3722,41 @@ async function createProtection(options = {}) {
         });
         req.on("end", () => {
           if (overflow) recordSkip("request", "body-cap", { bytes: size, limit: maxBytes });
-          const rawBody = overflow ? "" : Buffer.concat(chunks).toString("utf8");
-          let shaped;
-          let result;
-          try {
-            shaped = fromNodeRequest(req, rawBody);
-            result = engine.evaluate(shaped);
-          } catch (err) {
-            notify(onError, err, "onError");
-            return next();
-          }
-          decide(
-            "request",
-            result,
-            () => {
-              res.statusCode = 403;
-              if (isDocumentNavigation((n) => req.headers?.[n])) {
-                res.setHeader("content-type", "text/html; charset=utf-8");
-                res.end(renderBlockPage({ url: req.url || "/", code: result?.rule?.id }));
-              } else {
-                res.setHeader("content-type", "application/json");
-                res.end(JSON.stringify(blockBody(result)));
-              }
-            },
-            () => {
-              if (req.body === void 0) req.body = shaped.body;
-              if (nodeOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req));
-              next();
-            },
-            nodeRequestMeta(req)
-          );
+          screenNodeRequest(req, res, next, overflow ? "" : Buffer.concat(chunks).toString("utf8"));
         });
       };
+      function screenNodeRequest(req, res, next, rawBody, parsedBody) {
+        let shaped;
+        let result;
+        try {
+          shaped = fromNodeRequest(req, rawBody);
+          if (parsedBody !== void 0 && parsedBody !== null) shaped.body = parsedBody;
+          result = engine.evaluate(shaped);
+        } catch (err) {
+          notify(onError, err, "onError");
+          return next();
+        }
+        decide(
+          "request",
+          result,
+          () => {
+            res.statusCode = 403;
+            if (isDocumentNavigation((n) => req.headers?.[n])) {
+              res.setHeader("content-type", "text/html; charset=utf-8");
+              res.end(renderBlockPage({ url: req.url || "/", code: result?.rule?.id }));
+            } else {
+              res.setHeader("content-type", "application/json");
+              res.end(JSON.stringify(blockBody(result)));
+            }
+          },
+          () => {
+            if (req.body === void 0) req.body = shaped.body;
+            if (nodeOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req));
+            next();
+          },
+          nodeRequestMeta(req)
+        );
+      }
     }
   };
   if (options.egress) {
@@ -3266,24 +3793,22 @@ async function createProtection(options = {}) {
     const next = await resolveRules(options, store, { timeoutMs: options.refreshTimeoutMs, pulseAuth });
     mode = resolveMode(options, next);
     applyBundle(next);
+    if (detections) detections.setRulesEtag((await store.read())?.etag ?? null);
+    return next.source ?? { ok: true };
   };
   if (live) {
     protection.refresh = () => runRefreshTick();
     protection.refreshHandler = () => makeRefreshHandler(runRefreshTick, refreshSecret);
   }
-  if (options.refreshMs > 0 && live) {
-    const loop = startRefresh(runRefreshTick, { refreshMs: options.refreshMs, onError });
-    protection.stopRefresh = () => {
-      loop.stop();
-      firewallLog?.stop();
-      detections?.stop();
-    };
-  } else if (firewallLog) {
-    protection.stopRefresh = () => {
-      firewallLog.stop();
-      detections?.stop();
-    };
-  }
+  const loop = options.refreshMs > 0 && live ? startRefresh(runRefreshTick, { refreshMs: options.refreshMs, onError }) : null;
+  protection.stop = () => {
+    loop?.stop();
+    firewallLog?.stop();
+    detections?.stop();
+  };
+  protection.stopRefresh = protection.stop;
+  protection.detectionReporting = detectionReporting;
+  if (detections) protection.detectionHealth = () => detections.health();
   return protection;
 }
 function resolveMode(options, bundle) {
@@ -3294,22 +3819,35 @@ function resolveMode(options, bundle) {
   if (options?.mode === "dry-run") return "dry-run";
   return "dry-run";
 }
+var CREDENTIAL_FILES = [".patchstackrc.local.json", ".patchstackrc.json"];
+async function readCredentialField(options, field) {
+  if (typeof process === "undefined" || typeof process.cwd !== "function") return void 0;
+  let readFileSync;
+  let join;
+  try {
+    const [fs, pathMod] = await Promise.all([Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1)), Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1))]);
+    readFileSync = fs.readFileSync;
+    join = pathMod.join;
+  } catch {
+    return void 0;
+  }
+  const cwd = options?.cwd ?? process.cwd();
+  for (const filename of CREDENTIAL_FILES) {
+    try {
+      const value = JSON.parse(readFileSync(join(cwd, filename), "utf8"))?.[field];
+      if (typeof value === "string" && value.length > 0) return value;
+    } catch {
+    }
+  }
+  return void 0;
+}
 async function resolveApiKey(options) {
   if (typeof options?.apiKey === "string" && options.apiKey.length > 0) return options.apiKey;
   if (typeof process !== "undefined") {
     const fromEnv = process.env?.PATCHSTACK_API_KEY;
     if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
   }
-  try {
-    if (typeof process === "undefined" || typeof process.cwd !== "function") return void 0;
-    const [{ readFileSync }, { join }] = await Promise.all([Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1)), Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1))]);
-    const cwd = options?.cwd ?? process.cwd();
-    const raw = readFileSync(join(cwd, ".patchstackrc.json"), "utf8");
-    const key = JSON.parse(raw)?.apiKey;
-    if (typeof key === "string" && key.length > 0) return key;
-  } catch {
-  }
-  return void 0;
+  return readCredentialField(options, "apiKey");
 }
 async function resolvePulseAuth(options) {
   if (typeof options?.pulseAuth === "string" && options.pulseAuth.length > 0) return options.pulseAuth;
@@ -3317,15 +3855,8 @@ async function resolvePulseAuth(options) {
     const fromEnv = process.env?.PATCHSTACK_PULSE_AUTH;
     if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
   }
-  try {
-    if (typeof process === "undefined" || typeof process.cwd !== "function") return resolveApiKey(options);
-    const [{ readFileSync }, { join }] = await Promise.all([Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1)), Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1))]);
-    const cwd = options?.cwd ?? process.cwd();
-    const raw = readFileSync(join(cwd, ".patchstackrc.json"), "utf8");
-    const key = JSON.parse(raw)?.pulseAuth;
-    if (typeof key === "string" && key.length > 0) return key;
-  } catch {
-  }
+  const fromFile = await readCredentialField(options, "pulseAuth");
+  if (fromFile !== void 0) return fromFile;
   return resolveApiKey(options);
 }
 function byPhase(rules, phase) {
@@ -3610,11 +4141,13 @@ function applyHeaderMutation(headers, rule) {
     }
   }
 }
+var SAME_SITE = ["Strict", "Lax", "None"];
 function hardenCookie(cookie, { httpOnly = true, secure = true, sameSite = "Lax" } = {}) {
   let out = String(cookie);
   if (httpOnly && !/;\s*httponly/i.test(out)) out += "; HttpOnly";
   if (secure && !/;\s*secure/i.test(out)) out += "; Secure";
-  if (sameSite && !/;\s*samesite\s*=/i.test(out)) out += `; SameSite=${sameSite}`;
+  const canonical = SAME_SITE.find((v) => typeof sameSite === "string" && v.toLowerCase() === sameSite.toLowerCase());
+  if (canonical && !/;\s*samesite\s*=/i.test(out)) out += `; SameSite=${canonical}`;
   return out;
 }
 function rebuildResponse(response, body, redactedHeaders) {
@@ -3628,11 +4161,9 @@ function rebuildResponse(response, body, redactedHeaders) {
         } catch {
         }
       } else if (typeof value === "string") {
-        if (headers.get(name) !== value) {
-          try {
-            headers.set(name, value);
-          } catch {
-          }
+        try {
+          if (headers.get(name) !== value) headers.set(name, value);
+        } catch {
         }
       } else if (Array.isArray(value)) {
         try {