w-ipproxy 1.0.2 → 1.0.4

package/docs/WIpProxy.mjs.html

@@ -74,6 +74,8 @@ import provideServer from './provideServer.mjs'
  * @param {String} [opt.tar='https://httpbin.org/ip'] 輸入檢測目標網址字串，預設'https://httpbin.org/ip'
  * @param {Integer} [opt.timeGetProxies=30*1000] 輸入輪循抓取代理伺服器時間間隔整數，單位ms，預設30*1000
  * @param {Integer} [opt.timeTestProxies=60*1000] 輸入輪循測試代理伺服器時間間隔整數，單位ms，預設60*1000
+ * @param {Boolean} [opt.anonymityCheck=true] 輸入是否對代理做匿名性檢測布林值，開啟時會先打https://httpbin.org/ip驗證代理不會將本機真實IP透過X-Forwarded-For等方式洩漏給目標端，預設true
+ * @param {Integer} [opt.anonymityCheckRepeats=2] 輸入匿名性檢測重複次數整數，用以偵測負載平衡型代理的機率性洩漏，任一次洩漏即判定失敗，預設2
  * @param {Boolean} [opt.withServer=false] 輸入是否創建供數據供給伺服器布林值，預設false
  * @param {Integer} [opt.serverPort=8080] 輸入創建伺服器所用port整數，預設8080
  * @param {String} [opt.serverApiName='getProxies'] 輸入供給數據API名稱字串，預設'getProxies'
@@ -118,7 +120,7 @@ function WIpProxy(opt = {}) {
         `&timeout=5000` +
         // `&country=${join(['tw', 'cn', 'hk', 'jp', 'kr', 'sg', 'my', 'in', 'id', 'th', 'vn'])}` +
         // `&ssl=yes` +
-        `&anonymity=all`
+        `&anonymity=elite` //elite匿名代理, all會使用X-Forwarded-For儲存原本ip導致被識別
     }
 
     //tar
@@ -141,6 +143,19 @@ function WIpProxy(opt = {}) {
     }
     timeTestProxies = cint(timeTestProxies)
 
