@zswarm/core 0.1.7 → 0.1.9

package/dist/ops/routing.js

@@ -1,5 +1,6 @@
 import { hostname } from "node:os";
 import { sessionFromEnv } from "../zellij/session.js";
+import { describeServeTarget } from "./serve-tunnel.js";
 import { isTrue, optionalString } from "./util.js";
 export function invocationContext(args, env, injected) {
     const serve = optionalString(env.ZSWARM_SERVE);
@@ -9,7 +10,7 @@ export function invocationContext(args, env, injected) {
     const selected = sessionFromEnv(serve && !injected ? {} : env, optionalString(args.session));
     return {
         transport: injected?.kind ?? (serve ? "serve" : ssh ? "ssh" : "local"),
-        host: injected ? injected.host ?? hostname() : serve ?? ssh ?? hostname(),
+        host: injected ? injected.host ?? hostname() : serve ? describeServeTarget(serve) : ssh ?? hostname(),
         session: selected?.session ?? null,
         origin: {
             transport: injected ? "injected" : isTrue(args.local) ? "--local"

package/dist/ops/serve-bind.d.ts

@@ -0,0 +1,86 @@
+import { type NetworkInterfaceInfo } from "node:os";
+/** Bounded read of `tailscale status --json` for serve bind authorization. */
+export declare const SERVE_BIND_STATUS_MAX_BYTES: number;
+/** Default verification/startup budget for foreground `serve --listen` (not the server lifetime). */
+export declare const SERVE_BIND_VERIFY_TIMEOUT_MS = 10000;
+/** Env override for the Tailscale CLI binary (persisted on Windows install when set). */
+export declare const SERVE_TAILSCALE_BIN_ENV = "ZSWARM_TAILSCALE_BIN";
+export type TailscaleStatusRunner = (input: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    env: NodeJS.ProcessEnv;
+}) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export type NetworkInterfacesFn = () => NodeJS.Dict<NetworkInterfaceInfo[]>;
+export type ServeBindDeps = {
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    /**
+     * Relative verification budget when `deadline` is omitted. Callers that
+     * already fixed an absolute startup deadline should pass `deadline` instead
+     * of refreshing a new allowance from `now + timeoutMs`.
+     */
+    timeoutMs?: number;
+    /** Absolute verify/bind deadline (same clock as `now`). Preferred over `timeoutMs`. */
+    deadline?: number;
+    now?: () => number;
+    tailscaleStatus?: TailscaleStatusRunner;
+    networkInterfaces?: NetworkInterfacesFn;
+};
+export type ServeBindAuthorization = {
+    /** Exact host string passed to `server.listen` (literal, never a hostname). */
+    bindHost: string;
+    /** Canonical form used for membership checks. */
+    canonical: string;
+    family: 4 | 6;
+    mode: "loopback" | "tailscale";
+};
+export declare const SERVE_BIND_REMEDY: {
+    readonly literal: "Pass an explicit literal Tailscale IP from `tailscale ip -4` or `tailscale ip -6` (for example --listen 100.x.y.z:9419 or --listen '[fd7a:…]:9419'). Wildcards, hostnames, and non-Tailscale LAN/public addresses are refused.";
+    readonly loopbackDefault: "Default loopback (`127.0.0.1` / `::1`) needs no Tailscale CLI. Off-machine access stays an SSH tunnel to that loopback, or bind an owned Tailscale IP explicitly.";
+    readonly token: "Set ZSWARM_SERVE_TOKEN before serve. Tailnet membership does not replace the application token.";
+    readonly cliMissing: "Install the Tailscale CLI on this host (or set ZSWARM_TAILSCALE_BIN to its path), then retry. Loopback serve does not need Tailscale.";
+    readonly daemon: "Start Tailscale on this host (`tailscale up`) so `tailscale status --json` reports BackendState Running, then retry with the address from `tailscale ip`.";
+    readonly statusShape: "Tailscale status JSON was missing, truncated, oversized, or not the expected shape. Retry when `tailscale status --json --peers=false` succeeds locally.";
+    readonly notSelf: "That address is not in this node's Tailscale self addresses. Use `tailscale ip -4` / `-6` on this host; peer, subnet, and MagicDNS names are not bind identity.";
+    readonly conflict: "Tailscale status Self.TailscaleIPs and top-level TailscaleIPs disagree. Fix the local Tailscale profile, then retry.";
+    readonly osMissing: "Tailscale reported the address, but it is not assigned on a local OS interface (userspace/proxy-only Tailscale cannot use this mode). Use loopback + managed SSH, or enable a kernel/TUN Tailscale interface that owns the address.";
+    readonly cancelled: "Serve bind verification was cancelled before listen.";
+    readonly timeout: "Serve bind verification timed out before listen. Retry with a larger --timeout-ms on install, or check that the Tailscale CLI responds quickly.";
+    readonly bind: "Bind failed on the verified address with no fallback to 0.0.0.0, ::, loopback, or SSH. Free the port or restore the Tailscale address, then restart serve so verification runs again.";
+};
+/** Expand IPv6 to a fixed lowercase 8-hextet form for exact membership checks. */
+export declare function expandIPv6(address: string): string | null;
+/**
+ * Canonicalize a strict literal IP for comparison. Rejects hostnames, wildcards,
+ * unspecified addresses, and IPv4-mapped IPv6 after full expansion (no silent
+ * bypass onto the embedded v4 address).
+ */
+export declare function canonicalizeListenIp(raw: string): {
+    family: 4 | 6;
+    canonical: string;
+} | null;
+export declare function sameCanonicalIp(a: string, b: string): boolean;
+export declare function resolveTailscaleBin(env: NodeJS.ProcessEnv): string;
+export declare function defaultServeTailscaleStatus(input: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    env: NodeJS.ProcessEnv;
+}): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Authorize a serve listen host. Loopback needs no Tailscale evidence. Any other
+ * host requires a strict literal IP present in fresh local Tailscale self
+ * addresses and assigned on a local OS interface.
+ *
+ * Uses one absolute startup deadline across CLI and OS stages (shared with
+ * `startServe` when `deadline` is passed). Does not install a lifetime timer
+ * on a healthy server.
+ */
+export declare function authorizeServeListen(host: string, deps?: ServeBindDeps): Promise<ServeBindAuthorization>;

package/dist/ops/serve-bind.js

@@ -0,0 +1,354 @@
+import { execFile } from "node:child_process";
+import { isIP } from "node:net";
+import { networkInterfaces as osNetworkInterfaces } from "node:os";
+import { ZellijError } from "../errors.js";
+import { NOT_FOUND_EXIT } from "../exec.js";
+import { throwIfAborted } from "./util.js";
+function isLoopbackListenHost(host) {
+    const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    return (h === "127.0.0.1" ||
+        h === "localhost" ||
+        h === "::1" ||
+        h === "0:0:0:0:0:0:0:1");
+}
+/** Bounded read of `tailscale status --json` for serve bind authorization. */
+export const SERVE_BIND_STATUS_MAX_BYTES = 256 * 1024;
+/** Default verification/startup budget for foreground `serve --listen` (not the server lifetime). */
+export const SERVE_BIND_VERIFY_TIMEOUT_MS = 10_000;
+/** Env override for the Tailscale CLI binary (persisted on Windows install when set). */
+export const SERVE_TAILSCALE_BIN_ENV = "ZSWARM_TAILSCALE_BIN";
+export const SERVE_BIND_REMEDY = {
+    literal: "Pass an explicit literal Tailscale IP from `tailscale ip -4` or `tailscale ip -6` (for example --listen 100.x.y.z:9419 or --listen '[fd7a:…]:9419'). Wildcards, hostnames, and non-Tailscale LAN/public addresses are refused.",
+    loopbackDefault: "Default loopback (`127.0.0.1` / `::1`) needs no Tailscale CLI. Off-machine access stays an SSH tunnel to that loopback, or bind an owned Tailscale IP explicitly.",
+    token: "Set ZSWARM_SERVE_TOKEN before serve. Tailnet membership does not replace the application token.",
+    cliMissing: "Install the Tailscale CLI on this host (or set ZSWARM_TAILSCALE_BIN to its path), then retry. Loopback serve does not need Tailscale.",
+    daemon: "Start Tailscale on this host (`tailscale up`) so `tailscale status --json` reports BackendState Running, then retry with the address from `tailscale ip`.",
+    statusShape: "Tailscale status JSON was missing, truncated, oversized, or not the expected shape. Retry when `tailscale status --json --peers=false` succeeds locally.",
+    notSelf: "That address is not in this node's Tailscale self addresses. Use `tailscale ip -4` / `-6` on this host; peer, subnet, and MagicDNS names are not bind identity.",
+    conflict: "Tailscale status Self.TailscaleIPs and top-level TailscaleIPs disagree. Fix the local Tailscale profile, then retry.",
+    osMissing: "Tailscale reported the address, but it is not assigned on a local OS interface (userspace/proxy-only Tailscale cannot use this mode). Use loopback + managed SSH, or enable a kernel/TUN Tailscale interface that owns the address.",
+    cancelled: "Serve bind verification was cancelled before listen.",
+    timeout: "Serve bind verification timed out before listen. Retry with a larger --timeout-ms on install, or check that the Tailscale CLI responds quickly.",
+    bind: "Bind failed on the verified address with no fallback to 0.0.0.0, ::, loopback, or SSH. Free the port or restore the Tailscale address, then restart serve so verification runs again.",
+};
+function fail(message, details, remedy) {
+    throw new ZellijError("serve_auth", message, { ...details, remedy });
+}
+/** Expand IPv6 to a fixed lowercase 8-hextet form for exact membership checks. */
+export function expandIPv6(address) {
+    const raw = address.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    if (!raw || raw.includes(".") || isIP(raw) !== 6)
+        return null;
+    if (raw.includes(":::"))
+        return null;
+    const sides = raw.split("::");
+    if (sides.length > 2)
+        return null;
+    const head = sides[0] ? sides[0].split(":") : [];
+    const tail = sides.length === 2 && sides[1] ? sides[1].split(":") : [];
+    if (sides.length === 1 && head.length !== 8)
+        return null;
+    const missing = 8 - (head.length + tail.length);
+    if (sides.length === 2 && missing < 0)
+        return null;
+    if (sides.length === 1 && missing !== 0)
+        return null;
+    const mid = sides.length === 2 ? Array.from({ length: missing }, () => "0") : [];
+    const parts = [...head, ...mid, ...tail];
+    if (parts.length !== 8)
+        return null;
+    const hextets = [];
+    for (const part of parts) {
+        if (!/^[0-9a-f]{1,4}$/.test(part))
+            return null;
+        hextets.push(part.padStart(4, "0"));
+    }
+    return hextets.join(":");
+}
+const UNSPECIFIED_V6 = "0000:0000:0000:0000:0000:0000:0000:0000";
+function isUnsafeCanonicalIPv6(canonical) {
+    if (canonical === UNSPECIFIED_V6)
+        return true;
+    // IPv4-mapped (::ffff:x) after expansion, any spelling of the input.
+    const parts = canonical.split(":");
+    return (parts.length === 8 &&
+        parts[0] === "0000" &&
+        parts[1] === "0000" &&
+        parts[2] === "0000" &&
+        parts[3] === "0000" &&
+        parts[4] === "0000" &&
+        parts[5] === "ffff");
+}
+/**
+ * Canonicalize a strict literal IP for comparison. Rejects hostnames, wildcards,
+ * unspecified addresses, and IPv4-mapped IPv6 after full expansion (no silent
+ * bypass onto the embedded v4 address).
+ */
+export function canonicalizeListenIp(raw) {
+    const host = raw.trim().replace(/^\[|\]$/g, "");
+    if (!host)
+        return null;
+    if (host === "0.0.0.0" || host === "::" || host === "*" || host === "0")
+        return null;
+    const kind = isIP(host);
+    if (kind === 4) {
+        const parts = host.split(".");
+        if (parts.length !== 4)
+            return null;
+        const octets = [];
+        for (const part of parts) {
+            if (!/^\d{1,3}$/.test(part))
+                return null;
+            if (part.length > 1 && part.startsWith("0"))
+                return null;
+            const n = Number(part);
+            if (!Number.isInteger(n) || n < 0 || n > 255)
+                return null;
+            octets.push(n);
+        }
+        const canonical = octets.join(".");
+        if (canonical === "0.0.0.0")
+            return null;
+        return { family: 4, canonical };
+    }
+    if (kind === 6) {
+        const canonical = expandIPv6(host);
+        if (!canonical || isUnsafeCanonicalIPv6(canonical))
+            return null;
+        return { family: 6, canonical };
+    }
+    return null;
+}
+export function sameCanonicalIp(a, b) {
+    const left = canonicalizeListenIp(a);
+    const right = canonicalizeListenIp(b);
+    return Boolean(left && right && left.family === right.family && left.canonical === right.canonical);
+}
+function setKey(entry) {
+    return `${entry.family}/${entry.canonical}`;
+}
+function sameAddressSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const keys = new Set(a.map(setKey));
+    return b.every((entry) => keys.has(setKey(entry)));
+}
+/**
+ * Parse a present TailscaleIP list field. Fail closed on non-arrays and any
+ * non-canonicalizable member; do not filter invalid entries away.
+ */
+function parsePresentIpList(value, field) {
+    if (!Array.isArray(value)) {
+        fail(`zswarm serve Tailscale ${field} is not a valid address list`, { phase: "verify", cause: "invalid_ip_list", field }, SERVE_BIND_REMEDY.statusShape);
+    }
+    const out = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (typeof item !== "string" || !item.trim()) {
+            fail(`zswarm serve Tailscale ${field} contains a malformed address entry`, { phase: "verify", cause: "malformed_ip_entry", field }, SERVE_BIND_REMEDY.statusShape);
+        }
+        const normalized = canonicalizeListenIp(item);
+        if (!normalized) {
+            fail(`zswarm serve Tailscale ${field} contains an unusable address`, { phase: "verify", cause: "invalid_ip_entry", field }, SERVE_BIND_REMEDY.statusShape);
+        }
+        const key = setKey(normalized);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(normalized);
+    }
+    return out;
+}
+export function resolveTailscaleBin(env) {
+    const override = env[SERVE_TAILSCALE_BIN_ENV]?.trim();
+    return override || "tailscale";
+}
+export function defaultServeTailscaleStatus(input) {
+    const bin = resolveTailscaleBin(input.env);
+    return new Promise((resolve) => {
+        execFile(bin, ["status", "--json", "--peers=false"], {
+            timeout: Math.max(1, input.timeoutMs),
+            maxBuffer: SERVE_BIND_STATUS_MAX_BYTES,
+            windowsHide: true,
+            signal: input.signal,
+            env: input.env,
+        }, (error, stdout, stderr) => {
+            const failure = error;
+            if (failure && typeof failure.code === "string") {
+                const missing = failure.code === "ENOENT" || failure.code === "ENOTDIR";
+                resolve({
+                    code: missing ? NOT_FOUND_EXIT : 1,
+                    stdout: "",
+                    stderr: `${failure.code}: ${failure.message}`,
+                });
+                return;
+            }
+            if (failure && (failure.killed === true || failure.name === "AbortError")) {
+                resolve({
+                    code: -1,
+                    stdout: String(stdout ?? ""),
+                    stderr: failure.name === "AbortError" ? "tailscale cancelled" : "tailscale timed out",
+                });
+                return;
+            }
+            resolve({
+                code: failure && typeof failure.code === "number"
+                    ? failure.code
+                    : failure
+                        ? 1
+                        : 0,
+                stdout: String(stdout ?? "").slice(0, SERVE_BIND_STATUS_MAX_BYTES),
+                stderr: String(stderr ?? "").slice(0, 4_096),
+            });
+        });
+    });
+}
+function osOwnsCanonical(target, ifaces) {
+    for (const list of Object.values(ifaces)) {
+        if (!list)
+            continue;
+        for (const info of list) {
+            const normalized = canonicalizeListenIp(info.address);
+            if (normalized &&
+                normalized.family === target.family &&
+                normalized.canonical === target.canonical) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Authorize a serve listen host. Loopback needs no Tailscale evidence. Any other
+ * host requires a strict literal IP present in fresh local Tailscale self
+ * addresses and assigned on a local OS interface.
+ *
+ * Uses one absolute startup deadline across CLI and OS stages (shared with
+ * `startServe` when `deadline` is passed). Does not install a lifetime timer
+ * on a healthy server.
+ */
+export async function authorizeServeListen(host, deps = {}) {
+    const env = deps.env ?? process.env;
+    const signal = deps.signal;
+    const now = deps.now ?? Date.now;
+    throwIfAborted(signal);
+    if (isLoopbackListenHost(host)) {
+        const bindHost = host.trim().replace(/^\[|\]$/g, "");
+        return {
+            bindHost,
+            canonical: bindHost.toLowerCase(),
+            family: bindHost.includes(":") ? 6 : 4,
+            mode: "loopback",
+        };
+    }
+    const literal = canonicalizeListenIp(host);
+    if (!literal) {
+        fail(`zswarm serve refuses non-literal or unsafe listen host (${host}); bind only loopback or a verified local Tailscale IP`, { phase: "verify", cause: "listen_host", host }, SERVE_BIND_REMEDY.literal);
+    }
+    const deadline = typeof deps.deadline === "number" && Number.isFinite(deps.deadline)
+        ? deps.deadline
+        : now() + Math.max(1, Math.floor(deps.timeoutMs ?? SERVE_BIND_VERIFY_TIMEOUT_MS));
+    const remaining = () => deadline - now();
+    const assertRunnable = (stage) => {
+        throwIfAborted(signal);
+        const left = remaining();
+        if (left <= 0) {
+            fail(`zswarm serve bind verification timed out during ${stage} before listen`, { phase: "verify", cause: "timeout", stage }, SERVE_BIND_REMEDY.timeout);
+        }
+        return left;
+    };
+    const runner = deps.tailscaleStatus ?? defaultServeTailscaleStatus;
+    const ifacesFn = deps.networkInterfaces ?? osNetworkInterfaces;
+    const statusBudget = assertRunnable("status");
+    let statusResult;
+    try {
+        statusResult = await runner({ timeoutMs: statusBudget, signal, env });
+    }
+    catch (err) {
+        if (err instanceof ZellijError)
+            throw err;
+        fail(`Tailscale status failed during serve bind verification (${err instanceof Error ? err.message : "error"})`, { phase: "verify", cause: "tailscale_status" }, SERVE_BIND_REMEDY.daemon);
+    }
+    assertRunnable("status");
+    if (statusResult.code === NOT_FOUND_EXIT) {
+        fail("zswarm serve cannot verify a Tailscale listen address because the Tailscale CLI is missing", { phase: "verify", cause: "cli_missing" }, SERVE_BIND_REMEDY.cliMissing);
+    }
+    if (statusResult.code === -1) {
+        const cancelled = /cancel/i.test(statusResult.stderr) || signal?.aborted;
+        fail(cancelled
+            ? "zswarm serve bind verification was cancelled before listen"
+            : "zswarm serve bind verification timed out before listen", { phase: "verify", cause: cancelled ? "cancelled" : "timeout" }, cancelled ? SERVE_BIND_REMEDY.cancelled : SERVE_BIND_REMEDY.timeout);
+    }
+    if (statusResult.code !== 0) {
+        const combined = `${statusResult.stdout}\n${statusResult.stderr}`.toLowerCase();
+        const denied = /permission denied|access denied|failed to connect|tailscaled|daemon|stopped|needs.?login|logged out/.test(combined);
+        fail(denied
+            ? "zswarm serve cannot reach the local Tailscale daemon to verify the listen address"
+            : "zswarm serve Tailscale status failed while verifying the listen address", { phase: "verify", cause: denied ? "daemon_unavailable" : "status_failed", exit: statusResult.code }, SERVE_BIND_REMEDY.daemon);
+    }
+    const rawStdout = statusResult.stdout;
+    if (!rawStdout.trim()) {
+        fail("zswarm serve received empty Tailscale status JSON while verifying the listen address", { phase: "verify", cause: "empty_status" }, SERVE_BIND_REMEDY.statusShape);
+    }
+    if (Buffer.byteLength(rawStdout, "utf8") >= SERVE_BIND_STATUS_MAX_BYTES) {
+        fail("zswarm serve Tailscale status JSON exceeded the verification size cap", { phase: "verify", cause: "oversize_status" }, SERVE_BIND_REMEDY.statusShape);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawStdout);
+    }
+    catch {
+        fail("zswarm serve Tailscale status JSON was malformed while verifying the listen address", { phase: "verify", cause: "malformed_json" }, SERVE_BIND_REMEDY.statusShape);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        fail("zswarm serve Tailscale status JSON was not an object", { phase: "verify", cause: "invalid_status" }, SERVE_BIND_REMEDY.statusShape);
+    }
+    const status = parsed;
+    const backend = typeof status.BackendState === "string" ? status.BackendState.trim() : "";
+    if (backend !== "Running") {
+        fail(`zswarm serve requires Tailscale BackendState Running to bind a Tailscale address (saw ${backend || "missing"})`, { phase: "verify", cause: "backend_state", backendState: backend || null }, SERVE_BIND_REMEDY.daemon);
+    }
+    if (!status.Self || typeof status.Self !== "object" || Array.isArray(status.Self)) {
+        fail("zswarm serve Tailscale status is missing Self; cannot authorize a Tailscale listen address", { phase: "verify", cause: "missing_self" }, SERVE_BIND_REMEDY.statusShape);
+    }
+    const selfRow = status.Self;
+    if (!Object.prototype.hasOwnProperty.call(selfRow, "TailscaleIPs")) {
+        fail("zswarm serve Tailscale Self.TailscaleIPs is missing; cannot authorize a Tailscale listen address", { phase: "verify", cause: "missing_self_ips" }, SERVE_BIND_REMEDY.statusShape);
+    }
+    const selfIps = parsePresentIpList(selfRow.TailscaleIPs, "Self.TailscaleIPs");
+    if (selfIps.length === 0) {
+        fail("zswarm serve Tailscale Self.TailscaleIPs is empty; cannot authorize a Tailscale listen address", { phase: "verify", cause: "empty_self_ips" }, SERVE_BIND_REMEDY.notSelf);
+    }
+    // Absent root TailscaleIPs is allowed (Self is authoritative). A present
+    // field — including [] or a non-array — must be structurally valid and match Self.
+    if (Object.prototype.hasOwnProperty.call(status, "TailscaleIPs")) {
+        const rootIps = parsePresentIpList(status.TailscaleIPs, "TailscaleIPs");
+        if (!sameAddressSet(selfIps, rootIps)) {
+            fail("zswarm serve Tailscale Self.TailscaleIPs and TailscaleIPs conflict; refusing bind", { phase: "verify", cause: "self_root_conflict" }, SERVE_BIND_REMEDY.conflict);
+        }
+    }
+    // Peer entries are never identity evidence, even if a buggy CLI still emits them.
+    const matched = selfIps.find((entry) => entry.family === literal.family && entry.canonical === literal.canonical);
+    if (!matched) {
+        fail(`zswarm serve listen address ${host} is not a verified local Tailscale self address`, { phase: "verify", cause: "not_self_address", host: literal.canonical }, SERVE_BIND_REMEDY.notSelf);
+    }
+    assertRunnable("interfaces");
+    let ifaces;
+    try {
+        ifaces = ifacesFn();
+    }
+    catch (err) {
+        fail(`zswarm serve could not read OS interface addresses (${err instanceof Error ? err.message : "error"})`, { phase: "verify", cause: "os_interfaces" }, SERVE_BIND_REMEDY.osMissing);
+    }
+    assertRunnable("interfaces");
+    if (!osOwnsCanonical(matched, ifaces ?? {})) {
+        fail(`zswarm serve listen address ${literal.canonical} is not assigned on a local OS interface`, { phase: "verify", cause: "os_unassigned", host: literal.canonical }, SERVE_BIND_REMEDY.osMissing);
+    }
+    assertRunnable("authorize");
+    return {
+        bindHost: host.trim().replace(/^\[|\]$/g, ""),
+        canonical: matched.canonical,
+        family: matched.family,
+        mode: "tailscale",
+    };
+}

package/dist/ops/serve-install.d.ts

@@ -0,0 +1,88 @@
+import { type DoctorCheck } from "./doctor.js";
+import { type ServeHelloData } from "./serve.js";
+import { type NetworkInterfacesFn, type TailscaleStatusRunner } from "./serve-bind.js";
+import type { ServeInstallDeps, ServePowerShellResult } from "./types.js";
+/** Overall install/readiness deadline when `timeoutMs` is omitted. */
+export declare const DEFAULT_SERVE_INSTALL_TIMEOUT_MS = 30000;
+export declare const SERVE_NOT_READY_CODE = "serve_not_ready";
+export declare const SERVE_TASK_OWNED_CODE = "serve_task_owned";
+export declare const SERVE_TASK_VERSION_ENV = "ZSWARM_CORE_VERSION";
+export type ServeTaskAction = "inspect" | "register" | "start" | "stop" | "unregister";
+export type ServePowerShellExec = (script: string, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<ServePowerShellResult>;
+export type ServeCliLaunch = {
+    execPath: string;
+    scriptPath: string;
+};
+export type ServeInstallInput = ServeInstallDeps & {
+    listen?: string;
+    token?: string;
+    env?: NodeJS.ProcessEnv;
+    session?: string | null;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Test seams for Tailscale listen verification (before task mutation). */
+    tailscaleStatus?: TailscaleStatusRunner;
+    networkInterfaces?: NetworkInterfacesFn;
+};
+export type ServeInstallSuccess = {
+    installed: true;
+    ready: true;
+    running: true;
+    task: string;
+    listen: string;
+    command: string;
+    principal: {
+        userId: string;
+        logonType: string;
+        runLevel: string;
+        userSid?: string;
+    };
+    server: ServeHelloData;
+    session: string | null;
+    sessions: string[];
+    warning?: string;
+    inspection: {
+        checks: DoctorCheck[];
+    };
+};
+export declare function looksLikeMcpEntrypoint(scriptPath: string): boolean;
+export declare function looksLikeCliEntrypoint(scriptPath: string): boolean;
+/**
+ * Resolve node + CLI script for the logon task. MCP argv[1] is never installed.
+ */
+export declare function resolveServeCliLaunch(input: {
+    execPath?: string;
+    scriptPath?: string;
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+}): ServeCliLaunch;
+/** Host Zellij/IPC + configured server policy; controller routing is stripped. */
+export declare function serveTaskChildEnv(env: NodeJS.ProcessEnv): Record<string, string>;
+/** Child env persisted in the task, including package version and optional launch id. */
+export declare function serveTaskLaunchEnv(env: NodeJS.ProcessEnv, launchId?: string): Record<string, string>;
+export declare function isWindowsSid(value: string): boolean;
+/** Verified SID equality. Account-name / UPN resemblance is not identity. */
+export declare function sameWindowsSid(a: string, b: string): boolean;
+/** @deprecated Use sameWindowsSid; names are not verified identity. */
+export declare function sameWindowsAccount(a: string, b: string): boolean;
+export declare function buildServeTaskScript(action: ServeTaskAction, params?: {
+    command?: string;
+}): string;
+export declare function serveCommandFingerprint(command: string): string;
+/**
+ * Register/update the current-user Interactive logon task and wait until the
+ * requested server instance is authenticated and the host crew is visible.
+ */
+export declare function installServeLogon(input?: ServeInstallInput): Promise<ServeInstallSuccess>;
+export declare function uninstallServeLogon(input?: ServeInstallInput): Promise<{
+    task: string;
+    cleared: true;
+    stopped?: boolean;
+    missing?: boolean;
+    stopFailed?: boolean;
+}>;