zuplo 7.2.3 → 7.2.4

package/docs/policies/{akamai-ai-firewall → akamai-ai-firewall-v2-inbound}/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/akamai-ai-firewall.json",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/akamai-ai-firewall-v2-inbound.json",
   "type": "object",
   "title": "Akamai AI Firewall",
   "isDeprecated": false,
@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
+  "policyType": "akamai-ai-firewall-v2",
   "products": ["ai-gateway"],
   "description": "Akamai AI Firewall Inbound Policy",
   "deprecatedMessage": "",
@@ -21,7 +22,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "AkamaiAIFirewallInboundPolicy",
+          "const": "AkamaiAIFirewallV2InboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -29,9 +30,16 @@
           "description": "The module containing the policy"
         },
         "options": {
+          "x-zuplo-policy-type": "akamai-ai-firewall-v2",
           "title": "AkamaiAIFirewallPolicyOptions",
           "type": "object",
           "description": "The options for the Akamai AI Firewall policy.",
+          "examples": [
+            {
+              "configurationId": "$env(AKAMAI_AI_FIREWALL_CONFIGURATION_ID)",
+              "api-key": "$env(AKAMAI_AI_FIREWALL_API_KEY)"
+            }
+          ],
           "properties": {
             "configurationId": {
               "type": "string",
@@ -78,11 +86,33 @@
               },
               "additionalProperties": false
             },
+            "endpoints": {
+              "type": "array",
+              "title": "Applicable Endpoints",
+              "x-advanced": true,
+              "description": "The endpoint shapes this policy applies to. Omit to apply to all (openai-chat, openai-responses, anthropic-messages).",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "openai-chat",
+                  "openai-responses",
+                  "anthropic-messages"
+                ]
+              }
+            },
+            "onUnknownShape": {
+              "type": "string",
+              "title": "On Unknown Shape",
+              "x-advanced": true,
+              "description": "What to do when the request shape cannot be inspected. As a guardrail, this policy defaults to 'deny' (fail closed) so uninspectable content is never served.",
+              "enum": ["deny", "skip"],
+              "default": "deny"
+            },
             "onError": {
               "type": "string",
               "title": "On Firewall Error",
               "x-advanced": true,
-              "description": "What to do when the Akamai detect call itself fails (invalid API key, rate limit, outage). 'block' (the default) fails closed and returns a 502 so unverified content is never served; 'allow' fails open and lets the request through without inspection. An onError value in the AI Gateway app configuration takes precedence over this option.",
+              "description": "What to do when the Akamai detect call itself fails (invalid API key, rate limit, outage). 'block' (the default) fails closed and returns a 502 so unverified content is never served; 'allow' fails open and lets the request through without inspection.",
               "enum": ["block", "allow"],
               "default": "block"
             }
@@ -93,14 +123,11 @@
       },
       "examples": [
         {
-          "export": "AkamaiAIFirewallInboundPolicy",
+          "export": "AkamaiAIFirewallV2InboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "onError": "block",
-            "streamingAccumulation": {
-              "enabled": true,
-              "eventsInterval": 5
-            }
+            "configurationId": "$env(AKAMAI_AI_FIREWALL_CONFIGURATION_ID)",
+            "api-key": "$env(AKAMAI_AI_FIREWALL_API_KEY)"
           }
         }
       ]

package/docs/policies/akamai-firewall-for-ai-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
+  "policyType": "akamai-firewall-for-ai",
   "products": ["api-gateway"],
   "description": "Inspects each incoming request with Akamai's Firewall for AI detect API and blocks the request if Akamai returns a `deny` rule. Useful in front of AI-powered APIs to filter prompt injection, jailbreaks, and other unsafe inputs before they reach the model.\n\nThe body, headers, URL, and query string sent to Akamai are configurable; by default only the request body is captured. Bodies are read from a clone so the upstream handler still sees the original.",
   "deprecatedMessage": "",

