ipv6-bridge 1.0.0 → 2.1.1

package/src/cache.js

@@ -0,0 +1,108 @@
+/**
+ * IPv6 Bridge - Bounded TTL cache
+ *
+ * A small LRU cache with per-entry expiry, used to avoid a DNS lookup on every
+ * single request.
+ *
+ * Note on TTLs: entries expire after a fixed, configurable interval rather than
+ * the record's own DNS TTL. The bridge resolves through dns.lookup (the system
+ * resolver), which does not expose TTLs — that is a deliberate trade, because
+ * the alternative, dns.resolve*, ignores the hosts file and DoH configuration
+ * and fails outright on many modern hosts.
+ *
+ * @module cache
+ */
+
+class TtlCache {
+  /**
+   * @param {object} [options] - Cache options
+   * @param {number} [options.max=1000] - Maximum number of entries
+   * @param {number} [options.ttl=30000] - Entry lifetime in milliseconds
+   */
+  constructor({ max = 1000, ttl = 30000 } = {}) {
+    this.max = max;
+    this.ttl = ttl;
+    this.entries = new Map();
+    this.hits = 0;
+    this.misses = 0;
+    this.expirations = 0;
+  }
+
+  /**
+   * Read a live entry.
+   *
+   * @param {string} key - Cache key
+   * @returns {*} The stored value, or undefined if absent or expired
+   */
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      this.misses += 1;
+      return undefined;
+    }
+
+    if (entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      this.expirations += 1;
+      this.misses += 1;
+      return undefined;
+    }
+
+    // Refresh recency for LRU eviction.
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    this.hits += 1;
+    return entry.value;
+  }
+
+  /**
+   * Store an entry, evicting the least recently used if the cache is full.
+   *
+   * @param {string} key - Cache key
+   * @param {*} value - Value to store
+   * @param {number} [ttl] - Override lifetime for this entry
+   */
+  set(key, value, ttl = this.ttl) {
+    if (this.entries.has(key)) this.entries.delete(key);
+    this.entries.set(key, { value, expiresAt: Date.now() + ttl });
+
+    while (this.entries.size > this.max) {
+      const oldest = this.entries.keys().next().value;
+      this.entries.delete(oldest);
+    }
+  }
+
+  /** Remove every entry. */
+  clear() {
+    this.entries.clear();
+  }
+
+  /** Drop expired entries without waiting for them to be read. */
+  prune() {
+    const now = Date.now();
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= now) {
+        this.entries.delete(key);
+        this.expirations += 1;
+      }
+    }
+  }
+
+  /**
+   * @returns {{size: number, max: number, ttl: number, hits: number, misses: number, hitRate: number, expirations: number}}
+   */
+  stats() {
+    const lookups = this.hits + this.misses;
+    return {
+      size: this.entries.size,
+      max: this.max,
+      ttl: this.ttl,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: lookups === 0 ? 0 : Number((this.hits / lookups).toFixed(4)),
+      expirations: this.expirations,
+    };
+  }
+}
+
+module.exports = { TtlCache };

package/src/cli.js

@@ -3,97 +3,314 @@
 /**
  * IPv6 Bridge - Command-Line Interface
  *
- * Usage:
- *   npx ipv6-bridge start          Start the bridge (auto-detects if needed)
- *   npx ipv6-bridge --help         Show this help message
- *   npx ipv6-bridge --version      Show version
- *
- * Environment variables:
- *   IPV6_BRIDGE_PORT=<port>        Port to listen on (default: 8080)
- *   FORCE_BRIDGE=1                 Start even if bridge is not needed
- *   NAT64_PREFIX=<prefix>          Custom NAT64 prefix (default: 64:ff9b::)
- *
- * Stop the bridge with Ctrl+C or SIGTERM.
+ * Commands:
+ *   start     Start the bridge (auto-detects whether it is needed)
+ *   doctor    Diagnose IPv6, DNS64 and NAT64 on this network
+ *   status    Report what a running bridge is doing
  *
  * @file CLI entry point for IPv6 Bridge
  */
 
-const { start, stop } = require('./index');
-const { DEFAULT_PORT } = require('./config');
+const http = require('http');
 const { version } = require('../package.json');
 
-const HELP_TEXT = `
+let config;
+let bridge;
+try {
+  config = require('./config');
+  bridge = require('./index');
+} catch (err) {
+  // Configuration is validated at load time so misconfiguration fails here
+  // rather than as unexplainable connection errors later.
+  console.error(`Configuration error: ${err.message}`);
+  console.error('\nRun "ipv6-bridge --help" to see the accepted values.');
+  process.exit(1);
+}
+
+const { start, stop } = bridge;
+
+const SHORT_HELP = `
 IPv6 Bridge v${version}
