ipv6-bridge 1.0.0 → 2.1.1

package/src/index.js

@@ -1,62 +1,157 @@
-/**
- * IPv6 Bridge - Main Entry Point
- *
- * Coordinates bridge startup and shutdown. The bridge consists of:
- *
- * 1. Detection (detect.js): Checks if the bridge is needed.
- * 2. DNS64 Resolver (dns64.js): Synthesizes IPv6 addresses from IPv4.
- * 3. Proxy (proxy.js): HTTP/HTTPS proxy with NAT64 routing.
- *
- * @module ipv6-bridge
- */
-
-const { createProxy } = require('./proxy');
-const { needsBridge } = require('./detect');
-
-let activeServer = null;
-
-/**
- * Start the IPv6 bridge.
- *
- * @param {number} [port=8080] - Port to listen on
- * @returns {Promise<http.Server|null>} Server instance if started, null if not needed
- * @throws {Error} If already running or startup fails
- */
-async function start(port = 8080) {
-  if (activeServer) {
-    throw new Error('IPv6 Bridge is already running');
-  }
-
-  // Step 1: Detect if bridge is needed
-  const needed = await needsBridge();
-  if (!needed && !process.env.FORCE_BRIDGE) {
-    console.log('IPv6 bridge not needed — you have dual-stack or working NAT64.');
-    return null;
-  }
-
-  if (!needed) {
-    console.log('IPv6 bridge not needed, but FORCE_BRIDGE is set — starting anyway.');
-  }
-
-  // Step 2: Start the proxy server
-  activeServer = await createProxy(port);
-  return activeServer;
-}
-
-/**
- * Stop the IPv6 bridge.
- *
- * @returns {Promise<void>} Resolves when the server has closed
- */
-function stop() {
-  if (!activeServer) return Promise.resolve();
-
-  return new Promise((resolve) => {
-    activeServer.close(() => {
-      activeServer = null;
-      resolve();
-    });
-  });
-}
-
-module.exports = { start, stop };
+/**
+ * IPv6 Bridge - Main Entry Point
+ *
+ * Coordinates bridge startup and shutdown:
+ *
+ * 1. Detection (detect.js): Checks if the bridge is needed.
+ * 2. Discovery (discovery.js): Finds the network's NAT64 prefix (RFC 7050).
+ * 3. DNS64 Resolver (dns64.js): Synthesizes IPv6 addresses from IPv4.
+ * 4. Proxy (proxy.js): HTTP/HTTPS proxy with NAT64 routing.
+ * 5. SOCKS5 (socks5.js): Optional listener for non-HTTP protocols.
+ *
+ * @module ipv6-bridge
+ */
+
+const { createProxy } = require('./proxy');
+const { createSocksServer } = require('./socks5');
+const { needsBridge } = require('./detect');
+const { discoverAndApply, discoverPrefix } = require('./discovery');
+const agent = require('./agent');
+const { dnsCache } = require('./dns64');
+const stats = require('./stats');
+const config = require('./config');
+const log = require('./logger');
+
+let activeServer = null;
+let activeSocksServer = null;
+let pendingStart = null;
+
+/**
+ * Start the IPv6 bridge.
+ *
+ * @param {number} [port] - Port to listen on
+ * @param {object} [options] - Startup options
+ * @param {string} [options.host] - Interface to bind to (defaults to loopback)
+ * @param {boolean} [options.force] - Start even if detection says it isn't needed
+ * @param {boolean} [options.discoverPrefix] - Run RFC 7050 prefix discovery
+ * @param {number|null} [options.socksPort] - Also start a SOCKS5 listener
+ * @returns {Promise<http.Server|null>} Server instance if started, null if not needed
+ * @throws {Error} If already running or startup fails
+ */
+function start(port = config.DEFAULT_PORT, options = {}) {
+  // Assigned synchronously so concurrent callers cannot both pass the guard
+  // and leave a second, untracked server running.
+  if (activeServer || pendingStart) {
+    return Promise.reject(new Error('IPv6 Bridge is already running'));
+  }
+
+  const {
+    host = config.BIND_HOST,
+    force = Boolean(process.env.FORCE_BRIDGE),
+    discoverPrefix = config.PREFIX_DISCOVERY,
+    socksPort = config.SOCKS_PORT,
+  } = options;
+
+  pendingStart = (async () => {
+    const needed = await needsBridge();
+
+    if (!needed && !force) {
+      log.info('IPv6 bridge not needed — IPv4 is reachable or NAT64 already works.');
+      return null;
+    }
+    if (!needed) {
+      log.info('IPv6 bridge not needed, but a forced start was requested.');
+    }
+
+    if (discoverPrefix) {
+      // Best effort: a network without DNS64 simply keeps the configured prefix.
+      await discoverAndApply().catch((err) => {
+        log.debug(`NAT64 prefix discovery failed: ${err.message}`);
+      });
+    }
+
+    const server = await createProxy(port, host);
+
+    if (socksPort) {
+      try {
+        activeSocksServer = await createSocksServer(socksPort, host);
+      } catch (err) {
+        await new Promise((resolve) => server.close(resolve));
+        throw err;
+      }
+    }
+
+    return server;
+  })();
+
+  return pendingStart
+    .then((server) => {
+      activeServer = server;
+      return server;
+    })
+    .finally(() => {
+      pendingStart = null;
+    });
+}
+
+/**
+ * Stop the IPv6 bridge.
+ *
+ * Live connections are torn down; CONNECT tunnels would otherwise keep the
+ * server open indefinitely.
+ *
+ * @returns {Promise<void>} Resolves once everything has closed
+ */
+async function stop() {
+  const server = activeServer;
+  const socks = activeSocksServer;
+  activeServer = null;
+  activeSocksServer = null;
+
+  const closers = [];
+  if (server) {
+    closers.push(typeof server.closeGracefully === 'function'
+      ? server.closeGracefully()
+      : new Promise((resolve) => server.close(resolve)));
+  }
+  if (socks) {
+    closers.push(socks.closeGracefully());
+  }
+
+  await Promise.all(closers);
+}
+
+/**
+ * Snapshot what the bridge has done so far.
+ *
+ * Applications embedding the agents can use this to confirm translation is
+ * actually happening rather than silently falling back.
+ *
+ * @returns {object} Counters, routing modes, DNS cache stats and active prefix
+ */
+function getStats() {
+  const prefix = config.getPrefix();
+  return stats.snapshot({
+    dnsCache: dnsCache.stats(),
+    nat64Prefix: `${prefix.prefix}/${prefix.length}`,
+  });
+}
+
+module.exports = {
+  // Proxy lifecycle
+  start,
+  stop,
+
+  // Embeddable primitives — use the bridge from inside an application,
+  // with no proxy and no system configuration.
+  createAgent: agent.createAgent,
+  createHttpsAgent: agent.createHttpsAgent,
+  createAgents: agent.createAgents,
+  createLookup: agent.createLookup,
+  createConnector: agent.createConnector,
+
+  // Introspection
+  resolve: agent.resolve,
+  getStats,
+  discoverPrefix,
+};

