ipv6-bridge 1.0.0 → 2.1.1

package/src/dns64.js

@@ -1,13 +1,50 @@
 /**
  * IPv6 Bridge - DNS64 Resolver
  *
- * Implements DNS64 (RFC 6052) for synthesizing IPv6 addresses from IPv4.
+ * Implements DNS64 (RFC 6147) using the IPv4-embedded IPv6 address format
+ * defined by RFC 6052.
+ *
+ * Name resolution goes through dns.lookup (the operating system resolver)
+ * rather than dns.resolve*. dns.resolve* speaks directly to DNS servers over
+ * port 53 and ignores the hosts file, mDNS, DNS-over-HTTPS and any other
+ * system resolver configuration — on a DoH-only or split-DNS host it fails
+ * outright even though normal name resolution works fine.
  *
  * @module dns64
  */
 
-const dns = require('dns').promises;
-const { NAT64_PREFIX } = require('./config');
+const dns = require('dns');
+const net = require('net');
+const { embedIPv4, extractIPv4 } = require('./ipv6');
+const { TtlCache } = require('./cache');
+const config = require('./config');
+
+/**
+ * IPv4 ranges that are not globally reachable (RFC 6890).
+ * Stored as [network, prefixLength] pairs.
+ */
+const NON_GLOBAL_IPV4_RANGES = [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['172.16.0.0', 12],
+  ['192.0.0.0', 24],
+  ['192.0.2.0', 24],
+  ['192.88.99.0', 24],
+  ['192.168.0.0', 16],
+  ['198.18.0.0', 15],
+  ['198.51.100.0', 24],
+  ['203.0.113.0', 24],
+  ['224.0.0.0', 4],
+  ['240.0.0.0', 4],
+];
+
+const dnsCache = new TtlCache({
+  max: config.DNS_CACHE_MAX,
+  ttl: config.DNS_CACHE_TTL,
+});
 
 /**
  * Detect the IP version of an address string.
@@ -16,75 +53,220 @@ const { NAT64_PREFIX } = require('./config');
  * @returns {'ipv4'|'ipv6'|'hostname'|null} Address type
  */
 function detectIPVersion(addr) {
-  if (!addr) return null;
+  if (!addr || typeof addr !== 'string') return null;
 
-  // IPv4: dotted decimal (0-255 per octet)
-  if (/^(\d{1,3}\.){3}\d{1,3}$/.test(addr)) {
-    const parts = addr.split('.').map(Number);
-    if (parts.every((p) => p >= 0 && p <= 255)) {
-      return 'ipv4';
-    }
-  }
-
-  // IPv6: colon-delimited hex (includes :: shorthand)
-  if (/^[a-f0-9:]+$/i.test(addr) && addr.includes(':')) {
-    return 'ipv6';
-  }
+  const result = net.isIP(addr);
+  if (result === 4) return 'ipv4';
+  if (result === 6) return 'ipv6';
 
-  // Everything else is a hostname
+  // net.isIP returns 0 for non-IP strings (i.e. hostnames)
   return 'hostname';
 }
 
