@patchstack/connect 0.3.33 → 0.4.0

package/dist/cli.js

@@ -2176,7 +2176,7 @@ function ensureSourceMarker(cwd, shell, framework) {
 }
 
 // src/guide.ts
-import { existsSync as existsSync11, readFileSync as readFileSync6, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync6, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
 import path9 from "path";
 
 // src/protect/install/util.ts
@@ -2193,8 +2193,8 @@ function hasDependency(cwd, name) {
     return false;
   }
 }
-function hasResolvableCredential(cwd) {
-  if ((process.env.PATCHSTACK_API_KEY ?? "") !== "" || (process.env.PATCHSTACK_PULSE_AUTH ?? "") !== "") {
+function hasResolvableCredential(cwd, env = process.env) {
+  if ((env.PATCHSTACK_API_KEY ?? "") !== "" || (env.PATCHSTACK_PULSE_AUTH ?? "") !== "") {
     return true;
   }
   for (const file of [".patchstackrc.local.json", ".patchstackrc.json"]) {
@@ -2209,6 +2209,9 @@ function hasResolvableCredential(cwd) {
 }
 var SITE_UUID_PLACEHOLDER = "__PATCHSTACK_SITE_UUID__";
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isSiteUuid(value) {
+  return typeof value === "string" && UUID_RE.test(value);
+}
 function bakeSiteUuid(cwd, guardRelPath) {
   const rc = join2(cwd, ".patchstackrc.json");
   if (!existsSync2(rc)) {
@@ -3487,6 +3490,121 @@ var expressAdapter = {
   verify: (cwd) => verifyRegister(cwd, SPEC6)
 };
 
+// src/protect/install/reporting.ts
+import { existsSync as existsSync10 } from "fs";
+import { join as join12 } from "path";
+
+// src/protect/reporting-state.js
+var REPORTING_STATES = Object.freeze([
+  /** Enrolled, managed rules, credential present, not opted out. Events are sent. */
+  "on",
+  /** `PATCHSTACK_REPORT_DETECTIONS=0`. An explicit, per-deployment opt-out. */
+  "disabled-by-config",
+  /** `PATCHSTACK_TELEMETRY=0`. The broader switch, which covers this along with everything else. */
+  "disabled-by-telemetry-opt-out",
+  /** No site identity: a local or unenrolled install. Nothing to report against. */
+  "not-enrolled",
+  /**
+   * A site identity, but the rules running are not the platform's — the caller's own bundle, or none.
+   * There is no managed rule document to attribute a detection to, so a report would name a rule id the
+   * platform never issued.
+   */
+  "no-managed-rules",
+  /** Enrolled with managed rules, but no credential resolved, so a report would be refused. */
+  "unavailable-no-credential"
+]);
+function optedOut(value) {
+  if (value === void 0 || value === null || value === "") return false;
+  return /^(0|false|off|no)$/i.test(String(value));
+}
+function reportingState(input) {
+  const env = input.env ?? (typeof process !== "undefined" ? process.env : void 0) ?? {};
+  if (input.configOptOut === true) return { state: "disabled-by-config", reports: false };
+  if (optedOut(env.PATCHSTACK_REPORT_DETECTIONS)) return { state: "disabled-by-config", reports: false };
+  if (optedOut(env.PATCHSTACK_TELEMETRY)) return { state: "disabled-by-telemetry-opt-out", reports: false };
+  const siteUuid = input.siteUuid;
+  if (typeof siteUuid !== "string" || siteUuid === "") return { state: "not-enrolled", reports: false };
+  if (input.hasCredential !== true) return { state: "unavailable-no-credential", reports: false };
+  const managed = input.ruleOrigin === "api" || input.ruleOrigin === "cache";
+  if (!managed) return { state: "no-managed-rules", reports: false };
+  return { state: "on", reports: true };
+}
+function explainReportingState(state) {
+  switch (state) {
+    case "on":
+      return "Security events are reported to Patchstack for this site.";
+    case "disabled-by-config":
+      return "Reporting is off because PATCHSTACK_REPORT_DETECTIONS is set to a false value.";
+    case "disabled-by-telemetry-opt-out":
+      return "Reporting is off because PATCHSTACK_TELEMETRY is set to a false value, which covers all telemetry.";
+    case "not-enrolled":
+      return "Reporting is off because this install has no site identity \u2014 it is not enrolled in Patchstack-managed mitigation.";
+    case "no-managed-rules":
+      return "Reporting is off because the rules in force did not come from Patchstack, so a detection could not be attributed to a managed rule.";
+    case "unavailable-no-credential":
+      return "Reporting is unavailable because no API credential resolved, so a report would be refused.";
+    default:
+      return `Unrecognised reporting state: ${String(state)}.`;
+  }
+}
+
+// src/protect/install/reporting.ts
+function siteIdentity(cwd, env) {
+  const rc = join12(cwd, ".patchstackrc.json");
+  let recorded;
+  if (existsSync10(rc)) {
+    try {
+      recorded = JSON.parse(read(rc)).siteUuid;
+    } catch {
+      recorded = void 0;
+    }
+  }
+  if (isSiteUuid(recorded)) return { uuid: recorded, found: true };
+  const fromEnv = env.PATCHSTACK_SITE_UUID;
+  if (isSiteUuid(fromEnv)) return { uuid: fromEnv, found: true };
+  const anything = typeof recorded === "string" && recorded !== "" || (fromEnv ?? "") !== "";
+  return { uuid: null, found: anything };
+}
+function reportingChecks(cwd, env = process.env) {
+  const { uuid: siteUuid, found: identityFound } = siteIdentity(cwd, env);
+  const hasCredential = hasResolvableCredential(cwd, env);
+  const { state } = reportingState({ siteUuid, hasCredential, ruleOrigin: "api", env });
+  const checks = [
+    {
+      group: "reporting",
+      label: "this app is enrolled (a site identity is recorded)",
+      ok: siteUuid !== null,
+      hint: identityFound ? "a site identity is recorded but is not a usable UUID \u2014 check `siteUuid` in .patchstackrc.json, or PATCHSTACK_SITE_UUID. The guard protects the app and reports nothing, because there is nothing to attribute a detection to." : "no site identity \u2014 run `npx @patchstack/connect scan` to provision one, or set PATCHSTACK_SITE_UUID in the deployment. Without it the guard protects the app but reports nothing."
+    }
+  ];
+  if (state === "on") {
+    checks.push({
+      group: "reporting",
+      label: "detection reporting is switched on for this environment",
+      ok: true,
+      unverifiable: true,
+      hint: "nothing here switches it off, but whether it actually reports depends on the rules the guard resolves at runtime: reporting is on for Patchstack-delivered rules and off for a bundle of your own (`no-managed-rules`). Read `protection.detectionReporting` in the running app for the settled answer. This also only judges the environment it ran in \u2014 a deployment may set an opt-out this machine cannot see."
+    });
+  } else {
+    checks.push({
+      group: "reporting",
+      label: `detection reporting is off for this environment (${state})`,
+      ok: state === "disabled-by-config" || state === "disabled-by-telemetry-opt-out",
+      hint: `${explainReportingState(state)} Judged from this environment only; a deployment's is not this one.`
+    });
+  }
+  checks.push({
+    group: "reporting",
+    // A wired guard says events CAN be sent. It says nothing about whether any were, or whether the
+    // platform took them, and this is where an operator would otherwise assume both.
+    label: "delivery health (events attempted, acknowledged, refused, dropped)",
+    ok: true,
+    unverifiable: true,
+    hint: "not observable from here \u2014 the counters live in the running guard. Call `protection.detectionHealth()` in the deployment: it is undefined when there is no reporter, and otherwise reports what was attempted, acknowledged, refused and dropped for queue pressure. A wired guard is not evidence that anything arrived."
+  });
+  return checks;
+}
+
 // src/protect/install/index.ts
 var ADAPTERS = [
   tanstackSupabaseAdapter,
@@ -3537,17 +3655,25 @@ function runVerify(cwd) {
     const adapter = ADAPTERS.find((a) => a.detect(cwd));
     if (adapter) {
       const result = adapter.verify(cwd);
-      return { stack: adapter.label, ...result, checks: [...result.checks, ...credentialNote(cwd, adapter.name)] };
+      return {
+        stack: adapter.label,
+        ...result,
+        checks: [...result.checks, ...credentialNote(cwd, adapter.name), ...reportingChecks(cwd)]
+      };
     }
     const generic = genericVerify(cwd);
-    return { stack: "generic", ...generic, checks: [...generic.checks, ...credentialNote(cwd, "generic")] };
+    return {
+      stack: "generic",
+      ...generic,
+      checks: [...generic.checks, ...credentialNote(cwd, "generic"), ...reportingChecks(cwd)]
+    };
   } catch (err) {
     return { stack: "unknown", wired: false, checks: [{ label: "verification failed", ok: false, hint: String(err?.message ?? err) }] };
   }
 }
 
 // src/widget.ts
-import { existsSync as existsSync10, readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "fs";
 import path8 from "path";
 var WIDGET_SCRIPT_URL = "https://cdn.patchstack.com/patchstack-widget.js";
 var WIDGET_MARKER_ATTR = "data-patchstack-connect-widget";
@@ -3586,7 +3712,7 @@ ${indent}</body>`;
 }
 function findSourceShell(cwd) {
   for (const candidate of SOURCE_SHELL_CANDIDATES) {
-    if (existsSync10(path8.join(cwd, candidate))) {
+    if (existsSync11(path8.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -3680,7 +3806,7 @@ function detectPackageManager(cwd) {
     return declared;
   }
   for (const { filename, pm } of PM_BY_LOCKFILE) {
-    if (existsSync11(path9.join(cwd, filename))) {
+    if (existsSync12(path9.join(cwd, filename))) {
       return pm;
     }
   }
@@ -3777,7 +3903,7 @@ function resolveWidgetFileHint(cwd, framework) {
     ...GENERIC_WIDGET_FILES
   ];
   for (const candidate of candidates) {
-    if (existsSync11(path9.join(cwd, candidate))) {
+    if (existsSync12(path9.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -4160,10 +4286,10 @@ import { writeFileSync as writeFileSync8 } from "fs";
 // src/map/ts-loader.ts
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 async function loadTypeScript(cwd) {
   try {
-    const req = createRequire(pathToFileURL(join12(cwd, "package.json")));
+    const req = createRequire(pathToFileURL(join13(cwd, "package.json")));
     const resolved = req.resolve("typescript");
     const mod = await import(pathToFileURL(resolved).href);
     return mod.default ?? mod;
@@ -4435,7 +4561,7 @@ function npmPackageOf(spec) {
 
 // src/map/sources.ts
 import { readFileSync as readFileSync8, readdirSync as readdirSync5, realpathSync, statSync as statSync3 } from "fs";
-import { join as join13, relative as relative2, isAbsolute } from "path";
+import { join as join14, relative as relative2, isAbsolute } from "path";
 
 // src/map/routes.ts
 var ROUTE_REGISTER_NAMES = ["get", "post", "put", "patch", "delete", "options", "all", "head", "use"];
@@ -4519,7 +4645,7 @@ function hasEntrySignal(text) {
 }
 function detectFramework(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync8(join13(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync8(join14(cwd, "package.json"), "utf8"));
     const d = { ...pkg.dependencies, ...pkg.devDependencies };
     if (d["@tanstack/react-start"] || d["@tanstack/start"] || d["@tanstack/solid-start"]) return "tanstack-start";
     if (d["next"]) return "next";
@@ -4531,11 +4657,11 @@ function detectFramework(cwd) {
   } catch {
   }
   try {
-    if (statSync3(join13(cwd, "supabase", "functions")).isDirectory()) return "supabase-functions";
+    if (statSync3(join14(cwd, "supabase", "functions")).isDirectory()) return "supabase-functions";
   } catch {
   }
   try {
-    if (statSync3(join13(cwd, "functions")).isDirectory()) return "deno-functions";
+    if (statSync3(join14(cwd, "functions")).isDirectory()) return "deno-functions";
   } catch {
   }
   return "unknown";
@@ -4577,7 +4703,7 @@ function probeForSource(dir, budget) {
   for (const e of entries) {
     if (budget.left-- <= 0) return "unknown";
     if (e.isDirectory()) {
-      if (!SKIP_IS_DEFINITIONAL.has(e.name)) dirs.push(join13(dir, e.name));
+      if (!SKIP_IS_DEFINITIONAL.has(e.name)) dirs.push(join14(dir, e.name));
     } else if (isSourceFile(e.name)) return true;
     else if (e.isSymbolicLink()) return "unknown";
   }
@@ -4614,13 +4740,13 @@ function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ ne
       const probeable = !SKIP_IS_DEFINITIONAL.has(e.name);
       if (probeable && !e.isDirectory() && e.isSymbolicLink()) stats.skippedUnknown++;
       else if (probeable && e.isDirectory()) {
-        const held = probeForSource(join13(dir, e.name), probeBudget);
-        if (held === true) stats.skippedWithSource.push(join13(dir, e.name));
+        const held = probeForSource(join14(dir, e.name), probeBudget);
+        if (held === true) stats.skippedWithSource.push(join14(dir, e.name));
         else if (held === "unknown") stats.skippedUnknown++;
       }
       continue;
     }
-    const full = join13(dir, e.name);
+    const full = join14(dir, e.name);
     if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats, probeBudget);
     else if (e.isSymbolicLink()) {
       let st, real;
@@ -4690,7 +4816,7 @@ function detectDeploymentShapes(cwd, opts = {}) {
   const found = [];
   for (const candidate of DEPLOYMENT_SHAPES) {
     for (const file of candidate.files ?? []) {
-      const full = join13(cwd, file);
+      const full = join14(cwd, file);
       try {
         if (statSync3(full).isFile() && inProject(full)) {
           found.push({ shape: candidate.shape, source: file, evidence: candidate.evidence });
@@ -4700,7 +4826,7 @@ function detectDeploymentShapes(cwd, opts = {}) {
       }
     }
     for (const dir of candidate.dirs ?? []) {
-      const full = join13(cwd, dir);
+      const full = join14(cwd, dir);
       try {
         if (!statSync3(full).isDirectory() || !inProject(full)) continue;
       } catch {
@@ -4719,7 +4845,7 @@ function holdsFunctionEntry(dir) {
     for (const entry of readdirSync5(dir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
       try {
-        for (const nested of readdirSync5(join13(dir, entry.name), { withFileTypes: true })) {
+        for (const nested of readdirSync5(join14(dir, entry.name), { withFileTypes: true })) {
           if (nested.isFile() && /^index\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(nested.name)) return true;
         }
       } catch {
@@ -4735,7 +4861,7 @@ function holdsSourceFile(dir) {
       if (entry.isFile() && isSourceFile(entry.name)) return true;
       if (entry.isDirectory()) {
         try {
-          for (const nested of readdirSync5(join13(dir, entry.name), { withFileTypes: true })) {
+          for (const nested of readdirSync5(join14(dir, entry.name), { withFileTypes: true })) {
             if (nested.isFile() && isSourceFile(nested.name)) return true;
           }
         } catch {
@@ -4749,7 +4875,7 @@ function holdsSourceFile(dir) {
 
 // src/map/surface.ts
 import { readFileSync as readFileSync9 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 var STATIC_GENERATORS = [
   { dep: "vite", label: "vite" },
   { dep: "react-scripts", label: "create-react-app" },
@@ -4787,7 +4913,7 @@ var SHAPE_SIGNAL = {
 };
 function readManifest(cwd) {
   try {
-    const parsed = JSON.parse(readFileSync9(join14(cwd, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync9(join15(cwd, "package.json"), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
@@ -4800,7 +4926,7 @@ function nextExportsStatically(cwd, manifest, ts) {
   for (const file of ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"]) {
     let text;
     try {
-      text = readFileSync9(join14(cwd, file), "utf8");
+      text = readFileSync9(join15(cwd, file), "utf8");
     } catch {
       continue;
     }
@@ -5212,7 +5338,7 @@ function dedupeSinks(sinks, owner) {
 
 // src/map/module-graph.ts
 import { readFileSync as readFileSync10, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
-import { dirname as dirname7, join as join15, relative as relative3, resolve as resolvePath } from "path";
+import { dirname as dirname7, join as join16, relative as relative3, resolve as resolvePath } from "path";
 var RESOLVE_EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 function createModuleGraph(ts, opts) {
   const cache = /* @__PURE__ */ new Map();
@@ -5290,7 +5416,7 @@ function resolveRelativeModule(fromFile, spec) {
   }
   candidates.push(base);
   for (const e of RESOLVE_EXTS) candidates.push(base + e);
-  for (const e of RESOLVE_EXTS) candidates.push(join15(base, "index" + e));
+  for (const e of RESOLVE_EXTS) candidates.push(join16(base, "index" + e));
   for (const c of candidates) {
     try {
       if (statSync4(c).isFile()) return c;
@@ -5974,7 +6100,7 @@ function handlerEntry(name, kindLabel, params, body, ts, localSinks, bindings, c
 
 // src/map/imports.ts
 import { readFileSync as readFileSync11 } from "fs";
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 var MAX_SITES = 5;
 var NPM_NAME = /^(?:@[^/@\s~][^/@\s]*\/)?[^/@\s.~][^/@\s]*$/;
 function isNpmPackageName(pkg) {
@@ -5985,7 +6111,7 @@ function readPathAliases(cwd) {
   for (const name of ["tsconfig.json", "jsconfig.json"]) {
     let paths;
     try {
-      const raw = readFileSync11(join16(cwd, name), "utf8");
+      const raw = readFileSync11(join17(cwd, name), "utf8");
       const parsed = JSON.parse(stripJsonComments(raw));
       paths = parsed.compilerOptions?.paths;
     } catch {
@@ -7213,12 +7339,18 @@ async function runProtectCommand(args) {
   if (args.flags.get("check") === true) {
     const report = runVerify(process.cwd());
     console.log(`patchstack protect --check (${report.stack}):`);
-    for (const c of report.checks) {
+    const line = (c) => {
       const mark = c.unverifiable ? "?" : c.ok ? "\u2713" : "\u2717";
       const note = c.unverifiable || !c.ok ? c.hint : void 0;
       console.log(`  ${mark} ${c.label}${note ? ` \u2014 ${note}` : ""}`);
-    }
+    };
+    for (const c of report.checks.filter((c2) => c2.group !== "reporting")) line(c);
     console.log(report.wired ? "guard is wired \u2713" : "guard is NOT fully wired \u2717");
+    const reporting = report.checks.filter((c) => c.group === "reporting");
+    if (reporting.length > 0) {
+      console.log("reporting to Patchstack (does not affect the verdict above):");
+      for (const c of reporting) line(c);
+    }
     if (report.checks.some((c) => c.unverifiable)) {
       console.log("One or more checks could not be answered from here \u2014 see the `?` lines above.");
     }