@bjoernrochel/sevro 0.1.0-rc.2 → 0.1.0-rc.21

package/src/runtime/paths.ts

@@ -0,0 +1,313 @@
+import {
+  access,
+  lstat,
+  readdir,
+  readlink,
+  realpath,
+  stat,
+} from "node:fs/promises";
+import { constants, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { nativeStateProtectedRoots } from "../native-transcript-state";
+import { workspaceStatePath } from "../fixtures/workspace-state";
+import {
+  basename,
+  delimiter,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+
+export function insideRuntimeRoot(root: string, path: string): boolean {
+  const child = relative(root, path);
+  return (
+    child === "" ||
+    (!child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child))
+  );
+}
+
+export function isRuntimeHomeRoot(root: string): boolean {
+  return [homedir(), userInfo().homedir]
+    .map((home) => resolve(home))
+    .includes(root);
+}
+
+export function requireRuntimeReadRoots(
+  readRoots: string[],
+  protectedRoots: string[],
+): void {
+  const hardRoots = [
+    ...protectedRoots.filter((root) => !isRuntimeHomeRoot(root)),
+    ...runtimeCredentialRoots(),
+    ...nativeStateProtectedRoots(),
+    workspaceStatePath(),
+  ];
+  for (const root of readRoots) {
+    if (root === "/" || isRuntimeHomeRoot(root))
+      throw new Error("runtime read root is too broad");
+    if (overlapsRuntimeRoots([root], hardRoots))
+      throw new Error("runtime read root overlaps protected data");
+  }
+}
+
+function runtimeCredentialRoots(): string[] {
+  return credentialRoots().flatMap((root) => [
+    root,
+    canonicalCredentialRoot(root),
+  ]);
+}
+
+function overlapsRuntimeRoots(roots: string[], deniedRoots: string[]): boolean {
+  return roots.some((root) =>
+    deniedRoots.some(
+      (denied) =>
+        insideRuntimeRoot(denied, root) || insideRuntimeRoot(root, denied),
+    ),
+  );
+}
+
+function canonicalCredentialRoot(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code !== "ENOENT") throw cause;
+    const target = missingCredentialLink(path);
+    if (target) return canonicalCredentialRoot(target);
+    return join(canonicalCredentialRoot(dirname(path)), basename(path));
+  }
+}
+
+function missingCredentialLink(path: string): string | null {
+  try {
+    return lstatSync(path).isSymbolicLink()
+      ? resolve(dirname(path), readlinkSync(path))
+      : null;
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw cause;
+  }
+}
+
+export function runtimeExecutableProtection(
+  readRoots: string[],
+  protectedRoots: string[],
+  allowHomeRuntime: boolean,
+): string[] {
+  if (!allowHomeRuntime) return protectedRoots;
+  requireRuntimeReadRoots(readRoots, []);
+  return protectedRoots.filter((root) => !isRuntimeHomeRoot(root));
+}
+
+function credentialRoots(): string[] {
+  return [homedir(), userInfo().homedir].flatMap((home) =>
+    [
+      ".ssh",
+      ".aws",
+      ".codex",
+      ".claude",
+      ".config/gcloud",
+      ".local/share/keyrings",
+    ].map((path) => join(home, path)),
+  );
+}
+
+export async function canonicalRuntimeRoot(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code !== "ENOENT") throw cause;
+    const target = await missingRuntimeLink(path);
+    if (target) return canonicalRuntimeRoot(target);
+    return join(await canonicalRuntimeRoot(dirname(path)), basename(path));
+  }
+}
+
+async function missingRuntimeLink(path: string): Promise<string | null> {
+  try {
+    return (await lstat(path)).isSymbolicLink()
+      ? resolve(dirname(path), await readlink(path))
+      : null;
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw cause;
+  }
+}
+
+function installationRoot(directory: string): string | null {
+  if (basename(directory) !== "bin") return null;
+  const root = dirname(directory);
+  const broad = [
+    "/",
+    "/usr",
+    "/usr/local",
+    "/opt/homebrew",
+    ...[homedir(), userInfo().homedir].flatMap((home) => [
+      home,
+      join(home, ".local"),
+    ]),
+  ];
+  return broad.includes(root) ? null : root;
+}
+
+async function linkedToolRoots(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  if (entries.length > 4096)
+    throw new Error("runtime PATH directory exceeds entry limit");
+  const roots: string[] = [];
+  for (const entry of entries.filter((entry) => entry.isSymbolicLink())) {
+    const target = await linkedTarget(join(directory, entry.name));
+    if (!target) continue;
+    const bin = dirname(target);
+    roots.push(bin);
+    const installation = installationRoot(bin);
+    if (installation) roots.push(installation);
+  }
+  return roots;
+}
+
+async function linkedTarget(path: string): Promise<string | null> {
+  try {
+    const target = await realpath(path);
+    return (await stat(target)).isFile() ? target : null;
+  } catch (cause) {
+    if (
+      ["EACCES", "EPERM", "ENOENT"].includes(
+        (cause as NodeJS.ErrnoException).code ?? "",
+      )
+    )
+      return null;
+    throw cause;
+  }
+}
+
+/** Missing PATH entries are inert; relative entries cannot grant host access. */
+export async function runtimePathDirectories(
+  path: string | undefined,
+): Promise<string[]> {
+  if (path === undefined) return [];
+  const roots: string[] = [];
+  for (const entry of path.split(delimiter)) {
+    roots.push(...(await pathEntryRoots(entry)));
+  }
+  return [...new Set(roots)].sort();
+}
+
+function containsControl(value: string): boolean {
+  return Array.from(value).some(
+    (character) =>
+      character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f,
+  );
+}
+
+function requirePathEntry(entry: string): void {
+  if (!isAbsolute(entry) || containsControl(entry))
+    throw new Error("runtime PATH entries must be absolute and nonempty");
+}
+
+/** Ambient tool discovery must not grant access to the operator's credentials. */
+export async function runtimeInheritedPath(path: string): Promise<string> {
+  const deniedRoots = runtimeCredentialRoots();
+  const selected: string[] = [];
+  for (const entry of path.split(delimiter)) {
+    requirePathEntry(entry);
+    const paths = [resolve(entry), await canonicalRuntimeRoot(entry)];
+    if (overlapsRuntimeRoots(paths, deniedRoots)) continue;
+    if (overlapsRuntimeRoots(await pathEntryRoots(entry), deniedRoots))
+      continue;
+    selected.push(entry);
+  }
+  if (selected.length === 0)
+    throw new Error("runtime inherited PATH has no unprotected entries");
+  return selected.join(delimiter);
+}
+
+async function pathEntryRoots(entry: string): Promise<string[]> {
+  requirePathEntry(entry);
+  const directory = await existingDirectory(entry);
+  if (!directory) return [];
+  const installation = installationRoot(directory);
+  return [
+    resolve(entry),
+    directory,
+    ...(installation ? [installation] : []),
+    ...(await linkedToolRoots(directory)),
+  ];
+}
+
+async function existingDirectory(path: string): Promise<string | null> {
+  try {
+    const canonical = await realpath(path);
+    if (!(await stat(canonical)).isDirectory())
+      throw new Error("runtime PATH entry is not a directory");
+    await access(canonical, constants.R_OK | constants.X_OK);
+    return canonical;
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw cause;
+  }
+}
+
+export function runtimeDeclaredPath(
+  path: string,
+  environment: Record<string, string>,
+  base: string,
+): string {
+  const expanded = path.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g,
+    (_match: string, name: string) => {
+      const value = environment[name];
+      if (value === undefined)
+        throw new Error(`runtime path variable is undeclared: ${name}`);
+      return value;
+    },
+  );
+  if (containsControl(expanded) || expanded.includes("${"))
+    throw new Error("runtime path contains invalid characters");
+  return expanded.startsWith("~/")
+    ? join(homedir(), expanded.slice(2))
+    : resolve(base, expanded);
+}
+
+export async function declaredRuntimeRoots(
+  paths: string[],
+  environment: Record<string, string>,
+  base: string,
+): Promise<string[]> {
+  const roots = await Promise.all(
+    paths.map(async (path) => {
+      const directory = await existingDirectory(
+        runtimeDeclaredPath(path, environment, base),
+      );
+      if (!directory) throw new Error("declared runtime read root is missing");
+      return [directory, runtimeDeclaredPath(path, environment, base)];
+    }),
+  );
+  return [...new Set(roots.flat())];
+}
+
+export async function optionalRuntimeRoots(
+  paths: string[],
+  environment: Record<string, string>,
+  base: string,
+  protectedRoots: string[] = [],
+): Promise<{ roots: string[]; skipped: string[] }> {
+  const roots: string[] = [],
+    skipped: string[] = [];
+  for (const path of paths) {
+    const declared = runtimeDeclaredPath(path, environment, base);
+    requireRuntimeReadRoots(
+      [declared, await canonicalRuntimeRoot(declared)],
+      protectedRoots,
+    );
+    const directory = await existingDirectory(declared);
+    if (directory) roots.push(directory, declared);
+    else skipped.push(declared);
+  }
+  return {
+    roots: [...new Set(roots)].sort(),
+    skipped: [...new Set(skipped)].sort(),
+  };
+}

