@patchstack/connect 0.4.0 → 0.4.1

package/dist/protect.d.cts

@@ -168,8 +168,19 @@ export interface CreateProtectionOptions {
    *
    * What it sends on EVERY detection: the rule id and its revision, the request path, the query string's
    * parameter NAMES, the method, the parameters the rule reads, the phase, whether it was enforced, the
-   * rule-bundle ETag, and a timestamp — plus the values of the parameters the matched rule names, under a
-   * capture plan derived from that rule.
+   * rule-bundle ETag, a timestamp, the rule's category and the action it declares, and which call it
+   * belongs to — plus the values of the parameters the matched rule names, under a plan derived from
+   * that rule.
+   *
+   * The category and the declared action say what KIND of rule matched. Both are read from the rule
+   * itself and are `null` when it declares neither. Neither is the same as `enforced`:
+   * a rule declaring `block` while only observing reports that action with `enforced` false.
+   *
+   * Which call it belongs to is a token this guard mints and repeats on every rule that matched the same
+   * request or outbound call, so one call seen by two rules can be told from two calls. Nothing about
+   * the request goes into it — it is drawn from the runtime's randomness, or from the clock and
+   * `Math.random` where there is none. A request and its response share one; an outbound call gets its
+   * own. It is never a secret and never a boundary: what it has to do is not collide between two calls.
    *
    * Two fields depend on the phase. A request or response detection also carries the user agent and the
    * client address with its provenance. An egress detection carries neither: the call was the

package/dist/protect.d.ts

@@ -168,8 +168,19 @@ export interface CreateProtectionOptions {
    *
    * What it sends on EVERY detection: the rule id and its revision, the request path, the query string's
    * parameter NAMES, the method, the parameters the rule reads, the phase, whether it was enforced, the
-   * rule-bundle ETag, and a timestamp — plus the values of the parameters the matched rule names, under a
-   * capture plan derived from that rule.
+   * rule-bundle ETag, a timestamp, the rule's category and the action it declares, and which call it
+   * belongs to — plus the values of the parameters the matched rule names, under a plan derived from
+   * that rule.
+   *
+   * The category and the declared action say what KIND of rule matched. Both are read from the rule
+   * itself and are `null` when it declares neither. Neither is the same as `enforced`:
+   * a rule declaring `block` while only observing reports that action with `enforced` false.
+   *
+   * Which call it belongs to is a token this guard mints and repeats on every rule that matched the same
+   * request or outbound call, so one call seen by two rules can be told from two calls. Nothing about
+   * the request goes into it — it is drawn from the runtime's randomness, or from the clock and
+   * `Math.random` where there is none. A request and its response share one; an outbound call gets its
+   * own. It is never a secret and never a boundary: what it has to do is not collide between two calls.
    *
    * Two fields depend on the phase. A request or response detection also carries the user agent and the
    * client address with its provenance. An egress detection carries neither: the call was the

package/dist/protect.edge.js

@@ -3223,6 +3223,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" } }]
   }
 ];
@@ -3589,10 +3594,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;
@@ -4052,6 +4072,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],
@@ -4059,6 +4081,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,
@@ -4079,7 +4107,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",
@@ -4701,8 +4754,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,
@@ -4715,6 +4769,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,
@@ -4846,7 +4903,7 @@ async function createProtection(options = {}) {
       result,
       () => blockResponse(result, request),
       () => null,
-      requestMeta(shaped, request)
+      () => requestMeta(shaped, request)
     );
     return { blocked, client: shaped?._clientIp };
   };
@@ -4861,7 +4918,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;
@@ -4872,7 +4934,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);
@@ -5119,6 +5184,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;
@@ -5136,6 +5202,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)
@@ -5211,7 +5285,7 @@ async function createProtection(options = {}) {
             if (exprOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req, client));
             next();
           },
-          nodeRequestMeta(req, client)
+          () => nodeRequestMeta(req, client)
         );
       };
     },
@@ -5275,7 +5349,7 @@ async function createProtection(options = {}) {
             if (nodeOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req, shaped?._clientIp));
             next();
           },
-          nodeRequestMeta(req, shaped?._clientIp)
+          () => nodeRequestMeta(req, shaped?._clientIp)
         );
       }
     }
@@ -5749,11 +5823,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,
@@ -5777,7 +5877,7 @@ function requestMeta(shaped, request) {
     method = request.method ?? null;
     userAgent = request.headers?.get?.("user-agent") ?? null;
   }
-  return { method, path, ip: client.ip, clientIpSource: client.source, userAgent };
+  return { method, path, ip: client.ip, clientIpSource: client.source, userAgent, event: eventFor(request) };
 }
 function nodeRequestMeta(req, client) {
   if (!req) return {};
@@ -5791,7 +5891,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)
   };
 }
 export {