@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/__tests__/agent-identity.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Who the agent host runs as (`shared/agent-identity.ts`).
+ *
+ * Pinned:
+ *  - only root on Linux in a container shape (the start script's marker)
+ *    separates; a local runner, a non-root one, macOS and a runner started
+ *    without the layer do not;
+ *  - the agent's home is `STIGMER_AGENT_HOME` when set, else the default;
+ *  - the agent user and group are appended when missing, left alone when
+ *    present, and an id another account holds is refused;
+ *  - the agent's state lives under the agent's home when the runner
+ *    separates, else under this process's `HOME`;
+ *  - a separating runner is ready only when the user, its home and a
+ *    `setpriv` drop all work, and each failure is one line naming its fix.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import {
+  AGENT_GID,
+  AGENT_UID,
+  DEFAULT_AGENT_HOME,
+  agentIdentity,
+  agentStateHome,
+  ensureAgentUser,
+  prepareAgentSeparation,
+  setprivArgs,
+} from "../agent-identity.js";
+
+const layer = { STIGMER_RUNNER_LAYER: "1" };
+
+describe("whether the runner separates", () => {
+  it("separates only as root on Linux in a container shape", () => {
+    expect(agentIdentity({ platform: "linux", uid: 0, env: layer })).toEqual({ name: "stigmer-agent", uid: AGENT_UID, gid: AGENT_GID, home: DEFAULT_AGENT_HOME });
+    expect(agentIdentity({ platform: "linux", uid: 0, env: {} }), "no layer: a local runner").toBeNull();
+    expect(agentIdentity({ platform: "linux", uid: 1000, env: layer }), "not root").toBeNull();
+    expect(agentIdentity({ platform: "darwin", uid: 0, env: layer }), "not Linux").toBeNull();
+    expect(agentIdentity({ platform: "win32", uid: undefined, env: layer }), "no uids").toBeNull();
+  });
+
+  it("homes the agent where the deployment names, else at the default", () => {
+    expect(agentIdentity({ platform: "linux", uid: 0, env: { ...layer, STIGMER_AGENT_HOME: "/data/agent" } })?.home).toBe("/data/agent");
+    expect(agentIdentity({ platform: "linux", uid: 0, env: { ...layer, STIGMER_AGENT_HOME: "  " } })?.home).toBe(DEFAULT_AGENT_HOME);
+  });
+});
+
+describe("the agent user on a base image the operator brings", () => {
+  function files(passwd: string, group: string): { readonly passwd: string; readonly group: string } {
+    const dir = mkdtempSync(join(tmpdir(), "agent-identity-"));
+    writeFileSync(join(dir, "passwd"), passwd);
+    writeFileSync(join(dir, "group"), group);
+    return { passwd: join(dir, "passwd"), group: join(dir, "group") };
+  }
+  const identity = { name: "stigmer-agent", uid: AGENT_UID, gid: AGENT_GID, home: "/home/stigmer-agent" };
+
+  it("adds the user and the group when they are missing, and only once", () => {
+    const f = files("root:x:0:0:root:/root:/bin/bash", "root:x:0:\n");
+    ensureAgentUser(identity, f);
+    ensureAgentUser(identity, f);
+    expect(readFileSync(f.passwd, "utf8")).toBe("root:x:0:0:root:/root:/bin/bash\nstigmer-agent:x:10001:10001:Stigmer agent:/home/stigmer-agent:/bin/bash\n");
+    expect(readFileSync(f.group, "utf8")).toBe("root:x:0:\nstigmer-agent:x:10001:\n");
+  });
+
+  it("refuses an agent account whose ids are not the ones the runner starts it as", () => {
+    expect(() => ensureAgentUser(identity, files("root:x:0:0::/root:/bin/sh\nstigmer-agent:x:1500:1500::/home/stigmer-agent:/bin/sh\n", "root:x:0:\nstigmer-agent:x:10001:\n"))).toThrow(
+      "gives stigmer-agent id 1500; the runner starts the agent as 10001, so the account must have that id",
+    );
+  });
+
+  it("refuses an id another account already holds", () => {
+    expect(() => ensureAgentUser(identity, files("root:x:0:0::/root:/bin/sh\nsomeone:x:10001:10001::/home/someone:/bin/sh\n", "root:x:0:\n"))).toThrow(
+      "already gives id 10001 to someone; the agent user stigmer-agent needs it for its own",
+    );
+  });
+});
+
+/** `CapEff` with SETUID, SETGID, CHOWN, KILL and DAC_OVERRIDE, as every shipped shape grants (bits 7, 6, 0, 5, 1). */
+const ALL_FOUR = "Name:\tnode\nCapEff:\t00000000000000e3\n";
+
+describe("the agent's state and the drop to it", () => {
+  const identity = { name: "stigmer-agent", uid: AGENT_UID, gid: AGENT_GID, home: "/data/agent" };
+
+  it("keeps the agent's state under its home when the runner separates, else under HOME", () => {
+    expect(agentStateHome({ platform: "linux", uid: 0, env: { ...layer, HOME: "/root", STIGMER_AGENT_HOME: "/data/agent" } })).toBe("/data/agent");
+    expect(agentStateHome({ platform: "darwin", uid: 501, env: { HOME: "/Users/me" } })).toBe("/Users/me");
+  });
+
+  it("drops with the measured flags: the agent's ids, no groups, no inheritable capabilities, no new privileges", () => {
+    expect(setprivArgs(identity)).toEqual(["--reuid=10001", "--regid=10001", "--clear-groups", "--inh-caps=-all", "--no-new-privs"]);
+  });
+
+  it("is ready only when the user, its home and a setpriv drop all work", () => {
+    const steps: string[] = [];
+    const ok = { processStatus: () => ALL_FOUR, ensureUser: () => void steps.push("user"), makeHome: () => void steps.push("home"), probe: (args: readonly string[]) => (steps.push(args.join(" ")), { status: 0, stderr: "" }) };
+    expect(prepareAgentSeparation(identity, ok)).toBeNull();
+    expect(steps).toEqual(["user", "home", "--reuid=10001 --regid=10001 --clear-groups --inh-caps=-all --no-new-privs -- true"]);
+  });
+
+  it("refuses, with its one line, on a process that is not a root runner holding the four capabilities", () => {
+    // This test's process is that: no /proc at all on macOS, no capabilities
+    // as a Linux user, so the real check refuses either way.
+    expect(prepareAgentSeparation(identity)).toMatch(/^the runner (cannot read its own capabilities|lacks the SETUID, SETGID, CHOWN, KILL, DAC_OVERRIDE capabilities) /);
+    const home = join(mkdtempSync(join(tmpdir(), "agent-home-")), "agent");
+    expect(prepareAgentSeparation({ ...identity, home }, { processStatus: () => ALL_FOUR, ensureUser: () => {} }), "no setpriv drop from here").toMatch(
+      /^the runner cannot start processes as the agent user/,
+    );
+    expect(existsSync(home), "the home is made, still root's: the handover gives it away").toBe(true);
+  });
+
+  it("refuses, with its one line, a runner that cannot read its own capabilities", () => {
+    expect(
+      prepareAgentSeparation(identity, {
+        processStatus: () => {
+          throw new Error("ENOENT: /proc/self/status");
+        },
+      }),
+    ).toMatch(/^the runner cannot read its own capabilities \(ENOENT: \/proc\/self\/status\); see /);
+  });
+
+  it("names the fix for each way it cannot drop", () => {
+    const fine = { processStatus: () => ALL_FOUR, ensureUser: () => {}, makeHome: () => {} };
+    expect(prepareAgentSeparation(identity, { ...fine, processStatus: () => "Name:\tnode\nCapEff:\t00000000000000c3\n" })).toMatch(
+      /^the runner lacks the KILL capability it needs to run the agent as its own user \(SETUID, SETGID, CHOWN, KILL and DAC_OVERRIDE\); see /,
+    );
+    expect(prepareAgentSeparation(identity, { ...fine, processStatus: () => "CapEff:\t0000000000000000\n" })).toMatch(/^the runner lacks the SETUID, SETGID, CHOWN, KILL, DAC_OVERRIDE capabilities /);
+    expect(prepareAgentSeparation(identity, { ...fine, probe: () => ({ status: null, error: new Error("spawnSync setpriv ENOENT"), stderr: "" }) })).toMatch(
+      /^the runner cannot start processes as the agent user: setpriv is missing \(spawnSync setpriv ENOENT\); add util-linux's setpriv to the base image; see /,
+    );
+    expect(prepareAgentSeparation(identity, { ...fine, probe: () => ({ status: 1, stderr: "setpriv: setresuid failed: Operation not permitted\n" }) })).toMatch(
+      /^the runner cannot start processes as the agent user \(setpriv: setresuid failed: Operation not permitted\); check the pod's or container's security settings; see /,
+    );
+    expect(
+      prepareAgentSeparation(identity, {
+        ...fine,
+        ensureUser: () => {
+          throw new Error("/etc/passwd already gives id 10001 to someone");
+        },
+      }),
+    ).toMatch(/^the runner cannot prepare the agent user stigmer-agent: \/etc\/passwd already gives id 10001 to someone; see /);
+  });
+});

package/src/shared/__tests__/agent-servers.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Pins agentServerEntry (agent-servers.ts): a server an agent writes reads
+ * as an HTTP entry with its own URL and headers and the run values those
+ * headers name; it takes `Authorization: Bearer ${<NAME>_ACCESS_TOKEN}`
+ * only when the run's values for it hold that login, so a server with none
+ * is called with no login instead of refused for an unresolved header; and
+ * a server whose headers name Authorization themselves keeps its own.
+ */
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { AgentMcpServerSchema } from "@stigmer/apis/ai/stigmer/agentic/agent/v1/spec_pb";
+
+import { agentServerEntry } from "../agent-servers.js";
+
+const ZENDESK = create(AgentMcpServerSchema, {
+  name: "zendesk",
+  url: "https://acme-co.zendesk.com/mcp",
+  headers: { "X-Api-Key": "${ZENDESK_KEY}" },
+});
+
+function headersOf(entry: ReturnType<typeof agentServerEntry>): Record<string, string> {
+  return entry.transport.case === "http" ? { ...entry.transport.value.headers } : {};
+}
+
+describe("agentServerEntry", () => {
+  it("reads as an HTTP entry naming the run values its headers read", () => {
+    const entry = agentServerEntry(ZENDESK, undefined);
+    expect(entry.name).toBe("zendesk");
+    expect(entry.transport.case === "http" ? entry.transport.value.url : "").toBe("https://acme-co.zendesk.com/mcp");
+    expect(headersOf(entry)).toEqual({ "X-Api-Key": "${ZENDESK_KEY}" });
+    expect(entry.env).toEqual(["ZENDESK_KEY"]);
+  });
+
+  it("adds the login header only when the run's values hold the login", () => {
+    expect(headersOf(agentServerEntry(ZENDESK, { ZENDESK_KEY: "k" }))).toEqual({ "X-Api-Key": "${ZENDESK_KEY}" });
+    const signedIn = agentServerEntry(ZENDESK, { ZENDESK_KEY: "k", ZENDESK_ACCESS_TOKEN: "t" });
+    expect(headersOf(signedIn)).toEqual({ "X-Api-Key": "${ZENDESK_KEY}", Authorization: "Bearer ${ZENDESK_ACCESS_TOKEN}" });
+    expect(signedIn.env).toEqual(["ZENDESK_ACCESS_TOKEN", "ZENDESK_KEY"]);
+  });
+
+  it("keeps a server's own Authorization header, whatever the values hold", () => {
+    const own = create(AgentMcpServerSchema, {
+      name: "zendesk",
+      url: "https://acme-co.zendesk.com/mcp",
+      headers: { authorization: "Bearer ${ZD_TOKEN}" },
+    });
+    expect(headersOf(agentServerEntry(own, { ZD_TOKEN: "a", ZENDESK_ACCESS_TOKEN: "t" }))).toEqual({ authorization: "Bearer ${ZD_TOKEN}" });
+  });
+
+  it("leaves the agent's server as written", () => {
+    agentServerEntry(ZENDESK, { ZENDESK_ACCESS_TOKEN: "t" });
+    expect({ ...ZENDESK.headers }).toEqual({ "X-Api-Key": "${ZENDESK_KEY}" });
+  });
+});

package/src/shared/__tests__/approval-canonicalize.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  canonicalJson,
+  canonicalToolActionJson,
+  canonicalizeToolAction,
+  type ToolActionInput,
+} from "../approval-canonicalize.js";
+
+interface Vector {
+  name: string;
+  input: ToolActionInput;
+  expected: string;
+}
+
+// Single source of truth, shared with the future Go/Java implementations.
+const vectorsPath = fileURLToPath(
+  new URL("../../../../../../apis/testdata/hitl/canonicalization/vectors.json", import.meta.url),
+);
+const corpus = JSON.parse(readFileSync(vectorsPath, "utf-8")) as { vectors: Vector[] };
+
+describe("approval canonicalization vector corpus", () => {
+  it("loads a non-trivial corpus", () => {
+    expect(corpus.vectors.length).toBeGreaterThanOrEqual(10);
+  });
+
+  for (const v of corpus.vectors) {
+    it(`vector: ${v.name}`, () => {
+      expect(canonicalToolActionJson(v.input)).toBe(v.expected);
+    });
+  }
+});
+
+describe("canonicalJson", () => {
+  it("sorts object keys by UTF-16 code unit", () => {
+    expect(canonicalJson({ b: 1, a: 2, A: 3 })).toBe('{"A":3,"a":2,"b":1}');
+  });
+
+  it("preserves array order", () => {
+    expect(canonicalJson([3, 1, 2])).toBe("[3,1,2]");
+  });
+
+  it("drops undefined-valued keys", () => {
+    expect(canonicalJson({ a: 1, b: undefined })).toBe('{"a":1}');
+  });
+
+  it("rejects non-integer numbers (outside the canonical domain)", () => {
+    expect(() => canonicalJson({ x: 1.5 })).toThrow(/non-integer/);
+  });
+
+  it("rejects non-finite numbers", () => {
+    expect(() => canonicalJson({ x: Infinity })).toThrow(/non-finite/);
+  });
+});
+
+describe("canonicalizeToolAction normalization", () => {
+  it("is idempotent (canonicalizing the canonical form is a fixed point)", () => {
+    const input: ToolActionInput = {
+      toolName: "Write",
+      paths: ["/ws/src/b.ts", "/ws/src/a.ts"],
+      workspaceRoot: "/ws",
+      args: { flag: true },
+    };
+    const once = canonicalToolActionJson(input);
+    const twice = canonicalToolActionJson(input);
+    expect(twice).toBe(once);
+  });
+
+  it("redacts secret values to a stable digest without cleartext", () => {
+    const input: ToolActionInput = {
+      toolName: "create_secret",
+      args: { name: "db", value: "super-secret-password" },
+      secretKeys: ["value"],
+    };
+    const out = canonicalizeToolAction(input);
+    const redacted = out.args.value as string;
+
+    expect(redacted).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(redacted).not.toContain("super-secret-password");
+    expect(canonicalToolActionJson(input)).not.toContain("super-secret-password");
+  });
+
+  it("redaction is stable for the same secret and distinct for different secrets", () => {
+    const base = (value: string): ToolActionInput => ({
+      toolName: "t",
+      args: { value },
+      secretKeys: ["value"],
+    });
+    const a1 = canonicalizeToolAction(base("secret-a")).args.value;
+    const a2 = canonicalizeToolAction(base("secret-a")).args.value;
+    const b = canonicalizeToolAction(base("secret-b")).args.value;
+
+    expect(a1).toBe(a2);
+    expect(a1).not.toBe(b);
+  });
+
+  it("makes a workspace-absolute path relative and normalizes separators", () => {
+    const out = canonicalizeToolAction({
+      toolName: "Write",
+      paths: ["C:\\ws\\src\\main.ts"],
+      workspaceRoot: "C:\\ws",
+    });
+    expect(out.paths).toEqual(["src/main.ts"]);
+  });
+});

