Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
11.3 KB
Raw Blame
/**
 * The desktop app's private channel (S25.1–S25.3, docs/design.md "Security"). The app that launches
 * the daemon creates a connected pair of Unix sockets and hands one end to the daemon as fd 3. That
 * connection is the authentication: nothing is written to a file or an environment variable, and
 * there is no listening socket another process could reach. A daemon the app only attached to, one
 * started from a terminal, and the web have no channel, so privileged actions fail closed there.
 *
 * Frames are line-delimited JSON, in both directions:
 *   {"kind":"request","id":1,"method":"command","params":{...}}
 *   {"kind":"response","id":1,"result":{...}}  or  {"kind":"response","id":1,"error":"..."}
 * Each side numbers its own requests. The app sends `command` (a privileged message on behalf of a
 * window), `computer_register`, and `computer_unregister`; the daemon sends `approve` (a native
 * dialog, answered `{approved}`).
 */
import { type StdioOptions, spawnSync } from "node:child_process";
import { closeSync, fstatSync } from "node:fs";
import { Socket } from "node:net";
import type { Duplex } from "node:stream";
import { isWindowsAppChannel } from "./windows-app-channel.ts";

/** Where the app puts its end of the channel. */
export const APP_FD = 3;
/** Longer than the app's own 120 s dialog timeout, which answers "declined" first. */
export const APPROVAL_WAIT_MS = 130_000;
/**
 * A frame longer than this closes the channel; nothing legitimate comes close. The app has the same
 * rule, and a closed channel stops the daemon (S35.2), so neither side ever sends a longer one: an
 * oversized request fails (an approval is refused) and an oversized answer becomes an error.
 */
const MAX_FRAME = 1024 * 1024;

/** One argument of the action, in the order shown. */
export interface PreviewField {
	name: string;
	value: unknown;
}

/** What the app shows in its native dialog (apps/desktop approvals::ApprovalRequest). */
export interface AppApproval {
	/** The connector's name, as the user knows it. */
	connector: string;
	/** What it will do ("create pages"). */
	action: string;
	preview: PreviewField[];
	/** Replaces "Allow <connector> to <action>?" for a change the user started (S25.3). */
	title?: string;
	/** Replaces "The assistant wants to <action> in <connector>.". */
	summary?: string;
}

/** The app as the bridge sees it: whether it is there, and its native approvals. */
export interface AppLink {
	readonly connected: boolean;
	/** True only when the user allowed it; declined, unanswered, or the app gone resolve false. */
	approve(request: AppApproval, signal?: AbortSignal): Promise<boolean>;
}

type Frame =
	| { kind: "request"; id: number; method: string; params?: unknown }
	| { kind: "response"; id: number; result?: unknown; error?: string };

type Pending = { resolve(value: unknown): void; reject(error: Error): void; timer: NodeJS.Timeout };

export interface AppChannelOptions {
	log?: (line: string) => void;
	/** How long an approval waits for the app's answer. Default {@link APPROVAL_WAIT_MS}. */
	approvalWaitMs?: number;
}

export class AppChannel implements AppLink {
	/** Answers the app's requests; a thrown error goes back as the response's `error`. */
	handler: (method: string, params: unknown) => unknown = () => {
		throw new Error("The assistant is not ready yet.");
	};
	private readonly stream: Duplex;
	private readonly options: AppChannelOptions;
	private readonly pending = new Map<number, Pending>();
	private readonly closeListeners = new Set<() => void>();
	private buffer = "";
	private nextId = 0;
	private open = true;
	private closing?: Promise<void>;

	constructor(stream: Duplex, options: AppChannelOptions = {}) {
		this.stream = stream;
		this.options = options;
		stream.setEncoding("utf8");
		stream.on("data", (chunk: string) => this.receive(chunk));
		stream.on("end", () => this.close());
		stream.on("close", () => this.close());
		stream.on("error", (error: Error) => {
			this.log(`the app's channel failed: ${error.message}`);
			this.close();
		});
	}

