zuplo 7.3.2 → 7.4.3

package/docs/policies/ai-gateway-dlp-inbound/doc.md

@@ -8,42 +8,52 @@ Detection runs entirely inside your gateway using the built-in DLP engine (62
 data types backed by regexes, checksums such as Luhn and IBAN mod-97, and
 context-word scoring). Nothing is sent to a third-party scanning service.
 
-## Rules
+## Rules: inbound and outbound
 
-`rules` is a map. Each key names a built-in data type id (like `id-us-ssn`) or a
-group selector (like `pii`, `secret`, or any dash-aligned prefix such as
-`secret-aws`); each value is a rule object stating what happens when that type
-is found:
+`rules` has exactly two sections — `inbound` for what callers send the model
+(system prompt, message text, and tool-call arguments), `outbound` for what the
+model sends back (buffered responses whole, streaming responses as they stream).
+Each direction you include is scanned; each you omit is left untouched. There is
+no "both" shorthand and no mirroring — wanting the same behavior on both sides
+means stating it in both sections.
+
+Each section is a map. Keys name a built-in data type id (like `id-us-ssn`), a
+group selector (`pii`, `secret`, or any dash-aligned prefix such as
+`secret-aws`), or one of your custom detectors by name; each value is a rule
+object whose required `action` says what happens on a match:
 
 - `mask` — replace the matched text with a placeholder; the conversation
   continues.
 - `block` — reject the request (or terminate the response) with an error naming
   the detected types, never the values.
 - `log` — record a finding and let the traffic pass; use it to trial a rule.
-- `off` — exclude this type from a group enabled by a broader key.
-
-A rule states its action in one of two ways, never both: a single `action`
-applying in both directions, or the directional pair `inboundAction` /
-`outboundAction` — `inboundAction` governs what callers send the model,
-`outboundAction` governs what the model sends back (buffered responses whole,
-streaming responses as they stream). Either directional field alone limits the
-rule to that direction.
+- `off` — exclude this type from a group enabled by a broader key in the same
+  section.
 
-Types you do not mention are not scanned. The most specific key wins (exact id
-beats a prefix beats a group) and the winning entry decides everything for its
-type, direction included. When one stretch of text matches multiple rules, the
-severest action wins (block > mask > log).
+Because a rule lives inside a direction, everything about it is per-direction —
+its action, its detection level, its mask text, its partial masking:
 
 ```json
 "rules": {
-  "pii": { "inboundAction": "mask", "outboundAction": "block" },
-  "contact-phone": { "action": "off" },
-  "secret": { "action": "block" },
-  "finance-credit-card": { "action": "mask", "partialMask": { "keepLast": 4 } },
-  "finance-cvv": { "action": "block", "detection": "corroborated" }
+  "inbound": {
+    "pii": { "action": "mask" },
+    "contact-phone": { "action": "off" }
+  },
+  "outbound": {
+    "pii": { "action": "block" },
+    "finance-credit-card": { "action": "mask", "partialMask": { "keepLast": 4 } },
+    "finance-cvv": { "action": "block", "detection": "corroborated" }
+  }
 }
 ```
 
+Within one section: types you do not mention are not scanned; the most specific
+key wins (exact id beats a prefix beats a group) and the winning entry decides
+everything for its type in that direction. When one stretch of text matches
+multiple rules, the severest action wins (block > mask > log). The two sections
+never influence each other, and at least one section must enable at least one
+rule.
+
 ### Detection levels
 
 Each type combines its pattern with evidence — a checksum where the format has
@@ -74,29 +84,45 @@ chunks.
 
 ## Custom rules
 
-`customRules` adds your own detections: the same rule object plus a `name`, a
-regex `pattern`, and optional `context` words (`detection: "corroborated"` then
-means "only near one of those words"). Names must be distinct and must not reuse
-a built-in type id or group selector — built-in types are configured through
-`rules`. An invalid pattern or a colliding name fails the configuration at
-request time — a broken guardrail never degrades into a silent pass-through.
+`customRules` declares your own detectors — a `name`, a regex `pattern`, and
+optional `context` words. A detector does nothing by itself: activate it by name
+inside `rules.inbound` or `rules.outbound`, exactly like a built-in type, with
+its own action, detection level, and mask per direction
+(`detection: "corroborated"` then means "only near one of its context words").
+Names must be distinct and must not reuse a built-in type id or group selector.
+A rules key that matches neither a built-in nor a declared detector, an invalid
+pattern, or a colliding name fails the configuration at request time — a broken
+guardrail never degrades into a silent pass-through.
 
 ## Streaming responses
 
