zuplo 6.70.69 → 6.70.70

package/docs/articles/opentelemetry.mdx

@@ -222,8 +222,11 @@ export function runtimeInit(runtime: RuntimeExtensions) {
 ### Tracing and Logging Configuration
 
 Logging is only enabled when specifically configured with its own endpoint using
-the `logUrl` property. When using both tracing and logging, you can configure
-them with separate endpoints.
+the `logUrl` property. When using both tracing and logging, use the top-level
+`traceUrl`, `logUrl`, and `headers` properties instead of the `exporter` object
+shown above. The plugin supports both configuration shapes, but they're mutually
+exclusive: `exporter` configures tracing only, while `traceUrl` and `logUrl`
+configure tracing and logging together with a shared set of `headers`.
 
 ```ts title="zuplo.runtime.ts"
 import { OpenTelemetryPlugin } from "@zuplo/otel";

package/docs/articles/per-user-rate-limits-using-db.mdx

@@ -10,10 +10,9 @@ tags:
 ---
 
 In this example we show a more advanced implementation of
-[dynamic rate limiting](../articles/per-user-rate-limits-using-db.mdx). It uses
-a database lookup to get the customer details and combines that with the
-ZoneCache to improve performance, reduce latency and lower the load on the
-database.
+[dynamic rate limiting](./step-5-dynamic-rate-limiting.mdx). It uses a database
+lookup to get the customer details and combines that with the ZoneCache to
+improve performance, reduce latency and lower the load on the database.
 
 In this example we use [Supabase](https://supabase.com) as the database but you
 could use your own API, [Xata](https://xata.io),
@@ -22,8 +21,8 @@ all.
 
 If you haven't already, check out the
 [rate-limiting policy](../policies/rate-limit-inbound.mdx) and the
-[dynamic rate limiting quickstart](../articles/per-user-rate-limits-using-db.mdx).
-Then you should be oriented to how dynamic rate limiting works.
+[dynamic rate limiting quickstart](./step-5-dynamic-rate-limiting.mdx). Then you
+should be oriented to how dynamic rate limiting works.
 
 Below is a full implementation of a custom rate limiting function. In our
 example this is a module called `per-user-rate-limiting.ts`.

package/docs/articles/securing-the-gateway-with-client-mtls.mdx

@@ -1,39 +1,45 @@
 ---
-title: Client mTLS Authentication
+title: Client mTLS authentication
+sidebar_label: Client mTLS
+description:
+  Require API callers to present client certificates signed by a CA you trust
+  before they reach your Zuplo gateway.
 ---
 
 <EnterpriseFeature name="Client mTLS" />
 
 Client mTLS authentication lets your Zuplo gateway verify the identity of
-clients calling your API using certificates issued by your own Certificate
-Authority (CA). Both the client and the gateway authenticate each other during
-the TLS handshake, so only clients holding a certificate signed by your CA can
-reach your API.
+clients calling your API with certificates issued by your own certificate
+authority (CA). Both the client and the gateway authenticate each other during
+the TLS handshake. Routes protected by the `mtls-auth-inbound` policy only allow
+clients that present a valid certificate chain anchored by a CA you uploaded to
+Zuplo.
 
-## How Client mTLS Works
+## How client mTLS works
 
 When a client calls your Zuplo gateway:
 
-1. The client presents a certificate issued by your CA during the TLS handshake.
-2. Zuplo's edge verifies the certificate against the CA you've uploaded and
-   passes the verification result (and parsed certificate) to your gateway
-   workers.
-3. The [`mtls-auth-inbound`](../policies/mtls-auth-inbound.md) policy on your
+1. The client presents a certificate during the TLS handshake.
+2. Zuplo's edge verifies the client certificate chain against the CA
+   certificates uploaded to your account, then passes the verification result
+   and parsed client certificate to your gateway workers.
+3. The [`mtls-auth-inbound`](../policies/mtls-auth-inbound.mdx) policy on your
    route reads the verification result, enforces it, and attaches the parsed
    certificate metadata to `request.user.data.mtlsAuth` for use in your handlers
    and downstream policies.
 
 CA certificates are scoped to your Zuplo **account**, not a single project or
-deployment. Once a CA is uploaded, every gateway domain on the account will
-verify presented client certificates against it. The policy on each route
+deployment. Once a CA is uploaded, every gateway domain on the account can
+verify presented client certificate chains against it. The policy on each route
 controls whether unverified traffic is rejected or allowed through.
 
 ## Prerequisites
 
 Before you begin, you need:
 
-- A public CA certificate (PEM-encoded) that issued — or will issue — the client
-  certificates you want to accept
+- A public CA certificate (PEM-encoded) that has issued, or will issue, the
+  client certificates you want to accept, either directly or through
+  intermediate CAs
 - The [Zuplo CLI](../cli/overview.mdx) installed and authenticated
 - A Zuplo project where you can add the `mtls-auth-inbound` policy to a route
 
@@ -44,7 +50,7 @@ client certificates stay with you and your clients.
 
 :::
 
-## 1/ Upload Your CA Certificate
+## 1/ Upload your CA certificate
 
 Use the Zuplo CLI to upload your CA certificate. The CA is registered against
 your account and is automatically made available on all of your gateway domains.
@@ -79,21 +85,21 @@ CAs on the account at any time:
 zuplo ca-certificate list --account your-account
 ```
 
-See the [`ca-certificate` CLI reference](../cli/ca-certificate-create.md) for
+See the [`ca-certificate` CLI reference](../cli/ca-certificate-create.mdx) for
 all available subcommands (`create`, `list`, `describe`, `update`, `delete`).
 
 :::tip{title="Using an intermediate CA"}
 
 If your client certificates are issued by an intermediate CA (rather than
-directly by your root), upload the **intermediate** itself as the CA — not the
-root. The client certs used must be directly signed by the CA certificate you
-provide to Zuplo.
+directly by your root), upload the root CA certificate that anchors the chain.
+Clients must send the leaf certificate plus any intermediate certificates when
+they connect.
 
 :::
 
