@serfab/cadre-host 1.13.0 → 1.15.0

package/dist/nat/port-mapper.js

@@ -1,225 +1,184 @@
+import { BlockList } from 'node:net';
+import { networkInterfaces } from 'node:os';
 import debug from 'debug';
+import { upnpNat } from '@achingbrain/nat-port-mapper';
 import { NatError } from './types.js';
 const log = debug('cadre:host:nat-port-mapper');
-/** Default lease TTL: 1 hour. The router must keep our mapping at least this long. */
+/**
+ * Default lease TTL: 1 hour. `@achingbrain/nat-port-mapper` takes the TTL in
+ * milliseconds and floors the lease it asks the router for at 3600 s, so a
+ * shorter value here would still lease an hour.
+ */
 export const DEFAULT_LEASE_TTL_MS = 60 * 60 * 1000;
-/** Default refresh cadence: half the TTL, so two refreshes per lease. */
+/** Default renewal cadence: half the TTL, so two renewals per lease. */
 export const DEFAULT_REFRESH_MS = 30 * 60 * 1000;
+/** How long to listen for a UPnP gateway's SSDP answer before giving up. */
+export const GATEWAY_DISCOVERY_TIMEOUT_MS = 10000;
+/** Bound on one SOAP call to the router (map, unmap, external IP). */
+export const GATEWAY_OPERATION_TIMEOUT_MS = 10000;
+/** Signal that aborts after `ms`; the timer is cleared by `done()` so it never holds the process open. */
+function deadline(ms) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`timed out after ${ms} ms`)), ms);
+    timer.unref();
+    return { signal: controller.signal, done: () => clearTimeout(timer) };
+}
 /**
- * Default factory: loads @achingbrain/nat-port-mapper. Wrapped in dynamic
- * import so a missing dep at install time doesn't crash the package.
+ * Pick the IPv4 address of the local interface whose subnet contains the router.
+ *
+ * Not `mapAll`: that maps on every local address and leaves stray mappings for
+ * VPN and container interfaces. The address returned is the one a user is told
+ * to forward to, so it must be the one on the router's own network.
  */
