@akanjs/devkit 3.1.1 → 3.1.2-rc.0

package/codeAgent/agent/CodeAgentGate.ts

@@ -1,28 +1,72 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { CodeAgentProfile } from "akanjs/common";
+import { akanCodePaths } from "./akanCodePaths";
+import { codeAgentHostListed, codeAgentHostOf, codeAgentIsLoopback } from "./codeAgentHosts";
 import { stringArg } from "./stringArg";
 
 const writeTools = new Set(["write", "edit"]);
 const commandTools = new Set(["bash"]);
+// A client in command position (after a separator, `sh -c '`, `-exec`), past `VAR=value` and wrappers like `timeout 5`.
+// Gaps are spaces and tabs only: a newline is itself a separator, and letting `\s` take it too backtracks polynomially.
+const networkClients =
+  /(?:^[ \t]*|[\n;&|(`{][ \t]*|\s-\w*c\s+['"][ \t]*|\s-exec(?:dir)?\s+)(?:(?:[A-Za-z_]\w*=\S*|sudo|env|command|exec|nohup|time|timeout|nice|watch|stdbuf|xargs|-\S+|\d\S*)[ \t]+)*(?:[^\s;&|()`'"]*\/)?(curl|wget|nc|ncat|netcat|socat|telnet|ssh|scp|sftp|rsync|ftp)(?=$|[\s;&|)`'"])/g;
+const urlPattern = /\b[a-z][a-z0-9+.-]*:\/\/[^\s'"`<>|;&()]+/gi;
+// curl and wget read a `host:port` argument without a scheme as http.
+const hostPortPattern = /(?<=^|[\s'"=])(?:\[[0-9a-f:.]+\]|[a-z0-9.-]+):\d{1,5}(?=[/?#\s'"]|$)/gi;
+// A glob in a command that also matches these names is a broad sweep (`*.ts`), not an aim at one secret file.
+const ordinaryNames = ["index.ts", "a.ts", "a.tsx", "a.js", "a.json", "a.yaml", "a.md", "a.txt", "a.log", "README"];
 
 export interface GateVerdict {
   /** `undefined` means the call may run without asking. */
   block?: string;
   approval?: string;
+  /** Refused, not run, when nobody can be asked: the call would leave the machine. */
+  strict?: boolean;
+}
+
+interface NameRule {
+  glob: Bun.Glob;
+  samples: string[];
 }
 
 // Gated here, not in the engine's file-ops port: a throw there reads to the model as a tool bug, and it retries.
 export class CodeAgentGate {
   readonly #profile: CodeAgentProfile;
+  readonly #realRoot: string;
   readonly #deny: Bun.Glob[];
   readonly #allow: Bun.Glob[];
   readonly #deniedFragments: string[];
+  readonly #nameRules: NameRule[];
 
   constructor(profile: CodeAgentProfile) {
     this.#profile = profile;
-    this.#deny = (profile.paths.deny ?? []).map((pattern) => new Bun.Glob(pattern));
+    this.#realRoot = CodeAgentGate.#real(path.resolve(profile.paths.root));
+    const home = homedir();
+    const codeHome = path.resolve(akanCodePaths.globalDir());
+    const patterns = [
+      ...(profile.paths.deny ?? []).map((pattern) =>
+        pattern.startsWith("~/") ? path.join(home, pattern.slice(2)) : pattern,
+      ),
+      ...(profile.paths.deny?.length ? [`${codeHome}/**`] : []),
+    ];
+    this.#deny = patterns.map((pattern) => new Bun.Glob(pattern));
     this.#allow = (profile.paths.allow ?? []).map((pattern) => new Bun.Glob(pattern));
-    this.#deniedFragments = [...new Set((profile.paths.deny ?? []).map(CodeAgentGate.#fragmentOf).filter(Boolean))];
+    this.#deniedFragments = [
+      ...new Set(
+        (profile.paths.deny ?? [])
+          .flatMap(CodeAgentGate.#expandBraces)
+          .flatMap((pattern) => CodeAgentGate.#fragmentsOf(pattern, home)),
+      ),
+    ].filter(Boolean);
+    this.#nameRules = (profile.paths.deny ?? []).flatMap((pattern) => {
+      const name = /^\*\*\/([^/]+)$/.exec(pattern)?.[1];
+      if (!name || name === "**") return [];
+      const samples = CodeAgentGate.#expandBraces(name).map((entry) => entry.replace(/[*?]/g, "x"));
+      return [{ glob: new Bun.Glob(name), samples }];
+    });
   }
 
   verdict(toolName: string, args: unknown): GateVerdict {
@@ -36,6 +80,8 @@ export class CodeAgentGate {
       const denied = this.#deniedCommandReason(command);
       if (denied) return { block: denied };
     }
+    const network = this.#networkApproval(toolName, args);
+    if (network) return { approval: network, strict: true };
     if (!this.#needsApproval(toolName)) return {};
     return { approval: CodeAgentGate.#summarize(toolName, args) };
   }
@@ -43,23 +89,67 @@ export class CodeAgentGate {
   // A speed bump, not a boundary: a shell reaches any path; the real boundary is the `pod` profile's container.
   // It stops the obvious accident (`cat .env`) from persisting a live key into the transcript.
   #deniedCommandReason(command: string) {
-    const hit = this.#deniedFragments.find((fragment) => command.includes(fragment));
+    const hit =
+      this.#deniedFragments.find((fragment) => command.includes(fragment)) ??
+      CodeAgentGate.#wordsOf(command).find((word) => this.#namesDeniedFile(word));
     if (!hit) return undefined;
     return `The command names "${hit}", which the profile's deny list covers. Ask the user for the value instead of reading the file.`;
   }
 
+  #namesDeniedFile(word: string) {
+    const expanded = CodeAgentGate.#expandHome(word);
+    const name = path.basename(expanded);
+    if (/[*?[{]/.test(name)) {
+      const swept = new Bun.Glob(name);
+      if (ordinaryNames.some((ordinary) => swept.match(ordinary))) return false;
+      return this.#nameRules.some((rule) => rule.samples.some((sample) => swept.match(sample)));
+    }
+    const absolute = path.resolve(this.#profile.paths.root, expanded);
+    return this.#deny.some((glob) => glob.match(expanded) || glob.match(absolute));
+  }
+
   #deniedReason(target: string) {
-    const absolute = path.isAbsolute(target) ? target : path.resolve(this.#profile.paths.root, target);
-    const relative = path.relative(this.#profile.paths.root, absolute);
-    if (relative.startsWith("..") || path.isAbsolute(relative))
+    const absolute = path.resolve(this.#profile.paths.root, CodeAgentGate.#expandPath(target));
+    const relative = path.relative(path.resolve(this.#profile.paths.root), absolute);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
       return `Path is outside the agent root (${this.#profile.paths.root}).`;
-    if (this.#deny.some((glob) => glob.match(absolute) || glob.match(relative)))
+    // The deny list also judges the real path, so a link inside the root cannot lend a denied file an innocent name;
+    // the root is judged as written, since a linked package or lib leads out of it on purpose.
+    const real = CodeAgentGate.#real(absolute);
+    const candidates = [
+      [absolute, relative],
+      [real, path.relative(this.#realRoot, real)],
+    ];
+    if (candidates.some(([candidate, rel]) => this.#deny.some((glob) => glob.match(candidate) || glob.match(rel))))
       return "Path is on the profile's deny list (secrets and environment files are never readable).";
     if (this.#allow.length && !this.#allow.some((glob) => glob.match(absolute) || glob.match(relative)))
       return "Path is outside the profile's allow list.";
     return undefined;
   }
 
+  #networkApproval(toolName: string, args: unknown) {
+    const quiet = this.#profile.network.askOutside;
+    if (!quiet) return undefined;
+    if (toolName === "web_fetch") {
+      const url = stringArg(args, "url");
+      const host = url ? codeAgentHostOf(url) : undefined;
+      if (!host || codeAgentIsLoopback(host) || codeAgentHostListed(host, quiet)) return undefined;
+      return `fetch ${url}`;
+    }
+    const command = stringArg(args, "command");
+    if (!command || !commandTools.has(toolName)) return undefined;
+    const clients = [...command.matchAll(networkClients)].map((match) => match[1]);
+    if (!clients.length) return undefined;
+    // Only loopback is exempt here: a listed host still takes an upload under someone else's account.
+    const hosts = [
+      ...[...command.matchAll(urlPattern)].map((match) => codeAgentHostOf(match[0])),
+      ...[...command.matchAll(hostPortPattern)].map((match) => codeAgentHostOf(`http://${match[0]}`)),
+    ];
+    const httpOnly = clients.every((client) => client === "curl" || client === "wget");
+    if (httpOnly && hosts.length && hosts.every((host) => host && codeAgentIsLoopback(host))) return undefined;
+    return `reach the network: ${command.slice(0, 200)}`;
+  }
+
   #needsApproval(toolName: string) {
     switch (this.#profile.approval) {
       case "never":
@@ -75,13 +165,69 @@ export class CodeAgentGate {
     }
   }
 
+  // The engine's own path reading: `@` is stripped, `~` and `file://` expand, odd spaces become plain ones.
+  static #expandPath(target: string) {
+    const value = target.replace(/[  -   　]/g, " ").replace(/^@/, "");
+    if (/^file:\/\//.test(value)) {
+      try {
+        return fileURLToPath(value);
+      } catch {
+        return value;
+      }
+    }
+    return CodeAgentGate.#expandHome(value);
+  }
+
+  static #expandHome(value: string) {
+    const home = /^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/.exec(value);
+    return home ? path.join(homedir(), value.slice(home[0].length)) : value;
+  }
+
+  static #real(absolute: string) {
+    const rest: string[] = [];
+    let head = absolute;
+    for (;;) {
+      try {
+        return path.join(realpathSync(head), ...rest);
+      } catch {
+        const parent = path.dirname(head);
+        if (parent === head) return absolute;
+        rest.unshift(path.basename(head));
+        head = parent;
+      }
+    }
+  }
+
+  static #wordsOf(command: string) {
+    return command.split(/[\s;&|<>()`'"=,@]+/).filter(Boolean);
+  }
+
+  static #expandBraces(pattern: string): string[] {
+    const open = pattern.indexOf("{");
+    const close = open >= 0 ? pattern.indexOf("}", open) : -1;
+    if (close < 0) return [pattern];
+    const head = pattern.slice(0, open);
+    const tail = pattern.slice(close + 1);
+    return pattern
+      .slice(open + 1, close)
+      .split(",")
+      .flatMap((choice) => CodeAgentGate.#expandBraces(`${head}${choice}${tail}`));
+  }
+
   // A glob cannot match a shell line, so a deny pattern is reduced to a literal; a mid-pattern wildcard is dropped.
-  static #fragmentOf(pattern: string) {
+  static #fragmentsOf(pattern: string, home: string) {
+    if (pattern.startsWith("~/")) {
+      const rest = pattern.slice(2).replace(/\/\*\*$/, "");
+      return rest.includes("*")
+        ? []
+        : ["~/", "$HOME/", "$" + "{HOME}/", `${home}/`].map((prefix) => `${prefix}${rest}`);
+    }
     const trimmed = pattern
       .replace(/^\*\*\//, "")
       .replace(/\/\*\*$/, "/")
-      .replace(/^\*+/, "");
-    return trimmed.includes("*") ? "" : trimmed;
+      .replace(/^\*+/, "")
+      .replace(/\*+$/, "");
+    return trimmed.includes("*") ? [] : [trimmed];
   }
 
   static #summarize(toolName: string, args: unknown) {

package/codeAgent/agent/CodeAgentProxy.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type CodeAgentProfile, trimTrailingSlashes } from "akanjs/common";
+import { AkanCodeEnv } from "./AkanCodeEnv";
 import { akanCodeDefaultModel } from "./akanCodeModel";
 
 interface PreparedRequest {
@@ -36,17 +37,17 @@ export class CodeAgentProxy {
   }
 
   static fromEnv(profile?: CodeAgentProfile): CodeAgentProxy | null {
-    const baseUrl = process.env.AKAN_CODE_PROXY_URL?.trim() || profile?.network.proxyBaseUrl;
+    const baseUrl = AkanCodeEnv.get("AKAN_CODE_PROXY_URL")?.trim() || profile?.network.proxyBaseUrl;
     if (!baseUrl) return null;
-    const providers = (process.env.AKAN_CODE_PROXY_PROVIDERS ?? akanCodeDefaultModel.provider)
+    const providers = (AkanCodeEnv.get("AKAN_CODE_PROXY_PROVIDERS") ?? akanCodeDefaultModel.provider)
       .split(",")
       .map((provider) => provider.trim())
       .filter(Boolean);
     return new CodeAgentProxy({
       baseUrl,
       providers,
-      tokenFile: process.env.AKAN_CODE_PROXY_TOKEN_FILE?.trim() || undefined,
-      token: process.env.AKAN_CODE_PROXY_TOKEN?.trim() || undefined,
+      tokenFile: AkanCodeEnv.get("AKAN_CODE_PROXY_TOKEN_FILE")?.trim() || undefined,
+      token: AkanCodeEnv.get("AKAN_CODE_PROXY_TOKEN")?.trim() || undefined,
     });
   }
 

package/codeAgent/agent/CodeAgentRpcHost.ts

@@ -55,6 +55,9 @@ export class CodeAgentRpcHost {
     } catch {
       return this.#emit({ type: "error", message: "malformed command frame", fatal: false, seq: -1 });
     }
+    // A client that always opens with its token still connects where none is asked for.
+    if (request && typeof request === "object" && "auth" in request && !request.command)
+      return this.#reply({ type: "reply", id: "auth", ok: true });
     try {
       this.#reply({ type: "reply", id: request.id, ok: true, data: await this.#run(request.command) });
     } catch (error) {

package/codeAgent/agent/CodeAgentRpcListener.ts

@@ -1,40 +1,67 @@
-import { existsSync, rmSync } from "node:fs";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, rmSync } from "node:fs";
 import type { Socket, SocketListener } from "bun";
 import type { CodeAgentRpcHost } from "./CodeAgentRpcHost";
+import { codeAgentIsLoopback } from "./codeAgentHosts";
 
 export type CodeAgentRpcAddress = { unix: string } | { hostname: string; port: number };
 
+export interface CodeAgentRpcListenerOptions {
+  token?: string | null;
+}
+
 interface ClientState {
   pending: Buffer | null;
   decoder: TextDecoder;
+  admitted: boolean;
+  preface: string;
+  timer: ReturnType<typeof setTimeout> | null;
 }
 
 // One client at a time: a reconnecting control plane replaces a socket that has not timed out yet.
-// TCP binds 127.0.0.1 unless a host is named, because the wire has no authentication of its own.
+// A connection is a client only once its first line authenticates: until then it cannot displace the current one.
 export class CodeAgentRpcListener {
+  static readonly prefaceLimit = 4_096;
+  static readonly prefaceMs = 5_000;
   readonly #host: CodeAgentRpcHost;
   readonly #address: CodeAgentRpcAddress;
+  readonly #token: string | null;
   #listener: SocketListener<ClientState> | null = null;
   #client: Socket<ClientState> | null = null;
 
-  constructor(host: CodeAgentRpcHost, address: CodeAgentRpcAddress) {
+  constructor(host: CodeAgentRpcHost, address: CodeAgentRpcAddress, options: CodeAgentRpcListenerOptions = {}) {
     this.#host = host;
     this.#address = address;
+    this.#token =
+      options.token !== undefined ? options.token : "unix" in address ? null : CodeAgentRpcListener.newToken();
+  }
+
+  static newToken() {
+    return randomBytes(32).toString("base64url");
   }
 
-  static parse(spec: string): CodeAgentRpcAddress {
+  static parse(spec: string, { anyHost = false }: { anyHost?: boolean } = {}): CodeAgentRpcAddress {
     if (spec.startsWith("unix:")) return { unix: spec.slice("unix:".length) };
     const rest = spec.startsWith("tcp:") ? spec.slice("tcp:".length) : spec;
     const separator = rest.lastIndexOf(":");
-    const hostname = separator >= 0 ? rest.slice(0, separator) : "127.0.0.1";
+    const hostname = (separator >= 0 ? rest.slice(0, separator) : "") || "127.0.0.1";
     const port = Number(separator >= 0 ? rest.slice(separator + 1) : rest);
     if (!Number.isInteger(port) || port < 0 || port > 65_535)
       throw new Error(`--rpc-listen takes unix:<path> or tcp:[host:]<port>, not "${spec}"`);
-    return { hostname: hostname || "127.0.0.1", port };
+    if (!anyHost && !codeAgentIsLoopback(hostname))
+      throw new Error(
+        `--rpc-listen ${spec} would be reachable from other machines. Bind 127.0.0.1, or pass --rpc-bind-any to mean it.`,
+      );
+    return { hostname, port };
+  }
+
+  get port(): number | null {
+    const port = this.#listener && "port" in this.#listener ? this.#listener.port : null;
+    return typeof port === "number" ? port : null;
   }
 
-  get port() {
-    return this.#listener && "port" in this.#listener ? this.#listener.port : null;
+  get token() {
+    return this.#token;
   }
 
   listen() {
@@ -46,10 +73,17 @@ export class CodeAgentRpcListener {
       close: (client: Socket<ClientState>) => this.#close(client),
       error: (client: Socket<ClientState>) => this.#close(client),
     };
-    this.#listener =
-      "unix" in this.#address
-        ? Bun.listen<ClientState>({ unix: this.#address.unix, socket })
-        : Bun.listen<ClientState>({ hostname: this.#address.hostname, port: this.#address.port, socket });
+    if ("unix" in this.#address) {
+      // Created owner-only, so no other user can connect in the moment before the chmod.
+      const umask = process.umask(0o177);
+      try {
+        this.#listener = Bun.listen<ClientState>({ unix: this.#address.unix, socket });
+      } finally {
+        process.umask(umask);
+      }
+      chmodSync(this.#address.unix, 0o600);
+    } else
+      this.#listener = Bun.listen<ClientState>({ hostname: this.#address.hostname, port: this.#address.port, socket });
     this.#host.start();
     return this;
   }
@@ -70,16 +104,67 @@ export class CodeAgentRpcListener {
   }
 
   #open(client: Socket<ClientState>) {
-    client.data = { pending: null, decoder: new TextDecoder() };
+    client.data = { pending: null, decoder: new TextDecoder(), admitted: false, preface: "", timer: null };
+    client.data.timer = setTimeout(() => {
+      if (!client.data.admitted) client.end();
+    }, CodeAgentRpcListener.prefaceMs);
+  }
+
+  #data(client: Socket<ClientState>, data: Buffer) {
+    const text = client.data.decoder.decode(data, { stream: true });
+    if (client.data.admitted) {
+      if (client === this.#client) void this.#host.feed(text);
+      return;
+    }
+    client.data.preface += text;
+    const preface = client.data.preface.trimStart();
+    // A browser or any other protocol speaks first with something other than a JSON frame.
+    if (preface && !preface.startsWith("{")) {
+      client.end();
+      return;
+    }
+    if (!this.#token) {
+      this.#admit(client);
+      return void this.#host.feed(preface);
+    }
+    const newline = preface.indexOf("\n");
+    if (newline < 0) {
+      if (preface.length > CodeAgentRpcListener.prefaceLimit) client.end();
+      return;
+    }
+    if (!this.#authenticates(preface.slice(0, newline))) {
+      client.write(`${JSON.stringify({ type: "reply", id: "auth", ok: false, error: "unauthorized" })}\n`);
+      client.end();
+      return;
+    }
+    this.#admit(client);
+    this.#write(client, `${JSON.stringify({ type: "reply", id: "auth", ok: true })}\n`);
+    const rest = preface.slice(newline + 1);
+    if (rest) void this.#host.feed(rest);
+  }
+
+  #admit(client: Socket<ClientState>) {
+    if (client.data.timer) clearTimeout(client.data.timer);
+    client.data.timer = null;
+    client.data.admitted = true;
+    client.data.preface = "";
     const previous = this.#client;
     this.#client = client;
     previous?.end();
     this.#host.attach((line) => this.#write(client, line));
   }
 
-  #data(client: Socket<ClientState>, data: Buffer) {
-    if (client !== this.#client) return;
-    void this.#host.feed(client.data.decoder.decode(data, { stream: true }));
+  #authenticates(line: string) {
+    if (!this.#token) return true;
+    let auth: unknown;
+    try {
+      auth = (JSON.parse(line) as { auth?: unknown }).auth;
+    } catch {
+      return false;
+    }
+    if (typeof auth !== "string") return false;
+    const digest = (value: string) => createHash("sha256").update(value).digest();
+    return timingSafeEqual(digest(auth), digest(this.#token));
   }
 
   //* A socket write may take only part of a frame; the rest waits for `drain`, and frames behind it queue in order.
@@ -102,6 +187,7 @@ export class CodeAgentRpcListener {
   }
 
   #close(client: Socket<ClientState>) {
+    if (client.data?.timer) clearTimeout(client.data.timer);
     if (client !== this.#client) return;
     this.#client = null;
     this.#host.attach(null);

package/codeAgent/agent/WorkspaceTrust.ts

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { McpServerConfig } from "../tools/McpServerConfig";
+import { akanCodePaths } from "./akanCodePaths";
+
+export type WorkspaceTrustKind = "mcp" | "extensions";
+
+export interface WorkspaceTrustItem {
+  kind: WorkspaceTrustKind;
+  lines: string[];
+  hash: string;
+}
+
+type TrustRecord = Partial<Record<WorkspaceTrustKind, string>>;
+
+interface ExtensionWalk {
+  root: string;
+  files: { name: string; path: string }[];
+  bytes: number;
+  seen: Set<string>;
+  unchecked?: string;
+}
+
+const maxExtensionFiles = 10_000;
+const maxExtensionBytes = 64 * 1024 * 1024;
+
+// A repo's mcp.json starts processes and its extensions/ load as code, so each waits for a yes to its exact content.
+export class WorkspaceTrust {
+  static readonly #granted = new Map<string, string>();
+
+  static items(workspaceRoot: string, kinds: WorkspaceTrustKind[] = ["mcp", "extensions"]) {
+    return kinds
+      .map((kind) => WorkspaceTrust.#itemOf(workspaceRoot, kind))
+      .filter((item): item is WorkspaceTrustItem => !!item);
+  }
+
+  static pending(workspaceRoot: string, kinds?: WorkspaceTrustKind[]) {
+    return WorkspaceTrust.items(workspaceRoot, kinds).filter((item) => !WorkspaceTrust.#approved(workspaceRoot, item));
+  }
+
+  static isTrusted(workspaceRoot: string, kind: WorkspaceTrustKind) {
+    const item = WorkspaceTrust.#itemOf(workspaceRoot, kind);
+    return !item || WorkspaceTrust.#approved(workspaceRoot, item);
+  }
+
+  static approve(workspaceRoot: string, items: WorkspaceTrustItem[], remember: boolean) {
+    const key = WorkspaceTrust.#keyOf(workspaceRoot);
+    for (const item of items) WorkspaceTrust.#granted.set(`${key}\n${item.kind}`, item.hash);
+    const checked = items.filter((item) => item.hash);
+    if (!remember || !checked.length) return;
+    const all = WorkspaceTrust.#read();
+    const record: TrustRecord = { ...all[key] };
+    for (const item of checked) record[item.kind] = item.hash;
+    WorkspaceTrust.#write({ ...all, [key]: record });
+  }
+
+  static carry<T>(workspaceRoot: string, kind: WorkspaceTrustKind, edit: () => T): T {
+    const before = WorkspaceTrust.#itemOf(workspaceRoot, kind);
+    const trusted = !before || WorkspaceTrust.#approved(workspaceRoot, before);
+    const remembered = !before || WorkspaceTrust.#read()[WorkspaceTrust.#keyOf(workspaceRoot)]?.[kind] === before.hash;
+    const result = edit();
+    const after = WorkspaceTrust.#itemOf(workspaceRoot, kind);
+    if (trusted && after) WorkspaceTrust.approve(workspaceRoot, [after], remembered);
+    return result;
+  }
+
+  static #approved(workspaceRoot: string, item: WorkspaceTrustItem) {
+    const key = WorkspaceTrust.#keyOf(workspaceRoot);
+    return (
+      WorkspaceTrust.#granted.get(`${key}\n${item.kind}`) === item.hash ||
+      (!!item.hash && WorkspaceTrust.#read()[key]?.[item.kind] === item.hash)
+    );
+  }
+
+  static #itemOf(workspaceRoot: string, kind: WorkspaceTrustKind): WorkspaceTrustItem | undefined {
+    return kind === "mcp" ? WorkspaceTrust.#mcp(workspaceRoot) : WorkspaceTrust.#extensions(workspaceRoot);
+  }
+
+  static #mcp(workspaceRoot: string): WorkspaceTrustItem | undefined {
+    const servers = McpServerConfig.read(workspaceRoot, ["workspace"]).sort((a, b) => a.name.localeCompare(b.name));
+    if (!servers.length) return undefined;
+    return {
+      kind: "mcp",
+      lines: servers.map((ref) => `${ref.name}: ${McpServerConfig.targetOf(ref)}`),
+      hash: WorkspaceTrust.#digest(WorkspaceTrust.#canonical(servers)),
+    };
+  }
+
+  //? An item without a hash could not be checked: the trust file never keeps it, so it is asked about at every start.
+  static #extensions(workspaceRoot: string): WorkspaceTrustItem | undefined {
+    const dir = akanCodePaths.extensionsDir(workspaceRoot);
+    let root: string;
+    try {
+      root = realpathSync(dir);
+    } catch {
+      return undefined;
+    }
+    const walk: ExtensionWalk = { root, files: [], bytes: 0, seen: new Set() };
+    WorkspaceTrust.#walk(walk, dir, "");
+    const lines = walk.files.map((file) => file.name);
+    if (walk.unchecked) return { kind: "extensions", lines: [walk.unchecked, ...lines], hash: "" };
+    if (!walk.files.length) return undefined;
+    const hash = createHash("sha256");
+    for (const file of walk.files) hash.update(`${file.name}\0${WorkspaceTrust.#digest(readFileSync(file.path))}\n`);
+    return { kind: "extensions", lines, hash: hash.digest("hex") };
+  }
+
+  // Links are followed while they stay in the folder, since the engine follows them too.
+  static #walk(walk: ExtensionWalk, dir: string, prefix: string) {
+    let entries: string[];
+    try {
+      const real = realpathSync(dir);
+      if (walk.seen.has(real)) return;
+      walk.seen.add(real);
+      entries = readdirSync(dir)
+        .filter((entry) => entry !== ".git")
+        .sort();
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (walk.unchecked) return;
+      const full = path.join(dir, entry);
+      const name = prefix ? `${prefix}/${entry}` : entry;
+      try {
+        if (lstatSync(full).isSymbolicLink() && !WorkspaceTrust.#inside(walk.root, realpathSync(full))) {
+          walk.unchecked = `${name} links out of the folder: it cannot be checked, so it is asked about at every start`;
+          return;
+        }
+        const stat = statSync(full);
+        if (stat.isDirectory()) WorkspaceTrust.#walk(walk, full, name);
+        else if (stat.isFile()) {
+          walk.files.push({ name, path: full });
+          walk.bytes += stat.size;
+          if (walk.files.length > maxExtensionFiles || walk.bytes > maxExtensionBytes)
+            walk.unchecked = `more than ${maxExtensionFiles} files or ${maxExtensionBytes >> 20} MiB: too many to check, so asked about at every start`;
+        }
+      } catch {}
+    }
+  }
+
+  static #inside(root: string, real: string) {
+    const relative = path.relative(root, real);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+  }
+
+  static #keyOf(workspaceRoot: string) {
+    try {
+      return realpathSync(workspaceRoot);
+    } catch {
+      return path.resolve(workspaceRoot);
+    }
+  }
+
+  static #digest(content: string | Buffer) {
+    return createHash("sha256").update(content).digest("hex");
+  }
+
+  static #canonical(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map((entry) => WorkspaceTrust.#canonical(entry)).join(",")}]`;
+    if (value && typeof value === "object")
+      return `{${Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${WorkspaceTrust.#canonical(entry)}`)
+        .join(",")}}`;
+    return JSON.stringify(value);
+  }
+
+  static #read(): Record<string, TrustRecord> {
+    const file = akanCodePaths.trustFile();
+    if (!existsSync(file)) return {};
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as { workspaces?: Record<string, TrustRecord> };
+      return parsed.workspaces ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  static #write(workspaces: Record<string, TrustRecord>) {
+    akanCodePaths.ensureGlobalDir();
+    const file = akanCodePaths.trustFile();
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ workspaces }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    chmodSync(file, 0o600);
+  }
+}

package/codeAgent/agent/akanCodePaths.ts

@@ -1,6 +1,8 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { FileSys } from "../../fileSys";
+import { AkanCodeEnv } from "./AkanCodeEnv";
 
 // Two candidates: the CLI bundle flattens entry chunks into the package root, where `skills/` is a sibling.
 const builtinSkillsDir = () => {
@@ -9,7 +11,9 @@ const builtinSkillsDir = () => {
 };
 
 // One override for the whole set, so a `models.json` and the `auth.json` it names never drift apart.
-const globalDir = () => process.env.AKAN_CODE_HOME ?? path.join(homedir(), ".akan", "code");
+const globalDir = () => AkanCodeEnv.get("AKAN_CODE_HOME") ?? path.join(homedir(), ".akan", "code");
+
+const ensureGlobalDir = () => FileSys.ensurePrivateDir(globalDir());
 
 // Credentials live under the home directory, never the repo: a repo is what gets committed, zipped and shared.
 export const akanCodePaths = {
@@ -24,8 +28,11 @@ export const akanCodePaths = {
   globalMcpFile: () => path.join(globalDir(), "mcp.json"),
   globalSkillsDir: () => path.join(globalDir(), "skills"),
   globalDir,
+  ensureGlobalDir,
   authFile: () => path.join(globalDir(), "auth.json"),
   /** MCP bearer tokens, beside the provider keys and for the same reason: never in a directory that is shared. */
   mcpAuthFile: () => path.join(globalDir(), "mcpAuth.json"),
   modelsFile: () => path.join(globalDir(), "models.json"),
+  trustFile: () => path.join(globalDir(), "trust.json"),
+  rpcTokenFile: (port: number) => path.join(globalDir(), "rpc", `${port}.token`),
 } as const;