-Local DNS64/NAT64 proxy for IPv6-only networks.
+Access IPv4-only sites from an IPv6-only network.
+
+Usage: ipv6-bridge <command>
+
+Commands:
+  start     Start the proxy (auto-detects whether it is needed)
+  doctor    Diagnose IPv6, DNS64 and NAT64 on this network
+  status    Show what a running bridge is doing
+
+Run "ipv6-bridge --help" for all options and examples.
+`.trim();
+
+const FULL_HELP = `
+IPv6 Bridge v${version}
+Access IPv4-only sites from an IPv6-only network, without kernel modules or
+admin rights. Runs a local DNS64/NAT64-aware proxy in user space.
+
+USAGE
+  ipv6-bridge <command>
+
+COMMANDS
+  start                Start the proxy. Exits immediately if the bridge is not
+                       needed (IPv4 already works, or NAT64 already works).
+  doctor               Check resolvers, IPv4/IPv6 reachability, NAT64 gateway
+                       availability, prefix configuration and listener exposure.
+                       Exits non-zero if any check fails.
+  status               Query a running bridge and report whether traffic is
+                       actually being translated.
+  --help, -h           Show this message
+  --version, -v        Show the version number
+
+GETTING STARTED
+  ipv6-bridge doctor                     Find out whether you need the bridge
+  ipv6-bridge start                      Start it
+  ipv6-bridge status                     Confirm it is translating traffic
 
-Usage:
-  ipv6-bridge start           Start the bridge proxy
-  ipv6-bridge --help, -h      Show this help message
-  ipv6-bridge --version, -v   Show version number
+EXAMPLES
+  # Start on a different port
+  IPV6_BRIDGE_PORT=9090 ipv6-bridge start
 
