ipv6-bridge 1.0.0 → 2.1.1

package/docs/ROADMAP.md

@@ -0,0 +1,69 @@
+# Roadmap & Project Vision
+
+**IPv6 Bridge** is a zero-dependency DNS64/NAT64 bridge for hosts stranded on
+IPv6-only networks. This document tracks what has shipped and what is still
+open.
+
+## Shipped in 2.0
+
+These were the Tier 1 and Tier 2 items on the previous roadmap.
+
+- **DNS cache** — bounded LRU with TTL expiry, so repeat requests skip resolution.
+- **Connection pooling & keep-alive** — upstream sockets are reused across requests.
+- **Connection failover** — candidates are tried in preference order (native IPv6,
+  then NAT64, then direct IPv4) instead of failing on the first unreachable address.
+- **Improved network detection** — IPv4 reachability is checked first, so the bridge
+  no longer activates on healthy dual-stack networks.
+- **Custom NAT64 prefix formats** — every RFC 6052 prefix length (`/32`, `/40`,
+  `/48`, `/56`, `/64`, `/96`), validated against the RFC's own test vectors.
+- **NAT64 prefix discovery (RFC 7050)** — the network's real prefix is discovered
+  from `ipv4only.arpa` rather than assumed.
+- **SOCKS5 support** — ssh, git, databases and any other TCP protocol.
+- **PAC (Proxy Auto-Configuration)** — served at `/proxy.pac`.
+- **Per-domain routing policies** — `IPV6_BRIDGE_BYPASS` for split routing.
+- **Authentication** — Basic credentials and a client CIDR allowlist, enforced on
+  the HTTP, CONNECT and SOCKS5 paths.
+- **Observability** — `/healthz`, `/status` and Prometheus `/metrics`, including a
+  `translationRate` that shows whether translation is actually happening.
+- **Diagnostics** — `ipv6-bridge doctor`.
+
+## Open
+
+### Reliability
+
+- **Full Happy Eyeballs (RFC 8305)** — connection attempts are currently
+  sequential with a per-attempt timeout. True Happy Eyeballs races families with
+  a staggered delay, which lowers worst-case latency on partially broken networks.
+- **Real DNS TTLs** — the system resolver does not expose them, so the cache uses
+  a fixed TTL. Honouring real TTLs would need a resolver that reports them without
+  reintroducing the `dns.resolve*` failure mode on DoH-only hosts.
+- **Circuit breaking** — remember recently failed upstreams instead of retrying
+  every candidate on every request.
+
+### Protocol coverage
+
+- **HTTP/2 and HTTP/3 to the origin** — upstream requests are HTTP/1.1. This needs
+  a move away from Node's core `http` module for the upstream leg.
+- **SOCKS5 UDP (`UDP ASSOCIATE`)** — would extend coverage to DNS, QUIC and
+  game traffic.
+- **WebSocket** — works today inside a CONNECT tunnel, but not for plain-HTTP
+  `Upgrade` requests, which the proxy currently strips.
+
+### Operations
+
+- **Rate limiting** — per-client request and bandwidth caps for shared deployments.
+- **Structured JSON logging** — for log aggregation pipelines.
+- **Container image** — a published image with sensible defaults.
+
+### Reach
+
+- **Transparent interception** — the largest remaining adoption barrier is that
+  applications must be configured to use the proxy. A TUN-based mode would remove
+  that, at the cost of admin rights and platform-specific code, so it would need
+  to be an opt-in mode rather than a replacement for the user-space design.
+
+---
+
+*Contributions are welcome! If you're interested in tackling any of these roadmap
+items, please check out our [CONTRIBUTING.md](CONTRIBUTING.md) and open an issue
+to discuss the implementation plan.*

package/examples/basic-usage.js

@@ -5,34 +5,42 @@
  *
  * Run:
  *   node examples/basic-usage.js
