zuplo 6.67.32 → 6.68.0

package/docs/articles/cors.mdx

@@ -0,0 +1,447 @@
+---
+title: Configuring CORS
+sidebar_label: CORS
+---
+
+Cross-Origin Resource Sharing (CORS) controls which web applications on
+different domains can access your API. Zuplo handles CORS at the gateway level,
+automatically responding to preflight requests and adding the appropriate
+headers to responses.
+
+## Built-in Policies
+
+Every route has a `corsPolicy` property in its `x-zuplo-route` configuration.
+Zuplo provides two built-in policies:
+
+### `none`
+
+Disables CORS for the route. All CORS headers are stripped from responses, and
+preflight `OPTIONS` requests return a `404` response. This is the default when
+no `corsPolicy` is set.
+
+```json title="config/routes.oas.json"
+"x-zuplo-route": {
+  "corsPolicy": "none",
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)"
+  }
+}
+```
+
+### `anything-goes`
+
+Allows any origin, method, and header. This is useful for development or
+internal APIs but is **not recommended for production**. It sets:
+
+- `Access-Control-Allow-Origin`: The requesting origin (reflected back)
+- `Access-Control-Allow-Methods`: The route's configured methods
+- `Access-Control-Allow-Headers`: `*`
+- `Access-Control-Expose-Headers`: `*`
+- `Access-Control-Allow-Credentials`: `true`
+- `Access-Control-Max-Age`: `600`
+
+```json title="config/routes.oas.json"
+"x-zuplo-route": {
+  "corsPolicy": "anything-goes",
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)"
+  }
+}
+```
+
+## Custom CORS Policies
+
+For production use, create custom CORS policies with fine-grained control over
+which origins, methods, and headers are allowed.
+
+Custom CORS policies are defined in the `policies.json` file alongside regular
+policies, under the `corsPolicies` array:
+
+```json title="config/policies.json"
+{
+  "policies": [],
+  "corsPolicies": [
+    {
+      "name": "my-cors-policy",
+      "allowedOrigins": [
+        "https://app.example.com",
+        "https://admin.example.com"
+      ],
+      "allowedMethods": ["GET", "POST", "PUT", "DELETE"],
+      "allowedHeaders": ["Authorization", "Content-Type"],
+      "exposeHeaders": ["X-Request-Id"],
+      "maxAge": 3600,
+      "allowCredentials": true
+    }
+  ]
+}
+```
+
+Then reference the policy by name on each route:
+
+```json title="config/routes.oas.json"
+"x-zuplo-route": {
+  "corsPolicy": "my-cors-policy",
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)"
+  }
+}
+```
+
+You can also select the CORS policy from the route designer dropdown in the
+Zuplo Portal.
+
+### Policy Properties
+
+| Property           | Type                   | Required | Description                                                                                                    |
+| ------------------ | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `name`             | `string`               | Yes      | A unique name used to reference this policy on routes.                                                         |
+| `allowedOrigins`   | `string[]` or `string` | Yes      | Origins permitted to make cross-origin requests. Supports wildcards (see [Origin Matching](#origin-matching)). |
+| `allowedMethods`   | `string[]` or `string` | No       | HTTP methods allowed for cross-origin requests (e.g., `GET`, `POST`).                                          |
+| `allowedHeaders`   | `string[]` or `string` | No       | Request headers the client can send. Use `*` to allow any header.                                              |
+| `exposeHeaders`    | `string[]` or `string` | No       | Response headers the browser can access from JavaScript.                                                       |
+| `maxAge`           | `number`               | No       | Time in seconds the browser caches preflight results.                                                          |
+| `allowCredentials` | `boolean`              | No       | Whether to include credentials (cookies, authorization headers) in cross-origin requests.                      |
+
+All list properties (`allowedOrigins`, `allowedMethods`, `allowedHeaders`,
+`exposeHeaders`) accept either a JSON array of strings or a single
+comma-separated string:
+
+```json
+// Array format
+"allowedOrigins": ["https://app.example.com", "https://admin.example.com"]
+
+// Comma-separated string format
+"allowedOrigins": "https://app.example.com, https://admin.example.com"
+```
+
+:::warning
+
+Do not include a trailing `/` on origin values. For example,
+`https://example.com` is valid but `https://example.com/` does not work.
+
+:::
+
+## Origin Matching
+
+The `allowedOrigins` property supports several matching patterns:
+
+### Exact Match
+
+Specify the full origin including the protocol:
+
+```json
+"allowedOrigins": ["https://app.example.com"]
+```
+
+Origin matching is case-insensitive, so `https://APP.EXAMPLE.COM` matches
+`https://app.example.com`.
+
+### Wildcard (`*`)
+
+Allow any origin:
+
+```json
+"allowedOrigins": ["*"]
+```
+
+### Subdomain Wildcards
+
+Use `*.` to match a single subdomain level:
+
+```json
+"allowedOrigins": ["https://*.example.com"]
+```
+
+This matches `https://app.example.com` and `https://api.example.com`, but does
+**not** match:
+
+- `https://example.com` (no subdomain)
+- `https://v2.api.example.com` (multi-level subdomain)
+
+### Wildcards with Ports
+
+Subdomain wildcards work with ports:
+
+```json
+"allowedOrigins": ["http://*.localhost:3000"]
+```
+
+This matches `http://app.localhost:3000` but not `http://localhost:3000`.
+
+### Multiple Patterns
+
+Combine exact origins and wildcard patterns:
+
+```json
+"allowedOrigins": [
+  "https://*.example.com",
+  "https://specific.domain.com",
+  "http://localhost:3000"
+]
+```
+
+## Using Environment Variables
+
+Use [environment variables](./environment-variables.mdx) to configure different
+origins per environment:
+
+```json title="config/policies.json"
+{
+  "corsPolicies": [
+    {
+      "name": "my-cors-policy",
+      "allowedOrigins": "$env(ALLOWED_ORIGINS)",
+      "allowedHeaders": "$env(ALLOWED_HEADERS)",
+      "allowedMethods": ["GET", "POST", "PUT"],
+      "maxAge": 600,
+      "allowCredentials": true
+    }
+  ]
+}
+```
+
+Set the environment variable as a comma-separated string:
+
+```
+ALLOWED_ORIGINS=https://app.example.com, https://admin.example.com
+```
+
+Environment variables work for `allowedOrigins`, `allowedMethods`,
+`allowedHeaders`, and `exposeHeaders`.
+
+## How CORS Works in Zuplo
+
+### Preflight Requests
+
+When a browser makes a cross-origin request that requires preflight, it sends an
+`OPTIONS` request with `Origin` and `Access-Control-Request-Method` headers.
+Zuplo handles these automatically:
+
+1. Zuplo matches the `OPTIONS` request path and the requested method to a
+   configured route.
+2. If the route has a CORS policy, Zuplo checks whether the request origin
+   matches the policy's `allowedOrigins`.
+3. If the origin matches, Zuplo responds with a `200 OK` and the appropriate
+   CORS headers.
+4. If the origin does not match or the route has no CORS policy, Zuplo responds
+   with a `404 Not Found`.
+
+Preflight handling runs before any policies or handlers on the route.
+
+### Simple Requests
+
+For simple cross-origin requests (e.g., `GET` with standard headers), there is
+no preflight. Zuplo adds CORS headers to the response based on the route's
+policy. If the origin does not match, no CORS headers are added and the browser
+blocks the response.
+
+### Header Precedence
+
+Zuplo strips any existing CORS headers from upstream responses before applying
+the configured policy headers. This prevents conflicts and ensures the gateway
+is the single source of truth for CORS configuration.
+
+## Troubleshooting
+
+### No CORS headers in response
+
+- Verify the route has a `corsPolicy` set (not `none`).
+- Check that the request includes an `Origin` header. Browsers add this
+  automatically for cross-origin requests, but tools like `curl` do not.
+- Confirm the `Origin` value matches one of the `allowedOrigins` patterns
+  exactly (including the protocol like `https://`).
+
+### Preflight returns 404
+
+- Ensure the `corsPolicy` on the matching route is not set to `none`.
+- Verify the `Access-Control-Request-Method` header in the preflight request
+  matches a method configured on the route.
+- Check that the request path matches an existing route.
+
+### Preflight returns 400
+
+- The preflight request must include both the `Origin` and
+  `Access-Control-Request-Method` headers. A `400` response means one or both
+  are missing.
+
+### Wildcard subdomain not matching
+
+- The `*.` pattern only matches a **single** subdomain level.
+  `https://*.example.com` does not match `https://v2.api.example.com`.
+- The `*.` pattern does not match the base domain. `https://*.example.com` does
+  not match `https://example.com`. Add the base domain separately if needed.
+
+### Credentials not working
+
+- Set `allowCredentials` to `true` in the CORS policy.
+- When using credentials, `allowedOrigins` cannot rely on a literal `*` being
+  sent as the `Access-Control-Allow-Origin` header value. Zuplo reflects the
+  actual requesting origin instead, which is compatible with credentials.
+
+### Backend CORS headers conflicting with Zuplo
+
+If your backend service sends its own `Access-Control-*` headers, they can
+conflict with the headers Zuplo sets from the CORS policy. Zuplo strips existing
+CORS headers from upstream responses before applying the configured policy, but
+if you have custom outbound policies that interact with the response, backend
+CORS headers may leak through.
+
+To prevent conflicts, use the
+[Remove Response Headers](../policies/remove-headers-outbound.mdx) outbound
+policy to explicitly strip CORS headers from your backend response:
+
+```json title="config/policies.json"
+{
+  "name": "strip-backend-cors-headers",
+  "policyType": "remove-headers-outbound",
+  "handler": {
+    "export": "RemoveHeadersOutboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headers": [
+        "access-control-allow-origin",
+        "access-control-allow-methods",
+        "access-control-allow-headers",
+        "access-control-expose-headers",
+        "access-control-allow-credentials",
+        "access-control-max-age"
+      ]
+    }
+  }
+}
+```
+
+Alternatively, disable CORS on your backend entirely and let Zuplo be the single
+source of truth for CORS configuration.
+
+### Browser shows "CORS error" but the real issue is a 401 or 403
+
+When an API request fails with a `401 Unauthorized` or `403 Forbidden` response,
+the browser often reports it as a CORS error. This happens because the error
+response may not include the required `Access-Control-Allow-Origin` header, so
+the browser blocks access to the response entirely and surfaces a generic CORS
+message.
+
+This is especially common when an inbound policy (such as API key
+authentication) rejects the request before the handler runs. The preflight
+`OPTIONS` request succeeds because it runs before any policies, but the actual
+`GET` or `POST` request gets rejected by the authentication policy.
+
+To diagnose this:
+
+1. Check the request in the browser's Network tab. Look at the actual HTTP
+   status code -- if it is `401` or `403`, the problem is authentication, not
+   CORS.
+2. Test the same request with `curl` and include an `Origin` header to see the
+   full response:
+   ```bash
+   curl -v -H "Origin: https://app.example.com" \
+     -H "Authorization: Bearer YOUR_TOKEN" \
+     https://your-api.zuplo.dev/your-route
+   ```
+3. Fix the underlying authentication issue. Once the request returns a
+   successful response, the CORS headers are included and the browser error goes
+   away.
+
+### CORS headers lost in custom outbound policies
+
+When a custom outbound policy creates a new `Response` object, CORS headers that
+Zuplo added can be lost if the new response does not carry them forward. Zuplo
+applies CORS headers after the handler runs but before outbound policies
+execute, so any outbound policy that replaces the response must preserve the
+existing headers.
+
+Always pass the original response headers when constructing a new `Response`:
+
+```ts title="modules/my-outbound-policy.ts"
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const data = await response.json();
+
+  // Transform the data as needed
+  data.transformed = true;
+
+  // Preserve headers (including CORS headers) from the original response
+  return new Response(JSON.stringify(data), {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+```
+
+If you need to modify headers, copy them into a new `Headers` object first:
+
+```ts
+const headers = new Headers(response.headers);
+headers.set("x-custom-header", "value");
+
+return new Response(body, {
+  status: response.status,
+  headers,
+});
+```
+
+Avoid constructing a `Response` with no headers argument or with an empty
+`Headers` object, as this drops all CORS headers and causes the browser to block
+the response.
+
+### CORS on localhost during development
+
+When developing locally, the browser enforces CORS even for `localhost`. Common
+issues include:
+
+- **Port mismatch**: `http://localhost:3000` and `http://localhost:5173` are
+  different origins. Add each port you use to `allowedOrigins`.
+- **Protocol mismatch**: `http://localhost:3000` and `https://localhost:3000`
+  are different origins. Make sure the protocol matches.
+- **Missing localhost**: If you use a custom CORS policy without `localhost` in
+  `allowedOrigins`, browser requests from your local development server are
+  blocked.
+
+For development, either add your local origins to a custom CORS policy:
+
+```json
+"allowedOrigins": [
+  "https://app.example.com",
+  "http://localhost:3000",
+  "http://localhost:5173"
+]
+```
+
+Or use [environment variables](./environment-variables.mdx) to keep production
+and development origins separate:
+
+```json title="config/policies.json"
+{
+  "corsPolicies": [
+    {
+      "name": "my-cors-policy",
+      "allowedOrigins": "$env(ALLOWED_ORIGINS)"
+    }
+  ]
+}
+```
+
+Then set different values per environment:
+
+- **Production**: `ALLOWED_ORIGINS=https://app.example.com`
+- **Development**:
+  `ALLOWED_ORIGINS=https://app.example.com, http://localhost:3000`
+
+:::tip
+
+Use the `anything-goes` built-in policy for quick local testing when you do not
+need to validate CORS behavior. Switch to a custom policy before deploying to
+production.
+
+:::
+
+For more details on CORS, see the MDN documentation:
+[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).

package/docs/articles/custom-audit-log-policy.mdx

@@ -0,0 +1,95 @@
+---
+title: Custom Audit Logging Policy
+sidebar_label: Audit Logging
+---
+
+This guide explains how to add custom audit logging beyond the scope of the
+`AuditLogsInboundPolicy`.
+
+Audit logging is an important part of API security that plays a critical role in
+detecting and correcting issues such as unauthorized access or permission
+elevations within your system. Audit logging is also a requirement for many
+compliance certifications as well as part of the buying criteria for larger
+enterprises.
+
+Adding Audit Logging to your APIs that are secured with Zuplo is as easy as
+adding a custom policy. Typically you want to add audit logs to any API that
+modifies data, however depending on the API you may want it on read operations
+as well (for example retrieve a secret key, etc.)
+
+## Example Policy: WorkOS Audit Logs
+
+[WorkOS](https://workos.com/) provides various services that help enable
+enterprise features on your service such as SSO and Audit Logs. With Zuplo it's
+easy to create a [custom policy](../policies/custom-code-inbound.mdx) that uses
+[runtime hooks](../programmable-api/runtime-extensions.mdx) to log API calls
+using their API.
+
+```ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export async function auditLogPlugin(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+) {
+  // Clone the request so the body can be read in the hook
+  // note: remove this is you don't need content from the body
+  const cloned = request.clone();
+  context.addResponseSendingFinalHook(async (response) => {
+    const incomingBody = await cloned.json();
+    // This is an example event. Extract any additional data needed from the
+    // request.
+    const body = {
+      organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
+      event: {
+        action: "user.signed_in",
+        occurred_at: "2022-09-02T16:35:39.317Z",
+        version: 1,
+        actor: {
+          type: "user",
+          // Add the use the user sub for authenticated users
+          id: request.user.sub,
+          metadata: {
+            role: "user",
+          },
+        },
+        targets: [
+          {
+            type: "user",
+            id: "user_98432YHF",
+            name: "Jon Smith",
+          },
+          {
+            type: "team",
+            id: "team_J8YASKA2",
+            metadata: {
+              owner: "user_01GBTCQ2",
+            },
+          },
+        ],
+        context: {
+          location: request.headers.get("True-Client-IP"),
+          user_agent: request.headers.get("User-Agent"),
+        },
+        metadata: {
+          extra: incomingBody.extra,
+        },
+      },
+    };
+    await fetch("https://api.workos.com/audit_logs/events", {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: {
+        Authorization: `Bearer ${environment.WORKOS_API_KEY}`,
+        "Content-Type": "application/json",
+        // Optional idempotency key.
+        // See: https://workos.com/docs/reference/idempotency
+        // "Idempotency-Key": "YOUR_KEY_HERE"
+      },
+    });
+  });
+
+  return request;
+}
+```

package/docs/articles/custom-ci-cd-azure.mdx

@@ -0,0 +1,81 @@
+---
+title: "Azure Pipelines"
+sidebar_label: Azure Pipelines
+---
+
+Azure Pipelines brings enterprise-grade CI/CD to your Zuplo API gateway. Build
+complex deployment workflows with stages, approvals, and integrations across
+your Azure ecosystem.
+
+## Why Azure Pipelines with Zuplo?
+
+The Zuplo CLI integrates naturally with Azure Pipelines YAML workflows:
+
+**Enterprise pipeline features** — Multi-stage pipelines, deployment jobs,
+environment approvals, and service connections. Build the exact workflow your
+organization requires.
+
+**Azure ecosystem integration** — Deploy alongside your Azure Functions, App
+Services, and Kubernetes workloads. Manage secrets through Azure Key Vault.
+Track deployments in Azure DevOps.
+
+**Variable groups and templates** — Share configuration across pipelines. Define
+deployment templates once and reuse them across projects.
+
+**Compliance and auditing** — Full audit trails, branch policies, and approval
+gates satisfy enterprise compliance requirements.
+
+## How It Works
+
+The Zuplo CLI handles deployment and testing. Azure Pipelines orchestrates your
+workflow:
+
+```bash
+# Deploy to Zuplo (environment name from branch or --environment flag)
+npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+
+# Run tests against any Zuplo environment
+npx zuplo test --endpoint https://your-env.zuplo.dev
+
+# Clean up environments you no longer need
+npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+
+# Test locally before deploying
+npx zuplo dev  # starts local server on port 9000
+```
+
+Use `tee` to capture deployment output for passing the URL to test stages. The
+CLI outputs `Deployed to https://...` which you can parse with `grep` or `sed`.
+
+## Prerequisites
+
+1. **Disconnect Git integration** — If you're using Azure Pipelines for
+   deployments, disconnect the native Git integration to avoid duplicate
+   deployments. Go to **Settings** > **Source Control** and click
+   **Disconnect**.
+
+2. **Add your API key** — Store your Zuplo API key as a pipeline variable or in
+   a variable group. Go to **Pipelines** > **Library** to create a variable
+   group with `ZUPLO_API_KEY`.
+
+## Examples
+
+Start with the workflow that matches your needs:
+
+- **[Basic Deployment](./ci-cd-azure/basic-deployment.mdx)** — Deploy on every
+  push to main
+- **[Deploy and Test](./ci-cd-azure/deploy-and-test.mdx)** — Run tests after
+  deployment
+- **[PR Preview Environments](./ci-cd-azure/pr-preview-environments.mdx)** —
+  Isolated environments for every pull request
+- **[Local Testing in CI](./ci-cd-azure/local-testing.mdx)** — Test with local
+  Zuplo server before deploying
+- **[Tag-Based Releases](./ci-cd-azure/tag-based-releases.mdx)** — Deploy only
+  on tagged releases
+- **[Multi-Stage Deployment](./ci-cd-azure/multi-stage-deployment.mdx)** —
+  Staging to production with approval gates
+
+## Complete Example Repository
+
+See all these patterns working together in the
+[Zuplo CLI Example Project](https://github.com/zuplo/zup-cli-example-project).

package/docs/articles/custom-ci-cd-bitbucket.mdx

@@ -0,0 +1,80 @@
+---
+title: "Bitbucket Pipelines"
+sidebar_label: Bitbucket Pipelines
+---
+
+Bitbucket Pipelines brings CI/CD directly into your Bitbucket workflow. Define
+pipelines in `bitbucket-pipelines.yml` and deploy your Zuplo API gateway
+alongside your code reviews and pull requests.
+
+## Why Bitbucket Pipelines with Zuplo?
+
+The Zuplo CLI integrates naturally with Bitbucket's pipeline model:
+
+**Integrated with Bitbucket** — Pipelines run automatically on pushes and pull
+requests. See deployment status right in your PR. No external CI service to
+manage.
+
+**Branch and PR pipelines** — Define different pipelines for branches and pull
+requests. Deploy preview environments for PRs, production from main.
+
+**Deployment environments** — Track deployments with Bitbucket Deployments. See
+history, compare environments, and manage releases.
+
+**Atlassian ecosystem** — Connect with Jira for deployment tracking. Link
+deployments to issues automatically.
+
+## How It Works
+
+The Zuplo CLI handles deployment and testing. Bitbucket Pipelines orchestrates
+your workflow:
+
+```bash
+# Deploy to Zuplo (environment name from branch or --environment flag)
+npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+
+# Run tests against any Zuplo environment
+npx zuplo test --endpoint https://your-env.zuplo.dev
+
+# Clean up environments you no longer need
+npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+
+# Test locally before deploying
+npx zuplo dev  # starts local server on port 9000
+```
+
+Use artifacts to pass the deployment URL between steps. Write the URL to a file
+and mark it as an artifact for subsequent steps.
+
+## Prerequisites
+
+1. **Disconnect Git integration** — If you're using Bitbucket Pipelines for
+   deployments, disconnect the native Git integration to avoid duplicate
+   deployments. Go to **Settings** > **Source Control** and click
+   **Disconnect**.
+
+2. **Add your API key** — Store your Zuplo API key as a repository variable. Go
+   to **Repository settings** > **Repository variables** and add
+   `ZUPLO_API_KEY`. Check **Secured** to hide it in logs.
+
+## Examples
+
+Start with the workflow that matches your needs:
+
+- **[Basic Deployment](./ci-cd-bitbucket/basic-deployment.mdx)** — Deploy on
+  every push to main
+- **[Deploy and Test](./ci-cd-bitbucket/deploy-and-test.mdx)** — Run tests after
+  deployment
+- **[PR Preview Environments](./ci-cd-bitbucket/pr-preview-environments.mdx)** —
+  Isolated environments for pull requests
+- **[Local Testing in CI](./ci-cd-bitbucket/local-testing.mdx)** — Test with
+  local Zuplo server before deploying
+- **[Tag-Based Releases](./ci-cd-bitbucket/tag-based-releases.mdx)** — Deploy
+  only on tagged releases
+- **[Multi-Stage Deployment](./ci-cd-bitbucket/multi-stage-deployment.mdx)** —
+  Staging to production with manual triggers
+
+## Complete Example Repository
+
+See all these patterns working together in the
+[Zuplo CLI Example Project](https://github.com/zuplo/zup-cli-example-project).