@iicp/client 0.5.5 → 0.5.7

package/dist/nat_detection.js

@@ -28,10 +28,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectNat = detectNat;
 exports.detectIpv6 = detectIpv6;
+exports.rankedGlobalIpv6Candidates = rankedGlobalIpv6Candidates;
 exports.tryUpnpMapping = tryUpnpMapping;
 exports.probeExternalIp = probeExternalIp;
 exports.looksRoutable = looksRoutable;
 exports.detectCgnat = detectCgnat;
+exports.tryUpnpIpv6Pinhole = tryUpnpIpv6Pinhole;
+exports.tryOpenV6PinholeForEndpoint = tryOpenV6PinholeForEndpoint;
+exports.deleteIpv6Pinhole = deleteIpv6Pinhole;
 const dns = require("node:dns");
 const net = require("node:net");
 function newProfile(tier, method) {
@@ -73,6 +77,18 @@ async function detectNat(opts) {
         }
         profile.detectionLog.push(`tier-0: operator-configured public_endpoint=${JSON.stringify(operatorPublicEndpoint)} non-routable — falling through to tier-1 UPnP`);
     }
+    // Tier 0 auto-detect — cloud VM with a public IPv4 directly on a local interface.
+    const autoV4 = detectPublicV4OnInterfaces();
+    if (autoV4) {
+        const autoUrl = `http://${autoV4}:${bindPort}`;
+        profile.detectionLog.push(`tier-0: auto-detected public IPv4 on local interface → ${JSON.stringify(autoUrl)}`);
+        const t0 = newProfile(0, "direct");
+        t0.publicEndpoint = autoUrl;
+        t0.internalEndpoint = profile.internalEndpoint;
+        t0.detectionLog = profile.detectionLog;
+        t0.ipv6 = profile.ipv6;
+        return t0;
+    }
     // Tier 1 — UPnP
     const portsToMap = [bindPort];
     if (transportPort && transportPort !== bindPort)