+function ipv4ToInt(ipv4) {
+  return ipv4.split('.').reduce((acc, octet) => (acc * 256) + Number(octet), 0);
+}
+
 /**
- * Convert an IPv4 address to IPv6 using the NAT64 prefix (RFC 6052).
+ * Check whether an IPv4 address is globally reachable.
  *
- * The IPv4 address is embedded in the lower 32 bits of the IPv6 address:
- *   192.0.2.1 → 64:ff9b::c000:0201
+ * RFC 6052 section 3.1 forbids representing non-global IPv4 addresses with the
+ * well-known prefix, so these must not be handed to a NAT64 gateway.
+ *
+ * @param {string} ipv4 - IPv4 address
+ * @returns {boolean} true if the address is globally routable
+ */
+function isGlobalIPv4(ipv4) {
+  if (net.isIP(ipv4) !== 4) return false;
+
+  const addr = ipv4ToInt(ipv4);
+  return !NON_GLOBAL_IPV4_RANGES.some(([network, bits]) => {
+    const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+    return ((addr & mask) >>> 0) === ((ipv4ToInt(network) & mask) >>> 0);
+  });
+}
+
+/**
+ * Whether an IPv4 address may be synthesized with the configured prefix.
+ *
+ * An operator-assigned network-specific prefix may carry non-global addresses;
+ * the well-known prefix may not.
+ *
+ * @param {string} ipv4 - IPv4 address
+ * @returns {boolean} true if synthesis is permitted
+ */
+function canSynthesize(ipv4) {
+  if (net.isIP(ipv4) !== 4) return false;
+  return !config.usingWellKnownPrefix() || isGlobalIPv4(ipv4);
+}
+
+/**
+ * Convert an IPv4 address to IPv6 using the configured NAT64 prefix (RFC 6052).
+ *
+ * This is a pure format conversion; it does not enforce RFC 6052 section 3.1.
+ * Use canSynthesize() to decide whether conversion is appropriate.
  *
  * @param {string} ipv4 - IPv4 address (e.g., '192.0.2.1')
- * @returns {string} IPv6 address with NAT64 prefix
+ * @returns {string} IPv4-embedded IPv6 address
  * @throws {Error} If the input is not a valid IPv4 address
  */
 function ipv4ToIPv6(ipv4) {
   if (!ipv4 || typeof ipv4 !== 'string') {
     throw new Error('ipv4ToIPv6: address must be a non-empty string');
   }
-
-  const parts = ipv4.split('.').map(Number);
-  if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+  if (net.isIP(ipv4) !== 4) {
     throw new Error(`ipv4ToIPv6: invalid IPv4 address "${ipv4}"`);
   }
+  return embedIPv4(ipv4, config.getPrefix());
+}
 