package/docs/policies/akamai-firewall-for-ai-outbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
+  "policyType": "akamai-firewall-for-ai",
   "products": ["api-gateway"],
   "description": "Inspects each upstream response with Akamai's Firewall for AI detect API and replaces the response with a `403 Forbidden` if Akamai returns a `deny` rule. Useful behind AI-powered APIs to filter unsafe completions, sensitive data exposure, and toxic content before they reach the client.\n\nThe body, headers, URL, and query string sent to Akamai are configurable; by default only the response body is captured. Bodies are read from a clone so the client still receives the original.",
   "deprecatedMessage": "",

package/docs/policies/amberflo-metering-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "amberflo-metering-inbound",
   "products": ["api-gateway"],
   "description": "Amberflo is a usage metering and billing service. This policy allows you to send metering calls for each API to their meter ingest endpoint.",
   "deprecatedMessage": "",

package/docs/policies/api-key-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "api-key-inbound",
   "products": ["api-gateway"],
   "description": "Authenticates requests based on API Keys using Zuplo's built-in API key management. This policy validates API keys against Zuplo's key storage, caches results for performance, and automatically adds user information to authenticated requests.",
   "deprecatedMessage": "",

package/docs/policies/audit-log-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "audit-log-inbound",
   "products": ["api-gateway"],
   "description": "Capture detailed logs of requests for auditing purposes. The policy emits one structured CloudEvent per request, and user code can emit additional events via the static `log()` method.",
   "deprecatedMessage": "",

package/docs/policies/auth0-jwt-auth-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "auth0-jwt-auth-inbound",
   "products": ["api-gateway"],
   "description": "Authenticate users using Auth0 issued JWT tokens.",
   "deprecatedMessage": "",

package/docs/policies/authzen-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "authzen-inbound",
   "products": ["api-gateway"],
   "description": "Authorize requests using an AuthZEN compatible PDP",
   "deprecatedMessage": "",

package/docs/policies/axiomatics-authz-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "axiomatics-authz-inbound",
   "products": ["api-gateway"],
   "description": "Authorize requests using Axiomatics Policy Server.",
   "deprecatedMessage": "",

package/docs/policies/basic-auth-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "basic-auth-inbound",
   "products": ["api-gateway"],
   "description": "Authenticate requests using basic auth (i.e. username and password)",
   "deprecatedMessage": "",

package/docs/policies/bot-detection-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "bot-detection-inbound",
   "products": ["api-gateway"],
   "description": "Detect known and suspected bots based on sophisticated traffic analysis.",
   "deprecatedMessage": "",

package/docs/policies/brownout-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "brownout-inbound",
   "products": ["api-gateway"],
   "description": "The brownout policy allows performing scheduled downtime on your API",
   "deprecatedMessage": "",

package/docs/policies/caching-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "caching-inbound",
   "products": ["api-gateway"],
   "description": "Respond to matched incoming requests with cached content",
   "deprecatedMessage": "",

package/docs/policies/cdn-cache-control-outbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "cdn-cache-control-outbound",
   "products": ["api-gateway"],
   "description": "Sets the response headers that tell a CDN how long it may cache a response and which purge tags it belongs to, separately from what the browser is told.",
   "deprecatedMessage": "",

package/docs/policies/change-method-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "change-method-inbound",
   "products": ["api-gateway"],
   "description": "Changes the HTTP method of the incoming request.",
   "deprecatedMessage": "",

package/docs/policies/clear-headers-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "clear-headers-inbound",
   "products": ["api-gateway"],
   "description": "Removes all headers from the incoming request except for those in the exclude list.",
   "deprecatedMessage": "",

package/docs/policies/clear-headers-outbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "clear-headers-outbound",
   "products": ["api-gateway"],
   "description": "Removes all headers from the response except for those in the exclude list.",
   "deprecatedMessage": "",

package/docs/policies/clerk-jwt-auth-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "clerk-jwt-auth-inbound",
   "products": ["api-gateway"],
   "description": "Authenticate users using Clerk issued JWT tokens.",
   "deprecatedMessage": "",