-## 2/ Add the mTLS Auth Inbound Policy
+## 2/ Add the mTLS auth inbound policy
 
-Add the [`mtls-auth-inbound`](../policies/mtls-auth-inbound.md) policy to any
+Add the [`mtls-auth-inbound`](../policies/mtls-auth-inbound.mdx) policy to any
 route that should require a verified client certificate. The policy reads the
 verification result that Zuplo's edge attached to the request and either rejects
 unverified traffic or allows it through, depending on configuration.
@@ -115,34 +121,35 @@ unverified traffic or allows it through, depending on configuration.
 
 **Key options:**
 
-- `allowUnauthenticatedRequests` (default `false`): When `false`, the policy
-  rejects requests that don't present a valid client certificate signed by a CA
-  on your account. When `true`, the policy lets traffic through but still
-  attaches certificate metadata when a parseable client certificate is present —
-  useful for staged rollouts or logging-only modes.
+- `allowUnauthenticatedRequests` (default `false`): When set to `false`, the
+  policy rejects requests that don't present a valid client certificate signed
+  by a CA on your account. When set to `true`, the policy lets traffic through
+  but still attaches certificate metadata when a parseable client certificate is
+  present, which is useful for staged rollouts or logging-only modes.
 - `certIssuerDN`: The fully qualified issuer distinguished name that the client
-  certificate must be signed by.
+  certificate must be signed by. This is the issuer DN on the client
+  certificate, which may be an intermediate CA when the client sends a chain.
 
-See the full [policy reference](../policies/mtls-auth-inbound.md) for all
+See the full [policy reference](../policies/mtls-auth-inbound.mdx) for all
 options.
 
 :::tip{title="Finding your certIssuerDN value"}
 
-The issuer DN of a client certificate is the subject DN of the CA that signed
-it. Read it directly from your CA's PEM file with `openssl`:
+The issuer DN is stored on the client certificate itself. Read it from a client
+certificate that Zuplo should accept:
 
 ```bash
-openssl x509 -in ca.pem -noout -subject -nameopt RFC2253
+openssl x509 -in client.pem -noout -issuer -nameopt RFC2253
 ```
 