+ *
+ * The bridge only starts if this machine actually needs it. To try it on a
+ * dual-stack network, force it:
+ *   FORCE_BRIDGE=1 node examples/basic-usage.js
  */
 
 const { start, stop } = require('../src/index');
 
 async function main() {
-  try {
-    console.log('Starting IPv6 Bridge...\n');
-    const server = await start(8080);
-
-    if (server) {
-      const addr = server.address();
-      console.log(`Bridge started on port ${addr.port}`);
-      console.log(`Configure your browser/system proxy to localhost:${addr.port}\n`);
-      console.log('Press Ctrl+C to stop.\n');
-
-      process.on('SIGINT', async () => {
-        console.log('\nShutting down...');
-        await stop();
-        process.exit(0);
-      });
-    } else {
-      console.log('Bridge not needed — you have IPv4 connectivity or working NAT64.');
-      process.exit(0);
-    }
-  } catch (error) {
-    console.error('Error:', error.message);
-    process.exit(1);
+  console.log('Starting IPv6 Bridge...\n');
+
+  const server = await start(8080);
+
+  if (!server) {
+    console.log('Bridge not needed — IPv4 is reachable, or NAT64 already works.');
+    console.log('Run with FORCE_BRIDGE=1 to start it anyway.');
+    return;
   }
+
+  const { port } = server.address();
+  console.log(`Bridge started on port ${port}`);
+  console.log(`Configure your browser/system proxy to 127.0.0.1:${port}`);
+  console.log(`Check what it is doing: http://127.0.0.1:${port}/status\n`);
+  console.log('Press Ctrl+C to stop.\n');
+
+  const shutdown = async () => {
+    console.log('\nShutting down...');
+    await stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
 }
 
-main();
+main().catch((error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});

package/examples/embedded-usage.js

@@ -0,0 +1,100 @@
+/**
+ * IPv6 Bridge — Embedded Usage Example
+ *
+ * Using the bridge from inside an application: no proxy, no ports, no system
+ * configuration. Outbound connections gain DNS64 translation, address-family
+ * failover and connection pooling.
+ *
+ * This is the way to use the package in a deployed service.
+ *
+ * Run:
+ *   node examples/embedded-usage.js
+ */
+
+const https = require('https');
+const net = require('net');
+const {
+  createHttpsAgent,
+  createLookup,
+  resolve,
+  getStats,
+} = require('../src/index');
+
+// One agent for the lifetime of the process: it pools connections, so creating
+// a new one per request would throw that away.
+const agent = createHttpsAgent();
+
+function get(url) {
+  return new Promise((resolve, reject) => {
+    const options = { agent, headers: { 'User-Agent': 'ipv6-bridge-example' } };
+    const req = https.get(url, options, (res) => {
+      const via = res.socket.remoteAddress;
+      res.resume();
+      res.on('end', () => resolve({ status: res.statusCode, via }));
+    });
+    req.on('error', reject);
+    req.setTimeout(15000, () => {
+      req.destroy();
+      reject(new Error('request timed out'));
+    });
+  });
+}
+
+async function main() {
+  console.log('1. Which route would be used for each destination?\n');
+  for (const host of ['example.com', '8.8.8.8', '192.168.1.1']) {
+    const candidates = await resolve(host);
+    const preferred = candidates[0];
+    console.log(`   ${host.padEnd(16)} ${preferred.host}  (${preferred.mode})`);
+    if (candidates.length > 1) {
+      console.log(`   ${''.padEnd(16)} fallbacks: ${candidates.slice(1).map((c) => c.mode).join(', ')}`);
+    }
+  }
+
+  console.log('\n2. Making real requests through the agent\n');
+  for (const url of ['https://example.com/', 'https://api.github.com/']) {
+    try {
+      const { status, via } = await get(url);
+      console.log(`   ${url.padEnd(28)} ${status}  via ${via}`);
+    } catch (err) {
+      console.log(`   ${url.padEnd(28)} failed: ${err.message}`);
+    }
+  }
+
+  console.log('\n3. Using the lookup function with a raw socket\n');
+  await new Promise((resolve) => {
+    const socket = net.connect({ host: 'example.com', port: 443, lookup: createLookup() }, () => {
+      console.log(`   connected to example.com:443 via ${socket.remoteAddress}`);
+      socket.destroy();
+      resolve();
+    });
+    socket.on('error', (err) => {
+      console.log(`   connection failed: ${err.message}`);
+      resolve();
+    });
+  });
+
+  console.log('\n4. Did translation actually happen?\n');
+  const stats = getStats();
+  console.log(`   NAT64 prefix        ${stats.nat64Prefix}`);
+  console.log(`   translated          ${stats.routes.nat64}`);
+  console.log(`   native IPv6         ${stats.routes.nativeIpv6}`);
+  console.log(`   untranslated        ${stats.routes.directIpv4 + stats.routes.directIpv4Fallback}`);
+  console.log(`   translation rate    ${stats.translationRate ?? 'n/a'}`);
+  console.log(`   DNS cache hit rate  ${stats.dnsCache.hitRate}`);
+
+  if (stats.routes.directIpv4Fallback > 0 && stats.routes.nat64 === 0) {
+    console.log('\n   WARNING: connections fell back to untranslated IPv4.');
+    console.log('   On an IPv6-only network this means DNS64 is failing.');
+    console.log('   Run "ipv6-bridge doctor" to find out why.');
+  }
+
+  // Release pooled sockets so the process can exit.
+  agent.destroy();
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  agent.destroy();
+  process.exit(1);
+});

package/examples/production-usage.js

@@ -0,0 +1,106 @@
+/**
+ * IPv6 Bridge — Production Usage Example
+ *
+ * Shows the pieces that matter when the bridge is more than a local
+ * convenience: access control, SOCKS5 for non-HTTP traffic, prefix discovery,
+ * health monitoring and a clean shutdown.
+ *
+ * Run:
+ *   FORCE_BRIDGE=1 node examples/production-usage.js
+ */
+
+const http = require('http');
+const { start, stop } = require('../src/index');
+
+const PROXY_PORT = Number(process.env.IPV6_BRIDGE_PORT) || 8080;
+const SOCKS_PORT = Number(process.env.IPV6_BRIDGE_SOCKS_PORT) || 1080;
+
+// Access control must be configured before the bridge is required, because
+// configuration is read and validated at load time.
+if (!process.env.IPV6_BRIDGE_HOST) {
+  // Loopback is the default; set IPV6_BRIDGE_HOST to expose the proxy, and
+  // always pair that with IPV6_BRIDGE_AUTH or IPV6_BRIDGE_ALLOW.
+  process.env.IPV6_BRIDGE_HOST = '127.0.0.1';
+}
+
+/** Poll /status and report whether translation is actually happening. */
+function fetchStatus(port) {
+  return new Promise((resolve, reject) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/status' }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(3000, () => {
+      req.destroy();
+      reject(new Error('status request timed out'));
+    });
+  });
+}
+
+async function main() {
+  const server = await start(PROXY_PORT, {
+    // Run RFC 7050 discovery so the network's real NAT64 prefix is used.
+    discoverPrefix: true,
+    // Serve SOCKS5 as well, for ssh/git/database clients.
+    socksPort: SOCKS_PORT,
+  });
+
+  if (!server) {
+    console.log('Bridge not needed on this network.');
+    return;
+  }
+
+  const { port } = server.address();
+  console.log(`Proxy:  http://127.0.0.1:${port}`);
+  console.log(`SOCKS5: 127.0.0.1:${SOCKS_PORT}`);
+  console.log(`Health: http://127.0.0.1:${port}/healthz`);
+  console.log(`Metrics: http://127.0.0.1:${port}/metrics\n`);
+
+  // Periodically check that the bridge is doing what it claims. A translation
+  // rate of zero alongside rising fallbacks means DNS64 is failing.
+  const monitor = setInterval(async () => {
+    try {
+      const status = await fetchStatus(port);
+      const { nat64, directIpv4Fallback } = status.routes;
+
+      if (directIpv4Fallback > 0 && nat64 === 0) {
+        console.warn(
+          `[warn] ${directIpv4Fallback} connection(s) fell back to untranslated IPv4 ` +
+          `and none were translated. Run "ipv6-bridge doctor" to find out why.`
+        );
+      } else {
+        console.log(
+          `[ok] translated=${nat64} fallback=${directIpv4Fallback} ` +
+          `rate=${status.translationRate ?? 'n/a'} ` +
+          `cache=${status.dnsCache.hitRate}`
+        );
+      }
+    } catch (err) {
+      console.error(`[error] status check failed: ${err.message}`);
+    }
+  }, 15000);
+
+  const shutdown = async (signal) => {
+    console.log(`\nReceived ${signal}, shutting down...`);
+    clearInterval(monitor);
+    await stop();
+    console.log('Stopped cleanly.');
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+main().catch((error) => {
+  console.error('Failed to start:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ipv6-bridge",
-  "version": "1.0.0",
-  "description": "Local DNS64/NAT64 proxy for IPv6-only networks — access IPv4 sites from IPv6-only environments",
+  "version": "2.1.1",
+  "description": "DNS64-aware HTTP proxy for IPv6-only networks — access IPv4 sites from IPv6-only environments",
   "type": "commonjs",
   "main": "src/index.js",
   "bin": {
@@ -9,8 +9,8 @@
   },
   "scripts": {
     "start": "node src/cli.js start",
-    "test": "node --test tests/*.test.js",
-    "demo": "cd demo-app && npm install && npm start",
+    "test": "node --test",
+    "demo": "node demo-app/server.js",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -42,9 +42,9 @@
   "files": [
     "src/",
     "examples/",
+    "docs/",
     "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "dependencies": {}
 }

package/src/agent.js

@@ -0,0 +1,271 @@
+/**
+ * IPv6 Bridge - Embeddable connection primitives
+ *
+ * Everything here lets an application use DNS64/NAT64 translation directly,
+ * without running a proxy or changing any system configuration. Outbound
+ * connections are made over native IPv6 where possible, through a synthesized
+ * NAT64 address where translation is needed, and over IPv4 as a last resort.
+ *
+ * None of this can manufacture connectivity the host does not have. It makes
+ * the host reach everything it *can* reach, regardless of address family.
+ *
+ * @module agent
+ */
+
+const http = require('http');
+const https = require('https');
+const tls = require('tls');
+const { connectWithFallback } = require('./connect');
+const { resolveCandidates } = require('./dns64');
+const config = require('./config');
+
+function shouldBypass(hostname) {
+  return !config.BYPASS.isEmpty && config.BYPASS.matches(hostname);
+}
+
+/**
+ * Open a bridged TCP connection for an agent.
+ *
+ * @param {object} options - Connection options from the agent
+ * @param {number} defaultPort - Port to use when none is given
+ * @returns {Promise<net.Socket>} Connected socket
+ */
+function openSocket(options, defaultPort) {
+  const hostname = options.host;
+  const port = Number(options.port) || defaultPort;
+  return connectWithFallback(hostname, port, { bypass: shouldBypass(hostname) })
+    .then(({ socket }) => socket);
+}
+
+/**
+ * Layer TLS onto an already-connected plaintext socket, reporting success or
+ * failure through a Node-style callback.
+ *
+ * tls.connect() can throw synchronously — a caller-supplied option such as an
+ * invalid secureProtocol or cipher list fails while it builds the security
+ * context, before any socket event fires. Left uncaught, that throw would
+ * escape as an uncaught exception and crash the embedding host application on
+ * its very first request, which is a much worse outcome than the one failed
+ * connection a caught error produces.
+ *
+ * @param {net.Socket} socket - Connected plaintext socket to upgrade
+ * @param {object} tlsOptions - Options for tls.connect
+ * @param {string} hostname - Hostname to validate the certificate against
+ * @param {(err: Error|null, socket?: tls.TLSSocket) => void} callback - Result callback
+ */
+function upgradeToTls(socket, tlsOptions, hostname, callback) {
+  let secure;
+  try {
+    secure = tls.connect({
+      ...tlsOptions,
+      socket,
+      // SNI and certificate identity must use the real hostname, never the
+      // synthesized address the plaintext socket was dialled through.
+      host: hostname,
+      servername: tlsOptions.servername || hostname,
+    });
+  } catch (err) {
+    socket.destroy();
+    callback(err);
+    return;
+  }
+
+  const onError = (err) => {
+    socket.destroy();
+    callback(err);
+  };
+
+  secure.once('error', onError);
+  secure.once('secureConnect', () => {
+    secure.removeListener('error', onError);
+    callback(null, secure);
+  });
+}
+
+/**
+ * HTTP agent that resolves through DNS64 and pools the resulting sockets.
+ *
+ * Sockets are keyed by the original hostname, so pooling is unaffected by the
+ * fact that the address actually dialled may be synthesized.
+ */
+class BridgeHttpAgent extends http.Agent {
+  constructor(options = {}) {
+    super({
+      keepAlive: true,
+      keepAliveMsecs: config.KEEP_ALIVE_MS,
+      maxSockets: config.MAX_SOCKETS_PER_HOST,
+      timeout: config.CONNECTION_TIMEOUT,
+      ...options,
+    });
+  }
+
+  createConnection(options, callback) {
+    openSocket(options, 80).then(
+      (socket) => callback(null, socket),
+      (err) => callback(err)
+    );
+  }
+}
+
+/**
+ * HTTPS agent that performs the TLS handshake over a bridged socket.
+ *
+ * The certificate is validated against the original hostname, never against
+ * the synthesized address it was reached through — otherwise validation could
+ * never succeed and users would be pushed into disabling it.
+ */
+class BridgeHttpsAgent extends https.Agent {
+  constructor(options = {}) {
+    super({
+      keepAlive: true,
+      keepAliveMsecs: config.KEEP_ALIVE_MS,
+      maxSockets: config.MAX_SOCKETS_PER_HOST,
+      timeout: config.CONNECTION_TIMEOUT,
+      ...options,
+    });
+    this.tlsOptions = options;
+  }
+
+  createConnection(options, callback) {
+    const hostname = options.host;
+
+    openSocket(options, 443).then(
+      (socket) => upgradeToTls(socket, { ...this.tlsOptions, ...options }, hostname, callback),
+      (err) => callback(err)
+    );
+  }
+}
+
+/**
+ * Create an HTTP agent backed by the bridge.
+ *
+ * @param {object} [options] - http.Agent options
+ * @returns {http.Agent} Agent for use with http.request / axios / got
+ */
+function createAgent(options) {
+  return new BridgeHttpAgent(options);
+}
+
+/**
+ * Create an HTTPS agent backed by the bridge.
+ *
+ * @param {object} [options] - https.Agent options
+ * @returns {https.Agent} Agent for use with https.request / axios / got
+ */
+function createHttpsAgent(options) {
+  return new BridgeHttpsAgent(options);
+}
+
+/**
+ * Create agents for both protocols.
+ *
+ * @param {object} [options] - Agent options applied to both
+ * @returns {{http: http.Agent, https: https.Agent}} Agents by protocol
+ */
+function createAgents(options) {
+  return {
+    http: createAgent(options),
+    https: createHttpsAgent(options),
+  };
+}
+
+/**
+ * Create a dns.lookup-compatible function that applies DNS64 synthesis.
+ *
+ * Anything accepting a `lookup` option — net.connect, http.request, most
+ * client libraries — can use this without further changes. Matches the real
+ * dns.lookup contract: `options` may be omitted, a plain object, or (per
+ * Node's documented shorthand) an integer meaning the requested address
+ * family.
+ *
+ * @returns {Function} Function with the dns.lookup signature
+ */
+function createLookup() {
+  return function bridgeLookup(hostname, options, callback) {
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    } else if (typeof options === 'number') {
+      options = { family: options };
+    } else {
+      options = options || {};
+    }
+
+    resolveCandidates(hostname).then((candidates) => {
+      const matching = options.family
+        ? candidates.filter((c) => c.family === options.family)
+        : candidates;
+
+      if (options.family && matching.length === 0) {
+        const err = new Error(
+          `No family ${options.family} address available for ${hostname}`
+        );
+        err.code = 'EAI_ADDRFAMILY';
+        callback(err);
+        return;
+      }
+
+      const selected = matching.length > 0 ? matching : candidates;
+
+      if (options.all) {
+        callback(null, selected.map((c) => ({ address: c.host, family: c.family })));
+      } else {
+        callback(null, selected[0].host, selected[0].family);
+      }
+    }, (err) => callback(err));
+  };
+}
+
+/**
+ * Create a connector for undici (and therefore Node's global fetch).
+ *
+ * undici is not a dependency of this package. Applications that already use it
+ * can wire the bridge in:
+ *
+ *   const { Agent, setGlobalDispatcher } = require('undici');
+ *   const { createConnector } = require('ipv6-bridge');
+ *   setGlobalDispatcher(new Agent({ connect: createConnector() }));
+ *
+ * @returns {Function} Function matching undici's `connect` option
+ */
+function createConnector() {
+  return function bridgeConnect(options, callback) {
+    const { hostname, port, protocol } = options;
+    const isSecure = protocol === 'https:';
+    const targetPort = Number(port) || (isSecure ? 443 : 80);
+
+    connectWithFallback(hostname, targetPort, { bypass: shouldBypass(hostname) }).then(
+      ({ socket }) => {
+        if (!isSecure) {
+          callback(null, socket);
+          return;
+        }
+        upgradeToTls(socket, options, hostname, callback);
+      },
+      (err) => callback(err)
+    );
+  };
+}
+
+/**
+ * Resolve a hostname the way the bridge would, without connecting.
+ *
+ * Useful for logging or asserting in tests which route would be taken.
+ *
+ * @param {string} hostname - Hostname or IP literal
+ * @returns {Promise<Array<{host: string, family: number, mode: string}>>} Candidates
+ */
+function resolve(hostname) {
+  return resolveCandidates(hostname);
+}
+
+module.exports = {
+  createAgent,
+  createHttpsAgent,
+  createAgents,
+  createLookup,
+  createConnector,
+  resolve,
+  BridgeHttpAgent,
+  BridgeHttpsAgent,
+};