zuplo 6.71.20 → 6.71.22

package/docs/dev-portal/zudoku/configuration/footer.mdx

@@ -59,7 +59,7 @@ footer: {
       links: [
         { label: "Features", href: "/features" },
         { label: "Pricing", href: "/pricing" },
-        { label: "Documentation", href: "/docs" },
+        { label: "Documentation", href: "/" },
         { label: "GitHub", href: "https://github.com/org/repo" }, // Auto-detected as external
       ],
     },
@@ -184,7 +184,7 @@ footer: {
       links: [
         { label: "Features", href: "/features" },
         { label: "Pricing", href: "/pricing" },
-        { label: "Documentation", href: "/docs" }
+        { label: "Documentation", href: "/" }
       ]
     },
     {

package/docs/dev-portal/zudoku/configuration/overview.md

@@ -46,7 +46,7 @@ const config: ZudokuConfig = {
     },
     { type: "link", to: "api", label: "API Reference" },
   ],
-  redirects: [{ from: "/", to: "/docs/introduction" }],
+  redirects: [{ from: "/", to: "/introduction" }],
   apis: {
     type: "file",
     input: "./apis/openapi.yaml",

package/docs/dev-portal/zudoku/guides/redirects.md

@@ -85,7 +85,7 @@ signal a permanent move; the JavaScript redirect used on generic static hosts is
 The most common use of redirects is setting a landing page for the root path of your portal:
 
 ```ts
-redirects: [{ from: "/", to: "/docs/introduction" }];
+redirects: [{ from: "/", to: "/introduction" }];
 ```
 
 This sends visitors who arrive at your portal's root URL to your introduction page.
@@ -98,7 +98,7 @@ external links continue to work:
 ```ts
 redirects: [
   { from: "/api/authentication", to: "/guides/auth-overview" },
-  { from: "/api/getting-started", to: "/docs/quickstart" },
+  { from: "/api/getting-started", to: "/quickstart" },
   { from: "/reference", to: "/api" },
 ];
 ```

package/docs/handlers/websocket-handler.mdx

@@ -5,22 +5,35 @@ sidebar_label: WebSocket Handler
 
 :::note
 
-This is an Enterprise only feature at this time. Please contact us to trial this
-or sign up for an Enterprise account.
+WebSocket handlers are an Enterprise-only feature at this time. Please contact
+us to trial this or sign up for an Enterprise account.
 
 :::
 
-The WebSocket Handler enables you to manage WebSocket connections to your
-backend WebSocket APIs. It can be configured alongside other existing policies
-like [Rate Limiting](../policies/rate-limit-inbound.mdx),
-[API Keys](../policies/api-key-inbound.mdx), etc. and is available for use on
+Zuplo provides two handlers for proxying WebSocket connections to your backend
+WebSocket APIs:
+
+- **`webSocketHandler`** proxies WebSocket traffic straight through to your
+  backend without inspecting the messages. Use this when you only need to
+  authenticate, rate limit, or route the connection.
+- **`webSocketPipelineHandler`** does everything `webSocketHandler` does and
+  additionally runs every message through a policy pipeline, so you can inspect,
+  transform, or drop individual messages in either direction. See the
+  [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
+
+Both handlers can be configured alongside other existing policies like
+[Rate Limiting](../policies/rate-limit-inbound.mdx),
+[API Keys](../policies/api-key-inbound.mdx), etc. and are available for use on
 all environments.
 
-This handler is only configurable via the JSON View on a project's Route
+These handlers are only configurable via the JSON View on a project's Route
 Designer or directly in your project's `*.oas.json` file.
 
 ## Setup in `routes.oas.json`
 
+This section covers the passthrough `webSocketHandler`. To intercept messages,
+see the [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
+
 Configuration of the WebSocket Handler is similar to other available handlers.
 Set the name of the path that your WebSocket API route will use, set the use of
 the `webSocketHandler` export from `@zuplo/runtime` module in the handler
@@ -62,6 +75,9 @@ The WebSocket Handler accepts the following options in the `options` property:
 - **`rewritePattern`** (required): The URL pattern for the backend WebSocket
   endpoint. Supports JavaScript string interpolation syntax for dynamic URL
   construction based on request data and environment variables.
+- **`policies`** (optional, `webSocketPipelineHandler` only): Configures the
+  message-interception policies that run on each WebSocket frame. See the
+  [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
 
 Similar to other handlers using `rewritePattern`, it supports JavaScript string
 interpolation syntax and can be used to shape the URL based on data from the

package/docs/handlers/websocket-pipeline-handler.mdx

@@ -0,0 +1,189 @@
+---
+title: WebSocket Pipeline Handler
+sidebar_label: WebSocket Pipeline Handler
+---
+
+:::note
+
+The WebSocket Pipeline Handler is an Enterprise-only feature. Please contact us
+to trial this or sign up for an Enterprise account.
+
+:::
+
+The `webSocketPipelineHandler` proxies WebSocket connections exactly like the
+[WebSocket Handler](./websocket-handler.mdx), but additionally passes every
+WebSocket message through a pipeline of **policy functions** before forwarding
+it. Each policy can inspect, transform, or drop the message. Use this to redact
+sensitive fields, enforce a message schema, filter events, or add observability
+to real-time traffic.
+
+Messages are intercepted in both directions, configured independently:
+
+- **`inbound`** policies process messages traveling from the client to your
+  backend.
+- **`outbound`** policies process messages traveling from your backend to the
+  client.
+
+:::note
+
+The pipeline only intercepts **message** events. Connection lifecycle events are
+handled automatically: when either side closes, the other side is closed, and
+socket errors are logged and forwarded. There is no policy hook for `close` or
+`error` events.
+
+:::
+
+## Configuration
+
+Use the `webSocketPipelineHandler` export and add an `inbound` and/or `outbound`
+array under `options.policies`. Each entry points to an exported function in one
+of your project's modules.
+
+```json
+"/my-websocket": {
+  "x-zuplo-path": {
+    "pathMode": "open-api"
+  },
+  "get": {
+    "summary": "WebSocket route with message interception",
+    "x-zuplo-route": {
+      "corsPolicy": "none",
+      "handler": {
+        "export": "webSocketPipelineHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rewritePattern": "https://myservice.com/websocket",
+          "policies": {
+            "inbound": [
+              {
+                "module": "$import(./modules/websocket-policies)",
+                "export": "redactInbound"
+              }
+            ],
+            "outbound": [
+              {
+                "module": "$import(./modules/websocket-policies)",
+                "export": "filterOutbound"
+              }
+            ]
+          }
+        }
+      },
+      "policies": {
+        "inbound": []
+      }
+    },
+    "operationId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
+  }
+}
+```
+
+:::caution{title="Two different policies blocks"}
+
+The `policies` object inside `handler.options` configures the **message**
+policies that run on each WebSocket frame. This is separate from the route-level
+`policies` block (the `inbound` array next to `handler`), which configures the
+standard request policies — such as [API Key](../policies/api-key-inbound.mdx)
+or [Rate Limiting](../policies/rate-limit-inbound.mdx) — that run once during
+the initial connection upgrade.
+
+:::
+
+The `rewritePattern` option behaves identically to the
+[WebSocket Handler](./websocket-handler.mdx#handler-options), including
+JavaScript string interpolation.
+
+## Writing a message policy
+
+A message policy is an exported function that matches the following signature:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+async function webSocketPolicy(
+  data: string,
+  target: WebSocket,
+  source: WebSocket,
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<unknown>;
+```
+
+| Parameter | Description                                                                                                                                                                                                                                                             |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`    | The message payload. For text protocols this is a string; binary frames arrive in the platform's binary form (for example, an `ArrayBuffer`). For an `inbound` policy this is the message from the client; for an `outbound` policy it is the message from the backend. |
+| `target`  | The destination socket the message is being forwarded to. For `inbound` this is the backend connection; for `outbound` it is the client connection.                                                                                                                     |
+| `source`  | The socket the message originated from. Call `source.send(...)` to send a message back to the originator, such as an acknowledgement or error.                                                                                                                          |
+| `request` | The original [`ZuploRequest`](../programmable-api/zuplo-request.mdx) from the connection upgrade.                                                                                                                                                                       |
+| `context` | The [`ZuploContext`](../programmable-api/zuplo-context.mdx) for the connection.                                                                                                                                                                                         |
+
+The return value controls what happens next:
+
+- **Return the data** (modified or unchanged) to forward it to `target`. When
+  multiple policies are configured, the return value is passed as `data` to the
+  next policy in the array.
+- **Return `undefined`** to drop the message. It is not forwarded, and no
+  further policies run for that message.
+
+Policies run in the order they appear in the `inbound` / `outbound` array, and
+each policy may be asynchronous. If a policy throws, Zuplo logs the error and
+drops the message.
+
+## Example: redact fields from inbound messages
+
+This inbound policy parses each JSON message from the client, removes a
+sensitive field, and forwards the result to the backend.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export async function redactInbound(
+  data: string,
+  target: WebSocket,
+  source: WebSocket,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  let message: Record<string, unknown>;
+  try {
+    message = JSON.parse(data);
+  } catch (err) {
+    context.log.warn("Dropping non-JSON WebSocket message");
+    return undefined; // drop messages that aren't valid JSON
+  }
+
+  delete message.ssn;
+
+  return JSON.stringify(message);
+}
+```
+
+## Example: filter outbound messages
+
+This outbound policy inspects messages from the backend and drops internal
+events so they never reach the client. Other messages pass through unchanged.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export async function filterOutbound(
+  data: string,
+  target: WebSocket,
+  source: WebSocket,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const message = JSON.parse(data);
+
+  if (message.type === "internal") {
+    return undefined; // drop internal events; the client never sees them
+  }
+
+  return data;
+}
+```
+
+You can configure multiple policies in each direction to compose behavior — for
+example, one policy to validate a message against a schema and a second to
+redact fields. Because each policy receives the previous policy's output, order
+matters.

package/docs/mcp-gateway/cross-app-access/overview.mdx

@@ -10,9 +10,8 @@ description: |
 
 :::note{title="Beta"}
 
-Cross App Access support is in beta and builds on the
-[MCP Gateway](../introduction.mdx), which is also in beta. The configuration
-model and policy options may change before general availability.
+Cross App Access support is in beta. The configuration model and policy options
+may change before general availability.
 
 :::
 

package/docs/mcp-gateway/introduction.mdx

@@ -7,15 +7,6 @@ description:
   analytics.
 ---
 
-:::note{title="Beta"}
-
-The MCP Gateway is in beta. The configuration model and APIs may change before
-general availability. Build with it, share feedback — just pin a
-[compatibility date](./code-config/compatibility-dates.mdx) and expect the
-occasional rough edge.
-
-:::
-
 The Zuplo MCP Gateway fronts one or more remote
 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers with a
 single, OAuth-protected endpoint that AI clients connect to. Users sign in once

package/docs/policies/_index.md

@@ -43,7 +43,8 @@
 | formdata-to-json-inbound | Form Data to JSON | Converts form data in the incoming request to JSON. | api-gateway |
 | galileo-tracing-inbound | Galileo Tracing | Galileo Tracing Inbound Policy | ai-gateway |
 | geo-filter-inbound | Geo-location filtering | Block requests based on geo-location parameters: country, region code, and ASN | api-gateway |
-| graphql-analytics-outbound | GraphQL Analytics | Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.  Each error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. Bodies larger than `maxResponseBytes` (default 5 MiB) are not inspected.  The response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing. | api-gateway |
+| graphql-analytics-outbound | GraphQL Analytics | Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.  Each error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. The policy reads up to `maxScanBytes` of the body (128 KiB by default, 5 MiB maximum), scanning it for the `errors` token; a response larger than that is treated as error-free. When the token is found and the body fits, it is parsed and its errors reported.  The response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing. | api-gateway |
+| graphql-cache-inbound | GraphQL Cache | Caches GraphQL query responses at the edge so identical queries are served without a round-trip to the origin.  Unlike CDN caching that keys on the raw request body, this policy parses the GraphQL document and normalizes it before hashing: insignificant whitespace, field formatting, and fragment layout are collapsed, and variable object keys are sorted. Two requests that are semantically identical therefore share a cache entry even when their bodies differ byte-for-byte. There is no query size or nesting-depth limit.  Only `query` operations are cached. Mutations, subscriptions, malformed documents, and non-JSON bodies are forwarded to the origin untouched. Cache hits and misses are reported on the `x-cache` response header, with a short key fingerprint on `x-cache-key`.  To avoid serving one user's data to another, requests carrying an `authorization` or `cookie` header are not cached by default. Use `cacheKeyHeaders` to opt into caching them: each listed header's value is included in the cache key, so distinct credentials get distinct cache entries. | api-gateway |
 | graphql-complexity-limit-inbound | GraphQL Complexity Limit | Policy that limits the complexity and depth of GraphQL queries to prevent abuse. Protects your GraphQL API from expensive queries that could cause performance issues or denial of service attacks. | api-gateway |
 | graphql-disable-introspection-inbound | GraphQL Disable Introspection | Policy that disables GraphQL introspection queries in production. Introspection allows clients to discover the schema, which can be a security risk as it exposes your entire API structure. | api-gateway |
 | graphql-introspection-filter-outbound | GraphQL Introspection Filter | Filters GraphQL introspection responses to exclude specific types and fields.  This policy intercepts GraphQL introspection query responses and removes configured types and fields from the schema. Useful for hiding internal types or sensitive fields from the public schema. | api-gateway |
@@ -99,6 +100,7 @@
 | sleep-inbound | Sleep / Delay | Add a delay to the incoming request. Useful for testing. | api-gateway |
 | stripe-webhook-verification-inbound | Stripe Webhook Auth | The Stripe Webhook policy validates the authenticity of an incoming Stripe webhook. | api-gateway |
 | supabase-jwt-auth-inbound | Supabase JWT Auth | The Supabase JWT Authentication policy supports user JWT tokens created by Supabase. | api-gateway |
+| traffic-splitting-inbound | Traffic Splitting | Splits traffic randomly across a set of weighted base paths. On each request one base path is selected (weighted by `weight`) and written to the request custom context at `customOutputProperty`. Reference it from a later URL Rewrite `rewritePattern` or URL Forward `baseUrl`, e.g. `${context.custom.trafficSplitting.basePath}`. | api-gateway |
 | transform-body-inbound | Transform Request Body | Transform the body of an incoming request. | api-gateway |
 | transform-body-outbound | Transform Response Body | Transform the body of an outgoing response. | api-gateway |
 | upstream-azure-ad-service-auth-inbound | Upstream Azure AD Service Auth | Uses Azure Active Directory to add an Authorization header to the request in order to authenticate requests using Azure identity. | api-gateway |

package/docs/policies/graphql-analytics-outbound/doc.md

@@ -41,10 +41,13 @@ result in the batch.
 ## What is inspected
 
 Only responses with a JSON content type (`application/json` or any `+json` type
-such as `application/graphql-response+json`) are read, and bodies larger than
-`maxResponseBytes` (5 MiB by default) are skipped — by `Content-Length` when the
-header is present, or measured while reading when it is absent. Everything else
-passes through without the body being touched.
+such as `application/graphql-response+json`) are read. The policy reads up to
+`maxScanBytes` of the body (128 KiB by default, 5 MiB maximum) and scans it for
+the `errors` token; a response larger than that — by `Content-Length` when the
+header is present, or measured while reading when it is absent — is treated as
+error-free, so any errors it carries go unreported. Raise `maxScanBytes` if your
+GraphQL responses are larger. Everything else passes through without the body
+being touched.
 
 ## Logging
 
@@ -63,8 +66,9 @@ alert on it.
   `resolver`
 - `logErrors`: Also log a structured warning per errored response. **Default:**
   `false`
-- `maxResponseBytes`: Maximum response body size in bytes to inspect.
-  **Default:** `5242880` (5 MiB)
+- `maxScanBytes`: How many bytes of the response body to read and scan for the
+  `errors` token. A larger response is treated as error-free. Capped at 5 MiB.
+  **Default:** `131072` (128 KiB)
 
 ## Usage
 

package/docs/policies/graphql-analytics-outbound/schema.json

@@ -11,7 +11,7 @@
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],
-  "description": "Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.\n\nEach error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. Bodies larger than `maxResponseBytes` (default 5 MiB) are not inspected.\n\nThe response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing.",
+  "description": "Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.\n\nEach error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. The policy reads up to `maxScanBytes` of the body (128 KiB by default, 5 MiB maximum), scanning it for the `errors` token; a response larger than that is treated as error-free. When the token is found and the body fits, it is parsed and its errors reported.\n\nThe response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -64,12 +64,13 @@
               "default": false,
               "description": "When `true`, also write a structured warning to the request log (message, `extensions.code`, and path of each error — capped at the first 10) whenever a response contains GraphQL errors."
             },
-            "maxResponseBytes": {
+            "maxScanBytes": {
               "type": "integer",
               "minimum": 1,
-              "default": 5242880,
+              "maximum": 5242880,
+              "default": 131072,
               "x-show-example": false,
-              "description": "Maximum response body size in bytes the policy will inspect. Larger bodies — by `Content-Length`, or measured while reading when the header is absent — pass through without being scanned, so their GraphQL errors (if any) go unreported. The default is 5 MiB."
+              "description": "How many bytes of the response body the policy reads to look for GraphQL errors. The body is read and scanned for the `errors` token up to this limit; a body larger than the limit — by `Content-Length`, or measured while reading when the header is absent — is treated as error-free, so any errors it carries go unreported. The default of 128 KiB suits the common case, where servers emit `errors` near the front of the body. Raise it (up to the 5 MiB maximum) to detect errors in larger responses, at the cost of reading more of every response. When the token is found and the body fits within the limit, the body is parsed and its errors are reported."
             }
           }
         }

package/docs/policies/graphql-cache-inbound/doc.md

@@ -0,0 +1,137 @@
+The GraphQL Cache policy stores successful GraphQL query responses in a
+[ZoneCache](https://zuplo.com/docs/articles/zonecache) and serves later,
+identical queries directly from the edge.
+
+### How caching works
+
+For every inbound request the policy:
+
+1. Reads the request body and parses it as GraphQL JSON
+   (`{ "query": "...", "variables": { ... }, "operationName": "..." }`).
+2. Parses the query and re-prints it, producing a canonical form that ignores
+   insignificant whitespace, field formatting, and fragment layout.
+3. Canonicalizes the `variables` by recursively sorting object keys.
+4. Hashes the normalized query, canonicalized variables, and `operationName`
+   (SHA-256) into a cache key. `operationName` is included because a document
+   with multiple operations returns a different response depending on which
+   operation the client selects.
+
+On a **hit**, the cached response is returned immediately. On a **miss**, the
+request is forwarded to the origin and a successful response is stored for
+future requests.
+
+Every response served or stored by the policy carries two headers:
+
+- **`x-cache`** — `HIT` when served from cache, `MISS` when fetched from the
+  origin.
+- **`x-cache-key`** — the first 8 characters of the cache key, useful for
+  confirming that two requests resolve to the same entry.
+
+Both headers are added to `access-control-expose-headers` so browsers can read
+them, without overwriting any value an upstream CORS policy already set.
+
+### What is and isn't cached
+
+- Only `query` operations are cached. **Mutations** and **subscriptions** are
+  forwarded to the origin and never cached. In a multi-operation document the
+  operation selected by `operationName` is the one that decides this.
+- **Malformed** GraphQL and **non-JSON** bodies are forwarded untouched so the
+  origin can return a proper error. Documents with multiple operations but no
+  `operationName` (or an `operationName` that matches none) are also forwarded.
+- Only `200` responses are cached, and only when the body is a successful
+  GraphQL result. Because GraphQL returns execution errors with a `200` status
+  and an `errors` array, responses carrying a non-empty `errors` array — and
+  non-JSON `200` bodies — are **not** cached.
+
+### Options
+
+- **`cacheName`** - The name of the cache used to store responses. Defaults to
+  `graphql-responses`. Routes that share a name share a cache; use distinct
+  names to isolate caches per route or per upstream.
+- **`ttlSeconds`** - How long, in seconds, a cached response is served before it
+  is considered stale and the next request is forwarded to the origin to refresh
+  the entry. Defaults to `60`.
+- **`cacheKeyHeaders`** - Request header names whose values are included in the
+  cache key (matched case-insensitively), and the control for how credentialed
+  requests are cached. See
+  [Authentication and per-user caching](#authentication-and-per-user-caching)
+  below. Defaults to omitted.
+
+### Authentication and per-user caching
+
+A response cache keyed only on the query would serve the first user's response
+to everyone. To prevent that, the policy **does not cache requests that carry an
+`authorization` or `cookie` header** by default — those requests are forwarded
+to the origin every time.
+
+To cache authenticated traffic safely, list the headers that make a response
+user-specific in `cacheKeyHeaders`. Each listed header's value becomes part of
+the cache key, so every distinct value (for example, every bearer token) gets
+its own cache entry:
+
+```json
+{
+  "name": "graphql-cache",
+  "policyType": "graphql-cache-inbound",
+  "handler": {
+    "export": "GraphQLCacheInboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "ttlSeconds": 30,
+      "cacheKeyHeaders": ["authorization"]
+    }
+  }
+}
+```
+
+If a request still carries an `authorization` or `cookie` header that is **not**
+in `cacheKeyHeaders`, it is left uncached — so partially configuring the
+allowlist fails safe rather than leaking across users.
+
+#### Caching credentialed requests as a single shared entry
+
+Sometimes a request must carry `authorization` (or `cookie`) to be authorized,
+but the response is identical for everyone allowed through — the credential
+gates access without changing the data. In that case, set `cacheKeyHeaders` to
+an **empty array** to cache one response and share it across all callers:
+
+```json
+{
+  "name": "graphql-cache",
+  "policyType": "graphql-cache-inbound",
+  "handler": {
+    "export": "GraphQLCacheInboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "cacheKeyHeaders": []
+    }
+  }
+}
+```
+
+This is distinct from omitting the option: omitting it keeps the safe default
+(credentialed requests are not cached), whereas `[]` is an explicit assertion
+that the response does not depend on the caller. **Only use `[]` when that is
+true** — otherwise one caller's response will be served to others.
+
+Response cookies are never shared. `Set-Cookie` (along with `Set-Cookie2` and
+`Clear-Site-Data`) is stripped from the stored entry, so a cookie an origin sets
+on one caller's response is never replayed to another from cache. The caller
+whose request reached the origin still receives the original `Set-Cookie`.
+
+### Example
+
+```json
+{
+  "name": "graphql-cache",
+  "policyType": "graphql-cache-inbound",
+  "handler": {
+    "export": "GraphQLCacheInboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "cacheName": "graphql-responses",
+      "ttlSeconds": 60
+    }
+  }
+}
+```

package/docs/policies/graphql-cache-inbound/intro.md

@@ -0,0 +1,15 @@
+This policy caches GraphQL query responses at the edge so identical queries are
+served without a round-trip to your origin.
+
+Unlike CDN caching that keys on the raw request body, this policy parses each
+GraphQL document and normalizes it before building a cache key. Insignificant
+whitespace, field formatting, and fragment layout are collapsed, and variable
+object keys are sorted. As a result, two requests that are semantically
+identical share a cache entry even when their bodies differ byte-for-byte — and
+there is no query size or nesting-depth limit.
+
+Only `query` operations are cached. Mutations, subscriptions, malformed
+documents, and non-GraphQL bodies are always forwarded to the origin untouched.
+To avoid serving one user's data to another, requests carrying an
+`authorization` or `cookie` header are not cached unless you opt in with the
+`cacheKeyHeaders` option.

package/docs/policies/graphql-cache-inbound/schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/graphql/schemas/graphql-cache-inbound.json",
+  "type": "object",
+  "title": "GraphQL Cache",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Caches GraphQL query responses at the edge so identical queries are served without a round-trip to the origin.\n\nUnlike CDN caching that keys on the raw request body, this policy parses the GraphQL document and normalizes it before hashing: insignificant whitespace, field formatting, and fragment layout are collapsed, and variable object keys are sorted. Two requests that are semantically identical therefore share a cache entry even when their bodies differ byte-for-byte. There is no query size or nesting-depth limit.\n\nOnly `query` operations are cached. Mutations, subscriptions, malformed documents, and non-JSON bodies are forwarded to the origin untouched. Cache hits and misses are reported on the `x-cache` response header, with a short key fingerprint on `x-cache-key`.\n\nTo avoid serving one user's data to another, requests carrying an `authorization` or `cookie` header are not cached by default. Use `cacheKeyHeaders` to opt into caching them: each listed header's value is included in the cache key, so distinct credentials get distinct cache entries.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "GraphQLCacheInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/graphql)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "GraphQLCacheInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "required": [],
+          "additionalProperties": false,
+          "properties": {
+            "cacheName": {
+              "type": "string",
+              "default": "graphql-responses",
+              "examples": ["graphql-responses"],
+              "description": "The name of the cache used to store responses. Routes that share a name share a cache; use distinct names to isolate caches per route or per upstream."
+            },
+            "ttlSeconds": {
+              "type": "number",
+              "default": 60,
+              "examples": [60],
+              "description": "How long, in seconds, a cached response is served before it is considered stale and the next request is forwarded to the origin to refresh the entry."
+            },
+            "cacheKeyHeaders": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["authorization"]],
+              "description": "Request header names whose values are included in the cache key (matched case-insensitively), and the control for how credentialed requests are cached. Omit this option (the default) and requests carrying an `authorization` or `cookie` header are not cached, to avoid serving one user's response to another. List those headers to cache such requests keyed per value, so each distinct value gets its own entry (a credential header you don't list still blocks caching, so a partial list fails safe). Set it to an empty array `[]` to cache a single response shared across all callers — only do this when the response does not depend on who is calling, as it disables the per-user safety check."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "GraphQLCacheInboundPolicy",
+          "module": "$import(@zuplo/graphql)",
+          "options": {
+            "cacheKeyHeaders": ["authorization"],
+            "cacheName": "graphql-responses",
+            "ttlSeconds": 60
+          }
+        }
+      ]
+    }
+  }
+}