-This prints something like `subject=CN=example-ca,O=Example,C=US`. Copy the part
-after `subject=` into `certIssuerDN`. The policy tolerates casing and whitespace
+This prints something like `issuer=CN=example-ca,O=Example,C=US`. Copy the part
+after `issuer=` into `certIssuerDN`. The policy tolerates casing and whitespace
 differences, but not RDN reordering, so keep the order produced by `openssl`
 as-is.
 
 :::
 
-## 3/ Read Certificate Metadata in Your Handler
+## 3/ Read certificate metadata in your handler
 
 When verification succeeds, the policy attaches parsed certificate metadata to
 `request.user.data.mtlsAuth`. If `request.user` does not already exist, the
@@ -188,7 +195,7 @@ forward it to a backend.
 
 Once your CA is uploaded and the policy is on the route, you can verify the
 end-to-end flow with `curl`. You'll need a client certificate and private key
-issued by the CA you uploaded.
+issued by, or chained to, the CA you uploaded.
 
 Send the certificate and key with `--cert` and `--key`:
 
@@ -201,11 +208,27 @@ Confirm that:
 
 - A request **without** `--cert` is rejected with `401` when
   `allowUnauthenticatedRequests` is `false`.
-- A request with a certificate signed by your uploaded CA succeeds and your
+- A request with a certificate that chains to your uploaded CA succeeds and your
   handler sees the parsed certificate on `request.user.data.mtlsAuth`.
 - A request with a certificate signed by a different CA is rejected.
 
-## Managing CA Certificates
+:::tip{title="Using client certificates as part of a certificate chain"}
+
+If your client certificates are issued by an intermediate CA (rather than
+directly by your root), pass a certificate bundle to `curl` that includes the
+leaf client certificate followed by any intermediate CA certificates. Do not
+include the root CA in the client certificate bundle.
+
+```bash
+cat client.pem intermediate.pem > client-chain.pem
+
+curl --cert ./client-chain.pem --key ./client.key \
+  https://your-gateway.zuplo.app/v1/example
+```
+
+:::
+
+## Manage CA certificates
 
 ### Listing CAs
 
@@ -270,7 +293,7 @@ the CA's subject DN, update `certIssuerDN` to match the new value before cutting
 clients over — or temporarily set `allowUnauthenticatedRequests: true` to allow
 both issuers during the transition.
 
-## Local Development
+## Local development
 
 The `mtls-auth-inbound` policy relies on verification metadata supplied by
 Zuplo's edge proxy and does not work in local development with `zuplo dev`. Test
@@ -281,7 +304,9 @@ the policy in a working-copy or preview environment.
 ### Requests are rejected with 401
 
 - Confirm the client is presenting a certificate signed by a CA that's been
-  uploaded with `zuplo ca-certificate list`.
+  uploaded with `zuplo ca-certificate list`. If the client certificate is issued
+  by an intermediate CA, confirm the client sends the intermediate certificate
+  chain.
 - If you've set `certIssuerDN`, verify it matches
   `request.user.data.mtlsAuth.issuer` exactly (casing and whitespace are
   tolerated, but RDN order is not).
@@ -306,10 +331,10 @@ that custom domain.
 If you add a custom domain later and your clients aren't being verified against
 it, contact [support@zuplo.com](mailto:support@zuplo.com).
 
-## Additional Resources
+## Additional resources
 
-- [`mtls-auth-inbound` policy reference](../policies/mtls-auth-inbound.md)
-- [`ca-certificate` CLI reference](../cli/ca-certificate-create.md)
+- [`mtls-auth-inbound` policy reference](../policies/mtls-auth-inbound.mdx)
+- [`ca-certificate` CLI reference](../cli/ca-certificate-create.mdx)
 - [Gateway to Origin mTLS Authentication](./securing-backend-mtls.mdx) — the
   reverse direction, where Zuplo authenticates to your backend with a client
   certificate