-Environment variables:
-  IPV6_BRIDGE_PORT             Port to listen on (default: ${DEFAULT_PORT})
-  FORCE_BRIDGE                 Set to any value to force start
-  NAT64_PREFIX                 Custom NAT64 prefix (default: 64:ff9b::)
+  # Try it on a normal dual-stack network (detection would otherwise skip it)
+  FORCE_BRIDGE=1 ipv6-bridge start
+
+  # Also serve SOCKS5, so ssh / git / database clients can use it
+  IPV6_BRIDGE_SOCKS_PORT=1080 ipv6-bridge start
+
+  # Share it with a trusted LAN, with credentials required
+  IPV6_BRIDGE_HOST=0.0.0.0 IPV6_BRIDGE_AUTH=user:secret \\
+  IPV6_BRIDGE_ALLOW=192.168.1.0/24 ipv6-bridge start
+
+  # Reach internal hosts directly instead of through NAT64
+  IPV6_BRIDGE_BYPASS='*.internal.company.com,10.0.0.0/8' ipv6-bridge start
+
+  # Use a prefix your operator assigned instead of the well-known one
+  NAT64_PREFIX=2001:db8:122:344::/64 ipv6-bridge start
+
+CONNECTING CLIENTS
+  Browser / system proxy   127.0.0.1:${config.DEFAULT_PORT}
+  Automatic (PAC) config   http://127.0.0.1:${config.DEFAULT_PORT}/proxy.pac
+  curl                     curl -x http://127.0.0.1:${config.DEFAULT_PORT} https://example.com
+  git over SOCKS5          git config --global http.proxy socks5h://127.0.0.1:1080
+  ssh over SOCKS5          ssh -o ProxyCommand='nc -X 5 -x 127.0.0.1:1080 %h %p' host
+
+ENDPOINTS (while running)
+  /healthz        Liveness probe; reachable even when auth is enabled
+  /status         JSON: counters, routing modes, DNS cache, active prefix
+  /metrics        The same data in Prometheus format
+  /proxy.pac      Proxy auto-configuration file for browsers
+
+CONFIGURATION — network
+  IPV6_BRIDGE_PORT              Proxy listen port (default: 8080)
+  IPV6_BRIDGE_HOST              Interface to bind (default: 127.0.0.1)
+  IPV6_BRIDGE_SOCKS_PORT        Serve SOCKS5 on this port (default: off)
+  NAT64_PREFIX                  NAT64 prefix with optional /length
+                                (default: 64:ff9b::/96; RFC 6052 allows
+                                /32, /40, /48, /56, /64, /96)
+  IPV6_BRIDGE_DISCOVER_PREFIX   Discover the prefix via RFC 7050 (default: on)
+
+CONFIGURATION — access control
+  IPV6_BRIDGE_AUTH              Require "user:password" from clients
+  IPV6_BRIDGE_ALLOW             Client allowlist, e.g. "192.168.1.0/24"
+  IPV6_BRIDGE_BYPASS            Hosts to reach directly, e.g. "*.internal.com"
+
+CONFIGURATION — behaviour
+  FORCE_BRIDGE                  Start even when detection says it is not needed
+  IPV6_BRIDGE_CONTROL           Serve the endpoints above (default: on)
+  LOG_LEVEL                     silent, error, warn, info, debug (default: info)
+
+CONFIGURATION — tuning
+  IPV6_DNS_TIMEOUT              DNS timeout in ms (default: 5000)
+  IPV6_DNS_CACHE_TTL            DNS cache lifetime in ms (default: 30000)
+  IPV6_DNS_CACHE_MAX            Maximum cached entries (default: 1000)
+  IPV6_CONN_TIMEOUT             Connection timeout in ms (default: 10000)
+  IPV6_CONNECT_ATTEMPT_TIMEOUT  Per-address timeout before trying the next
+                                candidate, in ms (default: 3000)
+  IPV6_KEEP_ALIVE_MS            Idle lifetime of pooled sockets (default: 15000)
+  IPV6_MAX_SOCKETS_PER_HOST     Pooled sockets per host (default: 64)
+
+CONFIGURATION — detection endpoints
+  IPV4_TEST_URL                 Used to detect working IPv4
+  IPV6_TEST_URL                 Used to detect working IPv6
+  NAT64_TEST_HOST               IPv4-only host used to probe for NAT64
+
+SECURITY
+  The proxy binds to loopback and requires no credentials by default. If you
+  set IPV6_BRIDGE_HOST to a routable address, also set IPV6_BRIDGE_AUTH or
+  IPV6_BRIDGE_ALLOW — otherwise anyone who can reach this machine can relay
+  traffic through it under your IP address.
+
+DOCUMENTATION
+  Guide         docs/GUIDE.md      (when to use it, worked examples)
+  API           docs/API.md        (programmatic API, every setting)
+  Architecture  docs/ARCHITECTURE.md
 
 Stop the bridge with Ctrl+C or by sending SIGTERM.
 `.trim();
 
+/** Fetch JSON over HTTP with a short timeout. */
+function fetchJson(options) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(options, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          reject(new Error(`unexpected response from ${options.path}`));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(3000, () => {
+      req.destroy();
+      reject(new Error('request timed out'));
+    });
+  });
+}
+
+async function runStatus() {
+  const host = config.isLoopbackBind() ? '127.0.0.1' : config.BIND_HOST;
+  const port = config.DEFAULT_PORT;
+
+  let status;
+  try {
+    status = await fetchJson({ host, port, path: '/status' });
+  } catch (err) {
+    console.error(`No bridge is responding on ${host}:${port} (${err.message}).`);
+    console.error('\nStart one with "ipv6-bridge start", or set IPV6_BRIDGE_PORT');
+    console.error('if it is running on another port.');
+    process.exit(1);
+  }
+
+  const { counters, routes, dnsCache } = status;
+  const translated = routes.nat64;
+  const untranslated = routes.directIpv4 + routes.directIpv4Fallback;
+
+  console.log(`\nIPv6 Bridge on ${host}:${port}`);
+  console.log(`  Uptime          ${status.uptimeSeconds}s`);
+  console.log(`  NAT64 prefix    ${status.nat64Prefix}`);
+  console.log('');
+  console.log(`  HTTP requests   ${counters.httpRequests}`);
+  console.log(`  CONNECT tunnels ${counters.connectRequests}`);
+  console.log(`  SOCKS5 sessions ${counters.socksRequests}`);
+  console.log(`  Errors          ${counters.proxyErrors} (${counters.timeouts} timeouts)`);
+  console.log('');
+  console.log('  Routing');
+  console.log(`    via NAT64          ${routes.nat64}`);
+  console.log(`    native IPv6        ${routes.nativeIpv6}`);
+  console.log(`    direct IPv4        ${routes.directIpv4}`);
+  console.log(`    untranslated fallback ${routes.directIpv4Fallback}`);
+  console.log('');
+  console.log(`  DNS cache       ${dnsCache.size} entries, hit rate ${dnsCache.hitRate}`);
+  console.log('');
+
+  const routed = Object.values(routes).reduce((sum, count) => sum + count, 0);
+
+  if (routed === 0) {
+    console.log('  No traffic yet. Send a request through the proxy, then check again.');
+  } else if (translated > 0) {
+    console.log(`  Translating ${Math.round(status.translationRate * 100)}% of connections`);
+    console.log('  that needed it. The bridge is doing its job.');
+  } else if (routes.directIpv4Fallback > 0) {
+    console.log('  WARNING: connections fell back to untranslated IPv4.');
+    console.log('  DNS64 is failing, so the bridge is not translating anything.');
+    console.log('  Run "ipv6-bridge doctor" to find out why.');
+  } else if (untranslated > 0) {
+    console.log('  Nothing needed translating: these destinations were private or');
+    console.log('  loopback addresses, which are always reached directly.');
+  } else {
+    console.log('  Nothing needed translating: every destination already had an');
+    console.log('  IPv6 address, so no NAT64 synthesis was required.');
+  }
+  console.log('');
+}
+
 const command = process.argv[2];
-const port = process.env.IPV6_BRIDGE_PORT
-  ? parseInt(process.env.IPV6_BRIDGE_PORT, 10)
-  : DEFAULT_PORT;
 
-if (command === '--help' || command === '-h' || !command) {
-  console.log(HELP_TEXT);
+if (!command) {
+  console.log(SHORT_HELP);
   process.exit(0);
 }
 
-if (command === '--version' || command === '-v') {
+if (command === '--help' || command === '-h' || command === 'help') {
+  console.log(FULL_HELP);
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v' || command === 'version') {
   console.log(version);
   process.exit(0);
 }
 
-if (command === 'start') {
-  if (Number.isNaN(port) || port < 1 || port > 65535) {
-    console.error(`Error: Invalid port "${process.env.IPV6_BRIDGE_PORT}". Must be 1-65535.`);
+if (command === 'doctor') {
+  const { diagnose, format } = require('./doctor');
+  diagnose()
+    .then((report) => {
+      console.log(format(report));
+      process.exit(report.summary.fail > 0 ? 1 : 0);
+    })
+    .catch((err) => {
+      console.error(`Diagnostics failed: ${err.message}`);
+      process.exit(1);
+    });
+} else if (command === 'status') {
+  runStatus().catch((err) => {
+    console.error(`Error: ${err.message}`);
     process.exit(1);
-  }
+  });
+} else if (command === 'start') {
+  let shuttingDown = false;
+  const shutdown = (exitCode = 0) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log('\nStopping IPv6 Bridge...');
+    stop()
+      .then(() => process.exit(exitCode))
+      .catch(() => process.exit(1));
+  };
 
-  start(port)
+  start(config.DEFAULT_PORT)
     .then((server) => {
       if (!server) {
+        console.log('Run "ipv6-bridge doctor" for details, or set FORCE_BRIDGE=1 to start anyway.');
         process.exit(0);
       }
-      console.log(`\nIPv6 Bridge running on http://localhost:${port}`);
-      console.log(`Configure your browser/system proxy to localhost:${port}\n`);
+      const { port } = server.address();
+      const prefix = config.getPrefix();
+
+      console.log(`\nIPv6 Bridge running on http://${config.BIND_HOST}:${port}`);
+      console.log(`Configure your browser/system proxy to ${config.BIND_HOST}:${port}`);
+      console.log(`NAT64 prefix: ${prefix.prefix}/${prefix.length}`);
+      if (config.SOCKS_PORT) {
+        console.log(`SOCKS5 running on ${config.BIND_HOST}:${config.SOCKS_PORT}`);
+      }
+      if (config.CONTROL_ENDPOINTS) {
+        console.log(`Status: http://${config.BIND_HOST}:${port}/status`);
+        console.log(`PAC:    http://${config.BIND_HOST}:${port}/proxy.pac`);
+      }
+      console.log('');
     })
     .catch((err) => {
       console.error(`Error: ${err.message}`);
       process.exit(1);
     });
 
