zuplo 7.2.3 → 7.2.4

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

@@ -0,0 +1,127 @@
+The Data Loss Prevention (DLP) policy scans the **content** of AI requests and
+responses — system prompts, message text, thinking blocks, tool-result text, and
+(by default) tool-call arguments — for sensitive data, and applies a per-rule
+action when something is found. It never inspects structural fields: model
+names, temperatures, token counts, and usage pass through untouched.
+
+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` 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:
+
+- `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.
+
+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).
+
+```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" }
+}
+```
+
+### Detection levels
+
+Each type combines its pattern with evidence — a checksum where the format has
+one, context words (like "cvv" or "routing number") where it does not.
+`detection` says how much evidence a match needs: `corroborated` additionally
+requires one of the type's context words near the match (types without context
+words behave as standard); `standard` (the default) uses the catalog as tuned —
+distinctive shapes such as a dashed SSN act on their own, ambiguous shapes such
+as a bare CVV need nearby context; `aggressive` counts every pattern match and
+is false-positive-prone — pair it with `log` for audits. There are no numeric
+confidence thresholds to tune.
+
+## Masking
+
+The default replacement is the typed placeholder `[{type}]`, which renders the
+detected type id in UPPER_SNAKE form — `bob@acme.com` becomes `[CONTACT_EMAIL]`
+— keeping masked conversations legible to the model. Set a rule's `mask` to a
+literal like `[REDACTED]` to hide the type instead.
+`partialMask: { "keepLast": 4 }` keeps the last four characters and `*`-fills
+the rest, preserving length (`**** **** **** 4242`).
+
+## Allowed values
+
+`allowValues` lists exact strings never flagged by any rule — documentation
+samples like Stripe's public test card, or your own support email address. The
+exemption applies to the whole value even when it arrives split across streaming
+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.
+
+## 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.
+
+## Failure posture
+
+This policy is a guardrail and fails closed by default: content whose shape
+cannot be inspected is denied (`onUnknownShape: "deny"`, which also covers a
+streamed SSE event that cannot be parsed), and an internal scanner failure
+blocks with a 500 (`onError: "block"`). A detected value that masking cannot
+reach — one whose evidence spans two separate message fields, so no single field
+can be rewritten — is blocked instead of forwarded half-covered. Error responses
+(4xx/5xx) from the upstream are never scanned. Response hooks compose with other
+AI Gateway policies on compatibility dates of 2026-03-01 or later.
+
+## Known limits
+
+- 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
+  value (or one past `maxCarryChars`) is still detected — and can block — but
+  its earliest pieces may already have been delivered.
+- 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.
+- Streamed `logprobs` are removed from scanned chat streams: masking rewrites
+  the text they describe, and stale logprobs are worse than absent ones.
+- 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.

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

@@ -0,0 +1,5 @@
+Scans AI request and response content — system prompts, message text, and
+tool-call arguments — for sensitive data such as credit cards, national
+identifiers, and API keys, applying per-rule actions (mask, block, or log).
+Detection runs entirely inside the gateway, and streaming responses are scanned
+as they stream.