zuplo 6.67.32 → 6.68.0

package/docs/policies/request-validation-inbound/doc.md

@@ -0,0 +1,72 @@
+The Request Validation Inbound policy validates incoming requests against your
+OpenAPI schema definitions. This ensures that all requests to your API conform
+to your specified data structure and types before they reach your backend
+services.
+
+## How It Works
+
+This policy automatically validates incoming requests based on the OpenAPI
+schemas defined in your API specification. It checks:
+
+- **Request Bodies**: Validates JSON/XML payloads against your schema
+  definitions
+- **Query Parameters**: Ensures query parameters match expected types and
+  constraints
+- **Path Parameters**: Validates URL path parameters against defined patterns
+- **Headers**: Verifies required headers are present and conform to
+  specifications
+
+When a request fails validation, the policy returns a detailed 400 Bad Request
+response with specific information about which part of the request failed
+validation and why.
+
+## Configuration
+
+The policy requires minimal configuration as it automatically uses your existing
+OpenAPI schemas. You can enable or disable validation for specific parts of the
+request (body, query parameters, headers) through the policy options.
+
+## OpenAPI Schema Example
+
+Here's an example of how to specify a schema for validation in a request body in
+your OpenAPI specification:
+
+```json
+  "requestBody": {
+    "description": "user to add to the system",
+    "content": {
+      "application/json": {
+        "schema": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "integer"
+            }
+          },
+          "required": [
+            "name",
+            "age"
+          ]
+        }
+      }
+    }
+  }
+```
+
+## Advanced Validation
+
+The policy supports the full range of OpenAPI schema validation features,
+including:
+
+- Type validation (string, number, boolean, array, object)
+- Format validation (date, date-time, email, etc.)
+- Pattern matching with regular expressions
+- Numeric constraints (minimum, maximum, multipleOf)
+- String constraints (minLength, maxLength)
+- Array constraints (minItems, maxItems, uniqueItems)
+- Required properties
+- Enum values
+- Complex schemas with allOf, anyOf, oneOf, and not

package/docs/policies/request-validation-inbound/intro.md

@@ -0,0 +1,24 @@
+The Request Validation policy validates incoming requests against your OpenAPI
+schema definitions, ensuring that all requests conform to your API's expected
+structure and data types before they reach your backend services.
+
+With this policy, you'll benefit from:
+
+- **Data Integrity Protection**: Prevent malformed or invalid data from reaching
+  your backend systems
+- **Automatic Schema Enforcement**: Leverage your existing OpenAPI definitions
+  for validation without additional code
+- **Comprehensive Validation**: Validate request bodies, query parameters, path
+  parameters, and headers
+- **Detailed Error Responses**: Return clear, actionable error messages that
+  help API consumers fix invalid requests
+- **Developer-Friendly Experience**: Improve the developer experience by
+  providing immediate feedback on request issues
+- **Reduced Backend Errors**: Minimize crashes and unexpected behavior caused by
+  invalid input data
+- **API Contract Enforcement**: Ensure all API consumers adhere to your
+  documented API contract
+
+When configured, any requests that do not conform to your OpenAPI schema will be
+rejected with a `400: Bad Request` response containing a detailed error message
+(in JSON) explaining why the request was not accepted.

