zuplo 6.67.32 → 6.68.0

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

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "AWS Cognito JWT Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate requests with JWT tokens issued by AWS Cognito.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "CognitoJwtInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "CognitoJwtInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["region", "userPoolId"],
+          "properties": {
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "Allow unauthenticated requests to proceed. This is use useful if you want to use multiple authentication policies or if you want to allow both authenticated and non-authenticated traffic."
+            },
+            "region": {
+              "type": "string",
+              "examples": ["us-east-1"],
+              "description": "The AWS region where your Cognito instance is deployed."
+            },
+            "userPoolId": {
+              "type": "string",
+              "examples": ["$env(AWS_COGNITO_USER_POOL_ID)"],
+              "description": "The user pool identifier."
+            },
+            "oAuthResourceMetadataEnabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "CognitoJwtInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowUnauthenticatedRequests": false,
+            "oAuthResourceMetadataEnabled": false,
+            "region": "us-east-1",
+            "userPoolId": "$env(AWS_COGNITO_USER_POOL_ID)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/comet-opik-tracing-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": "Comet Opik Tracing",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["ai-gateway"],
+  "description": "Comet Opik Tracing Inbound Policy",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "CometOpikTracingInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "Comet Opik Tracing",
+          "description": "Track AI Gateway requests and responses using Comet Opik's LLM observability platform.",
+          "type": "object",
+          "properties": {
+            "apiKey": {
+              "description": "The Comet Opik API key for authentication.",
+              "type": "string"
+            },
+            "projectName": {
+              "description": "The Comet Opik project name for organizing traces.",
+              "type": "string"
+            },
+            "workspace": {
+              "description": "The Comet Opik workspace name.",
+              "type": "string"
+            },
+            "baseUrl": {
+              "description": "The base URL for the Comet Opik API (optional, defaults to https://www.comet.com/opik/api).",
+              "type": "string"
+            }
+          },
+          "required": ["apiKey", "projectName", "workspace"],
+          "additionalProperties": false
+        }
+      },
+      "examples": [
+        {
+          "export": "CometOpikTracingInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {}
+        }
+      ]
+    }
+  }
+}

package/docs/policies/complex-rate-limit-inbound/doc.md

@@ -0,0 +1,20 @@
+This policy allows setting multiple limits that can optionally be overridden
+programmatically.
+
+### Set Increments Programmatically
+
+Override the increments for limits in the current request.
+
+If your policy has a limit set as follows:
+
+```
+"limits": {
+  "compute": 10
+}
+```
+
+You can use this function to override the increment of the `compute` units
+consumed on a request by calling
+`ComplexRateLimitInboundPolicy.setIncrements(context, {     compute: 5,   });`
+on a custom policy. This can be useful if you want to dynamically change the
+increment of a limit based on data in the response (such as a header).

package/docs/policies/complex-rate-limit-inbound/intro.md

