@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/test-seam-dwvaKjRp.js

@@ -0,0 +1,459 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region lib/types/processes.js
+/**
+* Process primitives shared by the guard CLI and the exit agent: locating the
+* listener on a port and killing a process tree. One owner — the watchdog's
+* bash side keeps its own copy (different runtime), but every TypeScript
+* caller goes through here.
+*/
+function executable(name, candidates) {
+	return candidates.find((candidate) => existsSync(candidate)) ?? name;
+}
+const LSOF = executable("lsof", ["/usr/sbin/lsof", "/usr/bin/lsof"]);
+const PS = executable("ps", ["/bin/ps", "/usr/bin/ps"]);
+const PGREP = executable("pgrep", ["/usr/bin/pgrep", "/bin/pgrep"]);
+const SYSCTL = executable("sysctl", ["/usr/sbin/sysctl", "/sbin/sysctl"]);
+const PYTHON = executable("python3", ["/usr/bin/python3", "/opt/homebrew/bin/python3"]);
+const DARWIN_START_TOKEN = [
+	"import ctypes,struct,sys",
+	"p=int(sys.argv[1])",
+	"b=ctypes.create_string_buffer(136)",
+	"n=ctypes.CDLL(\"/usr/lib/libproc.dylib\").proc_pidinfo(p,3,0,b,136)",
+	"n == 136 or sys.exit(1)",
+	"s,u=struct.unpack_from(\"QQ\",b.raw,120)",
+	"print(f\"darwin:{s}:{u}\",end=\"\")"
+].join(";");
+/** Every process listening on a TCP port. An empty list also covers unavailable lsof. */
+function findPidsOnPort(port) {
+	try {
+		const out = execFileSync(LSOF, [
+			`-tiTCP:${port}`,
+			"-sTCP:LISTEN",
+			"-P"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		return [...new Set(out.split("\n").map(Number).filter((pid) => Number.isInteger(pid) && pid > 0))];
+	} catch {
+		return [];
+	}
+}
+/** TCP listen ports owned directly by one PID, using the same absolute lsof resolution. */
+function listeningPortsForPid(pid) {
+	try {
+		const out = execFileSync(LSOF, [
+			"-nP",
+			"-a",
+			"-p",
+			String(pid),
+			"-iTCP",
+			"-sTCP:LISTEN"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+		return [...new Set([...out.matchAll(/:(\d+) \(LISTEN\)/g)].map((match) => Number(match[1])).filter(Number.isInteger))];
+	} catch {
+		return [];
+	}
+}
+/** The first process listening on a TCP port, or null when none is (via lsof). */
+function findPidOnPort(port) {
+	return findPidsOnPort(port)[0]?.toString() ?? null;
+}
+/**
+* Current identity for a live process, or null when it cannot be proved.
+* Linux exposes a boot-scoped kernel start tick. Other POSIX hosts do not,
+* so bind the start instant to the boot, uid, session, and settled command.
+* This materially strengthens macOS ps(1)'s second-granularity lstart; all
+* guard captures occur after the watchdog/child has reached its steady argv.
+*/
+function processIdentity(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		const status = execFileSync(PS, [
+			"-o",
+			"stat=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		if (status === "" || status.startsWith("Z")) return null;
+		if (process.platform === "darwin") try {
+			const nativeStart = execFileSync(PYTHON, [
+				"-c",
+				DARWIN_START_TOKEN,
+				String(pid)
+			], {
+				encoding: "utf8",
+				stdio: "pipe"
+			}).trim();
+			if (/^darwin:\d+:\d+$/.test(nativeStart)) return {
+				pid,
+				startToken: nativeStart
+			};
+		} catch {}
+		const procStat = `/proc/${pid}/stat`;
+		if (existsSync(procStat)) {
+			const stat = readFileSync(procStat, "utf8");
+			const commandEnd = stat.lastIndexOf(")");
+			const startTicks = (commandEnd < 0 ? [] : stat.slice(commandEnd + 1).trim().split(/\s+/))[19];
+			if (startTicks === void 0 || startTicks === "") return null;
+			let bootId = "unknown-boot";
+			try {
+				bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || bootId;
+			} catch {}
+			return {
+				pid,
+				startToken: `linux:${bootId}:${startTicks}`
+			};
+		}
+		const processEvidence = execFileSync(PS, [
+			"-o",
+			"sess=",
+			"-o",
+			"uid=",
+			"-o",
+			"lstart=",
+			"-o",
+			"command=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		if (processEvidence === "") return null;
+		let bootEvidence = "unknown-boot";
+		try {
+			bootEvidence = execFileSync(SYSCTL, ["-n", "kern.boottime"], {
+				encoding: "utf8",
+				stdio: "pipe"
+			}).trim() || bootEvidence;
+		} catch {}
+		return {
+			pid,
+			startToken: `posix:${createHash("sha256").update(bootEvidence).update("\0").update(processEvidence).digest("hex")}`
+		};
+	} catch {
+		return null;
+	}
+}
+/** Whether the same, non-recycled process is still alive. */
+function processIdentityMatches(identity) {
+	return processIdentity(identity.pid)?.startToken === identity.startToken;
+}
+function parentPid(pid) {
+	try {
+		const value = Number(execFileSync(PS, [
+			"-o",
+			"ppid=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim());
+		return Number.isInteger(value) && value > 0 ? value : null;
+	} catch {
+		return null;
+	}
+}
+/** The live POSIX process-group id for one PID, or null when unavailable. */
+function processGroupId(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		const value = Number(execFileSync(PS, [
+			"-o",
+			"pgid=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim());
+		return Number.isInteger(value) && value > 0 ? value : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Prove that exactly one port listener belongs to a supervisor and return the
+* direct child root through which that supervisor owns it. This is captured
+* before cutover; the successor must stop this identity, never an arbitrary
+* process discovered later from the shared port.
+*/
+function findOwnedListener(port, supervisorPid) {
+	const listeners = findPidsOnPort(port);
+	if (listeners.length !== 1) return null;
+	const listenerPid = listeners[0];
+	if (listenerPid === void 0) return null;
+	const listener = processIdentity(listenerPid);
+	if (listener === null) return null;
+	let cursor = listenerPid;
+	let childRoot = null;
+	const seen = /* @__PURE__ */ new Set();
+	while (cursor > 0 && !seen.has(cursor)) {
+		seen.add(cursor);
+		const parent = parentPid(cursor);
+		if (parent === supervisorPid) {
+			childRoot = cursor;
+			break;
+		}
+		if (parent === null) return null;
+		cursor = parent;
+	}
+	if (childRoot === null) return null;
+	const child = processIdentity(childRoot);
+	return child === null ? null : {
+		child,
+		listener
+	};
+}
+/** POSIX single-quote one word for a shell command line. */
+function shellQuote(word) {
+	return `'${word.replace(/'/g, "'\\''")}'`;
+}
+/**
+* Discover how the process on a port was launched — its exact argv from
+* `ps -o command=`, its cwd from lsof, and its DSH_* environment from
+* `ps eww` — rendered as a shell command. This exists because the agent's
+* sandbox blocks ps entirely, so every fresh-machine agent fell into a
+* process-tree archaeology loop before its first restart; the CLI (running
+* unsandboxed) answers the same question mechanically and reliably. Returns
+* null when the process is gone or ps/lsof are unavailable.
+* @param pid - the listener's pid.
+*/
+function discoverLaunchCommand(pid) {
+	let argv;
+	let cwd;
+	try {
+		argv = execFileSync(PS, [
+			"-o",
+			"command=",
+			"-p",
+			pid
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		if (argv === "") return null;
+	} catch (error) {
+		throw new Error(`ps unavailable: ${String(error)}`);
+	}
+	try {
+		const out = execFileSync(LSOF, [
+			"-a",
+			"-p",
+			pid,
+			"-d",
+			"cwd",
+			"-Fn"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+		const match = /^n(.+)$/m.exec(out);
+		if (match === null) return null;
+		cwd = match[1] ?? "";
+	} catch (error) {
+		throw new Error(`lsof cwd unavailable: ${String(error)}`);
+	}
+	const TRANSIENT = /* @__PURE__ */ new Set([
+		"DSH_ANKH_RESTART_DRIVER",
+		"DSH_SESSION_ID",
+		"DSH_SESSION_JSONL",
+		"DSH_WEB_URL",
+		"DSH_SHELL"
+	]);
+	const env = {};
+	try {
+		const out = execFileSync(PS, [
+			"eww",
+			"-o",
+			"command",
+			"-p",
+			pid
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+		for (const token of out.split(/\s+/)) {
+			const eq = token.indexOf("=");
+			if (eq > 0 && token.slice(0, eq).startsWith("DSH_") && !TRANSIENT.has(token.slice(0, eq))) env[token.slice(0, eq)] = token.slice(eq + 1);
+		}
+	} catch {}
+	const envPart = Object.entries(env).map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ");
+	return `cd ${shellQuote(cwd)} && ${envPart !== "" ? `${envPart} ` : ""}${argv}`;
+}
+/**
+* Kill a pid AND its descendants, deepest first (best effort). The supervised
+* instance may have forked children; a plain signal on the pid alone would
+* orphan them (the EADDRINUSE race the watchdog's EADDRINUSE branch exists
+* for). The process-group model is NOT assumed — the instance is not
+* setsid'd — so the sweep walks `pgrep -P` instead. `pgrep` missing or
+* returning nothing is fine: the pid itself still gets the signal.
+*/
+function signalFrozenTree(pid, signal) {
+	let safe = true;
+	let children = [];
+	try {
+		const out = execFileSync(PGREP, ["-P", String(pid)], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		children = out === "" ? [] : out.split("\n");
+	} catch {}
+	for (const raw of children) {
+		const child = Number(raw);
+		if (!Number.isInteger(child) || child <= 0) continue;
+		try {
+			process.kill(child, "SIGSTOP");
+		} catch {
+			continue;
+		}
+		if (parentPid(child) !== pid) {
+			safe = false;
+			try {
+				process.kill(child, "SIGCONT");
+			} catch {}
+			continue;
+		}
+		safe = signalFrozenTree(child, signal) && safe;
+	}
+	try {
+		process.kill(pid, signal);
+		if (signal !== "SIGKILL") process.kill(pid, "SIGCONT");
+	} catch {}
+	return safe;
+}
+function killPidTree(pid, signal) {
+	try {
+		process.kill(pid, "SIGSTOP");
+	} catch {
+		return;
+	}
+	signalFrozenTree(pid, signal);
+}
+//#endregion
+//#region lib/types/test-seam.js
+/**
+* Explicit test-only process/event registration seam. Production execution is
+* inert unless a test runner supplies all ANKH_GUARD_TEST_* ownership values.
+*/
+const TEST_RUN_DIR_ENV = "ANKH_GUARD_TEST_RUN_DIR";
+const TEST_RUN_TOKEN_ENV = "ANKH_GUARD_TEST_RUN_TOKEN";
+const TEST_PROCESS_ROLE_ENV = "ANKH_GUARD_TEST_PROCESS_ROLE";
+const TEST_PROCESS_PORT_ENV = "ANKH_GUARD_TEST_PROCESS_PORT";
+const TEST_PROCESS_TEMP_ROOT_ENV = "ANKH_GUARD_TEST_PROCESS_TEMP_ROOT";
+const TEST_REGISTER_BIN_ENV = "ANKH_GUARD_TEST_REGISTER_BIN";
+const TEST_SLEEP_SCALE_ENV = "ANKH_GUARD_TEST_SLEEP_SCALE";
+function testCoordinates(env) {
+	const runDir = env[TEST_RUN_DIR_ENV];
+	const runToken = env[TEST_RUN_TOKEN_ENV];
+	if (runDir === void 0 || runDir === "" || runToken === void 0 || !/^[a-f0-9-]{16,}$/.test(runToken)) return null;
+	return {
+		runDir,
+		runToken
+	};
+}
+function safeRole(value) {
+	const role = value.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80);
+	return role === "" ? "unknown" : role;
+}
+function appendTestLifecycleEventForProcess(subjectPid, roleValue, event, detail, source = "child-self", env = process.env) {
+	const coordinates = testCoordinates(env);
+	if (coordinates === null) return;
+	const role = safeRole(roleValue);
+	const identity = processIdentity(subjectPid);
+	const pgid = processGroupId(subjectPid);
+	const record = {
+		version: 1,
+		runToken: coordinates.runToken,
+		source,
+		role,
+		event: safeRole(event),
+		pid: subjectPid,
+		...pgid === null ? {} : { pgid },
+		...identity === null ? {} : { startToken: identity.startToken },
+		wallTimeMs: Date.now(),
+		monotonicNs: process.hrtime.bigint().toString(),
+		...detail === void 0 ? {} : { detail }
+	};
+	try {
+		const dir = join(coordinates.runDir, "events");
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		appendFileSync(join(dir, `${subjectPid}-${source}.jsonl`), `${JSON.stringify(record)}\n`, { mode: 384 });
+	} catch {}
+}
+/** Record one credential-free event in this process's append-only event file. */
+function appendTestLifecycleEvent(event, detail, source = "child-self", env = process.env) {
+	appendTestLifecycleEventForProcess(process.pid, env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown", event, detail, source, env);
+}
+/**
+* Atomically publish an immutable PID/PGID/start-identity lease. The same PID
+* may be observed by its parent and then self-register; the first complete
+* record wins because both describe the same kernel start identity.
+*/
+function registerTestProcess(pid, role, options = {}) {
+	const env = options.env ?? process.env;
+	const coordinates = testCoordinates(env);
+	if (coordinates === null) return null;
+	const identity = options.identity ?? processIdentity(pid);
+	const pgid = processGroupId(pid);
+	if (identity === null || pgid === null) return null;
+	const portText = env[TEST_PROCESS_PORT_ENV];
+	const envPort = portText === void 0 ? void 0 : Number(portText);
+	const port = options.port ?? (Number.isInteger(envPort) && (envPort ?? 0) > 0 ? envPort : void 0);
+	const tempRoot = options.tempRoot ?? env["ANKH_GUARD_TEST_PROCESS_TEMP_ROOT"];
+	const record = {
+		version: 1,
+		runToken: coordinates.runToken,
+		role: safeRole(role),
+		pid,
+		pgid,
+		startToken: identity.startToken,
+		groupRoot: pgid === pid,
+		registeredAt: Date.now(),
+		source: options.source ?? (pid === process.pid ? "child-self" : "parent-observer"),
+		...tempRoot === void 0 || tempRoot === "" ? {} : { tempRoot },
+		...port === void 0 ? {} : { port }
+	};
+	try {
+		const dir = join(coordinates.runDir, "processes");
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const identityHash = createHash("sha256").update(identity.startToken).digest("hex").slice(0, 16);
+		writeFileSync(join(dir, `${pid}-${identityHash}.json`), `${JSON.stringify(record)}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code !== "EEXIST") return null;
+	}
+	return record;
+}
+/** Self-register only when an explicit test role accompanies the run lease. */
+function registerCurrentTestProcess(env = process.env) {
+	const role = env[TEST_PROCESS_ROLE_ENV];
+	if (role === void 0 || role === "") return null;
+	const record = registerTestProcess(process.pid, role, {
+		env,
+		source: "child-self"
+	});
+	if (record !== null) appendTestLifecycleEvent("process-registered", { pgid: record.pgid }, "child-self", env);
+	return record;
+}
+//#endregion
+export { processIdentity as _, TEST_RUN_DIR_ENV as a, appendTestLifecycleEvent as c, registerTestProcess as d, discoverLaunchCommand as f, listeningPortsForPid as g, killPidTree as h, TEST_REGISTER_BIN_ENV as i, appendTestLifecycleEventForProcess as l, findPidOnPort as m, TEST_PROCESS_ROLE_ENV as n, TEST_RUN_TOKEN_ENV as o, findOwnedListener as p, TEST_PROCESS_TEMP_ROOT_ENV as r, TEST_SLEEP_SCALE_ENV as s, TEST_PROCESS_PORT_ENV as t, registerCurrentTestProcess as u, processIdentityMatches as v };

package/lib/test-seam.js

@@ -0,0 +1,2 @@
+import { a as TEST_RUN_DIR_ENV, c as appendTestLifecycleEvent, d as registerTestProcess, i as TEST_REGISTER_BIN_ENV, l as appendTestLifecycleEventForProcess, n as TEST_PROCESS_ROLE_ENV, o as TEST_RUN_TOKEN_ENV, r as TEST_PROCESS_TEMP_ROOT_ENV, s as TEST_SLEEP_SCALE_ENV, t as TEST_PROCESS_PORT_ENV, u as registerCurrentTestProcess } from "./test-seam-dwvaKjRp.js";
+export { TEST_PROCESS_PORT_ENV, TEST_PROCESS_ROLE_ENV, TEST_PROCESS_TEMP_ROOT_ENV, TEST_REGISTER_BIN_ENV, TEST_RUN_DIR_ENV, TEST_RUN_TOKEN_ENV, TEST_SLEEP_SCALE_ENV, appendTestLifecycleEvent, appendTestLifecycleEventForProcess, registerCurrentTestProcess, registerTestProcess };

package/lib/types/browser-handoff.d.ts

@@ -0,0 +1,55 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import { type LaunchRole } from './launch-spec.ts';
+import { processIdentityMatches, type ProcessIdentity } from './processes.ts';
+export declare const BROWSER_HANDOFF_ROUTE = "/_ankh-guard/browser-handoff";
+export type BrowserHandoffChannel = 'original-tab' | 'fallback-tab';
+export type BrowserHandoffAuthentication = 'existing-cookie' | 'launch-url';
+export interface BrowserHandoffRegistration {
+    authority: string;
+    capabilitySha256: string;
+    armedAt: number;
+    acknowledgedAt?: number;
+}
+export interface BrowserHandoffRequest {
+    version: 2;
+    cutoverId: string;
+    registrations: BrowserHandoffRegistration[];
+}
+export interface BrowserHandoffAcknowledgement {
+    version: 1;
+    cutoverId: string;
+    role: LaunchRole;
+    authority: string;
+    listenerPid: number;
+    listenerStartToken: string;
+    channel: BrowserHandoffChannel;
+    authentication: BrowserHandoffAuthentication;
+    acknowledgedAt: number;
+}
+interface ConnectionSlice {
+    requestRejection?(request: IncomingMessage): 401 | 403 | undefined;
+    authenticatedUrl?(baseUrl: string): string;
+}
+interface BrowserHandoffDependencies {
+    stateDir: string;
+    pid?: number;
+    now?: () => number;
+    identityMatches?: typeof processIdentityMatches;
+    /** Boot-id source for the generation channel; production default is the serving process itself. */
+    identityProvider?: (pid: number) => ProcessIdentity | null;
+    connection?: ConnectionSlice;
+    /** Resolve lazily because WebServer can activate before the optional connection service. */
+    connectionProvider?: () => ConnectionSlice | undefined;
+    /** Test seams; production defaults turn idle polling into a held request. */
+    longPollMs?: number;
+    longPollIntervalMs?: number;
+}
+export declare function readBrowserHandoffRequest(stateDir: string): BrowserHandoffRequest | null;
+export declare function readBrowserHandoffAcknowledgement(stateDir: string): BrowserHandoffAcknowledgement | null;
+/** Create the exact HTTP handler; dependencies are injectable for deterministic protocol tests. */
+export declare function createBrowserHandoffHandler(dependencies: BrowserHandoffDependencies): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** Register the optional Web-profile bridge; headless/TUI compositions simply never activate it. */
+export declare function registerBrowserHandoff(ctx: Context, stateDir: string): void;
+export {};
+//# sourceMappingURL=browser-handoff.d.ts.map