@foldrun/core 0.2.0

package/src/deploy.ts

@@ -0,0 +1,458 @@
+// Deploying a workspace from a directory — the git-push half of the platform.
+//
+// A workspace is markdown, so there is nothing to build. Deploy is "make the
+// files on disk match the commit", which is a copy plus two things a copy
+// cannot do on its own:
+//
+//   1. Check first. Everything here is declarative, so the whole workspace can
+//      be validated before any of it is live — a broken flow is caught at push
+//      time rather than at 3am when its schedule fires. A platform deploying
+//      compiled code cannot do this cheaply. We can, and it is the reason to
+//      route deploys through here instead of writing files directly.
+//
+//   2. Refuse at the wrong moment. Swapping files under a running flow means
+//      step 3 reads agents that step 1 never saw.
+//
+// What a deploy must NOT touch is already settled by saveWorkspace: runs/,
+// state/, secrets.json, and any memory an agent wrote that the push doesn't
+// mention. Those are the platform's, not git's. This module decides whether a
+// deploy happens at all; saveWorkspace decides what survives it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  saveWorkspace,
+  workspaceDir,
+  listRuns,
+  parseFlow,
+  WORKSPACE_DIRS,
+  assertSafeName,
+  type DeployFile,
+} from "./store.ts";
+import { conformanceIssues } from "./okf.ts";
+import { repoDir } from "./gitrepo.ts";
+
+/** Directories a deploy never reads out of a source tree. */
+const NOT_SOURCE = new Set([".git", "node_modules", "runs", "outputs", ".foldrun", ".results"]);
+
+/** Files that are never part of a workspace, whatever directory they sit in. */
+const NOT_SOURCE_FILE = new Set([".DS_Store", "secrets.json"]);
+
+const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);
+
+export interface DeployIssue {
+  where: string;
+  message: string;
+}
+
+export interface DeployPlan {
+  files: DeployFile[];
+  /** Paths present now that the push does not ship — they will be removed. */
+  removed: string[];
+  added: string[];
+  updated: string[];
+  /** Empty when the deploy is safe to apply. */
+  issues: DeployIssue[];
+  /** Set when a run is in flight, which blocks the swap. */
+  blockedBy: string[];
+}
+
+export interface DeployResult extends DeployPlan {
+  applied: boolean;
+  /** The commit this workspace is now running, when the caller knows it. */
+  commit: string | null;
+  preserved: number;
+}
+
+/**
+ * Read a directory into the file list a deploy ships.
+ *
+ * Only what a workspace is made of: AGENTS.md and the tracked directories.
+ * Everything else in the repo — a README, .github/, a package.json — is
+ * skipped rather than rejected, because a workspace living in a repo alongside
+ * other things is the normal case, not an error.
+ */
+// Where single-file subagents authored by other tools are found, in
+// precedence order: the vendor-neutral cross-client location first, then any
+// tool-specific one for pragmatic compatibility. Extend the tail, never the
+// head. Shared by the deploy import (readTree) and the CLI checker so the two
+// agree on what counts as an agent.
+export const SUBAGENT_IMPORT_DIRS = [".agents/agents", ".claude/agents"] as const;
+
+export function readTree(dir: string): DeployFile[] {
+  const root = path.resolve(dir);
+  const out: DeployFile[] = [];
+
+  const walk = (abs: string, rel: string) => {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(abs).sort();
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (NOT_SOURCE.has(entry) || NOT_SOURCE_FILE.has(entry)) continue;
+      const full = path.join(abs, entry);
+      const next = rel ? `${rel}/${entry}` : entry;
+      // Never follow a link out of the tree — the same rule the file listing
+      // uses, for the same reason.
+      let stat: fs.Stats;
+      try {
+        if (fs.lstatSync(full).isSymbolicLink()) continue;
+        stat = fs.statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(full, next);
+      } else if (next === "AGENTS.md" || next === "project.md" || IN_WORKSPACE_DIR.test(next)) {
+        out.push({ path: next, content: fs.readFileSync(full, "utf8") });
+      }
+    }
+  };
+
+  walk(root, "");
+
+  // Bridge single-file subagents authored by ANY coding tool into the folder
+  // shape the runtime expects. The cross-client, vendor-neutral location is
+  // `.agents/agents/<name>.md` — the same `.agents/` root as `.agents/skills/`
+  // — and it is scanned first. A tool's own location (only `.claude/agents/`
+  // so far, as the one that ships single-file subagents) is scanned after, for
+  // pragmatic compatibility; add another vendor here when one appears, never
+  // ahead of the neutral location. A subagent's frontmatter — name,
+  // description, tools, model, effort, skills, mcpServers, disallowedTools — is
+  // already what a foldrun agent reads, so each maps to agents/<name>/agent.md
+  // with its content unchanged. A native agents/<name>/agent.md always wins,
+  // and the neutral location wins over a vendor one; the import only fills a
+  // gap, so authoring elsewhere and deploying here needs no rewrite. Unknown
+  // vendor-only keys (permissionMode, hooks, …) are ignored, as every other
+  // frontmatter reader here ignores what it does not use.
+  const nativeAgent = new Set(
+    out.filter((fEntry) => /^agents\/[^/]+\/agent\.md$/.test(fEntry.path)).map((fEntry) => fEntry.path),
+  );
+  for (const importDir of SUBAGENT_IMPORT_DIRS) {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(path.join(root, importDir)).sort();
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+      const name = entry.replace(/\.md$/, "");
+      const target = `agents/${name}/agent.md`;
+      // Native wins; and .claude/agents beats .agents/agents on a name clash
+      // (it is scanned first and this skips a path already imported).
+      if (nativeAgent.has(target) || out.some((fEntry) => fEntry.path === target)) continue;
+      const full = path.join(root, importDir, entry);
+      try {
+        if (fs.lstatSync(full).isSymbolicLink()) continue;
+        out.push({ path: target, content: fs.readFileSync(full, "utf8") });
+      } catch {
+        // an unreadable import is skipped, not fatal
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Everything wrong with an incoming workspace, before any of it is live.
+ *
+ * Deliberately the same questions `foldrun check` asks, against files that are
+ * not on disk yet. A deploy that would leave the workspace failing its own
+ * checker should not be a deploy.
+ */
+export function deployIssues(files: DeployFile[]): DeployIssue[] {
+  const issues: DeployIssue[] = [];
+  const at = (where: string, message: string) => issues.push({ where, message });
+
+  if (files.length === 0) at("/", "nothing to deploy — no workspace files in this tree");
+  if (files.length > 500) at("/", `${files.length} files — a workspace is capped at 500`);
+
+  // Path safety, as questions rather than exceptions: a push should report
+  // everything wrong with it at once, not fail on the first bad path.
+  for (const f of files) {
+    const norm = path.normalize(f.path);
+    if (norm.startsWith("..") || path.isAbsolute(norm) || norm.startsWith("runs")) {
+      at(f.path, "illegal path");
+    }
+    const base = norm.split("/").pop() ?? norm;
+    for (const want of ["AGENTS.md", "SKILL.md"]) {
+      if (base !== want && base.toLowerCase() === want.toLowerCase()) {
+        at(f.path, `must be spelled exactly "${want}" — the case is part of the standard`);
+      }
+    }
+  }
+
+  const agents = new Set<string>();
+  for (const f of files) {
+    const m = f.path.match(/^agents\/([^/]+)\/agent\.md$/);
+    if (m) agents.add(m[1]);
+  }
+  if (agents.size === 0) {
+    at("agents/", "no agents — a workspace needs at least one agents/<name>/agent.md");
+  }
+
+  // Flows, parsed from the incoming text rather than from disk. A step naming
+  // an agent that this push does not ship is the single most common way a
+  // deploy breaks a schedule, and it is free to catch here.
+  const flows = files.filter((f) => /^flows\/[^/]+\.md$/.test(f.path));
+  const flowNames = new Set<string>();
+  for (const f of flows) {
+    try {
+      flowNames.add(parseFlow(path.basename(f.path), f.content).name);
+    } catch {
+      // reported below, when it is parsed for real
+    }
+  }
+  for (const f of flows) {
+    let parsed;
+    try {
+      parsed = parseFlow(path.basename(f.path), f.content);
+    } catch (err) {
+      at(f.path, err instanceof Error ? err.message : String(err));
+      continue;
+    }
+    if (parsed.steps.length === 0) at(f.path, "no steps");
+    for (const s of parsed.steps) {
+      const target = s.subflow ?? s.agent;
+      const known = s.subflow ? flowNames.has(target) : agents.has(target);
+      if (!known) {
+        at(
+          `${f.path}${s.line ? `:${s.line}` : ""}`,
+          `[[${s.subflow ? "flow:" : ""}${target}]] does not exist in this deploy`,
+        );
+      }
+    }
+  }
+
+  // OKF conformance, which needs the files as a tree. Staged in a temp
+  // directory and thrown away — nothing touches the live workspace until every
+  // check above has passed.
+  const staged = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+  try {
+    for (const f of files) {
+      const norm = path.normalize(f.path);
+      if (norm.startsWith("..") || path.isAbsolute(norm)) continue;
+      const target = path.join(staged, norm);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, f.content);
+    }
+    for (const bundle of ["memory", "knowledge"]) {
+      for (const { file, issue } of conformanceIssues(path.join(staged, bundle))) {
+        at(`${bundle}/${file}`, issue);
+      }
+    }
+    for (const agent of agents) {
+      for (const bundle of ["memory", "knowledge"]) {
+        const dir = path.join(staged, "agents", agent, bundle);
+        for (const { file, issue } of conformanceIssues(dir)) {
+          at(`agents/${agent}/${bundle}/${file}`, issue);
+        }
+      }
+    }
+  } finally {
+    fs.rmSync(staged, { recursive: true, force: true });
+  }
+
+  return issues;
+}
+
+/**
+ * Runs that make this a bad moment to swap the files under them.
+ *
+ * A flow reads its agents step by step. Replacing them mid-run means step 3
+ * runs against a definition step 1 never saw, and the trace becomes a record
+ * of two different workspaces. A run waiting on a person counts too: they are
+ * about to approve work that the deploy would silently redefine.
+ */
+export function runsInFlight(tenant: string, workspace: string): string[] {
+  if (!fs.existsSync(workspaceDir(tenant, workspace))) return [];
+  return listRuns(tenant, workspace)
+    .filter((r) => r.status === "queued" || r.status === "running" || r.status === "awaiting-approval")
+    .map((r) => r.id);
+}
+
+/** What a deploy would do, without doing it. */
+export function planDeploy(tenant: string, workspace: string, files: DeployFile[]): DeployPlan {
+  const dir = workspaceDir(tenant, workspace);
+  const shipped = new Map(files.map((f) => [path.normalize(f.path), f.content]));
+
+  const present = new Set<string>();
+  if (fs.existsSync(dir)) {
+    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+      const rel = String(entry).split(path.sep).join("/");
+      if (NOT_SOURCE.has(rel.split("/")[0])) continue;
+      if (/(^|\/)(runs|outputs|\.results)\//.test(rel)) continue;
+      if (rel === "secrets.json") continue;
+      try {
+        if (!fs.statSync(path.join(dir, rel)).isFile()) continue;
+      } catch {
+        continue;
+      }
+      present.add(rel);
+    }
+  }
+
+  const added: string[] = [];
+  const updated: string[] = [];
+  for (const [rel, content] of shipped) {
+    if (!present.has(rel)) {
+      added.push(rel);
+      continue;
+    }
+    try {
+      if (fs.readFileSync(path.join(dir, rel), "utf8") !== content) updated.push(rel);
+    } catch {
+      updated.push(rel);
+    }
+  }
+
+  // What saveWorkspace will keep regardless — reporting these as removals
+  // would be a lie, and the alarming kind.
+  const kept = (rel: string) =>
+    /(^|\/)state\//.test(rel) || /(^|\/)memory\/[^/]+\.md$/.test(rel);
+  const removed = [...present].filter((rel) => !shipped.has(rel) && !kept(rel));
+
+  return {
+    files,
+    added: added.sort(),
+    updated: updated.sort(),
+    removed: removed.sort(),
+    issues: deployIssues(files),
+    blockedBy: runsInFlight(tenant, workspace),
+  };
+}
+
+export interface DeployOptions {
+  /** The commit these files came from, recorded so the dashboard can show it. */
+  commit?: string | null;
+  /** Attribution for the revision this deploy records. */
+  by?: string;
+  message?: string;
+  /** Apply even while runs are in flight. */
+  force?: boolean;
+}
+
+/**
+ * Deploy a file list to a workspace, if it checks out.
+ *
+ * Returns the plan either way, with `applied` saying whether anything changed.
+ * A refused deploy is a normal outcome, not an exception: the caller is a
+ * webhook or a CLI that needs to report *why*, and every reason is already in
+ * the plan.
+ */
+/** What a push recorded about itself, where the Repository page reads it. */
+export interface PushNote {
+  commit: string;
+  at: string;
+  applied: boolean;
+  issues?: unknown[];
+  blockedBy?: string[];
+  /** Set when a blocked push was applied later, by the retry. */
+  appliedAt?: string;
+}
+
+export const pushNotePath = (tenant: string, workspace: string) =>
+  path.join(repoDir(tenant, workspace), "foldrun-last-push.json");
+
+export function readPushNote(tenant: string, workspace: string): PushNote | null {
+  try {
+    return JSON.parse(fs.readFileSync(pushNotePath(tenant, workspace), "utf8")) as PushNote;
+  } catch {
+    return null;
+  }
+}
+
+export function writePushNote(tenant: string, workspace: string, note: PushNote) {
+  try {
+    fs.writeFileSync(pushNotePath(tenant, workspace), JSON.stringify(note));
+  } catch {
+    // The note is a record, not the deploy. Losing it must not fail a push.
+  }
+}
+
+/**
+ * A push whose deploy was refused only because a run was in flight is not a
+ * failure — it is a deploy that has not happened yet. Git already said the
+ * push succeeded (the deploy happens after the client is gone), so nothing
+ * would ever tell anyone the workspace on disk is behind `main`. This applies
+ * it once the runs are done.
+ *
+ * Only `blockedBy`: a push refused for `issues` is a broken workspace and
+ * wants a person, not a retry.
+ */
+export function applyPendingPush(
+  tenant: string,
+  workspace: string,
+  filesAt: (tenant: string, scope: string, ref: string) => DeployFile[],
+): { commit: string } | null {
+  const note = readPushNote(tenant, workspace);
+  if (!note || note.applied) return null;
+  if (!note.blockedBy?.length || (note.issues?.length ?? 0) > 0) return null;
+  if (runsInFlight(tenant, workspace).length > 0) return null;
+  // Only the commit the note names, and only while it is still what main
+  // points at — a newer push supersedes it and wrote its own note.
+  const result = deployWorkspace(tenant, workspace, filesAt(tenant, workspace, note.commit), {
+    commit: note.commit,
+    force: false,
+  });
+  writePushNote(tenant, workspace, {
+    ...note,
+    applied: result.applied,
+    issues: result.issues ?? [],
+    blockedBy: result.blockedBy ?? [],
+    ...(result.applied ? { appliedAt: new Date().toISOString() } : {}),
+  });
+  return result.applied ? { commit: note.commit } : null;
+}
+
+export function deployWorkspace(
+  tenant: string,
+  workspace: string,
+  files: DeployFile[],
+  opts: DeployOptions = {},
+): DeployResult {
+  assertSafeName(tenant, "tenant");
+  assertSafeName(workspace, "workspace");
+
+  const plan = planDeploy(tenant, workspace, files);
+  const blocked = plan.blockedBy.length > 0 && !opts.force;
+  if (plan.issues.length > 0 || blocked) {
+    return { ...plan, applied: false, commit: null, preserved: 0 };
+  }
+
+  const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message });
+  const commit = opts.commit ?? null;
+  if (commit) writeDeployedCommit(tenant, workspace, commit);
+  return { ...plan, applied: true, commit, preserved };
+}
+
+// Which commit a workspace is running.
+//
+// Outside the workspace directory on purpose: saveWorkspace replaces that
+// directory wholesale, so a marker written inside it would be deleted by the
+// very deploy it describes. It also is not a workspace file — nobody should
+// see it in the file tree or be able to edit it.
+const commitFile = (tenant: string, workspace: string) =>
+  path.join(workspaceDir(tenant, workspace), "..", `.${workspace}.deployed`);
+
+export function writeDeployedCommit(tenant: string, workspace: string, commit: string) {
+  const f = commitFile(tenant, workspace);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, `${JSON.stringify({ commit, at: new Date().toISOString() })}\n`);
+}
+
+export function deployedCommit(
+  tenant: string,
+  workspace: string,
+): { commit: string; at: string } | null {
+  try {
+    return JSON.parse(fs.readFileSync(commitFile(tenant, workspace), "utf8"));
+  } catch {
+    return null;
+  }
+}

