hono-ip 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# hono-ip
+
+A tiny, fast middleware for [Hono](https://hono.dev) that figures out your client's real IP address - even when your app sits behind proxies, load balancers, or CDNs.
+
+Works on **Node.js** and **Bun** out of the box. No regex. No dependencies.
+
+## Why?
+
+Getting the "real" client IP in a web app is surprisingly annoying. Your server sees the proxy's address, not the user's. Different infrastructure stacks stuff the original IP into different headers - Cloudflare uses `CF-Connecting-IP`, AWS might use `X-Forwarded-For`, Fastly has its own thing, and so on.
+
+This middleware checks all the common headers in a sensible order, validates every candidate with native `net.isIP` and hands you back a single, trustworthy string.
+
+## Quick start
+
+```bash
+npm install hono-ip
+```
+
+```ts
+import { Hono } from "hono";
+import { ipMiddleware } from "hono-ip";
+
+const app = new Hono();
+
+app.use(ipMiddleware());
+
+app.get("/", (c) => {
+  const ip = c.get("ip"); // string | null
+  return c.text(`Hello, ${ip ?? "stranger"}`);
+});
+```
+
+That's it. Every route after the middleware can read `c.get("ip")` or `c.var.ip`.
+
+## Going deeper
+
+### Trusted proxies
+
+By default, the middleware returns the **leftmost** IP from `X-Forwarded-For` - the classic approach. The problem is that a malicious client can prepend whatever they want to that header:
+
+```
+X-Forwarded-For: 6.6.6.6, <actual client>, <your proxy>
+                 ↑ attacker injected this
+```
+
+If you know your proxy IPs, pass them in. The middleware will then walk `X-Forwarded-For` **from the right**, skipping trusted addresses, and return the first IP it doesn't recognise - which is the real client:
+
+```ts
+app.use(
+  ipMiddleware({
+    trustedProxies: new Set(["10.0.0.1", "10.0.0.2"]),
+  })
+);
+```
+
+### Runtime-level connection info
+
+Headers can be spoofed. The one thing that _can't_ be faked is the TCP connection's remote address, which Hono exposes through its `getConnInfo` helper. Pass it in to use it as a final fallback:
+
+```ts
+// Bun
+import { getConnInfo } from "hono/bun";
+
+// Node.js
+// import { getConnInfo } from "@hono/node-server/conninfo";
+
+app.use(ipMiddleware({ getConnInfo }));
+```
+
+When no header yields a valid IP, the middleware will call `getConnInfo(c).remote.address` and use that instead. If `getConnInfo` throws (e.g. during tests where there's no real server), it's caught silently.
+
+### Using `getClientIp` directly
+
+You don't have to use the middleware. The core function is exported on its own:
+
+```ts
+import { getClientIp } from "hono-ip";
+
+app.get("/ip", (c) => {
+  const ip = getClientIp(c, {
+    trustedProxies: new Set(["10.0.0.1"]),
+  });
+  return c.json({ ip });
+});
+```
+
+### Custom context variable name
+
+If `"ip"` collides with something in your app:
+
+```ts
+app.use(ipMiddleware({ attributeName: "clientIp" }));
+
+// later
+c.get("clientIp");
+```
+
+## Resolution order
+
+The middleware checks these sources top-to-bottom and returns the first valid IP it finds:
+
+| Priority | Source | Notes |
+|----------|--------|-------|
+| 1 | `X-Client-IP` | Set by some proxies and load balancers |
+| 2 | `X-Forwarded-For` | Leftmost valid IP, or rightmost untrusted if `trustedProxies` is set |
+| 3 | `CF-Connecting-IP` | Cloudflare |
+| 4 | `Fastly-Client-Ip` | Fastly |
+| 5 | `True-Client-Ip` | Akamai, Cloudflare enterprise |
+| 6 | `X-Real-IP` | Nginx default config |
+| 7 | `X-Cluster-Client-IP` | Rackspace, Riverbed |
+| 8 | `X-Forwarded` | Non-standard single-IP variant |
+| 9 | `Forwarded-For` | Non-standard single-IP variant |
+| 10 | `Forwarded` | RFC 7239 - parses `for="..."` value, handles bracketed IPv6 |
+| 11 | `X-Appengine-User-Ip` | Google App Engine |
+| 12 | `getConnInfo()` | Hono runtime adapter (Bun / Node / CF Workers / Deno / …) |
+| 13 | `Cf-Pseudo-IPv4` | Cloudflare pseudo IPv4 for IPv6 visitors |
+
+## License
+Apache-2.0

package/dist/index.js

@@ -0,0 +1,4 @@
+import{createMiddleware as U}from"hono/factory";import{isIp as T,getFirstFromXForwardedFor as V,parseForwarded as W}from"./ip";import{isIp as v,isIpV4 as y,isIpV6 as D,extractIp as H,getFirstFromXForwardedFor as M,parseForwarded as R}from"./ip";var Y=["x-client-ip","cf-connecting-ip","fastly-client-ip","true-client-ip","x-real-ip","x-cluster-client-ip"],Z=["x-appengine-user-ip","cf-pseudo-ipv4"];function J(b,u){let q=b.req.header(u);if(!q)return null;let z=q.trim();return T(z)?z:null}function $(b,u){let q=J(b,"x-client-ip");if(q)return q;let z=V(b.req.header("x-forwarded-for"),u);if(z)return z;for(let G of Y){if(G==="x-client-ip")continue;let j=J(b,G);if(j)return j}let N=J(b,"x-forwarded");if(N)return N;let O=J(b,"forwarded-for");if(O)return O;let Q=W(b.req.header("forwarded"));if(Q)return Q;for(let G of Z){let j=J(b,G);if(j)return j}if(u?.getConnInfo)try{let j=u.getConnInfo(b)?.remote?.address;if(j&&T(j))return j}catch{}return console.log("No IP found"),null}function P(b={}){let u=b.attributeName??"ip";return U(async(q,z)=>{q.set(u,$(q,b)),await z()})}export{R as parseForwarded,D as isIpV6,y as isIpV4,v as isIp,P as ipMiddleware,M as getFirstFromXForwardedFor,$ as getClientIp,H as extractIp};
+
+//# debugId=5CD5D6EBA955279864756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["..\\src\\index.ts"],
+  "sourcesContent": [
+    "import { createMiddleware } from \"hono/factory\";\nimport type { Context } from \"hono\";\nimport {\n  isIp,\n  extractIp,\n  getFirstFromXForwardedFor,\n  parseForwarded,\n  type XffOptions,\n} from \"./ip\";\n\ndeclare module \"hono\" {\n  interface ContextVariableMap {\n    ip: string | null;\n  }\n}\n\n// ──────────────────────────────────────────────\n// Header priority (same order as request-ip):\n//   1. X-Client-IP\n//   2. X-Forwarded-For  (leftmost valid, or rightmost untrusted)\n//   3. CF-Connecting-IP\n//   4. Fastly-Client-Ip\n//   5. True-Client-Ip\n//   6. X-Real-IP\n//   7. X-Cluster-Client-IP\n//   8. X-Forwarded / Forwarded-For / Forwarded (RFC 7239)\n//   9. X-Appengine-User-Ip\n//  10. Hono getConnInfo  (Bun / Node / CF Workers / …)\n//  11. Cf-Pseudo-IPv4\n// ──────────────────────────────────────────────\n\nconst SIMPLE_HEADERS = [\n  \"x-client-ip\",\n  \"cf-connecting-ip\",\n  \"fastly-client-ip\",\n  \"true-client-ip\",\n  \"x-real-ip\",\n  \"x-cluster-client-ip\",\n] as const;\n\nconst FALLBACK_HEADERS = [\n  \"x-appengine-user-ip\",\n  \"cf-pseudo-ipv4\",\n] as const;\n\nfunction headerIp(c: Context, name: string): string | null {\n  const v = c.req.header(name);\n  if (!v) return null;\n  const ip = v.trim();\n  return isIp(ip) ? ip : null;\n}\n\nexport interface IpMiddlewareOptions extends XffOptions {\n  attributeName?: string;\n\n  getConnInfo?: (c: Context) => { remote: { address?: string } };\n}\n\nexport function getClientIp(c: Context, opts?: IpMiddlewareOptions): string | null {\n  const xClientIp = headerIp(c, \"x-client-ip\");\n  if (xClientIp) return xClientIp;\n\n  const xff = getFirstFromXForwardedFor(c.req.header(\"x-forwarded-for\"), opts);\n  if (xff) return xff;\n\n  for (const name of SIMPLE_HEADERS) {\n    if (name === \"x-client-ip\") continue;\n    const ip = headerIp(c, name);\n    if (ip) return ip;\n  }\n\n  const xForwarded = headerIp(c, \"x-forwarded\");\n  if (xForwarded) return xForwarded;\n\n  const forwardedFor = headerIp(c, \"forwarded-for\");\n  if (forwardedFor) return forwardedFor;\n\n  const forwarded = parseForwarded(c.req.header(\"forwarded\"));\n  if (forwarded) return forwarded;\n\n  for (const name of FALLBACK_HEADERS) {\n    const ip = headerIp(c, name);\n    if (ip) return ip;\n  }\n\n  if (opts?.getConnInfo) {\n    try {\n      const info = opts.getConnInfo(c);\n      const addr = info?.remote?.address;\n      if (addr && isIp(addr)) return addr;\n    } catch {}\n  }\n\n  console.log(\"No IP found\");\n  return null;\n}\n\nexport function ipMiddleware(opts: IpMiddlewareOptions = {}) {\n  const key = (opts.attributeName ?? \"ip\") as \"ip\";\n\n  return createMiddleware(async (c, next) => {\n    c.set(key, getClientIp(c, opts));\n    await next();\n  });\n}\n\nexport { isIp, isIpV4, isIpV6, extractIp, getFirstFromXForwardedFor, parseForwarded } from \"./ip\";"
+  ],
+  "mappings": "AAAA,2BAAS,qBAET,eACE,+BAEA,oBACA,aAoGF,eAAS,YAAM,YAAQ,eAAQ,+BAAW,oBAA2B,aA3ErE,IAAM,EAAiB,CACrB,cACA,mBACA,mBACA,iBACA,YACA,qBACF,EAEM,EAAmB,CACvB,sBACA,gBACF,EAEA,SAAS,CAAQ,CAAC,EAAY,EAA6B,CACzD,IAAM,EAAI,EAAE,IAAI,OAAO,CAAI,EAC3B,GAAI,CAAC,EAAG,OAAO,KACf,IAAM,EAAK,EAAE,KAAK,EAClB,OAAO,EAAK,CAAE,EAAI,EAAK,KASlB,SAAS,CAAW,CAAC,EAAY,EAA2C,CACjF,IAAM,EAAY,EAAS,EAAG,aAAa,EAC3C,GAAI,EAAW,OAAO,EAEtB,IAAM,EAAM,EAA0B,EAAE,IAAI,OAAO,iBAAiB,EAAG,CAAI,EAC3E,GAAI,EAAK,OAAO,EAEhB,QAAW,KAAQ,EAAgB,CACjC,GAAI,IAAS,cAAe,SAC5B,IAAM,EAAK,EAAS,EAAG,CAAI,EAC3B,GAAI,EAAI,OAAO,EAGjB,IAAM,EAAa,EAAS,EAAG,aAAa,EAC5C,GAAI,EAAY,OAAO,EAEvB,IAAM,EAAe,EAAS,EAAG,eAAe,EAChD,GAAI,EAAc,OAAO,EAEzB,IAAM,EAAY,EAAe,EAAE,IAAI,OAAO,WAAW,CAAC,EAC1D,GAAI,EAAW,OAAO,EAEtB,QAAW,KAAQ,EAAkB,CACnC,IAAM,EAAK,EAAS,EAAG,CAAI,EAC3B,GAAI,EAAI,OAAO,EAGjB,GAAI,GAAM,YACR,GAAI,CAEF,IAAM,EADO,EAAK,YAAY,CAAC,GACZ,QAAQ,QAC3B,GAAI,GAAQ,EAAK,CAAI,EAAG,OAAO,EAC/B,KAAM,EAIV,OADA,QAAQ,IAAI,aAAa,EAClB,KAGF,SAAS,CAAY,CAAC,EAA4B,CAAC,EAAG,CAC3D,IAAM,EAAO,EAAK,eAAiB,KAEnC,OAAO,EAAiB,MAAO,EAAG,IAAS,CACzC,EAAE,IAAI,EAAK,EAAY,EAAG,CAAI,CAAC,EAC/B,MAAM,EAAK,EACZ",
+  "debugId": "5CD5D6EBA955279864756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "hono-ip",
+  "version": "1.0.0",
+  "description": "A tiny, fast middleware for Hono that figures out your client's real IP address - even when your app sits behind proxies, load balancers, or CDNs.",
+  "keywords": [
+    "hono",
+    "ip",
+    "middleware"
+  ],
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build.ts"
+  },
+  "license": "Apache-2.0",
+  "author": "orielhaim",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orielhaim/hono-ip"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9"
+  },
+  "dependencies": {
+    "hono": "^4.12.3"
+  }
+}