@patchstack/connect 0.5.15 → 0.5.17

package/dist/protect.d.cts

@@ -15,8 +15,9 @@ export interface Protection {
   mode: "block" | "dry-run";
   /** Active rules split by phase. */
   rules: { request: unknown[]; response: unknown[]; egress: unknown[] };
-  /** (request) => Response (403 when blocked) | null (allow / dry-run). Request phase only. */
-  fetchGuard(): (request: Request) => Promise<Response | null>;
+  /** (request, ...hostArgs) => Response (403 when blocked) | null (allow / dry-run). Request phase only.
+   *  Any further arguments are the host's handler arguments, passed on to `peerAddress`. */
+  fetchGuard(): (request: Request, ...hostArgs: unknown[]) => Promise<Response | null>;
   /** Screens the request, then the response (secret-leak redaction / withhold). */
   fetch(handler: (request: Request, ...rest: unknown[]) => unknown): (request: Request, ...rest: unknown[]) => Promise<unknown>;
   /**
@@ -25,11 +26,30 @@ export interface Protection {
    * Pass the originating `request` wherever it is available. A response rule can be scoped to a route or a
    * method (`when`), and that scope can only be applied if the engine is given the request the response
    * belongs to — without it, a scoped response rule is delivered, counted as protection, and never matches.
+   *
+   * The client address is the one resolved when this guard screened that request, if it did; otherwise it
+   * is resolved here, and any further arguments are passed to `peerAddress` as the host's handler arguments.
+   *
+   * A rule that reads only response headers (`response.header.*`, `response.headers`) redacts or blocks on
+   * the headers alone, so it is enforced even when the body cannot be screened. A redaction masks only the
+   * header value it matched; protecting the body takes a rule on `response.body`, which masks the body and
+   * the same text wherever it appears in a header. A withheld response carries only its own `content-type`
+   * and `content-length`.
    */
-  screenResponse(response: Response, request?: Request): Promise<Response>;
+  screenResponse(response: Response, request?: Request, ...hostArgs: unknown[]): Promise<Response>;
   express(options?: { screenResponses?: boolean }): (req: unknown, res: unknown, next: () => void) => void;
+  /**
+   * Node / Connect middleware that reads the request body itself and exposes it as `req.body`.
+   *
+   * A body longer than `maxBodyBytes` (default 1 MiB) has its first `maxBodyBytes` screened, is counted as
+   * a `body-cap` skip in `coverage()` / `onSkip`, and is not exposed as `req.body`.
+   */
   node(options?: { maxBodyBytes?: number; screenResponses?: boolean }): (req: unknown, res: unknown, next: () => void) => void;
-  /** Present when `egress: true` — restores the original global fetch. */
+  /** Present when `egress: true` — removes this protection's outbound screen. Outbound calls are
+   *  screened by every protection that has one registered, and any one of them can refuse a call:
+   *  a host in one protection's `allowHosts` is still refused when another protection refuses it.
+   *  When the last one leaves, the original `fetch` and `node:http`/`node:https` functions are
+   *  restored. `stop()` calls this too; `stopRefresh()` does not. */
   uninstallEgress?: () => void;
   /** Present with a live source — re-fetch + hot-swap the rules once (used by the loop + push).
    *  Resolves with the outcome of the attempt: `ok: false` means the rules in force came from the
@@ -46,7 +66,8 @@ export interface Protection {
    *  the configured refresh secret (a push/zero-day trigger). No secret set → the handler 404s. */
   refreshHandler?: () => (request: Request) => Promise<Response>;
   /** Stops everything with a timer or a buffer behind it: the refresh loop, the block log, the
-   *  detection reporter (flushing what it holds). Always present, and safe to call twice. */
+   *  detection reporter (flushing what it holds), and this protection's outbound screen. Always
+   *  present, and safe to call twice. */
   /**
    * Stop everything holding a timer or a buffer.
    *
@@ -62,12 +83,19 @@ export interface Protection {
    *   reporter is finished with it, not that the underlying request has ended.
    * - A runtime that terminates the process regardless still wins, whatever this resolves.
    *
-   * What is accounted for also differs by reporter. Every detection event ends up delivered, refused or
-   * dropped, and `detectionHealth()` reports each. Block-log records have no counters at all, so one lost
-   * to a failed token exchange, a failed post, or a shutdown that ran out of time is reported nowhere.
+   * Both reporters account for what they held. Every detection event ends up delivered, refused or
+   * dropped, and `detectionHealth()` reports each; every block-log record ends up delivered, failed or
+   * dropped, and `blockLogHealth()` reports those.
    */
   stop: () => Promise<void>;
-  /** Alias of `stop`, under the name callers already have. */
+  /**
+   * How often the guard passed something through without inspecting it, in the cases it can observe,
+   * keyed `<phase>:<reason>` (for example `request:body-cap`, `response:live-stream`). Zero skips means
+   * nothing the guard could see was bypassed, not that nothing was.
+   */
+  coverage(): { skipped: Record<string, number> };
+  /** Stops the rule refresh only — the poll loop and its recovery retries. The reporters and this
+   *  protection's outbound screening keep running; use `stop()` to end those too. */
   stopRefresh: () => Promise<void>;
   /**
    * Where the rules in force came from, and whether the most recent resolution was clean — the same
@@ -128,6 +156,20 @@ export interface Protection {
       lastAcknowledgedAt: string | null;
     };
   };
+  /** Present when block-log reporting is on — where the block records went, in records. Carries no
+   *  request data. */
+  blockLogHealth?: () => {
+    /** Records the queue accepted. Each ends up delivered, failed, or dropped by a shutdown. */
+    recorded: number;
+    /** Records in a batch the endpoint acknowledged. */
+    delivered: number;
+    /** Records in a batch that was refused, or that could not be sent (including a failed token exchange). */
+    failed: number;
+    /** Records a shutdown discarded, plus records turned away because the queue was full. */
+    dropped: number;
+    /** Records waiting to be sent now. */
+    queued: number;
+  };
 }
 
 /**
@@ -233,7 +275,8 @@ export interface CreateProtectionOptions {
   detectionFlushMs?: number;
   /** Optional Source-Host header for connector hostname checks. */
   sourceHost?: string;