-Streaming responses are scanned as they stream. Providers emit deltas of a few
-characters, so each channel's text is first coalesced into scan pieces of at
-least 64 characters (clients concatenate deltas, so only the chunking shifts —
-never the text). The scanner carries a bounded tail of already-scanned text
-(`streaming.maxCarryChars`, default 512) into each new piece's scan, and each
-piece is released once the scan including its successor passes — so a value
-split across pieces is fully maskable before anything is delivered, at the cost
-of roughly one coalesced piece (~64 characters) of latency. When a `block` rule
-fires mid-stream, the stream terminates with the endpoint's native
-content-filter events (OpenAI clients see a `content_filter` error chunk and
-`[DONE]`; Anthropic clients see a well-formed `message_delta` with
-`stop_reason: "content_filter"` and `message_stop`). Setting
-`streaming.boundaryScan: false` scans each chunk alone and releases it
-immediately — lower cost, but values split across chunks are missed.
+How streaming (SSE) responses are inspected is set by `streaming.mode`:
+
+- **`stream` (default)** — scan deltas as they flow. Providers emit deltas of a
+  few characters, so each channel's text is first coalesced into scan pieces of
+  at least 64 characters (clients concatenate deltas, so only the chunking
+  shifts — never the text). The scanner carries a bounded tail of
+  already-scanned text (`streaming.maxCarryChars`, default 512) into each new
+  piece's scan, and each piece is released once the scan including its successor
+  passes — so a value split across pieces is fully maskable before anything is
+  delivered, at the cost of roughly one coalesced piece (~64 characters) of
+  latency. When a `block` rule fires mid-stream, the stream terminates with the
+  endpoint's native content-filter events (OpenAI clients see a `content_filter`
+  error chunk and `[DONE]`; Anthropic clients see a well-formed `message_delta`
+  with `stop_reason: "content_filter"` and `message_stop`). Setting
+  `streaming.boundaryScan: false` scans each chunk alone and releases it
+  immediately — lower cost, but values split across chunks are missed.
+- **`buffer`** — collect the entire response first, then scan it exactly like a
+  non-streaming response: one pass over each channel's complete text. Detection
+  is exact for values of ANY length (no carry window, no chunk boundaries — the
+  streaming limits below do not apply), and because nothing has been delivered
+  when the verdict lands, a `block` is a clean native 400 error naming the
+  detected types instead of a mid-stream termination. The trade is delivery: the
+  client receives nothing until the model finishes generating, and the gateway
+  holds the whole response in memory. The SSE framing is preserved — clients
+  still receive the same events, all at once.
+- **`off`** — streaming responses pass through unscanned, even when rules cover
+  the outbound direction. Buffered (non-streaming) responses are still scanned.
 
 ## Failure posture
 
@@ -111,6 +137,10 @@ AI Gateway policies on compatibility dates of 2026-03-01 or later.
 
 ## Known limits
 
+The first four limits apply to `streaming.mode: "stream"` only — `buffer` mode
+scans each channel's complete text in one pass, so chunking cannot hide a value
+from it:
+
 - Masking is complete for streamed values up to two coalesced scan pieces (~128
   characters) regardless of how finely the provider chunks its deltas, for types
   whose shape alone is decisive (dashed SSNs, cards, prefixed secrets). A longer
@@ -119,9 +149,13 @@ AI Gateway policies on compatibility dates of 2026-03-01 or later.
 - A context-gated match (a weak form, or a `corroborated` rule) whose context
   word arrives only in a LATER piece can leak the characters delivered before
   the context made it actionable; detection and blocking still fire.
+- Multi-line values such as PEM private key blocks are not detected across
+  streaming chunk boundaries.
 - Streamed `logprobs` are removed from scanned chat streams: masking rewrites
-  the text they describe, and stale logprobs are worse than absent ones.
+  the text they describe, and stale logprobs are worse than absent ones. (This
+  also applies to `buffer` mode, which rewrites the same events.)
+
+And in every mode:
+
 - Context words must appear in the conversation text itself; JSON field names in
   your application's data are not visible to the scanner.
-- Multi-line values such as PEM private key blocks are not detected across
-  streaming chunk boundaries.