	get connected(): boolean {
		return this.open;
	}

	/** Calls `listener` once when the channel closes (the app quit, or it was closed here). */
	onClose(listener: () => void): () => void {
		if (!this.open) {
			listener();
			return () => {};
		}
		this.closeListeners.add(listener);
		return () => this.closeListeners.delete(listener);
	}

	request(method: string, params: unknown, timeoutMs: number): Promise<unknown> {
		if (!this.open) return Promise.reject(new Error("The Gentle Dot app is not connected."));
		const id = ++this.nextId;
		const line = frameLine({ kind: "request", id, method, params });
		if (!line) return Promise.reject(new Error(`The request ${method} is too large for the Gentle Dot app.`));
		return new Promise((resolve, reject) => {
			const timer = setTimeout(() => {
				this.pending.delete(id);
				reject(new Error(`The Gentle Dot app did not answer ${method} in time.`));
			}, timeoutMs);
			this.pending.set(id, { resolve, reject, timer });
			if (this.open) this.stream.write(line);
		});
	}

	/** Rejects when there is no app to ask; every other failure is a refusal (fail closed). */
	approve(request: AppApproval, signal?: AbortSignal): Promise<boolean> {
		if (!this.open) return Promise.reject(new Error("The Gentle Dot app is not connected."));
		if (signal?.aborted) return Promise.resolve(false);
		const answer = this.request("approve", request, this.options.approvalWaitMs ?? APPROVAL_WAIT_MS).then(
			(result) => (result as { approved?: unknown } | undefined)?.approved === true,
			() => false,
		);
		if (!signal) return answer;
		const aborted = new Promise<boolean>((resolve) =>
			signal.addEventListener("abort", () => resolve(false), { once: true }),
		);
		return Promise.race([answer, aborted]);
	}

	/** Logical refusal/notification precedes transport drain. Memoize before notifying
	 * listeners: daemon shutdown may reenter close, but must never await itself. */
	close(): Promise<void> {
		if (this.closing) return this.closing;
		this.open = false;
		this.buffer = "";
		const stream = this.stream;
		const windows = isWindowsAppChannel(stream);
		this.closing = windows
			? Promise.resolve().then(async () => {
					const result = await stream.close("drain");
					if (result.mode !== "drain" || result.drained !== true)
						throw new Error("Windows app channel was not drained.");
				})
			: Promise.resolve();
		void this.closing.catch(() => {}); // EOF/error initiators have no awaiter
		if (!windows) this.stream.destroy();
		for (const [id, waiting] of this.pending) {
			clearTimeout(waiting.timer);
			waiting.reject(new Error("The Gentle Dot app closed its channel."));
			this.pending.delete(id);
		}
		for (const listener of [...this.closeListeners]) listener();
		this.closeListeners.clear();
		return this.closing;
	}

	private receive(chunk: string): void {
		if (!this.open) return;
		this.buffer += chunk;
		for (let end = this.buffer.indexOf("\n"); end >= 0; end = this.buffer.indexOf("\n")) {
			const line = this.buffer.slice(0, end);
			this.buffer = this.buffer.slice(end + 1);
			if (line.trim() !== "") this.onFrame(line);
			if (!this.open) return;
		}
		if (this.buffer.length > MAX_FRAME) {
			this.log("the app's channel sent a frame that is too long; closing it");
			this.close();
		}
	}