-  /** Optional fetch override (tests). */
+  /** Optional fetch override for the block-log and detection reporters (tests). The rules client and
+   *  the manifest re-post use the global `fetch`. */
   fetchImpl?: typeof fetch;
   /**
    * Re-fetch and hot-swap the live rules every N ms. For long-lived runtimes that aren't restarted
@@ -252,7 +295,8 @@ export interface CreateProtectionOptions {
    * During a refresh, also re-post the dependency manifest (the runtime counterpart to `scan`) so a
    * dependency added after boot — e.g. via `npm install <pkg>`, which fires no npm lifecycle hook —
    * is reported and enforced without a restart. Defaults on when a `siteUuid` is set; set false to
-   * refresh rules only. Only meaningful with `refreshMs > 0` and a Pulse `siteUuid`.
+   * refresh rules only. Only meaningful with a Pulse `siteUuid` and a refresh path: `refreshMs > 0` or a
+   * refresh secret. A manual `refresh()` re-posts too when either is configured.
    */
   reportManifest?: boolean;
   /** Directory the manifest re-scan reads the lockfile from during a refresh. Default process.cwd(). */
@@ -273,11 +317,20 @@ export interface CreateProtectionOptions {
     read(): unknown | Promise<unknown>;
     write(envelope: unknown): unknown | Promise<unknown>;
   };