package/src/shared/__tests__/approval-fingerprint.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  APPROVAL_FINGERPRINT_VERSION,
+  coarseToolIdentity,
+  computeApprovalFingerprint,
+  computeCoarseApprovalFingerprint,
+  deriveExecutionFingerprintKey,
+} from "../approval-fingerprint.js";
+import type { ToolActionInput } from "../approval-canonicalize.js";
+
+interface FingerprintVector {
+  name: string;
+  input: ToolActionInput;
+  expected: string;
+}
+
+// Single source of truth, shared byte-for-byte with the future Go/Java editions.
+const vectorsPath = fileURLToPath(
+  new URL("../../../../../../apis/testdata/hitl/fingerprint/vectors.json", import.meta.url),
+);
+const corpus = JSON.parse(readFileSync(vectorsPath, "utf-8")) as {
+  key: string;
+  full: FingerprintVector[];
+  coarse: FingerprintVector[];
+};
+
+describe("approval fingerprint vector corpus", () => {
+  it("loads a non-trivial corpus", () => {
+    expect(corpus.full.length).toBeGreaterThanOrEqual(4);
+    expect(corpus.coarse.length).toBeGreaterThanOrEqual(4);
+  });
+
+  for (const v of corpus.full) {
+    it(`full vector: ${v.name}`, () => {
+      expect(computeApprovalFingerprint(corpus.key, v.input)).toBe(v.expected);
+    });
+  }
+
+  for (const v of corpus.coarse) {
+    it(`coarse vector: ${v.name}`, () => {
+      expect(computeCoarseApprovalFingerprint(corpus.key, v.input)).toBe(v.expected);
+    });
+  }
+});
+
+describe("fingerprint invariants", () => {
+  const key = "test-key";
+
+  it("tags every fingerprint with the version", () => {
+    const fp = computeApprovalFingerprint(key, { toolName: "read" });
+    expect(fp.startsWith(`${APPROVAL_FINGERPRINT_VERSION}:`)).toBe(true);
+  });
+
+  it("is stable for the same action (an approval re-driven is the same lease)", () => {
+    const input: ToolActionInput = { toolName: "Write", paths: ["src/a.ts"], args: { contents: "x" } };
+    expect(computeApprovalFingerprint(key, input)).toBe(computeApprovalFingerprint(key, input));
+  });
+
+  it("changes when the action changes (a drifted action is re-asked, never reused)", () => {
+    const a = computeApprovalFingerprint(key, { toolName: "Write", paths: ["src/a.ts"] });
+    const b = computeApprovalFingerprint(key, { toolName: "Write", paths: ["src/b.ts"] });
+    expect(a).not.toBe(b);
+  });
+
+  it("is key-bound (a fingerprint from one key cannot satisfy another)", () => {
+    const input: ToolActionInput = { toolName: "Shell", shellCommand: "rm -rf /" };
+    expect(computeApprovalFingerprint("key-a", input)).not.toBe(computeApprovalFingerprint("key-b", input));
+  });
+});
+
+describe("coarse projection (Cursor substrate)", () => {
+  it("collapses the write/edit taxonomies onto one identity", () => {
+    // Same logical edit named in the hook taxonomy (Write) and the stream
+    // taxonomy (edit) over the same resource -> one fingerprint. This is the
+    // March-2026 failure class, prevented by construction.
+    const hookSide: ToolActionInput = { toolName: "Write", paths: ["a.txt"] };
+    const streamSide: ToolActionInput = { toolName: "edit", paths: ["a.txt"] };
+    expect(coarseToolIdentity(hookSide).tool).toBe("write");
+    expect(coarseToolIdentity(streamSide).tool).toBe("write");
+    expect(computeCoarseApprovalFingerprint("k", hookSide)).toBe(
+      computeCoarseApprovalFingerprint("k", streamSide),
+    );
+  });
+
+  it("isolates categories (approving a write never satisfies a shell)", () => {
+    const write: ToolActionInput = { toolName: "Write", paths: ["a.txt"] };
+    const shell: ToolActionInput = { toolName: "Shell", shellCommand: "a.txt" };
+    expect(computeCoarseApprovalFingerprint("k", write)).not.toBe(
+      computeCoarseApprovalFingerprint("k", shell),
+    );
+  });
+
+  it("keys MCP tools on tool name with an empty salient", () => {
+    const id = coarseToolIdentity({ toolName: "create_issue", mcpServerSlug: "GitHub" });
+    expect(id).toEqual({ tool: "create_issue", mcpServerSlug: "github", salient: "" });
+  });
+});
+
+describe("per-execution key derivation", () => {
+  it("is stable for the same execution (gateway approves and enforces across re-invocations)", () => {
+    const master = "master-secret";
+    expect(deriveExecutionFingerprintKey(master, "exec-1")).toEqual(
+      deriveExecutionFingerprintKey(master, "exec-1"),
+    );
+  });
+
+  it("isolates executions (a key from one execution cannot serve another)", () => {
+    const master = "master-secret";
+    expect(deriveExecutionFingerprintKey(master, "exec-1")).not.toEqual(
+      deriveExecutionFingerprintKey(master, "exec-2"),
+    );
+  });
+});