package/src/ipv6.js

@@ -0,0 +1,232 @@
+/**
+ * IPv6 Bridge - IPv6 address primitives
+ *
+ * Parsing, formatting, and the IPv4-embedded address format of RFC 6052.
+ * Node exposes no inet_pton/inet_ntop equivalent, so these are implemented
+ * here to keep the package dependency-free.
+ *
+ * @module ipv6
+ */
+
+const net = require('net');
+
+/** Prefix lengths permitted by RFC 6052 section 2.2. */
+const VALID_PREFIX_LENGTHS = [32, 40, 48, 56, 64, 96];
+
+/** The RFC 6052 section 3.1 well-known prefix, in canonical form. */
+const WELL_KNOWN_PREFIX_ADDRESS = '64:ff9b::';
+
+/**
+ * Parse an IPv6 address into its 16 bytes.
+ *
+ * @param {string} address - IPv6 address, optionally with an embedded IPv4 tail
+ * @returns {Buffer|null} 16-byte buffer, or null if the address is invalid
+ */
+function parseIPv6(address) {
+  if (typeof address !== 'string' || net.isIP(address) !== 6) return null;
+
+  let text = address;
+
+  // A trailing dotted-quad ("::ffff:192.0.2.1") is converted to hex groups.
+  const embedded = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(text);
+  if (embedded) {
+    const octets = embedded[1].split('.').map(Number);
+    const high = ((octets[0] << 8) | octets[1]).toString(16);
+    const low = ((octets[2] << 8) | octets[3]).toString(16);
+    text = text.slice(0, embedded.index) + `${high}:${low}`;
+  }
+
+  const [head, tail, ...extra] = text.split('::');
+  if (extra.length > 0) return null;
+
+  const parseGroups = (part) => (part ? part.split(':').filter((g) => g !== '') : []);
+  const headGroups = parseGroups(head);
+  const tailGroups = tail === undefined ? [] : parseGroups(tail);
+
+  const total = headGroups.length + tailGroups.length;
+  if (total > 8) return null;
+  if (tail === undefined && total !== 8) return null;
+
+  const groups = [
+    ...headGroups,
+    ...Array(8 - total).fill('0'),
+    ...tailGroups,
+  ];
+
+  const bytes = Buffer.alloc(16);
+  for (let i = 0; i < 8; i++) {
+    const value = parseInt(groups[i], 16);
+    if (Number.isNaN(value) || value < 0 || value > 0xffff) return null;
+    bytes.writeUInt16BE(value, i * 2);
+  }
+  return bytes;
+}
+
+/**
+ * Format 16 bytes as a canonical IPv6 address (RFC 5952): lowercase, with the
+ * longest run of zero groups compressed to "::".
+ *
+ * @param {Buffer} bytes - 16-byte buffer
+ * @returns {string} Canonical IPv6 address
+ */
+function formatIPv6(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length !== 16) {
+    throw new Error('formatIPv6: expected a 16-byte buffer');
+  }
+
+  const groups = [];
+  for (let i = 0; i < 8; i++) groups.push(bytes.readUInt16BE(i * 2));
+
+  // Find the longest run of two or more zero groups.
+  let bestStart = -1;
+  let bestLength = 0;
+  let runStart = -1;
+  for (let i = 0; i <= 8; i++) {
+    if (i < 8 && groups[i] === 0) {
+      if (runStart === -1) runStart = i;
+    } else if (runStart !== -1) {
+      const length = i - runStart;
+      if (length > bestLength) {
+        bestStart = runStart;
+        bestLength = length;
+      }
+      runStart = -1;
+    }
+  }
+
+  const hex = groups.map((g) => g.toString(16));
+  if (bestLength < 2) return hex.join(':');
+
+  const head = hex.slice(0, bestStart).join(':');
+  const tail = hex.slice(bestStart + bestLength).join(':');
+  return `${head}::${tail}`;
+}
+
+/**
+ * Parse an IPv4 address into its 4 bytes.
+ *
+ * @param {string} address - IPv4 address
+ * @returns {Buffer|null} 4-byte buffer, or null if invalid
+ */
+function parseIPv4(address) {
+  if (typeof address !== 'string' || net.isIP(address) !== 4) return null;
+  return Buffer.from(address.split('.').map(Number));
+}
+
+/**
+ * Parse a NAT64 prefix specification such as "64:ff9b::/96" or "64:ff9b::".
+ *
+ * @param {string} spec - Prefix, with an optional "/length" suffix
+ * @returns {{prefix: string, length: number, bytes: Buffer}} Parsed prefix
+ * @throws {Error} If the prefix or length is invalid
+ */
+function parsePrefix(spec) {
+  if (typeof spec !== 'string' || spec.trim() === '') {
+    throw new Error('NAT64 prefix must be a non-empty string');
+  }
+
+  const [address, lengthText] = spec.trim().split('/');
+  const length = lengthText === undefined ? 96 : Number(lengthText);
+
+  if (!VALID_PREFIX_LENGTHS.includes(length)) {
+    throw new Error(
+      `Invalid NAT64 prefix length /${lengthText}: RFC 6052 permits only ` +
+      `${VALID_PREFIX_LENGTHS.map((l) => `/${l}`).join(', ')}`
+    );
+  }
+
+  const bytes = parseIPv6(address);
+  if (!bytes) {
+    throw new Error(`Invalid NAT64 prefix "${address}": not a valid IPv6 address`);
+  }
+
+  // Everything past the prefix length must be zero.
+  for (let bit = length; bit < 128; bit++) {
+    const byte = bytes[Math.floor(bit / 8)];
+    if ((byte >> (7 - (bit % 8))) & 1) {
+      throw new Error(
+        `Invalid NAT64 prefix "${spec}": bits after /${length} must be zero`
+      );
+    }
+  }
+
+  const formatted = formatIPv6(bytes);
+
+  // RFC 6052 section 3.1 defines the well-known prefix only at /96.
+  if (formatted === WELL_KNOWN_PREFIX_ADDRESS && length !== 96) {
+    throw new Error(
+      `Invalid NAT64 prefix "${spec}": the well-known prefix ${WELL_KNOWN_PREFIX_ADDRESS} ` +
+      `is only defined as /96 (RFC 6052 section 3.1)`
+    );
+  }
+
+  return { prefix: formatted, length, bytes };
+}
+
+/**
+ * Byte positions an embedded IPv4 address occupies for a given prefix length.
+ *
+ * RFC 6052 section 2.2 reserves bits 64-71 (byte 8) as the "u" octet, which
+ * must be zero, so the address skips over it.
+ *
+ * @param {number} prefixLength - Prefix length in bits
+ * @returns {number[]} Four byte indices
+ */
+function embeddedPositions(prefixLength) {
+  const positions = [];
+  let index = prefixLength / 8;
+  while (positions.length < 4) {
+    if (index === 8) index = 9; // skip the reserved u octet
+    positions.push(index);
+    index += 1;
+  }
+  return positions;
+}
+
+/**
+ * Embed an IPv4 address into a NAT64 prefix (RFC 6052 section 2.2).
+ *
+ * @param {string} ipv4 - IPv4 address
+ * @param {{bytes: Buffer, length: number}} prefix - Parsed prefix
+ * @returns {string} IPv4-embedded IPv6 address
+ * @throws {Error} If the IPv4 address is invalid
+ */
+function embedIPv4(ipv4, prefix) {
+  const octets = parseIPv4(ipv4);
+  if (!octets) throw new Error(`embedIPv4: invalid IPv4 address "${ipv4}"`);
+
+  const bytes = Buffer.alloc(16);
+  prefix.bytes.copy(bytes, 0, 0, prefix.length / 8);
+
+  embeddedPositions(prefix.length).forEach((position, i) => {
+    bytes[position] = octets[i];
+  });
+
+  return formatIPv6(bytes);
+}
+
+/**
+ * Extract an IPv4 address embedded in an IPv6 address (RFC 6052 section 2.2).
+ *
+ * @param {string} address - IPv4-embedded IPv6 address
+ * @param {number} prefixLength - Prefix length in bits
+ * @returns {string|null} Extracted IPv4 address, or null if the input is invalid
+ */
+function extractIPv4(address, prefixLength) {
+  const bytes = parseIPv6(address);
+  if (!bytes || !VALID_PREFIX_LENGTHS.includes(prefixLength)) return null;
+
+  return embeddedPositions(prefixLength).map((position) => bytes[position]).join('.');
+}
+
+module.exports = {
+  VALID_PREFIX_LENGTHS,
+  WELL_KNOWN_PREFIX_ADDRESS,
+  parseIPv6,
+  formatIPv6,
+  parseIPv4,
+  parsePrefix,
+  embedIPv4,
+  extractIPv4,
+  embeddedPositions,
+};