+  /**
+   * The transport peer of a Fetch request, for runtimes where the host knows it and the `Request` does
+   * not — e.g. `(req, info) => info.remoteAddr.hostname` on Deno, `(req, server) => server.requestIP(req)?.address`
+   * on Bun. Called with the request the host served and the arguments its handler received (passed through
+   * `fetch(handler)`, `fetchGuard()(request, ...args)` and `screenResponse(response, request, ...args)`).
+   * The result counts as the peer for client address resolution, including `trustedProxy`. A throw, or a result that is not an address, supplies no peer.
+   */
+  peerAddress?: (request: Request, ...hostArgs: unknown[]) => string | null | undefined;
   /**
    * Declare which peers are this deployment's own reverse proxies, so a forwarded header can be believed.
    *
-   * With no policy, the client address is whatever the transport observed — the socket peer on Node, and
-   * nothing at all in a runtime that exposes no peer, where the provenance reads `unavailable`. A
+   * With no policy, the client address is whatever the transport observed — the socket peer on Node, the
+   * `peerAddress` result on a Fetch runtime, and nothing at all where neither is available, in which case
+   * the provenance reads `unavailable` (and, with a policy set, the guard warns once). A
    * forwarded header is never trusted implicitly: it is ordinary request input that any caller can send.
    *
    * A policy must say WHO is trusted, not just which header to read. Declare at least one of:
@@ -305,7 +358,40 @@ export interface CreateProtectionOptions {
     header?: string;
     isTrusted?: (ip: string) => boolean;
   };
-  /** Override the default response-phase (secret-leak) rule set. */
+  /** How long the boot-time rules fetch may take before the guard starts on its cache or bundled
+   *  fallback. Default 5000ms. Refreshes use `refreshTimeoutMs`. */
+  bootTimeoutMs?: number;
+  /** How long a refresh's rules fetch may take. Default 30000ms. */
+  refreshTimeoutMs?: number;
+  /** Largest request body the Fetch path buffers for inspection. A larger body is passed through
+   *  uninspected and counted as a `request:body-cap` skip. Default 1 MiB. The Node guard takes its own
+   *  `node({ maxBodyBytes })`. */
+  maxBodyBytes?: number;
+  /**
+   * Apply the valid part of a live rules update when some of its rules fail validation. By default the
+   * whole update is refused, the previous rules stay in force and the response is not cached; either
+   * way every rejected rule is reported through `onRuleRejected`.
+   */
+  acceptPartialBundle?: boolean;
+  /** Permit whitelist entries with no `rule_id`, which apply to every rule. Refused by default. */
+  allowGlobalWhitelists?: boolean;
+  /** Called for each delivered rule that failed validation and is not enforced. Without it, rejections
+   *  are written to the console. */
+  onRuleRejected?: (rejection: { id: string | number; reason: string; accepted?: boolean }) => void;
+  /** Called each time the guard passes something through without inspecting it (an oversized or
+   *  encoded body, a live stream, a binary body, an outbound call it could not resolve). `detail` carries
+   *  operational context such as sizes and hostnames — keep it server-side. `protection.coverage()`
+   *  holds the running counts. */
+  onSkip?: (skip: {
+    phase: Phase;
+    reason: string;
+    detail?: Record<string, unknown>;
+    count: number;
+  }) => void;
+  /**
+   * Override the default response-phase (secret-leak) rule set. A rule that reads only response headers is
+   * enforced from the headers, and masks only the header it matched — see `screenResponse`.
+   */
   responseRules?: unknown[];
   /** Override the default egress-phase (SSRF) rule set. */
   egressRules?: unknown[];
@@ -346,7 +432,15 @@ export interface CreateProtectionOptions {
    * only active when `egress` is on and node:dns is available (a no-op on edge runtimes).
    */
   screenDns?: boolean;
-  /** Redaction mask (string or per-category function). Default "[REDACTED]". */
+  /**
+   * Redaction mask (string or per-category function). Default "[REDACTED]".
+   *
+   * In a JSON response, a text-span redaction or encoding may change string values only. When a
+   * rewrite in `block` mode would change the document's structure instead — a match inside a key
+   * name or across fields, a bare number or literal, or a mask that leaves the document invalid — the
+   * whole response is withheld rather than masked. Structural `array_key_value` masking replaces the
+   * leaf it targets, and keeps every other value, including each number, exactly as it was spelled.
+   */
   maskWith?: string | ((category?: string) => string);
   /**
    * Operational problems the guard handled without failing a request. Without it, rules that are not
@@ -385,7 +479,7 @@ export function createSupabaseGuard(opts: {
   maxBodyBytes?: number;
   /** Maximum upstream request duration. Default 30 seconds. */
   timeoutMs?: number;
-}): (request: Request) => Promise<Response>;
+}): (request: Request, ...hostArgs: unknown[]) => Promise<Response>;
 
 /**
  * Server-function guard: inspect a TanStack server function's decoded args against the same

package/dist/protect.d.ts

@@ -15,8 +15,9 @@ export interface Protection {
   mode: "block" | "dry-run";
   /** Active rules split by phase. */
   rules: { request: unknown[]; response: unknown[]; egress: unknown[] };
