ipware

Node IPware

A Node application to retrieve user's IP address

Overview

Best attempt to get user's (client's) real ip-address while keeping it DRY.

How to install

1. npm install ipware
2. git clone http://github.com/un33k/node-ipware
    a. npm install node-ipware
3. wget https://github.com/un33k/node-ipware/zipball/master
    a. unzip the downloaded file
    b. npm install node-ipware

How to use

 // In your js file (e.g. app.js)
 var get_ip = require('ipware')().get_ip;
 app.use(function(req, res, next) {
     var ip_info = get_ip(req);
     console.log(ip_info);
     // { clientIp: '127.0.0.1', clientIpRoutable: false }
     next();
 });

 // `get_ip` also adds two fields to your request object
 // 1. `clientIp`, 2. `clientIpRoutable`
 // Where:
 //    `clientIp` holds the client's IP address
 //    'clientIpRoutable` is `true` if user's IP is `public`. (externally route-able)
 //                       is `false` if user's IP is `private`. (not externally route-able)

 // Advanced option: By default the left most address in the `HTTP_X_FORWARDED_FOR` or `X_FORWARDED_FOR`
 // is returned.  However, depending on your preference and needs, you can change this
 // behavior by passing the `right_most_proxy=True` to the API.
 // Note: Not all proxies are equal. So left to right or right to left preference is not a
 // rule that all proxy servers follow.

 var ip_info = get_ip(req, right_most_proxy=True)