package/src/runtime/query.ts

@@ -0,0 +1,85 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { homedir } from "node:os";
+import { terminateOwnedProcessGroup } from "../process-lifecycle";
+
+export class RuntimeMetadataQueryError extends Error {
+  constructor(
+    message: string,
+    readonly noActiveDeveloper = false,
+  ) {
+    super(message);
+  }
+}
+
+function exitError(
+  code: number | null,
+  stderr: Buffer[],
+): RuntimeMetadataQueryError {
+  const noSelection =
+    code === 2 &&
+    Buffer.concat(stderr)
+      .toString("utf8")
+      .toLowerCase()
+      .includes("unable to get active developer directory");
+  return new RuntimeMetadataQueryError(`exit ${String(code)}`, noSelection);
+}
+
+function stopQuery(child: ChildProcess): void {
+  if (child.pid === undefined) return;
+  terminateOwnedProcessGroup(
+    { pid: child.pid, kill: (signal) => child.kill(signal) },
+    { alwaysGroup: true, fallbackError: "propagate" },
+  );
+}
+
+/** Bound both output streams and stop every descendant of this metadata query. */
+export function runtimeMetadataQuery(
+  executable: string,
+  argument: string,
+  environment: Record<string, string>,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, [argument], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...environment,
+        HOME: homedir(),
+        HOMEBREW_NO_AUTO_UPDATE: "1",
+        LC_ALL: "C",
+        LANG: "C",
+      },
+    });
+    const chunks: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let bytes = 0;
+    const fail = (reason: string, cause?: unknown) => {
+      stopQuery(child);
+      reject(new Error(reason, { cause }));
+    };
+    const timer = setTimeout(() => {
+      fail("timeout exceeded");
+    }, 3000);
+    const consume = (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (bytes > 8192) fail("output limit exceeded");
+    };
+    child.stdout.on("data", (chunk: Buffer) => {
+      consume(chunk);
+      if (bytes <= 8192) chunks.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      consume(chunk);
+      if (bytes <= 8192) stderr.push(chunk);
+    });
+    child.on("error", (cause: Error) => {
+      fail("provider unavailable", cause);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      stopQuery(child);
+      if (code !== 0) reject(exitError(code, stderr));
+      else resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+  });
+}

