mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-20 15:19:16 +00:00
Bound the main-process TCC probe to 3s, only treat real private IPv4/IPv6 literals as LAN, prefer proxy as first hop when set, and annotate unreachability using either the target or the first hop. Closes the remaining merge blockers for #2663.
253 lines
8.8 KiB
JavaScript
253 lines
8.8 KiB
JavaScript
"use strict";
|
|
|
|
/**
|
|
* macOS Local Network privacy gate (Apple TN3179 / issue #2663).
|
|
*
|
|
* Since macOS 15, outbound TCP/UDP to LAN addresses requires the user's
|
|
* Local Network privilege. Netcatty already declares
|
|
* NSLocalNetworkUsageDescription and rewrites the main executable LC_UUID
|
|
* (#1040), but SSH sessions normally run inside Electron's utilityProcess
|
|
* (terminal worker). Connections from that helper often fail with
|
|
* EHOSTUNREACH without ever registering "Netcatty" under
|
|
* System Settings → Privacy & Security → Local Network — so the user never
|
|
* gets a prompt and has nothing to toggle.
|
|
*
|
|
* Before the worker opens a LAN socket, the main process performs a short
|
|
* TCP connect to the first hop so TCC attributes the attempt to the app
|
|
* bundle and can present the system alert.
|
|
*/
|
|
|
|
const net = require("node:net");
|
|
|
|
/** Keep the pre-SSH LAN probe short so dead hosts do not stall the dial. */
|
|
const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
|
|
const LOCAL_NETWORK_HINT =
|
|
"macOS may be blocking Local Network access. Open System Settings → Privacy & Security → Local Network, enable Netcatty, then reconnect.";
|
|
|
|
function stripIpBrackets(value) {
|
|
return String(value || "").replace(/^\[|\]$/g, "").trim();
|
|
}
|
|
|
|
function isIpv4LocalNetworkAddress(hostname) {
|
|
const parts = hostname.split(".");
|
|
if (parts.length !== 4 || !parts.every((part) => /^\d+$/.test(part))) return false;
|
|
const octets = parts.map(Number);
|
|
if (octets.some((n) => n < 0 || n > 255)) return false;
|
|
const [a, b] = octets;
|
|
if (a === 10) return true;
|
|
if (a === 172 && b >= 16 && b <= 31) return true;
|
|
if (a === 192 && b === 168) return true;
|
|
if (a === 169 && b === 254) return true;
|
|
if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT / Tailscale
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* First hextet of an IPv6 address (handles leading "::" compression).
|
|
* Returns null when the address is not a usable IPv6 form for prefix checks.
|
|
*/
|
|
function ipv6FirstHextet(address) {
|
|
const lower = String(address || "").toLowerCase();
|
|
if (!lower) return null;
|
|
if (lower.startsWith("::ffff:")) return null;
|
|
if (lower.startsWith("::")) return 0;
|
|
const first = lower.split(":")[0];
|
|
if (!/^[0-9a-f]{1,4}$/.test(first)) return null;
|
|
return Number.parseInt(first, 16);
|
|
}
|
|
|
|
function isIpv6LocalNetworkAddress(hostname) {
|
|
if (net.isIP(hostname) !== 6) return false;
|
|
const lower = hostname.toLowerCase();
|
|
if (lower.startsWith("::ffff:")) {
|
|
// IPv4-mapped IPv6 — classify the embedded v4 address.
|
|
return isLocalNetworkHostname(lower.slice("::ffff:".length));
|
|
}
|
|
const hextet = ipv6FirstHextet(lower);
|
|
if (hextet == null || Number.isNaN(hextet)) return false;
|
|
// fc00::/7 unique local
|
|
if (hextet >= 0xfc00 && hextet <= 0xfdff) return true;
|
|
// fe80::/10 link-local
|
|
if (hextet >= 0xfe80 && hextet <= 0xfebf) return true;
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* True only for literal private IP forms. Hostnames (including ones that
|
|
* merely start with "fc"/"fd") are never treated as LAN without resolution.
|
|
*/
|
|
function isLocalNetworkHostname(hostname) {
|
|
if (hostname == null) return false;
|
|
const cleaned = stripIpBrackets(hostname);
|
|
if (!cleaned) return false;
|
|
|
|
const ipVersion = net.isIP(cleaned);
|
|
if (ipVersion === 4) return isIpv4LocalNetworkAddress(cleaned);
|
|
if (ipVersion === 6) return isIpv6LocalNetworkAddress(cleaned);
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* First TCP hop the local process will open for this SSH dial.
|
|
* Prefer HTTP/SOCKS proxy host when configured, else first jump host, else target.
|
|
*/
|
|
function resolveFirstTcpEndpoint(options = {}) {
|
|
const proxy = options.proxy && typeof options.proxy === "object" ? options.proxy : null;
|
|
if (
|
|
proxy
|
|
&& proxy.type !== "command"
|
|
&& String(proxy.host || proxy.hostname || "").trim()
|
|
) {
|
|
const hostname = String(proxy.host || proxy.hostname || "").trim();
|
|
const port = Number(proxy.port);
|
|
return {
|
|
hostname,
|
|
port: Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 1080,
|
|
};
|
|
}
|
|
|
|
const jumpHosts = Array.isArray(options.jumpHosts) ? options.jumpHosts : [];
|
|
if (jumpHosts.length > 0) {
|
|
const first = jumpHosts[0] || {};
|
|
const hostname = String(first.hostname || first.host || "").trim();
|
|
const port = Number(first.port);
|
|
return {
|
|
hostname,
|
|
port: Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 22,
|
|
};
|
|
}
|
|
|
|
const hostname = String(options.hostname || options.host || "").trim();
|
|
const port = Number(options.port);
|
|
return {
|
|
hostname,
|
|
port: Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 22,
|
|
};
|
|
}
|
|
|
|
function looksLikeHostUnreachableMessage(message) {
|
|
const text = String(message || "");
|
|
return /EHOSTUNREACH|ENETUNREACH|host is unreachable|network is unreachable/i.test(text);
|
|
}
|
|
|
|
function annotateMacLocalNetworkErrorMessage(message, options = {}) {
|
|
const platform = options.platform || process.platform;
|
|
const text = String(message || "");
|
|
if (platform !== "darwin") return text;
|
|
if (!looksLikeHostUnreachableMessage(text)) return text;
|
|
if (text.includes("Local Network")) return text;
|
|
|
|
const candidates = [
|
|
options.hostname,
|
|
options.host,
|
|
options.firstHopHostname,
|
|
].filter((value) => value != null && String(value).trim() !== "");
|
|
const touchesLan = candidates.some((value) => isLocalNetworkHostname(value));
|
|
if (!touchesLan) return text;
|
|
return `${text}\n\n${LOCAL_NETWORK_HINT}`;
|
|
}
|
|
|
|
function createMacLocalNetworkAccessGate(options = {}) {
|
|
const platform = options.platform || process.platform;
|
|
const versions = options.versions || process.versions;
|
|
const netModule = options.net || net;
|
|
const probedKeys = options.probedKeys || new Set();
|
|
const inFlight = options.inFlight || new Map();
|
|
const probeTimeoutMs = Number.isFinite(options.probeTimeoutMs)
|
|
? Math.max(500, Math.round(options.probeTimeoutMs))
|
|
: DEFAULT_PROBE_TIMEOUT_MS;
|
|
const setTimer = options.setTimer || setTimeout;
|
|
const clearTimer = options.clearTimer || clearTimeout;
|
|
// Bare Node unit tests (and non-Electron CLIs) must never open LAN sockets.
|
|
// Only the real Electron main process should trigger the TCC prompt.
|
|
const electronRuntime = options.forceElectron === true
|
|
|| (options.forceElectron !== false && Boolean(versions?.electron));
|
|
|
|
function probeKey(hostname, port) {
|
|
return `${String(hostname).toLowerCase()}:${port}`;
|
|
}
|
|
|
|
function runProbe(hostname, port) {
|
|
return new Promise((resolve) => {
|
|
let settled = false;
|
|
let socket = null;
|
|
let timer = null;
|
|
|
|
const finish = () => {
|
|
if (settled) return;
|
|
settled = true;
|
|
if (timer) clearTimer(timer);
|
|
try { socket?.destroy(); } catch { /* ignore */ }
|
|
resolve();
|
|
};
|
|
|
|
try {
|
|
socket = netModule.connect({ host: hostname, port }, finish);
|
|
socket.once?.("error", finish);
|
|
if (typeof socket.setTimeout === "function") {
|
|
socket.setTimeout(probeTimeoutMs, finish);
|
|
} else {
|
|
timer = setTimer(finish, probeTimeoutMs);
|
|
}
|
|
} catch {
|
|
finish();
|
|
}
|
|
});
|
|
}
|
|
|
|
async function ensureAccess(connectOptions = {}) {
|
|
if (platform !== "darwin") return { skipped: true, reason: "platform" };
|
|
if (!electronRuntime) return { skipped: true, reason: "not-electron" };
|
|
|
|
const endpoint = resolveFirstTcpEndpoint(connectOptions);
|
|
if (!endpoint.hostname || !isLocalNetworkHostname(endpoint.hostname)) {
|
|
return { skipped: true, reason: "not-local-network" };
|
|
}
|
|
|
|
const key = probeKey(endpoint.hostname, endpoint.port);
|
|
if (probedKeys.has(key)) return { skipped: true, reason: "cached" };
|
|
|
|
const pending = inFlight.get(key);
|
|
if (pending) {
|
|
await pending;
|
|
return { skipped: true, reason: "in-flight" };
|
|
}
|
|
|
|
const probe = runProbe(endpoint.hostname, endpoint.port).finally(() => {
|
|
inFlight.delete(key);
|
|
probedKeys.add(key);
|
|
});
|
|
inFlight.set(key, probe);
|
|
await probe;
|
|
return { probed: true, hostname: endpoint.hostname, port: endpoint.port };
|
|
}
|
|
|
|
return {
|
|
ensureAccess,
|
|
isLocalNetworkHostname,
|
|
resolveFirstTcpEndpoint,
|
|
getProbeTimeoutMs: () => probeTimeoutMs,
|
|
annotateErrorMessage(message, connectOptions = {}) {
|
|
const endpoint = resolveFirstTcpEndpoint(connectOptions);
|
|
return annotateMacLocalNetworkErrorMessage(message, {
|
|
platform,
|
|
hostname: connectOptions.hostname || connectOptions.host,
|
|
firstHopHostname: endpoint.hostname,
|
|
});
|
|
},
|
|
};
|
|
}
|
|
|
|
const defaultGate = createMacLocalNetworkAccessGate();
|
|
|
|
module.exports = {
|
|
LOCAL_NETWORK_HINT,
|
|
DEFAULT_PROBE_TIMEOUT_MS,
|
|
isLocalNetworkHostname,
|
|
resolveFirstTcpEndpoint,
|
|
annotateMacLocalNetworkErrorMessage,
|
|
createMacLocalNetworkAccessGate,
|
|
ensureMacLocalNetworkAccess: (options) => defaultGate.ensureAccess(options),
|
|
annotateMacLocalNetworkError: (message, options) => defaultGate.annotateErrorMessage(message, options),
|
|
};
|