@@ -121,7 +137,7 @@ async function detectNat(opts) {
         if (cgnatWarning) {
             profile.detectionLog.push(`tier-1: ${cgnatWarning}`);
             // ADR-043 §10 — CGNAT IPv4 unreachable, but advertise IPv6 GUA if usable.
-            const v6 = tryIpv6Fallback(profile, bindPort, transportPort);
+            const v6 = await tryIpv6Fallback(profile, bindPort, transportPort);
             if (v6)
                 return v6;
             profile.operatorGuidance =
@@ -132,14 +148,20 @@ async function detectNat(opts) {
                     `funnel), (c) switch to IPv6 if your network supports it.`;
             return profile; // tier 4
         }
-        const publicUrl = `http://${upnp.externalIp}:${bindPort}`;
+        // ADR-041 §3 — advertise the EXTERNAL ports the IGD actually assigned.
+        // With AddAnyPortMapping fallback the external can differ from the
+        // internal (typical when another LAN host owns 9484 already).
+        const extBind = upnp.portMapping?.[bindPort] ?? bindPort;
+        const publicUrl = `http://${upnp.externalIp}:${extBind}`;
         let transportUrl;
         if (transportPort && upnp.mappedPorts.includes(transportPort) && transportPort !== bindPort) {
-            transportUrl = `iicp://${upnp.externalIp}:${transportPort}`;
-            profile.detectionLog.push(`tier-1: UPnP mapped ${bindPort} → ${publicUrl} AND ${transportPort} → ${transportUrl} (spec v0.7.0 dual-endpoint)`);
+            const extTransport = upnp.portMapping?.[transportPort] ?? transportPort;
+            transportUrl = `iicp://${upnp.externalIp}:${extTransport}`;
+            profile.detectionLog.push(`tier-1: UPnP mapped ${bindPort}→${extBind} (${publicUrl}) AND ${transportPort}→${extTransport} (${transportUrl}) ` +
+                `(spec v0.7.0 dual-endpoint; AddAnyPortMapping used if ext≠internal)`);
         }
         else {
-            profile.detectionLog.push(`tier-1: UPnP mapped ${bindPort} → ${publicUrl}`);
+            profile.detectionLog.push(`tier-1: UPnP mapped ${bindPort}→${extBind} (${publicUrl})`);
         }
         const result = newProfile(1, "upnp_mapped");
         result.publicEndpoint = publicUrl;
@@ -159,17 +181,111 @@ async function detectNat(opts) {
         profile.detectionLog.push(`tier-1: IGD found (${upnp.igdDevice}) but mapping refused — ${upnp.error}`);
     }
     // ADR-043 §10 — IPv6 fallback when no v4 path is usable.
-    const v6 = tryIpv6Fallback(profile, bindPort, transportPort);
+    const v6 = await tryIpv6Fallback(profile, bindPort, transportPort);
     if (v6)
         return v6;
+    // Tier 4 external tunnel auto-detect: ngrok, tailscale funnel, env-var override.
+    const tunnelUrl = await detectExternalTunnel(bindPort, Math.min(timeoutMs, 3000));
+    if (tunnelUrl) {
+        profile.detectionLog.push(`tier-4: external tunnel auto-detected → ${JSON.stringify(tunnelUrl)}`);
+        const t4 = newProfile(1, "external_tunnel");
+        t4.publicEndpoint = tunnelUrl;
+        t4.internalEndpoint = profile.internalEndpoint;
+        t4.detectionLog = profile.detectionLog;
+        return t4;
+    }
     profile.operatorGuidance =
         "No automatic port mapping available. Options:\n" +
             "  1. Configure your router to forward an external port to this host\n" +
             "  2. Set publicEndpoint to your real external URL\n" +
-            "  3. Use an external tunnel (Cloudflare Tunnel, ngrok, tailscale funnel)\n" +
+            "  3. Run `ngrok http <port>` or `cloudflared tunnel --url http://localhost:<port>` " +
+            "and export IICP_TUNNEL_URL=<the https URL>\n" +
             "See iicp.network/docs/nat-aware-adapter-setup.md for the details.";
     return profile;
 }
+// ── External tunnel auto-detect ──────────────────────────────────────────────
+/**
+ * Detect a running external tunnel daemon and return its public HTTPS URL.
+ *
+ * Checks in order:
+ *   1. IICP_TUNNEL_URL / TUNNEL_URL / CLOUDFLARE_TUNNEL_URL env vars
+ *   2. ngrok — local REST API at http://127.0.0.1:4040/api/tunnels
+ *   3. tailscale funnel — `tailscale serve status --json` CLI
+ */
+async function detectExternalTunnel(bindPort, timeoutMs = 3000) {
+    // env-var override (cloudflared Quick Tunnels, any custom setup)
+    for (const envVar of ["IICP_TUNNEL_URL", "TUNNEL_URL", "CLOUDFLARE_TUNNEL_URL"]) {
+        const url = process.env[envVar] ?? "";
+        if (url.startsWith("https://"))
+            return url;
+    }
+    const ngrok = await detectNgrokTunnel(bindPort, timeoutMs);
+    if (ngrok)
+        return ngrok;
+    return detectTailscaleFunnel(bindPort, timeoutMs);
+}
+async function detectNgrokTunnel(bindPort, timeoutMs = 3000) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), Math.min(timeoutMs, 2000));
+    try {
+        const resp = await fetch("http://127.0.0.1:4040/api/tunnels", { signal: ctrl.signal });
+        if (!resp.ok)
+            return null;
+        const data = (await resp.json());
+        let firstHttps = null;
+        for (const tunnel of data.tunnels ?? []) {
+            const pubUrl = tunnel.public_url ?? "";
+            if (!pubUrl.startsWith("https://"))
+                continue;
+            const cfgAddr = tunnel.config?.addr ?? "";
+            if (cfgAddr.includes(`:${bindPort}`))
+                return pubUrl;
+            if (!firstHttps)
+                firstHttps = pubUrl;
+        }
+        return firstHttps;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+async function detectTailscaleFunnel(bindPort, timeoutMs = 3000) {
+    const { execFile } = await import("node:child_process").catch(() => ({ execFile: null }));
+    if (!execFile)
+        return null;
+    const run = (cmd, args) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
+        execFile(cmd, args, (err, stdout) => {
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve(stdout);
+        });
+    });
+    try {
+        const statusJson = await run("tailscale", ["status", "--json"]);
+        const status = JSON.parse(statusJson);
+        const dnsName = (status.Self?.DNSName ?? "").replace(/\.$/, "");
+        if (!dnsName)
+            return null;
+        const serveJson = await run("tailscale", ["serve", "status", "--json"]);
+        const serve = JSON.parse(serveJson);
+        for (const [src, cfg] of Object.entries(serve.TCP ?? {})) {
+            if (cfg.Funnel && src.includes(`:${bindPort}`)) {
+                const portSuffix = bindPort !== 443 && bindPort !== 80 ? `:${bindPort}` : "";
+                return `https://${dnsName}${portSuffix}`;
+            }
+        }
+    }
+    catch {
+        /* not running or not installed */
+    }
+    return null;
+}
 /**
  * ADR-043 §4 — IPv6 qualification probe (#342).
  *
@@ -256,6 +372,56 @@ function listGlobalIpv6Addresses() {
     }
     return Array.from(new Set(out)).sort();
 }
+/**
+ * Enumerate local GUAs ranked by likelihood-of-being-pinhole-accepted.
+ *
+ * macOS only has the "secured" vs "temporary" vs "deprecated" flag distinction
+ * via `ifconfig` (node:os doesn't expose it). On Linux we fall back to first-
+ * GUA-per-interface. AVM FRITZ!Box only authorises AddPinhole for the
+ * **current temporary** RFC 4941 address, so on Mac we put those first.
+ */
+function rankedGlobalIpv6Candidates() {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { execSync } = require("node:child_process");
+            const out = execSync("ifconfig", { encoding: "utf-8" });
+            const currentTemp = [];
+            const secured = [];
+            const other = [];
+            for (const raw of out.split("\n")) {
+                const line = raw.trim();
+                if (!line.startsWith("inet6 "))
+                    continue;
+                const parts = line.split(/\s+/);
+                if (parts.length < 2)
+                    continue;
+                const addr = (parts[1] ?? "").split("%")[0];
+                if (!addr)
+                    continue;
+                const first = parseInt(addr.split(":")[0] ?? "0", 16);
+                if ((first & 0xe000) !== 0x2000)
+                    continue; // GUA only
+                const flags = parts.slice(2).join(" ").toLowerCase();
+                if (flags.includes("deprecated"))
+                    other.push(addr);
+                else if (flags.includes("secured"))
+                    secured.push(addr);
+                else if (flags.includes("temporary") || flags.includes("autoconf"))
+                    currentTemp.push(addr);
+                else
+                    other.push(addr);
+            }
+            const ranked = [...currentTemp, ...secured, ...other];
+            return Array.from(new Set(ranked));
+        }
+        catch {
+            return listGlobalIpv6Addresses();
+        }
+    }
+    return listGlobalIpv6Addresses();
+}
 function isPrivacyV6(addr) {
     // Heuristic — EUI-64 places `ff:fe` in the middle 16 bits of the interface ID.
     // RFC 4941 privacy addresses use a random interface ID without this marker.
@@ -266,7 +432,7 @@ function isPrivacyV6(addr) {
     // Crude: privacy addresses don't have 'ff:fe' anywhere in the last 4 hextets
     return !addr.toLowerCase().includes("ff:fe");
 }
-function tryIpv6Fallback(profile, bindPort, transportPort) {
+async function tryIpv6Fallback(profile, bindPort, transportPort) {
     if (!profile.ipv6)
         return null;
     if (!profile.ipv6.globalV6Available || !profile.ipv6.externalV6Reachable)
@@ -277,17 +443,39 @@ function tryIpv6Fallback(profile, bindPort, transportPort) {
     if (transportPort && transportPort !== bindPort) {
         transportUrl = `iicp://[${v6Addr}]:${transportPort}`;
     }
-    profile.detectionLog.push(`tier-1-ipv6: advertising ${publicUrl} (verified outbound v6; router firewall pinhole still required — covered by #343)`);
+    profile.detectionLog.push(`tier-1-ipv6: advertising ${publicUrl} (verified outbound v6; attempting UPnP IGDv2 pinhole — #343)`);
+    // ADR-043 §5 / #343 — attempt UPnP IPv6 firewall pinhole.
+    try {
+        const pin = await tryUpnpIpv6Pinhole(v6Addr, bindPort, { leaseSeconds: 3600 });
+        if (pin) {
+            profile.ipv6.pinholeActive = true;
+            profile.ipv6.pinholeUniqueId = pin.uniqueId;
+            profile.ipv6.pinholeLeaseSeconds = pin.leaseSeconds;
+            profile.ipv6.pinholeInboundAllowed = pin.inboundAllowed;
+            profile.detectionLog.push(`tier-1-ipv6: AddPinhole OK — uid=${pin.uniqueId} lease=${pin.leaseSeconds}s`);
+        }
+        else {
+            profile.ipv6.pinholeActive = false;
+            profile.detectionLog.push(`tier-1-ipv6: AddPinhole declined or no WANIPv6FirewallControl IGD found — operator must open inbound TCP/${bindPort} manually`);
+        }
+    }
+    catch (exc) {
+        profile.ipv6.pinholeActive = false;
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        profile.detectionLog.push(`tier-1-ipv6: pinhole attempt error: ${msg}`);
+    }
     const result = newProfile(1, "direct");
     result.publicEndpoint = publicUrl;
     result.transportEndpoint = transportUrl;
     result.internalEndpoint = profile.internalEndpoint;
     result.detectionLog = profile.detectionLog;
     result.ipv6 = profile.ipv6;
+    const pinholeNote = profile.ipv6.pinholeActive
+        ? `UPnP IPv6 pinhole opened (uid=${profile.ipv6.pinholeUniqueId}). `
+        : `Router firewall pinhole not opened — manual rule may be required. `;
     result.operatorGuidance =
         `Advertising IPv6 GUA ${v6Addr}. Inbound IPv4 isn't available (no UPnP success / CGNAT), ` +
-            `but your IPv6 surface is routable. For external clients to reach this node over IPv6, ` +
-            `ensure your router's firewall allows inbound TCP on port ${bindPort} → ${v6Addr}. ` +
+            `but your IPv6 surface is routable. ${pinholeNote}` +
             `The directory will Layer-2 dial-back to verify.`;
     return result;
 }
@@ -326,48 +514,185 @@ async function tryUpnpMapping(internalPorts, leaseSeconds) {
             client.close();
         return { success: false, mappedPorts: [], error: `externalIp failed: ${msg}` };
     }
-    try {
-        await client.portMapping({
-            public: primary,
-            private: primary,
-            ttl: leaseSeconds,
-            description: `iicp-client (ADR-041 tier-1) ${primary}`,
-            protocol: "tcp",
-        });
+    // Map a single port — try 1:1 portMapping first, fall back to a raw-SOAP
+    // AddAnyPortMapping call (IGDv2 §2.5.13) when the IGD reports conflict.
+    // nat-upnp doesn't expose AddAnyPortMapping directly, so we hit the
+    // WANIPConnection service via the same SSDP+SOAP plumbing the v6 pinhole
+    // path uses.
+    async function mapOne(internal) {
+        const desc = `iicp-client (ADR-041 tier-1) ${internal}`;
+        try {
+            await client.portMapping({
+                public: internal,
+                private: internal,
+                ttl: leaseSeconds,
+                description: desc,
+                protocol: "tcp",
+            });
+            return internal;
+        }
+        catch (exc) {
+            const msg = exc instanceof Error ? exc.message : String(exc);
+            // eslint-disable-next-line no-console
+            console.warn(`UPnP: portMapping ${internal} failed (${msg}); trying AddAnyPortMapping`);
+        }
+        const assigned = await tryAddAnyPortMapping(internal, desc, leaseSeconds);
+        if (assigned !== null) {
+            // eslint-disable-next-line no-console
+            console.log(`UPnP: AddAnyPortMapping assigned external ${assigned} for internal ${internal}`);
+        }
+        return assigned;
     }
-    catch (exc) {
-        const msg = exc instanceof Error ? exc.message : String(exc);
+    const assignedPrimary = await mapOne(primary);
+    if (assignedPrimary === null) {
         if (client.close)
             client.close();
         return {
             success: false,
             externalIp,
             mappedPorts: [],
-            error: `AddPortMapping failed for primary port ${primary}: ${msg}`,
+            error: `portMapping + AddAnyPortMapping both failed for primary port ${primary}`,
         };
     }
     const mapped = [primary];
+    const portMapping = { [primary]: assignedPrimary };
     for (const extra of internalPorts.slice(1)) {
-        try {
-            await client.portMapping({
-                public: extra,
-                private: extra,
-                ttl: leaseSeconds,
-                description: `iicp-client (ADR-041 tier-1) ${extra}`,
-                protocol: "tcp",
-            });
+        const assigned = await mapOne(extra);
+        if (assigned !== null) {
             mapped.push(extra);
+            portMapping[extra] = assigned;
         }
-        catch (exc) {
-            const msg = exc instanceof Error ? exc.message : String(exc);
-            // Best-effort — log via detection_log path; primary already succeeded.
+        else {
             // eslint-disable-next-line no-console
-            console.warn(`UPnP: failed to map additional port ${extra} (primary ${primary} ok): ${msg}`);
+            console.warn(`UPnP: failed to map additional port ${extra} (primary ${primary}→${assignedPrimary} ok)`);
         }
     }
     if (client.close)
         client.close();
-    return { success: true, externalIp, externalPort: primary, mappedPorts: mapped };
+    return {
+        success: true,
+        externalIp,
+        externalPort: assignedPrimary,
+        mappedPorts: mapped,
+        portMapping,
+    };
+}
+/**
+ * Raw-SOAP AddAnyPortMapping (IGDv2 §2.5.13) for the WANIPConnection /
+ * WANPPPConnection service. Used as a fallback when nat-upnp's 1:1
+ * portMapping fails on conflict.
+ */
+async function tryAddAnyPortMapping(internalPort, description, leaseSeconds) {
+    // Discover WANIPConnection / WANPPPConnection
+    const STypes = [
+        "urn:schemas-upnp-org:service:WANIPConnection:2",
+        "urn:schemas-upnp-org:service:WANIPConnection:1",
+        "urn:schemas-upnp-org:service:WANPPPConnection:1",
+    ];
+    for (const st of STypes) {
+        const hits = await ssdpDiscover(st, 3000);
+        for (const hit of hits) {
+            const svc = await fetchWanConnectionService(hit.location, st, 3000);
+            if (!svc)
+                continue;
+            // We need the LAN IP that's on the IGD's subnet — reuse the picked
+            // local IP. nat-upnp normally figures that out; here we let the IGD
+            // resolve it via the request source IP (NewInternalClient set below).
+            const localV4 = pickLocalV4ForGateway(hit.location);
+            if (!localV4)
+                continue;
+            const result = await soapCall(svc.controlURL, svc.serviceType, "AddAnyPortMapping", {
+                NewRemoteHost: "",
+                NewExternalPort: internalPort,
+                NewProtocol: "TCP",
+                NewInternalPort: internalPort,
+                NewInternalClient: localV4,
+                NewEnabled: 1,
+                NewPortMappingDescription: description,
+                NewLeaseDuration: leaseSeconds,
+            }, 5000);
+            const assigned = result ? parseInt(result.NewReservedPort ?? "0", 10) : 0;
+            if (assigned > 0)
+                return assigned;
+        }
+    }
+    return null;
+}
+async function fetchWanConnectionService(deviceUrl, expectedType, timeoutMs) {
+    let xml;
+    try {
+        const r = await fetch(deviceUrl, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!r.ok)
+            return null;
+        xml = await r.text();
+    }
+    catch {
+        return null;
+    }
+    const re = /<service>([\s\S]*?)<\/service>/gi;
+    let m;
+    while ((m = re.exec(xml)) !== null) {
+        const block = m[1];
+        const typeM = block.match(/<serviceType>([^<]+)<\/serviceType>/i);
+        const ctrlM = block.match(/<controlURL>([^<]+)<\/controlURL>/i);
+        if (typeM && ctrlM && typeM[1].trim() === expectedType) {
+            let controlURL = ctrlM[1].trim();
+            if (!/^https?:\/\//i.test(controlURL)) {
+                const base = new URL(deviceUrl);
+                controlURL = new URL(controlURL, `${base.protocol}//${base.host}`).toString();
+            }
+            return { controlURL, serviceType: expectedType };
+        }
+    }
+    return null;
+}
+function pickLocalV4ForGateway(deviceUrl) {
+    try {
+        const base = new URL(deviceUrl);
+        const gwHost = base.hostname;
+        const m = gwHost.match(/^(\d+\.\d+\.\d+)\./);
+        if (!m)
+            return null;
+        const prefix = m[1];
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const os = require("node:os");
+        const ifs = os.networkInterfaces();
+        for (const list of Object.values(ifs)) {
+            if (!list)
+                continue;
+            for (const ent of list) {
+                if (ent.family === "IPv4" && !ent.internal && ent.address.startsWith(prefix + ".")) {
+                    return ent.address;
+                }
+            }
+        }
+    }
+    catch {
+        /* no-op */
+    }
+    return null;
+}
+/**
+ * Cloud-VM auto-detect: returns the first public-routable IPv4 found on a
+ * local network interface. Covers bare-metal VPS scenarios (Hetzner,
+ * DigitalOcean, Vultr) where the public IP is assigned directly to an
+ * interface. On AWS/GCP (private IP only visible) returns null.
+ */
+function detectPublicV4OnInterfaces() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const nodeOs = require("node:os");
+    const ifs = nodeOs.networkInterfaces();
+    for (const list of Object.values(ifs)) {
+        if (!list)
+            continue;
+        for (const ent of list) {
+            if (ent.family !== "IPv4" || ent.internal)
+                continue;
+            if (!isNonPublicIpv4(ent.address))
+                return ent.address;
+        }
+    }
+    return null;
 }
 // ── External-IP probe + routability helpers ──────────────────────────────────
 async function probeExternalIp(url, timeoutMs = 5000) {
@@ -506,4 +831,209 @@ function withTimeout(p, ms) {
         });
     });
 }
+async function ssdpDiscover(serviceType, timeoutMs = 3000) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const dgram = require("node:dgram");
+    const sock = dgram.createSocket({ type: "udp4", reuseAddr: true });
+    const hits = [];
+    const msg = Buffer.from(`M-SEARCH * HTTP/1.1\r\n` +
+        `HOST: 239.255.255.250:1900\r\n` +
+        `MAN: "ssdp:discover"\r\n` +
+        `MX: 2\r\n` +
+        `ST: ${serviceType}\r\n\r\n`);
+    return new Promise((resolve) => {
+        sock.on("message", (data) => {
+            const text = data.toString("utf-8");
+            const locMatch = text.match(/LOCATION:\s*(\S+)/i);
+            const stMatch = text.match(/^ST:\s*(\S+)/im);
+            if (locMatch && stMatch) {
+                hits.push({ location: locMatch[1], st: stMatch[1] });
+            }
+        });
+        sock.on("error", () => {
+            sock.close();
+            resolve(hits);
+        });
+        sock.bind(0, () => {
+            sock.setBroadcast(true);
+            sock.send(msg, 1900, "239.255.255.250", () => undefined);
+        });
+        setTimeout(() => {
+            try {
+                sock.close();
+            }
+            catch { /* no-op */ }
+            resolve(hits);
+        }, timeoutMs);
+    });
+}
+async function fetchFirewallService(deviceUrl, timeoutMs = 3000) {
+    let xml;
+    try {
+        const r = await fetch(deviceUrl, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!r.ok)
+            return null;
+        xml = await r.text();
+    }
+    catch {
+        return null;
+    }
+    // Crude regex match — full XML parsing not worth the dep here.
+    const services = [];
+    const re = /<service>([\s\S]*?)<\/service>/gi;
+    let m;
+    while ((m = re.exec(xml)) !== null) {
+        const block = m[1];
+        const typeM = block.match(/<serviceType>([^<]+)<\/serviceType>/i);
+        const ctrlM = block.match(/<controlURL>([^<]+)<\/controlURL>/i);
+        if (typeM && ctrlM)
+            services.push({ type: typeM[1].trim(), control: ctrlM[1].trim() });
+    }
+    const v6 = services.find((s) => s.type.includes("WANIPv6FirewallControl"));
+    if (!v6)
+        return null;
+    // controlURL may be relative
+    let controlURL = v6.control;
+    if (!/^https?:\/\//i.test(controlURL)) {
+        const base = new URL(deviceUrl);
+        controlURL = new URL(controlURL, `${base.protocol}//${base.host}`).toString();
+    }
+    return { controlURL, serviceType: v6.type };
+}
+async function soapCall(controlURL, serviceType, action, args, timeoutMs = 5000) {
+    const argXml = Object.entries(args)
+        .map(([k, v]) => `<${k}>${String(v)}</${k}>`)
+        .join("");
+    const body = `<?xml version="1.0"?>\n` +
+        `<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" ` +
+        `s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">` +
+        `<s:Body>` +
+        `<u:${action} xmlns:u="${serviceType}">${argXml}</u:${action}>` +
+        `</s:Body></s:Envelope>`;
+    try {
+        const r = await fetch(controlURL, {
+            method: "POST",
+            headers: {
+                "Content-Type": 'text/xml; charset="utf-8"',
+                SOAPACTION: `"${serviceType}#${action}"`,
+            },
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!r.ok)
+            return null;
+        const text = await r.text();
+        const out = {};
+        const re = /<([A-Za-z][A-Za-z0-9_]*)>([^<]*)<\/\1>/g;
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            // Skip envelope/body wrappers
+            if (["Envelope", "Body"].includes(m[1]))
+                continue;
+            out[m[1]] = m[2];
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ADR-043 §5 (#343) — open an inbound IPv6 firewall pinhole on the IGD.
+ * Returns `{ uniqueId, leaseSeconds, inboundAllowed }` on success, null otherwise.
+ *
+ * Operators close the pinhole on shutdown via `deleteIpv6Pinhole(uniqueId)`.
+ */
+async function tryUpnpIpv6Pinhole(internalV6, internalPort, opts = {}) {
+    const lease = opts.leaseSeconds ?? 3600;
+    const protocol = opts.protocol ?? 6; // TCP
+    const timeout = opts.timeoutMs ?? 5000;
+    const hits = await ssdpDiscover("urn:schemas-upnp-org:service:WANIPv6FirewallControl:1", timeout);
+    for (const hit of hits) {
+        const svc = await fetchFirewallService(hit.location, timeout);
+        if (!svc)
+            continue;
+        const status = await soapCall(svc.controlURL, svc.serviceType, "GetFirewallStatus", {}, timeout);
+        const inboundAllowed = (status?.InboundPinholeAllowed ?? "0") === "1";
+        if (!inboundAllowed)
+            return null;
+        const result = await soapCall(svc.controlURL, svc.serviceType, "AddPinhole", {
+            RemoteHost: "",
+            RemotePort: 0,
+            InternalClient: internalV6,
+            InternalPort: internalPort,
+            Protocol: protocol,
+            LeaseTime: lease,
+        }, timeout);
+        if (!result)
+            return null;
+        const uid = parseInt(result.UniqueID ?? "0", 10);
+        return { uniqueId: uid, leaseSeconds: lease, inboundAllowed: true };
+    }
+    return null;
+}
+async function tryOpenV6PinholeForEndpoint(endpoint, bindPort) {
+    const log = [];
+    const m = endpoint.match(/^(https?):\/\/\[([0-9a-fA-F:]+)\](?::(\d+))?/);
+    if (!m)
+        return { pinholeActive: false, detectionLog: log };
+    const scheme = m[1];
+    const v6Host = m[2];
+    const portInUrl = m[3] ? parseInt(m[3], 10) : bindPort;
+    // GUA range check
+    const first = parseInt(v6Host.split(":")[0] ?? "0", 16);
+    if ((first & 0xe000) !== 0x2000) {
+        log.push(`v6 pinhole: skip — ${v6Host} is not a GUA (2000::/3 required)`);
+        return { pinholeActive: false, detectionLog: log };
+    }
+    const candidates = [v6Host, ...rankedGlobalIpv6Candidates().filter((c) => c !== v6Host)];
+    let chosen = null;
+    let chosenResult = null;
+    for (const cand of candidates) {
+        log.push(`v6 pinhole: attempting AddPinhole for [${cand}]:${portInUrl}`);
+        const r = await tryUpnpIpv6Pinhole(cand, portInUrl, { leaseSeconds: 3600 });
+        if (r) {
+            chosen = cand;
+            chosenResult = r;
+            break;
+        }
+    }
+    if (!chosen || !chosenResult) {
+        log.push("v6 pinhole: not opened on any local GUA — if your router is a " +
+            "FRITZ!Box, enable 'Internet → Filters → IPv6 → Selbständige " +
+            "Portfreigaben durch das Gerät erlauben' (or equivalent). Error 606 " +
+            "from the IGD = router-side ACL block, NOT a SOAP problem.");
+        return { pinholeActive: false, detectionLog: log };
+    }
+    const out = {
+        pinholeActive: true,
+        pinholeUniqueId: chosenResult.uniqueId,
+        pinholeLeaseSeconds: chosenResult.leaseSeconds,
+        pinholeInboundAllowed: chosenResult.inboundAllowed,
+        detectionLog: log,
+    };
+    log.push(`v6 pinhole: AddPinhole OK — uid=${chosenResult.uniqueId} lease=${chosenResult.leaseSeconds}s on [${chosen}]`);
+    if (chosen !== v6Host) {
+        const rewritten = `${scheme}://[${chosen}]:${portInUrl}`;
+        log.push(`v6 pinhole: rewriting public_endpoint ${endpoint} → ${rewritten} ` +
+            `(original v6 rejected by IGD, pinhole opened on different local GUA)`);
+        out.rewrittenEndpoint = rewritten;
+    }
+    return out;
+}
+/** ADR-043 §5 — close a previously-opened IPv6 pinhole. Best-effort. */
+async function deleteIpv6Pinhole(uniqueId, timeoutMs = 5000) {
+    const hits = await ssdpDiscover("urn:schemas-upnp-org:service:WANIPv6FirewallControl:1", timeoutMs);
+    for (const hit of hits) {
+        const svc = await fetchFirewallService(hit.location, timeoutMs);
+        if (!svc)
+            continue;
+        const result = await soapCall(svc.controlURL, svc.serviceType, "DeletePinhole", {
+            UniqueID: uniqueId,
+        }, timeoutMs);
+        if (result !== null)
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=nat_detection.js.map