zuplo 6.71.10 → 6.71.11

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

@@ -88,12 +88,26 @@ zuplo ca-certificate list --account your-account
 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"}
+:::caution{title="Upload the self-signed root CA, not an intermediate"}
 
-If your client certificates are issued by an intermediate CA (rather than
-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.
+Zuplo must build a complete chain from the presented client certificate up to a
+trust anchor. Upload the **self-signed root** CA that anchors the chain — not an
+intermediate or subordinate CA. Uploading a subordinate CA is the most common
+cause of the `FAILED to get issuer certificate` error (see
+[Troubleshooting](#failed-to-get-issuer-certificate)).
+
+To confirm a certificate is a self-signed root, check that its subject and
+issuer are identical:
+
+```bash
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+If `subject` and `issuer` match, it's a root. If they differ, the file is an
+intermediate CA — trace the chain to the root and upload that instead. When your
+client certificates are issued by an intermediate CA, clients still send the
+leaf certificate plus any intermediates when they connect (see
+[Test with curl](#4-test-with-curl)).
 
 :::
 
@@ -315,11 +329,73 @@ the policy in a working-copy or preview environment.
   `context.incomingRequestProperties.clientMtlsVerificationReason` to see why
   verification failed.
 
+### `FAILED to get issuer certificate`
+
+This error means Zuplo can't build a complete chain from the presented client
+certificate up to a trusted root. The usual cause is uploading an **intermediate
+or subordinate CA** instead of the **self-signed root** CA that anchors the
+chain.
+
+Confirm what you uploaded. A self-signed root has an identical subject and
+issuer:
+
+```bash
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+If `subject` and `issuer` differ, the file is an intermediate CA. Find the root
+that anchors the chain and re-upload it:
+
+```bash
+# Remove the incorrect CA
+zuplo ca-certificate delete --cert-id mtlsca_abc123 --account your-account
+
+# Upload the self-signed root instead
+zuplo ca-certificate create --name my_ca --cert ./root-ca.pem --account your-account
+```
+
+If your CA is an Active Directory Certificate Services (AD CS) deployment,
+export the issuing CA's own certificate and inspect it:
+
+```bash
+# Export the CA certificate (often DER-encoded)
+certutil -ca.cert ca.cer
+
+# Convert DER to the PEM format Zuplo requires
+openssl x509 -inform der -in ca.cer -out ca.pem
+
+# Verify subject == issuer (a root); if not, export the root above it instead
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+### `client certificate metadata not provided`
+
+The certificate verified at the edge, but the parsed certificate wasn't
+forwarded to your gateway workers, so `request.user.data.mtlsAuth` is empty even
+though the request was authenticated.
+
+The most common cause is an **oversized leaf client certificate**. Zuplo's edge
+can only forward client certificates up to roughly 10 KB of DER-encoded data.
+Certificates with large RSA keys, many Subject Alternative Names, or large
+custom extensions can exceed this. Check the DER size of the leaf certificate:
+
+```bash
+openssl x509 -in client.pem -outform der | wc -c
+```
+
+If the result is near or above ~10,000 bytes, reissue a smaller leaf
+certificate. Trim unnecessary extensions and SANs, or switch to ECDSA keys
+instead of large (4096-bit) RSA keys. This limit applies to the **leaf**
+certificate the edge forwards, not the full chain.
+
 ### `request.user.data.mtlsAuth` is missing
 
 - The policy only attaches metadata when a parseable client certificate is
   present on the request. Confirm the client is sending one.
 - Verify the route includes the `mtls-auth-inbound` policy.
+- If the certificate verifies but metadata is still missing, check the leaf
+  certificate size (see
+  [`client certificate metadata not provided`](#client-certificate-metadata-not-provided)).
 
 ### Custom domains
 
@@ -331,6 +407,27 @@ 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).
 
+### Custom domains behind your own CDN
+
+Inbound mTLS requires the TLS handshake to terminate at Zuplo's edge, because
+that's where the client certificate is verified and parsed. If you front your
+Zuplo gateway with **your own CDN** (for example, your own Cloudflare zone) that
+terminates TLS before traffic reaches Zuplo, the handshake — and the client
+certificate — ends at your CDN. Zuplo never sees the certificate, so the
+`mtls-auth-inbound` policy has nothing to verify.
+
+You have two supported options:
+
+- **Let Zuplo terminate TLS.** Point clients at a Zuplo-managed gateway domain,
+  or configure your custom domain directly on Zuplo so Zuplo terminates TLS. The
+  client certificate then reaches Zuplo's edge and inbound mTLS works as
+  documented above.
+- **Verify mTLS at your CDN.** If you must keep your own CDN in front, terminate
+  and verify the client certificate at the CDN, then forward the verified
+  identity to Zuplo in a request header. Validate that header in a Zuplo policy
+  instead of relying on `mtls-auth-inbound`. Make sure the header can't be
+  spoofed by clients that bypass your CDN.
+
 ## Additional resources
 
 - [`mtls-auth-inbound` policy reference](../policies/mtls-auth-inbound.mdx)

package/docs/guides/transform-route-params-url-rewrite.mdx

@@ -0,0 +1,307 @@
+---
+title: Transform Route Parameters for URL Rewrite
+sidebar_label: Transform Route Parameters
+description:
+  Learn how to use an inbound policy to transform route parameter values before
+  the URL Rewrite handler forwards the request to your backend.
+tags:
+  - custom-code
+  - backends
+---
+
+This guide explains how to transform incoming route parameter values in an
+inbound policy before the [URL Rewrite handler](../handlers/url-rewrite.mdx)
+uses them to build the upstream URL. This pattern is useful when your public API
+paths use different naming conventions than your internal backend.
+
+## Overview
+
+When you use the URL Rewrite handler, it builds the upstream URL by
+interpolating values like `${params.resourceType}` directly from the incoming
+route parameters. Sometimes, however, you need to **change** those values before
+the rewrite happens. Common scenarios include:
+
+- **Value mapping** — translating a public-facing parameter like `order` to an
+  internal value like `customerorder`
+- **Case normalization** — converting `Products` to `products` before forwarding
+- **Path translation** — mapping user-friendly slugs to internal identifiers
+
+The recommended approach is to read the route parameters in an inbound policy,
+transform them, store the results on
+[`context.custom`](../programmable-api/zuplo-context.mdx), and reference the
+transformed values in the URL Rewrite pattern.
+
+## Step-by-Step Example
+
+The solution has three parts: an **inbound policy** that reads `request.params`
+and stores transformed values on `context.custom`, a **URL Rewrite handler**
+that references those values using `${context.custom.*}` in the
+`rewritePattern`, and **route configuration** that wires the two together.
+
+Imagine your public API exposes a route like `/api/:resourceType/:resourceId`,
+but your backend expects the resource type to be prefixed with `customer`. A
+request to `/api/order/123` should be forwarded to
+`https://backend.example.com/api/customerorder/123`.
+
+### 1. Write the Inbound Policy
+
+Create a custom inbound policy that reads the route parameters, transforms the
+values, and stores them on `context.custom`:
+
+```ts title="modules/transform-params.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Read the original route parameter
+  const resourceType = request.params.resourceType;
+
+  // Transform the value — prefix with "customer"
+  const transformedResourceType = `customer${resourceType}`;
+
+  // Store the transformed value on context.custom
+  context.custom.transformedResourceType = transformedResourceType;
+
+  context.log.info({
+    message: "Transformed route parameter",
+    original: resourceType,
+    transformed: transformedResourceType,
+  });
+
+  return request;
+}
+```
+
+### 2. Register the Policy
+
+Add the policy to `config/policies.json`:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "transform-params",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/transform-params)"
+      }
+    }
+  ]
+}
+```
+
+### 3. Configure the Route
+
+Define the route in `config/routes.oas.json` with the inbound policy and a URL
+Rewrite handler that references `context.custom`:
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/api/{resourceType}/{resourceId}": {
+      "x-zuplo-path": {
+        "pathMode": "open-api"
+      },
+      "get": {
+        "summary": "Get resource by type and ID",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "urlRewriteHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "rewritePattern": "https://backend.example.com/api/${context.custom.transformedResourceType}/${params.resourceId}"
+            }
+          },
+          "policies": {
+            "inbound": ["transform-params"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+With this configuration, a request to `/api/order/123` flows through the
+pipeline as follows:
+
+1. The route matches with `params.resourceType = "order"` and
+   `params.resourceId = "123"`
+2. The `transform-params` inbound policy runs and sets
+   `context.custom.transformedResourceType = "customerorder"`
+3. The URL Rewrite handler builds the upstream URL:
+   `https://backend.example.com/api/customerorder/123`
+
+## Common Pitfall: Modifying `request.params` Directly
+
+:::caution
+
+Do not try to transform route parameters by constructing a new `ZuploRequest`
+with modified `params` and expecting the URL Rewrite handler to pick them up.
+
+:::
+
+A common first attempt is to create a new
+[`ZuploRequest`](../programmable-api/zuplo-request.mdx) with different `params`:
+
+```ts
+// ⚠️ This approach does NOT work as expected with URL Rewrite
+const newRequest = new ZuploRequest(request, {
+  params: {
+    ...request.params,
+    resourceType: "customerorder",
+  },
+});
+return newRequest;
+```
+
+In practice, the URL Rewrite handler evaluates `${params.*}` against the
+route-level parameters rather than the request object returned by a policy. This
+means the rewritten URL may contain `undefined` segments instead of your
+transformed values. Use `context.custom` for reliable interpolation of
+transformed values — the URL Rewrite handler's `rewritePattern` fully supports
+`${context.custom.*}`, and values set in an inbound policy are available when
+the handler runs.
+
+## Variations
+
+### Using a Lookup Map
+
+For more complex mappings where the transformation is not a simple string
+operation, use a lookup object:
+
+```ts title="modules/transform-params-map.ts"
+import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";
+
+// Map public resource types to internal names
+const RESOURCE_TYPE_MAP: Record<string, string> = {
+  order: "customerorder",
+  invoice: "billing-invoice",
+  profile: "user-profile",
+  subscription: "recurring-plan",
+};
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  const resourceType = request.params.resourceType;
+  const mappedType = RESOURCE_TYPE_MAP[resourceType];
+
+  if (!mappedType) {
+    return HttpProblems.notFound(request, context, {
+      detail: `Unknown resource type: ${resourceType}`,
+    });
+  }
+
+  context.custom.transformedResourceType = mappedType;
+
+  return request;
+}
+```
+
+### Transforming Multiple Parameters
+
+You can transform any number of route parameters and store each on
+`context.custom`. Reference them individually in the rewrite pattern:
+
+```ts title="modules/transform-multiple-params.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Normalize casing
+  context.custom.version = request.params.version?.toLowerCase();
+
+  // Map resource type
+  context.custom.resource =
+    request.params.resource === "users" ? "customers" : request.params.resource;
+
+  return request;
+}
+```
+
+Then use both values in the rewrite pattern:
+
+```json
+{
+  "rewritePattern": "https://backend.example.com/${context.custom.version}/${context.custom.resource}/${params.id}"
+}
+```
+
+### Combining with Body Transformation
+
+If your API also needs to transform values in the request body alongside route
+parameters, you can handle both in the same inbound policy. Create a new
+`ZuploRequest` with a modified body while storing the route parameter
+transformations on `context.custom`:
+
+```ts title="modules/transform-params-and-body.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Transform route parameter
+  context.custom.transformedResourceType = `customer${request.params.resourceType}`;
+
+  // Transform the request body if present
+  if (request.headers.get("content-type")?.includes("application/json")) {
+    const body = await request.json();
+
+    // Map fields in the body to match the backend schema
+    const transformedBody = {
+      ...body,
+      type: context.custom.transformedResourceType,
+    };
+
+    // Return a new request with the modified body
+    return new ZuploRequest(request, {
+      body: JSON.stringify(transformedBody),
+    });
+  }
+
+  return request;
+}
+```
+
+## Best Practices
+
+- **Use descriptive keys on `context.custom`** — names like
+  `context.custom.transformedResourceType` are easier to debug than generic keys
+  like `context.custom.value`
+- **Log transformations** — use `context.log` to record original and transformed
+  values so you can trace issues in production
+- **Validate before transforming** — return an appropriate error response (using
+  [`HttpProblems`](../programmable-api/http-problems.mdx)) if a parameter value
+  is unexpected, rather than forwarding bad data to your backend
+- **Keep the policy focused** — if your transformation logic is complex,
+  consider splitting it into a separate utility module imported by the policy
+
+## Next Steps
+
+- [URL Rewrite Handler](../handlers/url-rewrite.mdx) — full reference for
+  rewrite patterns and available interpolation variables
+- [Custom Code Patterns](../articles/custom-code-patterns.md) — common patterns
+  for writing inbound policies, outbound policies, and handlers
+- [ZuploContext](../programmable-api/zuplo-context.mdx) — reference for
+  `context.custom` and other context properties
+- [ZuploRequest](../programmable-api/zuplo-request.mdx) — reference for
+  `request.params` and constructing new requests
+- [User-Based Backend Routing](./user-based-backend-routing.mdx) — a related
+  pattern using `context.custom` with URL Rewrite for routing by user identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.10",
+  "version": "6.71.11",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.10",
-    "@zuplo/core": "6.71.10",
-    "@zuplo/runtime": "6.71.10",
+    "@zuplo/cli": "6.71.11",
+    "@zuplo/core": "6.71.11",
+    "@zuplo/runtime": "6.71.11",
     "@zuplo/test": "1.4.0"
   }
 }