Advanced users:

 // 1. Trusted Proxies:
 // *************************
 // To only get client ip addresses from your own trusted proxy server(s), use `get_trusted_ip()`.
 // In your js file (e.g. app.js)
 var get_trusted_ip = require('ipware')().get_trusted_ip;
 var trusted_proxies = ['177.144.11.100', '177.144.11.101'];
 app.use(function(req, res, next) {
     var ip_info = get_trusted_ip(req, trusted_proxies);
     console.log(ip_info);
     // { clientIp: '177.100.44.22', clientIpRoutable: true }
     next();
 });

 // Alternatively, you can pass in the trusted proxies via the configuration file.
 {
   ...
   "IPWARE_TRUSTED_PROXY_LIST": [
     '177.144.11.100',
     '177.144.11.101'
   ],
   ...
 }

 // 2. Customizable configuration file:
 // ***********************************
 // You can also use your own config file as below.
 // for `IPWARE_HTTP_HEADER_PRECEDENCE_ORDER` items, the
 // check is done from top to bottom where the request `headers`
 // is examined for the existence of the IP address field.

 // All lists that start with `IPV` are examined and if an IP
 // address starts with any of those patterns the IP is considered
 // `private`, otherwise the IP is considered `public` which means
 // the IP is externally routable. (reachable through the Internet :)

 // Simply copy the following content into a JSON file and
 // modify it to suit your needs and place it in your project
 // under version control.

 // Then you can use it like:
 // var get_ip = require('ipware')('../path/to/your/conf.json').get_ip;

 {
   "IPWARE_HTTP_HEADER_PRECEDENCE_ORDER": [
     "HTTP_X_FORWARDED_FOR",
     "HTTP_CLIENT_IP",
     "HTTP_X_REAL_IP",
     "HTTP_X_FORWARDED",
     "HTTP_X_CLUSTER_CLIENT_IP",
     "HTTP_FORWARDED_FOR",
     "HTTP_FORWARDED",
     "HTTP_VIA",
     "X_FORWARDED_FOR",
     "REMOTE_ADDR"
   ],

   "IPWARE_HTTP_HEADER_PROXY_PRECEDENCE_ORDER": [
     "HTTP_X_FORWARDED_FOR",
     "X_FORWARDED_FOR"
   ],

   "IPWARE_TRUSTED_PROXY_LIST": [
   ],

   "IPV4_EXTERNALLY_NON_ROUTABLE_IP_PREFIX": [
     "0."
   ],

   "IPV4_CLASS_A_PRIVATE_BLOCK_IP_PREFIX": [
     "10."
   ],

   "IPV4_CARRIER_GRADE_NAT_IP_PREFIX": [
     "100.64.",
     "100.65.",
     "100.66.",
     "100.67.",
     "100.68.",
     "100.69.",
     "100.70.",
     "100.71.",
     "100.72.",
     "100.73.",
     "100.74.",
     "100.75.",
     "100.76.",
     "100.77.",
     "100.78.",
     "100.79.",
     "100.80.",
     "100.81.",
     "100.82.",
     "100.83.",
     "100.84.",
     "100.85.",
     "100.86.",
     "100.87.",
     "100.88.",
     "100.89.",
     "100.90.",
     "100.91.",
     "100.92.",
     "100.93.",
     "100.94.",
     "100.95.",
     "100.96.",
     "100.97.",
     "100.98.",
     "100.99.",
     "100.100.",
     "100.101.",
     "100.102.",
     "100.103.",
     "100.104.",
     "100.105.",
     "100.106.",
     "100.107.",
     "100.108.",
     "100.109.",
     "100.110.",
     "100.111.",
     "100.112.",
     "100.113.",
     "100.114.",
     "100.115.",
     "100.116.",
     "100.117.",
     "100.118.",
     "100.119.",
     "100.120.",
     "100.121.",
     "100.122.",
     "100.123.",
     "100.124.",
     "100.125.",
     "100.126.",
     "100.127."
   ],

   "IPV4_LOCAL_LINK_BLOCK_IP_PREFIX": [
     "169.254."
   ],

   "IPV4_CLASS_B_PRIVATE_BLOCK_IP_PREFIX": [
     "172.16.",
     "172.17.",
     "172.18.",
     "172.19.",
     "172.20.",
     "172.21.",
     "172.22.",
     "172.23.",
     "172.24.",
     "172.25.",
     "172.26.",
     "172.27.",
     "172.28.",
     "172.29.",
     "172.30.",
     "172.31."
   ],

   "IPV4_INAA_SPECIAL_ADDRESS_REGISTRY_IP_PREFIX": [
     "192.0.0."
   ],

   "IPV4_DOCUMENTATION_AND_EXAMPLE_CODE_192_IP_PREFIX": [
     "192.0.2."
   ],

   "IPV4_CLASS_C_PRIVATE_BLOCK_IP_PREFIX": [
     "192.168."
   ],

   "IPV4_INNER_NETWORK_COMMUNICATION_BETWEEN_TWO_SEPARATE_SUBNETS_IP_PREFIX": [
     "198.18.",
     "198.19."
   ],

   "IPV4_DOCUMENTATION_AND_EXAMPLE_CODE_198_IP_PREFIX": [
     "198.51.100."
   ],

   "IPV4_DOCUMENTATION_AND_EXAMPLE_CODE_203_IP_PREFIX": [
     "203.0.113."
   ],

   "IPV4_MULTICAST_IP_PREFIX": [
     "224.",
     "225.",
     "226.",
     "227.",
     "228.",
     "229.",
     "230.",
     "231.",
     "232.",
     "233.",
     "234.",
     "235.",
     "236.",
     "237.",
     "238.",
     "239."
   ],

   "IPV4_RESERVED_IP_PREFIX": [
     "240.",
     "241.",
     "242.",
     "243.",
     "244.",
     "245.",
     "246.",
     "247.",
     "248.",
     "249.",
     "250.",
     "251.",
     "252.",
     "253.",
     "254."
   ],
   
   "IPV4_BRODCAST_IP_PREFIX": [
     "255."
   ],

   "IPV4_LOOPBACK_IP_PREFIX": [
     "127."
   ],

   "IPV6_EXAMPLE_CODE_DOCUMENTATION_IP_PREFIX": [
     "2001:db8:"
   ],

   "IPV6_PRIVATE_BLOCK_IP_PREFIX": [
     "fc00:"
   ],

   "IPV6_LINK_LOCAL_UNICAST_IP_PREFIX": [
     "fe80:"
   ],

   "IPV6_MULTICAST_IP_PREFIX": [
     "ff00:"
   ],

   "IPV6_LOOPBACK_IP_PREFIX": [
     "::1"
   ]
 }

Running the tests

To run the tests against the current environment:

npm install
npm test

License

Released under a (MIT) license.

Version

X.Y.Z Version

`MAJOR` version -- when you make incompatible API changes,
`MINOR` version -- when you add functionality in a backwards-compatible manner, and
`PATCH` version -- when you make backwards-compatible bug fixes.

Sponsors