-  // Graceful shutdown on SIGINT (Ctrl+C) and SIGTERM (container/daemon stop)
-  function shutdown() {
-    console.log('\nStopping IPv6 Bridge...');
-    stop().then(() => process.exit(0));
-  }
-
-  process.on('SIGINT', shutdown);
-  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', () => shutdown(0));
+  process.on('SIGTERM', () => shutdown(0));
 
-  // Catch unhandled errors to prevent silent crashes
   process.on('uncaughtException', (err) => {
     console.error('Uncaught exception:', err.message);
-    stop().then(() => process.exit(1));
+    shutdown(1);
   });
 
   process.on('unhandledRejection', (reason) => {
     console.error('Unhandled rejection:', reason);
-    stop().then(() => process.exit(1));
+    shutdown(1);
   });
 } else {
   console.error(`Unknown command: "${command}"\n`);
-  console.log(HELP_TEXT);
+  console.log(SHORT_HELP);
   process.exit(1);
 }

package/src/config.js

@@ -1,42 +1,177 @@
 /**
  * IPv6 Bridge - Configuration
  *
- * RFC 6052 Well-Known NAT64 Prefix and network test constants.
- * All values can be overridden via environment variables.
+ * All values can be overridden via environment variables. Invalid values throw
+ * at load time rather than surfacing later as unexplainable connection failures.
  *
  * @module config
  */
 
