zuplo 6.71.21 → 6.71.23

package/docs/articles/api-key-api.mdx

@@ -84,9 +84,9 @@ inside Zuplo)
 ```bash
 # Your Zuplo Account Name
 export ACCOUNT_NAME=my-account
-# Your bucket API URL (Found in Settings > General)
+# Your bucket name (Found in Services > API Key Service)
 export BUCKET_NAME=my-bucket
-# Your Zuplo API Key (Found in Settings > Zuplo API Keys)
+# Your Zuplo API Key (Found in Account Settings > Zuplo API Keys)
 export API_KEY=zpka_YOUR_API_KEY
 ```
 

package/docs/articles/graphql-caching.mdx

@@ -0,0 +1,96 @@
+---
+title: Cache GraphQL responses with Zuplo
+sidebar_label: Cache responses
+description:
+  Serve repeated GraphQL queries from the edge with the GraphQL Cache policy to
+  cut latency and reduce load on your origin.
+tags:
+  - caching
+  - backends
+---
+
+GraphQL clients send queries as POST request bodies, so a normal CDN — which
+keys on the URL — can't cache them. The
+[`graphql-cache-inbound`](../policies/graphql-cache-inbound.mdx) policy solves
+this: it parses each query, normalizes it into a canonical form, and caches the
+response in a [ZoneCache](../programmable-api/zone-cache.mdx) at the edge. Two
+requests that are semantically identical share a cache entry even when their
+bodies differ byte-for-byte.
+
+Only `query` operations are cached. Mutations, subscriptions, malformed
+documents, and responses that contain GraphQL `errors` are always forwarded to
+your origin untouched.
+
+## Add the cache policy
+
+Add `graphql-cache-inbound` to the inbound policies of your GraphQL route.
+
+<Stepper>
+
+1. **Open `policies.json`**
+
+   In the Zuplo Portal, open the **Code** tab and add the policy definition:
+
+   ```json title="config/policies.json"
+   {
+     "name": "graphql-cache",
+     "policyType": "graphql-cache-inbound",
+     "handler": {
+       "export": "GraphQLCacheInboundPolicy",
+       "module": "$import(@zuplo/graphql)",
+       "options": {
+         "cacheName": "graphql-responses",
+         "ttlSeconds": 60
+       }
+     }
+   }
+   ```
+
+2. **Attach it to your GraphQL route**
+
+   Add `"graphql-cache"` to the route's inbound policies in `routes.oas.json`,
+   ahead of any policy that rewrites the request.
+
+3. **Verify the cache is working**
+
+   Send the same query twice and inspect the response headers. The policy adds
+   `x-cache: MISS` on the first request and `x-cache: HIT` on the second. The
+   `x-cache-key` header (first 8 characters of the cache key) confirms two
+   requests resolve to the same entry.
+
+</Stepper>
+
+## Cache authenticated traffic safely
+
+By default, requests that carry an `authorization` or `cookie` header are
+**not** cached — otherwise the first user's response would be served to
+everyone. To cache per-user, list the headers that make a response user-specific
+in `cacheKeyHeaders`. Each distinct value gets its own entry:
+
+```json title="config/policies.json"
+{
+  "options": {
+    "ttlSeconds": 30,
+    "cacheKeyHeaders": ["authorization"]
+  }
+}
+```
+
+:::caution
+
+Setting `cacheKeyHeaders` to an empty array `[]` caches a single response and
+shares it across all callers. Only do this when the response genuinely doesn't
+depend on who is calling — otherwise one caller's data leaks to others.
+
+:::
+
+See the [GraphQL Cache policy reference](../policies/graphql-cache-inbound.mdx)
+for the full option matrix, including how credentialed requests fail safe.
+
+## Next steps
+
+- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
+  introspection controls
+- [GraphQL on Zuplo](./graphql.mdx) — set up the endpoint and Dev Portal docs
+- [GraphQL analytics](../analytics/tabs/graphql.md) — watch hit rates and
+  latency once traffic flows