package/src/logger.js

@@ -0,0 +1,47 @@
+/**
+ * IPv6 Bridge - Logger
+ *
+ * Minimal structured logger with level filtering.
+ * Respects the LOG_LEVEL environment variable (default: 'info').
+ *
+ * Levels: silent < error < warn < info < debug
+ *
+ * @module logger
+ */
+
+const LEVELS = { silent: -1, error: 0, warn: 1, info: 2, debug: 3 };
+
+const currentLevel = LEVELS[
+  (process.env.LOG_LEVEL || 'info').toLowerCase()
+] ?? LEVELS.info;
+
+function timestamp() {
+  return new Date().toISOString();
+}
+
+function format(level, msg) {
+  return `[${timestamp()}] [${level.toUpperCase()}] ${msg}`;
+}
+
+module.exports = {
+  error(msg) {
+    if (currentLevel >= LEVELS.error) {
+      console.error(format('error', msg));
+    }
+  },
+  warn(msg) {
+    if (currentLevel >= LEVELS.warn) {
+      console.warn(format('warn', msg));
+    }
+  },
+  info(msg) {
+    if (currentLevel >= LEVELS.info) {
+      console.log(format('info', msg));
+    }
+  },
+  debug(msg) {
+    if (currentLevel >= LEVELS.debug) {
+      console.log(format('debug', msg));
+    }
+  },
+};