package/src/egress.ts

@@ -0,0 +1,176 @@
+// Egress: the run sandbox never holds a credential it only ever puts in a
+// header.
+//
+// Until now a step's secrets were decrypted host-side and copied into the
+// sandbox as environment variables. The model never saw a value — only the
+// names — but every program in the pod could read them: a script tool, a
+// bash grant, a dependency `runtime:` installed. The pod was the blast
+// radius, and the credential was inside it.
+//
+// The egress proxy moves the credential to the boundary. The pod is handed
+// a per-step address (`http://<worker>/e/<lease>`) and a set of
+// placeholders (`${RESEND_API_KEY}`), and sends every API request through
+// that address with the placeholder still in the header. The worker holds
+// the lease, swaps the placeholder for the value on the way out — for the
+// host that secret was granted to, and no other — forwards the request, and
+// streams the answer back. The value exists in the worker's memory and on
+// the wire to the provider. Never in the pod.
+//
+// Three consumers, in the pod:
+//   - the http tools (api-tools.ts): every declared API
+//   - the translator (translator.ts): the model key, for Chat Completions
+//     and Responses providers
+//   - the Agent SDK itself, for Anthropic-shaped providers: its base URL is
+//     pointed through the proxy and its key IS the placeholder
+//
+// Script tools are the exception, on purpose: a script reads secrets from
+// its environment and may need the real value in process (a browser seeding
+// cookies, an ssh key). A step that grants such a script materialises its
+// secrets into the pod as before, and the run record says so. A script that
+// declares `secrets: proxied` in its tool file gets the placeholders and
+// `FOLDRUN_EGRESS` instead, and sends through the proxy like everything
+// else.
+//
+// This file is the vocabulary both sides share. The server is the
+// platform's (it needs a long-lived process and a Service); the pod side is
+// here in core, because it is what the runner image runs.
+
+/** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
+export const PLACEHOLDER = /\$\{([A-Z][A-Z0-9_]*)\}/g;
+
+/** The env var the pod reads to know it should send through a proxy. */
+export const EGRESS_ENV = "FOLDRUN_EGRESS";
+
+/** The placeholder name the platform's own model key travels under. */
+export const MODEL_KEY_NAME = "FOLDRUN_MODEL_KEY";
+
+/**
+ * The address a request to `target` should actually be sent to. With no
+ * proxy configured, the target itself — every caller works unchanged on a
+ * machine with no worker, which is the CLI and every test.
+ */
+export function viaEgress(egress: string | undefined | null, target: string): string {
+  if (!egress) return target;
+  return `${egress.replace(/\/+$/, "")}/${target}`;
+}
+
+/** The names referenced by placeholders in a string. */
+export function placeholderNames(text: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(PLACEHOLDER)) out.add(m[1]);
+  return [...out];
+}
+
+/** Replace the placeholders in `text` whose names `values` knows. Unknown
+ *  names stay literal, so a wrong grant fails loudly at the provider
+ *  instead of silently sending nothing. */
+export function substitutePlaceholders(text: string, values: Record<string, string>): string {
+  return text.replace(PLACEHOLDER, (whole, name: string) => (name in values ? values[name] : whole));
+}
+
+/** The host a granted secret may be sent to. Compared case-insensitively;
+ *  a port is part of the host. */
+export function hostOf(url: string): string | null {
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What one step is allowed to send, and where. The runner builds this
+ * from the step's declared secrets and the hosts its tools and provider
+ * name; the proxy enforces it per request.
+ */
+export interface EgressGrant {
+  /** Secret name → the hosts that secret may be substituted for. */
+  secrets: Record<string, { value: string; hosts: string[] }>;
+}
+
+export interface EgressLease {
+  /** The base the pod sends through: `http://…/e/<token>`. */
+  url: string;
+  /** The grant is finished being built — publish it. The runner keeps
+   *  adding grants after the lease exists (the model key's host needs the
+   *  lease URL first), so a store that is not this process's memory has
+   *  to be told when the grant is complete. Call before every attempt. */
+  commit(): Promise<void>;
+  /** One line per request, for the run trace. Drained by the runner. */
+  drainLog(): Promise<string[]>;
+  /** The step is over: the lease is void and its values are dropped. */
+  release(): Promise<void>;
+}
+
+/**
+ * The seam the platform fills. `null` from `lease` (or no `egress` at all)
+ * means "no proxy here" and the runner falls back to materialising, exactly
+ * as it always did.
+ */
+export interface EgressHooks {
+  lease(args: { tenant: string; runId: string; grant: EgressGrant }): Promise<EgressLease | null>;
+}
+
+/** Strip a header set of the proxy's own and hop-by-hop headers. */
+export const HOP_BY_HOP = new Set([
+  "connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer",
+  "transfer-encoding", "upgrade", "host", "content-length",
+]);
+
+const ANTHROPIC_DEFAULT_BASE = "https://api.anthropic.com";
+
+/**
+ * A model env (the SDK's ANTHROPIC_* variables) rewritten to send through
+ * a lease: the base URL goes via the proxy, and whichever credential is
+ * set becomes the `${FOLDRUN_MODEL_KEY}` placeholder — the SDK only ever
+ * puts it in a header, and the proxy fills it for that one host. Provider
+ * headers that carried a secret's value get the value swapped back for
+ * its `${NAME}`, so the pod holds the name and the proxy holds the value.
+ * Adds the grants it needs to `grant`. Pure apart from that.
+ */
+export function proxyModelEnv(
+  env: Record<string, string | undefined>,
+  leaseUrl: string,
+  grant: EgressGrant,
+  knownSecrets: Record<string, string> = {},
+  name: string = MODEL_KEY_NAME,
+): Record<string, string | undefined> {
+  const base = env.ANTHROPIC_BASE_URL || ANTHROPIC_DEFAULT_BASE;
+  const host = hostOf(base);
+  if (!host) return env;
+  const out: Record<string, string | undefined> = { ...env, ANTHROPIC_BASE_URL: viaEgress(leaseUrl, base) };
+  const credentialKeys = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"] as const;
+  for (const key of credentialKeys) {
+    const value = env[key];
+    if (typeof value === "string" && value.length) {
+      addGrant(grant, name, value, host);
+      out[key] = `\${${name}}`;
+    }
+  }
+  if (typeof env.ANTHROPIC_CUSTOM_HEADERS === "string") {
+    out.ANTHROPIC_CUSTOM_HEADERS = unsubstitute(env.ANTHROPIC_CUSTOM_HEADERS, knownSecrets, host, grant);
+  }
+  return out;
+}
+
+/** Put the `${NAME}` back where a known secret's value sits in `text`,
+ *  granting the name to `host`. Longest values first, so one that contains
+ *  another is replaced whole. */
+export function unsubstitute(text: string, knownSecrets: Record<string, string>, host: string, grant: EgressGrant): string {
+  let out = text;
+  const entries = Object.entries(knownSecrets).filter(([, v]) => v.length >= 8).sort((a, b) => b[1].length - a[1].length);
+  for (const [name, value] of entries) {
+    if (!out.includes(value)) continue;
+    out = out.split(value).join(`\${${name}}`);
+    addGrant(grant, name, value, host);
+  }
+  return out;
+}
+
+export function addGrant(grant: EgressGrant, name: string, value: string, host: string): void {
+  const h = host.toLowerCase();
+  const existing = grant.secrets[name];
+  if (existing) {
+    if (!existing.hosts.includes(h)) existing.hosts.push(h);
+  } else grant.secrets[name] = { value, hosts: [h] };
+}