package/docs/policies/cognito-jwt-auth-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "cognito-jwt-auth-inbound",
   "products": ["api-gateway"],
   "description": "Authenticate requests with JWT tokens issued by AWS Cognito.",
   "deprecatedMessage": "",

package/docs/policies/comet-opik-tracing-v2-inbound/doc.md

@@ -0,0 +1,78 @@
+# Comet Opik Tracing
+
+The Comet Opik Tracing policy integrates
+[Comet Opik](https://www.comet.com/docs/opik/) with the AI Gateway. It captures
+LLM inputs, outputs, model information, token usage, request metadata, and
+timing so you can debug applications, monitor production traffic, and evaluate
+model output in Opik.
+
+The policy supports Chat Completions, Responses, and Anthropic Messages. It
+creates the top-level trace synchronously before forwarding the request, so Opik
+API latency delays the provider request even when trace creation fails. The
+response span is delivered in the background. For a streaming response, the
+policy observes a clone of the original stream when it is still readable; the
+client does not wait for response-span delivery. If an earlier response hook has
+already consumed the original stream, output tracing is skipped and the client
+response continues unchanged.
+
+## Configure the policy
+
+Create or select an Opik project and workspace, then generate an API key.
+Declare the policy in `config/policies.json` and add it to each application
+chain that should emit traces:
+
+```json
+{
+  "name": "comet-opik-tracing-v2-inbound",
+  "policyType": "comet-opik-tracing-v2",
+  "handler": {
+    "export": "CometOpikTracingV2InboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "apiKey": "$env(COMET_OPIK_API_KEY)",
+      "projectName": "your-project-name",
+      "workspace": "your-workspace"
+    }
+  }
+}
+```
+
+Place the policy near the end of the chain so the trace records request-body
+changes made by earlier policies. The recorded model label comes from the app
+configuration when available, then falls back to the request body. A model
+selected through request-scoped routing is not included in this trace label.
+
+## Options
+
+| Option           | Default                          | What it does                                           |
+| ---------------- | -------------------------------- | ------------------------------------------------------ |
+| `apiKey`         | Required                         | Authenticates to Comet Opik.                           |
+| `projectName`    | Required                         | Selects the Opik project that receives traces.         |
+| `workspace`      | Required                         | Selects the Opik workspace.                            |
+| `baseUrl`        | `https://www.comet.com/opik/api` | Overrides the Opik API URL.                            |
+| `endpoints`      | All shapes                       | Limits tracing to selected AI Gateway endpoint shapes. |
+| `onUnknownShape` | `skip`                           | Skips or denies a request whose shape cannot be read.  |
+
+As an observer, the policy fails open by default. A trace API failure is logged
+but does not fail the AI request. Setting `onUnknownShape` to `deny` only
+changes the behavior for an uninspectable request shape.
+
+## Trace structure
+
+The policy creates one top-level trace when the request begins and an LLM span
+when the response completes. Records include:
+
+- Prompt or input content and the model name.
+- Completion text for streaming and non-streaming responses.
+- Input, output, and total token counts when the provider reports them.
+- Zuplo request ID and route for correlation.
+- Temperature and maximum-token settings when present.
+
+In Opik, you can annotate these traces, group them into datasets, run heuristic
+or LLM-as-a-judge evaluations, compare model variants, and monitor quality and
+cost trends.
+
+## Additional resources
+
+- [Comet Opik documentation](https://www.comet.com/docs/opik/)
+- [Opik tracing guide](https://www.comet.com/docs/opik/tracing/log_traces)

package/docs/policies/comet-opik-tracing-v2-inbound/intro.md

@@ -0,0 +1,10 @@
+The Comet Opik Tracing policy sends AI Gateway requests, responses, token usage,
+and timing data to Comet Opik for observability and evaluation. It supports
+streaming and non-streaming traffic across all AI Gateway request shapes.
+
+Place it near the end of the application policy chain so traces reflect the
+request body after earlier policy changes. Creating the top-level trace is
+synchronous, so the provider request waits for the Opik API call to finish,
+including failed calls. Response-span delivery runs in the background and does
+not modify the client response. Streaming output tracing is skipped if an
+earlier response hook has already consumed the original stream.

package/docs/policies/{comet-opik-tracing-inbound → comet-opik-tracing-v2-inbound}/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/comet-opik-tracing-inbound.json",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/comet-opik-tracing-v2-inbound.json",
   "type": "object",
   "title": "Comet Opik Tracing",
   "isDeprecated": false,
@@ -9,7 +9,8 @@
   "isInternal": false,
   "isBeta": false,
   "isHidden": false,
-  "requiresAI": false,
+  "requiresAI": true,
+  "policyType": "comet-opik-tracing-v2",
   "products": ["ai-gateway"],
   "description": "Comet Opik Tracing Inbound Policy",
   "deprecatedMessage": "",
@@ -21,7 +22,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "CometOpikTracingInboundPolicy",
+          "const": "CometOpikTracingV2InboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -29,9 +30,17 @@
           "description": "The module containing the policy"
         },
         "options": {
+          "x-zuplo-policy-type": "comet-opik-tracing-v2",
           "title": "Comet Opik Tracing",
           "description": "Track AI Gateway requests and responses using Comet Opik's LLM observability platform.",
           "type": "object",
+          "examples": [
+            {
+              "apiKey": "$env(COMET_OPIK_API_KEY)",
+              "projectName": "your-project-name",
+              "workspace": "your-workspace"
+            }
+          ],
           "properties": {
             "apiKey": {
               "description": "The Comet Opik API key for authentication.",
@@ -49,6 +58,28 @@
               "x-advanced": true,
               "description": "The base URL for the Comet Opik API (optional, defaults to https://www.comet.com/opik/api).",
               "type": "string"
+            },
+            "endpoints": {
+              "type": "array",
+              "title": "Applicable Endpoints",
+              "x-advanced": true,
+              "description": "The endpoint shapes this policy applies to. Omit to apply to all (openai-chat, openai-responses, anthropic-messages).",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "openai-chat",
+                  "openai-responses",
+                  "anthropic-messages"
+                ]
+              }
+            },
+            "onUnknownShape": {
+              "type": "string",
+              "title": "On Unknown Shape",
+              "x-advanced": true,
+              "description": "What to do on a shape the policy cannot read. As an observer this defaults to 'skip' (fail open — pass through untraced).",
+              "enum": ["deny", "skip"],
+              "default": "skip"
             }
           },
           "required": ["apiKey", "projectName", "workspace"],
@@ -57,9 +88,13 @@
       },
       "examples": [
         {
-          "export": "CometOpikTracingInboundPolicy",
+          "export": "CometOpikTracingV2InboundPolicy",
           "module": "$import(@zuplo/runtime)",
-          "options": {}
+          "options": {
+            "apiKey": "$env(COMET_OPIK_API_KEY)",
+            "projectName": "your-project-name",
+            "workspace": "your-workspace"
+          }
         }
       ]
     }