-  /** (request) => Response (403 when blocked) | null (allow / dry-run). Request phase only. */
-  fetchGuard(): (request: Request) => Promise<Response | null>;
+  /** (request, ...hostArgs) => Response (403 when blocked) | null (allow / dry-run). Request phase only.
+   *  Any further arguments are the host's handler arguments, passed on to `peerAddress`. */
+  fetchGuard(): (request: Request, ...hostArgs: unknown[]) => Promise<Response | null>;
   /** Screens the request, then the response (secret-leak redaction / withhold). */
   fetch(handler: (request: Request, ...rest: unknown[]) => unknown): (request: Request, ...rest: unknown[]) => Promise<unknown>;
   /**
@@ -25,11 +26,30 @@ export interface Protection {
    * Pass the originating `request` wherever it is available. A response rule can be scoped to a route or a
    * method (`when`), and that scope can only be applied if the engine is given the request the response
    * belongs to — without it, a scoped response rule is delivered, counted as protection, and never matches.
+   *
+   * The client address is the one resolved when this guard screened that request, if it did; otherwise it
+   * is resolved here, and any further arguments are passed to `peerAddress` as the host's handler arguments.
+   *
+   * A rule that reads only response headers (`response.header.*`, `response.headers`) redacts or blocks on
+   * the headers alone, so it is enforced even when the body cannot be screened. A redaction masks only the
+   * header value it matched; protecting the body takes a rule on `response.body`, which masks the body and
+   * the same text wherever it appears in a header. A withheld response carries only its own `content-type`
+   * and `content-length`.
    */
-  screenResponse(response: Response, request?: Request): Promise<Response>;
+  screenResponse(response: Response, request?: Request, ...hostArgs: unknown[]): Promise<Response>;
   express(options?: { screenResponses?: boolean }): (req: unknown, res: unknown, next: () => void) => void;
+  /**
+   * Node / Connect middleware that reads the request body itself and exposes it as `req.body`.
+   *
+   * A body longer than `maxBodyBytes` (default 1 MiB) has its first `maxBodyBytes` screened, is counted as
+   * a `body-cap` skip in `coverage()` / `onSkip`, and is not exposed as `req.body`.
+   */
   node(options?: { maxBodyBytes?: number; screenResponses?: boolean }): (req: unknown, res: unknown, next: () => void) => void;
-  /** Present when `egress: true` — restores the original global fetch. */
+  /** Present when `egress: true` — removes this protection's outbound screen. Outbound calls are
+   *  screened by every protection that has one registered, and any one of them can refuse a call:
+   *  a host in one protection's `allowHosts` is still refused when another protection refuses it.
+   *  When the last one leaves, the original `fetch` and `node:http`/`node:https` functions are
+   *  restored. `stop()` calls this too; `stopRefresh()` does not. */
   uninstallEgress?: () => void;
   /** Present with a live source — re-fetch + hot-swap the rules once (used by the loop + push).
    *  Resolves with the outcome of the attempt: `ok: false` means the rules in force came from the
@@ -46,7 +66,8 @@ export interface Protection {
    *  the configured refresh secret (a push/zero-day trigger). No secret set → the handler 404s. */
   refreshHandler?: () => (request: Request) => Promise<Response>;
   /** Stops everything with a timer or a buffer behind it: the refresh loop, the block log, the
-   *  detection reporter (flushing what it holds). Always present, and safe to call twice. */
+   *  detection reporter (flushing what it holds), and this protection's outbound screen. Always
+   *  present, and safe to call twice. */
   /**
    * Stop everything holding a timer or a buffer.
    *
@@ -62,12 +83,19 @@ export interface Protection {
    *   reporter is finished with it, not that the underlying request has ended.
    * - A runtime that terminates the process regardless still wins, whatever this resolves.
    *
-   * What is accounted for also differs by reporter. Every detection event ends up delivered, refused or
-   * dropped, and `detectionHealth()` reports each. Block-log records have no counters at all, so one lost
-   * to a failed token exchange, a failed post, or a shutdown that ran out of time is reported nowhere.
+   * Both reporters account for what they held. Every detection event ends up delivered, refused or
+   * dropped, and `detectionHealth()` reports each; every block-log record ends up delivered, failed or
+   * dropped, and `blockLogHealth()` reports those.
    */
   stop: () => Promise<void>;