package/docs/policies/request-validation-inbound/schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Request Validation",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "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.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "RequestValidationInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "RequestValidationInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "logLevel": {
+              "type": "string",
+              "default": "info",
+              "description": "The log level to use when logging validation errors.",
+              "enum": ["error", "warn", "info", "debug"]
+            },
+            "validateBody": {
+              "examples": ["reject-and-log"],
+              "type": "string",
+              "title": "ValidationOptions",
+              "default": "none",
+              "description": "The action to perform when validation fails.",
+              "enum": ["none", "log-only", "reject-and-log", "reject-only"]
+            },
+            "validateQueryParameters": {
+              "examples": ["log-only"],
+              "type": "string",
+              "title": "ValidationOptions",
+              "default": "none",
+              "description": "The action to perform when validation fails.",
+              "enum": ["none", "log-only", "reject-and-log", "reject-only"]
+            },
+            "validatePathParameters": {
+              "examples": ["log-only"],
+              "type": "string",
+              "title": "ValidationOptions",
+              "default": "none",
+              "description": "The action to perform when validation fails.",
+              "enum": ["none", "log-only", "reject-and-log", "reject-only"]
+            },
+            "validateHeaders": {
+              "type": "string",
+              "title": "ValidationOptions",
+              "default": "none",
+              "description": "The action to perform when validation fails.",
+              "enum": ["none", "log-only", "reject-and-log", "reject-only"]
+            },
+            "includeRequestInLogs": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether to include the request in the logs."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "RequestValidationInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "includeRequestInLogs": false,
+            "logLevel": "info",
+            "validateBody": "reject-and-log",
+            "validateHeaders": "none",
+            "validatePathParameters": "log-only",
+            "validateQueryParameters": "log-only"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/require-origin-inbound/intro.md

@@ -0,0 +1,12 @@
+The Require Origin policy is used to enforce that the client is sending an
+`origin` header that matches your allow-list specified in the policy options.
+
+This is useful if you want to stop any browser traffic from different domains.
+
+However, it is important to note that it does not guarantee that traffic is only
+coming from a browser. Somebody could simulate a browser request from a backend
+server and set any origin they like.
+
+If the incoming origin is missing, or not allowed - a 400 Forbidden Problem
+Response will be sent to the client. You can customize the `detail` property in
+the policy options.