package/src/runtime/seeds.ts

@@ -0,0 +1,134 @@
+import {
+  chmod,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { hashJson, sha256 } from "../identity";
+import type { RuntimePolicy } from "./config";
+import { insideRuntimeRoot } from "./paths";
+
+class SeedSnapshot {
+  private entries = 0;
+  private bytes = 0;
+  private readonly files: {
+    path: string;
+    sha256: string;
+    mode: number;
+    bytes: Buffer | null;
+  }[] = [];
+  constructor(
+    private readonly root: string,
+    private readonly retainContents = false,
+  ) {}
+
+  async digest(): Promise<string> {
+    await this.visit("", new Set());
+    return hashJson(
+      this.files.map(({ path, sha256, mode }) => ({ path, sha256, mode })),
+    );
+  }
+
+  private async visit(path: string, ancestors: Set<string>): Promise<void> {
+    const logical = join(this.root, path);
+    const canonical = await realpath(logical);
+    if (!insideRuntimeRoot(this.root, canonical))
+      throw new Error("runtime seed link escapes its source");
+    if (++this.entries > 16384)
+      throw new Error("runtime seed exceeds entry limit");
+    const info = await stat(canonical);
+    if (info.isDirectory()) {
+      this.files.push({
+        path,
+        sha256: "directory",
+        mode: info.mode & 0o777,
+        bytes: null,
+      });
+      await this.visitDirectory(path, canonical, ancestors);
+      return;
+    }
+    if (!info.isFile())
+      throw new Error("runtime seed contains an unsupported file");
+    await this.visitFile(path, canonical, info);
+  }
+
+  private async visitDirectory(
+    path: string,
+    canonical: string,
+    ancestors: Set<string>,
+  ): Promise<void> {
+    if (ancestors.has(canonical))
+      throw new Error("runtime seed contains a directory cycle");
+    const parents = new Set([...ancestors, canonical]);
+    for (const name of (await readdir(canonical)).sort())
+      await this.visit(join(path, name), parents);
+  }
+
+  private async visitFile(
+    path: string,
+    canonical: string,
+    info: { size: number; mode: number },
+  ): Promise<void> {
+    this.bytes += info.size;
+    if (this.bytes > 512 * 1024 * 1024)
+      throw new Error("runtime seed exceeds 512 MiB");
+    const bytes = await readFile(canonical);
+    this.files.push({
+      path,
+      sha256: sha256(bytes),
+      mode: info.mode & 0o777,
+      bytes: this.retainContents ? bytes : null,
+    });
+  }
+  async materialize(target: string): Promise<void> {
+    for (const file of this.files) {
+      const path = join(target, file.path);
+      if (file.bytes === null) await mkdir(path, { mode: 0o700 });
+      else
+        await writeFile(path, file.bytes, {
+          flag: "wx",
+          mode: file.mode,
+        });
+    }
+    for (const file of [...this.files].reverse())
+      await chmod(join(target, file.path), file.mode);
+  }
+}
+
+export async function runtimeSeedDigest(source: string): Promise<string> {
+  return new SeedSnapshot(await realpath(source)).digest();
+}
+
+type RuntimeSeed = NonNullable<RuntimePolicy["seeds"]>[number];
+const verifiedSeeds = new WeakMap<
+  RuntimeSeed,
+  { source: string; digest: string; snapshot: Promise<SeedSnapshot> }
+>();
+
+/** Contents stay in runner memory; no writable role or filesystem alias owns them. */
+export async function materializeRuntimeSeed(
+  seed: RuntimeSeed,
+  target: string,
+): Promise<void> {
+  let verified = verifiedSeeds.get(seed);
+  if (verified?.source !== seed.source || verified.digest !== seed.sha256) {
+    verified = {
+      source: seed.source,
+      digest: seed.sha256,
+      snapshot: verifiedSnapshot(seed),
+    };
+    verifiedSeeds.set(seed, verified);
+  }
+  await (await verified.snapshot).materialize(target);
+}
+
+async function verifiedSnapshot(seed: RuntimeSeed): Promise<SeedSnapshot> {
+  const snapshot = new SeedSnapshot(await realpath(seed.source), true);
+  if ((await snapshot.digest()) !== seed.sha256)
+    throw new Error("runtime seed changed after configuration snapshot");
+  return snapshot;
+}

package/src/runtime/shared-cache.ts

@@ -0,0 +1,143 @@
+import { access, lstat, realpath, symlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { userInfo } from "node:os";
+import { isAbsolute, join } from "node:path";
+import type { RuntimePolicy, RuntimeRole } from "./config";
+import { declaredRuntimeRoots, requireRuntimeReadRoots } from "./paths";
+
+export interface SharedCacheDirectory {
+  source: string;
+  target: string;
+  roles: RuntimeRole[];
+}
+
+export async function resolveSharedCaches(
+  caches: SharedCacheDirectory[],
+  environment: Record<string, string>,
+  base: string,
+  protectedRoots: string[],
+): Promise<SharedCacheDirectory[]> {
+  return Promise.all(
+    caches.map(async (cache) => {
+      const roots = await declaredRuntimeRoots(
+        [cache.source],
+        environment,
+        base,
+      );
+      requireRuntimeReadRoots(roots, protectedRoots);
+      const [declared] = roots;
+      if (!declared) throw new Error("runtime shared cache source is missing");
+      const source = await realpath(declared);
+      await requireSharedCache(source);
+      return { ...cache, source };
+    }),
+  );
+}
+
+export function selectedSharedCaches(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole = "candidate",
+): SharedCacheDirectory[] {
+  return (policy?.sharedCacheDirectories ?? []).filter((cache) =>
+    cache.roles.includes(role),
+  );
+}
+
+export async function sharedCacheRoots(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole = "candidate",
+  protectedRoots: string[],
+): Promise<string[]> {
+  requireSharedCachePolicy(policy);
+  const roots = selectedSharedCaches(policy, role).map((cache) => cache.source);
+  return requireWritableCacheRoots(roots, protectedRoots);
+}
+
+export function requireSharedCachePolicy(
+  policy: RuntimePolicy | undefined,
+): void {
+  if (!policy) return;
+  const caches = policy.sharedCacheDirectories ?? [];
+  const protectedRoots = [
+    ...policy.readOnlyRoots,
+    ...(policy.seeds ?? []).map((seed) => seed.source),
+  ];
+  for (const cache of caches) {
+    requireCacheRoles(cache.roles);
+    requireRuntimeReadRoots(
+      [cache.source],
+      [
+        ...protectedRoots,
+        ...caches
+          .filter((other) => other !== cache)
+          .map((other) => other.source),
+      ],
+    );
+  }
+}
+
+function requireCacheRoles(roles: RuntimeRole[]): void {
+  if (!Array.isArray(roles) || roles.length === 0)
+    throw new Error("runtime shared cache roles are invalid");
+  const allowed = ["candidate", "checks", "hooks", "semantic", "advisory"];
+  if (
+    new Set(roles).size !== roles.length ||
+    roles.some((role) => !allowed.includes(role))
+  )
+    throw new Error("runtime shared cache roles are invalid");
+}
+
+export function sharedCacheDenyRoots(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole = "candidate",
+): string[] {
+  return (policy?.sharedCacheDirectories ?? [])
+    .filter((cache) => !cache.roles.includes(role))
+    .map((cache) => cache.source);
+}
+
+export async function requireWritableCacheRoots(
+  roots: string[],
+  protectedRoots: string[],
+): Promise<string[]> {
+  requireRuntimeReadRoots(roots, protectedRoots);
+  for (const root of roots) await requireSharedCache(root);
+  return roots;
+}
+
+async function requireSharedCache(source: string): Promise<void> {
+  if (!isAbsolute(source) || (await realpath(source)) !== source)
+    throw new Error("runtime shared cache must be a canonical directory");
+  const info = await lstat(source);
+  if (!info.isDirectory() || info.uid !== userInfo().uid)
+    throw new Error("runtime shared cache must be an owned directory");
+  await access(source, constants.R_OK | constants.W_OK | constants.X_OK);
+}
+
+/** A slot aliases the operator-selected cache; its contents are never copied. */
+export async function linkSharedCaches(
+  policy: RuntimePolicy,
+  role: RuntimeRole,
+  root: string,
+): Promise<void> {
+  for (const cache of selectedSharedCaches(policy, role)) {
+    const target = join(root, cache.target);
+    try {
+      await symlink(cache.source, target, "dir");
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "EEXIST") throw cause;
+      await requireCacheSlot(target, cache.source, cause);
+    }
+  }
+}
+
+async function requireCacheSlot(
+  target: string,
+  source: string,
+  cause: unknown,
+): Promise<void> {
+  if (!(await lstat(target)).isSymbolicLink())
+    throw new Error("runtime shared cache slot was replaced", { cause });
+  if ((await realpath(target)) !== source)
+    throw new Error("runtime shared cache slot changed its source", { cause });
+}