package/docs/policies/complex-rate-limit-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "complex-rate-limit-inbound",
   "products": ["api-gateway"],
   "description": "The Complex Rate Limiting policy is an advanced rate limiting policy that let's you set rate limits based on custom counters (not just requests)",
   "deprecatedMessage": "",

package/docs/policies/composite-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "composite-inbound",
   "products": ["api-gateway"],
   "description": "Creates a composite, or group policy - composed of other inbound policies. For reuse across routes.",
   "deprecatedMessage": "",

package/docs/policies/composite-outbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "composite-outbound",
   "products": ["api-gateway"],
   "description": "Creates a composite, or group policy - composed of other outbound policies. For reuse across routes.",
   "deprecatedMessage": "",

package/docs/policies/curity-phantom-token-inbound/schema.json

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "curity-phantom-token-inbound",
   "products": ["api-gateway"],
   "description": "Authenticate users using the Curity Phantom Token Pattern.",
   "deprecatedMessage": "",

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

@@ -33,7 +33,7 @@ identifiers, `secret-aws` enables both AWS entities. Two named groups (`pii`,
 | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `pii`       | `contact` + `id` + `finance-credit-card` + `finance-iban`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | 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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
@@ -50,9 +50,12 @@ 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.
+The threshold is configurable via `minConfidence` (default `0.5`). Lowering it
+surfaces context-dependent entities without their context words. Raising it is
+not a precision filter: any recognizer whose base confidence falls below the
+threshold stops matching except near its context words, and most
+checksum-validated recognizers run at `0.85`, so high thresholds disable most
+of the catalog. To narrow detection, scope the `entities` list instead.
 
 ## Custom patterns
 
@@ -62,11 +65,23 @@ JavaScript regular expression `pattern`, and optionally a `confidence` and
 and skipped rather than failing the request. Remember to escape backslashes for
 JSON (for example `\\d` to match a digit).
 
+## Allowed values
+
+Use `allowValues` to exempt specific values that would otherwise match — for
+example the Stripe test card number `4242 4242 4242 4242` in a payments
+sandbox, or a public support email address. Entries are compared against the
+exact matched text (case-sensitive, separators included), so list every
+written form you want to allow.
+
 ## 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.
+binary bodies pass through untouched. Server-sent event streams
+(`text/event-stream`) are excluded from the default allow-list: scanning
+buffers the whole body, which would hold back every event until the stream
+ends. Override the allow-list with the `contentTypes` option if you need to
+scan a different set of content types (including `text/event-stream`, if you
+accept the buffering).
 
 ## Configuration
 
@@ -79,6 +94,7 @@ binary bodies pass through untouched. Override the allow-list with the
 - `action`: `mask`, `block`, or `log`. **Default:** `mask`
 - `mask`: Replacement string used when `action` is `mask`. **Default:**
   `[REDACTED]`
+- `allowValues`: Exact matched-text values that are never reported
 - `minConfidence`: Detection threshold (0-1). **Default:** `0.5`
 - `contentTypes`: Override the scannable content-type allow-list
 

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

@@ -10,6 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
+  "policyType": "data-loss-prevention-inbound",
   "products": ["api-gateway"],
   "description": "Scans the incoming request 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 forwarding the request), `block` (reject with a `422` listing the detected entity names only), or `log` (record a warning and forward unchanged). Only text content types are inspected; binary bodies pass through untouched, and the body is read from a clone so the upstream still receives the original stream.",
   "deprecatedMessage": "",
@@ -187,6 +188,14 @@
                 }
               }
             },
