{"id":32868226,"url":"https://github.com/programmernomad/node-cloudflare-realip","last_synced_at":"2025-11-09T08:02:11.295Z","repository":{"id":322980562,"uuid":"1091659307","full_name":"ProgrammerNomad/node-cloudflare-realip","owner":"ProgrammerNomad","description":"Secure Node.js utility to restore real visitor IPs behind Cloudflare by validating Cloudflare IP ranges.","archived":false,"fork":false,"pushed_at":"2025-11-07T11:04:57.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T12:20:50.776Z","etag":null,"topics":["cloudflare","express","fastify","middleware","proxy","real-ip","realip","reverse-proxy"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ProgrammerNomad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T10:29:44.000Z","updated_at":"2025-11-07T11:05:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ProgrammerNomad/node-cloudflare-realip","commit_stats":null,"previous_names":["programmernomad/node-cloudflare-realip"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ProgrammerNomad/node-cloudflare-realip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProgrammerNomad%2Fnode-cloudflare-realip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProgrammerNomad%2Fnode-cloudflare-realip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProgrammerNomad%2Fnode-cloudflare-realip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProgrammerNomad%2Fnode-cloudflare-realip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ProgrammerNomad","download_url":"https://codeload.github.com/ProgrammerNomad/node-cloudflare-realip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProgrammerNomad%2Fnode-cloudflare-realip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283475139,"owners_count":26841941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-09T02:00:05.828Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","express","fastify","middleware","proxy","real-ip","realip","reverse-proxy"],"created_at":"2025-11-09T08:00:39.906Z","updated_at":"2025-11-09T08:02:11.269Z","avatar_url":"https://github.com/ProgrammerNomad.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node Cloudflare RealIP\n\nRestore original visitor IP addresses when your Node.js app is behind Cloudflare. This package validates that the incoming connection comes from Cloudflare IP ranges before honoring Cloudflare headers like `CF-Connecting-IP` or `True-Client-IP`.\n\n## Why Use This Package?\n\nWhen your application is behind Cloudflare, the direct connection comes from Cloudflare's servers, not the actual visitor. Cloudflare provides the real visitor IP in headers like `CF-Connecting-IP`. However, **blindly trusting these headers is a security risk** - anyone could spoof them.\n\nThis package:\n- **Validates** the connection is actually from Cloudflare by checking IP ranges\n- Only then trusts Cloudflare headers to get the real visitor IP\n- Works with Express, Fastify, and any Node.js HTTP server\n- Includes bundled Cloudflare IP ranges + ability to fetch latest ranges\n\n## Features\n\n- **Secure**: Validates Cloudflare IP ranges before trusting headers\n- **Framework agnostic**: Works with Express, Fastify, raw HTTP servers, and more\n- **Lightweight**: Minimal dependencies (only `range_check` for IP validation)\n- **Auto-update**: Fetch latest Cloudflare IP ranges on demand\n- **TypeScript**: Includes TypeScript definitions\n- **Fast**: Bundled ranges for offline operation\n\n## Installation\n\n```bash\nnpm install node-cloudflare-realip\n```\n\n**Package is now live on npm!** Visit: [https://www.npmjs.com/package/node-cloudflare-realip](https://www.npmjs.com/package/node-cloudflare-realip)\n\n**Alternative package managers:**\n\n```bash\n# Using Yarn\nyarn add node-cloudflare-realip\n\n# Using pnpm\npnpm add node-cloudflare-realip\n\n# Using Bun\nbun add node-cloudflare-realip\n```\n\n## Quick Start\n\n### Express.js\n\n```javascript\nconst express = require('express');\nconst cloudflareRealIp = require('node-cloudflare-realip');\n\nconst app = express();\n\n// Load Cloudflare IP ranges\ncloudflareRealIp.load();\n\n// Apply middleware\napp.use(cloudflareRealIp.express());\n\napp.get('/', (req, res) =\u003e {\n  res.send('Your IP: ' + req.realIp);\n});\n\napp.listen(3000);\n```\n\n### Fastify\n\n```javascript\nconst fastify = require('fastify')();\nconst cloudflareRealIp = require('node-cloudflare-realip');\n\ncloudflareRealIp.load();\nfastify.addHook('onRequest', cloudflareRealIp.fastify());\n\nfastify.get('/', async (request, reply) =\u003e {\n  return { ip: request.realIp };\n});\n\nfastify.listen({ port: 3000 });\n```\n\n### Raw HTTP Server\n\n```javascript\nconst http = require('http');\nconst cloudflareRealIp = require('node-cloudflare-realip');\n\ncloudflareRealIp.load();\n\nhttp.createServer((req, res) =\u003e {\n  if (cloudflareRealIp.check(req)) {\n    req.realIp = cloudflareRealIp.get(req);\n  }\n  res.end('Your IP: ' + (req.realIp || req.socket.remoteAddress));\n}).listen(3000);\n```\n\n## API Reference\n\n### `load([callback])`\nLoad Cloudflare IP ranges from bundled `ranges.json`. Returns a Promise if no callback provided.\n\n### `updateFromCloudflare()`\nFetch the latest IP ranges from Cloudflare's official endpoints. Returns a Promise with updated ranges.\n\n### `check(req)`\nReturns `true` if the request comes from a Cloudflare IP and has CF headers.\n\n### `get(req)`\nReturns the real visitor IP from Cloudflare headers or falls back to socket address.\n\n### `express()`\nReturns Express middleware that automatically sets `req.realIp`.\n\n### `fastify()`\nReturns Fastify onRequest hook function.\n\n## Documentation\n\n- [Full Usage Guide](docs/usage.md)\n- [Examples](docs/examples.md) - Express, Fastify, HTTP, TypeScript examples\n- [Official Cloudflare Docs](https://developers.cloudflare.com/support/troubleshooting/restoring-visitor-ips/restoring-original-visitor-ips/)\n\n## How It Works\n\n1. Checks if request has Cloudflare headers (`CF-Connecting-IP` or `True-Client-IP`)\n2. Validates the connection's IP address is in Cloudflare's IP ranges\n3. If validated, trusts the Cloudflare header and sets `req.realIp`\n4. Optionally overrides `req.socket.remoteAddress` for seamless integration\n\n## Security\n\nThis package only trusts Cloudflare headers when the connection originates from verified Cloudflare IP ranges. This prevents IP spoofing attacks where malicious users could send fake `CF-Connecting-IP` headers.\n\n## Publishing to npm\n\nSee [docs/usage.md](docs/usage.md#publishing-to-npm) for publishing instructions.\n\n## License\n\nMIT\n\n## Links\n\n- **npm Package**: [https://www.npmjs.com/package/node-cloudflare-realip](https://www.npmjs.com/package/node-cloudflare-realip)\n- **GitHub Repository**: [https://github.com/ProgrammerNomad/node-cloudflare-realip](https://github.com/ProgrammerNomad/node-cloudflare-realip)\n- **Issues**: [https://github.com/ProgrammerNomad/node-cloudflare-realip/issues](https://github.com/ProgrammerNomad/node-cloudflare-realip/issues)\n# node-cloudflare-realip\nSecure Node.js utility to restore real visitor IPs behind Cloudflare by validating Cloudflare IP ranges.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogrammernomad%2Fnode-cloudflare-realip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogrammernomad%2Fnode-cloudflare-realip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogrammernomad%2Fnode-cloudflare-realip/lists"}