@mesh-tech/mesh-cli 0.1.1 → 0.12.0

package/dist/src/utils/tunnel-ownership.js

@@ -0,0 +1,274 @@
+/**
+ * Ownership contract for the tunnel runner (MESH-2407).
+ *
+ * Three silent-dead-tunnel incidents in ten days (MESH-2169, MESH-2014, the
+ * #2991 re-review) shared one enabler: readiness was inferred from "something
+ * accepts TCP on the port". That conflates LIVENESS (a listener exists) with
+ * OWNERSHIP (the listener is OUR runner, wired to OUR SOCKS upstream). This
+ * module is the ownership half of the contract:
+ *
+ *  - The runner that actually binds the forwarder ports writes a MANIFEST
+ *    (pid, process-group id, a per-run random token, a loopback control port)
+ *    and answers a one-shot control handshake with that token plus the ports
+ *    it is listening on — read from its in-process `net.Server`s, so the
+ *    answer can't be faked by a foreign listener and probing it opens no
+ *    SOCKS→VPC data connection.
+ *  - Callers verify ownership (manifest → live pid → control handshake →
+ *    token/socks-port/port-coverage match) instead of dialing ports. A port
+ *    that accepts TCP without passing the handshake is a SQUATTER and must be
+ *    a loud failure, never adopt-and-continue.
+ *  - Teardown signals process GROUPS recorded here (plus argv-discovered
+ *    runners), so no kill path can orphan a grandchild with ports still bound.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+export function mintRunnerToken() {
+    return crypto.randomBytes(16).toString('hex');
+}
+export function readRunnerManifest(file) {
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeRunnerManifest(file, manifest) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(manifest, null, 2), { mode: 0o600 });
+}
+/**
+ * Remove the manifest — but only if it is still OURS (`token` matches). A dying
+ * runner must not clobber the manifest of a newer runner that already replaced it.
+ * Omit `token` for teardown paths that own the whole tenant state.
+ */
+export function clearRunnerManifest(file, token) {
+    if (token !== undefined && readRunnerManifest(file)?.token !== token)
+        return;
+    try {
+        fs.unlinkSync(file);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Process-group id of a pid via `ps` (macOS/BSD); null when undiscoverable. */
+export function getProcessGroupId(pid) {
+    try {
+        const out = execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const pgid = Number(out);
+        return Number.isInteger(pgid) && pgid > 0 ? pgid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pids of tunnel-runner processes for a tenant, parsed from `ps` output
+ * (`pid command` lines). Matches both `__run` and the legacy `__supervise`
+ * argv, and skips `exclude` (the calling process, when it IS the runner).
+ * Pure for unit tests; `discoverRunnerPids` feeds it live `ps` output.
+ */
+export function parseRunnerPidsFromPs(psOutput, tenant, exclude) {
+    const pids = [];
+    for (const line of psOutput.split('\n')) {
+        if (!/vpn\s+tunnel\s+(?:__run|__supervise)\s+/.test(line))
+            continue;
+        const m = line.trim().match(/^(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const argv = m[2].split(/\s+/);
+        // The tenant is the argument right after __run/__supervise — an exact
+        // match, so tenant "enc" never matches a runner for tenant "encore".
+        const i = argv.findIndex((a) => a === '__run' || a === '__supervise');
+        if (i === -1 || argv[i + 1] !== tenant)
+            continue;
+        const pid = Number(m[1]);
+        if (pid !== exclude)
+            pids.push(pid);
+    }
+    return pids;
+}
+/** Live argv discovery of runner pids for a tenant (empty when `ps` fails). */
+export function discoverRunnerPids(tenant, exclude) {
+    try {
+        const out = execFileSync('ps', ['ax', '-o', 'pid=,command='], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return parseRunnerPidsFromPs(out, tenant, exclude);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Start the runner's one-shot control endpoint on a loopback ephemeral port.
+ * Each connection gets one JSON line (the live payload) and is closed — no
+ * protocol state, nothing routable, and probing it touches no data plane.
+ */
+export function startControlServer(payload) {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer((socket) => {
+            socket.on('error', () => { });
+            try {
+                socket.end(`${JSON.stringify(payload())}\n`);
+            }
+            catch {
+                socket.destroy();
+            }
+        });
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            resolve({ server, port: server.address().port });
+        });
+    });
+}
+/** Dial the control endpoint and parse its one-line JSON answer; null on any failure. */
+export function queryControl(port, timeoutMs = 700) {
+    return new Promise((resolve) => {
+        const s = new net.Socket();
+        let buf = '';
+        let done = false;
+        const fin = (v) => {
+            if (done)
+                return;
+            done = true;
+            s.destroy();
+            resolve(v);
+        };
+        s.setTimeout(timeoutMs);
+        s.once('timeout', () => fin(null));
+        s.once('error', () => fin(null));
+        s.on('data', (d) => {
+            buf += d.toString();
+        });
+        s.once('close', () => {
+            try {
+                fin(JSON.parse(buf));
+            }
+            catch {
+                fin(null);
+            }
+        });
+        s.connect(port, '127.0.0.1');
+    });
+}
+function defaultPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The ownership handshake: manifest → live pid → control endpoint → token,
+ * SOCKS port, and port coverage all match. Anything less is NOT ours — the
+ * caller must treat an accepting-but-unowned port as a squatter, never reuse it.
+ */
+export async function verifyRunnerOwnership(args) {
+    const { manifest } = args;
+    if (!manifest)
+        return { ok: false, reason: 'no-manifest' };
+    const alive = args.isPidAlive ?? defaultPidAlive;
+    if (!alive(manifest.pid))
+        return { ok: false, reason: 'runner-dead' };
+    const resp = await (args.query ?? queryControl)(manifest.controlPort);
+    if (!resp)
+        return { ok: false, reason: 'no-control-answer' };
+    if (resp.token !== manifest.token)
+        return { ok: false, reason: 'token-mismatch', resp };
+    if (resp.socksPort !== args.expectedSocksPort) {
+        return { ok: false, reason: 'socks-port-mismatch', resp };
+    }
+    const listening = new Set(resp.listening);
+    const missing = args.expectedPorts.filter((p) => !listening.has(p));
+    if (missing.length > 0) {
+        return { ok: false, reason: `ports-not-listening:${missing.join(',')}`, resp };
+    }
+    return { ok: true, reason: '', resp };
+}
+/**
+ * Poll an ownership check until it passes or `deadlineMs` of wall-clock elapses;
+ * returns the last (failing) check otherwise. The deadline bounds TIME, not
+ * rounds — each check can itself cost up to the control-query timeout, so a
+ * round-counting loop would multiply the promised deadline several-fold.
+ * Retrying also matters for correctness, not just latency: two failure reasons
+ * are transient by design (`ports-not-listening:` while the runner's self-heal
+ * loop rebinds a forwarder, `no-control-answer` under accept-backlog pressure),
+ * and a single-shot sample of a healthy shared runner in one of those windows
+ * would tear it down for every concurrent session on the tenant (MESH-2014).
+ */
+export async function pollOwnership(check, deadlineMs) {
+    let last = { ok: false, reason: 'not-checked' };
+    const end = Date.now() + deadlineMs;
+    do {
+        last = await check();
+        if (last.ok)
+            return last;
+        await new Promise((r) => setTimeout(r, 250));
+    } while (Date.now() < end);
+    return last;
+}
+/** Best-effort `lsof` description of what holds a port ("cmd (pid N)"); null if unknown. */
+export function describePortOwner(port) {
+    try {
+        const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fcp'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // -F output: "p<pid>\nc<command>\n…" per process.
+        const pid = out.match(/^p(\d+)$/m)?.[1];
+        const cmd = out.match(/^c(.+)$/m)?.[1];
+        if (!pid && !cmd)
+            return null;
+        return `${cmd ?? '?'} (pid ${pid ?? '?'})`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Of `ports`, the ones something is accepting TCP on. Called AFTER ownership
+ * failed / teardown ran, so every hit is a foreign or stale listener.
+ */
+export async function findSquattedPorts(ports, accepts) {
+    const squatted = [];
+    for (const port of ports) {
+        if (await accepts(port))
+            squatted.push({ port, owner: describePortOwner(port) });
+    }
+    return squatted;
+}
+/**
+ * The loud-failure text for a squatted tunnel port (`mesh dev doctor` style:
+ * what is wrong, why we refuse, exactly what to run). Never adopt-and-continue.
+ */
+export function buildSquatterError(tenant, squatted, detail) {
+    const lines = squatted.map((s) => `    127.0.0.1:${s.port}  held by ${s.owner ?? 'an unidentified process'}`);
+    const first = squatted[0]?.port ?? '<port>';
+    return [
+        `Tunnel port(s) for tenant '${tenant}' are bound by a process mesh does not own${detail ? ` (${detail})` : ''}:`,
+        ...lines,
+        `  Refusing to reuse a foreign listener — traffic would silently flow to the wrong upstream.`,
+        `  To fix:`,
+        `    mesh vpn -t ${tenant} tunnel down --stop    # tear down mesh-owned runners + daemon`,
+        `    lsof -nP -iTCP:${first} -sTCP:LISTEN        # identify what still holds the port`,
+        `  then stop that process and re-run.`,
+        // Port blocks are a 63-bucket hash (MESH-2375), so a DIFFERENT tenant's
+        // runner can collide onto this block — in which case the `down` above is a
+        // no-op and only lsof identifies the real owner.
+        `  (If lsof names another mesh runner, it belongs to a different tenant — tear that one down instead.)`,
+    ].join('\n');
+}
+//# sourceMappingURL=tunnel-ownership.js.map

package/dist/src/utils/tunnel-ownership.js.map

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

package/dist/src/utils/vpn-join.d.ts

@@ -0,0 +1,32 @@
+type CtxConfig = {
+    issuer?: string;
+    vpnJoinBroker?: string;
+} | null;
+/**
+ * Resolve the broker URL, preferring the platform-published value from
+ * discovery (ContextConfig.vpnJoinBroker) and falling back to DNS-convention
+ * derivation for platforms not yet redeployed with the payload field.
+ */
+export declare function resolveVpnJoinBroker(context: string, getCfg?: (c: string) => CtxConfig): string | null;
+/**
+ * FALLBACK ONLY. Derive by convention — issuer host `identity.<env>.<domain>`
+ * → `vpn-join.<env>.<domain>` — mirroring deriveLoginServer (dev.ts:1479).
+ * Prefer resolveVpnJoinBroker, which reads the platform-published URL first.
+ */
+export declare function deriveVpnJoinBroker(context: string, getCfg?: (c: string) => CtxConfig): string | null;
+export interface MintDeps {
+    getValidToken: (context: string) => Promise<string | null>;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Fetch a single-use pre-auth key from the broker. Returns null on ANY failure
+ * (no token, non-2xx, network error) so the caller falls back to the browser
+ * relay join — the broker path is strictly additive.
+ */
+export declare function mintPreAuthKey(context: string, brokerUrl: string, deps: MintDeps): Promise<{
+    authKey: string;
+    loginServer: string;
+} | null>;
+export declare function realMintDeps(): MintDeps;
+export {};
+//# sourceMappingURL=vpn-join.d.ts.map

package/dist/src/utils/vpn-join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpn-join.d.ts","sourceRoot":"","sources":["../../../src/utils/vpn-join.ts"],"names":[],"mappings":"AAEA,KAAK,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,SAA4B,GAClD,MAAM,GAAG,IAAI,CAIf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,SAA4B,GAClD,MAAM,GAAG,IAAI,CAWf;AAED,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAgB1D;AAGD,wBAAgB,YAAY,IAAI,QAAQ,CAEvC"}

package/dist/src/utils/vpn-join.js

@@ -0,0 +1,62 @@
+import { getContextConfig, getValidToken } from "../commands/login.js";
+/**
+ * Resolve the broker URL, preferring the platform-published value from
+ * discovery (ContextConfig.vpnJoinBroker) and falling back to DNS-convention
+ * derivation for platforms not yet redeployed with the payload field.
+ */
+export function resolveVpnJoinBroker(context, getCfg = getContextConfig) {
+    const cfg = getCfg(context);
+    if (cfg?.vpnJoinBroker)
+        return cfg.vpnJoinBroker;
+    return deriveVpnJoinBroker(context, getCfg);
+}
+/**
+ * FALLBACK ONLY. Derive by convention — issuer host `identity.<env>.<domain>`
+ * → `vpn-join.<env>.<domain>` — mirroring deriveLoginServer (dev.ts:1479).
+ * Prefer resolveVpnJoinBroker, which reads the platform-published URL first.
+ */
+export function deriveVpnJoinBroker(context, getCfg = getContextConfig) {
+    const cfg = getCfg(context);
+    if (!cfg?.issuer)
+        return null;
+    try {
+        const u = new URL(cfg.issuer);
+        const parts = u.hostname.split(".");
+        parts[0] = "vpn-join";
+        return `https://${parts.join(".")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch a single-use pre-auth key from the broker. Returns null on ANY failure
+ * (no token, non-2xx, network error) so the caller falls back to the browser
+ * relay join — the broker path is strictly additive.
+ */
+export async function mintPreAuthKey(context, brokerUrl, deps) {
+    const token = await deps.getValidToken(context);
+    if (!token)
+        return null;
+    const doFetch = deps.fetchFn ?? fetch;
+    try {
+        const res = await doFetch(`${brokerUrl}/preauth`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body.authKey)
+            return null;
+        return { authKey: body.authKey, loginServer: body.loginServer ?? "" };
+    }
+    catch {
+        return null;
+    }
+}
+// Convenience for production callers that use the real login.ts token source.
+export function realMintDeps() {
+    return { getValidToken: (c) => getValidToken(c) };
+}
+//# sourceMappingURL=vpn-join.js.map

package/dist/src/utils/vpn-join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpn-join.js","sourceRoot":"","sources":["../../../src/utils/vpn-join.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAIvE;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,SAAmC,gBAAgB;IAEnD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,GAAG,EAAE,aAAa;QAAE,OAAO,GAAG,CAAC,aAAa,CAAC;IACjD,OAAO,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,SAAmC,gBAAgB;IAEnD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;QACtB,OAAO,WAAW,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAOD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,SAAiB,EACjB,IAAc;IAEd,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,SAAS,UAAU,EAAE;YAChD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA+C,CAAC;QAC9E,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC"}

package/dist/src/utils/vpn.d.ts

@@ -0,0 +1,62 @@
+/**
+ * VPN detection utilities
+ */
+/**
+ * Detect whether a Tailscale VPN connection is active.
+ *
+ * Uses socket-aware `execTailscaleCmd` so it works in both kernel tun mode
+ * (standard socket) and legacy userspace networking (/tmp/tailscale.sock).
+ * Returns `true` only when BackendState is "Running" and Self.Online is true.
+ * Returns `false` silently on any failure (binary missing, daemon stopped,
+ * parse error, missing fields).
+ */
+export declare function isVpnConnected(): Promise<boolean>;
+/** Connection details for the Headscale DNS writer sidecar. */
+export interface HeadscaleDnsConfig {
+    namespace: string;
+    pod: string;
+    container: string;
+    filePath: string;
+}
+/**
+ * Build a HeadscaleDnsConfig from tenant/env, following the same naming
+ * convention as `mesh vpn` (⁠{tenant}-{env}-headscale).
+ *
+ * Pod name, container, and file path are infrastructure conventions that
+ * rarely change — override via the optional parameter if they do.
+ */
+export declare function headscaleDnsConfig(tenant?: string, env?: string, overrides?: Partial<HeadscaleDnsConfig>): HeadscaleDnsConfig;
+export interface DnsRecord {
+    name: string;
+    type: "A";
+    value: string;
+}
+/**
+ * Retrieve the current Tailscale hostname and IP address.
+ *
+ * Returns `null` when Tailscale is not installed, not running, or not online.
+ */
+export declare function getTailscaleInfo(): Promise<{
+    hostname: string;
+    ip: string;
+} | null>;
+/**
+ * Read DNS records from the dns-writer sidecar in the Headscale pod.
+ *
+ * Throws with an actionable message if kubectl can't reach the pod.
+ * Returns an empty array when the file is missing or contains invalid JSON.
+ */
+export declare function readDnsRecords(cfg: HeadscaleDnsConfig): DnsRecord[];
+/**
+ * Write DNS A records to the dns-writer sidecar in the Headscale pod.
+ *
+ * Pipes JSON via stdin to avoid shell-escaping issues.
+ * Throws with an actionable message if kubectl can't reach the pod.
+ */
+export declare function registerDnsRecords(cfg: HeadscaleDnsConfig, records: DnsRecord[]): void;
+/**
+ * Remove DNS records whose `name` ends with `suffix` from the Headscale pod.
+ * Best-effort: logs a warning on failure instead of throwing.
+ */
+export declare function unregisterDnsRecords(cfg: HeadscaleDnsConfig, suffix: string): void;
+//# sourceMappingURL=vpn.d.ts.map

package/dist/src/utils/vpn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpn.d.ts","sourceRoot":"","sources":["../../../src/utils/vpn.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH;;;;;;;;GAQG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAQvD;AASD,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,SAAS,EACf,GAAG,SAAQ,EACX,SAAS,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GACtC,kBAAkB,CAQpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAsDD;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAqBzF;AAUD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EAAE,CA6BnE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAgBtF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAQlF"}

package/dist/src/utils/vpn.js

@@ -0,0 +1,183 @@
+/**
+ * VPN detection utilities
+ */
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+const TAILSCALE_PATHS = [
+    "tailscale",
+    "/Applications/Tailscale.app/Contents/MacOS/Tailscale",
+];
+/**
+ * Detect whether a Tailscale VPN connection is active.
+ *
+ * Uses socket-aware `execTailscaleCmd` so it works in both kernel tun mode
+ * (standard socket) and legacy userspace networking (/tmp/tailscale.sock).
+ * Returns `true` only when BackendState is "Running" and Self.Online is true.
+ * Returns `false` silently on any failure (binary missing, daemon stopped,
+ * parse error, missing fields).
+ */
+export async function isVpnConnected() {
+    try {
+        const stdout = await execTailscaleCmd(["status", "--json"]);
+        const status = JSON.parse(stdout);
+        return status.BackendState === "Running" && status.Self?.Online === true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// DNS record management & Tailscale info
+// ---------------------------------------------------------------------------
+/** Standard socket (kernel tun mode), then legacy (userspace mode). */
+const TAILSCALE_SOCKET_PATHS = ["/var/run/tailscale/tailscaled.sock", "/tmp/tailscale.sock"];
+/**
+ * Build a HeadscaleDnsConfig from tenant/env, following the same naming
+ * convention as `mesh vpn` (⁠{tenant}-{env}-headscale).
+ *
+ * Pod name, container, and file path are infrastructure conventions that
+ * rarely change — override via the optional parameter if they do.
+ */
+export function headscaleDnsConfig(tenant = "mesh", env = "dev", overrides) {
+    return {
+        namespace: `${tenant}-${env}-headscale`,
+        pod: "headscale-0",
+        container: "dns-writer",
+        filePath: "/var/lib/headscale/dns/extra-records.json",
+        ...overrides,
+    };
+}
+/**
+ * Execute a tailscale CLI command, trying each known binary path.
+ * Automatically appends `--socket <path>` when a tailscale socket is found.
+ */
+function execTailscaleCmd(args) {
+    const socketPath = TAILSCALE_SOCKET_PATHS.find(existsSync);
+    const attempts = [];
+    for (const binary of TAILSCALE_PATHS) {
+        if (socketPath) {
+            attempts.push({ binary, args: ["--socket", socketPath, ...args] });
+        }
+        attempts.push({ binary, args });
+    }
+    return new Promise((resolve, reject) => {
+        let index = 0;
+        function tryNext() {
+            if (index >= attempts.length) {
+                reject(new Error("All tailscale binary attempts failed"));
+                return;
+            }
+            const attempt = attempts[index++];
+            execFile(attempt.binary, attempt.args, (error, stdout) => {
+                if (error) {
+                    tryNext();
+                }
+                else {
+                    resolve(stdout);
+                }
+            });
+        }
+        tryNext();
+    });
+}
+/**
+ * Retrieve the current Tailscale hostname and IP address.
+ *
+ * Returns `null` when Tailscale is not installed, not running, or not online.
+ */
+export async function getTailscaleInfo() {
+    try {
+        const stdout = await execTailscaleCmd(["status", "--json"]);
+        const status = JSON.parse(stdout);
+        if (status.BackendState === "Running" &&
+            status.Self?.Online === true &&
+            status.Self.HostName &&
+            status.Self.TailscaleIPs?.length) {
+            return {
+                hostname: status.Self.HostName,
+                ip: status.Self.TailscaleIPs[0],
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Helper: build kubectl exec args for the dns-writer sidecar. */
+function dnsWriterExec(cfg, cmd, interactive = false) {
+    return [
+        "exec", ...(interactive ? ["-i"] : []),
+        "-n", cfg.namespace, cfg.pod, "-c", cfg.container, "--", ...cmd,
+    ];
+}
+/**
+ * Read DNS records from the dns-writer sidecar in the Headscale pod.
+ *
+ * Throws with an actionable message if kubectl can't reach the pod.
+ * Returns an empty array when the file is missing or contains invalid JSON.
+ */
+export function readDnsRecords(cfg) {
+    try {
+        const raw = execFileSync("kubectl", dnsWriterExec(cfg, ["cat", cfg.filePath]), {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed === "[]")
+            return [];
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            console.warn(`[vpn] DNS records file contains invalid JSON, treating as empty`);
+            return [];
+        }
+    }
+    catch (err) {
+        const msg = err.message ?? String(err);
+        if (msg.includes("not found") || msg.includes("Unable to connect")) {
+            throw new Error(`Cannot reach Headscale DNS writer (namespace=${cfg.namespace}, pod=${cfg.pod}).\n` +
+                `Verify kubectl context and that the Headscale pod is running:\n` +
+                `  kubectl get pods -n ${cfg.namespace}`);
+        }
+        if (msg.includes("No such file")) {
+            return [];
+        }
+        // Unexpected error — rethrow
+        throw err;
+    }
+}
+/**
+ * Write DNS A records to the dns-writer sidecar in the Headscale pod.
+ *
+ * Pipes JSON via stdin to avoid shell-escaping issues.
+ * Throws with an actionable message if kubectl can't reach the pod.
+ */
+export function registerDnsRecords(cfg, records) {
+    const json = JSON.stringify(records);
+    try {
+        execFileSync("kubectl", dnsWriterExec(cfg, ["sh", "-c", `cat > '${cfg.filePath}'`], true), { input: json, stdio: ["pipe", "pipe", "pipe"] });
+    }
+    catch (err) {
+        const msg = err.message ?? String(err);
+        throw new Error(`Failed to write DNS records to Headscale (namespace=${cfg.namespace}, pod=${cfg.pod}).\n` +
+            `${msg.includes("not found") ? "Pod not found. " : ""}` +
+            `Verify kubectl context: kubectl get pods -n ${cfg.namespace}`);
+    }
+}
+/**
+ * Remove DNS records whose `name` ends with `suffix` from the Headscale pod.
+ * Best-effort: logs a warning on failure instead of throwing.
+ */
+export function unregisterDnsRecords(cfg, suffix) {
+    try {
+        const records = readDnsRecords(cfg);
+        const filtered = records.filter((r) => !r.name.endsWith(suffix));
+        registerDnsRecords(cfg, filtered);
+    }
+    catch {
+        // Best-effort cleanup — silent on failure
+    }
+}
+//# sourceMappingURL=vpn.js.map

package/dist/src/utils/vpn.js.map

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