+const { parsePrefix, WELL_KNOWN_PREFIX_ADDRESS } = require('./ipv6');
+const netmatch = require('./netmatch');
+
+/** The RFC 6052 section 3.1 well-known prefix. */
+const WELL_KNOWN_PREFIX = WELL_KNOWN_PREFIX_ADDRESS;
+
+function intFromEnv(name, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === '') return fallback;
+
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new Error(`${name} must be a positive integer, got "${raw}"`);
+  }
+
+  const value = Number(trimmed);
+  if (value < min || value > max) {
+    throw new Error(`${name} must be between ${min} and ${max}, got "${raw}"`);
+  }
+  return value;
+}
+
+function boolFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === '') return fallback;
+  return !['0', 'false', 'no', 'off'].includes(raw.trim().toLowerCase());
+}
+
+/**
+ * The active NAT64 prefix. Held in a mutable slot because RFC 7050 discovery
+ * can replace the configured default with the one the network actually uses.
+ */
+let activePrefix;
+try {
+  activePrefix = parsePrefix(process.env.NAT64_PREFIX || `${WELL_KNOWN_PREFIX}/96`);
+} catch (err) {
+  throw new Error(`Invalid NAT64_PREFIX: ${err.message}`);
+}
+
+const configuredPrefix = activePrefix;
+
+/** @returns {{prefix: string, length: number, bytes: Buffer}} The active prefix */
+function getPrefix() {
+  return activePrefix;
+}
+
+/**
+ * Replace the active NAT64 prefix (used by RFC 7050 discovery).
+ *
+ * @param {{prefix: string, length: number, bytes: Buffer}} prefix - Parsed prefix
+ */
+function setPrefix(prefix) {
+  activePrefix = prefix;
+}
+
+/** Restore the prefix that was configured at startup. */
+function resetPrefix() {
+  activePrefix = configuredPrefix;
+}
+
+/** @returns {boolean} true if the active prefix is the well-known one */
+function usingWellKnownPrefix() {
+  return activePrefix.prefix === WELL_KNOWN_PREFIX;
+}
+
+function parseAuth() {
+  const raw = process.env.IPV6_BRIDGE_AUTH;
+  if (!raw || raw.trim() === '') return null;
+
+  const separator = raw.indexOf(':');
+  if (separator < 1 || separator === raw.length - 1) {
+    throw new Error('IPV6_BRIDGE_AUTH must be in "user:password" form');
+  }
+
+  return {
+    username: raw.slice(0, separator),
+    password: raw.slice(separator + 1),
+    header: 'Basic ' + Buffer.from(raw).toString('base64'),
+  };
+}
+
+const BIND_HOST = process.env.IPV6_BRIDGE_HOST || '127.0.0.1';
+const AUTH = parseAuth();
+const ALLOW_FROM = netmatch.compile(process.env.IPV6_BRIDGE_ALLOW);
+const BYPASS = netmatch.compile(process.env.IPV6_BRIDGE_BYPASS);
+
+function isLoopbackBind(host = BIND_HOST) {
+  return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+}
+
 module.exports = {
-  /**
-   * NAT64 Prefix (RFC 6052)
-   *
-   * The well-known prefix used to synthesize IPv6 addresses from IPv4.
-   * Override with the NAT64_PREFIX environment variable if your ISP
-   * uses a non-standard prefix.
-   *
-   * Example: 192.0.2.1 → 64:ff9b::c000:0201
-   *
-   * @see https://tools.ietf.org/html/rfc6052#section-2.1
-   */
-  NAT64_PREFIX: process.env.NAT64_PREFIX || '64:ff9b::',
+  WELL_KNOWN_PREFIX,
+  getPrefix,
+  setPrefix,
+  resetPrefix,
+  usingWellKnownPrefix,
+  isLoopbackBind,
+
+  /** Configured NAT64 prefix as written by the user. */
+  NAT64_PREFIX: configuredPrefix.prefix,
+  NAT64_PREFIX_LENGTH: configuredPrefix.length,
+
+  /** Default proxy listen port. */
+  DEFAULT_PORT: intFromEnv('IPV6_BRIDGE_PORT', 8080, { max: 65535 }),
 
   /**
-   * Default port for the proxy server.
-   * Override with the IPV6_BRIDGE_PORT environment variable.
+   * Interface the proxy binds to. Defaults to loopback: without authentication
+   * a routable bind turns the host into an open relay.
    */
-  DEFAULT_PORT: 8080,
+  BIND_HOST,
+
+  /** Optional SOCKS5 listener port; disabled when unset. */
+  SOCKS_PORT: process.env.IPV6_BRIDGE_SOCKS_PORT
+    ? intFromEnv('IPV6_BRIDGE_SOCKS_PORT', 1080, { max: 65535 })
+    : null,
+
+  /** Optional Basic credentials required from proxy clients. */
+  AUTH,
+
+  /** Client addresses permitted to use the proxy (empty means "any"). */
+  ALLOW_FROM,
+
+  /** Hosts that should bypass NAT64 and be reached directly. */
+  BYPASS,
+
+  /** Whether to serve /healthz, /status, /metrics and /proxy.pac. */
+  CONTROL_ENDPOINTS: boolFromEnv('IPV6_BRIDGE_CONTROL', true),
+
+  /** Whether to attempt RFC 7050 NAT64 prefix discovery at startup. */
+  PREFIX_DISCOVERY: boolFromEnv('IPV6_BRIDGE_DISCOVER_PREFIX', true),
+
+  /** DNS resolution timeout in milliseconds. */
+  DNS_TIMEOUT: intFromEnv('IPV6_DNS_TIMEOUT', 5000),
+
+  /** Lifetime of a cached DNS result, in milliseconds. */
+  DNS_CACHE_TTL: intFromEnv('IPV6_DNS_CACHE_TTL', 30000),
+
+  /** Maximum number of cached DNS results. */
+  DNS_CACHE_MAX: intFromEnv('IPV6_DNS_CACHE_MAX', 1000),
+
+  /** Proxy connection timeout in milliseconds. */
+  CONNECTION_TIMEOUT: intFromEnv('IPV6_CONN_TIMEOUT', 10000),
+
+  /** How long to wait for one candidate address before trying the next. */
+  CONNECT_ATTEMPT_TIMEOUT: intFromEnv('IPV6_CONNECT_ATTEMPT_TIMEOUT', 3000),
+
+  /** Idle keep-alive socket lifetime for pooled upstream connections. */
+  KEEP_ALIVE_MS: intFromEnv('IPV6_KEEP_ALIVE_MS', 15000),
+
+  /** Maximum pooled sockets per upstream host. */
+  MAX_SOCKETS_PER_HOST: intFromEnv('IPV6_MAX_SOCKETS_PER_HOST', 64),
 
   /**
-   * Test URL for IPv6 connectivity detection.
-   * Must be a server with IPv6 support.
+   * Endpoint used to test native IPv6 connectivity. Overridable so detection
+   * still works where the default host is unreachable or blocked.
    */
-  IPV6_GOOGLE: 'http://ipv6.google.com',
+  IPV6_TEST_URL: process.env.IPV6_TEST_URL || 'http://ipv6.google.com',
+
+  /** Endpoint used to test whether plain IPv4 connectivity already works. */
+  IPV4_TEST_URL: process.env.IPV4_TEST_URL || 'http://ipv4.google.com',
 
   /**
-   * Hostname for NAT64 availability testing.
-   * An IPv4-only hostname that should be reachable via NAT64
-   * if the ISP gateway is properly configured.
+   * IPv4-only hostname used to probe for an upstream NAT64 gateway. Resolved
+   * via DNS64 and connected to over IPv6; success means the ISP already
+   * provides NAT64 and the bridge is unnecessary.
    */
-  IPV4_GOOGLE: 'ipv4.google.com',
+  NAT64_TEST_HOST: process.env.NAT64_TEST_HOST || 'ipv4.google.com',
 };