package/docs/articles/graphql-security.mdx

@@ -2,179 +2,190 @@
 title: Secure your GraphQL API with Zuplo
 sidebar_label: Secure your GraphQL API
 description:
-  Learn how to secure your GraphQL API using Zuplo's security policies to
-  prevent DoS attacks and protect schema information.
+  Protect your GraphQL API from denial-of-service attacks and schema discovery
+  using Zuplo's GraphQL security policies.
 tags:
   - authentication
   - backends
 ---
 
-**Secure your GraphQL API with Zuplo**
+GraphQL gives clients enormous flexibility over what they ask for — which is
+also what makes it easy to abuse. A single request can nest arbitrarily deep,
+fan out into thousands of resolver calls, or map your entire schema through
+introspection. Zuplo ships three policies that close these gaps at the edge,
+before a malicious request ever reaches your origin:
 
-GraphQL is a powerful query language for your APIs. While it offers great
-flexibility for clients, it also exposes potential security risks. Fortunately,
-with Zuplo, you can secure your GraphQL API by implementing various policies.
-This article walks you through our security policies:
-[GraphQL Complexity Limit](/docs/policies/graphql-complexity-limit-inbound), and
-[GraphQL Disable Introspection](/docs/policies/graphql-disable-introspection-inbound).
+| Risk                | Policy                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| Deep / costly query | [`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx)           |
+| Schema discovery    | [`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx) |
+| Schema over-sharing | [`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx) |
 
-## 1. Understanding the Risks
+This guide explains each risk and shows the policy configuration that addresses
+it. It assumes you've already
+[added a GraphQL endpoint to your gateway](./graphql.mdx).
 
-### a. Deeply Nested Queries
+## Understand the risks
 
-Without restrictions, a client can send deeply nested queries that could
-potentially overwhelm your server, resulting in a Denial of Service (DoS)
-attack. This is because deeply nested queries can cause the server to process a
-huge amount of data and operations. While this might be a planned attack, it
-could also be a mistake by a client who is unaware of the query depth limit.
+### Deeply nested or expensive queries
 
-### b. Query Complexity
+Without limits, a client can send a deeply nested query that forces your server
+to resolve a huge graph of data, or a flat-but-expensive query that triggers
+thousands of resolver calls. Either can exhaust resources and cause a
+denial-of-service — whether the client is a deliberate attacker or simply
+unaware of the cost of their query.
 
-Even without deep nesting, a query can be crafted to be very complex. This could
-force your server to execute resource-intensive operations, potentially slowing
-down the system or causing a DoS.
+### Introspection
 
-### c. Introspection
+GraphQL lets clients introspect your schema with `__schema` and `__type`
+queries. This is invaluable during development, but in production it hands
+potential attackers a complete map of your types, fields, and relationships.
 
-GraphQL allows clients to introspect your schema. While this is beneficial
-during development, it can expose detailed schema information to potential
-attackers in production.
+## Limit query depth and complexity
 
-## 2. Add your GraphQL API & setting up Policies
+The
+[`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx)
+policy guards against expensive queries in two complementary ways. You can use
+either or both.
 
-### Set Up POST Endpoint
+### Depth limit
 
-If you didn't already do so, you need to set up a POST endpoint in your API.
-This endpoint will be used to send the GraphQL queries to your API. The
-urlRewriteHandler to rewrite the request to your GraphQL API. For this example
-let's assume your GraphQL API is hosted at `https://api.example.com/graphql`.
+A depth limit caps how many levels a query can nest. It needs no schema and is
+the simplest first line of defense. Add it under `useDepthLimit`:
 
-To do so, add the following to your `config/routes.oas.json`
-
-```json
+```json title="config/policies.json"
 {
-  "post": {
-    "summary": "GraphQL Query",
-    "description": "The endpoint for GraphQL queries.",
-    "x-zuplo-route": {
-      "corsPolicy": "none",
-      "handler": {
-        "export": "urlRewriteHandler",
-        "module": "$import(@zuplo/runtime)",
-        "options": {
-          "rewritePattern": "https://api.example.com/graphql"
-        }
-      },
-      "policies": {
-        "inbound": [
-          "graphql-complexity-limit-policy",
-          "graphql-disable-introspection-policy"
-        ]
+  "name": "graphql-complexity-limit-policy",
+  "policyType": "graphql-complexity-limit-inbound",
+  "handler": {
+    "export": "GraphQLComplexityLimitInboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "useDepthLimit": {
+        "depthLimit": 20
       }
-    },
-    "operationId": "52bdf225-eaa7-441c-afb9-b7df046a142e"
+    }
   }
 }
 ```
 
-For all the risks mentioned above, Zuplo offers policies that can be configured
-to protect your GraphQL API. These policies can be configured for Zuplo. We'll
-create the configuration for the three policies `graphql-depth-limit`,
-`graphql-complexity-points` and `graphql-disable-introspection-policy` next.
+### Complexity limit
 
-### a. GraphQL Depth Limit
+A complexity limit scores each query against your schema and rejects queries
+above a threshold, catching expensive queries that aren't necessarily deep.
+Because it scores against the schema, it needs your GraphQL endpoint URL for
+introspection. Combine it with the depth limit:
 
-This policy limits how deep a query can be nested. Check our
-[detailed policy documentation](/docs/policies/graphql-complexity-limit-inbound)
-for more information.
-
-Add this into your `config/policies.json`
-
-```json
+```json title="config/policies.json"
 {
-  "policies": [
-    {
-      "name": "graphql-complexity-limit-policy",
-      "policyType": "graphql-complexity-limit-inbound",
-      "handler": {
-        "export": "GraphQLComplexityLimitInboundPolicy",
-        "module": "$import(@zuplo/graphql)",
-        "options": {
-          "useDepthLimit": {
-            "depthLimit": 20
-          }
-        }
+  "name": "graphql-complexity-limit-policy",
+  "policyType": "graphql-complexity-limit-inbound",
+  "handler": {
+    "export": "GraphQLComplexityLimitInboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "useDepthLimit": {
+        "depthLimit": 20
+      },
+      "useComplexityLimit": {
+        "complexityLimit": 50,
+        "endpointUrl": "https://api.example.com/graphql"
       }
     }
-  ]
+  }
 }
 ```
 
-By limiting the query depth, you prevent malicious or mistakenly deep queries
-from consuming excessive server resources.
+A query that exceeds either limit is rejected with a `400` and a GraphQL error;
+requests within the limits pass through. See the
+[policy reference](../policies/graphql-complexity-limit-inbound.mdx) for the
+full option set.
 
-### b. GraphQL Complexity Limit
+## Disable introspection in production
 
