zuplo 6.70.70 → 6.70.71

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/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/zone-cache.mdx

@@ -18,7 +18,7 @@ time-to-live (TTL) after which it expires and is removed from the cache. Each
 cached object can be up to 512 MB in size.
 
 There's an demonstration of ZoneCache use in the
-[Per User Rate Limits Using a Database](../articles/per-user-rate-limits-using-db.mdx)
+[Per User Rate Limits Using a Database](../rate-limiting/per-user-rate-limits-using-db.mdx)
 example.
 
 ## Constructor

package/docs/rate-limiting/combining-policies.mdx

@@ -0,0 +1,293 @@
+---
+title: Combining rate limit policies
+sidebar_label: Combining policies
+description:
+  Apply multiple rate limits to the same route, combine rate limiting with
+  quotas, and design multi-layer protection strategies.
+---
+
+Real-world APIs rarely need just one rate limiting boundary. A payment endpoint
+might need a per-minute burst limit to protect against runaway scripts _and_ a
+per-hour cap to enforce fair usage. A monetized API might pair a monthly quota
+with a per-second spike guard. Zuplo supports all of these patterns by letting
+you stack multiple policies on the same route.
+
+## Multiple rate limits on one route
+
+You can apply two or more rate limiting policies to a single route. Each policy
+maintains its own counter independently, and the request must pass every policy
+to reach the backend.
+
+A common pattern is combining a short-window burst limit with a longer-window
+sustained limit. The following example enforces both a 1,000-requests-per-hour
+ceiling and a 100-requests-per-minute burst limit on the same route.
+
+### Define the policies
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "rate-limit-hourly",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 1000,
+          "timeWindowMinutes": 60
+        }
+      }
+    },
+    {
+      "name": "rate-limit-per-minute",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+### Attach them to a route
+
+List both policies in the route's inbound pipeline. Place the longest time
+window first:
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["rate-limit-hourly", "rate-limit-per-minute"]
+    }
+  }
+}
+```
+
+:::tip
+
+Apply the longest time window first. If a caller already exhausted the hourly
+quota, the request is rejected immediately without incrementing the per-minute
+counter. This avoids wasting counter writes on requests that would fail anyway.
+
+:::
+
+Each policy tracks its own sliding window counter scoped by its `name`. A
+request that passes the hourly check still gets evaluated against the per-minute
+check. If either policy rejects the request, the client receives a
+`429 Too Many Requests` response.
+
+## Rate limiting vs. quotas
+
+Rate limiting and quotas both cap usage, but they solve different problems.
+
+| Aspect            | Rate limiting                                       | Quota                                        |
+| ----------------- | --------------------------------------------------- | -------------------------------------------- |
+| **Time window**   | Short: seconds, minutes, or hours                   | Long: hourly, daily, weekly, or monthly      |
+| **Purpose**       | Protect backends from traffic spikes                | Enforce billing-period usage caps            |
+| **Counter reset** | Sliding window rolls continuously                   | Fixed period anchored to a start date        |
+| **Typical use**   | "100 requests per minute per user"                  | "10,000 requests per month per subscription" |
+| **Policy**        | [Rate Limiting](../policies/rate-limit-inbound.mdx) | [Quota](../policies/quota-inbound.mdx)       |
+
+Use rate limiting when you need to smooth traffic and prevent bursts. Use quotas
+when you need to enforce a usage allowance over a billing cycle. In many APIs,
+you use both together: a monthly quota to cap total usage and a per-minute rate
+limit to prevent any single caller from overwhelming the backend within that
+quota.
+
+### Example: quota plus rate limit
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "monthly-quota",
+      "policyType": "quota-inbound",
+      "handler": {
+        "export": "QuotaInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "period": "monthly",
+          "quotaBy": "user",
+          "allowances": {
+            "requests": 10000
+          }
+        }
+      }
+    },
+    {
+      "name": "burst-rate-limit",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+On the route, place the quota policy first so that callers who already used
+their monthly allowance are rejected before the rate limit counter is
+incremented:
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monthly-quota", "burst-rate-limit"]
+    }
+  }
+}
+```
+
+## Rate limiting with monetization
+
+The [Monetization policy](../articles/monetization/monetization-policy.md)
+handles subscription validation, quota enforcement, and metering in one step. It
+already enforces billing-period usage limits tied to the customer's plan, so you
+do not need a separate quota policy on monetized routes.
+
+Rate limiting is still valuable alongside monetization. A customer with a 50,000
+requests-per-month plan could theoretically send all 50,000 requests in a single
+minute, which would overwhelm your backend even though it falls within the
+monthly allowance. Adding a rate limiting policy prevents that spike.
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monetization-inbound", "rate-limit-per-minute"]
+    }
+  }
+}
+```
+
+:::note
+
+The monetization policy handles API key authentication internally. You do not
+need a separate `api-key-auth` policy on monetized routes. Place the
+monetization policy first so that `request.user` is populated before the rate
+limit policy runs.
+
+:::
+
+These two layers are complementary:
+
+- **Monetization** enforces monthly or billing-period usage limits and tracks
+  metered usage for billing.
+- **Rate limiting** enforces per-minute or per-second spike protection to keep
+  your backend healthy.
+
+## Counter scoping
+
+Rate limit counters are scoped by the policy's `name` field combined with the
+caller identifier (user, IP, or custom key). Understanding this scoping is
+important when you apply the same policy type to multiple routes.
+
+### Shared counters
+
+If two routes reference the same policy name, they share a counter. A caller who
+makes 60 requests to `/orders` and 40 requests to `/products` — both using a
+policy named `rate-limit-per-minute` — counts as 100 total requests against that
+policy's limit.
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "paths": {
+    "/orders": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["rate-limit-per-minute"]
+          }
+        }
+      }
+    },
+    "/products": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["rate-limit-per-minute"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Shared counters are useful when you want a single global limit that applies
+across all routes for a given caller.
+
+### Independent counters
+
+To give each route its own counter, create separate policy instances with
+different names:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "rate-limit-orders",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    },
+    {
+      "name": "rate-limit-products",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 200,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+Now a caller can make 100 requests per minute to `/orders` and 200 requests per
+minute to `/products` independently. Exhausting the orders limit does not affect
+the products limit.
+
+:::warning
+
+If you duplicate a policy definition and forget to change the `name`, both
+routes share the same counter. Always verify that policy names are distinct when
+you intend independent counters.
+
+:::
+
+## Related resources
+
+- [Rate Limiting policy reference](../policies/rate-limit-inbound.mdx)
+- [Complex Rate Limiting policy reference](../policies/complex-rate-limit-inbound.mdx)
+- [Quota policy reference](../policies/quota-inbound.mdx)
+- [Monetization policy](../articles/monetization/monetization-policy.md)
+- [How rate limiting works](./how-it-works.md)
+- [Dynamic Rate Limiting](./dynamic-rate-limiting.mdx)