zuplo 6.67.32 → 6.68.0

package/docs/policies/jwt-scopes-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": "JWT Scope Validation",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Validates that the JWT token includes specific scopes",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "JWTScopeValidationInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "JWTScopeValidationInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["scopes"],
+          "properties": {
+            "scopes": {
+              "type": "array",
+              "description": "An array of of JWT scopes.",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["read:users", "write:projects"]]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "JWTScopeValidationInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "scopes": ["read:users", "write:projects"]
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/ldap-auth-inbound/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "LDAP Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": true,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate requests using an LDAP server.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "LDAPAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "LDAPAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["ldapConnectorName"],
+          "properties": {
+            "ldapConnectorName": {
+              "type": "string",
+              "examples": ["my-ldap-connector"],
+              "description": "The name of your configured LDAP service connector."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "LDAPAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "ldapConnectorName": "my-ldap-connector"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/mock-api-inbound/schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Mock API Response",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Returns example responses from the OpenAPI document associated with this route.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "MockApiInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "MockApiInboundOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "random": {
+              "type": "boolean",
+              "default": false,
+              "description": "Indicates whether the response should be selected randomly, from the available examples (that match any filter criteria). If `false` the first matching example is used."
+            },
+            "responsePrefixFilter": {
+              "type": "string",
+              "description": "Specifies a prefix to match the responses to select from. Typically this is a status code like \"200\" or \"2XX\". If you want the policy to select randomly from all 2XX codes, set this property to \"2\" and random to `true`."
+            },
+            "contentType": {
+              "type": "string",
+              "examples": ["application/json"],
+              "description": "Specify the content-type of the response to select from. If not specified, the first matching response is used (or random)."
+            },
+            "exampleName": {
+              "type": "string",
+              "examples": ["example1"],
+              "description": "Specify the name of the example to select. If not specified, the first matching response is used (or random)."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "MockApiInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "contentType": "application/json",
+            "exampleName": "example1",
+            "random": false
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,44 @@
+By default, Zuplo will read the `request.user.sub` property and assign this as
+the moesif `user_id` attribute when sending to Moesif. However, this and the
+following attributes can be overriden in a
+[custom code policy](/docs/policies/custom-code-inbound).
+
+- `api_version`
+- `company_id`
+- `session_token`
+- `user_id`
+- `metadata`
+
+Here is some example code that shows how to override two of these attributes
+
+```ts
+// Add this import at the top of your doc
+import { setMoesifContext } from "@zuplo/runtime";
+
+setMoesifContext(context, {
+  userId: "user-1234",
+  metadata: {
+    some: "arbitrary",
+    meta: "data",
+  },
+});
+```
+
+## Execute on every route
+
+If you want to execute this policy on every route, you can add a hook in your
+[runtime extensions](/docs/programmable-api/runtime-extensions) file
+`zuplo.runtime.ts`:
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addRequestHook((request, context) => {
+    return context.invokeInboundPolicy("moesif-inbound", request);
+  });
+}
+```
+
+Note you can add a guard clause around the context.invokeInboundPolicy if you
+want to exclude a few routes.

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

@@ -0,0 +1,6 @@
+Moesif [moesif.com](https://moesif.com) is an API analytics and monetization
+platform. This policy allows you to measure (and meter) API calls flowing
+through your Zuplo gateway.
+
+Add the policy to each route you want to meter. Note you can specify the Meter
+API Name and Meter Value (meter increment) at the policy level.

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

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Moesif Analytics & Billing",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Moesif is an API analytics and billing service. This policy allows you to send metering calls for each API to their events batch endpoint.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "MoesifInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "MoesifInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy. Many of them can be overridden at the code level in a request using the `AmberfloMeteringPolicy.setRequestProperties` method.",
+          "additionalProperties": false,
+          "required": ["applicationId"],
+          "properties": {
+            "applicationId": {
+              "type": "string",
+              "examples": ["$env(MOESIF_APPLICATION_ID)"],
+              "description": "Your Moesif application ID."
+            },
+            "logRequestBody": {
+              "type": "boolean",
+              "default": true,
+              "description": "Set to false to disable sending the request body to Moesif."
+            },
+            "logResponseBody": {
+              "type": "boolean",
+              "default": true,
+              "description": "Set to false to disable sending the response body to Moesif."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "MoesifInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "applicationId": "$env(MOESIF_APPLICATION_ID)",
+            "logRequestBody": true,
+            "logResponseBody": true
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+# Monetization Metering Policy
+
+The Monetization policy validates subscriptions and records usage. Meter usage
+is sent in a final response hook after status-code filtering.
+
+## Configuration
+
+- `meters` (optional): static meter increments applied on metered responses.
+- `meterOnStatusCodes`: status codes/ranges that trigger metering.
+- auth/cache settings: `authHeader`, `authScheme`, `cacheTtlSeconds`.
+
+### Static meter configuration
+
+```json
+{
+  "name": "monetization-inbound-policy",
+  "policyType": "monetization-inbound",
+  "options": {
+    "meters": {
+      "api": 1
+    },
+    "meterOnStatusCodes": "200-299"
+  }
+}
+```
+
+## Runtime meter updates
+
+You can set or update meter increments at different points in a request
+lifecycle (for example in an inbound policy, handler, or outbound policy). The
+monetization policy reads the latest values in its final hook before sending
+usage.
+
+### Set (replace) request meter increments
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+MonetizationInboundPolicy.setMeters(context, {
+  input_tokens: 1000,
+  output_tokens: 250,
+});
+```
+
+### Add (accumulate) request meter increments
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+MonetizationInboundPolicy.addMeters(context, { input_tokens: 500 });
+MonetizationInboundPolicy.addMeters(context, { input_tokens: 300 });
+```
+
+### Read current request meter increments
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+const meters = MonetizationInboundPolicy.getMeters(context);
+```
+
+## Meter merge behavior
+
+- The final hook merges `options.meters` and request meter increments from
+  `setMeters` / `addMeters`.
+- `setMeters` replaces the current runtime meter map and overrides matching keys
+  from `options.meters`.
+- `addMeters` accumulates into the current runtime meter map and then merges
+  additively with `options.meters`.
+- If both are empty, metering is skipped.
+
+For a meter key like `api` with `options.meters.api = 1`:
+
+- `setMeters(context, { api: 50 })` sends `api: 50`.
+- `addMeters(context, { api: 50 })` sends `api: 51`.
+
+## Prerequisites
+
+- `monetization-inbound` is enabled in your route/pipeline.
+- Meter names match entitlements on the subscription.
+- Meter quantities are finite positive numbers.
+
+## Notes
+
+- `setMeters` replaces current request meter increments.
+- `addMeters` accumulates values across multiple calls.
+- Entitlements are validated before usage is sent.

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

@@ -0,0 +1,6 @@
+The Monetization policy allows you to track and monetize the usage of your API
+resources, declaratively and programmatically.
+
+Follow our
+[Early Access: Getting Started with Monetization Guide](https://github.com/zuplo-samples/monetization-preview)
+to get started.

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

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Monetization",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Monetization inbound policy for API key validation and usage metering.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "MonetizationInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "MonetizationInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "authHeader": {
+              "type": "string",
+              "default": "Authorization",
+              "x-show-example": false,
+              "description": "The name of the header with the key."
+            },
+            "authScheme": {
+              "type": "string",
+              "default": "Bearer",
+              "x-show-example": false,
+              "description": "The scheme used on the header."
+            },
+            "cacheTtlSeconds": {
+              "type": "number",
+              "default": 60,
+              "description": "The time to cache authentication results for a particular key. Higher values will decrease latency. Cached results will be valid until the cache expires even in the event the key is deleted, etc."
+            },
+            "meters": {
+              "type": "object",
+              "examples": [
+                {
+                  "requests": 1
+                }
+              ],
+              "patternProperties": {
+                "^.*$": {
+                  "type": "number"
+                }
+              },
+              "description": "The meters to be used by the policy against the subscription quota."
+            },
+            "meterOnStatusCodes": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              ],
+              "x-show-example": false,
+              "description": "A list of successful status codes and ranges \"200-299, 304\" that should trigger a metering call.",
+              "default": "200-299",
+              "examples": ["200-399"]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "MonetizationInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheTtlSeconds": 60,
+            "meters": {
+              "requests": 1
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/mtls-auth-inbound/intro.md

@@ -0,0 +1,6 @@
+This policy will authenticate users based on mTLS certificates that are
+configured for your project. This policy is available only to enterprise
+customers (contact sales@zuplo.com to request info). When a requests is
+authenticated with an mTLS certificate, the certificate data will be set as the
+user object of the request. The `user.sub` property will be the value of the
+certificates DN.

package/docs/policies/mtls-auth-inbound/schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "mTLS Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": true,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate requests based on the mTLS protocol.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "MTLSAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "MTLSAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "Indicates whether the request should continue if authentication fails. Default is `false` which means unauthenticated users will automatically receive a 401 response."
+            },
+            "allowExpiredCertificates": {
+              "type": "boolean",
+              "default": false,
+              "description": "Indicates whether the request should continue if the certificate is expired."
+            },
+            "allowRevokedCertificates": {
+              "type": "boolean",
+              "default": false,
+              "description": "Indicates whether the request should continue if the certificate is revoked."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "MTLSAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowExpiredCertificates": false,
+            "allowRevokedCertificates": false,
+            "allowUnauthenticatedRequests": false
+          }
+        }
+      ]
+    }
+  }
+}