zuplo 6.73.31 → 6.74.6

package/docs/articles/check-ip-address.mdx

@@ -2,16 +2,175 @@
 title: How to check an incoming IP address
 sidebar_label: "Check IP Address"
 description:
-  Learn how to access the true client IP address of requests using the
-  true-client-ip header.
+  Read the client IP address of an incoming request, and understand when that
+  address can be trusted on each deployment type.
 tags:
   - request-handling
   - deployment
 ---
 
-Sometimes you want to access the true IP address of the gateway's client making
-the current request. To do this you can read the `true-client-ip` header:
+To get the IP address of the client that made the current request, read it from
+the request context:
 
 ```ts
-const ip = request.headers.get("true-client-ip");
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const ip = context.incomingRequestProperties.ip;
+  return new Response(ip ?? "unknown");
+}
 ```
+
+This is the official way to read the client IP. Zuplo resolves the address from
+the layer in front of your gateway, so you get the same property regardless of
+where the gateway runs.
+
+## Handle an unknown address
+
+The value is `undefined` when nothing identified the caller. Handle that case
+explicitly:
+
+```ts
+const ip = context.incomingRequestProperties.ip;
+if (!ip) {
+  return HttpProblems.badRequest(request, context, {
+    detail: "Could not determine the client IP address",
+  });
+}
+```
+
+Don't substitute a placeholder such as `"unknown"` or `0.0.0.0` and then key on
+it. Every unidentified caller collapses into that single value, so a rate limit
+keyed on it throttles them as one client, and an allow list keyed on it either
+admits all of them or none.
+
+## When the address can be trusted
+
+An IP address is only as trustworthy as the layer that determined it. Zuplo
+reports an address only where that layer establishes it, so the value is either
+trustworthy or `undefined` — never one the caller chose.
+
+| Deployment        | Determined by                         | Trustworthy                              |
+| ----------------- | ------------------------------------- | ---------------------------------------- |
+| Zuplo Cloud       | The Zuplo edge                        | Yes                                      |
+| Zuplo Dedicated   | Your environment, configured by Zuplo | Yes                                      |
+| Self-hosted       | The proxy you run                     | Only if that proxy overwrites the header |
+| Local development | Nothing — the caller is loopback      | Reports `127.0.0.1`                      |
+
+Zuplo Cloud and Zuplo Dedicated need no configuration. Self-hosted deployments
+depend on the proxy you run, covered in
+[Self-hosted deployments](#self-hosted-deployments).
+
+:::caution
+
+Don't read an IP header from `request.headers` yourself. Which header carries
+the caller's address depends on where the gateway runs, so a header that holds
+it on one deployment may be absent on another — or may hold whatever the caller
+put there. Use `context.incomingRequestProperties.ip`, which resolves the right
+one for the deployment.
+
+:::
+
+## The `x-forwarded-for` header
+
+`x-forwarded-for` carries a client address through a chain of proxies. Each
+proxy appends the address it received the request from, producing a list:
+
+```
+X-Forwarded-For: 203.0.113.7, 198.51.100.4
+```
+
+The header reaches your code and your backend unchanged, so you can read it
+directly:
+
+```ts
+const chain = (request.headers.get("x-forwarded-for") ?? "")
+  .split(",")
+  .map((entry) => entry.trim())
+  .filter(Boolean);
+```
+
+To use it correctly, understand what the list contains. A caller can send an
+`X-Forwarded-For` of its own, and every proxy after that appends to whatever
+arrived. So the front of the list is whatever the caller wrote, and only entries
+added by a hop you operate mean anything.
+
+That leads to a few rules:
+
+- Count positions from the **end**. The last entry was added by the hop nearest
+  your gateway; the first came from the caller.
+- Decide in advance how many hops you operate, and ignore anything beyond them.
+  A caller can pad the front with as many entries as it likes.
+- Don't search the list for an address you recognize — a caller can put one
+  there.
+- Expect IPv6 entries, which may be bracketed and carry a port, such as
+  `[2001:db8::1]:8080`.
+
+:::danger
+
+An address is only as reliable as the hop that established it. If you key a rate
+limit on a value the caller can choose, they escape the limit by rotating it.
+The same value in an allow list can be used to impersonate an allowed client,
+and in an audit record it produces entries that didn't happen.
+
+:::
+
+If you only need the caller's address, `context.incomingRequestProperties.ip`
+already gives it to you without any of this.
+
+## Running your own CDN or proxy in front of Zuplo
+
+If your own CDN, load balancer, or WAF sits in front of your gateway, then that
+hop — not the end user — is the client Zuplo sees.
+`incomingRequestProperties.ip` returns its address.
+
+To identify the end user, have your CDN write the address into a header of your
+own and read that header in your code:
+
+```ts
+const endUserIp = request.headers.get("x-acme-client-ip");
+```
+
+This works only if your CDN **overwrites** that header on every request. If it
+merely adds the header when absent, a caller can supply their own value and it
+passes straight through to your code.
+
+## Zuplo Dedicated
+
+Zuplo configures your Dedicated environment to determine the client address, so
+there's nothing for you to set up. `context.incomingRequestProperties.ip`
+returns the caller's address the same way it does on Zuplo Cloud.
+
+Dedicated environments aren't identical to one another — they differ by cloud,
+region, and what sits in front of the gateway, such as a CDN or WAF you already
+operate. If you need to know exactly how the address is determined for your
+environment, or you're adding a network layer in front of it, contact your
+account team or [support](mailto:support@zuplo.com). Adding a hop in front of
+the gateway changes which address the gateway sees, as described in
+[Running your own CDN or proxy in front of Zuplo](#running-your-own-cdn-or-proxy-in-front-of-zuplo).
+
+## Self-hosted deployments
+
+On a self-hosted deployment you run the proxy in front of the gateway, so
+determining the client address is yours to configure. The gateway reads it from
+the `x-real-ip` request header.
+
+Your proxy must **overwrite** that header rather than pass one through. If a
+client-supplied `x-real-ip` reaches the gateway untouched, any caller can choose
+its own address by sending it. NGINX's `real_ip` module does this correctly by
+default. Confirm the behavior against your own configuration before relying on
+the address for anything security-sensitive.
+
+:::warning
+
+A gateway reachable directly, with no proxy in front of it, has nothing
+determining the client address. Don't expose a self-hosted gateway to the
+internet directly if you rely on the client IP.
+
+:::
+
+## Geolocation
+
+To act on where a caller is rather than their address,
+`incomingRequestProperties` already carries resolved geolocation — `country`,
+`city`, `region`, `latitude`, `longitude`, `asn`, and more. There's no need to
+geolocate the IP address yourself. See
+[ZuploContext](../programmable-api/zuplo-context.mdx#incomingrequestproperties).

package/docs/articles/monetization/quickstart.md

@@ -301,7 +301,7 @@ Next, you need to apply the Monetization policy to some or all of your routes.
 1. Click on the three-dot menu on the **monetization-inbound** policy.
 2. Select **Apply Policy**.
 3. Choose individual routes that you want to count towards the metered requests,
-   or click **Select All** to add the policy to every route in the project.
+   or click **Select all** to add the policy to every route in the project.
 
 ![Adding the policy to add routes](../../../public/media/monetization/policy-add-routes.png)
 

package/docs/mcp-gateway/how-to/connect-upstream-api-key.mdx

@@ -40,15 +40,15 @@ Virtual Server**, with these choices:
    **Path** you want to expose on your gateway.
 2. **Inbound Auth**: pick whatever your clients should authenticate with. OAuth
    through an identity provider works exactly as it does for OAuth upstreams.
-3. **Tools**: choose **Passthrough** or **Curate** as usual.
-4. **Outbound Auth**: choose **None**, then set the inbound `Authorization`
-   header handling to **Remove auth token**. The upstream doesn't use OAuth, so
-   the gateway shouldn't run a token exchange, and the inbound client's token
-   must be stripped before forwarding so it doesn't leak to the upstream.
+3. **Tools**: choose **Filter & curate** or **Passthrough** as usual.
+4. **Outbound Auth**: choose **None**, then turn on **Remove inbound
+   Authorization header**. The upstream doesn't use OAuth, so the gateway
+   shouldn't run a token exchange, and the inbound client's token must be
+   stripped before forwarding so it doesn't leak to the upstream.
 
 <ModalScreenshot size="md">
 
-![Outbound auth set to None with Remove auth token selected](../../../public/media/mcp-gateway-upstream-api-key/01-outbound-auth-none.png)
+![Outbound auth set to None with the inbound Authorization header removed](../../../public/media/mcp-gateway-upstream-api-key/01-outbound-auth-none.png)
 
 </ModalScreenshot>
 

package/docs/mcp-gateway/how-to/curate-tools.mdx

@@ -14,8 +14,8 @@ description:
 
 When an upstream MCP server exposes more capabilities than belong in front of an
 AI client, curate the subset that passes through. In the Portal, the **MCP
-Gateway Virtual Server** wizard does this on its **Tools** step: choose
-**Curate** instead of **Passthrough** and pick exactly what to expose. The
+Gateway Virtual Server** wizard does this on its **Tools** step: choose **Filter
+& curate** instead of **Passthrough** and pick exactly what to expose. The
 wizard writes an `mcp-capability-filter-inbound` policy and attaches it to the
 route for you.
 
@@ -47,7 +47,7 @@ For a full walkthrough of creating one, see the
 
    <ModalScreenshot size="md">
 
-   ![Choose Passthrough or Curate on the Tools step](../../../public/media/mcp-gateway-quickstart/04-tools.png)
+   ![Choose Filter & curate or Passthrough on the Tools step](../../../public/media/mcp-gateway-quickstart/04-tools.png)
 
    </ModalScreenshot>
 

package/docs/mcp-gateway/quickstart.mdx

@@ -103,15 +103,15 @@ result on your machine.
    server exposes to its clients:
    - **Passthrough** federates the upstream's catalog live. Zero config, and the
      safest default. Everything the upstream offers is exposed.
-   - **Curate** lets you pick specific tools, prompts, and resources. Use this
-     to control what users can do. For example, drop all destructive tools and
-     expose only read and write tools.
+   - **Filter & curate** lets you pick specific tools, prompts, and resources.
+     Use this to control what users can do. For example, drop all destructive
+     tools and expose only read and write tools.
 
    Choose **Passthrough** and click **Next**.
 
    <ModalScreenshot size="md">
 
-   ![Choose Passthrough or Curate for the exposed catalog](../../public/media/mcp-gateway-quickstart/04-tools.png)
+   ![Choose Filter & curate or Passthrough for the exposed catalog](../../public/media/mcp-gateway-quickstart/04-tools.png)
 
    </ModalScreenshot>
 

package/docs/programmable-api/zuplo-context.mdx

@@ -48,9 +48,15 @@ const elapsed = Date.now() - context.custom.startTime;
 
 ### `incomingRequestProperties`
 
-Information about the incoming request such as geolocation data. This is a
-read-only object with the following properties:
-
+Information about the incoming request such as the client IP address and
+geolocation data. This is a read-only object with the following properties:
+
+- `ip` - The IP address of the client that made the request, for example,
+  "203.0.113.7". This is the only supported way to read the client IP; don't
+  read an IP header from `request.headers` yourself. The value is `undefined`
+  when nothing identified the caller. See
+  [how to check an incoming IP address](../articles/check-ip-address.mdx) for
+  when the address can be trusted on each deployment type.
 - `asn` - ASN of the incoming request, for example, 395747.
 - `asOrganization` - The organization which owns the ASN of the incoming
   request, for example, Google Cloud.

package/package.json

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