feat: auto-detect timezone/locale from proxy IP via geoip

Adds geoip=True parameter to launch(), launch_async(), and
launch_context(). Resolves proxy exit IP → MaxMind GeoLite2-City
lookup → timezone + locale. Downloads ~70MB DB on first use from
P3TERX mirror, caches in ~/.cloakbrowser/geoip/.

Optional deps: pip install cloakbrowser[geoip] / npm install mmdb-lib
Explicit timezone/locale always override auto-detected values.
This commit is contained in:
CloakHQ
2026-03-01 01:53:50 +01:00
parent 59b9d71684
commit 67efadef26
14 changed files with 891 additions and 15 deletions
+34 -1
View File
@@ -75,7 +75,19 @@ const browser = await launch({
args: ['--window-size=1920,1080'],
});
// Browser + context in one call
// With timezone and locale (sets --timezone and --lang binary flags)
const browser = await launch({
timezone: 'America/New_York',
locale: 'en-US',
});
// Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib)
const browser = await launch({
proxy: 'http://proxy:8080',
geoip: true,
});
// Browser + context in one call (timezone/locale set both binary flags AND context)
const context = await launchContext({
userAgent: 'Custom UA',
viewport: { width: 1920, height: 1080 },
@@ -84,6 +96,27 @@ const context = await launchContext({
});
```
### Auto Timezone/Locale from Proxy IP
When using a proxy, antibot systems check that your browser's timezone and locale match the proxy's location. Install `mmdb-lib` to enable auto-detection from an offline GeoIP database (~70 MB, downloaded on first use):
```bash
npm install mmdb-lib
```
```javascript
// Auto-detect — timezone and locale set from proxy's IP geolocation
const browser = await launch({ proxy: 'http://proxy:8080', geoip: true });
// Works with launchContext too
const context = await launchContext({ proxy: 'http://proxy:8080', geoip: true });
// Explicit values always win over auto-detection
const browser = await launch({ proxy: 'http://proxy:8080', geoip: true, timezone: 'Europe/London' });
```
> **Note:** For rotating residential proxies, the DNS-resolved IP may differ from the exit IP. Pass explicit `timezone`/`locale` in those cases.
### Utilities
```javascript
+18 -2
View File
@@ -1,18 +1,19 @@
{
"name": "cloakbrowser",
"version": "0.1.0",
"version": "0.2.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "cloakbrowser",
"version": "0.1.0",
"version": "0.2.0",
"license": "MIT",
"dependencies": {
"tar": "^7.0.0"
},
"devDependencies": {
"@types/node": "^20.10.0",
"mmdb-lib": "^3.0.2",
"playwright-core": "^1.40.0",
"puppeteer-core": "^21.0.0",
"typescript": "^5.3.0",
@@ -22,10 +23,14 @@
"node": ">=18.0.0"
},
"peerDependencies": {
"mmdb-lib": ">=2.0.0",
"playwright-core": ">=1.40.0",
"puppeteer-core": ">=21.0.0"
},
"peerDependenciesMeta": {
"mmdb-lib": {
"optional": true
},
"playwright-core": {
"optional": true
},
@@ -1839,6 +1844,17 @@
"dev": true,
"license": "MIT"
},
"node_modules/mmdb-lib": {
"version": "3.0.2",
"resolved": "https://registry.npmjs.org/mmdb-lib/-/mmdb-lib-3.0.2.tgz",
"integrity": "sha512-7e87vk0DdWT647wjcfEtWeMtjm+zVGqNohN/aeIymbUfjHQ2T4Sx5kM+1irVDBSloNC3CkGKxswdMoo8yhqTDg==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=10",
"npm": ">=6"
}
},
"node_modules/ms": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+6 -1
View File
@@ -1,6 +1,6 @@
{
"name": "cloakbrowser",
"version": "0.2.0",
"version": "0.2.1",
"description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.",
"type": "module",
"main": "dist/index.js",
@@ -43,6 +43,7 @@
"node": ">=18.0.0"
},
"peerDependencies": {
"mmdb-lib": ">=2.0.0",
"playwright-core": ">=1.40.0",
"puppeteer-core": ">=21.0.0"
},
@@ -52,6 +53,9 @@
},
"puppeteer-core": {
"optional": true
},
"mmdb-lib": {
"optional": true
}
},
"dependencies": {
@@ -59,6 +63,7 @@
},
"devDependencies": {
"@types/node": "^20.10.0",
"mmdb-lib": "^3.0.2",
"playwright-core": "^1.40.0",
"puppeteer-core": "^21.0.0",
"typescript": "^5.3.0",
+262
View File
@@ -0,0 +1,262 @@
/**
* GeoIP-based timezone and locale detection from proxy IP.
*
* Optional feature — requires `mmdb-lib` package:
* npm install mmdb-lib
*
* Downloads GeoLite2-City.mmdb (~70 MB) on first use,
* caches in `~/.cloakbrowser/geoip/`.
*/
import fs from "node:fs";
import path from "node:path";
import { createWriteStream } from "node:fs";
import dns from "node:dns/promises";
import net from "node:net";
import { getCacheDir } from "./config.js";
// P3TERX mirror of MaxMind GeoLite2-City — no license key needed
const GEOIP_DB_URL =
"https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb";
const GEOIP_DB_FILENAME = "GeoLite2-City.mmdb";
const GEOIP_UPDATE_INTERVAL_MS = 30 * 86_400_000; // 30 days
/** Country ISO code → BCP 47 locale (covers ~90% of proxy traffic). */
export const COUNTRY_LOCALE_MAP: Record<string, string> = {
US: "en-US", GB: "en-GB", AU: "en-AU", CA: "en-CA", NZ: "en-NZ",
IE: "en-IE", ZA: "en-ZA", SG: "en-SG",
DE: "de-DE", AT: "de-AT", CH: "de-CH",
FR: "fr-FR", BE: "fr-BE",
ES: "es-ES", MX: "es-MX", AR: "es-AR", CO: "es-CO", CL: "es-CL",
BR: "pt-BR", PT: "pt-PT",
IT: "it-IT", NL: "nl-NL",
JP: "ja-JP", KR: "ko-KR", CN: "zh-CN", TW: "zh-TW", HK: "zh-HK",
RU: "ru-RU", UA: "uk-UA", PL: "pl-PL", CZ: "cs-CZ", RO: "ro-RO",
IL: "he-IL", TR: "tr-TR", SA: "ar-SA", AE: "ar-AE", EG: "ar-EG",
IN: "hi-IN", ID: "id-ID", PH: "en-PH",
TH: "th-TH", VN: "vi-VN", MY: "ms-MY",
SE: "sv-SE", NO: "nb-NO", DK: "da-DK", FI: "fi-FI",
GR: "el-GR", HU: "hu-HU", BG: "bg-BG",
};
export interface GeoResult {
timezone: string | null;
locale: string | null;
}
/**
* Resolve timezone and locale from a proxy's IP address.
* Returns `{ timezone, locale }` — either may be null on failure.
* Never throws.
*/
export async function resolveProxyGeo(
proxyUrl: string
): Promise<GeoResult> {
let Reader: any;
try {
const mmdb = await import("mmdb-lib");
Reader = mmdb.default?.Reader ?? mmdb.Reader;
} catch {
throw new Error(
"mmdb-lib is required for geoip: true. Install it with:\n npm install mmdb-lib"
);
}
const dbPath = await ensureGeoipDb();
if (!dbPath) return { timezone: null, locale: null };
// Exit IP (through proxy) is most accurate — gateway DNS may differ from exit
let ip = await resolveExitIp(proxyUrl);
if (!ip) ip = await resolveProxyIp(proxyUrl);
if (!ip) return { timezone: null, locale: null };
try {
const buf = fs.readFileSync(dbPath);
const reader = new Reader(buf);
const result = reader.get(ip) as any;
const timezone: string | null = result?.location?.time_zone ?? null;
const countryCode: string | null = result?.country?.iso_code ?? null;
const locale =
countryCode ? (COUNTRY_LOCALE_MAP[countryCode] ?? null) : null;
return { timezone, locale };
} catch {
return { timezone: null, locale: null };
}
}
// ---------------------------------------------------------------------------
// Proxy IP resolution
// ---------------------------------------------------------------------------
/** @internal Exported for testing. */
export async function resolveProxyIp(
proxyUrl: string
): Promise<string | null> {
try {
const url = new URL(proxyUrl);
const hostname = url.hostname;
if (!hostname) return null;
// Already a literal IP?
if (net.isIP(hostname)) return hostname;
// DNS resolve
const { address } = await dns.lookup(hostname);
return address;
} catch {
return null;
}
}
function isPrivateIp(ip: string): boolean {
// Quick check for common private ranges
if (ip.startsWith("10.") || ip.startsWith("127.") || ip === "::1") return true;
if (ip.startsWith("172.")) {
const second = parseInt(ip.split(".")[1], 10);
if (second >= 16 && second <= 31) return true;
}
if (ip.startsWith("192.168.")) return true;
return false;
}
const IP_ECHO_URLS = [
"https://api.ipify.org",
"https://checkip.amazonaws.com",
"https://ifconfig.me/ip",
];
async function resolveExitIp(proxyUrl: string): Promise<string | null> {
// Node.js fetch doesn't support proxy natively — use a CONNECT tunnel via http
// For simplicity, use a direct HTTP request to a plain-text IP echo service
// through the proxy using Node's http module
try {
const { default: http } = await import("node:http");
const { default: https } = await import("node:https");
const proxyUrlObj = new URL(proxyUrl);
for (const echoUrl of IP_ECHO_URLS) {
try {
const ip = await new Promise<string | null>((resolve, reject) => {
const targetUrl = new URL(echoUrl);
const connectReq = http.request({
host: proxyUrlObj.hostname,
port: parseInt(proxyUrlObj.port || "80", 10),
method: "CONNECT",
path: `${targetUrl.hostname}:443`,
headers: proxyUrlObj.username
? {
"Proxy-Authorization":
"Basic " +
Buffer.from(
`${decodeURIComponent(proxyUrlObj.username)}:${decodeURIComponent(proxyUrlObj.password || "")}`
).toString("base64"),
}
: {},
timeout: 10_000,
});
connectReq.on("connect", (_res, socket) => {
const req = https.request(
echoUrl,
{ socket, timeout: 5_000 } as any,
(res) => {
let data = "";
res.on("data", (chunk: Buffer) => (data += chunk.toString()));
res.on("end", () => {
const ip = data.trim();
resolve(net.isIP(ip) ? ip : null);
});
}
);
req.on("error", () => resolve(null));
req.end();
});
connectReq.on("error", () => resolve(null));
connectReq.on("timeout", () => {
connectReq.destroy();
resolve(null);
});
connectReq.end();
});
if (ip) return ip;
} catch {
continue;
}
}
} catch {
// Fallback: couldn't import http modules
}
return null;
}
// ---------------------------------------------------------------------------
// GeoIP database management
// ---------------------------------------------------------------------------
function getGeoipDir(): string {
return path.join(getCacheDir(), "geoip");
}
async function ensureGeoipDb(): Promise<string | null> {
const dir = getGeoipDir();
const dbPath = path.join(dir, GEOIP_DB_FILENAME);
if (fs.existsSync(dbPath)) {
maybeTriggerUpdate(dbPath);
return dbPath;
}
try {
await downloadGeoipDb(dbPath);
return dbPath;
} catch {
return null;
}
}
async function downloadGeoipDb(dest: string): Promise<void> {
const dir = path.dirname(dest);
fs.mkdirSync(dir, { recursive: true });
console.log("[cloakbrowser] Downloading GeoIP database (~70 MB)…");
const tmpPath = `${dest}.tmp.${Date.now()}`;
try {
const response = await fetch(GEOIP_DB_URL, { redirect: "follow" });
if (!response.ok || !response.body) {
throw new Error(`HTTP ${response.status}`);
}
const fileStream = createWriteStream(tmpPath);
const reader = response.body.getReader();
for (;;) {
const { done, value } = await reader.read();
if (done) break;
fileStream.write(value);
}
await new Promise<void>((resolve, reject) => {
fileStream.end(() => resolve());
fileStream.on("error", reject);
});
fs.renameSync(tmpPath, dest);
console.log(`[cloakbrowser] GeoIP database ready: ${dest}`);
} catch (err) {
if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
throw err;
}
}
function maybeTriggerUpdate(dbPath: string): void {
try {
const age = Date.now() - fs.statSync(dbPath).mtimeMs;
if (age < GEOIP_UPDATE_INTERVAL_MS) return;
} catch {
return;
}
// Fire-and-forget background update
downloadGeoipDb(dbPath).catch(() => {});
}
+33 -4
View File
@@ -26,7 +26,8 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
const { chromium } = await import("playwright-core");
const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
const args = buildArgs(options);
const resolved = await maybeResolveGeoip(options);
const args = buildArgs({ ...options, ...resolved });
const browser = await chromium.launch({
executablePath: binaryPath,
@@ -59,15 +60,17 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
export async function launchContext(
options: LaunchContextOptions = {}
): Promise<BrowserContext> {
const browser = await launch(options);
// Resolve geoip BEFORE launch() to avoid double-resolution
const resolved = await maybeResolveGeoip(options);
const browser = await launch({ ...options, ...resolved, geoip: false });
let context: BrowserContext;
try {
context = await browser.newContext({
...(options.userAgent ? { userAgent: options.userAgent } : {}),
...(options.viewport ? { viewport: options.viewport } : {}),
...(options.locale ? { locale: options.locale } : {}),
...(options.timezoneId ? { timezoneId: options.timezoneId } : {}),
...(resolved.locale ? { locale: resolved.locale } : {}),
...(resolved.timezone ? { timezoneId: resolved.timezone } : {}),
});
} catch (err) {
await browser.close();
@@ -88,6 +91,25 @@ export async function launchContext(
// Internal
// ---------------------------------------------------------------------------
async function maybeResolveGeoip(
options: LaunchOptions
): Promise<{ timezone?: string; locale?: string }> {
if (!options.geoip || !options.proxy) return { timezone: options.timezone, locale: options.locale };
if (options.timezone && options.locale) return { timezone: options.timezone, locale: options.locale };
const { resolveProxyGeo } = await import("./geoip.js");
const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(options.proxy);
return {
timezone: options.timezone ?? geoTz ?? undefined,
locale: options.locale ?? geoLocale ?? undefined,
};
}
/** @internal Exposed for unit tests only. */
export function _buildArgsForTest(options: LaunchOptions): string[] {
return buildArgs(options);
}
function buildArgs(options: LaunchOptions): string[] {
const args: string[] = [];
if (options.stealthArgs !== false) {
@@ -96,5 +118,12 @@ function buildArgs(options: LaunchOptions): string[] {
if (options.args) {
args.push(...options.args);
}
// Timezone/locale flags — always inject when set
if (options.timezone) {
args.push(`--timezone=${options.timezone}`);
}
if (options.locale) {
args.push(`--lang=${options.locale}`);
}
return args;
}
+22 -1
View File
@@ -26,7 +26,8 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
const puppeteer = await import("puppeteer-core");
const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
const args = buildArgs(options);
const resolved = await maybeResolveGeoip(options);
const args = buildArgs({ ...options, ...resolved });
// Puppeteer handles proxy via CLI args, not a separate option.
// Chromium's --proxy-server does NOT support inline credentials,
@@ -66,6 +67,20 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
// Internal
// ---------------------------------------------------------------------------
async function maybeResolveGeoip(
options: LaunchOptions
): Promise<{ timezone?: string; locale?: string }> {
if (!options.geoip || !options.proxy) return { timezone: options.timezone, locale: options.locale };
if (options.timezone && options.locale) return { timezone: options.timezone, locale: options.locale };
const { resolveProxyGeo } = await import("./geoip.js");
const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(options.proxy);
return {
timezone: options.timezone ?? geoTz ?? undefined,
locale: options.locale ?? geoLocale ?? undefined,
};
}
function buildArgs(options: LaunchOptions): string[] {
const args: string[] = [];
if (options.stealthArgs !== false) {
@@ -74,5 +89,11 @@ function buildArgs(options: LaunchOptions): string[] {
if (options.args) {
args.push(...options.args);
}
if (options.timezone) {
args.push(`--timezone=${options.timezone}`);
}
if (options.locale) {
args.push(`--lang=${options.locale}`);
}
return args;
}
+6
View File
@@ -11,6 +11,12 @@ export interface LaunchOptions {
args?: string[];
/** Include default stealth fingerprint args (default: true). Set false to use custom --fingerprint flags. */
stealthArgs?: boolean;
/** IANA timezone, e.g. "America/New_York". Sets --timezone binary flag. */
timezone?: string;
/** BCP 47 locale, e.g. "en-US". Sets --lang binary flag. */
locale?: string;
/** Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib). */
geoip?: boolean;
/** Raw options passed directly to playwright/puppeteer launch(). */
launchOptions?: Record<string, unknown>;
}
+45
View File
@@ -0,0 +1,45 @@
import { describe, it, expect } from "vitest";
import { COUNTRY_LOCALE_MAP, resolveProxyIp } from "../src/geoip.js";
describe("resolveProxyIp", () => {
it("returns literal IPv4 from proxy URL", async () => {
expect(await resolveProxyIp("http://10.50.96.5:8888")).toBe("10.50.96.5");
});
it("handles proxy URL with credentials", async () => {
expect(await resolveProxyIp("http://user:pass@10.50.96.5:8888")).toBe(
"10.50.96.5"
);
});
it("resolves localhost", async () => {
const ip = await resolveProxyIp("http://localhost:8888");
expect(ip).toBeTruthy();
expect(["127.0.0.1", "::1"]).toContain(ip);
});
it("returns null for invalid URL", async () => {
expect(await resolveProxyIp("not-a-url")).toBeNull();
});
it("returns null for empty string", async () => {
expect(await resolveProxyIp("")).toBeNull();
});
});
describe("COUNTRY_LOCALE_MAP", () => {
it("contains common countries", () => {
for (const code of ["US", "GB", "DE", "FR", "JP", "BR", "IL", "RU"]) {
expect(COUNTRY_LOCALE_MAP[code]).toBeDefined();
}
});
it("values are BCP 47 language-REGION format", () => {
for (const [code, locale] of Object.entries(COUNTRY_LOCALE_MAP)) {
const parts = locale.split("-");
expect(parts).toHaveLength(2);
expect(parts[0]).toMatch(/^[a-z]{2,3}$/);
expect(parts[1]).toMatch(/^[A-Z]{2}$/);
}
});
});