@@ -0,0 +1,23 @@
+Limit the number of requests based on complex counters derived from request or
+response details. This is an advanced version of the
+[Rate Limit Policy](https://zuplo.com/docs/policies/rate-limit-inbound) with
+support for multiple limits and dynamic increments.
+
+With this policy, you'll benefit from:
+
+- **Advanced Rate Control**: Create multiple rate limits with different
+  thresholds and time windows for sophisticated traffic management
+- **Dynamic Limiting**: Adjust rate limit increments based on request or
+  response data to implement usage-based pricing models
+- **Resource Protection**: Shield your downstream services from traffic spikes
+  and abuse while ensuring optimal performance
+- **Flexible Implementation**: Define custom limit keys based on any request
+  attribute for precise control over your API traffic
+- **Granular Usage Plans**: Implement tiered consumption rates for different
+  user segments to maximize monetization opportunities
+- **Comprehensive Monitoring**: Track limit usage with detailed metrics to
+  identify patterns and optimize your API strategy
+- **Intelligent Traffic Shaping**: Prioritize critical requests while throttling
+  less important traffic during peak loads
+- **Seamless Scalability**: Handle growing API traffic with configurable limits
+  that adapt to your business needs

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

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Complex Rate Limiting",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "The Complex Rate Limiting policy is an advanced rate limiting policy that let's you set rate limits based on custom counters (not just requests)",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ComplexRateLimitInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ComplexRateLimitInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["rateLimitBy", "limits", "timeWindowMinutes"],
+          "properties": {
+            "rateLimitBy": {
+              "type": "string",
+              "default": "user",
+              "title": "RateLimitByType",
+              "enum": ["user", "ip", "function", "all"],
+              "description": "The identifying element of the request that enforces distinct rate limits. For example, you can limit by `user`, `ip`, `function` or `all` - function allows you to specify a simple function to create a string identifier to create a rate-limit group."
+            },
+            "limits": {
+              "type": "object",
+              "description": "A dictionary (string: number) of limits to be enforced across custom counters for this policy.",
+              "additionalProperties": {
+                "type": "number"
+              }
+            },
+            "timeWindowMinutes": {
+              "type": "integer",
+              "default": 60,
+              "description": "The time window in which the requests are rate-limited. The count restarts after each window expires."
+            },
+            "identifier": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "The function that returns dynamic configuration data. Used only with `rateLimitBy=function`.",
+              "required": ["export", "module"],
+              "properties": {
+                "export": {
+                  "type": "string",
+                  "default": "",
+                  "description": "used only with rateLimitBy=function. Specifies the export to load your custom bucket function, e.g. `default`, `rateLimitIdentifier`.",
+                  "examples": ["default"]
+                },
+                "module": {
+                  "type": "string",
+                  "default": "",
+                  "description": "Specifies the module to load your custom bucket function, in the format `$import(./modules/my-module)`.",
+                  "examples": ["$import(./modules/my-module)"]
+                }
+              }
+            },
+            "headerMode": {
+              "type": "string",
+              "default": "retry-after",
+              "title": "RateLimitHeaderMode",
+              "enum": ["none", "retry-after"],
+              "description": "Adds the retry-after header."
+            },
+            "throwOnFailure": {
+              "type": "boolean",
+              "default": false,
+              "description": "If true, the policy will throw an error in the event there is a problem connecting to the rate limit service."
+            },
+            "mode": {
+              "type": "string",
+              "default": "strict",
+              "title": "RateLimitMode",
+              "enum": ["strict", "async"],
+              "description": "The mode of the policy. If set to `async`, the policy will check if the request is over the rate limit without blocking. This can result in some requests allowed over the rate limit."
+            }
+          },
+          "examples": [
+            {
+              "rateLimitBy": "ip",
+              "limits": {
+                "apples": 2,
+                "bananas": 3
+              },
+              "timeWindowMinutes": 0.6
+            },
+            {
+              "rateLimitBy": "function",
+              "identifier": {
+                "export": "$import(./modules/my-module)",
+                "module": "default"
+              }
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "ComplexRateLimitInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "limits": {
+              "apples": 2,
+              "bananas": 3
+            },
+            "rateLimitBy": "ip",
+            "timeWindowMinutes": 0.6
+          }
+        },
+        {
+          "export": "ComplexRateLimitInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "identifier": {
+              "export": "$import(./modules/my-module)",
+              "module": "default"
+            },
+            "rateLimitBy": "function"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/composite-inbound/doc.md

@@ -0,0 +1,69 @@
+This policy allows you to create groups of other policies for easy reuse across
+multiple routes. Policies are referenced by their `name` as defined in your
+policies.json file.
+
+### Policy Configuration
+
+The Composite Inbound policy requires a list of policy names to include in the
+group:
+
+```json
+{
+  "policies": [
+    "rate-limit-policy",
+    "api-key-auth-policy",
+    "request-validation-policy"
+  ]
+}
+```
+
+Each policy name in the array must correspond to a valid policy defined in your
+policies.json file.
+
+### Usage Examples
+
+#### Creating a Security Group
+
+You can create a security policy group that combines authentication and rate
+limiting:
+
+```json
+{
+  "name": "security-group",
+  "handler": {
+    "export": "CompositeInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "policies": ["api-key-auth", "rate-limit"]
+    }
+  }
+}
+```
+
+#### Creating a Validation Group
+
+You can create a validation policy group that combines schema validation and
+custom validation logic:
+
+```json
+{
+  "name": "validation-group",
+  "handler": {
+    "export": "CompositeInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "policies": ["json-schema-validator", "custom-validation-policy"]
+    }
+  }
+}
+```
+
+### Important Considerations
+
+- Be careful not to create circular references, which can cause your gateway to
+  fail
+- Policies will be executed in the order they are listed in the `policies` array
+- Each policy in the composite group must be properly configured in your
+  policies.json file
+- The composite policy can be used in route definitions just like any other
+  policy

package/docs/policies/composite-inbound/intro.md

@@ -0,0 +1,15 @@
+Create reusable groups of policies that can be applied together across multiple
+routes. This policy allows you to organize and manage collections of policies by
+referencing them by their `name`.
+
+With this policy, you'll benefit from:
+
+- **Simplified Management**: Group related policies together for easier
+  maintenance
+- **Consistent Security**: Apply the same set of policies across multiple routes
+- **Reduced Configuration**: Minimize repetitive policy definitions in your
+  routes
+- **Modular Design**: Create logical policy groupings based on function or
+  security level
+- **Streamlined Updates**: Change policy configurations in one place and apply
+  everywhere

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

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Composite Inbound (Group Policies)",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Creates a composite, or group policy - composed of other inbound policies. For reuse across routes.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "CompositeInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "CompositeInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "policies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["policy1", "policy2"]],
+              "description": "The list of policy references (beware circular references)."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "CompositeInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "policies": ["policy1", "policy2"]
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/composite-outbound/intro.md

