@patchstack/connect 0.4.0 → 0.4.1

package/dist/protect.cjs

@@ -4736,6 +4736,11 @@ var DEFAULT_EGRESS_RULES = [
     title: "Outbound request to an internal / metadata address (SSRF)",
     phase: "egress",
     category: "ssrf",
+    // Declared, not implied. Nothing in the egress path reads it — a match refuses the call, and the
+    // rule's mode decides whether it actually did — but the action is part of how a rule describes
+    // itself to whatever reports on it, and a rule that declares nothing is reported as a rule nobody
+    // can classify.
+    action: "block",
     rule_v2: [{ parameter: "egress.host", match: { type: "internal_host" } }]
   }
 ];
@@ -5103,10 +5108,25 @@ function worthRetrying(status) {
 }
 var ATTEMPT_TIMEOUT_MS = 1e4;
 var STOP_BUDGET_MS = 5e3;
+var CATEGORY_PATTERN = /^[a-z][a-z0-9-]*$/;
+var RESERVED_CATEGORY = "unknown";
+function declaredClass(declared, recognised) {
+  if (typeof declared !== "string" || declared === "") return { value: null, dropped: false };
+  if (!recognised(declared)) return { value: null, dropped: false };
+  if (declared.length > MAX_CLASS_CHARS) return { value: null, dropped: true };
+  return { value: declared, dropped: false };
+}
+var recognisedCategory = (value) => value !== RESERVED_CATEGORY && CATEGORY_PATTERN.test(value);
+var recognisedAction = (value) => ACTIONS.includes(value);
 var MAX_ROUTE_CHARS = 256;
 var MAX_PARAMETERS = 25;
 var MAX_PARAMETER_CHARS = 64;
 var MAX_IDENTIFIER_CHARS = 256;
+var MAX_CLASS_CHARS = 64;
+var EVENT_PATTERN = /^[0-9a-f]{32}$/;
+function eventIdentity(value) {
+  return typeof value === "string" && EVENT_PATTERN.test(value) ? value : null;
+}
 var MAX_CAPTURED_VALUES = 10;
 var MAX_CAPTURED_VALUE_CHARS = 512;
 var MAX_QUERY_KEYS = 10;
