zuplo 6.67.32 → 6.68.0

package/docs/policies/upstream-zuplo-jwt-auth-inbound/schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Upstream Zuplo JWT",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Generates a Zuplo JWT token and attaches it to the outgoing request. This policy creates a self-signed JWT using the Zuplo JWT plugin and adds it to the specified header for upstream authentication.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamZuploJwtAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamZuploJwtAuthInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the Upstream Zuplo JWT Auth Inbound policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "audience": {
+              "type": "string",
+              "examples": ["https://api.example.com", "my-service"],
+              "description": "The audience claim for the JWT."
+            },
+            "headerName": {
+              "type": "string",
+              "default": "Authorization",
+              "examples": ["Authorization", "X-API-Token"],
+              "description": "The header name where the JWT will be attached. Defaults to 'Authorization'."
+            },
+            "tokenPrefix": {
+              "type": "string",
+              "default": "Bearer",
+              "examples": ["Bearer", "Token"],
+              "description": "The prefix to use before the JWT token. Defaults to 'Bearer'. Set to an empty string to send the token without a prefix."
+            },
+            "additionalClaims": {
+              "type": "object",
+              "examples": [
+                {
+                  "role": "admin",
+                  "custom": "value"
+                }
+              ],
+              "description": "Additional claims to include in the JWT. These will be merged with the default claims.",
+              "additionalProperties": true
+            },
+            "expiresIn": {
+              "oneOf": [
+                {
+                  "type": "number",
+                  "description": "Expiration time in seconds."
+                },
+                {
+                  "type": "string",
+                  "description": "Expiration time as a string."
+                }
+              ],
+              "default": 300,
+              "examples": [300, "5m", "1h", "7d"],
+              "description": "JWT expiration time. Can be a number (seconds) or a string with units (e.g., '5m' for 5 minutes, '1h' for 1 hour, '7d' for 7 days). Defaults to 300 seconds (5 minutes)."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamZuploJwtAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "additionalClaims": {
+              "role": "admin",
+              "custom": "value"
+            },
+            "audience": "https://api.example.com",
+            "expiresIn": 300,
+            "headerName": "Authorization",
+            "tokenPrefix": "Bearer"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/validate-json-schema-inbound/doc.md

@@ -0,0 +1,129 @@
+Here's a simple, example JSON Schema
+
+```json
+{
+  "title": "Car",
+  "type": "object",
+  "properties": {
+    "make": {
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "maxSpeed": {
+      "description": "Max Speed in Mile Per Hour (MPH)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "color": {
+      "enum": ["black", "brown", "blue", "red", "silver"],
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["make", "model"]
+}
+```
+
+> Note - "title" is a required property of JSON schema
+
+This defines a body that should be of type object with required string
+properties `make` and `model`. It also defines two optional properties
+`maxSpeed` and `color`. The former must be an integer greater than or equal to
+zero and `color` can (in this silly example) can be one of "black", "brown",
+"red", "silver" or "blue". No other properties can be on this object.
+
+The schemas file should live in the `schemas` folder of your project - for the
+purposes of this example let's imagine it is called `car.json`.
+
+<ZupIt repoUrl="https://github.com/zuplo/samples-basic-auth" />
+
+## Configuration
+
+Here is an example configuration (this would go in `policies.json`).
+
+```json
+{
+  "name": "validate-car-policy",
+  "policyType": "validate-json-schema-inbound",
+  "handler": {
+    "export": "ValidateJsonSchemaInbound",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "validator": "$import(./schemas/car.json)"
+    }
+  }
+}
+```
+
+- `name` the name of your policy instance, this is used to refer to your policy
+  from your routes, see below.
+- `policyType` the identifier of the policy. This is used by the Zuplo UI. Value
+  should be `validate-json-schema-inbound`.
+- `handler/export` The name of the exported type. Value should be
+  `ValidateJsonSchemaInboundPolicy`.
+- `handler/module` the module containing the policy. Value should be
+  `@zuplo/runtime`.
+- `handler/options` The options for this policy:
+  - `validator` a
+    '$import' reference to the schema - e.g. `$import(./schemas/car.json)`
+
+This policy is then referenced from each route where you want the policy to be
+enforced, for example:
+
+```json
+{
+  "path": "/products/:123",
+  "methods": ["POST"],
+  "handler": {
+    "module": "$import(./modules/products)",
+    "export": "postProducts"
+  },
+  "corsPolicy": "None",
+  "policies": {
+    "inbound": ["validate-car-policy"]
+  }
+}
+```
+
+You can test this in the API Test Console with the following (correct) body
+
+```json
+{
+  "make": "Alfa Romeo",
+  "model": "156",
+  "maxSpeed": 134,
+  "color": "silver"
+}
+```
+
+## Errors
+
+### Missing fields
+
+If the request body is missing a required field, an error similar to the
+following will be returned.
+
+```json
+{
+  "code": "SCHEMA_VALIDATION_FAILED",
+  "help_url": "https://zup.fail/SCHEMA_VALIDATION_FAILED",
+  "message": "Incoming body did not pass schema validation",
+  "errors": ["Body must have required property 'price'"]
+}
+```
+
+### Invalid Field Type
+
+If the request body contains a field that is not of the correct type, an error
+similar to the following will be returned.
+
+```json
+{
+  "code": "SCHEMA_VALIDATION_FAILED",
+  "help_url": "https://zup.fail/SCHEMA_VALIDATION_FAILED",
+  "message": "Incoming body did not pass schema validation",
+  "errors": ["price must be number"]
+}
+```

package/docs/policies/validate-json-schema-inbound/intro.md

@@ -0,0 +1,7 @@
+The Validate JSON Schema policy is used to validate the body of incoming
+requests. It works using JSON Schemas defined in the `Schemas` folder of your
+project.
+
+When configured, any requests that do not have a body conforming to your JSON
+schema will be rejected with a `400: Bad Request` response containing a detailed
+error message (in JSON) explaining why the body was not accepted.

package/docs/policies/validate-json-schema-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": "JSON Body Validation",
+  "isDeprecated": true,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Validates the body of an incoming request based on a JSON schema.",
+  "deprecatedMessage": "Use the new [Request Validation Policy](https://zuplo.com/docs/policies/request-validation-inbound). The new policy validates JSON bodies like this policy, but also supports validation of parameters, query strings, etc.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "ValidateJsonSchemaInbound",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "ValidateJsonSchemaInboundOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["validator"],
+          "properties": {
+            "validator": {
+              "type": "string",
+              "examples": ["$import(./schemas/example-schema.json)"],
+              "description": "The JSON schema to validate against."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "ValidateJsonSchemaInbound",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "validator": "$import(./schemas/example-schema.json)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/web-bot-auth-inbound/doc.md

@@ -0,0 +1,104 @@
+## How It Works
+
+The policy checks for HTTP Message Signatures in the request headers
+(`Signature` and `Signature-Input`). These signatures are verified using the
+`web-bot-auth` npm package.
+
+When a bot makes a request to your API, the policy:
+
+1. Checks if the request has signature headers
+2. Verifies the signature using the `web-bot-auth` library
+3. Extracts the bot identity from the verified signature
+4. Checks if the bot is in the allowed list
+5. Either allows or blocks the request based on configuration
+
+## Configuration Options
+
+| Option                         | Type     | Required | Default | Description                                                  |
+| ------------------------------ | -------- | -------- | ------- | ------------------------------------------------------------ |
+| `allowedBots`                  | string[] | Yes      | -       | List of bot identifiers that are allowed to access the API   |
+| `blockUnknownBots`             | boolean  | Yes      | true    | Whether to block bots that aren't in the allowed list        |
+| `allowUnauthenticatedRequests` | boolean  | No       | false   | Allow requests without bot signatures to proceed             |
+| `directoryUrl`                 | string   | No       | -       | Optional URL to a directory of known bots (for verification) |
+
+## Example Configuration
+
+```json
+{
+  "allowedBots": ["googlebot", "bingbot", "yandexbot"],
+  "blockUnknownBots": true,
+  "allowUnauthenticatedRequests": false,
+  "directoryUrl": "https://example.com/bot-directory.json"
+}
+```
+
+## Bot Directory
+
+If you specify a `directoryUrl`, the policy will fetch the directory of known
+bots from that URL. The directory should be a JSON object mapping bot
+identifiers to their public keys in JWK format.
+
+Example directory:
+
+```json
+{
+  "googlebot": {
+    "kty": "OKP",
+    "crv": "Ed25519",
+    "kid": "googlebot",
+    "x": "..."
+  },
+  "bingbot": {
+    "kty": "OKP",
+    "crv": "Ed25519",
+    "kid": "bingbot",
+    "x": "..."
+  }
+}
+```
+
+## Request Context
+
+When a bot is successfully authenticated, the policy adds the bot identity to
+the request context. You can access this in subsequent policies or handlers
+using the `getBotId` helper function:
+
+```typescript
+import { getBotId } from "@zuplo/runtime";
+
+// In your policy or handler
+const botId = getBotId(context);
+```
+
+## Error Handling
+
+If a bot fails authentication, the policy returns a 401 Unauthorized response
+with an error message. If a request doesn't have signature headers and
+`allowUnauthenticatedRequests` is false, the policy also returns a 401 response.
+
+## Cryptographic Verification
+
+When a directory URL is provided, the policy performs cryptographic verification
+of the bot signatures:
+
+1. It fetches the bot's public key from the directory
+2. Imports the key using the Web Crypto API
+3. Verifies the signature against the request data
+
+This provides strong cryptographic assurance that the bot is who it claims to
+be.
+
+## Implementation Details
+
+The policy uses the `web-bot-auth` npm package to implement HTTP Message
+Signatures verification. The implementation:
+
+1. Uses the `verify` function from the `web-bot-auth` package to handle
+   signature verification
+2. Validates that the bot is in the allowed list
+3. Optionally verifies the signature against a directory of known bots
+4. Adds the verified bot identity to the request context
+
+This implementation leverages the standard web-bot-auth library for bot
+authentication, ensuring compatibility and security across different bot
+providers.

package/docs/policies/web-bot-auth-inbound/intro.md

@@ -0,0 +1,16 @@
+Authenticate bots using HTTP Message Signatures via the official web-bot-auth
+npm package. This policy allows you to specify friendly bots and block others
+based on configuration.
+
+With this policy, you'll benefit from:
+
+- **Enhanced API Security**: Protect your endpoints from unauthorized bot
+  traffic while allowing legitimate bots
+- **Cryptographic Verification**: Leverage HTTP Message Signatures to ensure
+  bots are who they claim to be
+- **Flexible Bot Management**: Easily configure which bots are allowed to access
+  your API
+- **Detailed Request Context**: Access bot identity information in subsequent
+  policies or handlers
+- **Seamless Integration**: Works with standard HTTP Message Signatures used by
+  major bot providers

package/docs/policies/web-bot-auth-inbound/schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Web Bot Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Authenticate bots using web-bot-auth HTTP Message Signatures.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "WebBotAuthInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "Web Bot Auth Inbound Policy Options",
+          "description": "Options for the Web Bot Auth Inbound Policy.",
+          "type": "object",
+          "properties": {
+            "allowedBots": {
+              "type": "array",
+              "description": "List of bot identifiers that are allowed to access the API.",
+              "items": {
+                "type": "string"
+              }
+            },
+            "blockUnknownBots": {
+              "type": "boolean",
+              "description": "Whether to block bots that aren't in the allowed list.",
+              "default": true
+            },
+            "allowUnauthenticatedRequests": {
+              "type": "boolean",
+              "description": "Allow requests without bot signatures to proceed. This is useful if you want to use multiple authentication policies or if you want to allow both authenticated and non-authenticated traffic.",
+              "default": false
+            },
+            "directoryUrl": {
+              "type": "string",
+              "description": "Optional URL to a directory of known bots (for verification).",
+              "default": null
+            }
+          },
+          "required": ["allowedBots", "blockUnknownBots"],
+          "additionalProperties": false
+        }
+      },
+      "examples": [
+        {
+          "export": "WebBotAuthInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowUnauthenticatedRequests": false,
+            "allowedBots": [],
+            "blockUnknownBots": true,
+            "directoryUrl": null
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/xml-to-json-outbound/doc.md

@@ -0,0 +1,71 @@
+This policy can help expose legacy XML or SOAP APIs using modern JSON REST APIs.
+The policy is configurable in ways that make it easier to strip parts of the XML
+document that you are unlikely to use, such as processing instructions,
+namespaces, or directives. The default options for this policy will generally
+give you a fairly clean output. However, it is likely that the output of the raw
+conversion is still not in the best format.
+
+The best way to clean up the output of your XML is first, run this policy, then
+add a [custom code outbound policy](/docs/policies/custom-code-outbound) that
+further reshapes the JSON data structure. An example policy that cleans up a
+SOAP response is shown below.
+
+```xml title="SOAP Response"
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <m:ListOfCurrenciesByNameResponse xmlns:m="http://www.oorsprong.org/websamples.countryinfo">
+      <m:ListOfCurrenciesByNameResult>
+        <m:tCurrency>
+          <m:sISOCode>USD</m:sISOCode>
+          <m:sName>Dollar</m:sName>
+        </m:tCurrency>
+        <m:tCurrency>
+          <m:sISOCode>EUR</m:sISOCode>
+          <m:sName>Euro</m:sName>
+        </m:tCurrency>
+      </m:ListOfCurrenciesByNameResult>
+    </m:ListOfCurrenciesByNameResponse>
+  </soap:Body>
+</soap:Envelope>
+```
+
+The code in the policy below takes the output (`response.json()`) of the XML to
+JSON Outbound policy and reshapes it to a simple JSON structure.
+
+```ts title="modules/clean-soap.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function cleanSoapBody(
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  const soap = await response.json();
+  const data: { isoCode: string; name: string }[] =
+    soap.Envelope.Body.ListOfCurrenciesByNameResponse.ListOfCurrenciesByNameResult.tCurrency.map(
+      (c) => ({
+        isoCode: c.sISOCode,
+        name: c.sName,
+      })
+    );
+
+  return new Response(JSON.stringify({ total: data.length, data }), {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}
+``;
+```
+
+The JSON response of your API would then be a easily consumable JSON object.
+
+```json title="JSON Response"
+{
+  "total": 2,
+  "data": [
+    { "isoCode": "USD", "name": "Dollar" },
+    { "isoCode": "EUR", "name": "Euro" }
+  ]
+}
+```

package/docs/policies/xml-to-json-outbound/intro.md

@@ -0,0 +1,4 @@
+This policy is useful for converting legacy XML or SOAP APIs into modern REST
+APIs. It can be useful to add a custom outbound policy that runs after this
+policy to further transform the raw converted content into something more user
+friendly.