zuplo 6.67.32 → 6.68.0

package/docs/policies/akamai-ai-firewall/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": "Akamai AI Firewall",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["ai-gateway"],
+  "description": "Akamai AI Firewall Inbound Policy",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AkamaiAIFirewallInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "AkamaiAIFirewallPolicyOptions",
+          "type": "object",
+          "description": "The options for the Akamai AI Firewall policy.",
+          "properties": {
+            "configurationId": {
+              "type": "string",
+              "title": "Configuration ID",
+              "description": "The configuration ID of the AI Firewall."
+            },
+            "api-key": {
+              "type": "string",
+              "title": "API Key",
+              "description": "The API key for the AI Firewall."
+            },
+            "applicationId": {
+              "type": "string",
+              "title": "Application ID",
+              "description": "The application ID to identify this usage of the AI Firewall (optional)."
+            },
+            "streamingAccumulation": {
+              "type": "object",
+              "title": "Streaming Accumulation Settings",
+              "description": "Configuration for accumulating and validating streaming responses.",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "title": "Enable Streaming Accumulation",
+                  "description": "Enable accumulation and validation of streaming responses.",
+                  "default": true
+                },
+                "eventsInterval": {
+                  "type": "number",
+                  "title": "Events Interval",
+                  "description": "Number of SSE events to accumulate before checking with Akamai (default: 5).",
+                  "minimum": 1,
+                  "maximum": 100,
+                  "default": 5
+                },
+                "checkIntervalMs": {
+                  "type": "number",
+                  "title": "Check Interval (ms)",
+                  "description": "Time interval in milliseconds for periodic checks (alternative to chunk count).",
+                  "minimum": 100,
+                  "maximum": 10000
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "required": ["configurationId", "api-key"],
+          "additionalProperties": false
+        }
+      },
+      "examples": [
+        {
+          "export": "AkamaiAIFirewallInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "streamingAccumulation": {
+              "enabled": true,
+              "eventsInterval": 5
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/amberflo-metering-inbound/doc.md

@@ -0,0 +1,183 @@
+This policy integrates with [Amberflo](https://www.amberflo.io) to enable
+usage-based metering and billing for your API. It automatically tracks API usage
+and sends metering data to Amberflo when requests match your configured success
+criteria.
+
+### How It Works
+
+The policy performs the following operations:
+
+1. Monitors API requests and captures successful responses based on configured
+   status codes
+2. Collects metering data including customer ID, meter name, and value
+3. Batches metering events for efficient processing
+4. Sends the data to Amberflo's ingest endpoint
+5. Provides error handling and logging
+
+### Policy Configuration
+
+Configure the policy with your Amberflo API key and metering parameters:
+
+```json
+{
+  "name": "amberflo-metering",
+  "export": "AmberfloMeteringInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "apiKey": "$env(AMBERFLO_API_KEY)",
+    "meterApiName": "api-requests",
+    "meterValue": 1,
+    "customerIdPropertyPath": ".sub",
+    "statusCodes": "200-299",
+    "dimensions": {
+      "environment": "production"
+    }
+  }
+}
+```
+
+### Customer Identification
+
+You can identify customers in three ways:
+
+1. **Dynamic Property Path**: Extract customer ID from the request user object
+   (recommended)
+2. **Static Default**: Set a global customer ID at the policy level (not
+   recommended)
+3. **Programmatic Setting**: Set customer ID in code for complete flexibility
+
+#### Using customerIdPropertyPath
+
+The `customerIdPropertyPath` extracts the customer ID from the `request.user`
+object. For example, with a JWT token or API Key metadata containing:
+
+```json
+{
+  "sub": "bobby-tables",
+  "data": {
+    "email": "bob@example.com",
+    "name": "Bobby Tables",
+    "accountNumber": 1233423,
+    "roles": ["admin"]
+  }
+}
+```
+
+You can access properties using dot notation (note the required leading dot):
+
+- For the `sub` property: `".sub"`
+- For nested properties: `".data.accountNumber"`
+
+### Programmatic Configuration
+
+You can dynamically set metering properties in your code using the
+`AmberfloMeteringPolicy` helper class:
+
+```ts
+import {
+  AmberfloMeteringPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: MyPolicyOptionsType,
+  policyName: string
+) {
+  AmberfloMeteringPolicy.setRequestProperties(context, {
+    customerId: request.user.sub,
+    meterApiName: request.params.color,
+    meterValue: request.params.quantity || 1,
+    dimensions: {
+      region: request.headers.get("x-region") || "default",
+    },
+  });
+
+  return request;
+}
+```
+
+### Configuration Options
+
+| Option                   | Type         | Required | Description                                                                                |
+| ------------------------ | ------------ | -------- | ------------------------------------------------------------------------------------------ |
+| `apiKey`                 | string       | Yes      | Your Amberflo API key for authentication                                                   |
+| `meterApiName`           | string       | Yes\*    | The name of the meter to use when sending metering calls                                   |
+| `meterValue`             | number       | Yes\*    | The value to increment the meter by (typically 1 for counting API calls)                   |
+| `customerIdPropertyPath` | string       | No       | Path to extract customer ID from `request.user` object                                     |
+| `customerId`             | string       | No       | Default customer ID if not using `customerIdPropertyPath`                                  |
+| `dimensions`             | object       | No       | Additional dimensions to include with metering data                                        |
+| `statusCodes`            | string/array | Yes      | Status codes that trigger metering (e.g., "200-299" or [200, 201])                         |
+| `url`                    | string       | No       | Custom URL for the Amberflo ingest endpoint (defaults to "https://app.amberflo.io/ingest") |
+
+\*Can be set programmatically if not provided in policy configuration
+
+### Usage Examples
+
+#### Basic API Request Metering
+
+Apply the policy to routes you want to meter:
+
+```json
+{
+  "paths": {
+    "/api/products": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["jwt-auth", "amberflo-product-api-metering"]
+          },
+          "handler": {
+            "export": "forwardToOrigin",
+            "module": "$import(@zuplo/runtime)"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### Different Meters for Different Endpoints
+
+Create separate policy instances for different meters:
+
+```json
+[
+  {
+    "name": "amberflo-read-metering",
+    "export": "AmberfloMeteringInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "apiKey": "$env(AMBERFLO_API_KEY)",
+      "meterApiName": "api-reads",
+      "meterValue": 1,
+      "customerIdPropertyPath": ".sub",
+      "statusCodes": "200-299"
+    }
+  },
+  {
+    "name": "amberflo-write-metering",
+    "export": "AmberfloMeteringInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "apiKey": "$env(AMBERFLO_API_KEY)",
+      "meterApiName": "api-writes",
+      "meterValue": 1,
+      "customerIdPropertyPath": ".sub",
+      "statusCodes": "200-299"
+    }
+  }
+]
+```
+
+### Best Practices
+
+- Store your Amberflo API key as an environment variable using
+  `$env(AMBERFLO_API_KEY)`
+- Use `customerIdPropertyPath` instead of hardcoding customer IDs
+- Consider creating different meters for different types of API operations
+- Add relevant dimensions to your metering data for better analytics
+- Monitor your Amberflo dashboard to track API usage patterns

package/docs/policies/amberflo-metering-inbound/intro.md

@@ -0,0 +1,20 @@
+Seamlessly integrate usage-based metering and billing into your API with
+Amberflo integration. This policy automatically tracks API usage and sends
+metering data to [Amberflo](https://www.amberflo.io) for accurate billing and
+consumption analytics.
+
+With this policy, you'll benefit from:
+
+- **Usage-Based Billing**: Easily implement consumption-based pricing models for
+  your API
+- **Granular Metering**: Track usage at the customer and endpoint level with
+  customizable dimensions
+- **Flexible Configuration**: Define meter names, values, and customer
+  identification at the policy or code level
+- **Batch Processing**: Efficiently send usage data with automatic batching for
+  optimal performance
+- **Real-Time Analytics**: Monitor API consumption patterns through Amberflo's
+  dashboard
+
+Add the policy to each route you want to meter, with the ability to customize
+meter names, values, and dimensions per endpoint or dynamically in your code.

package/docs/policies/amberflo-metering-inbound/schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Amberflo Metering / Billing",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Amberflo is a usage metering and billing service. This policy allows you to send metering calls for each API to their meter ingest endpoint.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AmberfloMeteringInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "AmberfloMeteringInboundPolicyOptions",
+          "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.",
+          "required": ["apiKey"],
+          "additionalProperties": false,
+          "properties": {
+            "apiKey": {
+              "type": "string",
+              "examples": ["$env(AMBERFLO_API_KEY)"],
+              "description": "The API key to use when sending metering calls to Amberflo."
+            },
+            "meterApiName": {
+              "type": "string",
+              "examples": ["$env(AMBERFLO_METER_API_NAME)"],
+              "description": "The name of the meter to use when sending metering calls to Amberflo (overridable in code)."
+            },
+            "meterValue": {
+              "type": "number",
+              "examples": ["$env(AMBERFLO_METER_VALUE)"],
+              "description": "The value to use when sending metering calls to Amberflo (overridable in code)."
+            },
+            "customerIdPropertyPath": {
+              "type": "string",
+              "examples": [".sub"],
+              "default": ".sub",
+              "description": "The path to the property on `request.user` contains the customer ID. For example `.data.accountNumber` would read the `request.user.data.accountNumber` property."
+            },
+            "customerId": {
+              "type": "string",
+              "description": "The default customerId for all metering calls - overridable in code and by `customerIdPropertyPath`."
+            },
+            "dimensions": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "A dictionary of dimensions to be sent to Amberflo (extensible in code)."
+            },
+            "statusCodes": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              ],
+              "description": "A list of successful status codes and ranges \"200-299, 304\" that should trigger a metering call to Amberflo.",
+              "default": "200-299"
+            },
+            "url": {
+              "type": "string",
+              "default": " https://app.amberflo.io/ingest",
+              "description": "The URL to send metering events. This is useful for testing purposes."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AmberfloMeteringInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "apiKey": "$env(AMBERFLO_API_KEY)",
+            "customerIdPropertyPath": ".sub",
+            "meterApiName": "$env(AMBERFLO_METER_API_NAME)",
+            "meterValue": "$env(AMBERFLO_METER_VALUE)",
+            "statusCodes": "200-299",
+            "url": " https://app.amberflo.io/ingest"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/api-key-inbound/doc.md

@@ -0,0 +1,77 @@
+Adding API Key authentication to your Zuplo API takes only a few minutes. This
+document shows you how to add the policy to your routes, create an API key, and
+make a request using the API Key.
+
+## Add the API Key Policy
+
+The first step to setting up API Key authentication is to add the API
+Authentication 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 API Keys. Expand
+   the **Policies** section and click **Add Policy**. Search for and select the
+   API Key Inbound policy.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/1a35f4e6-9309-4f22-89da-2e2c25e68403.png" />
+
+3. With the policy selected, you will see the configuration and information
+   about the options. For this tutorial just leave the options as they are and
+   click **OK** to save the policy.
+
+   <Screenshot src="https://cdn.zuplo.com/assets/736fad78-37c8-4f12-9e58-8e697a14284c.png" />
+
+## Create an API Key
+
+In order to make a request to the route, you'll need an API Key.
+
+1. In the [Zuplo Portal](https://portal.zuplo.com) open the **API Key
+   Consumers** section in the **Settings** tab.
+
+2. Click the button **Add New Consumer**.
+
+3. In the form that appears, enter a value for the **Subject** such as
+   `my-test`. You can leave the other fields empty. Click **OK** to create the
+   consumer.
+   <Screenshot src="https://cdn.zuplo.com/assets/68b4571d-fcbc-4c92-977f-7612cd0cfb32.png" size="md" />
+
+4. Now you can see the newly created consumer and its default API key. Select
+   the **Copy** button to copy the API Key. You will use this value in the next
+   section.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/98a3d62f-1b61-4f41-8bac-665e0b02309e.png" size="lg" />
+
+### Test the Policy
+
+Finally, you'll make two API requests to your route to test that authentication
+is working as expected.
+
+1. In the route designer on the route you added the policy, click the **Test**
+   button. In the dialog that opens, click **Test** to make a request.
+
+2. The API Gateway should respond with a **401 Unauthorized** response.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/626e10a2-2350-439a-9081-1ccf1fe90cad.png" size="md" />
+
+3. Now to make an authenticated request, add a header to the request called
+   `Authorization`. Set the value of the header to `Bearer YOUR_API_KEY`
+   replacing `YOUR_API_KEY` with the value of the API Key you copied in the
+   previous section.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/11a3f88a-8613-43c9-9429-4c82e1f1ab4d.png" size="lg" />
+
+4. Click the **Test** button and a **200 OK** response should be returned.
+
+  <Screenshot src="https://cdn.zuplo.com/assets/8182f932-8db6-4456-842f-f65158b174c0.png" size="md" />
+
+You have now setup API Key Authentication on your API Gateway.
+
+See [this document](/docs/articles/api-key-management) for more information
+about API Keys and API Key Management with Zuplo.
+
+## Writing Tests with the Auth Policy
+
+For information on running tests while using API Key Authentication see the
+document
+[Testing API Key Authentication](/docs/articles/testing-api-key-authentication).

package/docs/policies/api-key-inbound/intro.md

@@ -0,0 +1,30 @@
+You can learn more about the Zuplo API Key Service
+[in our documentation](https://zuplo.com/docs/articles/api-key-api#buckets)
+
+Authenticate requests with Zuplo's fully managed API Key service. This policy is
+the easiest way to secure your API and can be combined with other policies like
+Rate limiting, quotas, and more to build a fully featured API to support your
+partners, developers, or customers.
+
+With this policy, you'll benefit from:
+
+- **Simplified Authentication**: Implement API key authentication in minutes
+  with zero code
+- **Enhanced Security**: Protect your APIs with robust key validation and
+  management
+- **Developer-Friendly Experience**: Provide an intuitive way for consumers to
+  authenticate with your API
+- **Complete Management Solution**: Create, revoke, and rotate API keys through
+  Zuplo's built-in management portal
+- **Flexible Implementation**: Support multiple authentication methods including
+  header, query parameter, or cookie
+- **Granular Access Control**: Assign custom metadata and permissions to
+  different API keys
+- **Analytics Integration**: Track API key usage and monitor consumption
+  patterns
+
+For more information on Zuplo's API Key Management service and options enabling
+self-serve API Key management see the following resources:
+
+- [API Key Authentication Overview](https://zuplo.com/docs/articles/api-key-management)
+- [API Key Management API](https://zuplo.com/docs/articles/api-key-api)

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

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "API Key Authentication",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "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.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ApiKeyInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ApiKeyInboundPolicyOptions",
+          "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."
+            },
+            "bucketName": {
+              "type": "string",
+              "x-show-example": false,
+              "description": "The name of the API Key service bucket. Defaults to the autogenerated bucket name for your project."
+            },
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "default": false,
+              "description": "If requests should proceed even if the policy does not successfully authenticate the request. Defaults to false and rejects any request without a valid API key (returning a `401 - Unauthorized` response). Set to `true` to support multiple authentication methods or support both authenticated and anonymous requests."
+            },
+            "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."
+            },
+            "disableAutomaticallyAddingKeyHeaderToOpenApi": {
+              "type": "boolean",
+              "x-show-example": false,
+              "description": "Zuplo will automatically document your API key header within your OpenAPI specification & Developer Portal. Set this to `true` to disable this behavior."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "ApiKeyInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowUnauthenticatedRequests": false,
+            "cacheTtlSeconds": 60
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/archive-request-aws-s3-inbound/intro.md

@@ -0,0 +1,4 @@
+In this example shows how you can archive the body of incoming requests to AWS
+S3 Storage. This can be useful for auditing, logging, or archival scenarios.
+Additionally, you could use this policy to save the body of a request and then
+enqueue some asynchronous work that uses this body.

package/docs/policies/archive-request-aws-s3-inbound/policy.ts

@@ -0,0 +1,58 @@
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+type PolicyOptions = {
+  region: string;
+  bucketName: string;
+  path: string;
+  accessKeyId: string;
+  accessKeySecret: string;
+};
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+  policyName: string,
+) {
+  // NOTE: policy options should be validated, but to keep the sample short,
+  // we are skipping that here.
+
+  // Initialize the S3 client
+  const s3Client = new S3Client({
+    region: options.region,
+    credentials: {
+      accessKeyId: options.accessKeyId,
+      secretAccessKey: options.accessKeySecret,
+    },
+  });
+
+  // Create the file
+  const file = `${options.path}/${Date.now()}-${crypto.randomUUID()}.req.txt`;
+
+  // because we will read the body, we need to
+  // create a clone of this request first, otherwise
+  // there may be two attempts to read the body
+  // causing a runtime error
+  const clone = request.clone();
+
+  // In this example we assume the body could be text, but you could also
+  // request the blob() to handle binary data types like images.
+  //
+  // This example loads the entire body into memory. This is fine for
+  // small payloads, but if you have a large payload you should instead
+  // save the body via streaming.
+  const body = await clone.text();
+
+  // Create the S3 command
+  const command = new PutObjectCommand({
+    Bucket: options.bucketName,
+    Key: file,
+    Body: body,
+  });
+
+  // Use the S3 client to save the object
+  await s3Client.send(command);
+
+  // Continue the request
+  return request;
+}