+    //anonymityCheck
+    let anonymityCheck = get(opt, 'anonymityCheck')
+    if (!isbol(anonymityCheck)) {
+        anonymityCheck = true
+    }
+
+    //anonymityCheckRepeats
+    let anonymityCheckRepeats = get(opt, 'anonymityCheckRepeats')
+    if (!ispint(anonymityCheckRepeats)) {
+        anonymityCheckRepeats = 2
+    }
+    anonymityCheckRepeats = cint(anonymityCheckRepeats)
+
     //withServer
     let withServer = get(opt, 'withServer')
     if (!isbol(withServer)) {
@@ -170,6 +185,71 @@ function WIpProxy(opt = {}) {
     let prxsRaw = []
     let kpPrx = {}
 
+    //myRealIp: 本機真實公網IP, 用於匿名性檢測時比對代理egress是否洩漏
+    let myRealIp = ''
+    let myRealIpReady = false
+    let myRealIpPm = null
+    async function _fetchMyRealIp() {
+        if (myRealIpReady) {
+            return
+        }
+        if (!myRealIpPm) {
+            myRealIpPm = (async () => {
+                try {
+                    let res = await axios.get('https://httpbin.org/ip', { timeout: 10000 })
+                    let origin = get(res, 'data.origin', '')
+                    if (isestr(origin)) {
+                        //origin可能為"1.2.3.4"或"1.2.3.4:port", 取首個逗號前且去port
+                        myRealIp = origin.split(',')[0].trim().split(':')[0]
+                    }
+                }
+                catch (err) {
+                    //取不到就算了, 匿名性檢查會自動跳過
+                }
+                myRealIpReady = true
+            })()
+        }
+        await myRealIpPm
+    }
+
+    async function _anonymityCheckCore(host, port) {
+        if (!anonymityCheck) {
+            return { ok: true }
+        }
+        if (!isestr(myRealIp)) {
+            return { ok: true } //沒抓到自己IP就無從比對, 放行
+        }
+        let agent = new https.Agent({ rejectUnauthorized: false })
+        for (let i = 0; i < anonymityCheckRepeats; i++) {
+            try {
+                let res = await axios.get('https://httpbin.org/ip', {
+                    proxy: { host, port, protocol: 'http' },
+                    httpsAgent: agent,
+                    timeout: 5000,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/122.0.0.0 Safari/537.36',
+                        'Accept': 'application/json',
+                    },
+                    validateStatus: () => true,
+                })
+                if (res.status !== 200) {
+                    return { ok: false, reason: `anonymity status[${res.status}]` }
+                }
+                let origin = get(res, 'data.origin', '')
+                if (!isestr(origin)) {
+                    return { ok: false, reason: 'anonymity non-json' }
+                }
+                if (origin.indexOf(myRealIp) >= 0) {
+                    return { ok: false, reason: `leaks real IP` }
+                }
+            }
+            catch (err) {
+                return { ok: false, reason: trim(err.message || '') }
+            }
+        }
+        return { ok: true }
+    }
+
     async function _getProxiesCore(src) {
         let ps = []
 
@@ -249,6 +329,12 @@ function WIpProxy(opt = {}) {
             }
         }
 
+        //匿名性預檢: 先確認代理不會透過X-Forwarded-For等洩漏本機真實IP
+        let ac = await _anonymityCheckCore(host, port)
+        if (!ac.ok) {
+            return ret('error', ac.reason)
+        }
+
         //r
         let r = {}
         try {
@@ -345,6 +431,9 @@ function WIpProxy(opt = {}) {
 
         let core = async() => {
 
+            //確保本機真實IP已取得, 供匿名性檢查比對
+            await _fetchMyRealIp()
+
             //get
             let r = await _testProxiesCore(prxsRaw)
 
@@ -452,7 +541,7 @@ export default WIpProxy
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.2</a> on Tue Mar 17 2026 21:42:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Apr 17 2026 13:33:04 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.2</a> on Tue Mar 17 2026 21:42:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Apr 17 2026 13:33:04 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "w-ipproxy",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "dist/w-ipproxy.umd.js",
   "dependencies": {
-    "@hapi/hapi": "^21.4.7",
+    "@hapi/hapi": "^21.4.8",
     "axios": "^1.13.6",
     "cheerio": "^1.2.0",
-    "lodash-es": "^4.17.23",
-    "wsemi": "^1.8.43"
+    "lodash-es": "^4.18.1",
+    "wsemi": "^1.8.47"
   },
   "devDependencies": {
-    "w-package-tools": "^1.1.3"
+    "w-package-tools": "^1.1.5"
   },
   "scripts": {
     "test": "mocha --parallel --timeout 60000",

package/src/WIpProxy.mjs

@@ -27,6 +27,8 @@ import provideServer from './provideServer.mjs'
  * @param {String} [opt.tar='https://httpbin.org/ip'] 輸入檢測目標網址字串，預設'https://httpbin.org/ip'
  * @param {Integer} [opt.timeGetProxies=30*1000] 輸入輪循抓取代理伺服器時間間隔整數，單位ms，預設30*1000
  * @param {Integer} [opt.timeTestProxies=60*1000] 輸入輪循測試代理伺服器時間間隔整數，單位ms，預設60*1000
+ * @param {Boolean} [opt.anonymityCheck=true] 輸入是否對代理做匿名性檢測布林值，開啟時會先打https://httpbin.org/ip驗證代理不會將本機真實IP透過X-Forwarded-For等方式洩漏給目標端，預設true
+ * @param {Integer} [opt.anonymityCheckRepeats=2] 輸入匿名性檢測重複次數整數，用以偵測負載平衡型代理的機率性洩漏，任一次洩漏即判定失敗，預設2
  * @param {Boolean} [opt.withServer=false] 輸入是否創建供數據供給伺服器布林值，預設false
  * @param {Integer} [opt.serverPort=8080] 輸入創建伺服器所用port整數，預設8080
  * @param {String} [opt.serverApiName='getProxies'] 輸入供給數據API名稱字串，預設'getProxies'
@@ -71,7 +73,7 @@ function WIpProxy(opt = {}) {
         `&timeout=5000` +
         // `&country=${join(['tw', 'cn', 'hk', 'jp', 'kr', 'sg', 'my', 'in', 'id', 'th', 'vn'])}` +
         // `&ssl=yes` +
-        `&anonymity=all`
+        `&anonymity=elite` //elite匿名代理, all會使用X-Forwarded-For儲存原本ip導致被識別
     }
 
     //tar
@@ -94,6 +96,19 @@ function WIpProxy(opt = {}) {
     }
     timeTestProxies = cint(timeTestProxies)
 
+    //anonymityCheck
+    let anonymityCheck = get(opt, 'anonymityCheck')
+    if (!isbol(anonymityCheck)) {
+        anonymityCheck = true
+    }
+
+    //anonymityCheckRepeats
+    let anonymityCheckRepeats = get(opt, 'anonymityCheckRepeats')
+    if (!ispint(anonymityCheckRepeats)) {
+        anonymityCheckRepeats = 2
+    }
+    anonymityCheckRepeats = cint(anonymityCheckRepeats)
+
     //withServer
     let withServer = get(opt, 'withServer')
     if (!isbol(withServer)) {
@@ -123,6 +138,71 @@ function WIpProxy(opt = {}) {
     let prxsRaw = []
     let kpPrx = {}
 
+    //myRealIp: 本機真實公網IP, 用於匿名性檢測時比對代理egress是否洩漏
+    let myRealIp = ''
+    let myRealIpReady = false
+    let myRealIpPm = null
+    async function _fetchMyRealIp() {
+        if (myRealIpReady) {
+            return
+        }
+        if (!myRealIpPm) {
+            myRealIpPm = (async () => {
+                try {
+                    let res = await axios.get('https://httpbin.org/ip', { timeout: 10000 })
+                    let origin = get(res, 'data.origin', '')
+                    if (isestr(origin)) {
+                        //origin可能為"1.2.3.4"或"1.2.3.4:port", 取首個逗號前且去port
+                        myRealIp = origin.split(',')[0].trim().split(':')[0]
+                    }
+                }
+                catch (err) {
+                    //取不到就算了, 匿名性檢查會自動跳過
+                }
+                myRealIpReady = true
+            })()
+        }
+        await myRealIpPm
+    }
+
+    async function _anonymityCheckCore(host, port) {
+        if (!anonymityCheck) {
+            return { ok: true }
+        }
+        if (!isestr(myRealIp)) {
+            return { ok: true } //沒抓到自己IP就無從比對, 放行
+        }
+        let agent = new https.Agent({ rejectUnauthorized: false })
+        for (let i = 0; i < anonymityCheckRepeats; i++) {
+            try {
+                let res = await axios.get('https://httpbin.org/ip', {
+                    proxy: { host, port, protocol: 'http' },
+                    httpsAgent: agent,
+                    timeout: 5000,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/122.0.0.0 Safari/537.36',
+                        'Accept': 'application/json',
+                    },
+                    validateStatus: () => true,
+                })
+                if (res.status !== 200) {
+                    return { ok: false, reason: `anonymity status[${res.status}]` }
+                }
+                let origin = get(res, 'data.origin', '')
+                if (!isestr(origin)) {
+                    return { ok: false, reason: 'anonymity non-json' }
+                }
+                if (origin.indexOf(myRealIp) >= 0) {
+                    return { ok: false, reason: `leaks real IP` }
+                }
+            }
+            catch (err) {
+                return { ok: false, reason: trim(err.message || '') }
+            }
+        }
+        return { ok: true }
+    }
+
     async function _getProxiesCore(src) {
         let ps = []
 
@@ -202,6 +282,12 @@ function WIpProxy(opt = {}) {
             }
         }
 
+        //匿名性預檢: 先確認代理不會透過X-Forwarded-For等洩漏本機真實IP
+        let ac = await _anonymityCheckCore(host, port)
+        if (!ac.ok) {
+            return ret('error', ac.reason)
+        }
+
         //r
         let r = {}
         try {
@@ -298,6 +384,9 @@ function WIpProxy(opt = {}) {
 
         let core = async() => {
 
+            //確保本機真實IP已取得, 供匿名性檢查比對
+            await _fetchMyRealIp()
+
             //get
             let r = await _testProxiesCore(prxsRaw)
 

package/test/anonymity.test.mjs

@@ -0,0 +1,140 @@
+import assert from 'assert'
+import axios from 'axios'
+import https from 'https'
+import wip from '../src/WIpProxy.mjs'
+
+
+describe('anonymity (elite + anonymityCheck)', function() {
+    this.timeout(240 * 1000) //4min, 因為getProxiesOnce加上獨立leak驗證本身就耗時
+
+    let myIp = ''
+    let ps = []
+
+    before(async function() {
+
+        //取本機真實公網IP
+        try {
+            let r = await axios.get('https://httpbin.org/ip', { timeout: 10000 })
+            myIp = r.data?.origin || ''
+        }
+        catch (err) {
+            this.skip()
+        }
+        if (!myIp) {
+            this.skip()
+        }
+
+        //預設設定已是anonymity=elite且啟用anonymityCheck, 走完整過濾路徑
+        let wo = wip({})
+        ps = await wo.getProxiesOnce()
+
+    })
+
+    it('no returned proxy should leak real IP via httpbin origin', async function() {
+        if (ps.length === 0) {
+            this.skip()
+        }
+
+        let agent = new https.Agent({ rejectUnauthorized: false })
+        let sample = ps.slice(0, 30)
+        let pms = sample.map(async (p) => {
+            try {
+                let res = await axios.get('https://httpbin.org/ip', {
+                    proxy: { host: p.host, port: p.port, protocol: 'http' },
+                    httpsAgent: agent,
+                    timeout: 8000,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/122.0.0.0 Safari/537.36',
+                        'Accept': 'application/json',
+                    },
+                    validateStatus: () => true,
+                })
+                if (res.status !== 200) {
+                    return { proxy: p.proxy, ok: true, reason: 'non-200, ignored' }
+                }
+                let origin = res.data?.origin
+                if (typeof origin !== 'string') {
+                    return { proxy: p.proxy, ok: true, reason: 'non-json, ignored' }
+                }
+                //回傳origin含本機真實IP即代表該代理洩漏
+                let leaks = origin.indexOf(myIp) >= 0
+                return { proxy: p.proxy, ok: !leaks, origin }
+            }
+            catch (err) {
+                //網路錯誤不算洩漏, 直接放行
+                return { proxy: p.proxy, ok: true, reason: err.message }
+            }
+        })
+        let rrs = await Promise.all(pms)
+        let leaked = rrs.filter((r) => !r.ok)
+
+        assert.strictEqual(
+            leaked.length, 0,
+            `expected 0 proxies to leak real IP, got ${leaked.length}: ` +
+            leaked.slice(0, 5).map((r) => `${r.proxy} (origin=${r.origin})`).join('; ')
+        )
+    })
+
+    it('no returned proxy should carry X-Forwarded-For / Via when viewed from target', async function() {
+        if (ps.length === 0) {
+            this.skip()
+        }
+
+        let LEAK_IP_HEADERS = [
+            'x-forwarded-for', 'x-real-ip', 'x-client-ip', 'client-ip',
+            'true-client-ip', 'cf-connecting-ip', 'forwarded',
+            'x-originating-ip', 'x-cluster-client-ip',
+        ]
+        let LEAK_PROXY_HEADERS = [
+            'via', 'proxy-connection', 'x-proxy-id',
+        ]
+
+        let agent = new https.Agent({ rejectUnauthorized: false })
+        let sample = ps.slice(0, 30)
+        let pms = sample.map(async (p) => {
+            try {
+                let res = await axios.get('https://httpbin.org/headers', {
+                    proxy: { host: p.host, port: p.port, protocol: 'http' },
+                    httpsAgent: agent,
+                    timeout: 8000,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/122.0.0.0 Safari/537.36',
+                        'Accept': 'application/json',
+                    },
+                    validateStatus: () => true,
+                })
+                if (res.status !== 200 || typeof res.data?.headers !== 'object') {
+                    return { proxy: p.proxy, ok: true, reason: 'ignored' }
+                }
+                let hs = {}
+                for (let k in res.data.headers) {
+                    hs[k.toLowerCase()] = String(res.data.headers[k])
+                }
+                let bad = []
+                for (let k of LEAK_IP_HEADERS) {
+                    if (k in hs && hs[k].indexOf(myIp) >= 0) {
+                        bad.push(`${k}=${hs[k]}`)
+                    }
+                }
+                for (let k of LEAK_PROXY_HEADERS) {
+                    if (k in hs) {
+                        bad.push(`${k}=${hs[k]}`)
+                    }
+                }
+                return { proxy: p.proxy, ok: bad.length === 0, bad }
+            }
+            catch (err) {
+                return { proxy: p.proxy, ok: true, reason: err.message }
+            }
+        })
+        let rrs = await Promise.all(pms)
+        let leaked = rrs.filter((r) => !r.ok)
+
+        assert.strictEqual(
+            leaked.length, 0,
+            `expected 0 proxies with leaky headers, got ${leaked.length}: ` +
+            leaked.slice(0, 5).map((r) => `${r.proxy} (${r.bad.join(',')})`).join('; ')
+        )
+    })
+
+})

package/test/getProxiesOnce.test.mjs

@@ -0,0 +1,89 @@
+import assert from 'assert'
+import axios from 'axios'
+import https from 'https'
+import wip from '../src/WIpProxy.mjs'
+
+
+describe('getProxiesOnce', function() {
+    this.timeout(180 * 1000) //3min, 因為需要抓清單+檢測+獨立驗證
+
+    let myIp = ''
+    let ps = []
+
+    before(async function() {
+
+        //取本機真實公網IP (不走代理), 作為後續洩漏比對基準
+        try {
+            let r = await axios.get('https://httpbin.org/ip', { timeout: 10000 })
+            myIp = r.data?.origin || ''
+        }
+        catch (err) {
+            //網路異常則整組test跳過
+            this.skip()
+        }
+        if (!myIp) {
+            this.skip()
+        }
+
+        //取代理清單 (預設anonymity=elite + 匿名性檢查)
+        let wo = wip({})
+        ps = await wo.getProxiesOnce()
+
+    })
+
+    it('should return a non-empty array of proxy objects', function() {
+        //若上游proxyscrape當下無代理供應, 放行以免CI誤報 (非本專案bug)
+        if (ps.length === 0) {
+            this.skip()
+        }
+        assert.ok(Array.isArray(ps))
+        for (let p of ps) {
+            assert.strictEqual(typeof p.host, 'string')
+            assert.ok(p.host.length > 0)
+            assert.strictEqual(typeof p.port, 'number')
+            assert.ok(p.port > 0)
+            assert.strictEqual(p.proxy, `${p.host}:${p.port}`)
+        }
+    })
+
+    it('majority of returned proxies should be independently usable against httpbin', async function() {
+        if (ps.length === 0) {
+            this.skip()
+        }
+
+        //獨立再打一次httpbin.org/ip, 不倚賴內建的檢測結果
+        let agent = new https.Agent({ rejectUnauthorized: false })
+        let sample = ps.slice(0, 30) //取前30個避免長時間阻塞CI
+        let pms = sample.map(async (p) => {
+            try {
+                let res = await axios.get('https://httpbin.org/ip', {
+                    proxy: { host: p.host, port: p.port, protocol: 'http' },
+                    httpsAgent: agent,
+                    timeout: 8000,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/122.0.0.0 Safari/537.36',
+                        'Accept': 'application/json',
+                    },
+                    validateStatus: () => true,
+                })
+                return res.status === 200
+                    && typeof res.data === 'object'
+                    && res.data !== null
+                    && typeof res.data.origin === 'string'
+            }
+            catch (err) {
+                return false
+            }
+        })
+        let rrs = await Promise.all(pms)
+        let okCount = rrs.filter((v) => v).length
+        let ratio = okCount / rrs.length
+
+        //要求至少50%仍可用, 免疫於個別代理剛好在測試間掛掉的flakiness
+        assert.ok(
+            ratio >= 0.5,
+            `independent reachability ratio too low: ${okCount}/${rrs.length} (${(ratio * 100).toFixed(1)}%)`
+        )
+    })
+
+})

package/toolg/gDistRollup.mjs

@@ -1,20 +1,17 @@
 import rollupFiles from 'w-package-tools/src/rollupFiles.mjs'
 import getFiles from 'w-package-tools/src/getFiles.mjs'
-import w from 'wsemi'
 
 
 let fdSrc = './src'
 let fdTar = './dist'
-let fns = getFiles(fdSrc)
-fns = fns.filter((v) => {
-    return w.strleft(v, 1) === 'W'
-})
+
 
 rollupFiles({
-    fns,
+    fns: 'WIpProxy.mjs',
     fdSrc,
     fdTar,
-    nameDistType: 'kebabCase',
+    hookNameDist: () => 'w-ipproxy',
+    // nameDistType: 'kebabCase', //直接由hookNameDist給予
     globals: {
         '@hapi/hapi': '@hapi/hapi',
         '@hapi/inert': '@hapi/inert',