	private onFrame(line: string): void {
		let frame: Frame;
		try {
			frame = JSON.parse(line) as Frame;
		} catch {
			this.log("the app's channel sent a frame that is not JSON; ignored");
			return;
		}
		if (typeof frame !== "object" || frame === null || typeof frame.id !== "number") return;
		if (frame.kind === "response") {
			const waiting = this.pending.get(frame.id);
			if (!waiting) return;
			this.pending.delete(frame.id);
			clearTimeout(waiting.timer);
			if (typeof frame.error === "string") waiting.reject(new Error(frame.error));
			else waiting.resolve(frame.result);
			return;
		}
		if (frame.kind !== "request" || typeof frame.method !== "string") return;
		const { id, method } = frame;
		Promise.resolve()
			.then(() => {
				if (!this.open) throw new Error("The Gentle Dot app closed its channel.");
				return this.handler(method, frame.params);
			})
			.then(
				(result) => this.write({ kind: "response", id, result: result ?? {} }),
				(error: Error) => this.write({ kind: "response", id, error: error.message }),
			);
	}

	private write(frame: Frame): void {
		const line =
			frameLine(frame) ??
			frameLine({ kind: "response", id: frame.id, error: "The answer is too large to send." });
		if (this.open && line) this.stream.write(line);
	}

	private log(line: string): void {
		this.options.log?.(line);
	}
}

/** The frame as one line, or undefined when it is longer than {@link MAX_FRAME}. */
function frameLine(frame: Frame): string | undefined {
	const json = JSON.stringify(frame);
	return Buffer.byteLength(json) > MAX_FRAME ? undefined : `${json}\n`;
}

/**
 * True when a child spawned the way the daemon spawns its children would hold the socket `identity`
 * (`dev:ino`) on `fd`. Node offers no way to mark an inherited descriptor close-on-exec; on macOS
 * libuv spawns with `POSIX_SPAWN_CLOEXEC_DEFAULT`, so children get only their stdio. This checks
 * that instead of assuming it.
 */
export function childInherits(
	fd: number,
	identity: string,
	stdio: StdioOptions = ["ignore", "pipe", "ignore"],
) {
	// Unix dev:ino equality cannot prove Windows handle exclusion; fail closed without probing.
	if (process.platform === "win32") return true;
	const script = `try{const s=require("fs").fstatSync(${fd},{bigint:true});process.stdout.write(s.dev+":"+s.ino)}catch{}`;
	const probe = spawnSync(process.execPath, ["-e", script], { stdio, encoding: "utf8", timeout: 10_000 });
	// A probe that could not run proves nothing: treat it as a leak.
	if (probe.error || probe.status !== 0) return true;
	return probe.stdout === identity;
}

export interface InheritedChannelOptions extends AppChannelOptions {
	fd?: number;
	/** Tests replace the inheritance check. */
	probe?: (fd: number, identity: string) => boolean;
}

/**
 * The socket the app handed over on fd 3, or undefined when there is none (it is not a socket, or it
 * is Node's own IPC channel). When a child would inherit it, it is closed and refused: an agent
 * holding it could act as the app.
 */
export function inheritedAppSocket(options: InheritedChannelOptions = {}): Socket | undefined {
	// No equivalent Windows transport/exclusion is established yet. Do not inspect or wrap a
	// Windows handle as a Unix socket; acquisition stays unavailable, independently of the protocol.
	if (process.platform === "win32") return undefined;
	const fd = options.fd ?? APP_FD;
	if (process.env.NODE_CHANNEL_FD === String(fd)) return undefined;
	let identity: string;
	try {
		const stat = fstatSync(fd, { bigint: true });
		if (!stat.isSocket()) return undefined;
		identity = `${stat.dev}:${stat.ino}`;
	} catch {
		return undefined;
	}
	const inherits = options.probe ?? childInherits;
	if (inherits(fd, identity)) {
		options.log?.("the app's channel was refused: children would inherit it; connectors cannot be changed");
		closeSync(fd);
		return undefined;
	}
	return new Socket({ fd, readable: true, writable: true });
}

/** {@link inheritedAppSocket} as a channel. */
export function openInheritedChannel(options: InheritedChannelOptions = {}): AppChannel | undefined {
	const socket = inheritedAppSocket(options);
	return socket ? new AppChannel(socket, options) : undefined;
}