@@ -5566,6 +5586,8 @@ function createDetectionReporter(opts) {
       const id = capText(String(ruleId), MAX_IDENTIFIER_CHARS);
       const revision = capText(revisionOf(detection.rule) ?? "", MAX_IDENTIFIER_CHARS);
       const etag = capText(rulesEtag ?? "", MAX_IDENTIFIER_CHARS);
+      const classCategory = declaredClass(detection.rule?.category, recognisedCategory);
+      const classAction = declaredClass(detection.rule?.action, recognisedAction);
       for (const [name, field] of [
         ["rule_id", id],
         ["rule_revision", revision],
@@ -5573,6 +5595,12 @@ function createDetectionReporter(opts) {
       ]) {
         if (field.truncated) truncated.push(name);
       }
+      for (const [name, field] of [
+        ["category", classCategory],
+        ["action", classAction]
+      ]) {
+        if (field.dropped) truncated.push(name);
+      }
       queue.push({
         rule_id: id.value,
         route: route.value,
@@ -5593,7 +5621,32 @@ function createDetectionReporter(opts) {
         ...query.total > queryKeys.length ? { query_keys_total: query.total } : {},
         // Who asked. Capped, since it is client-supplied text and this is an event with a size bound.
         user_agent: userAgent === null ? null : userAgent.value,
+        // What KIND of match this was: which phase it happened in, what class of thing the rule is for,
+        // and what the rule DECLARES it does about it.
+        //
+        // Three separate facts, and none of them is `enforced` below. A rule declaring `block` while
+        // observing reports exactly that — `action: 'block'`, `enforced: false` — which is what a
+        // dry-run window consists of. Reading either off the other would describe such a window as
+        // protection that never happened, or as rules that do nothing.
+        //
+        // `null` where the rule says nothing, never a guess. A consumer can tell "this rule is for
+        // secret exposure" from "we cannot say what this rule is for", and a filled-in value would take
+        // that distinction away for the sake of a tidier field.
         phase: detection.phase ?? null,
+        // `null` where the rule declared nothing, and also where what it declared could not be carried:
+        // both are "we cannot say what this rule is for", which is a different fact from a class we do
+        // know, and `truncated` distinguishes the second from the first.
+        category: classCategory.value,
+        action: classAction.value,
+        // Which call this detection belongs to, so a consumer can tell one call two rules saw from two
+        // separate calls. Two rules matching one call is the ordinary case — a rule that enforces and a
+        // rule that only observes are meant to match the same thing — so without this, adding these up
+        // reports one call more than once.
+        //
+        // Nothing about the request goes into it: it is only ever compared with other identities, so
+        // deriving it from the address or the path would carry something about whoever made the request
+        // into a place nothing needs it. That is a property of how it is minted, not of its shape.
+        event: eventIdentity(detection.event),
         // 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",
@@ -6215,8 +6268,9 @@ async function createProtection(options = {}) {
     if (!permitsAnything(entry.plan)) return { plan: entry.reference };
     return { plan: entry.reference, ...captureValues(entry.plan, result.resolver) };
   };
-  const decide = (phase, result, block, allow2, ctx = {}) => {
+  const decide = (phase, result, block, allow2, describe = () => ({})) => {
     if (!result || !result.blocked) return allow2();
+    const ctx = describe() ?? {};
     const effectiveMode = ruleMode(result.rule);
     onDetect({
       phase,
@@ -6229,6 +6283,9 @@ async function createProtection(options = {}) {
       method: ctx.method,
       path: ctx.path,
       ip: ctx.ip,
+      // Which call this was. Named here rather than spread from `ctx` for the same reason as everything
+      // else in this payload: a field reaches the wire because someone listed it.
+      event: ctx.event ?? null,
       // Provenance travels with the address. Without it a consumer cannot tell an observed peer from a
       // value read out of a forwarded header, and `null` from "there was no address to establish".
       clientIpSource: ctx.clientIpSource,
@@ -6360,7 +6417,7 @@ async function createProtection(options = {}) {
       result,
       () => blockResponse(result, request),
       () => null,
-      requestMeta(shaped, request)
+      () => requestMeta(shaped, request)
     );
     return { blocked, client: shaped?._clientIp };
   };
@@ -6375,7 +6432,12 @@ async function createProtection(options = {}) {
         originalUrl: u.pathname + u.search,
         headers,
         ip: resolved.ip ?? "",
-        _clientIp: resolved
+        _clientIp: resolved,
+        // The request itself, so the identity can be asked for LATER. This context is built on every
+        // request whether or not anything matches, so asking here would mint one for every request —
+        // and asking of the context rather than of the request would give the response a different
+        // identity from the request that caused it, reporting one call as two.
+        _eventOf: request
       };
     } catch {
       return void 0;
@@ -6386,7 +6448,10 @@ async function createProtection(options = {}) {
     originalUrl: req.url,
     headers: req.headers || {},
     ip: client?.ip ?? "",
-    _clientIp: client ?? { ip: null, source: "unavailable" }
+    _clientIp: client ?? { ip: null, source: "unavailable" },
+    // The request itself, for the same reasons as on the fetch path above: asked for later, and
+    // asked of the request rather than of this context.
+    _eventOf: req
   } : void 0;
   const screenResp = async (response, reqCtx) => {
     const read = await readTextResponse(response, screenCap);
@@ -6633,6 +6698,7 @@ async function createProtection(options = {}) {
     } catch {
       egressPath = typeof url === "string" ? url : null;
     }
+    const egressEvent = mintEvent();
     let block = false;
     for (const { rule, engine: re } of egressRuleSet) {
       let result;
@@ -6650,6 +6716,14 @@ async function createProtection(options = {}) {
         category: rule?.category,
         rule,
         message: result.message,
+        // One identity for this outbound call, shared by every rule that matches it — the egress phase
+        // evaluates all of them rather than stopping at the first, so without this two rules refusing one
+        // call would count as two calls refused.
+        //
+        // Its own identity, not the identity of whatever request the application was serving when it made
+        // the call. An outbound attempt is a thing that happened in its own right, and a call made outside
+        // any request — a job, a timer — has no request to belong to.
+        event: egressEvent,
         method: typeof method === "string" ? method : null,
         path: egressPath,
         capture: evidenceFrom(result)
@@ -6725,7 +6799,7 @@ async function createProtection(options = {}) {
             if (exprOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req, client));
             next();
           },
-          nodeRequestMeta(req, client)
+          () => nodeRequestMeta(req, client)
         );
       };
     },
@@ -6789,7 +6863,7 @@ async function createProtection(options = {}) {
             if (nodeOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req, shaped?._clientIp));
             next();
           },
-          nodeRequestMeta(req, shaped?._clientIp)
+          () => nodeRequestMeta(req, shaped?._clientIp)
         );
       }
     }
@@ -7263,11 +7337,37 @@ function defaultOnDetect({ phase, mode, category, rule, message }) {
   const tag = mode === "block" ? "BLOCK" : "DETECT (dry-run)";
   console.warn(`[patchstack] ${tag} phase=${phase ?? "request"} category=${category ?? "?"} rule=${rule?.id ?? "?"} ${message ?? ""}`.trim());
 }
+var eventIdentities = /* @__PURE__ */ new WeakMap();
+function mintEvent() {
+  try {
+    const bytes = globalThis.crypto?.getRandomValues?.(new Uint8Array(16));
+    if (bytes) return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  } catch {
+  }
+  try {
+    let hex = Date.now().toString(16);
+    while (hex.length < 32) hex += Math.floor(Math.random() * 4294967295).toString(16).padStart(8, "0");
+    return hex.slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+function eventFor(request) {
+  if (request === null || typeof request !== "object") return mintEvent();
+  const existing = eventIdentities.get(request);
+  if (existing !== void 0) return existing;
+  const minted = mintEvent();
+  if (minted !== null) eventIdentities.set(request, minted);
+  return minted;
+}
 function requestMetaFromContext(reqCtx) {
   if (!reqCtx) return {};
   const client = reqCtx._clientIp ?? { ip: null, source: "unavailable" };
   return {
     method: reqCtx.method ?? null,
+    // The originating request's identity, so a response detection and the request detection for the same
+    // request are one event rather than two. Asked for here, which is inside a detection being raised.
+    event: eventFor(reqCtx._eventOf),
     // Path AND query. The reporter is what drops the query's VALUES, keeping its parameter names, so
     // trimming it here would leave a Fetch or response detection unable to say what was requested.
     path: typeof reqCtx.originalUrl === "string" ? reqCtx.originalUrl : null,
@@ -7291,7 +7391,7 @@ function requestMeta(shaped, request) {
     method = request.method ?? null;
     userAgent = request.headers?.get?.("user-agent") ?? null;
   }
-  return { method, path: path7, ip: client.ip, clientIpSource: client.source, userAgent };
+  return { method, path: path7, ip: client.ip, clientIpSource: client.source, userAgent, event: eventFor(request) };
 }
 function nodeRequestMeta(req, client) {
   if (!req) return {};
@@ -7305,7 +7405,8 @@ function nodeRequestMeta(req, client) {
     // verified, and a second derivation could disagree with the one the engine evaluated.
     ip: resolved.ip,
     clientIpSource: resolved.source,
-    userAgent: typeof ua === "string" ? ua : Array.isArray(ua) ? ua[0] : null
+    userAgent: typeof ua === "string" ? ua : Array.isArray(ua) ? ua[0] : null,
+    event: eventFor(req)
   };
 }
 // Annotate the CommonJS export names for ESM import in node: