zuplo 6.67.32 → 6.68.0

package/docs/mcp-server/tools.mdx

@@ -0,0 +1,306 @@
+---
+title: MCP Server Tools
+sidebar_label: Tools
+---
+
+The MCP (Model Context Protocol) Server handler supports tools, enabling you to
+expose your API routes as executable functions that AI clients can call to
+perform actions or retrieve data.
+
+Tools are the core building block of MCP servers, allowing AI systems to
+interact with your services and discover capabilities through your Zuplo
+gateway.
+
+## Overview
+
+Zuplo's MCP tools work by automatically transforming your API routes into MCP
+tool definitions. When an AI client calls a tool, the MCP server invokes the
+corresponding route handler in your gateway.
+
+This means any existing API route can be instantly turned into an MCP tool with
+minimal configuration.
+
+## Configuration
+
+### Route Configuration
+
+Configure a route in your OpenAPI doc:
+
+```json
+{
+  "/weather/current": {
+    "get": {
+      "operationId": "getCurrentWeather",
+      "summary": "Get current weather",
+      "description": "Retrieve current weather conditions for a specified location",
+      "parameters": [
+        {
+          "name": "location",
+          "in": "query",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "default",
+          "module": "$import(./modules/weather)"
+        },
+        "mcp": {
+          "type": "tool",
+          "name": "get_current_weather",
+          "description": "Retrieve current weather conditions for a specified location"
+        }
+      }
+    }
+  }
+}
+```
+
+To provide MCP specific metadata for the tool, use the `mcp` property within
+`x-zuplo-route`:
+
+The `x-zuplo-route.mcp` configuration for tools supports:
+
+- `type` (`string`: optional, defaults to `tool`) - Set to `"tool"` to denote
+  this operation is an MCP tool.
+- `name` (`string`: optional) - The identifier for the MCP tool. Defaults to the
+  operation's `operationId`. If the `operationId` is not set, falls back to an
+  auto-generated name.
+- `description` (`string`: optional) - Description of what the tool does. Falls
+  back to the operation's `description` or `summary`. If the route's
+  `description` or `summary` fields are not set, falls back to an auto-generated
+  description.
+- `enabled` (`boolean`: optional) - Whether this tool is enabled. Defaults to
+  `true`.
+- `annotations` (`object`: optional) - An object containing tool annotations:
+  - `title` (`string`: optional) - A human-readable title for the tool, often
+    used by clients.
+  - `readOnlyHint` (`boolean`: optional) - Hint that the tool is read-only.
+  - `destructiveHint` (`boolean`: optional) - Hint that the tool has mutating
+    side effects.
+  - `idempotentHint` (`boolean`: optional) - Hint that the tool is idempotent.
+  - `openWorldHint` (`boolean`: optional) - Hint that the tool operates in an
+    open-world context of external entities (like web-search).
+- `_meta` (`object`: optional) - An object containing any arbitrary metadata.
+
+The route handler for your tool can be any standard Zuplo request handler like
+[the URL Forwarder](../handlers/url-forward.mdx) or
+[the Redirect handler](../handlers/redirect.mdx) or a
+[custom function module](../handlers/custom-handler.mdx). The route receives the
+request triggered by the MCP tool call within the gateway and returns a response
+that will be passed back through the MCP server to the AI client.
+
+:::tip
+
+`POST` routes with a `requestBody` and a defined `schema` are translated into an
+MCP tool's parameters. When invoked, these are validated by the MCP server to
+ensure the tool is being correctly used by the LLM.
+
+Other methods like `GET`, `DELETE`, etc. work in a similar fashion in order to
+support complex tools in the shape of your APIs.
+
+:::
+
+### MCP Server Handler Configuration
+
+Add tool configuration to your MCP Server handler options using the `operations`
+array:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "x-zuplo-route": {
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "name": "example-mcp-server",
+              "version": "1.0.0",
+              "operations": [
+                {
+                  "file": "./config/routes.oas.json",
+                  "id": "getCurrentWeather"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+See further details in the
+[MCP Server Handler documentation](../handlers/mcp-server.mdx).
+
+## Testing MCP Tools
+
+### List Available Tools
+
+Use the MCP `tools/list` method to see available tools:
+
+```bash
+curl https://my-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/list"
+  }'
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "tools": [
+      {
+        "name": "get_current_weather",
+        "description": "Retrieve current weather conditions for a specified location",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "location": {
+              "type": "string"
+            }
+          },
+          "required": ["location"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Call a Tool
+
+Use the MCP `tools/call` method to execute a tool:
+
+```bash
+curl https://my-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/call",
+    "params": {
+      "name": "get_current_weather",
+      "arguments": {
+        "location": "San Francisco"
+      }
+    }
+  }'
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"location\":\"San Francisco\",\"temperature\":72,\"condition\":\"Sunny\"}"
+      }
+    ]
+  }
+}
+```
+
+## Best Practices
+
+### Meaningful Names and Descriptions
+
+Always set meaningful `operationId`s (like `get_users`, `create_new_deployment`,
+or `update_shopping_cart`) and descriptions as these help LLMs understand
+exactly _what_ each tool does.
+
+When you need to provide more meaningful descriptions or names that don't align
+well with the `operationId`, set the metadata in `x-zuplo-route.mcp`.
+
+:::tip
+
+Read more about authoring usable tools and good prompt engineering practices
+with
+[Anthropic's Prompt engineering overview](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview).
+
+:::
+
+AI models rely heavily on tool descriptions to understand when and how to use a
+tool.
+
+- **Be Descriptive**: Explain exactly what the tool does and what inputs it
+  expects.
+- **Use Meaningful Names**: Operation IDs like `create_user` or
+  `search_products` are much better than `op1` or `endpoint`.
+
+### Schema Design
+
+Use descriptive and well-structured JSON schemas for your tools (in your OpenAPI
+`requestBody` and `response`). This is used by the server to validate MCP client
+inputs (that is, JSON generated by an LLM). Providing descriptive schemas
+ensures an MCP Client's LLM always has the appropriate context on exactly what
+arguments to provide to tools and can dramatically reduce invalid tool usage.
+This validation is done automatically.
+
+```json
+// Good! Uses descriptive names and specific types with limiters and formats.
+{
+  "type": "object",
+  "required": ["userId"],
+  "properties": {
+    "userId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Valid UUID for user ID"
+    },
+    "amount": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 10000,
+      "description": "Amount in cents"
+    }
+  }
+}
+```
+
+```json
+// Bad! Confusing. What's "a"? What's "b"? An LLM won't understand this.
+{
+  "type": "object",
+  "required": ["userId"],
+  "properties": {
+    "a": {
+      "type": "string"
+    },
+    "b": {
+      "type": "number"
+    }
+  }
+}
+```
+
+Defining clear schemas in your OpenAPI document ensures your handler always
+receives valid data. The MCP server uses these schemas to validate arguments
+provided by the AI client _before_ your handler is ever called. Input validation
+is an important part of MCP, so ensure you have strong validation in your
+OpenAPI JSON schemas!
+
+### Custom Tools
+
+For complex workflows that don't map 1:1 to a single API route, or require
+advanced logic, consider using [Custom MCP Tools](./custom-tools.mdx).

package/docs/policies/_index.md

@@ -0,0 +1,92 @@
+# Zuplo Policies
+
+| Policy ID | Name | Description | Products |
+| --- | --- | --- | --- |
+| ab-test-inbound | A/B Test Inbound | An A/B test policy is used to handle requests differently based on parameters such as user, ip, etc. | api-gateway |
+| ab-test-outbound | A/B Test Outbound | An A/B test policy is used to handle responses differently based on parameters such as user, ip, etc. | api-gateway |
+| acl-policy-inbound | Access Control List | The access control list inbound policy limits access to resources based on parameters on the authenticated user. | api-gateway |
+| set-query-params-inbound | Add or Set Query Parameters | Adds or sets query parameters on the incoming request. | api-gateway |
+| set-headers-inbound | Add or Set Request Headers | Adds or sets headers on the incoming request. | api-gateway |
+| akamai-ai-firewall | Akamai AI Firewall | Akamai AI Firewall Inbound Policy | ai-gateway |
+| amberflo-metering-inbound | Amberflo Metering / Billing | Amberflo is a usage metering and billing service. This policy allows you to send metering calls for each API to their meter ingest endpoint. | api-gateway |
+| api-key-inbound | API Key Authentication | 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. | api-gateway |
+| archive-request-aws-s3-inbound | Archive Request to AWS S3 | Archive the incoming request body to AWS S3 storage | api-gateway |
+| archive-request-azure-storage-inbound | Archive Request to Azure Storage | Archive the incoming request to Azure blob storage. | api-gateway |
+| archive-request-gcp-storage-inbound | Archive Request to GCP Storage | Archive the incoming request to Google Cloud Storage. | api-gateway |
+| archive-response-aws-s3-outbound | Archive Response to AWS S3 | Archive the outgoing response body to AWS S3 storage | api-gateway |
+| archive-response-azure-storage-outbound | Archive Response to Azure Storage | Archive the outgoing response to Azure blob storage. | api-gateway |
+| audit-log-inbound | Audit Logs | Capture detailed logs of requests for auditing purposes. | api-gateway |
+| auth0-jwt-auth-inbound | Auth0 JWT Auth | Authenticate users using Auth0 issued JWT tokens. | api-gateway |
+| authzen-inbound | AuthZEN Authorization | Authorize requests using an AuthZEN compatible PDP | api-gateway |
+| cognito-jwt-auth-inbound | AWS Cognito JWT Auth | Authenticate requests with JWT tokens issued by AWS Cognito. | api-gateway |
+| axiomatics-authz-inbound | Axiomatics Authorization | Authorize requests using Axiomatics Policy Server. | api-gateway |
+| basic-auth-inbound | Basic Auth | Authenticate requests using basic auth (i.e. username and password) | api-gateway |
+| bot-detection-inbound | Bot Detection | Detect known and suspected bots based on sophisticated traffic analysis. | api-gateway |
+| brownout-inbound | Brown Out | The brownout policy allows performing scheduled downtime on your API | api-gateway |
+| caching-inbound | Caching | Respond to matched incoming requests with cached content | api-gateway |
+| change-method-inbound | Change Method | Changes the HTTP method of the incoming request. | api-gateway |
+| clear-headers-inbound | Clear Request Headers | Removes all headers from the incoming request except for those in the exclude list. | api-gateway |
+| clear-headers-outbound | Clear Response Headers | Removes all headers from the response except for those in the exclude list. | api-gateway |
+| clerk-jwt-auth-inbound | Clerk JWT Auth | Authenticate users using Clerk issued JWT tokens. | api-gateway |
+| comet-opik-tracing-inbound | Comet Opik Tracing | Comet Opik Tracing Inbound Policy | ai-gateway |
+| complex-rate-limit-inbound | Complex Rate Limiting | 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) | api-gateway |
+| composite-inbound | Composite Inbound (Group Policies) | Creates a composite, or group policy - composed of other inbound policies. For reuse across routes. | api-gateway |
+| composite-outbound | Composite Outbound (Group Policies) | Creates a composite, or group policy - composed of other outbound policies. For reuse across routes. | api-gateway |
+| curity-phantom-token-inbound | Curity Phantom Token Auth | Authenticate users using the Curity Phantom Token Pattern. | api-gateway |
+| custom-code-inbound | Custom Code Inbound | Enables a custom code policy written in TypeScript. Change YOUR_MODULE to the name of your module (without .ts extension) | api-gateway |
+| custom-code-outbound | Custom Code Outbound | A custom outbound response policy. | api-gateway |
+| firebase-jwt-inbound | Firebase JWT Auth | Authenticate users using Firebase issued JWT tokens. | api-gateway |
+| 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-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 |
+| hmac-auth-inbound | HMAC Auth | Authenticate requests using the HMAC-SHA256 authentication scheme. | api-gateway |
+| http-deprecation-outbound | HTTP Deprecation | Sets HTTP deprecation headers on the outgoing response following the IETF HTTP Deprecation Header standard. Supports the Deprecation, Sunset, and Link headers. | api-gateway |
+| ip-restriction-inbound | IP Restriction | Block or allow requests based on their IP address. | api-gateway |
+| validate-json-schema-inbound | JSON Body Validation (deprecated) | Validates the body of an incoming request based on a JSON schema. | api-gateway |
+| open-id-jwt-auth-inbound | JWT Auth | The Open ID JWT Authentication policy allows you to authenticate incoming requests using an Open ID compliant bearer token. | api-gateway |
+| jwt-scopes-inbound | JWT Scope Validation | Validates that the JWT token includes specific scopes | api-gateway |
+| ldap-auth-inbound | LDAP Auth | Authenticate requests using an LDAP server. | api-gateway |
+| mock-api-inbound | Mock API Response | Returns example responses from the OpenAPI document associated with this route. | api-gateway |
+| moesif-inbound | Moesif Analytics & Billing | Moesif is an API analytics and billing service. This policy allows you to send metering calls for each API to their events batch endpoint. | api-gateway |
+| monetization-inbound | Monetization | Monetization inbound policy for API key validation and usage metering. | api-gateway |
+| mtls-auth-inbound | mTLS Auth | Authenticate requests based on the mTLS protocol. | api-gateway |
+| okta-fga-authz-inbound | Okta FGA Authorization | Authorize requests using Okta FGA. | api-gateway |
+| okta-jwt-auth-inbound | Okta JWT Auth | Authenticate users using Okta issued JWT tokens. | api-gateway |
+| openfga-authz-inbound | OpenFGA Authorization | Authorize requests using OpenFGA. | api-gateway |
+| openmeter-inbound | OpenMeter | OpenMeter is a usage metering service. This policy allows you to send metering calls for each API to their event ingest endpoint. It also supports entitlement checking to verify if a subject has access to a feature. | api-gateway |
+| prompt-injection-outbound | Prompt Injection Detection | Uses an LLM agent to detect prompt injection attempts in user provided content or potentially poisoned response bodies. This is primarily intended to be used with downstream LLM agents who are at risk of having prompt injection attacks executed against them. | api-gateway |
+| propel-auth-jwt-inbound | PropelAuth JWT Auth | Authenticate users using PropelAuth issued JWT tokens. | api-gateway |
+| query-param-to-header-inbound | Query Parameter to Header | Extracts a query parameter and sets it as a header in the request. | api-gateway |
+| quota-inbound | Quota | The Quota policy enables you to set monthly, weekly, daily or hourly quotas on your API. | api-gateway |
+| rate-limit-inbound | Rate Limiting | Rate limiting policy to control the number of requests to your API. Supports multiple identification strategies (by user, IP, header, etc.) and can operate in strict or async mode for different performance characteristics. | api-gateway |
+| rbac-policy-inbound | RBAC Authorization | The RBAC authorization inbound policy limits access to resources based on the roles of the authenticated user. | api-gateway |
+| readme-metrics-inbound | Readme Metrics | Readme is a developer documentation and API metrics company. This policy pushes logs to their API calls dashboard. | api-gateway |
+| remove-query-params-inbound | Remove Query Parameters | Remove query parameters from the incoming request | api-gateway |
+| remove-headers-inbound | Remove Request Headers | Remove headers from the incoming request. | api-gateway |
+| remove-headers-outbound | Remove Response Headers | Remove configured headers from the outgoing response. | api-gateway |
+| replace-string-outbound | Replace String in Response Body | Replace a string in the incoming request body | api-gateway |
+| request-size-limit-inbound | Request Size Limit | Enforces a maximum size in bytes of the incoming request. | api-gateway |
+| request-validation-inbound | Request Validation | Validates incoming requests against your OpenAPI specification. Checks query parameters, path parameters, headers, and request body to ensure they match the defined schema before processing. | api-gateway |
+| require-origin-inbound | Require Origin | Sets an allow-list for an origin header | api-gateway |
+| secret-masking-outbound | Secret Masking | Masks common secrets like Zuplo API keys, GitHub tokens, or SSH private key in the response body. | api-gateway |
+| semantic-cache-inbound | Semantic Cache | Respond to matched incoming requests with semantically cached content  The Semantic Cache Inbound policy caches responses based on semantic similarity of cache keys rather than exact matches. This allows for more flexible caching where similar requests can return cached responses even if the cache key is not exactly the same.  The policy uses Large Language Model (LLM) embeddings to determine semantic similarity between cache keys based on a configurable similarity tolerance.  Options: - semanticTolerance: The semantic similarity threshold for semantic cache matches (0-1, default: 0.2). Values closer to 0 require higher similarity. Can be overridden by custom functions. - expirationSecondsTtl: The timeout of the cache in seconds (default: 3600, 1 hour). Can be overridden by custom functions. - namespace: Optional namespace to isolate cache entries (default: "default"). Useful for multi-tenant scenarios or different cache contexts. - cacheBy: Determines how cache keys are generated: 'function' for custom logic or 'propertyPath' to extract from JSON body. | api-gateway |
+| set-body-inbound | Set Body | Sets the body of the request in the inbound pipeline - make sure to convert a GET/HEAD request to another method when using this policy. | api-gateway |
+| set-headers-outbound | Set Headers | Adds or sets headers on the on the outgoing response. | api-gateway |
+| set-status-outbound | Set Status Code | Sets the status code on the on the outgoing response. | api-gateway |
+| 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 |
+| 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 |
+| upstream-firebase-admin-auth-inbound | Upstream Firebase Admin Auth | Creates a Firebase Admin token and attaches it to the outgoing request. Useful when calling Firebase services as an administrator. | api-gateway |
+| upstream-firebase-user-auth-inbound | Upstream Firebase User Auth | Creates a Firebase custom user token and attaches it to the outgoing request. Useful when calling Firebase services as user. | api-gateway |
+| upstream-gcp-federated-auth-inbound | Upstream GCP Federated Auth | Authenticates with GCP resources or Google services using Workload Identity Federation allowing secure access to these resources without requiring the use of a service account private key. | api-gateway |
+| upstream-gcp-jwt-inbound | Upstream GCP Self-Signed JWT | Creates a self-signed JWT token (generated using a Google Service Account JSON) and attaches it to the outgoing request. Useful when calling GCP services like Cloud Endpoints / ESPv2 | api-gateway |
+| upstream-gcp-service-auth-inbound | Upstream GCP Service Auth | Creates an ID Token from Google's OAuth service and attaches it to the outgoing request. Useful when calling GCP services or Google APIs that are secured with GCP IAM. | api-gateway |
+| upstream-zuplo-jwt-auth-inbound | Upstream Zuplo JWT | Generates a Zuplo JWT token and attaches it to the outgoing request. This policy creates a self-signed JWT using the Zuplo JWT plugin and adds it to the specified header for upstream authentication. | api-gateway |
+| web-bot-auth-inbound | Web Bot Auth | Authenticate bots using web-bot-auth HTTP Message Signatures. | api-gateway |
+| xml-to-json-outbound | XML to JSON Outbound | Parses XML and converts it to JSON. | api-gateway |

package/docs/policies/ab-test-inbound/intro.md

@@ -0,0 +1,8 @@
+This example shows how to perform an action on incoming requests based on the
+result of a randomly generated number. A/B tests could also be performed on
+properties such as the `request.user`.
+
+A/B tests can also be combined with other policies by passing data to downstream
+policies. For example, you could save a value in `ContextData` based on the
+results of the A/B test and use that value in a later policy to modify the
+request.

package/docs/policies/ab-test-inbound/policy.ts

@@ -0,0 +1,14 @@
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  // Generate a random number to segment the test groups
+  const score = Math.random();
+
+  if (score < 0.5) {
+    // Do something for half the requests
+  } else {
+    // Do something else for the other half
+  }
+
+  return request;
+}

package/docs/policies/ab-test-inbound/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/ab-test-inbound.json",
+  "type": "object",
+  "title": "A/B Test Inbound",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "An A/B test policy is used to handle requests differently based on parameters such as user, ip, etc.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The export from the custom policy"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        }
+      }
+    }
+  }
+}

package/docs/policies/ab-test-outbound/intro.md

@@ -0,0 +1,8 @@
+This example shows how to perform an action on incoming requests based on the
+result of a randomly generated number. A/B tests could also be performed on
+properties such as the `request.user`.
+
+A/B tests can also be combined with other policies by passing data to downstream
+policies. For example, you could save a value in `ContextData` based on the
+results of the A/B test and use that value in a later policy to modify the
+request.

package/docs/policies/ab-test-outbound/policy.ts

@@ -0,0 +1,26 @@
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Generate a random number to segment the test groups
+  const score = Math.random();
+
+  // Get the outgoing response body
+  const data = await response.json();
+
+  // Modify the body based on the random value
+  if (score < 0.5) {
+    data.testEnabled = true;
+  } else {
+    data.testEnabled = false;
+  }
+
+  // Stringify the data object
+  const body = JSON.stringify(data);
+
+  // Return a new response with the updated body
+  return new Response(body, response);
+}

package/docs/policies/ab-test-outbound/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/ab-test-outbound.json",
+  "type": "object",
+  "title": "A/B Test Outbound",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "An A/B test policy is used to handle responses differently based on parameters such as user, ip, etc.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The export from the custom policy"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        }
+      }
+    }
+  }
+}

package/docs/policies/acl-policy-inbound/intro.md

@@ -0,0 +1,5 @@
+ACL policies can be built many ways depending on your requirements. This example
+shows how to perform an authorization check on a hard-coded list of users.
+
+This policy could be extended to fetch data from external sources or even use an
+authorization service such as [OpenFGA](https://openfga.dev/).

package/docs/policies/acl-policy-inbound/policy.ts

@@ -0,0 +1,32 @@
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface PolicyOptions {
+  users: string[];
+}
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+  policyName: string,
+) {
+  // Check that an authenticated user is set
+  // NOTE: This policy requires an authentication policy to run before
+  if (!request.user) {
+    context.log.error(
+      "User isn't authenticated. A authorization policy must come before the ACL policy.",
+    );
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  // Check that the user has one of the allowed roles
+  if (!options.users.includes(request.user.sub)) {
+    context.log.error(
+      `The user '${request.user.sub}' isn't authorized to perform this action.`,
+    );
+    return HttpProblems.forbidden(request, context);
+  }
+
+  // If they made it here, they are authorized
+  return request;
+}

package/docs/policies/acl-policy-inbound/schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/acl-policy-inbound.json",
+  "type": "object",
+  "title": "Access Control List",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "The access control list inbound policy limits access to resources based on parameters on the authenticated user.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": ["users"],
+          "properties": {
+            "users": {
+              "type": "array",
+              "description": "The list of users authorized to access the resource",
+              "items": {
+                "type": "string",
+                "description": "The user's sub"
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "users": ["google|12345", "google|23456"]
+          }
+        }
+      ]
+    }
+  }
+}