sept-agent 0.1.2 → 0.1.4

package/src/cli/hands-record.ts

@@ -0,0 +1,213 @@
+/** Private ownership receipts for the optional local hands setup commands. */
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  chmodSync,
+  openSync,
+  fsyncSync,
+  closeSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { randomUUID } from "node:crypto";
+import { atomicWrite, SeptError } from "../durable/index.js";
+
+/** Fixed paths returned directly as existing createWorker options; no credential is generated. */
+export interface HandsPaths {
+  stateRoot: string;
+  agentDir: string;
+  workspaceRoot: string;
+  handsConfigurationPath: string;
+}
+
+/** Durable exclusive setup identity survives partial creation and never grants task authority. */
+export interface HandsReceipt {
+  version: 1;
+  owner: string;
+  engineSocket: string;
+  socketIdentity: string;
+  daemonId: string;
+  image: string;
+  containerId?: string;
+  generation?: string;
+  phase: "prepared" | "creating" | "running" | "ready" | "failed" | "finished";
+}
+
+/** Derive the sole supported fresh-instance layout. */
+export function handsPaths(root: string): HandsPaths {
+  return {
+    stateRoot: join(root, "state"),
+    agentDir: join(root, "agent"),
+    workspaceRoot: join(root, "workspace"),
+    handsConfigurationPath: join(root, "hands.json"),
+  };
+}
+
+/** Refuse lexical aliases and mutable ancestors before creating or reading ownership. */
+export function trustedHandsRoot(value: string | undefined, fresh = false): string {
+  if (
+    value === undefined ||
+    !isAbsolute(value) ||
+    value.length > 4096 ||
+    /[\x00-\x1f,]/.test(value)
+  ) {
+    throw new SeptError(
+      "hands requires a canonical absolute --root without control characters or commas",
+    );
+  }
+  const existing = fresh ? dirname(value) : value;
+  if (realpathSync(existing) !== existing || normalize(value) !== value) {
+    throw new SeptError("Hands root must be canonical");
+  }
+  validateAncestors(existing);
+  return value;
+}
+
+function validateAncestors(existing: string): void {
+  for (let path = existing; ; path = dirname(path)) {
+    const stat = lstatSync(path);
+    const owner = stat.uid === 0 || stat.uid === process.getuid?.();
+    const sticky = stat.uid === 0 && (stat.mode & 0o1000) !== 0;
+    if (!stat.isDirectory() || !owner || ((stat.mode & 0o022) !== 0 && !sticky)) {
+      throw new SeptError("Hands root ancestry is not trusted");
+    }
+    if (path === dirname(path)) {
+      return;
+    }
+  }
+}
+
+/** Create only a new root: a failed or foreign instance is never overwritten or adopted by init. */
+export function createHandsRoot(root: string): HandsPaths {
+  mkdirSync(root, { mode: 0o755 });
+  chmodSync(root, 0o755);
+  const paths = handsPaths(root);
+  for (const directory of [
+    paths.stateRoot,
+    paths.agentDir,
+    paths.workspaceRoot,
+    join(root, "evidence"),
+    join(root, "docker-cli"),
+  ]) {
+    mkdirSync(directory, { mode: 0o700 });
+  }
+  mkdirSync(join(root, "resources"), { mode: 0o755 });
+  chmodSync(join(root, "resources"), 0o755);
+  syncSetupDirectory(root);
+  syncSetupDirectory(dirname(root));
+  return paths;
+}
+
+function syncSetupDirectory(path: string): void {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+/** Persist recovery ownership before creating a container and after every identity transition. */
+export function writeHandsReceipt(root: string, receipt: HandsReceipt): void {
+  atomicWrite(join(root, "evidence", "setup.json"), receipt);
+}
+
+/** Read bounded private ownership, refusing edited schema, symlinks, hardlinks or broad permissions. */
+export function readHandsReceipt(root: string): HandsReceipt {
+  const path = join(root, "evidence", "setup.json");
+  const raw = readHandsMetadata(path, 16 * 1024);
+  if (!isRecord(raw)) {
+    throw new SeptError("Hands setup ownership is malformed");
+  }
+  return decodeReceipt(raw);
+}
+
+/** Read private bounded setup metadata without presenting hostile JSON or filesystem diagnostics. */
+export function readHandsMetadata(path: string, maximum: number): unknown {
+  try {
+    const file = lstatSync(path);
+    if (
+      !file.isFile() ||
+      file.nlink !== 1 ||
+      file.uid !== process.getuid?.() ||
+      (file.mode & 0o077) !== 0 ||
+      file.size > maximum
+    ) {
+      throw new SeptError("Hands metadata must be a bounded private owned regular file");
+    }
+    const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return raw;
+  } catch (error: unknown) {
+    throw new SeptError("Hands setup metadata is unavailable or malformed", { cause: error });
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeReceipt(raw: Record<string, unknown>): HandsReceipt {
+  const keys = [
+    "version",
+    "owner",
+    "engineSocket",
+    "socketIdentity",
+    "daemonId",
+    "image",
+    "containerId",
+    "generation",
+    "phase",
+  ];
+  if (Object.keys(raw).some((key) => !keys.includes(key)) || raw.version !== 1) {
+    throw new SeptError("Hands setup ownership is malformed");
+  }
+  const containerId =
+    raw.containerId === undefined ? undefined : text(raw.containerId, /^[a-f0-9]{64}$/);
+  const generation = raw.generation === undefined ? undefined : text(raw.generation);
+  return {
+    version: 1,
+    owner: text(raw.owner, /^[a-f0-9-]{36}$/),
+    engineSocket: text(raw.engineSocket),
+    socketIdentity: text(raw.socketIdentity),
+    daemonId: text(raw.daemonId),
+    image: text(raw.image, /^sha256:[a-f0-9]{64}$/),
+    phase: receiptPhase(raw.phase),
+    ...(containerId === undefined ? {} : { containerId }),
+    ...(generation === undefined ? {} : { generation }),
+  };
+}
+
+function text(value: unknown, pattern?: RegExp): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > 4096 ||
+    /[\x00-\x1f]/.test(value)
+  ) {
+    throw new SeptError("Hands setup ownership text is malformed");
+  }
+  if (pattern !== undefined && !pattern.test(value)) {
+    throw new SeptError("Hands setup ownership identity is malformed");
+  }
+  return value;
+}
+
+function receiptPhase(value: unknown): HandsReceipt["phase"] {
+  switch (value) {
+    case "prepared":
+    case "creating":
+    case "running":
+    case "ready":
+    case "failed":
+    case "finished":
+      return value;
+    default:
+      throw new SeptError("Hands setup phase is malformed");
+  }
+}
+
+/** Generate the unguessable container ownership label before any Engine effect. */
+export function newHandsOwner(): string {
+  return randomUUID();
+}

package/src/cli/hands.ts

@@ -0,0 +1,207 @@
+/** Optional local setup composition; the existing worker and policy authority remain unchanged. */
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { acquireStateRootLease, atomicWrite, SeptError } from "../durable/index.js";
+import { DockerEngineControl, loadHandsConfiguration } from "../execution/index.js";
+import { finishHands } from "./hands-finish.js";
+import { runPermissions } from "./permissions.js";
+import type { CliInvocation } from "./options.js";
+import {
+  createHandsRoot,
+  handsPaths,
+  newHandsOwner,
+  trustedHandsRoot,
+  writeHandsReceipt,
+  type HandsReceipt,
+} from "./hands-record.js";
+import { createHandsArguments, handsDocker } from "./hands-docker.js";
+import { captureHandsOwner, inspectHandsOwner, stopHandsOwner } from "./hands-owner.js";
+
+/** Execute the two installed operator commands; signals join cleanup before the process exits. */
+export async function runHands(invocation: CliInvocation): Promise<unknown> {
+  if (invocation.action !== "init" && invocation.action !== "finish") {
+    throw new SeptError("Usage: sept hands init|finish --root <absolute-new-instance>");
+  }
+  const abort = new AbortController();
+  const cancel = (): void => {
+    abort.abort();
+  };
+  process.on("SIGINT", cancel);
+  process.on("SIGTERM", cancel);
+  try {
+    return invocation.action === "init"
+      ? await initialize(invocation.options, abort.signal)
+      : await finishHands(invocation.options);
+  } finally {
+    process.off("SIGINT", cancel);
+    process.off("SIGTERM", cancel);
+  }
+}
+
+function assertNotCancelled(signal: AbortSignal): void {
+  if (signal.aborted) {
+    throw new SeptError("Hands setup cancelled; ownership and recovery receipts retained");
+  }
+}
+
+async function initialize(options: Record<string, string>, signal: AbortSignal): Promise<unknown> {
+  const root = trustedHandsRoot(options.root, true);
+  if (options.access !== "files" && options.access !== "none") {
+    throw new SeptError("hands init requires explicit --access files|none");
+  }
+  if (
+    options.image === undefined ||
+    options.image.length > 512 ||
+    options.image.startsWith("-") ||
+    options["engine-socket"] === undefined
+  ) {
+    throw new SeptError("hands init requires --image and explicit local --engine-socket");
+  }
+  const engine = await DockerEngineControl.open(options["engine-socket"]);
+  try {
+    assertNotCancelled(signal);
+    createHandsRoot(root);
+    return await initializeOwned(root, options, engine, signal);
+  } finally {
+    await engine.close();
+  }
+}
+
+async function initializeOwned(
+  root: string,
+  options: Record<string, string>,
+  engine: DockerEngineControl,
+  signal: AbortSignal,
+): Promise<unknown> {
+  const release = acquireStateRootLease(join(root, "evidence"));
+  const receipt = initialReceipt(options, engine);
+  try {
+    writeHandsReceipt(root, receipt);
+    resolveImage(root, receipt, options.image ?? "");
+    await createContainer(root, receipt, engine, signal);
+    await activatePermissions(root, options.access === "files");
+    assertNotCancelled(signal);
+    receipt.phase = "ready";
+    writeHandsReceipt(root, receipt);
+    return {
+      ...handsPaths(root),
+      containerId: receipt.containerId,
+      generation: receipt.generation,
+      access: options.access,
+    };
+  } catch (error: unknown) {
+    await initializationFailure(root, receipt, engine);
+    throw new SeptError("Hands initialization failed; recovery evidence retained under --root", {
+      cause: error,
+    });
+  } finally {
+    release();
+  }
+}
+
+function resolveImage(root: string, receipt: HandsReceipt, imageName: string): void {
+  const image = handsDocker(root, receipt, ["image", "inspect", "--format", "{{.Id}}", imageName]);
+  if (!/^sha256:[a-f0-9]{64}$/.test(image)) {
+    throw new SeptError("Hands image must already be locally available with immutable identity");
+  }
+  receipt.image = image;
+}
+
+function initialReceipt(
+  options: Record<string, string>,
+  engine: DockerEngineControl,
+): HandsReceipt {
+  return {
+    version: 1,
+    owner: newHandsOwner(),
+    engineSocket: realpathSync(options["engine-socket"] ?? ""),
+    socketIdentity: engine.socketIdentity,
+    daemonId: engine.daemonId,
+    image: `sha256:${"0".repeat(64)}`,
+    phase: "prepared",
+  };
+}
+
+async function createContainer(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+  signal: AbortSignal,
+): Promise<void> {
+  receipt.phase = "creating";
+  writeHandsReceipt(root, receipt);
+  receipt.containerId = handsDocker(root, receipt, createHandsArguments(root, receipt));
+  await inspectHandsOwner(root, receipt, engine);
+  assertNotCancelled(signal);
+  handsDocker(root, receipt, ["start", receipt.containerId]);
+  const state = await inspectHandsOwner(root, receipt, engine);
+  if (typeof state.StartedAt !== "string" || state.Running !== true) {
+    throw new SeptError("Hands start generation was not established");
+  }
+  receipt.generation = state.StartedAt;
+  writeHandsReceipt(root, receipt);
+  const paths = handsPaths(root);
+  atomicWrite(paths.handsConfigurationPath, {
+    profile: "docker-linux-warm-v1",
+    engineSocket: receipt.engineSocket,
+    containerId: receipt.containerId,
+    generation: receipt.generation,
+    workspace: paths.workspaceRoot,
+    resources: join(root, "resources"),
+    dataDomain: "private",
+    workspaceLimits: { bytes: 134217728, inodes: 32768 },
+    shell: false,
+    readOnlyMounts: [],
+  });
+  await captureHandsOwner(
+    root,
+    receipt,
+    loadHandsConfiguration(paths.handsConfigurationPath),
+    engine,
+  );
+  assertNotCancelled(signal);
+}
+
+async function activatePermissions(root: string, files: boolean): Promise<void> {
+  const paths = handsPaths(root);
+  const policy = join(root, "evidence", "initial-policy.json");
+  atomicWrite(policy, {
+    mode: "scoped",
+    workspace: { read: files, write: files },
+    selected: [],
+    execute: false,
+    network: false,
+  });
+  await runPermissions(
+    {
+      command: "permissions",
+      action: "set",
+      options: { hands: paths.handsConfigurationPath, policy, revision: "0" },
+    },
+    paths.stateRoot,
+    paths.agentDir,
+  );
+}
+
+async function initializationFailure(
+  root: string,
+  receipt: HandsReceipt,
+  engine: DockerEngineControl,
+): Promise<void> {
+  let stopped = receipt.phase === "prepared";
+  try {
+    if (!stopped) {
+      await stopHandsOwner(root, receipt, engine);
+      stopped = true;
+    }
+  } catch {
+    // Unknown ownership never authorizes a broader stop; retain evidence for explicit reconciliation.
+  } finally {
+    receipt.phase = "failed";
+    writeHandsReceipt(root, receipt);
+    atomicWrite(join(root, "evidence", "initialization-failure.json"), {
+      stopped,
+      reconciliationRequired: !stopped,
+    });
+  }
+}

package/src/cli/options.ts

@@ -6,6 +6,7 @@
 import { CliError } from "./errors.js";
 
 const OPTION_KEYS = {
+  hands: ["root", "engine-socket", "image", "access"],
   worker: ["hands", "agent-dir", "host", "port", "state-dir", "workspace-root"],
   run: [
     "hands",
@@ -83,7 +84,8 @@ export function parseCliInvocation(argv: string[]): CliInvocation | undefined {
   if (!isCommand(command)) {
     return undefined;
   }
-  const hasAction = command === "models" || command === "auth" || command === "permissions";
+  const hasAction =
+    command === "models" || command === "auth" || command === "permissions" || command === "hands";
   const action = hasAction ? argv[3] : undefined;
   const options = parseOptions(argv.slice(hasAction ? 4 : 3), OPTION_KEYS[command]);
   return action === undefined ? { command, options } : { command, action, options };

package/src/cli.ts

@@ -15,7 +15,7 @@ async function main(): Promise<void> {
   const invocation = parseCliInvocation(process.argv);
   if (invocation === undefined) {
     process.stderr.write(
-      "Usage: sept worker|run|doctor|health|models|auth|permissions [action] [options]\n",
+      "Usage: sept worker|run|doctor|health|models|auth|permissions|hands [action] [options]\n",
     );
     process.exitCode = 2;
     return;

package/src/execution/hands-process-owner.ts

@@ -15,10 +15,7 @@ import type {
   NamespaceLifetime,
 } from "./contracts.js";
 
-interface ProcessIdentity {
-  pid: number;
-  start: string;
-}
+type ProcessIdentity = ReturnType<typeof parseProcessIdentity>;
 interface CommandOptions {
   network: boolean;
   timeout?: number;
@@ -169,6 +166,8 @@ export class HandsProcessOwner {
   }
   private async waitCommand(attachment: HandsAttachment, state: CommandState): Promise<void> {
     while (!state.stop.signal.aborted) {
+      // EOF may arrive while inspection is in flight; only a later Engine read can prove a closed stream lost its exec.
+      const closedBeforeInspection = state.attachmentClosed;
       const inspected = await this.engine.inspectExec(attachment.execId);
       if (inspected.ContainerID !== this.configuration.containerId) {
         throw new SeptError("Hands command exec identity changed");
@@ -176,7 +175,7 @@ export class HandsProcessOwner {
       if (inspected.Running === false) {
         return;
       }
-      if (state.attachmentClosed) {
+      if (closedBeforeInspection) {
         attachment.assertJoined();
         throw new SeptError("Hands command stream closed before its exec joined");
       }

package/src/execution/index.ts

@@ -34,3 +34,13 @@ export {
 
 /** Exact-family filter generation for trusted consumer-owned network setup. */
 export { networkFirewall } from "./network-profile.js";
+
+/** Local setup uses the same authenticated Engine and pinned namespace cleanup as the worker. */
+export { DockerEngineControl } from "./docker-engine.js";
+export {
+  captureNamespaceLifetime,
+  stopCapturedNamespace,
+  parseNamespaceLifetime,
+} from "./hands-processes.js";
+
+export { guardedCommand } from "./hands-guarded-command.js";