![Oracle Drags Its Feet in the JavaScript Trademark Dispute](https://cdn.sanity.io/images/cgdhsj6q/production/919c3b22c24f93884c548d60cbb338e819ff2435-1024x1024.webp?w=400&fit=max&auto=format)
Security News
Oracle Drags Its Feet in the JavaScript Trademark Dispute
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
@fullerstack/nax-ipware
Advanced tools
A node library for server applications retrieving user's real IP address
A node library for server applications retrieving user's real IP address
Best attempt to get client's IP address while keeping it DRY.
There is not a good out-of-the-box
solution against fake IP addresses, aka IP Address Spoofing.
You are encouraged to read the Advanced users section of this page and
use trusted proxy prefixes
and/or proxy count
features to match your needs, especially if you are
planning to include ipware
in any authentication, security or anti-fraud
related architecture.
You are also encouraged to use ip filtering alongside ipware
for optimal result.
npm install @fullerstack/nax-ipware
OR yarn add @fullerstack/nax-ipware
# In a view or a middleware where the `request` object is available
// In your js file (e.g. app.js)
import {Ipware} from '@fullerstack/nax-ipware';
const ipware = new Ipware();
app.use(function(req, res, next) {
req.ipInfo = ipware.getClientIP(req)
// { ip: '177.139.100.100', isPublic: true, isRouteTrusted: false }
// do something with the ip address (e.g. pass it down through the request)
// note: ip address doesn't change often, so better cache it for performance,
// you should have distinct session ID for public and anonymous users to cache the ip address
next();
});
Flags ⇩ | ⇩ Description |
---|---|
count ⇨ | : Total number of expected proxies (pattern: client, proxy1, ..., proxy2 ): if count = 0 then client : if count = 1 then client, proxy1 : if count = 2 then client, proxy1, proxy2 : if count = 3 then client, proxy1, proxy2 proxy3 |
proxyList ⇨ | : List of trusted proxies (pattern: client, proxy1, ..., proxy2 ): if proxyList = ['10.1.'] then client, 10.1.1.1 OR client, proxy1, 10.1.1.1 : if proxyList = ['10.1', '10.2.'] then client, 10.1.1.1 OR client, proxy1, 10.2.2.2 : if proxyList = ['10.1', '10.2.'] then client, 10.1.1.1 10.2.2.2 OR client, 10.1.1.1 10.2.2.2 |
publicOnly ⇨ | : Returns only public and internet routable IP or null |
Output Field ⇩ | ⇩ Description |
---|---|
ip ⇨ | : IP address of the client |
isPublic ⇨ | : If ip is public and internet routable, true , else false |
isRouteTrusted ⇨ | : If proxy count and/or proxyList provided and matched, true , else false |
The client IP address can be found in one or more request headers attributes. The lookup order is top to bottom and the default attributes are as follow.
// The default meta precedence order
export const IPWARE_HEADERS_IP_ATTRIBUTES_ORDER: string[] = [
'X_FORWARDED_FOR', // Load balancers or proxies such as AWS ELB (default client is `left-most` [`<client>, <proxy1>, <proxy2>`])
'HTTP_X_FORWARDED_FOR', // Similar to X_FORWARDED_TO
'HTTP_CLIENT_IP', // Standard headers used by providers such as Amazon EC2, Heroku etc.
'HTTP_X_REAL_IP',
'HTTP_X_FORWARDED',
'HTTP_X_CLUSTER_CLIENT_IP',
'HTTP_FORWARDED_FOR',
'HTTP_FORWARDED',
'HTTP_VIA',
'X-REAL-IP', // NGINX
'X-CLUSTER-CLIENT-IP', // Rackspace Cloud Load Balancers
'X_FORWARDED',
'FORWARDED_FOR',
'CF-CONNECTING-IP', // CloudFlare
'TRUE-CLIENT-IP', // CloudFlare Enterprise,
'FASTLY-CLIENT-IP', // Firebase, Fastly
'FORWARDED',
];
You can customize the order by providing your own list during initialization when calling new Ipware(options)
.
You can pass your custom list on every call, when calling the api to fetch the ip.
ipware.getClientIP(request, {
requestHeadersOrder: ['X_FORWARDED_FOR'],
});
ipware.getClientIP(request, {
requestHeadersOrder: ['X_FORWARDED_FOR', 'HTTP_X_FORWARDED_FOR'],
});
// ... etc
A default list that holds the private IP prefixes is called IPWARE_PRIVATE_IP_PREFIX
.
This list is used to determine if an IP address is public
or private
.
It is recommended that you send us any private
IP addresses that we have missed, to be included in the default list.
export const IPWARE_PRIVATE_IP_PREFIX: string[] = [
'0.', // messages to software
'10.', // class A private block
...[
// carrier-grade NAT (IPv4)
'100.64.',
'100.65.',
'100.66.',
'100.67.',
],
// many more prefixes
]
You can customize the private IP prefixes by providing your own list during initialization when calling new Ipware(options)
.
You can pass your custom list on every call, when calling the api to fetch the ip.
ipware.getClientIP(request, {
privateIpPrefixes: ['0.', '10.'], // your own private IP addresses
});
ipware.getClientIP(request, {
privateIpPrefixes: ['0.', '10.', '2001:10:'], // your own private IP addresses
});
// ... etc
If your node server is behind one or more known proxy server(s), you can filter out unwanted requests
by providing a trusted proxy list
, or a known proxy count
.
You can customize the proxy IP prefixes by providing your own list during initialization when calling new Ipware(options)
.
You can pass your custom list on every call, when calling the proxy-aware api to fetch the ip.
// In the above scenario, use your load balancer IP address as a way to filter out unwanted requests.
const ipInfo = ipware.getClientIP(request, {
proxy: {
proxyList: ['177.139.233.132']
},
});
// If you have multiple proxies, simply add them to the list
const ipInfo = ipware.getClientIP(request, {
proxy: {
proxyList: ['177.139.233.100', '177.139.233.132']
},
});
// For proxy servers with fixed sub-domain and dynamic IP, use the following pattern.
const ipInfo = ipware.getClientIP(request, {
proxy: {
proxyList: ['177.139.', '177.140']
},
});
const ipInfo = ipware.getClientIP(request, {
proxy: {
proxyList: ['177.139.233.', '177.139.240']
},
});
// For proxy by ip address and count
const ipInfo = ipware.getClientIP(request, {
proxy: {
proxyList: ['177.139.', '177.140'],
count: 2
},
});
// For strict mode, we either return the ip that matches the proxy info, or none
const ipInfo = ipware.getClientIP(request, {
proxy: {
strict: true,
proxyList: ['177.139.233.', '177.139.240']
},
});
In the following example
, your public load balancer (LB) can be seen as a trusted
proxy.
`Real` Client <public> <-> <public> LB (Server) <private> <-----> <private> Node Server
^
|
`Fake` Client <private> <-> <private> LB (Server) <private> -+
If your node server is behind a known
number of proxies, but your deploy on multiple providers and don't want to track proxy IPs, you still can filter out unwanted requests by providing proxy count
.
You can customize the proxy count by providing your count
during initialization when calling new Ipware(options)
.
You can pass your custom count
on every call, when calling the proxy-aware api to fetch the ip.
// In the above scenario, the total number of proxies can be used as a way to filter out unwanted requests.
const ipInfo = ipware.getClientIP(request, {
proxy: {
count: 1
},
});
// For proxy by count, and proxy list
const ipInfo = ipware.getClientIP(request, {
proxy: {
count: 1
proxyList: ['177.139.233.']
},
});
// For strict mode, we either return the ip that matches the proxy info, or none
const ipInfo = ipware.getClientIP(request, {
proxy: {
strict: true,
count: 1
},
});
In the following example
, your public load balancer (LB) can be seen as the only
proxy.
`Real` Client <public> <-> <public> LB (Server) <private> <---> <private> Node Server
^
|
`Fake` Client <private> ---+
// For publicOnly mode, we either return the first public IP address based on order or none
const ipInfo = ipware.getClientIP(request, {
publicOnly: true
});
If your proxy server has a custom
configuration where the right-most
IP address is that of the originating client, you
can indicate right-most
as the order
when calling any api.
Please note that the de-facto standard
for the originating client IP address is the left-most
as per client, proxy1, proxy2
, and the right-most
proxy is the most
trusted proxy.
To run the tests against the current environment:
yarn nx test nax-ipware
Released under a (MIT) license.
X.Y.Z Version
`MAJOR` version -- making incompatible API changes
`MINOR` version -- adding functionality in a backwards-compatible manner
`PATCH` version -- making backwards-compatible bug fixes
FAQs
A node library for server applications retrieving user's real IP address
The npm package @fullerstack/nax-ipware receives a total of 11,433 weekly downloads. As such, @fullerstack/nax-ipware popularity was classified as popular.
We found that @fullerstack/nax-ipware demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.
Security News
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.