-  const hex1 = ((parts[0] << 8) | parts[1]).toString(16).padStart(4, '0');
-  const hex2 = ((parts[2] << 8) | parts[3]).toString(16).padStart(4, '0');
-  return `${NAT64_PREFIX}${hex1}:${hex2}`;
+/**
+ * Recover the IPv4 address embedded in a synthesized IPv6 address.
+ *
+ * @param {string} address - IPv4-embedded IPv6 address
+ * @returns {string|null} The IPv4 address, or null if not embedded
+ */
+function ipv6ToIPv4(address) {
+  return extractIPv4(address, config.getPrefix().length);
 }
 
 /**
- * Resolve a hostname to IPv6 addresses using DNS64 (RFC 6052).
+ * Look up every address for a hostname via the system resolver, with a timeout.
  *
- * 1. Try native AAAA resolution first.
- * 2. Fall back to A resolution and synthesize IPv6 via NAT64 prefix.
+ * @param {string} hostname - Hostname to look up
+ * @param {number} [timeoutMs] - Timeout in milliseconds
+ * @returns {Promise<Array<{address: string, family: number}>>} Resolved records
+ */
+function lookupAll(hostname, timeoutMs = config.DNS_TIMEOUT) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      settled = true;
+      const err = new Error(`DNS lookup for "${hostname}" timed out after ${timeoutMs}ms`);
+      err.code = 'ETIMEDOUT';
+      reject(err);
+    }, timeoutMs);
+
+    dns.lookup(hostname, { all: true, verbatim: true }, (err, addresses) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (err) reject(err);
+      else resolve(addresses);
+    });
+  });
+}
+
+/** Rotate an array so repeated lookups spread across available records. */
+function rotate(items) {
+  if (items.length < 2) return items;
+  const offset = Math.floor(Math.random() * items.length);
+  return [...items.slice(offset), ...items.slice(0, offset)];
+}
+
+/**
+ * Resolve a hostname into an ordered list of connection candidates.
+ *
+ * Candidates are ordered most- to least-preferred, so a caller can fail over
+ * rather than giving up on the first unreachable address:
+ *
+ *   1. native IPv6 (the host is already reachable without translation)
+ *   2. NAT64-synthesized IPv6 (what this bridge exists to provide)
+ *   3. direct IPv4 (last resort; not translated)
+ *
+ * @param {string} hostname - Hostname or IP literal
+ * @returns {Promise<Array<{host: string, family: number, mode: string}>>} Candidates
+ */
+async function resolveCandidates(hostname) {
+  const ipVersion = detectIPVersion(hostname);
+
+  if (ipVersion === 'ipv6') {
+    return [{ host: hostname, family: 6, mode: 'ipv6-literal' }];
+  }
+
+  if (ipVersion === 'ipv4') {
+    if (canSynthesize(hostname)) {
+      return [
+        { host: ipv4ToIPv6(hostname), family: 6, mode: 'nat64' },
+        { host: hostname, family: 4, mode: 'direct-ipv4' },
+      ];
+    }
+    // RFC 6052 section 3.1: non-global IPv4 cannot use the well-known prefix.
+    return [{ host: hostname, family: 4, mode: 'direct-ipv4' }];
+  }
+
+  const cached = dnsCache.get(hostname);
+  if (cached) return cached;
+
+  const records = await lookupAll(hostname);
+
+  const ipv6 = rotate(records.filter((r) => r.family === 6).map((r) => r.address));
+  const ipv4 = rotate(records.filter((r) => r.family === 4).map((r) => r.address));
+
+  if (ipv6.length === 0 && ipv4.length === 0) {
+    throw new Error(`No A or AAAA records found for ${hostname}`);
+  }
+
+  const candidates = [
+    ...ipv6.map((host) => ({ host, family: 6, mode: 'native-ipv6' })),
+    ...ipv4.filter(canSynthesize).map((address) => ({
+      host: ipv4ToIPv6(address), family: 6, mode: 'nat64',
+    })),
+    ...ipv4.map((host) => ({ host, family: 4, mode: 'direct-ipv4' })),
+  ];
+
+  dnsCache.set(hostname, candidates);
+  return candidates;
+}
+
+/**
+ * Resolve a hostname, reporting how it would be reached.
+ *
+ * @param {string} hostname - Domain name to resolve
+ * @returns {Promise<{addresses: string[], mode: string}>} Addresses and routing mode
+ * @throws {Error} If the hostname cannot be resolved at all
+ */
+async function resolveHost(hostname) {
+  const candidates = await resolveCandidates(hostname);
+  const primary = candidates[0].mode;
+  return {
+    addresses: candidates.filter((c) => c.mode === primary).map((c) => c.host),
+    mode: primary,
+  };
+}
+
+/**
+ * Resolve a hostname to IPv6 addresses using DNS64.
  *
  * @param {string} hostname - Domain name to resolve
  * @returns {Promise<string[]>} Array of IPv6 addresses
- * @throws {Error} If DNS resolution fails completely
+ * @throws {Error} If no IPv6 address can be produced
  */
 async function resolveIPv6(hostname) {
-  try {
-    const resolver = dns.resolve6(hostname);
-    const timeout = new Promise((_, reject) =>
-      setTimeout(() => reject(new Error('DNS timeout')), 5000)
+  const candidates = await resolveCandidates(hostname);
+  const ipv6 = candidates.filter((c) => c.family === 6).map((c) => c.host);
+
+  if (ipv6.length === 0) {
+    throw new Error(
+      `Cannot produce an IPv6 address for ${hostname}: it resolves only to ` +
+      `non-global IPv4 addresses, which RFC 6052 section 3.1 forbids ` +
+      `representing with the well-known prefix`
     );
-    return await Promise.race([resolver, timeout]);
-  } catch {
-    try {
-      const ipv4 = await dns.resolve4(hostname);
-      return ipv4.map(ipv4ToIPv6);
-    } catch (err) {
-      throw new Error(`DNS resolution failed for ${hostname}: ${err.message}`);
-    }
   }
+
+  return ipv6;
 }
 
-module.exports = { ipv4ToIPv6, resolveIPv6, detectIPVersion };
+module.exports = {
+  ipv4ToIPv6,
+  ipv6ToIPv4,
+  resolveIPv6,
+  resolveHost,
+  resolveCandidates,
+  detectIPVersion,
+  isGlobalIPv4,
+  canSynthesize,
+  lookupAll,
+  dnsCache,
+};

package/src/doctor.js

@@ -0,0 +1,222 @@
+/**
+ * IPv6 Bridge - Diagnostics
+ *
+ * Answers the question a user actually has when their IPv6-only network is
+ * misbehaving: what is broken, and what should I do about it?
+ *
+ * Every check reports what it observed and, on failure, what that implies.
+ *
+ * @module doctor
+ */
+
+const os = require('os');
+const dns = require('dns');
+const dnsPromises = require('dns').promises;
+const { lookupAll } = require('./dns64');
+const { discoverPrefix } = require('./discovery');
+const { hasIPv4, hasIPv6, hasWorkingNAT64 } = require('./detect');
+const config = require('./config');
+
+const PASS = 'pass';
+const FAIL = 'fail';
+const WARN = 'warn';
+const INFO = 'info';
+
+function interfaces() {
+  const result = { ipv4: [], ipv6: [] };
+  for (const [name, addresses] of Object.entries(os.networkInterfaces())) {
+    for (const address of addresses || []) {
+      if (address.internal) continue;
+      const family = address.family === 'IPv4' || address.family === 4 ? 'ipv4' : 'ipv6';
+      result[family].push(`${name}: ${address.address}`);
+    }
+  }
+  return result;
+}
+
+/**
+ * Compare the system resolver against direct DNS queries.
+ *
+ * These disagree more often than people expect: dns.resolve* bypasses the
+ * hosts file and any DNS-over-HTTPS configuration, so it can fail completely
+ * on a host where normal name resolution works.
+ */
+async function checkResolvers() {
+  const checks = [];
+  const probe = 'example.com';
+
+  let systemOk = false;
+  try {
+    const records = await lookupAll(probe);
+    systemOk = records.length > 0;
+    checks.push({
+      name: 'System resolver (dns.lookup)',
+      status: PASS,
+      detail: `${probe} -> ${records.map((r) => r.address).join(', ')}`,
+    });
+  } catch (err) {
+    checks.push({
+      name: 'System resolver (dns.lookup)',
+      status: FAIL,
+      detail: `${probe} did not resolve (${err.code || err.message})`,
+      advice: 'Name resolution is broken for every program on this machine, not just the bridge. Check your DNS settings or VPN.',
+    });
+  }
+
+  try {
+    await dnsPromises.resolve4(probe);
+    checks.push({
+      name: 'Direct DNS queries (dns.resolve)',
+      status: PASS,
+      detail: `servers: ${dns.getServers().join(', ')}`,
+    });
+  } catch (err) {
+    checks.push({
+      name: 'Direct DNS queries (dns.resolve)',
+      status: systemOk ? INFO : WARN,
+      detail: `failed (${err.code || err.message}); configured servers: ${dns.getServers().join(', ')}`,
+      advice: systemOk
+        ? 'Harmless: the bridge resolves through the system resolver, which works. Tools that query port 53 directly will fail on this host.'
+        : 'Both resolution paths are failing. Check DNS configuration.',
+    });
+  }
+
+  return checks;
+}
+
+async function checkConnectivity() {
+  const checks = [];
+
+  const ipv4 = await hasIPv4();
+  checks.push({
+    name: 'IPv4 connectivity',
+    status: ipv4 ? PASS : INFO,
+    detail: ipv4 ? `reached ${config.IPV4_TEST_URL}` : `could not reach ${config.IPV4_TEST_URL}`,
+    advice: ipv4 ? 'IPv4 works, so the bridge is not required on this network.' : undefined,
+  });
+
+  const ipv6 = await hasIPv6();
+  checks.push({
+    name: 'IPv6 connectivity',
+    status: ipv6 ? PASS : (ipv4 ? INFO : FAIL),
+    detail: ipv6 ? `reached ${config.IPV6_TEST_URL}` : `could not reach ${config.IPV6_TEST_URL}`,
+    advice: !ipv6 && !ipv4
+      ? 'Neither protocol works. The bridge cannot help until basic connectivity is restored.'
+      : undefined,
+  });
+
+  if (ipv6) {
+    const nat64 = await hasWorkingNAT64();
+    checks.push({
+      name: 'Upstream NAT64 gateway',
+      status: nat64 ? PASS : INFO,
+      detail: nat64
+        ? `reached ${config.NAT64_TEST_HOST} over a synthesized address`
+        : `could not reach ${config.NAT64_TEST_HOST} over a synthesized address`,
+      advice: nat64
+        ? 'Your network already translates IPv4 traffic; the bridge is optional here.'
+        : 'No NAT64 gateway responded. If this is an IPv6-only network, the bridge is needed — but it can only work if your ISP operates a NAT64 gateway.',
+    });
+  }
+
+  return checks;
+}
+
+async function checkPrefix() {
+  const current = config.getPrefix();
+  const checks = [{
+    name: 'Configured NAT64 prefix',
+    status: INFO,
+    detail: `${current.prefix}/${current.length}${process.env.NAT64_PREFIX ? ' (from NAT64_PREFIX)' : ' (default)'}`,
+  }];
+
+  const discovered = await discoverPrefix().catch(() => null);
+
+  if (!discovered) {
+    checks.push({
+      name: 'NAT64 prefix discovery (RFC 7050)',
+      status: INFO,
+      detail: 'ipv4only.arpa returned no synthesized AAAA records',
+      advice: 'This resolver does not provide DNS64. On an IPv6-only network that usually means you must point at a DNS64 resolver, or set NAT64_PREFIX manually.',
+    });
+    return checks;
+  }
+
+  const matches = discovered.prefix === current.prefix && discovered.length === current.length;
+  checks.push({
+    name: 'NAT64 prefix discovery (RFC 7050)',
+    status: matches ? PASS : WARN,
+    detail: `network advertises ${discovered.prefix}/${discovered.length}`,
+    advice: matches
+      ? undefined
+      : `This differs from the prefix in use. Set NAT64_PREFIX=${discovered.prefix}/${discovered.length} or let discovery apply it automatically.`,
+  });
+
+  return checks;
+}
+
+function checkSecurity() {
+  const checks = [];
+  const loopback = config.isLoopbackBind();
+  const guarded = Boolean(config.AUTH) || !config.ALLOW_FROM.isEmpty;
+
+  checks.push({
+    name: 'Listener exposure',
+    status: loopback || guarded ? PASS : WARN,
+    detail: loopback
+      ? `bound to ${config.BIND_HOST} (loopback only)`
+      : `bound to ${config.BIND_HOST}${guarded ? ' with access control' : ' with no access control'}`,
+    advice: loopback || guarded
+      ? undefined
+      : 'Anyone who can reach this host can relay traffic through it. Set IPV6_BRIDGE_AUTH or IPV6_BRIDGE_ALLOW, or bind to 127.0.0.1.',
+  });
+
+  return checks;
+}
+
+/**
+ * Run every diagnostic check.
+ *
+ * @returns {Promise<{checks: object[], summary: {pass: number, warn: number, fail: number}, interfaces: object}>}
+ */
+async function diagnose() {
+  const checks = [
+    ...await checkResolvers(),
+    ...await checkConnectivity(),
+    ...await checkPrefix(),
+    ...checkSecurity(),
+  ];
+
+  const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
+  for (const check of checks) summary[check.status] += 1;
+
+  return { checks, summary, interfaces: interfaces() };
+}
+
+/**
+ * Render diagnostics as human-readable text.
+ *
+ * @param {object} report - Result of diagnose()
+ * @returns {string} Formatted report
+ */
+function format(report) {
+  const symbols = { pass: '  OK  ', fail: ' FAIL ', warn: ' WARN ', info: ' INFO ' };
+  const lines = ['', 'IPv6 Bridge diagnostics', '======================='];
+
+  lines.push('', 'Network interfaces:');
+  lines.push(`  IPv4: ${report.interfaces.ipv4.join(', ') || 'none'}`);
+  lines.push(`  IPv6: ${report.interfaces.ipv6.join(', ') || 'none'}`);
+  lines.push('');
+
+  for (const check of report.checks) {
+    lines.push(`[${symbols[check.status]}] ${check.name}`);
+    lines.push(`          ${check.detail}`);
+    if (check.advice) lines.push(`          -> ${check.advice}`);
+  }
+
+  const { pass, warn, fail } = report.summary;
+  lines.push('', `${pass} passed, ${warn} warning(s), ${fail} failure(s)`, '');
+  return lines.join('\n');
+}
+
+module.exports = { diagnose, format };