@piagent/platform 1.1.9 → 1.2.1

package/packages/piagent-core/mcp/mcp-approval-store.js

@@ -0,0 +1,216 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { stableJson } from "../capabilities/capability-core.js";
+
+// Approval for MCP servers that arrive inside a repository.
+//
+// A repository can carry `.mcp.json` and `.pi/mcp.json`. Cloning one and opening
+// a session should not hand its author a process on this machine with this
+// operator's credentials, so a server found in those files is not usable until
+// somebody here says so.
+//
+// The record lives in the operator's home, never in the repository. That is the
+// whole point: a repository that could approve its own servers has not been
+// gated. It also means a fork, a rename, or a second checkout starts unapproved
+// rather than inheriting a decision made about different code.
+//
+// What is stored is the digest of the entry that was approved. Approval is
+// consent to what the server runs, so a changed command, URL or argument list is
+// a new question — the same split the capability lock draws between what a
+// project consented to and which build produced it.
+
+const STORE_FILE = "piagent-mcp-approvals.json";
+const MAX_STORE_BYTES = 256 * 1024;
+const SCHEMA_VERSION = 1;
+
+/** @param {{home?: string}} [options] @returns {string|undefined} */
+export function approvalStorePath(options = {}) {
+  const base = options.home ?? os.homedir();
+  if (typeof base !== "string" || base.length === 0) return undefined;
+  return path.join(base, ".pi", STORE_FILE);
+}
+
+/**
+ * The digest of a server entry, over the definition only. Two projects that
+ * declare the same server produce the same digest, which is fine: the store is
+ * keyed by project as well, so approving one does not approve the other.
+ *
+ * This is a content identifier, not a credential hash, and SHA-256 is the right
+ * primitive for it. The question it answers is "is this the same definition the
+ * operator approved", so it has to be fast, unsalted and stable across runs —
+ * every property a password hash is deliberately built to lack. Nothing is ever
+ * verified against it, and no secret reaches it: `add` refuses to write a
+ * credential value into MCP config and takes a `${VAR}` reference instead, so
+ * what gets hashed is a command line, a URL, variable names, and an OAuth client
+ * id and scope list, all of which are public identifiers.
+ *
+ * @param {unknown} entry
+ * @returns {string}
+ */
+export function serverEntryDigest(entry) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(entry)).digest("hex")}`;
+}
+
+/**
+ * A project is identified by its resolved path. Resolved, because a checkout
+ * reached through a symlink is the same checkout, and because macOS reaches
+ * `/var` that way.
+ * @param {string} projectPath
+ * @returns {string}
+ */
+export function projectKey(projectPath) {
+  try {
+    return fs.realpathSync(projectPath);
+  } catch {
+    return path.resolve(projectPath);
+  }
+}
+
+/**
+ * The store, and whether the empty case means "nothing decided" or "nobody could
+ * read it". Both read as pending, which is the right answer for a gate and the
+ * wrong one for a write: overwriting a store this process could not parse throws
+ * away every decision recorded in it, and the operator's only clue would be that
+ * their other projects silently returned to pending.
+ *
+ * @param {{home?: string}} [options]
+ * @returns {{projects: Record<string, Record<string, {digest?: string, decision?: string, decidedAt?: string}>>, readable: boolean, detail?: string}}
+ */
+export function loadApprovalStore(options = {}) {
+  const file = approvalStorePath(options);
+  if (!file) return { projects: {}, readable: false, detail: "no home directory to read an approval store from" };
+  let raw;
+  try {
+    // A store larger than this is not something this code wrote.
+    if (fs.statSync(file).size > MAX_STORE_BYTES) {
+      return { projects: {}, readable: false, detail: `${file} is larger than ${MAX_STORE_BYTES} bytes` };
+    }
+    raw = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    // Absent is the ordinary state before the first decision.
+    if (error && typeof error === "object" && error.code === "ENOENT") return { projects: {}, readable: true };
+    return { projects: {}, readable: false, detail: `cannot read ${file}` };
+  }
+  let document;
+  try {
+    document = JSON.parse(raw);
+  } catch (error) {
+    return { projects: {}, readable: false, detail: `cannot parse ${file}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const projects = document?.projects;
+  if (projects === undefined && document && typeof document === "object" && !Array.isArray(document)) {
+    // A document with no `projects` key is a store this code did not write.
+    return { projects: {}, readable: false, detail: `${file} has no projects object` };
+  }
+  if (!projects || typeof projects !== "object" || Array.isArray(projects)) {
+    return { projects: {}, readable: false, detail: `${file} has no projects object` };
+  }
+  return { projects, readable: true };
+}
+
+/** @param {{home?: string}} [options] @returns {Record<string, Record<string, {digest?: string, decision?: string, decidedAt?: string}>>} */
+export function readApprovalStore(options = {}) {
+  // An unreadable store denies rather than permits: every server reads as
+  // undecided, which is the state that blocks.
+  return loadApprovalStore(options).projects;
+}
+
+/**
+ * @param {Record<string, unknown>} projects
+ * @param {{home?: string}} [options]
+ * @returns {boolean}
+ */
+export function writeApprovalStore(projects, options = {}) {
+  const file = approvalStorePath(options);
+  if (!file) return false;
+  const document = { schemaVersion: SCHEMA_VERSION, projects };
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {"approved"|"rejected"|"pending"|"changed"} ApprovalState
+ */
+
+/**
+ * What the operator has decided about this server as it is defined right now.
+ *
+ * `changed` is separated from `pending` on purpose. They both block, but they are
+ * different events: one is a server nobody has looked at, the other is a server
+ * that was approved and is no longer what was approved. Collapsing them would
+ * hide the second, which is the one worth reading.
+ *
+ * @param {{projectPath: string, name: string, entry: unknown, store?: Record<string, unknown>, home?: string}} options
+ * @returns {{state: ApprovalState, digest: string, approvedDigest?: string}}
+ */
+export function approvalState(options) {
+  const store = options.store ?? readApprovalStore({ home: options.home });
+  const digest = serverEntryDigest(options.entry);
+  const record = /** @type {Record<string, {digest?: string, decision?: string}>|undefined} */ (
+    store[projectKey(options.projectPath)]
+  )?.[options.name];
+  if (!record || typeof record.decision !== "string") return { state: "pending", digest };
+  if (record.decision === "rejected") return { state: "rejected", digest, approvedDigest: record.digest };
+  if (record.decision !== "approved") return { state: "pending", digest };
+  if (record.digest !== digest) return { state: "changed", digest, approvedDigest: record.digest };
+  return { state: "approved", digest, approvedDigest: record.digest };
+}
+
+/**
+ * @param {{projectPath: string, name: string, entry: unknown, decision: "approved"|"rejected", now?: number, home?: string}} options
+ * @returns {boolean}
+ */
+export function recordApproval(options) {
+  const loaded = loadApprovalStore({ home: options.home });
+  // Writing on top of a store nobody could parse would drop every decision it
+  // holds -- including the ones for other projects, which the operator would
+  // find out about only by watching them go back to pending one at a time.
+  if (!loaded.readable) return false;
+  const store = loaded.projects;
+  const key = projectKey(options.projectPath);
+  const project = { ...(store[key] ?? {}) };
+  project[options.name] = {
+    decision: options.decision,
+    digest: serverEntryDigest(options.entry),
+    decidedAt: new Date(options.now ?? Date.now()).toISOString()
+  };
+  return writeApprovalStore({ ...store, [key]: project }, { home: options.home });
+}
+
+/**
+ * Drop a decision so the server returns to pending. Used by `piagent-mcp reset`
+ * and when a server is removed, so a later server reusing the name does not
+ * inherit the decision — the digest check would catch it, but leaving a record
+ * for a server that no longer exists is just debris.
+ * @param {{projectPath: string, name?: string, home?: string}} options
+ * @returns {boolean}
+ */
+export function clearApproval(options) {
+  const loaded = loadApprovalStore({ home: options.home });
+  if (!loaded.readable) return false;
+  const store = loaded.projects;
+  const key = projectKey(options.projectPath);
+  // Nothing recorded is the state this function exists to reach, so it succeeds.
+  // Returning false here would be indistinguishable from a failed write, and the
+  // caller has to be able to tell those apart.
+  if (!store[key]) return true;
+  if (!options.name) {
+    const { [key]: _removed, ...rest } = store;
+    return writeApprovalStore(rest, { home: options.home });
+  }
+  const { [options.name]: _dropped, ...project } = store[key];
+  const next = Object.keys(project).length > 0 ? { ...store, [key]: project } : (() => {
+    const { [key]: _empty, ...rest } = store;
+    return rest;
+  })();
+  return writeApprovalStore(next, { home: options.home });
+}

package/packages/piagent-core/mcp/mcp-auth-readiness.js

@@ -0,0 +1,225 @@
+import fs from "node:fs";
+import path from "node:path";
+import { REPOSITORY_SCOPES } from "./mcp-config-layers.js";
+import { approvalState } from "./mcp-approval-store.js";
+import { CATALOG_OPTIONAL_ENV } from "./mcp-server-catalog.js";
+
+// Whether a configured server can actually be used, answered from state this
+// process already has. No network, no child process: this runs at session start,
+// and a check that costs a round trip would be paid on every session for
+// information that changes when somebody edits a config.
+//
+// The line it will not cross is guessing. Two things are knowable here — an
+// environment variable a config references is set or it is not, an executable is
+// on PATH or it is not — and those are reported. Whether an OAuth sign-in is
+// still valid is known to Pi and not to this file, so it is reported as
+// "sign-in is handled elsewhere" rather than as a failure that may not be one.
+
+const ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/**
+ * @typedef {"disabled"|"rejected"|"approval-changed"|"pending-approval"|"needs-command"|"needs-env"|"oauth"|"ready"} ReadinessState
+ */
+
+/**
+ * States that mean the server will not answer a tool call. `oauth` is not one of
+ * them: it may well be signed in already.
+ * @type {Set<ReadinessState>}
+ */
+export const BLOCKING_STATES = new Set([
+  "disabled", "rejected", "approval-changed", "pending-approval", "needs-command", "needs-env"
+]);
+
+/**
+ * Every `${VAR}` a server entry references, wherever it appears.
+ * @param {unknown} entry
+ * @returns {string[]}
+ */
+export function referencedEnvVars(entry) {
+  const names = new Set();
+  walk(entry, (text) => {
+    for (const match of text.matchAll(ENV_REFERENCE)) names.add(match[1]);
+  });
+  // `bearerTokenEnvVar` names its variable directly instead of through a
+  // `${VAR}` reference, which is the entire point of the field: the token must
+  // not appear in the config. The walk above only recognises the reference form,
+  // so without this the one server setting that guarantees a credential is
+  // needed was the one setting that never produced a needs-env.
+  if (typeof entry?.bearerTokenEnvVar === "string" && entry.bearerTokenEnvVar.trim()) {
+    names.add(entry.bearerTokenEnvVar.trim());
+  }
+  return [...names].sort();
+}
+
+/** @param {unknown} value @param {(text: string) => void} visit @returns {void} */
+function walk(value, visit) {
+  if (typeof value === "string") {
+    visit(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) walk(item, visit);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) walk(item, visit);
+  }
+}
+
+/**
+ * @param {string} command
+ * @param {{env?: Record<string, string|undefined>}} [options]
+ * @returns {boolean}
+ */
+export function commandOnPath(command, options = {}) {
+  const env = options.env ?? process.env;
+  if (typeof command !== "string" || command.length === 0) return false;
+  // An explicit path is checked where it points rather than searched for.
+  if (command.includes(path.sep)) return isExecutable(command);
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!directory) continue;
+    if (isExecutable(path.join(directory, command))) return true;
+  }
+  return false;
+}
+
+/** @param {string} file @returns {boolean} */
+function isExecutable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {object} ServerReadiness
+ * @property {string} name
+ * @property {string} scope
+ * @property {ReadinessState} state
+ * @property {string} detail human-readable, never contains a value
+ * @property {string} [remedy] the command that resolves it
+ * @property {string[]} missingEnv
+ */
+
+/**
+ * The import kind a server arrived through, or undefined when the layer named
+ * it directly.
+ * @param {{origin?: string}} server
+ * @returns {string|undefined}
+ */
+function importedFrom(server) {
+  return server.origin?.startsWith("import:") ? server.origin.slice("import:".length) : undefined;
+}
+
+/**
+ * @param {{name: string, scope: string, entry: Record<string, unknown>, requiresApproval?: boolean, origin?: string}} server
+ * @param {{projectPath: string, env?: Record<string, string|undefined>, home?: string, store?: Record<string, unknown>}} options
+ * @returns {ServerReadiness}
+ */
+export function evaluateServerReadiness(server, options) {
+  const env = options.env ?? process.env;
+  const base = { name: server.name, scope: server.scope, missingEnv: /** @type {string[]} */ ([]) };
+
+  if (server.entry.enabled === false) {
+    return { ...base, state: "disabled", detail: "disabled in config", remedy: `piagent-mcp enable ${server.name} --scope ${server.scope}` };
+  }
+
+  // `collectServers` decides this, because the scope a server is listed under
+  // is not the same question as who put it there: a `global` config importing
+  // a repository-relative kind reads its definitions out of the clone. Falling
+  // back to scope keeps a caller that builds a server record by hand working.
+  const needsApproval = server.requiresApproval ?? REPOSITORY_SCOPES.has(server.scope);
+  if (needsApproval) {
+    const approval = approvalState({
+      projectPath: options.projectPath,
+      name: server.name,
+      entry: server.entry,
+      store: options.store,
+      home: options.home
+    });
+    if (approval.state === "rejected") {
+      return { ...base, state: "rejected", detail: "rejected for this project", remedy: `piagent-mcp approve ${server.name}` };
+    }
+    if (approval.state === "changed") {
+      return {
+        ...base,
+        state: "approval-changed",
+        detail: "definition changed since it was approved",
+        remedy: `piagent-mcp get ${server.name} then piagent-mcp approve ${server.name}`
+      };
+    }
+    if (approval.state === "pending") {
+      return {
+        ...base,
+        state: "pending-approval",
+        // Naming the scope alone reads as a lie for an imported server: the
+        // scope is where the `imports` key sits, and the definition is in a
+        // different file entirely. Say which of the two it was.
+        detail: importedFrom(server)
+          ? `imported from ${importedFrom(server)} config by the ${server.scope} layer, and not approved here`
+          : `defined by this repository in ${server.scope} scope and not approved here`,
+        remedy: `piagent-mcp approve ${server.name}`
+      };
+    }
+  }
+
+  if (typeof server.entry.command === "string" && !commandOnPath(server.entry.command, { env })) {
+    return {
+      ...base,
+      state: "needs-command",
+      detail: `${server.entry.command} is not on PATH`,
+      remedy: `install ${server.entry.command}, or edit the server with piagent-mcp add ${server.name} --scope ${server.scope} -- <command>`
+    };
+  }
+
+  const optional = new Set(CATALOG_OPTIONAL_ENV[server.name] ?? []);
+  const missingEnv = referencedEnvVars(server.entry)
+    .filter((name) => !optional.has(name))
+    .filter((name) => !env[name]?.trim());
+  if (missingEnv.length > 0) {
+    return {
+      ...base,
+      missingEnv,
+      state: "needs-env",
+      detail: `${missingEnv.join(", ")} ${missingEnv.length === 1 ? "is" : "are"} referenced but not set`,
+      remedy: `export ${missingEnv[0]}=... in your shell profile`
+    };
+  }
+
+  if (server.entry.auth === "oauth") {
+    return {
+      ...base,
+      state: "oauth",
+      detail: "signs in with OAuth; Pi holds the session",
+      remedy: `/mcp-auth ${server.name} inside Pi if it is not signed in`
+    };
+  }
+
+  return { ...base, state: "ready", detail: "ready" };
+}
+
+/**
+ * One line for the session start, or nothing when every server is usable.
+ *
+ * Only definite problems are named. A server waiting on OAuth is left out
+ * because this process cannot tell a signed-in one from a signed-out one, and a
+ * notice that appears every session regardless of state stops being read.
+ *
+ * @param {ServerReadiness[]} readiness
+ * @returns {string|undefined}
+ */
+export function readinessNotice(readiness) {
+  const blocked = readiness.filter((item) => BLOCKING_STATES.has(item.state));
+  if (blocked.length === 0) return undefined;
+  const waiting = blocked.filter((item) => item.state === "pending-approval" || item.state === "approval-changed");
+  const parts = blocked.slice(0, 4).map((item) => `${item.name} (${item.detail})`);
+  const overflow = blocked.length > parts.length ? `, and ${blocked.length - parts.length} more` : "";
+  const lead = waiting.length > 0
+    ? "MCP servers need a decision or setup"
+    : "MCP servers are configured but cannot connect";
+  // This line is only ever printed at session start, so it names the command
+  // that answers it from there rather than sending the reader to a shell.
+  return `${lead}: ${parts.join("; ")}${overflow}. Run \`/piagent-mcp doctor\` for what each one needs.`;
+}