@@ -0,0 +1,6 @@
+The Composite outbound policy allows you to create groups of other policies, for
+easy reuse across multiple routes. Other policies are referenced by their
+`name`.
+
+Be careful not to create circular references which can cause your gateway to
+fail.

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

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Composite Outbound (Group Policies)",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Creates a composite, or group policy - composed of other outbound policies. For reuse across routes.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "CompositeOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "CompositeOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "policies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["policy1", "policy2"]],
+              "description": "The list of policy references (beware circular references)."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "CompositeOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "policies": ["policy1", "policy2"]
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/curity-phantom-token-inbound/doc.md

@@ -0,0 +1,109 @@
+Adding the Curity Phantom Token Pattern to your route is trivial. Before getting
+started, make sure that you have an instance of
+[the Curity Identity Server](https://curity.io/) up and running.
+
+### Setup the Curity Identity Server
+
+Getting the Curity Identity Server up and running is quick. Follow the
+[Getting Started Guide](https://curity.io/resources/getting-started/) to install
+and configure the server.
+
+#### Introspection
+
+In addition to the instructions outlined in the Getting Started Guide a client
+that enable introspection is needed. Typical recommendation for this is to
+create a new separate client that only enables the introspection capability.
+
+![](https://cdn.zuplo.com/assets/fed55feb-479f-40e6-82a3-734a7459fd97.png)
+
+#### Exposing the Runtime
+
+Depending on where the Curity Identity Server is deployed you might have to
+expose the runtime node using a reverse proxy. One option is to use
+[ngrok](https://curity.io/resources/learn/expose-local-curity-ngrok/) but other
+solutions could also be used.
+
+#### OAuth Tools
+
+With the server up and running and available you can use
+[OAuth Tools](https://oauth.tools/) to test the configuration and make sure that
+you are able to obtain a token. If an opaque token is possible to obtain you are
+good to continue.
+
+### Set Environment Variables
+
+Before adding the policy, there are a few environment variables that will need
+to be set that will be used in the Curity Phantom Token Policy.
+
+1. In the [Zuplo Portal](https://portal.zuplo.com) open the **Environment
+   Variables** section in the **Settings** tab.
+
+2. Click **Add new Variable** and enter the name `INTROSPECTION_URL` in the name
+   field. Set the value to URL endpoint of the Curity Identity Server that
+   handles introspection. Ex.
+   `https://idsvr.example.com/oauth/v2/oauth-introspect`
+
+3. Click **Add new Variable** again and enter the name `CLIENT_ID` in the name
+   field. Set the value to ID of the client that you added the introspection
+   capability to.
+
+4. Click **Add new Variable** again and enter the name `CLIENT_SECRET` in the
+   name field. Set the value to the secret of the client that you added the
+   introspection capability to. **Make sure to enable `is Secret?`.**
+
+### Add the Curity Phantom Token Policy
+
+The next step is to add the Curity Phantom Token Auth policy to a route in your
+project.
+
+The next step is to add the Curity Phantom Token Auth policy to a route in your
+project.
+
+1. In the [Zuplo Portal](https://portal.zuplo.com) open the **Route Designer**
+   in the **Files** tab then click **routes.oas.json**.
+
+2. Select or create a route that you want to authenticate with the Curity
+   Phantom Token Pattern. Expand the **Policies** section and click **Add
+   Policy**. Search for and select the **Curity Phantom Token Auth** policy.
+
+<!-- ![img](../../static/media/curity-phantom-token-auth/curity-phantom-token-auth-policy.jpg) -->
+
+3. Add the following to options:
+
+```json
+    "clientId": "$env(CLIENT_ID)",
+    "clientSecret": "$env(CLIENT_SECRET)",
+    "introspectionUrl": "$env(INTROSPECTION_URL)",
+```
+
+The policy configuration should now look like this:
+
+<!-- ![img](../../static/media/curity-phantom-token-auth/curity-phantom-token-policy-config.jpg) -->
+
+4. Click **OK** to save the policy.
+
+5. Click **Save All** to save all the configurations.
+
+### Test the Policy
+
+Head over to [OAuth Tools](https://oauth.tools/) to test the policy.
+
+1. Run a flow to obtain an opaque token (typically Code Flow)
+
+2. Configure an **External API** flow and add your Zuplo endpoint in the **API
+   Endpoint** field. Set the request method and choose the opaque token obtained
+   in step 1.
+
+![](https://cdn.zuplo.com/assets/a7752689-f57d-45e5-8103-87116d3ab779.png)
+
+3. Click **Send**. The panel on the right should now display the response from
+   the API. If the upstream API echoes back what is sent you will see that the
+   `Authorization` header now contains a JWT instead of the original opaque
+   token that was sent in the request.
+
+### Conclusion
+
+You have now setup the Curity Phantom Token Pattern for Authentication. Your API
+Gateway now accepts an opaque access token in the Authorization header and will
+handle obtaining a corresponding signed JWT that will be passed on to the
+upstream API.

package/docs/policies/curity-phantom-token-inbound/intro.md

@@ -0,0 +1,3 @@
+Authenticate requests with Phantom Tokens issued by Curity. The payload of the
+Phantom JWT token, if successfully authenticated, with be on the
+`request.user.data` object accessible to the runtime.