@patchstack/connect 0.3.29 → 0.3.31

package/dist/protect.cjs

@@ -237,6 +237,7 @@ var init_client = __esm({
 // src/config.ts
 async function resolveConfig(options) {
   const fromFile = await readConfigFile(options.cwd);
+  const fromSecretFile = await readSecretFile(options.cwd);
   const fromEnv = readEnv();
   const siteUuid = options.cliSiteUuid ?? fromEnv.siteUuid ?? fromFile.siteUuid ?? null;
   const endpoint = options.cliEndpoint ?? fromEnv.endpoint ?? fromFile.endpoint ?? DEFAULT_ENDPOINT;
@@ -261,8 +262,8 @@ async function resolveConfig(options) {
       "CONFIG_MISSING"
     );
   }
-  const apiKeyRaw = fromEnv.apiKey ?? fromFile.apiKey ?? null;
-  const pulseAuthRaw = fromEnv.pulseAuth ?? fromFile.pulseAuth ?? apiKeyRaw;
+  const apiKeyRaw = fromEnv.apiKey ?? fromSecretFile.apiKey ?? fromFile.apiKey ?? null;
+  const pulseAuthRaw = fromEnv.pulseAuth ?? fromSecretFile.pulseAuth ?? fromFile.pulseAuth ?? apiKeyRaw;
   return {
     siteUuid: siteUuid === null || siteUuid.length === 0 ? null : siteUuid,
     apiKey: apiKeyRaw === null || apiKeyRaw.length === 0 ? null : apiKeyRaw,
@@ -273,8 +274,15 @@ async function resolveConfig(options) {
     widget: fromFile.widget !== false
   };
 }
+async function readSecretFile(cwd) {
+  const file = await readJsonFile(cwd, SECRET_FILENAME);
+  return { apiKey: file.apiKey, pulseAuth: file.pulseAuth };
+}
 async function readConfigFile(cwd) {
-  const target = import_node_path.default.join(cwd, CONFIG_FILENAME);
+  return readJsonFile(cwd, CONFIG_FILENAME);
+}
+async function readJsonFile(cwd, filename) {
+  const target = import_node_path.default.join(cwd, filename);
   let raw;
   try {
     raw = await (0, import_promises.readFile)(target, "utf8");
@@ -327,7 +335,7 @@ function isUuid(value) {
 function isEnvironment(value) {
   return value === "production" || value === "sandbox";
 }
-var import_promises, import_node_path, CONFIG_FILENAME, DEFAULT_ENVIRONMENT;
+var import_promises, import_node_path, CONFIG_FILENAME, SECRET_FILENAME, DEFAULT_ENVIRONMENT;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
@@ -336,6 +344,7 @@ var init_config = __esm({
     init_types();
     init_client();
     CONFIG_FILENAME = ".patchstackrc.json";
+    SECRET_FILENAME = ".patchstackrc.local.json";
     DEFAULT_ENVIRONMENT = "production";
   }
 });
@@ -358,7 +367,7 @@ async function readDeclaredDependencyNames(cwd) {
     return [];
   }
   const names = /* @__PURE__ */ new Set();
-  for (const group of ["dependencies", "devDependencies"]) {
+  for (const group of ["dependencies", "devDependencies", "optionalDependencies"]) {
     const deps = parsed[group];
     if (typeof deps !== "object" || deps === null) {
       continue;
@@ -376,6 +385,23 @@ function missingDependencies(declared, packages) {
   const present = new Set(packages.map((entry) => entry.name));
   return declared.filter((name) => !present.has(name));
 }
+function disagreements(packages, other) {
+  const otherVersions = /* @__PURE__ */ new Map();
+  for (const entry of other) {
+    if (!otherVersions.has(entry.name)) otherVersions.set(entry.name, entry.version);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const conflicts = [];
+  for (const entry of packages) {
+    if (seen.has(entry.name)) continue;
+    seen.add(entry.name);
+    const otherVersion = otherVersions.get(entry.name);
+    if (otherVersion !== void 0 && otherVersion !== entry.version) {
+      conflicts.push({ name: entry.name, version: entry.version, otherVersion });
+    }
+  }
+  return conflicts;
+}
 var import_promises2, import_node_path2;
 var init_consistency = __esm({
   "src/parsers/consistency.ts"() {
@@ -385,11 +411,163 @@ var init_consistency = __esm({
   }
 });
 
+// src/parsers/report.ts
+function newReport() {
+  return { unreadable: 0, samples: [] };
+}
+function recordUnreadable(report, sample) {
+  if (!report) return;
+  report.unreadable++;
+  if (report.samples.length < MAX_SAMPLES) report.samples.push(sample);
+}
+function unreadableWarning(filename, report) {
+  if (report.unreadable === 0) return null;
+  const shown = report.samples.join(", ");
+  const one = report.unreadable === 1;
+  return `${filename}: ${report.unreadable} entr${one ? "y was" : "ies were"} not in a form this scanner reads (${shown}${report.unreadable > report.samples.length ? ", \u2026" : ""}), so ${one ? "it is" : "they are"} absent from this manifest. Anything installed only through ${one ? "that entry" : "those entries"} is not being checked.`;
+}
+var MAX_SAMPLES;
+var init_report = __esm({
+  "src/parsers/report.ts"() {
+    "use strict";
+    MAX_SAMPLES = 3;
+  }
+});
+
+// src/parsers/bun.ts
+async function parseBunLockfile(lockfilePath, report) {
+  let raw;
+  try {
+    raw = await (0, import_promises3.readFile)(lockfilePath, "utf8");
+  } catch (cause) {
+    throw new PatchstackError(`Could not read lockfile at ${lockfilePath}`, "LOCKFILE_NOT_FOUND", cause);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stripTrailingCommas(raw));
+  } catch (cause) {
+    throw new PatchstackError(`Lockfile at ${lockfilePath} is not valid JSON`, "LOCKFILE_PARSE_ERROR", cause);
+  }
+  const packages = parsed?.packages;
+  if (typeof packages !== "object" || packages === null) {
+    throw new PatchstackError(`Lockfile at ${lockfilePath} has no "packages" entries`, "LOCKFILE_PARSE_ERROR");
+  }
+  const direct = directDependencyNames(parsed);
+  const entries = [];
+  let skipped = 0;
+  for (const [key, value] of Object.entries(packages)) {
+    const descriptor = Array.isArray(value) ? value[0] : value;
+    if (typeof descriptor !== "string") {
+      skipped++;
+      recordUnreadable(report, key);
+      continue;
+    }
+    const split = splitDescriptor(descriptor);
+    if (split === null) {
+      skipped++;
+      if (!isDeliberatelyExcluded(descriptor)) recordUnreadable(report, key);
+      continue;
+    }
+    entries.push({
+      name: split.name,
+      version: split.version,
+      ...direct.has(split.name) ? { direct: true } : {},
+      ...key === split.name ? {} : { path: key }
+    });
+  }
+  if (entries.length === 0) {
+    throw new PatchstackError(
+      `Lockfile at ${lockfilePath} lists no registry packages${skipped > 0 ? ` (${skipped} non-registry entr${skipped === 1 ? "y" : "ies"} skipped)` : ""}`,
+      "LOCKFILE_PARSE_ERROR"
+    );
+  }
+  return entries;
+}
+function splitDescriptor(descriptor) {
+  const at = descriptor.lastIndexOf("@");
+  if (at <= 0) return null;
+  const name = descriptor.slice(0, at);
+  const version = descriptor.slice(at + 1);
+  if (name === "" || version === "") return null;
+  if (NON_REGISTRY_VERSION.test(version)) return null;
+  return { name, version };
+}
+function isDeliberatelyExcluded(descriptor) {
+  const at = descriptor.lastIndexOf("@");
+  if (at <= 0) return false;
+  return NON_REGISTRY_VERSION.test(descriptor.slice(at + 1));
+}
+function directDependencyNames(parsed) {
+  const names = /* @__PURE__ */ new Set();
+  const workspaces = parsed?.workspaces;
+  if (typeof workspaces !== "object" || workspaces === null) return names;
+  for (const workspace of Object.values(workspaces)) {
+    if (typeof workspace !== "object" || workspace === null) continue;
+    for (const group of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+      const deps = workspace[group];
+      if (typeof deps !== "object" || deps === null) continue;
+      for (const name of Object.keys(deps)) names.add(name);
+    }
+  }
+  return names;
+}
+function stripTrailingCommas(source) {
+  const out = [];
+  let inString = false;
+  let pendingComma = -1;
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (inString) {
+      out.push(ch);
+      if (ch === "\\") {
+        const next = source[i + 1];
+        if (next !== void 0) {
+          out.push(next);
+          i++;
+        }
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      pendingComma = -1;
+      out.push(ch);
+      continue;
+    }
+    if (ch === ",") {
+      pendingComma = out.length;
+      out.push(ch);
+      continue;
+    }
+    if (ch === "}" || ch === "]") {
+      if (pendingComma !== -1) out[pendingComma] = " ";
+      pendingComma = -1;
+      out.push(ch);
+      continue;
+    }
+    if (!/\s/.test(ch)) pendingComma = -1;
+    out.push(ch);
+  }
+  return out.join("");
+}
+var import_promises3, NON_REGISTRY_VERSION;
+var init_bun = __esm({
+  "src/parsers/bun.ts"() {
+    "use strict";
+    import_promises3 = require("fs/promises");
+    init_types();
+    init_report();
+    NON_REGISTRY_VERSION = /^[a-z][a-z0-9+.-]*:|\//i;
+  }
+});
+
 // src/parsers/npm.ts
 async function parseNpmLockfile(lockfilePath) {
   let raw;
   try {
-    raw = await (0, import_promises3.readFile)(lockfilePath, "utf8");
+    raw = await (0, import_promises4.readFile)(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(`Could not read lockfile at ${lockfilePath}`, "LOCKFILE_NOT_FOUND", cause);
   }
@@ -468,11 +646,11 @@ function isDirectV2(pkgPath) {
   const nmCount = parts.filter((p) => p === "node_modules").length;
   return nmCount === 1;
 }
-var import_promises3, import_node_path3;
+var import_promises4, import_node_path3;
 var init_npm = __esm({
   "src/parsers/npm.ts"() {
     "use strict";
-    import_promises3 = require("fs/promises");
+    import_promises4 = require("fs/promises");
     import_node_path3 = __toESM(require("path"), 1);
     init_types();
   }
@@ -482,7 +660,7 @@ var init_npm = __esm({
 async function walkNodeModules(cwd) {
   const root = import_node_path4.default.join(cwd, "node_modules");
   try {
-    const info = await (0, import_promises4.stat)(root);
+    const info = await (0, import_promises5.stat)(root);
     if (!info.isDirectory()) {
       throw new PatchstackError(
         `${root} exists but is not a directory.`,
@@ -499,104 +677,134 @@ async function walkNodeModules(cwd) {
       cause
     );
   }
-  const entries = [];
-  await walk(root, entries, 0);
-  return entries;
+  const seen = /* @__PURE__ */ new Map();
+  try {
+    seen.set(await (0, import_promises5.realpath)(cwd), -1);
+  } catch {
+  }
+  return dedupeByShallowest(await walk(root, 0, seen, cwd));
+}
+function dedupeByShallowest(found) {
+  const best = /* @__PURE__ */ new Map();
+  for (const item of found) {
+    const current = best.get(item.realpath);
+    if (current === void 0 || item.depth < current.depth) best.set(item.realpath, item);
+  }
+  return [...best.values()].map(({ entry }) => entry);
 }
-async function walk(dir, acc, depth) {
+async function walk(dir, depth, seen, root) {
   let names;
   try {
-    names = await (0, import_promises4.readdir)(dir);
+    names = await (0, import_promises5.readdir)(dir);
   } catch {
-    return;
+    return [];
   }
-  for (const name of names) {
-    if (name.startsWith(".")) {
-      continue;
-    }
+  const perEntry = await mapLimit(names, async (name) => {
+    if (name.startsWith(".") && !PACKAGE_STORE_DIRS.has(name)) return [];
     const fullPath = import_node_path4.default.join(dir, name);
-    if (!await isPlainDirectory(fullPath)) {
-      continue;
-    }
+    const resolved = await claim(fullPath, seen, depth);
+    if (resolved === null) return [];
+    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen, root);
     if (name.startsWith("@")) {
       let subNames;
       try {
-        subNames = await (0, import_promises4.readdir)(fullPath);
+        subNames = await (0, import_promises5.readdir)(fullPath);
       } catch {
-        continue;
+        return [];
       }
-      for (const sub of subNames) {
-        if (sub.startsWith(".")) {
-          continue;
-        }
+      const scoped = await mapLimit(subNames, async (sub) => {
+        if (sub.startsWith(".")) return [];
         const scopedDir = import_node_path4.default.join(fullPath, sub);
-        if (!await isPlainDirectory(scopedDir)) {
-          continue;
-        }
-        await readPackage(scopedDir, depth, acc);
-        await walkNested(scopedDir, acc, depth);
-      }
-      continue;
+        const scopedReal = await claim(scopedDir, seen, depth);
+        if (scopedReal === null) return [];
+        return packageAndNested(scopedDir, scopedReal, depth, seen, root);
+      });
+      return scoped.flat();
     }
-    await readPackage(fullPath, depth, acc);
-    await walkNested(fullPath, acc, depth);
-  }
+    return packageAndNested(fullPath, resolved, depth, seen, root);
+  });
+  return perEntry.flat();
+}
+async function packageAndNested(pkgDir, resolved, depth, seen, root) {
+  const [own, nested] = await Promise.all([readPackage(pkgDir, depth, root), walkNested(pkgDir, depth, seen, root)]);
+  return own === null ? nested : [{ entry: own, realpath: resolved, depth }, ...nested];
 }
-async function readPackage(pkgDir, depth, acc) {
+async function mapLimit(items, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+function installLocation(root, pkgDir, impl = import_node_path4.default) {
+  return impl.relative(root, pkgDir).split(impl.sep).join("/");
+}
+async function readPackage(pkgDir, depth, root) {
   let raw;
   try {
-    raw = await (0, import_promises4.readFile)(import_node_path4.default.join(pkgDir, "package.json"), "utf8");
+    raw = await (0, import_promises5.readFile)(import_node_path4.default.join(pkgDir, "package.json"), "utf8");
   } catch {
-    return;
+    return null;
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    return;
+    return null;
   }
   if (typeof parsed.name !== "string" || parsed.name.length === 0) {
-    return;
+    return null;
   }
   if (typeof parsed.version !== "string" || parsed.version.length === 0) {
-    return;
+    return null;
   }
-  acc.push({
-    name: parsed.name,
-    version: parsed.version,
-    direct: depth === 0
-  });
+  return { name: parsed.name, version: parsed.version, path: installLocation(root, pkgDir), direct: depth === 0 };
 }
-async function walkNested(pkgDir, acc, depth) {
+async function walkNested(pkgDir, depth, seen, root) {
   const nested = import_node_path4.default.join(pkgDir, "node_modules");
-  if (!await isPlainDirectory(nested)) {
-    return;
+  if (await claim(nested, seen, depth + 1) === null) {
+    return [];
   }
-  await walk(nested, acc, depth + 1);
+  return walk(nested, depth + 1, seen, root);
 }
-async function isPlainDirectory(dir) {
+async function claim(dir, seen, depth) {
+  let resolved;
   try {
-    const info = await (0, import_promises4.lstat)(dir);
-    return info.isDirectory() && !info.isSymbolicLink();
+    const info = await (0, import_promises5.lstat)(dir);
+    if (!info.isDirectory() && !info.isSymbolicLink()) return null;
+    resolved = await (0, import_promises5.realpath)(dir);
+    const target = await (0, import_promises5.stat)(resolved);
+    if (!target.isDirectory()) return null;
   } catch {
-    return false;
+    return null;
   }
+  const claimed = seen.get(resolved);
+  if (claimed !== void 0 && claimed <= depth) return null;
+  seen.set(resolved, depth);
+  return resolved;
 }
-var import_promises4, import_node_path4;
+var import_promises5, import_node_path4, PACKAGE_STORE_DIRS, CONCURRENCY;
 var init_node_modules = __esm({
   "src/parsers/node_modules.ts"() {
     "use strict";
-    import_promises4 = require("fs/promises");
+    import_promises5 = require("fs/promises");
     import_node_path4 = __toESM(require("path"), 1);
     init_types();
+    PACKAGE_STORE_DIRS = /* @__PURE__ */ new Set([".bun", ".pnpm", ".store"]);
+    CONCURRENCY = 32;
   }
 });
 
 // src/parsers/pnpm.ts
-async function parsePnpmLockfile(lockfilePath) {
+async function parsePnpmLockfile(lockfilePath, report) {
   let raw;
   try {
-    raw = await (0, import_promises5.readFile)(lockfilePath, "utf8");
+    raw = await (0, import_promises6.readFile)(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(
       `Could not read lockfile at ${lockfilePath}`,
@@ -617,6 +825,7 @@ async function parsePnpmLockfile(lockfilePath) {
   for (const key of packageKeys) {
     const parsed = parsePackageKey(key);
     if (parsed === null) {
+      recordUnreadable(report, key);
       continue;
     }
     entries.push({
@@ -837,12 +1046,13 @@ function extractLeafName(trimmed) {
   }
   return name.length > 0 ? name : null;
 }
-var import_promises5, DEP_SECTIONS;
+var import_promises6, DEP_SECTIONS;
 var init_pnpm = __esm({
   "src/parsers/pnpm.ts"() {
     "use strict";
-    import_promises5 = require("fs/promises");
+    import_promises6 = require("fs/promises");
     init_types();
+    init_report();
     DEP_SECTIONS = /* @__PURE__ */ new Set([
       "dependencies",
       "devDependencies",
@@ -852,10 +1062,10 @@ var init_pnpm = __esm({
 });
 
 // src/parsers/yarn.ts
-async function parseYarnLockfile(lockfilePath) {
+async function parseYarnLockfile(lockfilePath, report) {
   let raw;
   try {
-    raw = await (0, import_promises6.readFile)(lockfilePath, "utf8");
+    raw = await (0, import_promises7.readFile)(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(
       `Could not read lockfile at ${lockfilePath}`,
@@ -863,7 +1073,7 @@ async function parseYarnLockfile(lockfilePath) {
       cause
     );
   }
-  const blocks = parseBlocks(raw);
+  const blocks = parseBlocks(raw, report);
   if (blocks.length === 0) {
     throw new PatchstackError(
       `Lockfile at ${lockfilePath} contains no package entries`,
@@ -892,13 +1102,18 @@ async function parseYarnLockfile(lockfilePath) {
   }
   return entries;
 }
-function parseBlocks(raw) {
+function parseBlocks(raw, report) {
   const lines = raw.split(/\r?\n/);
   const blocks = [];
   let current = null;
   const finalize = () => {
-    if (current !== null && current.version.length > 0 && current.names.size > 0) {
+    if (current === null) {
+      return;
+    }
+    if (current.version.length > 0 && current.names.size > 0) {
       blocks.push(current);
+    } else if (current.unreadable) {
+      recordUnreadable(report, current.key);
     }
     current = null;
   };
@@ -915,13 +1130,13 @@ function parseBlocks(raw) {
       }
       const keyLine = trimmed.slice(0, -1);
       const names = /* @__PURE__ */ new Set();
+      let unreadable = false;
       for (const spec of splitDescriptors(keyLine)) {
-        const name = extractName(spec);
-        if (name !== null) {
-          names.add(name);
-        }
+        const classified = classifyDescriptor(spec);
+        if (classified.name !== void 0) names.add(classified.name);
+        else if (!classified.excluded) unreadable = true;
       }
-      current = { names, version: "" };
+      current = { names, version: "", key: keyLine, unreadable: unreadable && names.size === 0 };
       continue;
     }
     if (current === null) {
@@ -976,20 +1191,36 @@ function splitDescriptors(keyLine) {
   }
   return parts;
 }
-function extractName(rawSpec) {
+function classifyDescriptor(rawSpec) {
   let s = rawSpec.trim();
   if (s.length === 0) {
-    return null;
+    return { excluded: true };
   }
   if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
     s = s.slice(1, -1);
   }
-  const atIdx = s.lastIndexOf("@");
+  if (NON_PACKAGE_KEYS.has(s)) {
+    return { excluded: true };
+  }
+  const atIdx = s.indexOf("@", 1);
   if (atIdx <= 0) {
-    return null;
+    return {};
   }
   const name = s.slice(0, atIdx);
-  return name.length > 0 ? name : null;
+  const range = s.slice(atIdx + 1);
+  if (name.length === 0) {
+    return {};
+  }
+  if (NON_REGISTRY_PROTOCOLS.test(range)) {
+    return { excluded: true };
+  }
+  const alias = /^npm:(.+)$/i.exec(range);
+  if (alias !== null) {
+    const target = alias[1] ?? "";
+    const targetAt = target.indexOf("@", 1);
+    return { name: targetAt > 0 ? target.slice(0, targetAt) : name };
+  }
+  return { name };
 }
 function parseVersionField(content) {
   if (!content.startsWith("version")) {
@@ -1014,7 +1245,7 @@ async function readDirectDepNames(cwd) {
   const names = /* @__PURE__ */ new Set();
   let raw;
   try {
-    raw = await (0, import_promises6.readFile)(import_node_path5.default.join(cwd, "package.json"), "utf8");
+    raw = await (0, import_promises7.readFile)(import_node_path5.default.join(cwd, "package.json"), "utf8");
   } catch {
     return names;
   }
@@ -1039,13 +1270,16 @@ async function readDirectDepNames(cwd) {
   }
   return names;
 }
-var import_promises6, import_node_path5;
+var import_promises7, import_node_path5, NON_PACKAGE_KEYS, NON_REGISTRY_PROTOCOLS;
 var init_yarn = __esm({
   "src/parsers/yarn.ts"() {
     "use strict";
-    import_promises6 = require("fs/promises");
+    import_promises7 = require("fs/promises");
     import_node_path5 = __toESM(require("path"), 1);
     init_types();
+    init_report();
+    NON_PACKAGE_KEYS = /* @__PURE__ */ new Set(["__metadata"]);
+    NON_REGISTRY_PROTOCOLS = /^(?:workspace|patch|virtual|portal|file|link|exec|git|github|https?|ssh):/i;
   }
 });
 
@@ -1080,34 +1314,58 @@ async function scanLockfile(cwd) {
   const declared = await readDeclaredDependencyNames(cwd);
   const warnings = [];
   let firstParsed = null;
-  let walkTried = false;
+  let walked = null;
+  let walkWasCandidate = false;
+  const parsedSources = [];
   for (const candidate of candidates) {
     let packages;
+    const report = newReport();
     try {
-      packages = await runStrategy(candidate, cwd);
+      packages = await runStrategy(candidate, cwd, report);
     } catch {
       continue;
     }
-    walkTried ||= candidate.strategy === "node-modules-walk";
+    const unreadable = unreadableWarning(candidate.filename, report);
+    if (unreadable !== null) warnings.push(unreadable);
+    if (candidate.strategy === "node-modules-walk") {
+      walked = packages;
+      walkWasCandidate = true;
+    }
     firstParsed ??= { packages, filename: candidate.filename };
-    const missing = missingDependencies(declared, packages);
-    if (missing.length === 0) {
-      return manifestWith(packages, warnings);
+    parsedSources.push({ packages, filename: candidate.filename });
+  }
+  for (const source of parsedSources) {
+    const missing = missingDependencies(declared, source.packages);
+    if (missing.length > 0) {
+      warnings.push(staleWarning(source.filename, missing));
+      continue;
     }
-    warnings.push(staleWarning(candidate.filename, missing));
+    const conflicts = otherCompleteSources(parsedSources, source, declared).flatMap(
+      (other) => disagreements(source.packages, other.packages).map((conflict) => ({ other: other.filename, conflict }))
+    );
+    if (conflicts.length === 0) {
+      return manifestWith(source.packages, warnings);
+    }
+    warnings.push(conflictWarning(source.filename, conflicts));
+    break;
   }
-  if (!walkTried) {
+  if (walked === null) {
     try {
-      const packages = await walkNodeModules(cwd);
-      const missing = missingDependencies(declared, packages);
-      if (missing.length > 0) {
-        warnings.push(staleWarning("node_modules/", missing));
-      }
-      warnings.push("Scanned node_modules/ instead. Delete the stale lockfile to silence this warning.");
-      return manifestWith(packages, warnings);
+      walked = await walkNodeModules(cwd);
     } catch {
+      walked = null;
     }
   }
+  if (walked !== null) {
+    const missing = missingDependencies(declared, walked);
+    if (missing.length > 0) {
+      warnings.push(staleWarning("node_modules/", missing));
+    }
+    warnings.push(
+      walkWasCandidate ? "Reporting node_modules/, which is what the build loads." : "Scanned node_modules/ instead. Delete the stale lockfile to silence this warning."
+    );
+    return manifestWith(walked, warnings);
+  }
   if (firstParsed === null) {
     const expected = LOCKFILE_CANDIDATES.map((candidate) => candidate.filename).join(", ");
     throw new PatchstackError(
@@ -1123,6 +1381,15 @@ async function scanLockfile(cwd) {
 function manifestWith(packages, warnings) {
   return warnings.length > 0 ? { ecosystem: "npm", packages, warnings } : { ecosystem: "npm", packages };
 }
+function otherCompleteSources(all, current, declared) {
+  return all.filter(
+    (source) => source.filename !== current.filename && missingDependencies(declared, source.packages).length === 0
+  );
+}
+function conflictWarning(filename, conflicts) {
+  const shown = conflicts.slice(0, 3).map(({ other, conflict }) => `${conflict.name} ${conflict.version} vs ${conflict.otherVersion} in ${other}`).join("; ");
+  return `${filename} and another lockfile disagree about installed versions (${shown}${conflicts.length > 3 ? `, +${conflicts.length - 3} more` : ""}). Scanned node_modules/ instead. Remove whichever lockfile your package manager does not maintain.`;
+}
 function staleWarning(source, missing) {
   const sample = missing.slice(0, 3).join(", ");
   const suffix = missing.length > 3 ? `, +${missing.length - 3} more` : "";
@@ -1137,41 +1404,50 @@ async function presentLockfiles(cwd) {
   );
   return probed.filter((candidate) => candidate.present).map(({ filename, strategy, filePath }) => ({ ecosystem: "npm", filename, strategy, filePath }));
 }
-async function runStrategy(detected, cwd) {
+async function runStrategy(detected, cwd, report) {
   switch (detected.strategy) {
     case "npm-lockfile":
       return parseNpmLockfile(detected.filePath);
+    case "bun-lockfile":
+      return parseBunLockfile(detected.filePath, report);
+    // The hand-written scanners. Each meets entries it was not written for, and each is asked to say how
+    // many it dropped, because a manifest short a package reads exactly like a project without it.
     case "pnpm-lockfile":
-      return parsePnpmLockfile(detected.filePath);
+      return parsePnpmLockfile(detected.filePath, report);
     case "yarn-lockfile":
-      return parseYarnLockfile(detected.filePath);
+      return parseYarnLockfile(detected.filePath, report);
     case "node-modules-walk":
       return walkNodeModules(cwd);
   }
 }
 async function exists(filePath) {
   try {
-    await (0, import_promises7.access)(filePath);
+    await (0, import_promises8.access)(filePath);
     return true;
   } catch {
     return false;
   }
 }
-var import_promises7, import_node_path6, LOCKFILE_CANDIDATES;
+var import_promises8, import_node_path6, LOCKFILE_CANDIDATES;
 var init_parsers = __esm({
   "src/parsers/index.ts"() {
     "use strict";
-    import_promises7 = require("fs/promises");
+    import_promises8 = require("fs/promises");
     import_node_path6 = __toESM(require("path"), 1);
     init_types();
     init_consistency();
+    init_bun();
     init_npm();
     init_node_modules();
     init_pnpm();
     init_yarn();
+    init_report();
     LOCKFILE_CANDIDATES = [
       { filename: "package-lock.json", strategy: "npm-lockfile" },
-      { filename: "bun.lock", strategy: "node-modules-walk" },
+      // Read directly, not walked. Bun's isolated layout puts packages under a dot-directory and makes the
+      // top level symlinks into it, so a `node_modules` walk finds nothing there — and isolated is the default
+      // for new workspaces.
+      { filename: "bun.lock", strategy: "bun-lockfile" },
       { filename: "bun.lockb", strategy: "node-modules-walk" },
       { filename: "pnpm-lock.yaml", strategy: "pnpm-lockfile" },
       { filename: "yarn.lock", strategy: "yarn-lockfile" }
@@ -1180,21 +1456,33 @@ var init_parsers = __esm({
 });
 
 // src/normalize.ts
-function buildWirePayload(manifest) {
+function buildWirePayload(manifest, options = {}) {
+  const withPaths = options.installPaths === true;
   const seen = /* @__PURE__ */ new Map();
   const wirePackages = [];
+  const byIdentity = /* @__PURE__ */ new Map();
+  let entriesWithoutPath = 0;
   for (const entry of manifest.packages) {
+    const identity = `${entry.name}@${entry.version}`;
+    const location = withPaths && entry.path !== void 0 && entry.path !== "" ? entry.path : void 0;
+    if (location === void 0) entriesWithoutPath++;
+    const existing = byIdentity.get(identity);
+    if (existing) {
+      if (location !== void 0) addPath(existing, location);
+      continue;
+    }
     const versions = seen.get(entry.name);
     if (versions) {
-      if (versions.has(entry.version)) {
-        continue;
-      }
       versions.add(entry.version);
     } else {
       seen.set(entry.name, /* @__PURE__ */ new Set([entry.version]));
     }
-    wirePackages.push({ name: entry.name, version: entry.version });
+    const wire = { name: entry.name, version: entry.version };
+    if (location !== void 0) addPath(wire, location);
+    byIdentity.set(identity, wire);
+    wirePackages.push(wire);
   }
+  for (const wire of wirePackages) wire.paths?.sort();
   wirePackages.sort((a, b) => {
     if (a.name === b.name) {
       return compareVersions(a.version, b.version);
@@ -1208,7 +1496,18 @@ function buildWirePayload(manifest) {
     }
   }
   return {
-    payload: { ecosystem: manifest.ecosystem, packages: wirePackages },
+    payload: {
+      ecosystem: manifest.ecosystem,
+      packages: wirePackages,
+      // Every entry had a location, so a missing path anywhere means the package is not installed there.
+      // One entry without one forfeits that for the whole payload: a consumer reading a short `paths` has
+      // no way to tell which entry was the incomplete one.
+      //
+      // No separate check for "locations were not requested": with them off every entry counts as without
+      // one, so this is already false — which is the default, and the safe direction. An explicit
+      // `withPaths &&` here was a guard no test could distinguish from its absence.
+      installPathsComplete: entriesWithoutPath === 0 && manifest.packages.length > 0
+    },
     stats: {
       uniqueNames: seen.size,
       duplicateNames,
@@ -1216,6 +1515,10 @@ function buildWirePayload(manifest) {
     }
   };
 }
+function addPath(wire, installPath) {
+  if (wire.paths === void 0) wire.paths = [installPath];
+  else if (!wire.paths.includes(installPath)) wire.paths.push(installPath);
+}
 function compareVersions(a, b) {
   if (a === b) {
     return 0;
@@ -1450,6 +1753,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;
@@ -1572,6 +1914,8 @@ var RequestResolver = class {
         } catch {
           return value;
         }
+      case "htmlentitydecode":
+        return decodeHtmlEntities(String(value));
       case "intval":
         return parseInt(String(value), 10) || 0;
       case "getArrayValues":
@@ -2239,6 +2583,30 @@ function expandIPv6(host) {
   }
   return out;
 }
+var JWT_CANDIDATE = /(?<![A-Za-z0-9_-])(?<![A-Za-z0-9_-]\.)eyJ[A-Za-z0-9_-]{2,2048}\.[A-Za-z0-9_-]{2,8192}\.[A-Za-z0-9_-]{0,2048}(?![A-Za-z0-9_-])(?!\.[A-Za-z0-9_-])/g;
+function base64UrlToBase64(segment) {
+  const padded = segment.length % 4 === 0 ? segment : segment + "=".repeat(4 - segment.length % 4);
+  return padded.replace(/-/g, "+").replace(/_/g, "/");
+}
+function jwtClaimSpans(text, claim2, value) {
+  const found = /* @__PURE__ */ new Set();
+  if (typeof text !== "string" || typeof claim2 !== "string" || claim2 === "") return [];
+  const wanted = String(value);
+  for (const [token] of text.matchAll(JWT_CANDIDATE)) {
+    const parts = token.split(".");
+    let payload;
+    try {
+      payload = JSON.parse(base64DecodeUtf8(base64UrlToBase64(parts[1])));
+    } catch {
+      continue;
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) continue;
+    if (!Object.prototype.hasOwnProperty.call(payload, claim2)) continue;
+    const actual = payload[claim2];
+    if (typeof actual === "string" && actual === wanted) found.add(token);
+  }
+  return [...found];
+}
 var warnedScopes = /* @__PURE__ */ new Set();
 function warnUnrecognisedScope(when) {
   const key = Object.keys(when).sort().join(",");
@@ -2267,16 +2635,30 @@ function ruleAppliesTo(when, resolver) {
     return true;
   }
 }
+function foldPathForScope(value) {
+  const out = String(value).toLowerCase();
+  return out.endsWith("/") ? out.slice(0, -1) : out;
+}
+var REGEX_SYNTAX = /[\\^$*+?()[\]{}|]/;
+var REGEX_FORM = /^\/(.+?)\/([gimsuy]*)$/s;
+function isRegexForm(pattern) {
+  const parts = REGEX_FORM.exec(pattern);
+  return parts !== null && REGEX_SYNTAX.test(parts[1]);
+}
 function pathMatches(pattern, path7) {
-  if (pattern.length > 2 && pattern.startsWith("/") && pattern.endsWith("/")) {
+  if (isRegexForm(pattern)) {
     const re = safeRegExp(pattern);
     return re ? re.test(path7) : false;
   }
-  if (pattern.includes("*")) {
-    const re = safeRegExp("/^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^?]*") + "$/");
-    return re ? re.test(path7) : false;
+  const target = foldPathForScope(path7);
+  const folded = foldPathForScope(pattern);
+  if (folded.includes("*")) {
+    const trailing = folded.endsWith("/*");
+    const body = (trailing ? folded.slice(0, -2) : folded).replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^?]*");
+    const re = safeRegExp("/^" + body + (trailing ? "(?:/[^?]*)?" : "") + "$/");
+    return re ? re.test(target) : false;
   }
-  return path7 === pattern;
+  return target === folded;
 }
 function normalizeDefaultPort(host) {
   return String(host).toLowerCase().replace(/:(?:80|443)$/, "");
@@ -2429,6 +2811,8 @@ function matchValue(type, value, matchVal, matchObj) {
       const stripped = strValue.replace(/[ _\-,]/g, "");
       return ctypeResult(strValue, /^[\w$€-￿]*$/.test(stripped), matchVal);
     }
+    case "jwt_claim_equals":
+      return jwtClaimSpans(strValue, matchObj?.claim, matchVal).length > 0;
     case "array_key_value":
       return arrayKeyValue(value, matchObj);
     // file_contains (uploaded-file content scanning) is NOT WordPress-specific, but is
@@ -3195,13 +3579,43 @@ var DEFAULT_RESPONSE_RULES = [
     rule_v2: [{ parameter: "response.body", match: { type: "regex", value: "/\\b(?:sk_live_[0-9A-Za-z]{16,}|rk_live_[0-9A-Za-z]{16,}|gh[opsu]_[0-9A-Za-z]{36}|github_pat_[0-9A-Za-z_]{60,}|glpat-[0-9A-Za-z_-]{20,}|xox[baprs]-[0-9A-Za-z-]{10,}|sk-ant-[0-9A-Za-z_-]{20,}|ya29\\.[0-9A-Za-z_-]{20,}|npm_[0-9A-Za-z]{36})(?![0-9A-Za-z])/" } }]
   },
   {
-    id: "resp-jwt",
-    title: "JWT in response body",
+    id: "resp-supabase-secret-key",
+    title: "Supabase secret key in response body",
+    phase: "response",
+    category: "secret-exposure",
+    action: "redact",
+    // Supabase's opaque key format, which is not a JWT and so is not covered by the JWT rule below.
+    // `sb_secret_` is the elevated one — documented as full access, bypassing Row Level Security,
+    // backend-only — while `sb_publishable_` is meant for public clients and must pass untouched.
+    // Both key systems are live at once: new keys sit alongside the legacy `anon` / `service_role`
+    // JWTs rather than replacing them, so this rule and the JWT rule cover different halves.
+    //
+    // The documented grammar is the prefix, 22 base64url characters, `_`, then an 8-character
+    // base64url checksum. Matching it exactly is what keeps the mask on the key and off the response
+    // around it: a variable-length suffix would either run past the key into adjacent syntax or stop
+    // short and leave the tail of a real key visible. The trailing guard rejects a longer run of key
+    // characters, which is not this format.
+    prefilter: ["sb_secret_"],
+    rule_v2: [{ parameter: "response.body", match: { type: "regex", value: "/\\bsb_secret_[A-Za-z0-9_-]{22}_[A-Za-z0-9_-]{8}(?![A-Za-z0-9_-])/" } }]
+  },
+  {
+    id: "resp-supabase-service-role-key",
+    title: "Supabase service_role key in response body",
     phase: "response",
     category: "secret-exposure",
     action: "redact",
+    // Scoped to the one role that must never leave: `service_role` bypasses Row Level Security
+    // entirely. A JWT in a response body is not inherently a leak — the Supabase `anon` key is public
+    // by design and a login response carries the user's own access token — so this decides on the
+    // decoded payload rather than on the shape of the token.
+    //
+    // `jwt_claim_equals` also yields the matching token spans, which is what lets `redact` mask those
+    // tokens and serve the rest of the response.
+    //
+    // A broad any-JWT rule is a reasonable thing to want; it belongs in the managed hardening bundle as
+    // an opt-in, observe-only rule rather than an on-by-default mask.
     prefilter: ["eyJ"],
-    rule_v2: [{ parameter: "response.body", match: { type: "regex", value: "/\\beyJ[A-Za-z0-9_-]{8,}\\.eyJ[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}\\b/" } }]
+    rule_v2: [{ parameter: "response.body", match: { type: "jwt_claim_equals", claim: "role", value: "service_role" } }]
   },
   {
     id: "resp-db-connection-string",
@@ -3426,25 +3840,468 @@ 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",
+  "jwt_claim_equals",
+  "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([
+  "positive-number",
+  "boolean",
+  "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" })
+  }),
+  // Decides on a JWT's DECODED payload rather than its shape, and yields the matching token spans so
+  // `redact` masks only those tokens. `claim` names an own, top-level claim; `value` is compared with
+  // exact string equality. Anything not positively identified — undecodable, not JSON, not an object,
+  // oversized, claim missing, claim not a string, or a different value — is a no-match.
+  jwt_claim_equals: Object.freeze({
+    required: Object.freeze(["claim", "value"]),
+    shapes: Object.freeze({ claim: "non-empty-string", value: "non-empty-string" })
+  }),
+  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 "positive-number":
+      return typeof value === "number" && Number.isFinite(value) && value > 0 ? null : "must be a finite positive number";
+    case "boolean":
+      return typeof value === "boolean" ? null : "must be true or false";
+    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 RULE_PROPERTY_SHAPES = Object.freeze({
+  max_bytes: "positive-number",
+  bypass_limit: "boolean",
+  ensure: "boolean",
+  prefilter: "non-empty-string-list"
+});
+var ENFORCEMENT_VALUES = Object.freeze(["dry-run"]);
+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 nullPropertyProblem(rule) {
+  if (!rule || typeof rule !== "object") return null;
+  for (const property of RULE_PROPERTIES) {
+    if (property in rule && rule[property] === null) {
+      return `"${property}" is present but null; omit it to mean the default, since a null is a value that was meant to be something and is not`;
+    }
+  }
+  return null;
+}
+function rulePropertyProblem(rule) {
+  if (!rule || typeof rule !== "object") return null;
+  for (const [property, shape] of Object.entries(RULE_PROPERTY_SHAPES)) {
+    if (rule[property] === void 0 || rule[property] === null) continue;
+    const problem = operandShapeProblem(shape, rule[property]);
+    if (problem) return `"${property}" ${problem}`;
+  }
+  return null;
+}
+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);
@@ -3453,8 +4310,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) {
@@ -3476,37 +4333,47 @@ 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}"`;
-  const capOverride = rule.max_bytes;
-  if (capOverride !== void 0 && !(Number(capOverride) > 0)) return "max_bytes must be a positive number";
+  const nullReason = nullPropertyProblem(rule);
+  if (nullReason) return nullReason;
+  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 propertyReason = rulePropertyProblem(rule);
+  if (propertyReason) return propertyReason;
   return conditionsProblem(rule.rule_v2);
 }
 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;
     }
   }
@@ -3534,64 +4401,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;
@@ -3644,8 +4514,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");
@@ -3672,7 +4543,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;
     }
@@ -3701,6 +4573,12 @@ function ruleParameters(rule) {
   walk2(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(path7) {
   if (typeof path7 !== "string" || path7 === "") return null;
   const cut = path7.search(/[?#]/);
@@ -3709,16 +4587,30 @@ function routeOf(path7) {
 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;
@@ -3732,6 +4624,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)}`, {
@@ -3740,15 +4634,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;
       }
     })();
   };
@@ -3777,7 +4678,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) {
@@ -3791,7 +4697,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 })
   };
 }
 
@@ -4056,22 +4979,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;
@@ -4405,11 +5338,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;
@@ -4427,38 +5366,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) {
@@ -4495,24 +5437,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) {
@@ -4523,22 +5463,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([import("fs"), import("path")]);
+    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([import("fs"), import("path")]);
-    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;
@@ -4546,15 +5499,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([import("fs"), import("path")]);
-    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) {
@@ -4687,6 +5633,8 @@ function extractRedactors(rule) {
         }
       } else if ((m.type === "contains" || m.type === "stripos") && m.value != null) {
         out.push({ literal: String(m.value) });
+      } else if (m.type === "jwt_claim_equals" && typeof m.claim === "string") {
+        out.push({ jwtClaim: { claim: m.claim, value: String(m.value ?? "") } });
       } else if (m.type === "array_key_value" && m.match && isBodyParam(c.parameter)) {
         const keys = Array.isArray(m.key) ? m.key : [m.key];
         for (const key of keys) {
@@ -4705,7 +5653,11 @@ function applyRedactors(body, redactors, mask, transform) {
   let out = body;
   for (const r of redactors) {
     if (r.re) out = out.replace(r.re, transform ? (m) => transform(m) : mask);
-    else if (r.literal) {
+    else if (r.jwtClaim) {
+      for (const token of jwtClaimSpans(out, r.jwtClaim.claim, r.jwtClaim.value)) {
+        out = out.split(token).join(transform ? transform(token) : mask);
+      }
+    } else if (r.literal) {
       const re = new RegExp(r.literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
       out = out.replace(re, (m) => transform ? transform(m) : mask);
     }
@@ -4839,11 +5791,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) {
@@ -4857,11 +5811,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 {