-  /** Alias of `stop`, under the name callers already have. */
+  /**
+   * How often the guard passed something through without inspecting it, in the cases it can observe,
+   * keyed `<phase>:<reason>` (for example `request:body-cap`, `response:live-stream`). Zero skips means
+   * nothing the guard could see was bypassed, not that nothing was.
+   */
+  coverage(): { skipped: Record<string, number> };
+  /** Stops the rule refresh only — the poll loop and its recovery retries. The reporters and this
+   *  protection's outbound screening keep running; use `stop()` to end those too. */
   stopRefresh: () => Promise<void>;
   /**
    * Where the rules in force came from, and whether the most recent resolution was clean — the same
@@ -128,6 +156,20 @@ export interface Protection {
       lastAcknowledgedAt: string | null;
     };
   };
+  /** Present when block-log reporting is on — where the block records went, in records. Carries no
+   *  request data. */
+  blockLogHealth?: () => {
+    /** Records the queue accepted. Each ends up delivered, failed, or dropped by a shutdown. */
+    recorded: number;
+    /** Records in a batch the endpoint acknowledged. */
+    delivered: number;
+    /** Records in a batch that was refused, or that could not be sent (including a failed token exchange). */
+    failed: number;
+    /** Records a shutdown discarded, plus records turned away because the queue was full. */
+    dropped: number;
+    /** Records waiting to be sent now. */
+    queued: number;
+  };
 }
 
 /**
@@ -233,7 +275,8 @@ export interface CreateProtectionOptions {
   detectionFlushMs?: number;
   /** Optional Source-Host header for connector hostname checks. */
   sourceHost?: string;
-  /** Optional fetch override (tests). */
+  /** Optional fetch override for the block-log and detection reporters (tests). The rules client and
+   *  the manifest re-post use the global `fetch`. */
   fetchImpl?: typeof fetch;
   /**
    * Re-fetch and hot-swap the live rules every N ms. For long-lived runtimes that aren't restarted
@@ -252,7 +295,8 @@ export interface CreateProtectionOptions {
    * During a refresh, also re-post the dependency manifest (the runtime counterpart to `scan`) so a
    * dependency added after boot — e.g. via `npm install <pkg>`, which fires no npm lifecycle hook —
    * is reported and enforced without a restart. Defaults on when a `siteUuid` is set; set false to
-   * refresh rules only. Only meaningful with `refreshMs > 0` and a Pulse `siteUuid`.
+   * refresh rules only. Only meaningful with a Pulse `siteUuid` and a refresh path: `refreshMs > 0` or a
+   * refresh secret. A manual `refresh()` re-posts too when either is configured.
    */
   reportManifest?: boolean;
   /** Directory the manifest re-scan reads the lockfile from during a refresh. Default process.cwd(). */
@@ -273,11 +317,20 @@ export interface CreateProtectionOptions {
     read(): unknown | Promise<unknown>;
     write(envelope: unknown): unknown | Promise<unknown>;
   };