package/src/netmatch.js

@@ -0,0 +1,122 @@
+/**
+ * IPv6 Bridge - Address and hostname matching
+ *
+ * Shared matching logic for the client allowlist and the bypass list.
+ * Supports IPv4/IPv6 CIDR ranges, bare addresses, and hostname wildcards.
+ *
+ * @module netmatch
+ */
+
+const net = require('net');
+const { parseIPv6, parseIPv4 } = require('./ipv6');
+
+/**
+ * Normalize an address into bytes. IPv4-mapped IPv6 addresses ("::ffff:1.2.3.4",
+ * which is how a dual-stack listener reports IPv4 peers) are reduced to IPv4.
+ *
+ * @param {string} address - IP address
+ * @returns {{bytes: Buffer, family: number}|null} Normalized address
+ */
+function toBytes(address) {
+  if (typeof address !== 'string') return null;
+
+  const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i.exec(address);
+  const candidate = mapped ? mapped[1] : address;
+
+  const version = net.isIP(candidate);
+  if (version === 4) return { bytes: parseIPv4(candidate), family: 4 };
+  if (version === 6) {
+    const bytes = parseIPv6(candidate);
+    return bytes ? { bytes, family: 6 } : null;
+  }
+  return null;
+}
+
+/**
+ * Parse a CIDR rule such as "192.168.0.0/16", "10.0.0.1" or "2001:db8::/32".
+ *
+ * @param {string} rule - CIDR or bare address
+ * @returns {{bytes: Buffer, family: number, bits: number}|null} Parsed rule
+ */
+function parseCidr(rule) {
+  const [address, lengthText] = String(rule).trim().split('/');
+  const parsed = toBytes(address);
+  if (!parsed) return null;
+
+  const maxBits = parsed.family === 4 ? 32 : 128;
+  const bits = lengthText === undefined ? maxBits : Number(lengthText);
+  if (!Number.isInteger(bits) || bits < 0 || bits > maxBits) return null;
+
+  return { ...parsed, bits };
+}
+
+/**
+ * Test whether an address falls inside a parsed CIDR rule.
+ *
+ * @param {string} address - IP address to test
+ * @param {{bytes: Buffer, family: number, bits: number}} rule - Parsed rule
+ * @returns {boolean} true if the address matches
+ */
+function matchesCidr(address, rule) {
+  const parsed = toBytes(address);
+  if (!parsed || !rule || parsed.family !== rule.family) return false;
+
+  const wholeBytes = Math.floor(rule.bits / 8);
+  const remainingBits = rule.bits % 8;
+
+  for (let i = 0; i < wholeBytes; i++) {
+    if (parsed.bytes[i] !== rule.bytes[i]) return false;
+  }
+
+  if (remainingBits === 0) return true;
+
+  const mask = (0xff << (8 - remainingBits)) & 0xff;
+  return (parsed.bytes[wholeBytes] & mask) === (rule.bytes[wholeBytes] & mask);
+}
+
+/**
+ * Compile a comma-separated rule list into a matcher.
+ *
+ * Each rule is either a CIDR/address or a hostname pattern, where a leading
+ * "*." matches any subdomain and the bare domain itself.
+ *
+ * @param {string} spec - Comma-separated rules
+ * @returns {{isEmpty: boolean, rules: string[], matches: (value: string) => boolean}} Matcher
+ */
+function compile(spec) {
+  const rules = String(spec || '')
+    .split(',')
+    .map((r) => r.trim().toLowerCase())
+    .filter(Boolean);
+
+  const cidrs = [];
+  const hostPatterns = [];
+
+  for (const rule of rules) {
+    const cidr = parseCidr(rule);
+    if (cidr) cidrs.push(cidr);
+    else hostPatterns.push(rule);
+  }
+
+  function matches(value) {
+    if (!value) return false;
+    const target = String(value).toLowerCase();
+
+    if (net.isIP(target) !== 0 || /^::ffff:/i.test(target)) {
+      if (cidrs.some((rule) => matchesCidr(target, rule))) return true;
+    }
+
+    return hostPatterns.some((pattern) => {
+      if (pattern === '*') return true;
+      if (pattern.startsWith('*.')) {
+        const domain = pattern.slice(2);
+        return target === domain || target.endsWith('.' + domain);
+      }
+      return target === pattern;
+    });
+  }
+
+  return { isEmpty: rules.length === 0, rules, matches };
+}
+
+module.exports = { compile, parseCidr, matchesCidr, toBytes };