package/docs/policies/require-origin-inbound/schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Require Origin",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Sets an allow-list for an origin header",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "RequireOriginInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "RequireOriginInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["origins"],
+          "properties": {
+            "origins": {
+              "type": "string",
+              "examples": ["https://example.com, https://example.org"],
+              "description": "A comma separated string containing valid origins."
+            },
+            "failureDetail": {
+              "type": "string",
+              "default": "Forbidden",
+              "examples": [
+                "Your origin is not authorized to make this request."
+              ],
+              "description": "The `detail` of the HTTP Problem response, if the origin is missing or disallowed."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "RequireOriginInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "failureDetail": "Your origin is not authorized to make this request.",
+            "origins": "https://example.com, https://example.org"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/secret-masking-outbound/doc.md

@@ -0,0 +1,41 @@
+This policy masks sensitive secrets in outgoing requests to prevent exposure to
+downstream consumers. This is especially useful for AI agents and MCP clients
+(where LLMs should not consume potentially sensitive user generated information
+or poisoned agents are attempting to leak information they have access to).
+
+## Configuration
+
+- `mask`: The mask to use when redacting information. **Default:** `[REDACTED]`
+- `additionalPatterns`: Additional Regex patterns to mask secrets with (make
+  sure to correctly escape "meta escape" characters: i.e., `\b` should be
+  escaped `\\b` to avoid a JSON parsing error. Otherwise, you may see build
+  errors).
+
+## Usage
+
+Apply this policy to outbound requests in your route configuration:
+
+```json
+{
+  "policies": [
+    {
+      "name": "secret-masking-policy",
+      "policyType": "secret-masking-outbound",
+      "handler": {
+        "export": "SecretMaskingOutboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "mask": "<SECRET MASKED>",
+          "additionalPatterns": ["\\b(\\w+)=\\w+\\b"]
+        }
+      }
+    }
+  ]
+}
+```
+
+# Masked secrets
+
+- Zuplo API keys (i.e. `zpka_xxx`)
+- GitHub Tokens and Personal Access Tokens (i.e. `ghp_xxx`)
+- Private key blocks (i.e. `BEGIN PRIVATE KEY` and `END PRIVATE KEY`)

package/docs/policies/secret-masking-outbound/intro.md

@@ -0,0 +1,13 @@
+The Secret Masking policy searches for and masks common secrets and replaces
+them with a placeholder. Secrets that are automatically masked include:
+
+- Zuplo API keys
+- GitHub Tokens and Personal Access Tokens
+- Private key blocks
+- And more!
+
+See the [policy documentation](https://zuplo.com/docs/policies/overview) for a
+full description of secrets that are masked via this policy.
+
+This is especially useful as an outbound policy for MCP servers, APIs that
+interface with user generated content, or AI consumers.

package/docs/policies/secret-masking-outbound/schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Secret Masking",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Masks common secrets like Zuplo API keys, GitHub tokens, or SSH private key in the response body.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "SecretMaskingOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "SecretMaskingOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the secret masking policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "mask": {
+              "type": "string",
+              "description": "The string to replace detected secrets with.",
+              "examples": ["[REDACTED]"],
+              "default": "[REDACTED]"
+            },
+            "additionalPatterns": {
+              "type": "array",
+              "description": "Extra regex patterns for secrets to mask.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "SecretMaskingOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "additionalPatterns": [],
+            "mask": "[REDACTED]"
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,63 @@
+## How it works
+
+1. **Cache Key Generation**: The policy generates a cache key either through a
+   custom function or by extracting a value from the request body using a
+   property path.
+
+2. **Semantic Matching**: When a request comes in, the policy checks the
+   semantic cache service to find semantically similar cache keys based on the
+   configured similarity tolerance.
+
+3. **Response Caching**: Successful responses are cached in the semantic cache
+   service with the generated cache key.
+
+4. **LLM-powered Similarity**: The cache matching uses Large Language Model
+   (LLM) embeddings to determine semantic similarity between cache keys.
+
+## Configuration
+
+The policy supports two modes for cache key generation:
+
+- **Function Mode**: Use a custom function to generate cache keys
+- **Property Path Mode**: Extract cache keys from JSON request body using a
+  property path
+
+### Key Parameters
+
+- **semanticTolerance** (optional): A number between 0 and 1 that controls how
+  similar cache keys need to be for a match. Default is 0.8. Higher values
+  (closer to 1) require more similarity, while lower values allow more flexible
+  matching. Can be overridden by custom functions when using
+  `cacheBy: "function"`.
+- **expirationSecondsTtl** (optional): Cache expiration time in seconds. Default
+  is 3600 (1 hour). Can be overridden by custom functions when using
+  `cacheBy: "function"`.
+- **namespace** (optional): An optional string to isolate cache entries within a
+  specific namespace. This is useful for multi-tenant scenarios or when you want
+  to separate different cache contexts. When specified, only cache entries
+  within the same namespace will be matched and retrieved.
+
+### Custom Functions
+
+When using `cacheBy: "function"`, your custom function should return an object
+with the following structure:
+
+```typescript
+{
+  cacheKey: string;           // Required: The cache key for semantic matching
+  semanticTolerance?: number;       // Optional: Override the policy's similarity tolerance
+  expirationSecondsTtl?: number;      // Optional: Override the policy's cache expiration time
+}
+```
+
+This allows for dynamic configuration where different requests can have
+different caching behaviors based on your custom logic.
+
+## Use Cases
+
+- Caching API responses where requests may be semantically similar but not
+  identical
+- Natural language query caching where similar questions should return the same
+  response
+- User-specific caching where slight variations in user identifiers map to the
+  same cache entry

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

@@ -0,0 +1,4 @@
+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.

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

@@ -0,0 +1,179 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Semantic Cache",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Respond to matched incoming requests with semantically cached content\n\nThe 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.\n\nThe policy uses Large Language Model (LLM) embeddings to determine semantic similarity between cache keys based on a configurable similarity tolerance.\n\nOptions: - 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.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "SemanticCacheInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "SemanticCacheInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["cacheBy"],
+          "properties": {
+            "semanticTolerance": {
+              "type": "number",
+              "default": 0.2,
+              "minimum": 0,
+              "maximum": 1,
+              "description": "The semantic similarity threshold for semantic cache matches. Values closer to 0 require closer similarity, while larger values allow more flexible matching. Default is 0.2."
+            },
+            "expirationSecondsTtl": {
+              "type": "number",
+              "default": 3600,
+              "minimum": 60,
+              "description": "The timeout of the cache in seconds. Defaults to 1 hour."
+            },
+            "namespace": {
+              "type": "string",
+              "default": "default",
+              "description": "Optional namespace to isolate cache entries. Useful for multi-tenant scenarios or different cache contexts."
+            },
+            "cacheBy": {
+              "type": "string",
+              "enum": ["function", "propertyPath"],
+              "description": "Determines how the cache key is generated. Use 'function' for custom logic or 'propertyPath' to extract from JSON body."
+            },
+            "cacheByFunction": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "The function that returns dynamic cache key data. Used only with `cacheBy=function`.",
+              "required": ["export", "module"],
+              "properties": {
+                "export": {
+                  "type": "string",
+                  "description": "Specifies the export to load your custom cache key function, e.g. `default`, `cacheKeyIdentifier`.",
+                  "examples": ["default", "cacheKeyIdentifier"]
+                },
+                "module": {
+                  "type": "string",
+                  "description": "Specifies the module to load your custom cache key function, in the format `$import(./modules/my-module)`.",
+                  "examples": ["$import(./modules/my-module)"]
+                }
+              }
+            },
+            "cacheByPropertyPath": {
+              "type": "string",
+              "description": "The path to the property in the request body (JSON) to use as cache key. For example '.userId' would read the 'userId' property from the request body. Only works with cacheBy=propertyPath.",
+              "examples": [".userId", ".data.customerId"]
+            },
+            "statusCodes": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "examples": [[200, 201]],
+              "default": [200, 206, 301, 302, 303, 410],
+              "description": "Response status codes to be cached."
+            },
+            "returnCacheStatusHeader": {
+              "type": "boolean",
+              "default": false,
+              "description": "If true, the policy will return a custom header with the cache status. The default header name is `zp-semantic-cache`."
+            },
+            "cacheStatusHeaderName": {
+              "type": "string",
+              "default": "zp-semantic-cache",
+              "description": "The name of the header to return the cache status. Only used if `returnCacheStatusHeader` is true."
+            }
+          },
+          "allOf": [
+            {
+              "if": {
+                "properties": {
+                  "cacheBy": {
+                    "const": "function"
+                  }
+                }
+              },
+              "then": {
+                "required": ["cacheByFunction"]
+              }
+            },
+            {
+              "if": {
+                "properties": {
+                  "cacheBy": {
+                    "const": "propertyPath"
+                  }
+                }
+              },
+              "then": {
+                "required": ["cacheByPropertyPath"]
+              }
+            }
+          ],
+          "examples": [
+            {
+              "cacheBy": "propertyPath",
+              "cacheByPropertyPath": ".userId",
+              "semanticTolerance": 0.8,
+              "expirationSecondsTtl": 3600,
+              "namespace": "user-cache"
+            },
+            {
+              "cacheBy": "function",
+              "cacheByFunction": {
+                "export": "cacheKeyFunction",
+                "module": "$import(./modules/cache-key)"
+              },
+              "semanticTolerance": 0.9,
+              "expirationSecondsTtl": 1800,
+              "namespace": "api-cache"
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "SemanticCacheInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheBy": "propertyPath",
+            "cacheByPropertyPath": ".userId",
+            "expirationSecondsTtl": 3600,
+            "namespace": "user-cache",
+            "semanticTolerance": 0.8
+          }
+        },
+        {
+          "export": "SemanticCacheInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheBy": "function",
+            "cacheByFunction": {
+              "export": "cacheKeyFunction",
+              "module": "$import(./modules/cache-key)"
+            },
+            "expirationSecondsTtl": 1800,
+            "namespace": "api-cache",
+            "semanticTolerance": 0.9
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/set-body-inbound/intro.md

@@ -0,0 +1,7 @@
+The Set Body policy allows you to set or override the incoming request body.
+[GET or HEAD requests do not support bodies on Zuplo](https://zuplo.com/docs/articles/zp-body-removed),
+so be sure to use the
+[Change Method](https://zuplo.com/docs/policies/change-method-inbound) policy to
+update the method to a `POST` or whatever is appropriate. You might also need to
+use the [Set Header](https://zuplo.com/docs/policies/set-headers-inbound) policy
+to set a `content-type`.