zuplo 6.70.69 → 6.70.71

package/docs/policies/data-loss-prevention-outbound/doc.md

@@ -0,0 +1,116 @@
+This policy inspects the body of each upstream response for sensitive data and
+applies a configurable action. It is the outbound counterpart to the
+[Data Loss Prevention - Inbound](/docs/policies/data-loss-prevention-inbound)
+policy, which inspects incoming requests.
+
+Detection happens entirely inside the gateway isolate — response bodies are
+never sent to a third-party service.
+
+## Actions
+
+- **`mask`** (default) — every detected value is replaced with the `mask` string
+  and the modified response is returned to the client. Overlapping matches are merged
+  and masked once.
+- **`block`** — the response is replaced with a `422 Unprocessable Content`. The
+  problem detail lists only the names of the detected entities, never the
+  matched values, so the policy never leaks the data it caught.
+- **`log`** — a structured warning is written (entity ids and counts only) and
+  the response is returned unchanged.
+
+## Built-in recognizers
+
+Enable entities individually or by **group selector** in the `entities`
+option, or omit it to use the full catalog. Entity ids follow a
+`{category}-{scope}-{name}` taxonomy, and any dash-aligned prefix of an id is a
+valid selector: `secret` enables every secret, `id-au` enables Australia's
+identifiers, `secret-aws` enables both AWS entities. Two named groups (`pii`,
+`region-eu`) bundle entities across categories.
+
+| Group         | Entities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `secret`     | `secret-private-key`, `secret-jwt`, `secret-aws-access-key`, `secret-aws-bedrock`, `secret-github`, `secret-gitlab`, `secret-zuplo`, `secret-openai`, `secret-anthropic`, `secret-google-api-key`, `secret-stripe`, `secret-slack`, `secret-discord-webhook`, `secret-npm`, `secret-pypi`, `secret-sendgrid`, `secret-twilio`, `secret-hugging-face`, `secret-databricks`, `secret-shopify`, `secret-square`, `secret-mailchimp`, `secret-mailgun`, `secret-postman`, `secret-terraform`, `secret-sentry`, `secret-digitalocean`, `secret-heroku`, `secret-perplexity`, `secret-azure-client`, `secret-telegram-bot` |
+| `finance`   | `finance-credit-card` (Luhn), `finance-iban` (per-country length + mod-97), `finance-crypto-wallet`, `finance-us-aba-routing` (checksum), `finance-swift-bic`, `finance-us-bank-account`, `finance-cvv`                                                                                                                                                                                                                                                                                                                                                                              |
+| `id` | `id-us-ssn`, `id-us-itin`, `id-us-passport`, `id-uk-nino`, `id-uk-nhs` (mod-11), `id-ca-sin` (Luhn), `id-au-abn`, `id-au-acn`, `id-au-tfn`, `id-au-medicare` (all checksummed), `id-in-aadhaar` (Verhoeff), `id-in-pan`, `id-sg-nric` (checksum), `id-es-nif` (checksum), `id-it-fiscal-code` (checksum), `id-pl-pesel` (checksum), `id-nl-bsn` (11-proef), `id-br-cpf` (checksum), `id-fr-nir` (mod-97)                                                                                                                                                                            |
+| `contact`     | `contact-email`, `contact-phone`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `network`     | `network-ipv4`, `network-ipv6`, `network-mac`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `pii`         | `contact` + `id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Prefixes      | `id-us`, `id-uk`, `id-au`, `id-ca`, `id-in`, `id-sg`, `id-es`, `id-it`, `id-pl`, `id-nl`, `id-br`, `id-fr`, `finance-us`, `secret-aws` — everything whose id starts with that prefix                                                                                                                                                                                                                                                                                                  |
+| `region-eu`   | `id-es-nif`, `id-it-fiscal-code`, `id-pl-pesel`, `id-nl-bsn`, `id-fr-nir`, `finance-iban`                                                                                                                                                                                                                                                                                                                                                                                              |
+
+## Context-word scoring
+
+Every match gets a confidence score. Recognizers whose raw pattern is just "a
+run of digits" (bank accounts, routing numbers, NHS numbers, …) carry a low
+base confidence and a list of **context words**; when one of those words
+appears near the match — in prose, or in a JSON key, form field, or header-like
+label (`nhsNumber`, `routing_number`, `cvv:`) — the confidence is boosted above
+the detection threshold.
+
+For example, with the `id-uk-nhs` entity enabled, `{"nhsNumber": "9434765919"}` is
+masked while the same digits in `{"orderId": "9434765919"}` pass through
+untouched.
+
+The threshold is configurable via `minConfidence` (default `0.5`): lower it to
+detect context-dependent entities everywhere, raise it to keep only prefix- and
+checksum-validated matches.
+
+## Custom patterns
+
+Add your own recognizers with `customPatterns`. Each entry has a `name`, a
+JavaScript regular expression `pattern`, and optionally a `confidence` and
+`context` words to participate in context scoring. Invalid patterns are logged
+and skipped rather than failing the response. Remember to escape backslashes for
+JSON (for example `\\d` to match a digit).
+
+## Content types
+
+Only text-based bodies (JSON, XML, form-encoded, and `text/*`) are scanned;
+binary bodies pass through untouched. Override the allow-list with the
+`contentTypes` option if you need to scan a different set of content types.
+
+## Configuration
+
+- `engine`: The detection engine. Only `builtin` is available today. **Default:**
+  `builtin`
+- `entities`: Recognizer ids and/or group selectors (prefixes, `pii`,
+  `region-eu`) to enable. **Default:** all
+  recognizers
+- `customPatterns`: Additional `{ name, pattern, confidence?, context? }` regex
+  recognizers
+- `action`: `mask`, `block`, or `log`. **Default:** `mask`
+- `mask`: Replacement string used when `action` is `mask`. **Default:**
+  `[REDACTED]`
+- `minConfidence`: Detection threshold (0-1). **Default:** `0.5`
+- `contentTypes`: Override the scannable content-type allow-list
+
+## Usage
+
+Apply this policy to outbound responses in your route configuration:
+
+```json
+{
+  "policies": [
+    {
+      "name": "data-loss-prevention-outbound",
+      "policyType": "data-loss-prevention-outbound",
+      "handler": {
+        "export": "DataLossPreventionOutboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "action": "mask",
+          "entities": ["secret", "finance", "id-us", "contact-email"],
+          "mask": "[REDACTED]",
+          "customPatterns": [
+            {
+              "name": "employee-id",
+              "pattern": "EMP-\\d{6}",
+              "confidence": 0.3,
+              "context": ["employee"]
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```

package/docs/policies/data-loss-prevention-outbound/intro.md

@@ -0,0 +1,18 @@
+The Data Loss Prevention (DLP) policy scans upstream response bodies for
+sensitive data — personally identifiable information (PII), secrets and API
+keys for dozens of vendors, payment and bank identifiers, and national IDs for
+many countries — using a catalog of 60+ built-in recognizers plus any custom
+patterns you add. When a match is found it takes a configurable action: mask
+the matches, block the response, or log a warning and let it through.
+
+Recognizers are selected individually or via entity groups (`secret`,
+`finance`, `pii`, `id-us`, `id-uk`, `region-eu`, …). Detection runs entirely in the
+gateway isolate using regular expressions, checksums (Luhn, mod-97, Verhoeff,
+and friends), and context-word scoring — no response data leaves the gateway.
+This is especially useful in front of APIs that interface with user-generated
+content, MCP servers, and AI consumers, where a response might otherwise leak
+data the client should never see.
+
+Pair with the
+[Data Loss Prevention - Inbound](/docs/policies/data-loss-prevention-inbound)
+policy to also scan incoming requests before they reach your handler.

package/docs/policies/data-loss-prevention-outbound/schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/data-loss-prevention-outbound.json",
+  "type": "object",
+  "title": "Data Loss Prevention",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Scans the upstream response body for sensitive data — PII, secrets, and financial identifiers — using an extensible catalog of built-in recognizers plus any custom patterns, and takes a configurable action when a match is found.\n\nThe action is one of `mask` (redact matches before returning the response), `block` (replace the response with a `422` listing the detected entity names only), or `log` (record a warning and return unchanged). Only text content types are inspected; binary bodies pass through untouched, and the body is read from a clone so the client still receives the original stream.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "DataLossPreventionOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "DataLossPreventionOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the Data Loss Prevention outbound policy. Scans the upstream response body for sensitive data and applies the configured action (mask, block, or log).",
+          "additionalProperties": false,
+          "required": [],
+          "examples": [
+            {
+              "action": "mask",
+              "entities": ["secret", "finance", "contact-email", "id-us-ssn"],
+              "mask": "[REDACTED]"
+            }
+          ],
+          "properties": {
+            "engine": {
+              "type": "string",
+              "enum": ["builtin"],
+              "default": "builtin",
+              "description": "The detection engine. Only `builtin` (in-isolate regex + checksum detection with context-word scoring) is available today. This is the extension point for a future hosted `presidio-service` mode; declaring it now keeps adding that mode an additive, non-breaking change."
+            },
+            "entities": {
+              "type": "array",
+              "description": "Built-in recognizer ids and/or group selectors to enable. Entity ids follow a {category}-{scope}-{name} taxonomy, and any dash-aligned id prefix acts as a selector (for example `secret` is every secret, `id-au` is Australia's identifiers, `secret-aws` is both AWS entities), plus the named groups `pii` and `region-eu`. Available selectors: `contact`, `finance`, `finance-us`, `id`, `id-au`, `id-br`, `id-ca`, `id-es`, `id-fr`, `id-in`, `id-it`, `id-nl`, `id-pl`, `id-sg`, `id-uk`, `id-us`, `network`, `pii`, `region-eu`, `secret`, `secret-aws`. When omitted, the full built-in catalog is used.",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "contact",
+                  "finance",
+                  "finance-us",
+                  "id",
+                  "id-au",
+                  "id-br",
+                  "id-ca",
+                  "id-es",
+                  "id-fr",
+                  "id-in",
+                  "id-it",
+                  "id-nl",
+                  "id-pl",
+                  "id-sg",
+                  "id-uk",
+                  "id-us",
+                  "network",
+                  "pii",
+                  "region-eu",
+                  "secret",
+                  "secret-aws",
+                  "contact-email",
+                  "contact-phone",
+                  "finance-credit-card",
+                  "finance-crypto-wallet",
+                  "finance-cvv",
+                  "finance-iban",
+                  "finance-swift-bic",
+                  "finance-us-aba-routing",
+                  "finance-us-bank-account",
+                  "id-au-abn",
+                  "id-au-acn",
+                  "id-au-medicare",
+                  "id-au-tfn",
+                  "id-br-cpf",
+                  "id-ca-sin",
+                  "id-es-nif",
+                  "id-fr-nir",
+                  "id-in-aadhaar",
+                  "id-in-pan",
+                  "id-it-fiscal-code",
+                  "id-nl-bsn",
+                  "id-pl-pesel",
+                  "id-sg-nric",
+                  "id-uk-nhs",
+                  "id-uk-nino",
+                  "id-us-itin",
+                  "id-us-passport",
+                  "id-us-ssn",
+                  "network-ipv4",
+                  "network-ipv6",
+                  "network-mac",
+                  "secret-anthropic",
+                  "secret-aws-access-key",
+                  "secret-aws-bedrock",
+                  "secret-azure-client",
+                  "secret-databricks",
+                  "secret-digitalocean",
+                  "secret-discord-webhook",
+                  "secret-github",
+                  "secret-gitlab",
+                  "secret-google-api-key",
+                  "secret-heroku",
+                  "secret-hugging-face",
+                  "secret-jwt",
+                  "secret-mailchimp",
+                  "secret-mailgun",
+                  "secret-npm",
+                  "secret-openai",
+                  "secret-perplexity",
+                  "secret-postman",
+                  "secret-private-key",
+                  "secret-pypi",
+                  "secret-sendgrid",
+                  "secret-sentry",
+                  "secret-shopify",
+                  "secret-slack",
+                  "secret-square",
+                  "secret-stripe",
+                  "secret-telegram-bot",
+                  "secret-terraform",
+                  "secret-twilio",
+                  "secret-zuplo"
+                ]
+              }
+            },
+            "customPatterns": {
+              "type": "array",
+              "description": "Additional customer-defined regex recognizers. Invalid patterns are logged and skipped rather than failing the response.",
+              "items": {
+                "type": "object",
+                "title": "DlpCustomPattern",
+                "additionalProperties": false,
+                "required": ["name", "pattern"],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Identifier reported in findings and block details for this pattern."
+                  },
+                  "pattern": {
+                    "type": "string",
+                    "description": "A JavaScript regular expression source string. Remember to escape backslashes for JSON (for example `\\\\d` for a digit)."
+                  },
+                  "confidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1,
+                    "default": 0.85,
+                    "description": "Base confidence (0-1) for matches of this pattern. The default of 0.85 is above the default detection threshold; combine a low value with `context` words for patterns that are only sensitive in context."
+                  },
+                  "context": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Context words that boost a match's confidence by 0.45 when one appears near the match (in the surrounding field, label, or key)."
+                  }
+                }
+              }
+            },
+            "action": {
+              "type": "string",
+              "enum": ["mask", "block", "log"],
+              "default": "mask",
+              "description": "What to do when sensitive data is detected. `mask` redacts matches before returning the response, `block` replaces the response with a 422 listing only the detected entity names, and `log` records a warning and returns the response unchanged."
+            },
+            "mask": {
+              "type": "string",
+              "default": "[REDACTED]",
+              "examples": ["[REDACTED]"],
+              "description": "The string that replaces detected values when `action` is `mask`."
+            },
+            "minConfidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.5,
+              "x-show-example": false,
+              "description": "Minimum confidence (0-1) a match must reach to count as a finding. Context-dependent recognizers (for example `finance-us-bank-account` or `finance-us-aba-routing`) sit below the default threshold of 0.5 until a context word near the match boosts them above it. Lower the threshold to surface them everywhere; raise it to keep only prefix- or checksum-validated matches."
+            },
+            "contentTypes": {
+              "type": "array",
+              "description": "Override the set of scannable content-type prefixes. When omitted, the built-in text content-type allow-list (JSON, XML, form-encoded, text/\\*) is used.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "DataLossPreventionOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "action": "mask",
+            "entities": ["secret", "finance", "contact-email", "id-us-ssn"],
+            "mask": "[REDACTED]"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/ip-restriction-inbound/policy.ts

@@ -29,7 +29,7 @@ export default async function (
   // If the blocked IP addresses are set, then the incoming IP
   // can't be in that list
   if (options.blockedIpAddresses) {
-    const blocked = ipRangeCheck(ip, options.allowedIpAddresses);
+    const blocked = ipRangeCheck(ip, options.blockedIpAddresses);
     if (blocked) {
       return HttpProblems.unauthorized(request, context);
     }

package/docs/programmable-api/background-dispatcher.mdx

@@ -13,7 +13,7 @@ groups entries and invokes your callback with batches at regular intervals.
 ```ts
 new BackgroundDispatcher<T>(
   dispatchFunction: (entries: T[]) => Promise<void>,
-  options: { msDelay: number }
+  options: { msDelay: number; name?: string }
 )
 ```
 
@@ -21,6 +21,7 @@ Creates a new background dispatcher instance.
 
 - `dispatchFunction` - Asynchronous function called with batched entries
 - `options.msDelay` - Milliseconds between dispatch calls (required, non-zero)
+- `options.name` - Optional name that identifies the dispatcher in error logs
 - `T` - The type of entries being batched
 
 ## Methods
@@ -30,7 +31,7 @@ Creates a new background dispatcher instance.
 Adds an entry to the batch queue for later dispatch.
 
 ```ts
-enqueue(entry: T, context: ZuploContext): void
+enqueue(entry: T): void
 ```
 
 ## Example
@@ -74,12 +75,9 @@ const backgroundDispatcher = new BackgroundDispatcher<ExampleEntry>(
 // This is an example Request Handler that used the component, a simple
 // "Hello World" handler.
 export default async function (request: ZuploRequest, context: ZuploContext) {
-  backgroundDispatcher.enqueue(
-    {
-      message: `new request on '${request.url}' with id ${context.requestId}`,
-    },
-    context,
-  );
+  backgroundDispatcher.enqueue({
+    message: `new request on '${request.url}' with id ${context.requestId}`,
+  });
 
   return "Hello World!";
 }

package/docs/programmable-api/http-problems.mdx

@@ -116,24 +116,6 @@ return HttpProblems.unauthorized(
 );
 ```
 
-## HttpStatusCode Enum
-
-The `HttpStatusCode` enum provides numeric constants for all HTTP status codes:
-
-```typescript
-import { HttpStatusCode } from "@zuplo/runtime";
-
-// Use in responses
-return new Response("Created", {
-  status: HttpStatusCode.Created, // 201
-});
-
-// Use in comparisons
-if (response.status === HttpStatusCode.NotFound) {
-  // Handle 404
-}
-```
-
 ## See Also
 
 - [ProblemResponseFormatter](./problem-response-formatter.mdx)