zuplo 6.73.31 → 6.74.2

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/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.2",
   "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.2",
+    "@zuplo/core": "6.74.2",
+    "@zuplo/runtime": "6.74.2",
     "@zuplo/test": "1.4.4"
   }
 }