@foldrun/core 0.3.0 → 0.5.0

package/src/api-tools.ts

@@ -101,6 +101,14 @@ export interface ApiToolResult {
   server: ReturnType<typeof createSdkMcpServer> | null;
   /** Tool names to allow, e.g. mcp__foldrun_apis__call_google_ads. */
   toolNames: string[];
+  /** SDK tool name → the API it was built for, recorded as each tool is
+   *  made: `crm`'s operation `admin_list` is `crm_admin_list` beside an API
+   *  named `crm_admin`, so the name alone cannot say whose it is. */
+  owners: Record<string, string>;
+  /** SDK tool name → the HTTP method of a typed operation. A generic
+   *  call_<api> carries its method in each call's input instead. Read by the
+   *  browser-pod fallback (browser-pod.ts) to tell a GET from a write. */
+  methods: Record<string, string>;
   /** Secrets referenced but not set — surfaced as run warnings. */
   missingSecrets: string[];
   /** Human-readable lines describing each API, appended to the system prompt. */
@@ -318,7 +326,7 @@ export function buildApiTools(
   resolved?: { env: Record<string, string | undefined>; missing: string[] },
 ): ApiToolResult {
   if (apis.length === 0) {
-    return { server: null, toolNames: [], missingSecrets: [], promptLines: [], drainLog: () => [] };
+    return { server: null, toolNames: [], owners: {}, methods: {}, missingSecrets: [], promptLines: [], drainLog: () => [] };
   }
 
   const neededSecrets = [...new Set(apis.flatMap(secretsUsedByApi))];
@@ -337,6 +345,8 @@ export function buildApiTools(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the SDK types its own list this way
   const tools: SdkMcpToolDefinition<any>[] = [];
   const toolNames: string[] = [];
+  const owners: Record<string, string> = {};
+  const methods: Record<string, string> = {};
   const promptLines: string[] = [];
 
   for (const api of apis) {
@@ -344,18 +354,34 @@ export function buildApiTools(
     // this process. Two steps on two workers each get their own.
     const bucket = api.rate ? new TokenBucket(api.rate.count, api.rate.perSec) : null;
     const ops = api.resolvedOperations ?? [];
-    // An explicit `operations:` list means "only these": no escape hatch.
-    const withGeneric = !(api.operations && ops.length);
+    // An explicit `operations:` list means "only these": no escape hatch,
+    // ever. It fails closed. If the document did not load, or yielded none of
+    // the listed operations, the API gets no tools this run rather than the
+    // generic one: an allowlist that opens when a vendor renames an
+    // operation or a URL moves is not an allowlist.
+    const allowlisted = !!api.operations?.length;
+    const withGeneric = !allowlisted;
+    if (allowlisted && !ops.length) {
+      promptLines.push(
+        `- **${api.name}** — unavailable this run: its \`operations:\` allowlist resolved no operations, ` +
+          `so no tool is exposed. Report it as blocked; do not reach this API another way.`,
+      );
+      continue;
+    }
 
     const typedNames: string[] = [];
     for (const op of ops) {
       tools.push(typedTool(api, op, env, bucket, log));
       typedNames.push(typedToolName(api.name, op.id));
+      methods[`mcp__foldrun_apis__${typedToolName(api.name, op.id)}`] = String(op.method ?? "").toUpperCase();
     }
     if (withGeneric) tools.push(genericTool(api, env, bucket, log));
 
     const names = [...typedNames, ...(withGeneric ? [`call_${api.name}`] : [])];
-    toolNames.push(...names.map((n) => `mcp__foldrun_apis__${n}`));
+    for (const n of names) {
+      toolNames.push(`mcp__foldrun_apis__${n}`);
+      owners[`mcp__foldrun_apis__${n}`] = api.name;
+    }
 
     const rateLine = api.rate ? ` Rate limit ${api.rate.count}/${Math.round(api.rate.count / api.rate.perSec)}s — over it, calls wait.` : "";
     if (ops.length) {
@@ -382,6 +408,8 @@ export function buildApiTools(
   return {
     server,
     toolNames,
+    owners,
+    methods,
     missingSecrets: missing,
     promptLines,
     drainLog: () => log.splice(0, log.length),

package/src/approvals.ts

@@ -10,8 +10,10 @@
 // at a desk. So the decision lives in core and the routes only say who made
 // it.
 
-import { readRun, writeRun, type RunRecord } from "./store.ts";
+import crypto from "node:crypto";
+import { readRun, writeRun, readFlow, mayApprove, type FlowInfo, type RunRecord } from "./store.ts";
 import { platform } from "./platform.ts";
+import { approveToken, installKey } from "./webhook.ts";
 
 export interface ApprovalDecision {
   decision: "approve" | "reject";
@@ -23,6 +25,174 @@ export interface ApprovalDecision {
   step?: number;
   /** Who decided, as it reads after the verb: "by a human", "via emailed link". */
   by: string;
+  /**
+   * The person behind the decision, when a session made it: their email and
+   * the role they hold. A link and an external event have neither, and are
+   * checked by their token instead — the token IS the authority there.
+   *
+   * Two rules read this. `approvers:` in the flow file names who may decide
+   * that flow's gates at all. And nobody approves a run they started
+   * themselves: a gate exists so that a second person looks, and a flow a
+   * person kicked off and then waved through is a gate that never happened.
+   */
+  actor?: { email?: string | null; role?: string | null } | null;
+  /**
+   * The emailed link's token, when a link is deciding. Read here rather
+   * than trusted from the route, because what a link may decide is policy:
+   * the step it was minted for, before it expires, once, and never a gate
+   * whose flow names its approvers unless the link was minted for one of
+   * them. See readApproveLink.
+   */
+  link?: string;
+}
+
+// ----------------------------------------------------------------- links
+
+/** How long an emailed link decides for when the flow does not say. */
+export const APPROVE_LINK_DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** What a link may decide: one step, until a moment, as somebody or as
+ *  nobody. A `run` link is the older kind — bound to the run alone, and
+ *  kept working, once, for runs that were already waiting when this
+ *  changed. */
+export type ApproveLink =
+  | { kind: "step"; step: number; expiresAt: string; approver: string | null }
+  | { kind: "run" };
+
+/** The link's lifetime: the flow's `approve_within:` when it has one —
+ *  after that the gate has expired on its own — else a week. */
+export function approveLinkTtlMs(flow: Pick<FlowInfo, "approveWithin"> | null | undefined): number {
+  return flow?.approveWithin ? flow.approveWithin * 1000 : APPROVE_LINK_DEFAULT_TTL_MS;
+}
+
+const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64url");
+const unb64 = (s: string) => Buffer.from(s, "base64url").toString("utf8");
+
+function signLink(tenant: string, workspace: string, runId: string, step: number, expires: number, approver: string): string {
+  return crypto
+    .createHmac("sha256", installKey())
+    .update(`approve-link:${tenant}/${workspace}/${runId}/${step}/${expires}/${approver}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * The token an emailed link carries. Bound to one step of one run and to
+ * a moment, and — when the notification went to a named approver — to
+ * that person, so the link decides as them. A link that was only bound
+ * to the run approved every later gate of that run for as long as it ran,
+ * and a forwarded one let anyone past `approvers:`.
+ *
+ * `step.expires.approver.signature`; the signature covers all of it plus
+ * the run's identity, under the install key, so rotating the key kills
+ * every link at once, the way it kills every hook.
+ */
+export function approveLinkToken(
+  tenant: string,
+  workspace: string,
+  runId: string,
+  link: { step: number; expiresAt: number; approver?: string | null },
+): string {
+  const approver = (link.approver ?? "").trim().toLowerCase();
+  const expires = Math.floor(link.expiresAt);
+  return `${link.step}.${expires}.${approver ? b64(approver) : "-"}.${signLink(tenant, workspace, runId, link.step, expires, approver)}`;
+}
+
+/** The path an emailed link opens — absolute when the caller prefixes the
+ *  install's public origin. `decision=reject` pre-selects; a GET never
+ *  decides. */
+export function approveLinkPath(
+  tenant: string,
+  workspace: string,
+  runId: string,
+  link: { step: number; expiresAt: number; approver?: string | null },
+): string {
+  return `/api/approve/${tenant}/${workspace}/${runId}?token=${approveLinkToken(tenant, workspace, runId, link)}`;
+}
+
+const same = (a: string, b: string) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+
+/**
+ * What a presented token is, or why it is nothing. 401 for a token that
+ * was never minted for this run, 410 for one that was and has expired —
+ * the second deserves a sentence, because the person holding it did
+ * nothing wrong.
+ */
+export function readApproveLink(
+  tenant: string,
+  workspace: string,
+  runId: string,
+  presented: string,
+  now = Date.now(),
+): { link: ApproveLink } | { error: string; status: 401 | 410 } {
+  const invalid = { error: "invalid token", status: 401 as const };
+  if (!presented) return invalid;
+  const parts = presented.split(".");
+  if (parts.length === 4) {
+    const [stepText, expText, approverText, sig] = parts;
+    if (!/^\d+$/.test(stepText) || !/^\d+$/.test(expText)) return invalid;
+    let approver = "";
+    try {
+      approver = approverText === "-" ? "" : unb64(approverText);
+    } catch {
+      return invalid;
+    }
+    const step = Number(stepText);
+    const expires = Number(expText);
+    if (!same(sig, signLink(tenant, workspace, runId, step, expires, approver))) return invalid;
+    if (now >= expires) return { error: "this link has expired — open the run in the dashboard to decide it", status: 410 };
+    return { link: { kind: "step", step, expiresAt: new Date(expires).toISOString(), approver: approver || null } };
+  }
+  if (same(presented, approveToken(tenant, workspace, runId))) return { link: { kind: "run" } };
+  return invalid;
+}
+
+/** A used link is written on the run as a digest, never the token. */
+const linkDigest = (token: string) => crypto.createHash("sha256").update(token).digest("hex").slice(0, 24);
+
+/**
+ * Everything a link has to pass before it decides anything, answered the
+ * same way for the page that shows the gate and the POST that decides it.
+ * Returns which waiting steps the link may decide and who it decides as.
+ */
+export function checkApproveLink(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+  presented: string,
+  now = Date.now(),
+): { ok: true; link: ApproveLink; steps: number[]; approver: string | null } | { ok: false; status: number; message: string } {
+  const read = readApproveLink(tenant, workspace, run.id, presented, now);
+  if ("error" in read) return { ok: false, status: read.status, message: read.error };
+  const { link } = read;
+  if (run.approvalLinksUsed?.includes(linkDigest(presented))) {
+    return { ok: false, status: 409, message: "this link was already used — a link decides once" };
+  }
+  // The older, run-bound link: kept for runs already waiting, but not for
+  // longer than a new link would have been.
+  if (link.kind === "run") {
+    const since = Date.parse(run.parkedAt ?? run.startedAt);
+    if (Number.isFinite(since) && now - since > APPROVE_LINK_DEFAULT_TTL_MS) {
+      return { ok: false, status: 410, message: "this link has expired — open the run in the dashboard to decide it" };
+    }
+  }
+  const waiting = run.steps
+    .map((s, i) => ({ s, i }))
+    .filter(({ s, i }) => s.status === "awaiting-approval" && s.waitFor !== "event" && (link.kind === "run" || i === link.step))
+    .map(({ i }) => i);
+  const approver = link.kind === "step" ? link.approver : null;
+  // A flow that names its approvers is asking for a person; a link is a
+  // possession. Only a link minted for one of the named approvers carries
+  // enough of an identity to be checked against the list.
+  const flow = readFlow(tenant, workspace, run.flow);
+  if (flow?.approvers?.length && !approver) {
+    return {
+      ok: false,
+      status: 403,
+      message: `this flow names who may approve it (${flow.approvers.join(", ")}), and an emailed link carries no identity — sign in to the dashboard to decide it`,
+    };
+  }
+  return { ok: true, link, steps: waiting, approver };
 }
 
 /** An error the HTTP layer can map straight to a status — see errorResponse. */
@@ -52,9 +222,19 @@ export async function decideApproval(
   const run = readRun(tenant, workspace, runId);
   if (!run) throw new ApprovalError("run not found", 404);
 
+  // A link decides what it was minted for, as whom it was minted for.
+  let allowed: number[] | null = null;
+  if (d.link !== undefined) {
+    const check = checkApproveLink(tenant, workspace, run, d.link);
+    if (!check.ok) throw new ApprovalError(check.message, check.status);
+    allowed = check.steps;
+    d = { ...d, actor: check.approver ? { email: check.approver, role: null } : null };
+  }
+  assertMayDecide(tenant, workspace, run, d);
+
   const waiting = run.steps
     .map((s, i) => ({ s, i }))
-    .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i));
+    .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i) && (allowed === null || allowed.includes(i)));
   if (waiting.length === 0) throw new ApprovalError("nothing is awaiting approval", 409);
 
   const note = typeof d.note === "string" ? d.note.trim() : "";
@@ -83,6 +263,16 @@ export async function decideApproval(
           : `rejected ${d.by}${reason ? `: ${reason.slice(0, 200)}` : ""}`,
     });
   }
+  // The deadline belonged to the gate that just closed. Leaving it on the
+  // record would hand a later gate in the same run a deadline that has
+  // already passed.
+  if (run.steps.every((s) => s.status !== "awaiting-approval")) run.approveBy = null;
+  // A link decides once. Written as a digest on the record, so a step that
+  // parks again — a loop, a rerun from the gate — is not decided by the
+  // same forwarded mail.
+  if (d.link !== undefined) {
+    run.approvalLinksUsed = [...(run.approvalLinksUsed ?? []), linkDigest(d.link)].slice(-50);
+  }
   writeRun(tenant, workspace, run);
 
   // A parked run has no process polling for this decision — the worker
@@ -96,6 +286,67 @@ export async function decideApproval(
   return { run, steps: waiting.map(({ i }) => i) };
 }
 
+/**
+ * The two rules a person's decision has to pass. A token-bearing door — the
+ * emailed link, an external event — carries no actor and is not checked
+ * here: possession of a token derived from the run is its own authority,
+ * and the link was mailed to whoever the account told us to ask.
+ *
+ * Throws 403, which the routes surface verbatim: a refusal that does not say
+ * which rule refused sends someone to the wrong settings page.
+ */
+function assertMayDecide(tenant: string, workspace: string, run: RunRecord, d: ApprovalDecision): void {
+  if (!d.actor) return;
+  const email = (d.actor.email ?? "").trim().toLowerCase();
+  // Rejecting your own run is always allowed: stopping something you started
+  // needs no second opinion, and the gate's whole purpose is that it does
+  // not proceed. Only approval needs someone else.
+  if (d.decision === "approve" && email && run.startedBy && run.startedBy === email) {
+    throw new ApprovalError(
+      "you started this run — an approval gate asks a second person, so someone else has to answer it",
+      403,
+    );
+  }
+  const flow = readFlow(tenant, workspace, run.flow);
+  if (!mayApprove(flow, d.actor)) {
+    throw new ApprovalError(
+      `this flow's approvers: list does not include you (${flow?.approvers?.join(", ")})`,
+      403,
+    );
+  }
+}
+
+/**
+ * A gate that ran out of time. `approve_within:` in the flow file stamps a
+ * deadline when the run parks; past it, the gate is rejected and the run
+ * fails, exactly as if a person had said no.
+ *
+ * Rejection, not approval, is the only safe way for a clock to answer a
+ * question a person was asked. The whole reason the step is parked is that
+ * someone wanted to look at it first.
+ *
+ * Returns whether it acted. Called from the same sweep that closes abandoned
+ * runs, so an expiry needs nothing running of its own.
+ */
+export async function expireStaleGate(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+  now = Date.now(),
+): Promise<boolean> {
+  if (run.status !== "awaiting-approval" || !run.approveBy) return false;
+  if (now < new Date(run.approveBy).getTime()) return false;
+  // A step waiting on `wait: event` is not waiting on a person and is not
+  // this deadline's business.
+  if (!run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event")) return false;
+  await decideApproval(tenant, workspace, run.id, {
+    decision: "reject",
+    by: "automatically — nobody answered in time",
+    reason: `no decision within the flow's approve_within: (due ${run.approveBy})`,
+  });
+  return true;
+}
+
 /**
  * Release a run parked on `wait: event` with what arrived. The payload is
  * stored on the step — not as an approval note, which is a person's