+  /**
+   * The transport peer of a Fetch request, for runtimes where the host knows it and the `Request` does
+   * not — e.g. `(req, info) => info.remoteAddr.hostname` on Deno, `(req, server) => server.requestIP(req)?.address`
+   * on Bun. Called with the request the host served and the arguments its handler received (passed through
+   * `fetch(handler)`, `fetchGuard()(request, ...args)` and `screenResponse(response, request, ...args)`).
+   * The result counts as the peer for client address resolution, including `trustedProxy`. A throw, or a result that is not an address, supplies no peer.
+   */
+  peerAddress?: (request: Request, ...hostArgs: unknown[]) => string | null | undefined;
   /**
    * Declare which peers are this deployment's own reverse proxies, so a forwarded header can be believed.
    *
-   * With no policy, the client address is whatever the transport observed — the socket peer on Node, and
-   * nothing at all in a runtime that exposes no peer, where the provenance reads `unavailable`. A
+   * With no policy, the client address is whatever the transport observed — the socket peer on Node, the
+   * `peerAddress` result on a Fetch runtime, and nothing at all where neither is available, in which case
+   * the provenance reads `unavailable` (and, with a policy set, the guard warns once). A
    * forwarded header is never trusted implicitly: it is ordinary request input that any caller can send.
    *
    * A policy must say WHO is trusted, not just which header to read. Declare at least one of:
@@ -305,7 +358,40 @@ export interface CreateProtectionOptions {
     header?: string;
     isTrusted?: (ip: string) => boolean;
   };
-  /** Override the default response-phase (secret-leak) rule set. */
+  /** How long the boot-time rules fetch may take before the guard starts on its cache or bundled
+   *  fallback. Default 5000ms. Refreshes use `refreshTimeoutMs`. */
+  bootTimeoutMs?: number;
+  /** How long a refresh's rules fetch may take. Default 30000ms. */
+  refreshTimeoutMs?: number;
+  /** Largest request body the Fetch path buffers for inspection. A larger body is passed through
+   *  uninspected and counted as a `request:body-cap` skip. Default 1 MiB. The Node guard takes its own
+   *  `node({ maxBodyBytes })`. */
+  maxBodyBytes?: number;
+  /**
+   * Apply the valid part of a live rules update when some of its rules fail validation. By default the
+   * whole update is refused, the previous rules stay in force and the response is not cached; either
+   * way every rejected rule is reported through `onRuleRejected`.
+   */
+  acceptPartialBundle?: boolean;
+  /** Permit whitelist entries with no `rule_id`, which apply to every rule. Refused by default. */
+  allowGlobalWhitelists?: boolean;
+  /** Called for each delivered rule that failed validation and is not enforced. Without it, rejections
+   *  are written to the console. */
+  onRuleRejected?: (rejection: { id: string | number; reason: string; accepted?: boolean }) => void;
+  /** Called each time the guard passes something through without inspecting it (an oversized or
+   *  encoded body, a live stream, a binary body, an outbound call it could not resolve). `detail` carries
+   *  operational context such as sizes and hostnames — keep it server-side. `protection.coverage()`
+   *  holds the running counts. */
+  onSkip?: (skip: {
+    phase: Phase;
+    reason: string;
+    detail?: Record<string, unknown>;
+    count: number;
+  }) => void;
+  /**
+   * Override the default response-phase (secret-leak) rule set. A rule that reads only response headers is
+   * enforced from the headers, and masks only the header it matched — see `screenResponse`.
+   */
   responseRules?: unknown[];
   /** Override the default egress-phase (SSRF) rule set. */
   egressRules?: unknown[];
@@ -346,7 +432,15 @@ export interface CreateProtectionOptions {
    * only active when `egress` is on and node:dns is available (a no-op on edge runtimes).
    */
   screenDns?: boolean;
-  /** Redaction mask (string or per-category function). Default "[REDACTED]". */
+  /**
+   * Redaction mask (string or per-category function). Default "[REDACTED]".
+   *
+   * In a JSON response, a text-span redaction or encoding may change string values only. When a
+   * rewrite in `block` mode would change the document's structure instead — a match inside a key
+   * name or across fields, a bare number or literal, or a mask that leaves the document invalid — the
+   * whole response is withheld rather than masked. Structural `array_key_value` masking replaces the
+   * leaf it targets, and keeps every other value, including each number, exactly as it was spelled.
+   */
   maskWith?: string | ((category?: string) => string);
   /**
    * Operational problems the guard handled without failing a request. Without it, rules that are not
@@ -385,7 +479,7 @@ export function createSupabaseGuard(opts: {
   maxBodyBytes?: number;
   /** Maximum upstream request duration. Default 30 seconds. */
   timeoutMs?: number;
-}): (request: Request) => Promise<Response>;
+}): (request: Request, ...hostArgs: unknown[]) => Promise<Response>;
 
 /**
  * Server-function guard: inspect a TanStack server function's decoded args against the same