@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/installkind.ts

@@ -0,0 +1,50 @@
+// How this qcr was installed, read from where its package sits.
+//
+// A leaf: no import at all, so the daemon's host check (src/runhost.ts) and
+// the npm bin's verbs (src/npmverbs.ts) share it without the daemon reaching
+// the login and pi verbs.
+
+/** The release image's app root (src/tui/companion.ts `CONTAINER.app`). */
+export const IMAGE_APP_ROOT = "/opt/qcr";
+
+export type Installer = "npm" | "pnpm" | "bun";
+
+/** How this qcr was installed, read from where its package sits. */
+export type InstallKind =
+  | { kind: "image" }
+  | { kind: "checkout"; root: string }
+  | { kind: "global"; installer: Installer; root: string }
+  | { kind: "local"; installer: Installer; root: string };
+
+/** Where this qcr's package sits, and who put it there. The path decides
+ * first (pnpm's and bun's global stores are recognisable); otherwise the user
+ * agent of the package manager that ran it (`npm_config_user_agent`); npm is
+ * the default. A package outside any `node_modules/` is a checkout; the
+ * release image is its own kind. */
+export function detectInstall(
+  pkgRoot: string,
+  env: Readonly<Record<string, string | undefined>>,
+): InstallKind {
+  const p = pkgRoot.replace(/\\/g, "/");
+  if (p === IMAGE_APP_ROOT || p.startsWith(`${IMAGE_APP_ROOT}/`) || env["QCR_IMAGE_TOOL_UID"])
+    return { kind: "image" };
+  const parts = p.split("/");
+  if (!parts.includes("node_modules")) return { kind: "checkout", root: pkgRoot };
+  const ua = (env["npm_config_user_agent"] ?? "").trim();
+  let installer: Installer = "npm";
+  if (/\/\.bun\/install\/global\//.test(p) || /\/\.bun\//.test(p)) installer = "bun";
+  else if (/\/pnpm\/global\//.test(p) || p.includes("/.pnpm/") || /\/pnpm-global\//.test(p))
+    installer = "pnpm";
+  else if (ua.startsWith("pnpm/")) installer = "pnpm";
+  else if (ua.startsWith("bun/")) installer = "bun";
+  // npm's global root is <prefix>/lib/node_modules (unix) or <prefix>/node_modules
+  // (Windows); pnpm's and bun's global stores are named for it.
+  const global =
+    /\/lib\/node_modules\//.test(p) ||
+    /\/pnpm\/global\//.test(p) ||
+    /\/pnpm-global\//.test(p) ||
+    /\/\.bun\/install\/global\//.test(p) ||
+    /\/npm\/node_modules\//i.test(p) ||
+    (env["npm_config_global"] ?? "") === "true";
+  return { kind: global ? "global" : "local", installer, root: pkgRoot };
+}

package/src/ipc/capability.ts

@@ -0,0 +1,333 @@
+// Per-command capabilities and how they reach a process.
+//
+// A capability is 128 random bits minted for ONE command. The daemon never puts
+// it in argv or env. It writes it into a 0600 file that it unlinks at once,
+// keeps the descriptor, and hands the host that descriptor as an inherited fd;
+// env carries only the fd NUMBER. Every reader takes the secret with pread at
+// offset 0, which does not consume it, so the host and each post shim (children
+// of the model's bash, which inherit the fd) can all read it, round after round.
+//
+// tmux does not pass fds to a pane, so a takeover or debug pi gets a LAUNCH
+// FILE instead (`LaunchFiles`): the launcher in the pane opens it, unlinks it
+// and execs pi with the fd. An unclaimed launch file is deleted after 30 s and
+// its capability revoked.
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import { CAPABILITY_RE, IpcError } from "./protocol.js";
+
+/** The socket's directory under the daemon's state dir: 0700, daemon uid. */
+export function runDirOf(stateDir: string): string {
+  return join(stateDir, "run");
+}
+export function socketPathOf(stateDir: string): string {
+  return join(runDirOf(stateDir), "qcr.sock");
+}
+export function capsDirOf(stateDir: string): string {
+  return join(runDirOf(stateDir), "caps");
+}
+
+/** Make `dir` (and parents) and force it to 0700 owned by this uid. A dir that
+ * belongs to someone else is an error: the daemon's secrets live under it.
+ * `searchable` makes it 0710 instead: the group may pass through it to a name it
+ * already knows (the socket, for the tool uid's post and read shims),
+ * never list it or create anything in it. */
+/** Whether the model's tools run as another uid of this process's group (the
+ * entrypoint named one): the dirs a pane's pi must pass through to reach what
+ * was shared with it are then searchable by the group (0710), never listable. */
+export function toolUidSplit(env: NodeJS.ProcessEnv = process.env): boolean {
+  return /^[1-9][0-9]*$/.test(env["QCR_TOOL_UID"] ?? "");
+}
+
+export function ensurePrivateDir(dir: string, o: { searchable?: boolean } = {}): void {
+  const mode = o.searchable === true ? 0o710 : 0o700;
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = statSync(dir);
+  if (typeof process.getuid === "function" && st.uid !== process.getuid())
+    throw new Error(`${dir} is not owned by this user`);
+  if ((st.mode & 0o777) !== mode) chmodSync(dir, mode);
+}
+
+/** Linux's O_TMPFILE is `__O_TMPFILE | O_DIRECTORY` with `__O_TMPFILE` = 020000000
+ * on every architecture we run on; node does not export it. */
+const O_TMPFILE = process.platform === "linux" ? 0o20000000 | constants.O_DIRECTORY : 0;
+
+/** A new capability: 128 random bits as 32 hex characters. */
+export function mintCapability(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/**
+ * The daemon-side table of live capabilities, one per command. Verification is
+ * constant-time. Revoking drops the entry and tells the listeners (the server
+ * closes that command's connections).
+ */
+export class CapabilityStore {
+  private readonly caps = new Map<string, string>();
+  private readonly revokeListeners = new Set<(commandId: string) => void>();
+
+  /** Mint (or replace) the command's capability. */
+  mint(commandId: string): string {
+    const cap = mintCapability();
+    this.caps.set(commandId, cap);
+    return cap;
+  }
+
+  get(commandId: string): string | undefined {
+    return this.caps.get(commandId);
+  }
+
+  verify(commandId: string, presented: string): boolean {
+    const live = this.caps.get(commandId);
+    if (live === undefined || !CAPABILITY_RE.test(presented)) return false;
+    return timingSafeEqual(Buffer.from(live), Buffer.from(presented));
+  }
+
+  revoke(commandId: string): void {
+    if (!this.caps.delete(commandId)) return;
+    for (const fn of this.revokeListeners) fn(commandId);
+  }
+
+  onRevoke(fn: (commandId: string) => void): () => void {
+    this.revokeListeners.add(fn);
+    return () => this.revokeListeners.delete(fn);
+  }
+
+  size(): number {
+    return this.caps.size;
+  }
+}
+
+/**
+ * The handoff: a descriptor on a 0600 file that has no name. O_TMPFILE where the
+ * kernel and filesystem give it; otherwise a file created exclusively and
+ * unlinked in the same breath. The caller keeps the fd, passes it to the host
+ * as an inherited stdio entry and closes it when the command ends.
+ */
+export function createCapabilityFd(runDir: string, capability: string): number {
+  if (!CAPABILITY_RE.test(capability)) throw new Error("not a capability");
+  ensurePrivateDir(runDir);
+  let fd = -1;
+  if (O_TMPFILE !== 0) {
+    try {
+      fd = openSync(runDir, O_TMPFILE | constants.O_RDWR, 0o600);
+    } catch {
+      fd = -1; // no O_TMPFILE here (old kernel, odd filesystem): fall back
+    }
+  }
+  if (fd < 0) {
+    const name = join(runDir, `.cap-${process.pid}-${randomBytes(6).toString("hex")}`);
+    fd = openSync(name, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL, 0o600);
+    unlinkSync(name);
+  }
+  try {
+    writeSync(fd, capability, 0);
+  } catch (e) {
+    closeSync(fd);
+    throw e;
+  }
+  return fd;
+}
+
+/** Read the capability from an inherited fd with pread at offset 0: the offset
+ * is never moved, so every reader sees the secret, every time. */
+export function readCapabilityFd(fd: number): string {
+  const buf = Buffer.alloc(64);
+  const n = readSync(fd, buf, 0, buf.length, 0);
+  const cap = buf.subarray(0, n).toString("utf8").trim();
+  if (!CAPABILITY_RE.test(cap)) throw new IpcError("unauthorized", "the fd holds no capability");
+  return cap;
+}
+
+/** The fd's index in the child. 0-2 are stdio. */
+export const CAP_FD_INDEX = 3;
+
+/** A spawn `stdio` array: the caller's three standard streams plus the
+ * capability fd at `CAP_FD_INDEX`. */
+export function stdioWithCapability(
+  std: readonly [unknown, unknown, unknown],
+  capFd: number,
+): Array<unknown> {
+  return [std[0], std[1], std[2], capFd];
+}
+
+export interface IpcEnvInput {
+  socketPath: string;
+  commandId: string;
+  generation: number;
+  /** The fd NUMBER in the child, not the secret. */
+  capFdIndex?: number;
+}
+
+/** The env a host and its shims read: the socket, which command, which
+ * generation, and the fd number. No secret. */
+export function ipcEnv(input: IpcEnvInput): Record<string, string> {
+  return {
+    QCR_IPC_SOCKET: input.socketPath,
+    QCR_IPC_COMMAND_ID: input.commandId,
+    QCR_IPC_GENERATION: String(input.generation),
+    QCR_IPC_CAP_FD: String(input.capFdIndex ?? CAP_FD_INDEX),
+  };
+}
+
+export interface LaunchFile {
+  path: string;
+  commandId: string;
+}
+
+export interface LaunchFilesOptions {
+  /** `<state>/run/caps` */
+  capsDir: string;
+  store: CapabilityStore;
+  /** Unclaimed files are deleted and their capability revoked after this. */
+  ttlMs?: number;
+  now?: () => number;
+}
+
+/** How long a launch file may sit unclaimed. */
+export const LAUNCH_FILE_TTL_MS = 30_000;
+
+/**
+ * Launch files for panes that cannot inherit an fd (tmux). The daemon creates
+ * the file; the launcher in the pane claims it (`claimLaunchFile`), which
+ * unlinks it. One that is still on disk at its deadline was never claimed, so
+ * it is removed and the command's capability revoked.
+ */
+export class LaunchFiles {
+  private readonly pending = new Map<
+    string,
+    { commandId: string; deadline: number; timer: NodeJS.Timeout }
+  >();
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(private readonly opts: LaunchFilesOptions) {
+    this.ttlMs = opts.ttlMs ?? LAUNCH_FILE_TTL_MS;
+    this.now = opts.now ?? (() => Date.now());
+    ensurePrivateDir(opts.capsDir);
+    this.purge();
+  }
+
+  /** Delete whatever a previous daemon left behind: its workers died with it. */
+  purge(): void {
+    for (const name of readdirSync(this.opts.capsDir)) {
+      try {
+        unlinkSync(join(this.opts.capsDir, name));
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+  create(commandId: string): LaunchFile {
+    const cap = this.opts.store.get(commandId);
+    if (cap === undefined) throw new Error(`no capability minted for ${commandId}`);
+    const path = join(this.opts.capsDir, `${randomBytes(12).toString("hex")}.cap`);
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+      writeSync(fd, cap);
+    } finally {
+      closeSync(fd);
+    }
+    const timer = setTimeout(() => this.sweep(), this.ttlMs + 1);
+    timer.unref();
+    this.pending.set(path, { commandId, deadline: this.now() + this.ttlMs, timer });
+    return { path, commandId };
+  }
+
+  /** Forget the claimed, remove and revoke the expired. Returns the command ids
+   * revoked. Runs from the deadline timer and may be called directly. */
+  sweep(): string[] {
+    const revoked: string[] = [];
+    for (const [path, entry] of this.pending) {
+      if (!existsFile(path)) {
+        clearTimeout(entry.timer);
+        this.pending.delete(path);
+        continue; // claimed: the launcher unlinked it
+      }
+      if (this.now() < entry.deadline) continue;
+      try {
+        unlinkSync(path);
+      } catch {
+        /* claimed in the meantime */
+      }
+      clearTimeout(entry.timer);
+      this.pending.delete(path);
+      this.opts.store.revoke(entry.commandId);
+      revoked.push(entry.commandId);
+    }
+    return revoked;
+  }
+
+  /** Remove the unclaimed launch files of `commandId`, if any: its host is being
+   * stopped. The capability is the caller's to revoke. A claimed file is already
+   * gone. */
+  cancel(commandId: string): number {
+    let n = 0;
+    for (const [path, entry] of this.pending) {
+      if (entry.commandId !== commandId) continue;
+      try {
+        unlinkSync(path);
+      } catch {
+        /* claimed in the meantime */
+      }
+      clearTimeout(entry.timer);
+      this.pending.delete(path);
+      n++;
+    }
+    return n;
+  }
+
+  /** Files created and neither claimed nor expired yet. */
+  outstanding(): number {
+    return this.pending.size;
+  }
+
+  dispose(): void {
+    for (const e of this.pending.values()) clearTimeout(e.timer);
+    this.pending.clear();
+  }
+}
+
+function existsFile(path: string): boolean {
+  try {
+    statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The launcher's half: open the launch file, check it is ours and private,
+ * unlink it, and return the open fd. The unlink is the claim: of two openers
+ * only one unlinks, and the other is refused.
+ */
+export function claimLaunchFile(path: string): number {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || (st.mode & 0o077) !== 0)
+      throw new IpcError("unauthorized", "the launch file is not a private regular file");
+    if (typeof process.getuid === "function" && st.uid !== process.getuid())
+      throw new IpcError("unauthorized", "the launch file belongs to another user");
+    unlinkSync(path);
+    readCapabilityFd(fd);
+    return fd;
+  } catch (e) {
+    closeSync(fd);
+    throw e;
+  }
+}

package/src/ipc/client.ts

@@ -0,0 +1,269 @@
+// The worker's and the shims' end of the socket.
+//
+// A host process or a post shim reads its capability from the inherited fd
+// (QCR_IPC_CAP_FD) with pread each time it connects, says hello, then sends
+// requests and events. Nothing here touches the engine or pi.
+import net from "node:net";
+import { readCapabilityFd } from "./capability.js";
+import {
+  type IpcEventKind,
+  type IpcMessage,
+  type IpcRole,
+  type ResponseMessage,
+  IPC_VERSION,
+  IpcError,
+  LineDecoder,
+  MAX_LINE_BYTES,
+  decodeMessage,
+  encodeMessage,
+} from "./protocol.js";
+
+export interface IpcClientOptions {
+  socketPath: string;
+  role: IpcRole;
+  commandId: string;
+  capability: string;
+  /** The generation this process was started with. */
+  generation: number;
+  timeoutMs?: number;
+  maxLineBytes?: number;
+}
+
+interface Waiting {
+  resolve(r: ResponseMessage): void;
+  reject(e: unknown): void;
+  timer: NodeJS.Timeout | undefined;
+}
+
+export class IpcClient {
+  private nextId = 1;
+  private readonly waiting = new Map<string, Waiting>();
+  private controlHandler: ((kind: string, body: unknown) => void) | null = null;
+  private errorHandler: ((e: IpcError) => void) | null = null;
+  private closeHandler: ((e: IpcError) => void) | null = null;
+  private closedBySelf = false;
+  private ended: IpcError | null = null;
+
+  private constructor(
+    private readonly socket: net.Socket,
+    private readonly opts: IpcClientOptions,
+    /** What the daemon said in its hello_ok. */
+    readonly pr: number,
+    readonly serverGeneration: number,
+    decoder: LineDecoder,
+  ) {
+    socket.removeAllListeners("data");
+    socket.on("data", (chunk) => this.onData(chunk, decoder));
+    socket.on("close", () => this.end(new IpcError("closed", "the connection closed")));
+    socket.on("error", () => this.end(new IpcError("closed", "the connection failed")));
+  }
+
+  static async connect(opts: IpcClientOptions): Promise<IpcClient> {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const decoder = new LineDecoder(opts.maxLineBytes ?? MAX_LINE_BYTES);
+    const socket = net.connect(opts.socketPath);
+    // Frames that arrived in the same chunk as hello_ok; the connection replays them.
+    let early: string[] = [];
+    const hello = await new Promise<IpcMessage>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        socket.destroy();
+        reject(new IpcError("timeout", "no hello answer"));
+      }, timeoutMs);
+      const fail = (e: unknown) => {
+        clearTimeout(timer);
+        socket.destroy();
+        reject(e instanceof IpcError ? e : new IpcError("closed", "could not connect"));
+      };
+      socket.once("error", fail);
+      socket.once("close", () => fail(new IpcError("closed", "closed before hello_ok")));
+      socket.on("data", (chunk) => {
+        try {
+          const [line, ...rest] = decoder.push(chunk);
+          if (line === undefined) return;
+          early = rest;
+          clearTimeout(timer);
+          socket.off("error", fail);
+          resolve(decodeMessage(line));
+        } catch (e) {
+          fail(e);
+        }
+      });
+      socket.once("connect", () => {
+        socket.write(
+          encodeMessage({
+            v: IPC_VERSION,
+            type: "hello",
+            role: opts.role,
+            command_id: opts.commandId,
+            capability: opts.capability,
+          }),
+        );
+      });
+    });
+    if (hello.type === "error") {
+      socket.destroy();
+      throw new IpcError(hello.error.code, hello.error.message);
+    }
+    if (hello.type !== "hello_ok") {
+      socket.destroy();
+      throw new IpcError("bad_request", "expected hello_ok");
+    }
+    const client = new IpcClient(socket, opts, hello.pr, hello.generation, decoder);
+    // After the caller has registered its handlers, as a frame read later would be.
+    if (early.length > 0) setImmediate(() => client.handleLines(early));
+    return client;
+  }
+
+  /** Call an op and wait for its answer; a refusal rejects with the typed error. */
+  async request<T = unknown>(
+    op: string,
+    body?: unknown,
+    opts: { pr?: number; timeoutMs?: number } = {},
+  ): Promise<T> {
+    if (this.ended) throw this.ended;
+    const id = String(this.nextId++);
+    const msg: IpcMessage = {
+      v: IPC_VERSION,
+      type: "request",
+      id,
+      op,
+      generation: this.opts.generation,
+      ...(opts.pr !== undefined ? { pr: opts.pr } : {}),
+      ...(body !== undefined ? { body } : {}),
+    };
+    const line = encodeMessage(msg, this.opts.maxLineBytes);
+    // `timeoutMs: 0` waits without a timer: a permit grant may queue behind
+    // every other worker's lenses, and the worker's own wall clock bounds it.
+    const waitMs = opts.timeoutMs ?? this.opts.timeoutMs ?? 10_000;
+    const res = await new Promise<ResponseMessage>((resolve, reject) => {
+      const timer =
+        waitMs > 0
+          ? setTimeout(() => {
+              this.waiting.delete(id);
+              reject(new IpcError("timeout", `no answer to ${op}`));
+            }, waitMs)
+          : undefined;
+      this.waiting.set(id, { resolve, reject, timer });
+      this.socket.write(line);
+    });
+    if (!res.ok) throw new IpcError(res.error!.code, res.error!.message);
+    return res.body as T;
+  }
+
+  /** Report an event. Fire and forget: a refusal arrives through `onError`. */
+  event(kind: IpcEventKind, body?: unknown): void {
+    if (this.ended) throw this.ended;
+    this.socket.write(
+      encodeMessage(
+        {
+          v: IPC_VERSION,
+          type: "event",
+          kind,
+          generation: this.opts.generation,
+          ...(body !== undefined ? { body } : {}),
+        },
+        this.opts.maxLineBytes,
+      ),
+    );
+  }
+
+  /** Resolves once everything written so far has left this process: a worker
+   * that sends its last event and exits calls it first. */
+  drain(): Promise<void> {
+    if (this.ended) return Promise.resolve();
+    return new Promise((resolve) => this.socket.write("", () => resolve()));
+  }
+
+  onControl(fn: (kind: string, body: unknown) => void): void {
+    this.controlHandler = fn;
+  }
+
+  onError(fn: (e: IpcError) => void): void {
+    this.errorHandler = fn;
+  }
+
+  /** The daemon's end of the connection went away (it restarted, or revoked the
+   * capability). Not called for a `close()` of this side. */
+  onClose(fn: (e: IpcError) => void): void {
+    this.closeHandler = fn;
+  }
+
+  close(): void {
+    this.closedBySelf = true;
+    this.socket.end();
+    this.end(new IpcError("closed", "closed by this side"));
+  }
+
+  private onData(chunk: Buffer | string, decoder: LineDecoder): void {
+    let lines: string[];
+    try {
+      lines = decoder.push(chunk);
+    } catch (e) {
+      this.end(e as IpcError);
+      this.socket.destroy();
+      return;
+    }
+    this.handleLines(lines);
+  }
+
+  private handleLines(lines: string[]): void {
+    for (const line of lines) {
+      let msg: IpcMessage;
+      try {
+        msg = decodeMessage(line);
+      } catch {
+        continue; // a message this build cannot read; the next may be fine
+      }
+      if (msg.type === "response") {
+        const w = this.waiting.get(msg.id);
+        if (w === undefined) continue;
+        clearTimeout(w.timer);
+        this.waiting.delete(msg.id);
+        w.resolve(msg);
+      } else if (msg.type === "control") {
+        this.controlHandler?.(msg.kind, msg.body);
+      } else if (msg.type === "error") {
+        this.errorHandler?.(new IpcError(msg.error.code, msg.error.message));
+      }
+    }
+  }
+
+  private end(e: IpcError): void {
+    if (this.ended) return;
+    this.ended = e;
+    for (const w of this.waiting.values()) {
+      clearTimeout(w.timer);
+      w.reject(e);
+    }
+    this.waiting.clear();
+    if (!this.closedBySelf) this.closeHandler?.(e);
+  }
+}
+
+export type IpcEnv = Readonly<Record<string, string | undefined>>;
+
+/** Is the env one of a host or a shim of a worker-hosted command? */
+export function hasIpcEnv(env: IpcEnv = process.env): boolean {
+  return !!env.QCR_IPC_SOCKET && !!env.QCR_IPC_CAP_FD;
+}
+
+/**
+ * Connect the way a worker or a shim does: the socket, command and generation
+ * from env, the capability from the inherited fd, read afresh with pread.
+ */
+export async function connectFromEnv(
+  role: IpcRole,
+  env: IpcEnv = process.env,
+  extra: Partial<Pick<IpcClientOptions, "timeoutMs" | "maxLineBytes">> = {},
+): Promise<IpcClient> {
+  const socketPath = env.QCR_IPC_SOCKET;
+  const fdText = env.QCR_IPC_CAP_FD;
+  const commandId = env.QCR_IPC_COMMAND_ID;
+  const generation = Number(env.QCR_IPC_GENERATION);
+  if (!socketPath || !fdText || !commandId || !Number.isSafeInteger(generation) || generation < 0)
+    throw new IpcError("bad_request", "the IPC env is incomplete");
+  if (!/^\d{1,4}$/.test(fdText))
+    throw new IpcError("bad_request", "QCR_IPC_CAP_FD is not an fd number");
+  const capability = readCapabilityFd(Number(fdText));
+  return IpcClient.connect({ socketPath, role, commandId, capability, generation, ...extra });
+}