-We can extend the same policy to also check for complexity. By defining a max
-for each type of operation, and then it limits the total complexity a query can
-have. In order to use the Complexity Limit you need to allow introspection in
-your GraphQL API.
+The
+[`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx)
+policy blocks any query containing `__schema` or `__type` with a `403`, hiding
+your schema from clients. It takes no options:
 
-```json
+```json title="config/policies.json"
 {
-  "policies": [
-    {
-      "name": "graphql-complexity-limit-policy",
-      "policyType": "graphql-complexity-limit-inbound",
-      "handler": {
-        "export": "GraphQLComplexityLimitInboundPolicy",
-        "module": "$import(@zuplo/graphql)",
-        "options": {
-          "useDepthLimit": {
-            "depthLimit": 20
-          },
-          "useComplexityLimit": {
-            "complexityLimit": 50,
-            "endpointUrl": "https://api.example.com/graphql"
-          }
-        }
+  "name": "graphql-disable-introspection-policy",
+  "policyType": "graphql-disable-introspection-inbound",
+  "handler": {
+    "export": "GraphQLDisableIntrospectionInboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {}
+  }
+}
+```
+
+## Expose a partial schema instead
+
+Disabling introspection entirely isn't always what you want. If you need clients
+(or [MCP-connected AI agents](../mcp-server/graphql.mdx)) to introspect part of
+your schema while keeping sensitive types and fields hidden, use the outbound
+[`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx)
+policy. It strips chosen types and fields from introspection responses:
+
+```json title="config/policies.json"
+{
+  "name": "graphql-introspection-filter-policy",
+  "policyType": "graphql-introspection-filter-outbound",
+  "handler": {
+    "export": "GraphQLIntrospectionFilterOutboundPolicy",
+    "module": "$import(@zuplo/graphql)",
+    "options": {
+      "excludeTypes": ["AdminUser"],
+      "excludeTypeFields": {
+        "User": ["password", "ssn"],
+        "Query": ["adminUsers"]
       }
     }
-  ]
+  }
 }
 ```
 
-The complexity limit ensures that a potential attacker can't overload the system
-by sending overly complicated queries.
-
-### c. GraphQL Disable Introspection
+## Attach the policies to your route
 
-Disable introspection in production environments to hide schema details.
+Add the inbound policies to your GraphQL route in `routes.oas.json`. The
+outbound filter policy goes in the `outbound` array:
 
-```json
+```json title="config/routes.oas.json"
 {
-  "policies": [
-    {
-      "name": "graphql-disable-introspection-policy",
-      "policyType": "graphql-disable-introspection-inbound",
+  "post": {
+    "summary": "GraphQL Endpoint",
+    "x-graphql": true,
+    "x-zuplo-route": {
+      "corsPolicy": "none",
       "handler": {
-        "export": "GraphQLDisableIntrospectionInboundPolicy",
-        "module": "$import(@zuplo/graphql)",
-        "options": {}
+        "export": "urlRewriteHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rewritePattern": "https://api.example.com/graphql"
+        }
+      },
+      "policies": {
+        "inbound": [
+          "graphql-complexity-limit-policy",
+          "graphql-disable-introspection-policy"
+        ]
       }
-    }
-  ]
+    },
+    "operationId": "graphql-secure"
+  }
 }
 ```
 
-By disabling introspection in production, you prevent attackers from gaining
-insights into your GraphQL schema, thereby reducing potential attack vectors.
+## Example repository
+
+For a complete, runnable setup, see the
+[GraphQL API with Zuplo example repository](https://github.com/zuplo/zuplo-graphql-example).
 
-## 4. Example Repository
+## Next steps
 
-For those who prefer a hands-on approach or wish to see these configurations in
-action, there is a GitHub repository with everything set up. This repository
-offers a comprehensive example of how to configure and secure a GraphQL API
-using Zuplo. Check out the
-[GraphQL API with Zuplo example repository](https://github.com/zuplo/zuplo-graphql-example)
-to dive deeper.
+- [Cache GraphQL responses](./graphql-caching.mdx) — cut latency with edge
+  caching
+- [Test GraphQL queries](./testing-graphql.mdx) — verify your secured endpoint
+- [GraphQL analytics](../analytics/tabs/graphql.md) — surface errors and monitor
+  traffic

package/docs/articles/graphql-support.mdx

@@ -0,0 +1,107 @@
+---
+title: GraphQL support on Zuplo
+sidebar_label: Overview
+description:
+  Everything Zuplo supports for GraphQL APIs — proxying, security, caching,
+  analytics, Dev Portal docs, and MCP — with links to each guide and policy.
+tags:
+  - backends
+---
+
+Zuplo treats GraphQL as a first-class backend. Proxy your existing GraphQL
+server through the gateway, then layer on security, caching, analytics, and
+documentation using policies built for the GraphQL request shape — where every
+operation is a `POST` to a single URL, so URL-based gateway features don't
+apply.
+
+This page summarizes what Zuplo supports for GraphQL and links to each guide and
+policy reference.
+
+:::tip{title="New here?"}
+
+Start with [Set up an endpoint](./graphql.mdx) to proxy your GraphQL API through
+the gateway, then come back to layer on the capabilities below.
+
+:::
+
+## Connect and route
+
+Proxy any GraphQL server through a `POST /graphql` route using the
+[URL Rewrite handler](../handlers/url-rewrite.mdx). The Route Designer ships a
+**GraphQL Endpoint** template, and the `x-graphql` route extension marks a route
+as GraphQL so the gateway and Dev Portal treat it accordingly.
+
+- [Set up an endpoint](./graphql.mdx) — add or mark a GraphQL route
+
+## Secure the endpoint
+
+GraphQL's flexibility is also its attack surface: a single request can nest
+arbitrarily deep, fan out into thousands of resolver calls, or map your whole
+schema through introspection. Zuplo closes these gaps at the edge.
+
+| Risk                | What Zuplo does                                  |
+| ------------------- | ------------------------------------------------ |
+| Deep / costly query | Reject queries over a depth or complexity score  |
+| Schema discovery    | Block introspection in production                |
+| Schema over-sharing | Strip chosen types and fields from introspection |
+
+- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
+  introspection controls
+
+## Accelerate with caching
+
+A normal CDN keys on the URL, so it can't cache GraphQL queries sent as request
+bodies. The GraphQL cache parses each query, normalizes it into a canonical
+form, and serves semantically identical queries from one edge cache entry.
+
+- [Cache GraphQL responses](./graphql-caching.mdx) — serve repeated queries from
+  the edge
+
+## Observe traffic
+
+Report GraphQL operations and their errors to analytics, even when the upstream
+returns errors inside a `200` response. The GraphQL analytics dashboard surfaces
+operation volume, latency, and error classes once traffic flows.
+
+- [GraphQL analytics](../analytics/tabs/graphql.md) — monitor operations,
+  latency, and errors
+
+## Document in the Dev Portal
+
+The `@zudoku/plugin-graphql` package renders a browsable type reference and an
+interactive playground in your Dev Portal, generated from your schema or a live
+endpoint. Register one instance per API.
+
+- [Document the API in your Dev Portal](./graphql.mdx#document-the-api-in-your-dev-portal)
+  — add the GraphQL plugin
+
+## Expose GraphQL to AI agents
+
+Turn GraphQL queries into MCP tools so AI agents can call your API through the
+Model Context Protocol, with the same policies and auth applied.
+
+- [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose queries as
+  MCP tools
+
+## Policies at a glance
+
+Every GraphQL-aware policy Zuplo ships, with its direction and purpose:
+
+| Policy                                                                                           | Direction | Purpose                                           |
+| ------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------- |
+| [`graphql-cache-inbound`](../policies/graphql-cache-inbound.mdx)                                 | Inbound   | Cache repeated queries at the edge                |
+| [`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx)           | Inbound   | Reject queries that are too deep or too expensive |
+| [`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx) | Inbound   | Block schema introspection in production          |
+| [`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx) | Outbound  | Hide chosen types and fields from introspection   |
+| [`graphql-analytics-outbound`](../policies/graphql-analytics-outbound.mdx)                       | Outbound  | Report operations and errors to analytics         |
+
+## Next steps
+
+- [Set up an endpoint](./graphql.mdx) — proxy your GraphQL API through the
+  gateway
+- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
+  introspection controls
+- [Cache GraphQL responses](./graphql-caching.mdx) — cut latency with edge
+  caching
+- [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose queries to
+  AI agents

package/docs/articles/graphql.mdx

@@ -18,6 +18,7 @@ your schema in the Dev Portal. This guide walks you through setting it up.
       Rewrite handler
 - [ ] Tag the route with the `x-graphql` extension
 - [ ] Surface failed operations with the `graphql-analytics-outbound` policy
+- [ ] Add caching and security policies to protect and accelerate the endpoint
 - [ ] Add the `graphqlPlugin` to the Developer Portal
 
 :::
@@ -111,6 +112,23 @@ To fine-tune analytics, see the
 [GraphQL Analytics policy reference](../policies/graphql-analytics-outbound.mdx)
 for the full set of options.
 
+## Protect and accelerate the endpoint
+
+Once requests are flowing, attach GraphQL-aware policies to the route. Zuplo
+ships a set built specifically for the GraphQL request shape:
+
+| Goal                                       | Policy                                                                                           |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| Cache repeated queries at the edge         | [`graphql-cache-inbound`](../policies/graphql-cache-inbound.mdx)                                 |
+| Block deep or expensive queries            | [`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx)           |
+| Disable schema introspection in production | [`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx) |
+| Hide sensitive types from introspection    | [`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx) |
+| Report failed operations to analytics      | [`graphql-analytics-outbound`](../policies/graphql-analytics-outbound.mdx)                       |
+
+See [Secure your GraphQL API](./graphql-security.mdx) for the complexity and
+introspection policies, and [Cache GraphQL responses](./graphql-caching.mdx) to
+serve identical queries from the edge.
+
 ## Document the API in your Dev Portal
 
 The `@zudoku/plugin-graphql` package renders a browsable type reference and a
@@ -161,6 +179,8 @@ the playground is pointed at the right endpoint.
 
 - [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
   introspection policies
+- [Cache GraphQL responses](./graphql-caching.mdx) — serve repeated queries from
+  the edge
 - [Testing GraphQL queries](./testing-graphql.mdx) — test the endpoint from the
   Zuplo Portal or external tools
 - [GraphQL analytics](../analytics/tabs/graphql.md) — monitor operation volume,

package/docs/articles/hosting-options.mdx

@@ -46,16 +46,17 @@ For more information, see the
 
 ## 3. Self-Hosted (On-Premises)
 
-Run Zuplo on your own infrastructure in any cloud or private data center using
-Kubernetes. Zuplo Self-Hosted runs exclusively on Kubernetes and can be deployed
-to any Kubernetes environment. Deployment is simple and uses Helm charts.
-
-Self-Hosted is available in two deployment models:
-
-- **Hybrid Deployment**: Run the Zuplo API Gateway on your Kubernetes cluster
-  while leveraging shared services for features such as rate limiting
-- **Full Self-Hosted**: Run all Zuplo components on your Kubernetes cluster for
-  complete control and isolation
+Run Zuplo on your own infrastructure in any cloud or private data center. Zuplo
+Self-Hosted runs exclusively on Kubernetes and is installed with a single Helm
+chart into your cluster.
+
+In the standard hybrid deployment model, you run the Zuplo API Gateway and its
+management plane on your Kubernetes cluster, while a small set of Zuplo cloud
+services provides supporting features such as deployment configuration and API
+key management. All API traffic to your gateways stays on your infrastructure.
+For environments with strict egress restrictions,
+[book a meeting](https://zuplo.com/meeting) to review your requirements with the
+Zuplo team.
 
 Self-Hosted is ideal for organizations that need:
 
@@ -63,8 +64,8 @@ Self-Hosted is ideal for organizations that need:
 - To run Zuplo in a private data center or on-premises Kubernetes environment
 - To meet strict data sovereignty or regulatory requirements
 - To integrate with existing on-premises systems and networks
-- To customize the deployment architecture to match your specific requirements
 
 For more information, see the
-[Self-Hosted documentation](/docs/self-hosted/overview) or
-[book a meeting](https://zuplo.com/meeting) with us.
+[Self-Hosted documentation](/docs/self-hosted/overview.md), including the
+[requirements](/docs/self-hosted/overview.md#requirements) to prepare for a
+deployment, or [book a meeting](https://zuplo.com/meeting) with the Zuplo team.