-export async function createDefaultPortMapper(opts = {}) {
-    let mod;
-    try {
-        mod = (await import('@achingbrain/nat-port-mapper'));
-    }
-    catch (err) {
-        throw new NatError('mapping_failed', `@achingbrain/nat-port-mapper is not installed: ${err.message}`);
-    }
-    let client;
-    try {
-        client = await mod.upnpNat({
+export function pickLanAddress(routerHost, interfaces = networkInterfaces()) {
+    for (const entries of Object.values(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.family !== 'IPv4' || entry.internal || !entry.cidr)
+                continue;
+            const prefix = Number(entry.cidr.split('/')[1]);
+            if (!Number.isInteger(prefix))
+                continue;
+            const subnet = new BlockList();
+            try {
+                subnet.addSubnet(entry.address, prefix, 'ipv4');
+                if (subnet.check(routerHost, 'ipv4'))
+                    return entry.address;
+            }
+            catch (err) {
+                log('skipping interface entry %s (%s): %s', entry.address, entry.cidr, err.message);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * UPnP port mapper over `@achingbrain/nat-port-mapper` v4: `upnpNat()` hands
+ * out a client that discovers gateways; mapping, unmapping and the external IP
+ * live on the discovered `Gateway`.
+ *
+ * The library's auto-refresh stays off: cadre-host renews leases itself so it
+ * can report lease expiry and per-mapping failures.
+ */
+export class UpnpPortMapper {
+    constructor(opts = {}) {
+        this.gateway = null;
+        this.lanAddress = null;
+        this.client = upnpNat({
             description: opts.description ?? 'sereus-cadre-host',
-            ttl: Math.round((opts.ttlMs ?? DEFAULT_LEASE_TTL_MS) / 1000),
+            autoRefresh: false,
         });
     }
-    catch (err) {
-        throw new NatError('mapping_failed', `upnpNat() failed: ${err.message}`);
-    }
-    return new NatPortMapperAdapter(client, opts.ttlMs ?? DEFAULT_LEASE_TTL_MS);
-}
-class NatPortMapperAdapter {
-    constructor(client, defaultTtlMs) {
-        this.client = client;
-        this.defaultTtlMs = defaultTtlMs;
-    }
-    async map(opts) {
-        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;
-        const protocol = opts.protocol ?? 'tcp';
-        let externalIp = null;
-        try {
-            externalIp = await this.client.externalIp();
-        }
-        catch (err) {
-            log('externalIp() failed: %s', err.message);
-        }
+    async discover() {
+        const gateway = await this.findIpv4Gateway();
+        if (!gateway)
+            return null;
+        const lanAddress = pickLanAddress(gateway.host);
+        if (!lanAddress) {
+            throw new NatError('router_unreachable', `found a UPnP router at ${gateway.host} but no local IPv4 interface shares its subnet`);
+        }
+        this.gateway = gateway;
+        this.lanAddress = lanAddress;
+        log('discovered gateway %s (%s), mapping from %s', gateway.id, gateway.host, lanAddress);
+        return { lanAddress, routerHost: gateway.host };
+    }
+    async map(req) {
+        const { gateway, lanAddress } = this.requireGateway();
+        const op = deadline(GATEWAY_OPERATION_TIMEOUT_MS);
         try {
-            await this.client.map({
-                localPort: opts.internalPort,
-                externalPort: opts.externalPort,
-                protocol,
-                ttl: Math.round(ttlMs / 1000),
+            const mapping = await gateway.map(req.internalPort, lanAddress, {
+                externalPort: req.internalPort,
+                protocol: req.protocol,
+                ttl: req.ttlMs,
+                autoRefresh: false,
+                signal: op.signal,
             });
+            return { externalPort: mapping.externalPort, leaseExpiresAt: new Date(Date.now() + req.ttlMs) };
         }
         catch (err) {
-            throw new NatError('mapping_failed', `router refused mapping for port ${opts.externalPort}: ${err.message}`);
-        }
-        return {
-            mode: 'auto-upnp',
-            externalIp,
-            externalPort: opts.externalPort,
-            internalPort: opts.internalPort,
-            protocol,
-            leaseExpiresAt: new Date(Date.now() + ttlMs),
-        };
-    }
-    async verify(externalPort, protocol = 'tcp') {
-        void externalPort;
-        void protocol;
-        // The current library doesn't expose an introspection API. Treat a
-        // working externalIp() as a proxy for "router still reachable" — refresh
-        // failures will surface via re-running map().
+            throw new NatError('mapping_failed', `router refused the mapping for port ${req.internalPort}: ${err.message}`);
+        }
+        finally {
+            op.done();
+        }
+    }
+    // NOTE: the library tracks the mappings this process made and `unmap` only sends a
+    // delete for those, so after a host restart a port mapped by the previous process is
+    // left to expire with its lease rather than deleted. It also names the INTERNAL port
+    // as the external one in that delete, so a mapping the router granted on another
+    // external port is not deleted either; it, too, expires with its lease (1 h). And it
+    // appends one tracked entry per successful `map` of a port, so after N renewals an
+    // unmap sends N deletes (the first is the one that counts); they all run under the
+    // one 10 s bound, which caps the cost of a process that has renewed for days.
+    async unmap(internalPort, _protocol) {
+        if (!this.gateway)
+            return;
+        const op = deadline(GATEWAY_OPERATION_TIMEOUT_MS);
         try {
-            await this.client.externalIp();
-            return true;
+            await this.gateway.unmap(internalPort, { signal: op.signal });
         }
         catch (err) {
-            log('verify() failed: %s', err.message);
-            return false;
+            log('unmap(%d) failed: %s', internalPort, err.message);
+        }
+        finally {
+            op.done();
         }
     }
     async externalIp() {
+        if (!this.gateway)
+            return null;
+        const op = deadline(GATEWAY_OPERATION_TIMEOUT_MS);
         try {
-            return await this.client.externalIp();
+            return await this.gateway.externalIp({ signal: op.signal });
         }
         catch (err) {
             log('externalIp() failed: %s', err.message);
             return null;
         }
-    }
-    async unmap(externalPort, protocol = 'tcp') {
-        try {
-            await this.client.unmap({ externalPort, protocol });
-        }
-        catch (err) {
-            log('unmap(%d) failed: %s', externalPort, err.message);
-        }
-    }
-    async stop() {
-        try {
-            await this.client.stop();
+        finally {
+            op.done();
         }
-        catch (err) {
-            log('stop() failed: %s', err.message);
-        }
-    }
-}
-/**
- * Long-running orchestrator over a PortMapper. Owns the refresh timer and
- * surfaces the latest state for the NatService snapshot.
- */
-export class PortMapperService {
-    constructor(opts) {
-        this.refreshHandle = null;
-        this.started = false;
-        this.mapper = opts.mapper;
-        this.externalPort = opts.externalPort;
-        this.internalPort = opts.internalPort;
-        this.protocol = opts.protocol ?? 'tcp';
-        this.ttlMs = opts.ttlMs ?? DEFAULT_LEASE_TTL_MS;
-        this.refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;
-        this.nowFn = opts.now ?? (() => new Date());
-        this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
-        this.clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
-        this.state = {
-            mode: 'disabled',
-            externalPort: this.externalPort,
-            internalPort: this.internalPort,
-            routerExternalIp: null,
-            leaseExpiresAt: null,
-            lastError: null,
-        };
     }
-    getState() {
-        return { ...this.state };
-    }
-    /** Install the mapping and schedule periodic refresh. */
-    async start() {
-        if (this.started)
-            return;
-        this.started = true;
-        await this.installMapping();
-        this.scheduleRefresh();
-    }
-    /** Release the mapping and clear timers. Idempotent. */
+    /**
+     * Forget the gateway. Deliberately not `gateway.stop()`: that deletes every
+     * mapping this process made, and hosted children keep running across a host
+     * restart, so their mappings must outlive this process.
+     */
     async stop() {
-        if (!this.started)
-            return;
-        this.started = false;
-        if (this.refreshHandle) {
-            this.clearTimer(this.refreshHandle);
-            this.refreshHandle = null;
-        }
+        this.gateway = null;
+        this.lanAddress = null;
+    }
+    requireGateway() {
+        if (!this.gateway || !this.lanAddress) {
+            throw new NatError('router_unreachable', 'no UPnP gateway discovered');
+        }
+        return { gateway: this.gateway, lanAddress: this.lanAddress };
+    }
+    /**
+     * First IPv4 gateway to answer the SSDP search, or null when none did within
+     * the timeout.
+     *
+     * NOTE: the library searches for `InternetGatewayDevice:2` only (its
+     * `upnp/discovery.js`), and a router that implements only version 1 does not
+     * answer a version-2 search, so such a router reads as "not found". There is
+     * no library option for it; if it shows up on real hosts, the fix is a fork or
+     * another library.
+     */
+    async findIpv4Gateway() {
+        const search = deadline(GATEWAY_DISCOVERY_TIMEOUT_MS);
         try {
-            await this.mapper.unmap(this.externalPort, this.protocol);
-        }
-        catch (err) {
-            log('unmap during stop failed: %s', err.message);
-        }
-        try {
-            await this.mapper.stop();
+            for await (const gateway of this.client.findGateways({ signal: search.signal })) {
+                if (gateway.family === 'IPv4')
+                    return gateway;
+            }
+            return null;
         }
         catch (err) {
-            log('mapper.stop() failed: %s', err.message);
-        }
-        this.state = {
-            ...this.state,
-            mode: 'disabled',
-            routerExternalIp: null,
-            leaseExpiresAt: null,
-        };
-    }
-    /** Force an immediate verify+refresh cycle (used by testReachability). */
-    async refresh() {
-        if (!this.started)
-            return this.getState();
-        const ok = await this.mapper.verify(this.externalPort, this.protocol).catch(() => false);
-        if (!ok) {
-            log('verify() returned false; re-mapping');
-            await this.installMapping();
-            return this.getState();
+            if (search.signal.aborted)
+                return null;
+            throw new NatError('router_unreachable', `UPnP discovery failed: ${err.message}`);
         }
-        // Refresh: re-issue the mapping to extend the lease.
-        await this.installMapping();
-        return this.getState();
-    }
-    scheduleRefresh() {
-        if (this.refreshHandle)
-            this.clearTimer(this.refreshHandle);
-        this.refreshHandle = this.setTimer(() => {
-            void this.refresh().catch((err) => log('refresh timer error: %s', err.message));
-            // Re-arm after the call to avoid drift.
-            this.scheduleRefresh();
-        }, this.refreshMs);
-    }
-    async installMapping() {
-        try {
-            const r = await this.mapper.map({
-                externalPort: this.externalPort,
-                internalPort: this.internalPort,
-                protocol: this.protocol,
-                ttlMs: this.ttlMs,
-            });
-            this.state = {
-                mode: r.mode,
-                externalPort: r.externalPort,
-                internalPort: r.internalPort,
-                routerExternalIp: r.externalIp,
-                leaseExpiresAt: r.leaseExpiresAt,
-                lastError: null,
-            };
-            log('mapped port %d (mode=%s, externalIp=%s)', r.externalPort, r.mode, r.externalIp ?? '?');
-        }
-        catch (err) {
-            const message = err.message;
-            this.state = {
-                ...this.state,
-                mode: 'failed',
-                leaseExpiresAt: null,
-                lastError: message,
-            };
-            log('mapping failed: %s', message);
+        finally {
+            search.done();
         }
     }
 }

package/dist/nat/port-mapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"port-mapper.js","sourceRoot":"","sources":["../../src/nat/port-mapper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"port-mapper.js","sourceRoot":"","sources":["../../src/nat/port-mapper.ts"],"names":[],"mappings":"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"}

package/dist/nat/reachability.d.ts

@@ -1,19 +1,36 @@
-import type { DirectReachability, PortForwardMode } from './types.js';
-export interface ReachabilityInput {
-    portMode: PortForwardMode;
+/**
+ * Reachability verdicts: one per hosted node, and the host-level roll-up the
+ * dashboard badge shows. Heuristics over the mapping table, not a dial-back —
+ * libp2p AutoNAT is a later ticket.
+ */
+import type { DirectReachability, NodeReachability, NodeVerdict, PortRoute } from './types.js';
+export interface NodeVerdictInput {
+    tcp: PortRoute;
+    /** Null for a handle persisted by an older build without a WebSocket port. */
+    ws: PortRoute | null;
+    /** Whether a public host part exists: a DDNS hostname, or a public IPv4. */
+    hostKnown: boolean;
     cgnatDetected: boolean;
+    upnpEnabled: boolean;
+    gatewayFound: boolean;
+    /** The address a user forwards to; null when no gateway was found. */
+    lanAddress: string | null;
+}
+export interface NodeVerdictResult {
+    verdict: NodeVerdict;
+    reason: string | null;
 }
 /**
- * v1 reachability heuristic.
- *
- * Returns:
- *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
- *     external IP isn't actually reachable from the open internet).
- *   - 'unreachable' when port mapping failed.
- *   - 'reachable' when an auto mapping succeeded.
- *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
- *
- * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
- * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
+ * `unreachable` when either port has no usable route or the host part is
+ * unknown; otherwise `manual` when either port is forwarded by hand, `direct`
+ * when the ports are reached as-is (public mode, with the firewall reminder as
+ * the reason), else `mapped`. A UPnP route under CGNAT is not usable: the
+ * router's mapping is on a carrier-private address.
+ */
+export declare function evaluateNodeReachability(input: NodeVerdictInput): NodeVerdictResult;
+/**
+ * Host roll-up: `cgnat` when CGNAT is detected and no node is reachable
+ * through a manual route; `unknown` with no running nodes; `reachable` when
+ * every running node is `mapped`/`manual`/`direct`; else `unreachable`.
  */
-export declare function evaluateReachability(input: ReachabilityInput): DirectReachability;
+export declare function evaluateHostReachability(nodes: ReadonlyArray<Pick<NodeReachability, 'running' | 'verdict'>>, cgnatDetected: boolean): DirectReachability;

package/dist/nat/reachability.js

@@ -1,29 +1,117 @@
 /**
- * v1 reachability heuristic.
- *
- * Returns:
- *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
- *     external IP isn't actually reachable from the open internet).
- *   - 'unreachable' when port mapping failed.
- *   - 'reachable' when an auto mapping succeeded.
- *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
- *
- * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
- * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
+ * Reachability verdicts: one per hosted node, and the host-level roll-up the
+ * dashboard badge shows. Heuristics over the mapping table, not a dial-back —
+ * libp2p AutoNAT is a later ticket.
  */
-export function evaluateReachability(input) {
+/**
+ * `unreachable` when either port has no usable route or the host part is
+ * unknown; otherwise `manual` when either port is forwarded by hand, `direct`
+ * when the ports are reached as-is (public mode, with the firewall reminder as
+ * the reason), else `mapped`. A UPnP route under CGNAT is not usable: the
+ * router's mapping is on a carrier-private address.
+ */
+export function evaluateNodeReachability(input) {
+    const ports = portRoutes(input);
+    const failing = ports.filter(({ route }) => !usable(route, input.cgnatDetected));
+    if (!input.hostKnown) {
+        return { verdict: 'unreachable', reason: HOST_UNKNOWN_REASON };
+    }
+    if (failing.length > 0) {
+        return { verdict: 'unreachable', reason: describeFailures(failing, input) };
+    }
+    if (ports.some(({ route }) => route.source === 'manual'))
+        return { verdict: 'manual', reason: null };
+    if (ports.some(({ route }) => route.source === 'direct'))
+        return { verdict: 'direct', reason: firewallReminder(ports) };
+    return { verdict: 'mapped', reason: null };
+}
+/**
+ * Host roll-up: `cgnat` when CGNAT is detected and no node is reachable
+ * through a manual route; `unknown` with no running nodes; `reachable` when
+ * every running node is `mapped`/`manual`/`direct`; else `unreachable`.
+ */
+export function evaluateHostReachability(nodes, cgnatDetected) {
+    const running = nodes.filter((n) => n.running);
+    if (cgnatDetected && !running.some((n) => n.verdict === 'manual'))
+        return 'cgnat';
+    if (running.length === 0)
+        return 'unknown';
+    return running.every((n) => n.verdict !== 'unreachable') ? 'reachable' : 'unreachable';
+}
+const HOST_UNKNOWN_REASON = "This host's public address is unknown: no dynamic DNS hostname is set and no public IPv4 address was detected. " +
+    'Set a DDNS hostname, or check that this machine can reach the internet.';
+function portRoutes(input) {
+    const out = [{ kind: 'tcp', route: input.tcp }];
+    if (input.ws)
+        out.push({ kind: 'ws', route: input.ws });
+    return out;
+}
+function usable(route, cgnatDetected) {
+    if (route.externalPort === null || route.source === null)
+        return false;
+    return !(cgnatDetected && route.source === 'upnp');
+}
+/** Behind CGNAT no router-side remedy helps, so CGNAT outranks whatever else failed the port. */
+function causeOf(route, input) {
     if (input.cgnatDetected)
         return 'cgnat';
-    switch (input.portMode) {
-        case 'auto-upnp':
-        case 'auto-natpmp':
-            return 'reachable';
-        case 'failed':
-            return 'unreachable';
-        case 'manual':
-        case 'disabled':
-        default:
-            return 'unknown';
+    if (route.error)
+        return 'refused';
+    if (!input.upnpEnabled)
+        return 'upnp_off';
+    if (!input.gatewayFound)
+        return 'no_gateway';
+    return 'pending';
+}
+/** One sentence per distinct cause, each naming every port that failed for it. */
+function describeFailures(failing, input) {
+    const byCause = new Map();
+    for (const entry of failing) {
+        const cause = causeOf(entry.route, input);
+        byCause.set(cause, [...(byCause.get(cause) ?? []), entry]);
     }
+    return [...byCause.entries()].map(([cause, entries]) => describeCause(cause, entries, input)).join(' ');
+}
+function describeCause(cause, entries, input) {
+    const names = entries.map(({ kind, route }) => `${kindLabel(kind)} port ${route.internalPort}`);
+    const lan = input.lanAddress ?? "this machine's LAN address";
+    const forwardHint = `Forward ${entries.length === 1 ? 'port' : 'ports'} ${listPorts(entries)} to ${lan} on your router, then tell cadre-host the external ${entries.length === 1 ? 'port' : 'ports'}.`;
+    switch (cause) {
+        case 'cgnat':
+            return `This host is behind carrier-grade NAT, so the ${joinNames(names)} cannot be reached from outside through your router, and neither UPnP nor a port forward on your router will help; a relay is needed.`;
+        case 'refused': {
+            const errors = entries.map(({ route }) => route.error).filter((e) => !!e);
+            return `Router refused the ${joinNames(names)} mapping (${errors.join('; ')}). ${forwardHint}`;
+        }
+        case 'upnp_off':
+            return `UPnP is off, so the ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped. Turn UPnP on, or: ${lowerFirst(forwardHint)}`;
+        case 'no_gateway':
+            return `No UPnP router answered, so the ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped. Enable UPnP on your router, or: ${lowerFirst(forwardHint)}`;
+        case 'pending':
+            return `The ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped yet; the router is being asked.`;
+    }
+}
+/** Public mode: nothing to map, but a host or cloud firewall can still block the ports. */
+function firewallReminder(ports) {
+    const numbers = ports.map(({ route }) => route.internalPort);
+    const ufw = numbers.length === 2 && Math.abs(numbers[0] - numbers[1]) === 1
+        ? `${Math.min(...numbers)}:${Math.max(...numbers)}/tcp`
+        : `${numbers.join(',')}/tcp`;
+    return `Reached directly at this machine's public address. Allow TCP ${ports.length === 1 ? 'port' : 'ports'} ${listPorts(ports)} through any firewall `
+        + `(for example: sudo ufw allow ${ufw}; and any cloud-provider firewall).`;
+}
+function kindLabel(kind) {
+    return kind === 'tcp' ? 'TCP' : 'WebSocket';
+}
+function listPorts(entries) {
+    return joinNames(entries.map(({ route }) => String(route.internalPort)));
+}
+function joinNames(names) {
+    if (names.length <= 1)
+        return names[0] ?? '';
+    return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+function lowerFirst(s) {
+    return s.charAt(0).toLowerCase() + s.slice(1);
 }
 //# sourceMappingURL=reachability.js.map

package/dist/nat/reachability.js.map

@@ -1 +1 @@
-{"version":3,"file":"reachability.js","sourceRoot":"","sources":["../../src/nat/reachability.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAwB;IAC3D,IAAI,KAAK,CAAC,aAAa;QAAE,OAAO,OAAO,CAAC;IACxC,QAAQ,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvB,KAAK,WAAW,CAAC;QACjB,KAAK,aAAa;YAChB,OAAO,WAAW,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC;QACvB,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}
+{"version":3,"file":"reachability.js","sourceRoot":"","sources":["../../src/nat/reachability.ts"],"names":[],"mappings":"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"}