+            "allowValues": {
+              "type": "array",
+              "x-advanced": true,
+              "description": "Values that are never reported as findings, compared against the exact matched text (case-sensitive, separators included). Use this to exempt well-known non-sensitive values that share a sensitive shape — for example the Stripe test card number `4242 4242 4242 4242` in a payments sandbox, or a public support email address. List every written form you want to allow (a spaced and an unspaced card number are different matches).",
+              "items": {
+                "type": "string"
+              }
+            },
             "minConfidence": {
               "type": "number",
               "minimum": 0,
@@ -194,7 +203,7 @@
               "default": 0.5,
               "x-show-example": false,
               "x-advanced": true,
-              "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."
+              "description": "Minimum confidence (0-1) a match must reach to count as a finding. Every match starts at its recognizer's base confidence and gains a fixed boost of 0.45 when one of the recognizer's context words appears near it. Ambiguous shapes (for example `finance-us-bank-account` or `finance-cvv`) have a low base confidence and only cross the default threshold of 0.5 with that boost; lower the threshold to surface them without context. Raising the threshold is not a precision filter: any recognizer whose base confidence falls below it stops matching entirely except near its context words, and most checksum-validated recognizers run at 0.85, so values above 0.85 disable most of the catalog. To narrow detection, scope the `entities` list instead."
             },
             "contentTypes": {
               "type": "array",