package/docs/articles/step-1-setup-basic-gateway.mdx

@@ -9,7 +9,7 @@ sidebar_label: "1 - Setup Your Gateway"
 />
 
 In this tutorial we'll set up a simple gateway. We'll use a simple origin API at
-[getting-started.zuplo.io](https://getting-started.zuplo.io).
+[echo.zuplo.io](https://echo.zuplo.io).
 
 Note - Zuplo also supports building and running your API locally. To learn more
 [see the documentation](./local-development.mdx).
@@ -78,8 +78,6 @@ Note - Zuplo also supports building and running your API locally. To learn more
    }
    ```
 
-   A secret? Let's try and find out what this API is hiding!
-
 1. Put the base URL in an **Environment Variable**
 
    When working with Zuplo, you'll eventually want each

package/docs/articles/step-2-add-rate-limiting.mdx

@@ -69,7 +69,7 @@ limiter.
    </ModalScreenshot>
 
    Your rate limiting policy is now intercepting excess requests, protecting the
-   `getting-started` API.
+   echo API.
 
 </Stepper>
 

package/docs/articles/testing.mdx

@@ -258,7 +258,7 @@ For CI/CD examples with other providers, see
 
 ## Writing tests
 
-Using Node.js 18 and the Zuplo CLI, it's very easy to write tests that make
+Using Node.js and the Zuplo CLI, it's very easy to write tests that make
 requests to your API using `fetch` and then validate expectations with `expect`
 from [chai](https://www.chaijs.com/api/bdd/).
 

package/docs/articles/troubleshooting.md

@@ -289,11 +289,15 @@ details.
 
 ### GET or HEAD requests with a body
 
-Sending a body with a `GET` or `HEAD` request results in a `GET_HEAD_BODY_ERROR`
-response. Some HTTP clients attach a body by default.
+Zuplo removes the body from any `GET` or `HEAD` request on entry and adds a
+`zp-body-removed: true` header so the backend knows the body was removed. The
+request then proceeds as normal, so the symptom is a missing body at the backend
+rather than an error response. Some HTTP clients attach a body by default.
 
 **Fix:** Remove the request body for `GET` and `HEAD` requests, or change the
-HTTP method to `POST` or `PUT` if a body is required.
+HTTP method to `POST` or `PUT` if a body is required. See
+[zp-body-removed](../programmable-api/zp-body-removed.mdx) for details,
+including an example policy that rejects these requests instead.
 
 ## Getting help
 

package/docs/articles/waf-ddos-akamai.md

@@ -24,19 +24,22 @@ your API Gateway. This is a good way to ensure that only Akamai can access your
 API Gateway. However, as Akamai is a multi-tenant service, this method isn't
 sufficient to protect unauthorized traffic from hitting your API Gateway.
 
-In Zuplo, you can utilize the IP Address Restriction policy to limit traffic to
-only the Akamai IP addresses. You don't need to provide the address list
-manually, instead you can utilize the built-in list as shown below.
+In Zuplo, you can use the custom
+[IP Restriction policy](../policies/ip-restriction-inbound.mdx) to limit traffic
+to only the Akamai IP addresses. Copy the policy code from that page into a
+module in your project (for example, `modules/ip-restriction-inbound.ts`), then
+configure the policy with the IP ranges that Akamai publishes for your account
+in Akamai Control Center.
 
 ```json
 {
   "name": "allow-akamai-only",
-  "policyType": "ip-address-restriction-inbound",
+  "policyType": "ip-restriction-inbound",
   "handler": {
-    "export": "IPAddressRestrictionInbound",
-    "module": "$import(@zuplo/runtime)",
+    "export": "default",
+    "module": "$import(./modules/ip-restriction-inbound)",
     "options": {
-      "allowedIpAddresses": ["list:akamai"]
+      "allowedIpAddresses": ["23.32.0.0/11", "104.64.0.0/10"]
     }
   }
 }
@@ -57,20 +60,36 @@ In Akamai, you can configure custom headers using the Property Manager or the
 Akamai API. Add a custom header with a secret value that only you and Akamai
 know.
 
-In Zuplo, you can utilize the Header Restriction policy to limit traffic to only
-those requests that include the custom header and secret value.
+In Zuplo, you can use a small custom code policy to limit traffic to only those
+requests that include the custom header and secret value.
+
+```ts title="modules/require-akamai-header.ts"
+import {
+  environment,
+  HttpProblems,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const headerValue = request.headers.get("x-akamai-auth");
+  if (!headerValue || headerValue !== environment.AKAMAI_SECRET_HEADER_VALUE) {
+    return HttpProblems.unauthorized(request, context);
+  }
+  return request;
+}
+```
 
 ```json
 {
   "name": "allow-akamai-custom-header",
-  "policyType": "require-header-inbound",
+  "policyType": "custom-code-inbound",
   "handler": {
-    "export": "RequireHeaderInboundPolicy",
-    "module": "$import(@zuplo/runtime)",
-    "options": {
-      "headerName": "x-akamai-auth",
-      "allowedValues": ["$env(AKAMAI_SECRET_HEADER_VALUE)"]
-    }
+    "export": "default",
+    "module": "$import(./modules/require-akamai-header)"
   }
 }
 ```

package/docs/articles/waf-ddos-aws-waf-shield.mdx

@@ -26,19 +26,22 @@ way to ensure that only CloudFront can access your API Gateway. However, as
 CloudFront is available to any AWS customer, this method isn't sufficient to
 protect unauthorized traffic from hitting your API Gateway.
 
-In Zuplo, you can utilize the IP Address Restriction policy to limit traffic to
-only the CloudFront IP addresses. You don't need to provide the address list
-manually, instead you can utilize the built-in list as shown below.
+In Zuplo, you can use the custom
+[IP Restriction policy](../policies/ip-restriction-inbound.mdx) to limit traffic
+to only the CloudFront IP addresses. Copy the policy code from that page into a
+module in your project (for example, `modules/ip-restriction-inbound.ts`), then
+configure the policy with the `CLOUDFRONT` ranges from the
+[AWS IP address ranges list](https://ip-ranges.amazonaws.com/ip-ranges.json).
 
 ```json
 {
   "name": "allow-cloudfront-only",
-  "policyType": "ip-address-restriction-inbound",
+  "policyType": "ip-restriction-inbound",
   "handler": {
-    "export": "IPAddressRestrictionInbound",
-    "module": "$import(@zuplo/runtime)",
+    "export": "default",
+    "module": "$import(./modules/ip-restriction-inbound)",
     "options": {
-      "allowedIpAddresses": ["list:aws-cloudfront"]
+      "allowedIpAddresses": ["13.32.0.0/15", "13.35.0.0/16"]
     }
   }
 }
@@ -55,20 +58,36 @@ checked by your API Gateway. This provides an additional layer of security on
 top of IP address restrictions and prevents any unauthorized traffic from
 hitting your API Gateway - regardless of the source.
 
-In Zuplo, you can utilize the Header Restriction policy to limit traffic to only
-those requests that include the custom header and secret value.
+In Zuplo, you can use a small custom code policy to limit traffic to only those
+requests that include the custom header and secret value.
+
+```ts title="modules/require-secure-header.ts"
+import {
+  environment,
+  HttpProblems,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const headerValue = request.headers.get("secure-header");
+  if (!headerValue || headerValue !== environment.MY_SECRET_HEADER_VALUE) {
+    return HttpProblems.unauthorized(request, context);
+  }
+  return request;
+}
+```
 
 ```json
 {
   "name": "allow-cloudfront-custom-header",
-  "policyType": "require-header-inbound",
+  "policyType": "custom-code-inbound",
   "handler": {
-    "export": "RequireHeaderInboundPolicy",
-    "module": "$import(@zuplo/runtime)",
-    "options": {
-      "headerName": "secure-header",
-      "allowedValues": ["$env(MY_SECRET_HEADER_VALUE)"]
-    }
+    "export": "default",
+    "module": "$import(./modules/require-secure-header)"
   }
 }
 ```

package/docs/articles/waf-ddos-fastly.mdx

@@ -27,19 +27,22 @@ your API Gateway. This is a good way to ensure that only Fastly can access your
 API Gateway. However, as Fastly is a multi-tenant service, this method isn't
 sufficient to protect unauthorized traffic from hitting your API Gateway.
 
-In Zuplo, you can utilize the IP Address Restriction policy to limit traffic to
-only the Fastly IP addresses. You don't need to provide the address list
-manually, instead you can utilize the built-in list as shown below.
+In Zuplo, you can use the custom
+[IP Restriction policy](../policies/ip-restriction-inbound.mdx) to limit traffic
+to only the Fastly IP addresses. Copy the policy code from that page into a
+module in your project (for example, `modules/ip-restriction-inbound.ts`), then
+configure the policy with the address ranges from
+[Fastly's public IP list](https://api.fastly.com/public-ip-list).
 
 ```json
 {
   "name": "allow-fastly-only",
-  "policyType": "ip-address-restriction-inbound",
+  "policyType": "ip-restriction-inbound",
   "handler": {
-    "export": "IPAddressRestrictionInbound",
-    "module": "$import(@zuplo/runtime)",
+    "export": "default",
+    "module": "$import(./modules/ip-restriction-inbound)",
     "options": {
-      "allowedIpAddresses": ["list:fastly"]
+      "allowedIpAddresses": ["151.101.0.0/16", "199.232.0.0/16"]
     }
   }
 }

package/docs/cli/deploy.mdx

@@ -124,16 +124,19 @@ zuplo deploy --project my-project --environment my-env-name
 
 ## Polling timeout
 
-By default, the deploy command will poll the status of the deployment every
-second for 150 seconds. For most deployments this is enough time for the build
-and deploy process to complete. However, if you have a large project, this may
-not be enough time. You can increase the timeout by setting the following
-environment variables.
-
-- `POLL_INTERVAL` - The interval in seconds between each poll. Default is 1
-  second.
-- `MAX_POLL_RETRIES` - The maximum number of retries before the command times
-  out. Default is 150.
+By default, the deploy command polls the status of the deployment every second
+for up to 250 attempts (a little over four minutes). For most deployments this
+is enough time for the build and deploy process to complete. However, if you
+have a large project, this may not be enough time. You can increase the timeout
+by setting the following environment variables.
+
+- `POLL_INTERVAL` - The interval in milliseconds between each poll. Default is
+  `1000` (1 second).
+- `MAX_POLL_RETRIES` - The maximum number of polls before the command times
+  out. Default is `250`.
+
+The following example polls every 5 seconds for up to 300 attempts (25
+minutes).
 
 ```bash
 POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy

package/docs/cli/deploy.partial.mdx

@@ -27,16 +27,19 @@ zuplo deploy --project my-project --environment my-env-name
 
 ## Polling timeout
 
-By default, the deploy command will poll the status of the deployment every
-second for 150 seconds. For most deployments this is enough time for the build
-and deploy process to complete. However, if you have a large project, this may
-not be enough time. You can increase the timeout by setting the following
-environment variables.
-
-- `POLL_INTERVAL` - The interval in seconds between each poll. Default is 1
-  second.
-- `MAX_POLL_RETRIES` - The maximum number of retries before the command times
-  out. Default is 150.
+By default, the deploy command polls the status of the deployment every second
+for up to 250 attempts (a little over four minutes). For most deployments this
+is enough time for the build and deploy process to complete. However, if you
+have a large project, this may not be enough time. You can increase the timeout
+by setting the following environment variables.
+
+- `POLL_INTERVAL` - The interval in milliseconds between each poll. Default is
+  `1000` (1 second).
+- `MAX_POLL_RETRIES` - The maximum number of polls before the command times
+  out. Default is `250`.
+
+The following example polls every 5 seconds for up to 300 attempts (25
+minutes).
 
 ```bash
 POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy