@jr2/orchestrator 0.6.0 → 0.7.0

package/src/secret-placement.ts

@@ -3,13 +3,20 @@
 //
 //   - a Workspace's pod: the Held secrets its `workspace()` lists under `secrets: [...]`, and the
 //     model keys of the Agents whose Turns run there — a model key is claimed by the PROVIDER;
-//   - the Instance Harness: the model keys of the `"none"` Agents it hosts, and nothing else (they
-//     cannot execute code, ADR-0031, so nothing else is theirs to use);
+//   - the Instance Harness: the model keys of the `"none"` Agents it hosts, and the secrets of the
+//     remote MCP servers they name (ADR-0079), and nothing else (they cannot execute code, ADR-0031,
+//     so nothing else is theirs to use);
+//   - a Workspace's pod also holds the secret of each MCP server an Agent there names (ADR-0079):
+//     "a Custodian holds what its pod's Agents name";
 //   - an Effector: what its Effects name with `secret("name")` — the Instance Effector what its
 //     `http` Effects name and the token of each `dispatch` with a target (ADR-0071; a dispatch with
 //     no target runs in the Orchestrator's own process and names nothing); a Workspace's Sandbox Effector what its file-body `http`s and
 //     credentialed `command`s name. The push credential its `push`es spend is not placed here: the provision
-//     names the entry the slot's url matches on the Sandbox, by reference (git-push.ts, ADR-0051).
+//     names the entry the slot's url matches on the Sandbox, by reference (git-push.ts, ADR-0051);
+//   - the Instance Effector also holds the secret of each Hook with a `mac` verifier, and its fence
+//     takes each host that a Hook's kind declares in `posts`, with no secret (ADR-0068, ADR-0078);
+//   - the Orchestrator gets only the sha-256 digest of the secret of each Hook with a `token`
+//     verifier, in `jr2-hook-digests`, and never the value (ADR-0078).
 //
 // `hosts`, `headers` and `paths` are an entry's BINDING — where a Custodian may put the value — and
 // never its placement. Both is both, and `jr2 up` reports it per pod; an entry nothing names goes
@@ -19,6 +26,7 @@
 // the list does not hold, and an Effect secret shorter than 8 characters (ADR-0068): the Effector
 // replaces every match of a secret in what it returns, and a short one would match ordinary text.
 
+import { createHash } from "node:crypto";
 import {
   providerClaims,
   sourceOf,
@@ -27,7 +35,8 @@ import {
   type HeldBinding,
   type HeldLookups,
 } from "./held-secrets.ts";
-import type { JR2Config } from "./config.ts";
+import { isStdioServer, mcpTimeoutMs, type JR2Config, type McpRemoteServer } from "./config.ts";
+import { hookParts } from "./hook-kinds/door.ts";
 import { needsASlot } from "./effect.ts";
 import { declaredPushKinds, pushRefusal } from "./git-push.ts";
 import { INSTANCE_HARNESS_HELD_POD } from "./names.ts";
@@ -42,6 +51,10 @@ export type EffectSecret = { name: string; source: HeldBinding["source"] };
 /** One target an Effect placed in an Effector may call, with the secrets it names there. */
 export type EffectorTargetConfig = { scheme: "http" | "https"; host: string; port: number; secrets: string[] };
 
+/** One MCP server an `mcp` Effect placed in the Instance Effector calls (ADR-0079): `effector.json`'s
+ * `mcp` entry — its url, the name of its secret, and its `timeout` in milliseconds. Never a value. */
+export type EffectorMcpServer = { url: string; secret?: string; timeoutMs: number };
+
 /** What one Effector placement holds and allows — what `jr2 up` converges from. */
 export type EffectorPlan = {
   placement: "instance";
@@ -51,12 +64,22 @@ export type EffectorPlan = {
   values: Record<string, string>;
   /** `effector.json`'s targets: one per distinct (target, secrets) an Effect placed there names. */
   targets: EffectorTargetConfig[];
+  /** `effector.json`'s `mcp`: each server an `mcp` Effect placed there names, by its name in the
+   * `mcp` block (ADR-0079). Empty when there is none. */
+  mcp: Record<string, EffectorMcpServer>;
   /** The longest timeout among the Effects placed there, in milliseconds. */
   longestTimeoutMs: number;
   /** The Effects placed there, as `<workflow>/<slot>`. */
   effects: string[];
+  /** The Hooks it serves (ADR-0068): each one with a `mac` verifier, or whose kind declares
+   * `posts`, by name. */
+  hooks: string[];
 };
 
+/** The secret of a Hook with a `token` verifier (ADR-0078): `jr2 up` writes the sha-256 digest of
+ * its value into `jr2-hook-digests`, from the literal or from the key of the user's Secret. */
+export type HookTokenSecret = { name: string } & ({ value: string } | { secret: string; key: string });
+
 /** One registered Machine's Effect, as `jr2 up` walked it. */
 export type PlacedEffect = { workflow: string; effect: CarriedEffect };
 
@@ -67,8 +90,9 @@ export type PlacedWorkspace = { workflow: string; pod: WorkspacePod };
 export type PlacementWalk = {
   effects: readonly PlacedEffect[];
   workspaces: readonly PlacedWorkspace[];
-  /** The models of the `"none"` Agents — present when the Instance Harness is converged. */
-  instanceHarness?: { models: readonly string[] };
+  /** The models of the `"none"` Agents, and the MCP servers they name (ADR-0079) — present when
+   * the Instance Harness is converged. */
+  instanceHarness?: { models: readonly string[]; servers?: readonly string[] };
 };
 
 /** One Harness pod's Held secrets: what its Custodian holds. */
@@ -79,8 +103,11 @@ export type HeldPodPlan = {
   label: string;
   /** The names it holds, in list order; the custom provider's key last. */
   names: string[];
-  /** Of `names`, those a provider claims (the rest the `workspace()` lists). */
+  /** Of `names`, those a provider claims (the rest the `workspace()` lists, or an MCP server). */
   byProvider: string[];
+  /** Of `names`, the secrets of the MCP servers its Agents name (ADR-0079), each with those
+   * servers. Absent when there is none. */
+  byServer?: Record<string, string[]>;
 };
 
 /** One push of a Workspace (ADR-0067, ADR-0051): its Repo Slot, whether it signs, and — for a slot the
@@ -120,10 +147,12 @@ export type SecretPlacements = {
   held: HeldPodPlan[];
   /** Every name some pod holds — what `heldSecretsOf` normalizes. */
   claimed: Set<string>;
-  /** The Instance Effector, when an Effect is placed there; absent otherwise. */
+  /** The Instance Effector, when an Effect is placed there or a Hook needs it; absent otherwise. */
   instance?: EffectorPlan;
   /** Each Workspace whose body places an Effect in its Sandbox Effector. */
   sandbox: SandboxEffectorPlan[];
+  /** The secrets of the `token` Hooks, in list order: only their digests reach the Orchestrator. */
+  hookTokens: HookTokenSecret[];
   /** One line per secret, then one per pod: where each goes, what each holds. */
   report: string[];
   warnings: string[];
@@ -184,7 +213,7 @@ export function secretPlacementsOf(
   walk: PlacementWalk,
   lookups: Pick<HeldLookups, "secretKeys" | "valueLength"> = {},
 ): SecretPlacements {
-  const { entries, namedBy, instancePlaced } = namesOf(config, walk);
+  const { entries, namedBy, instancePlaced, hooks, tokenHooks } = namesOf(config, walk);
   const { pods, redundant } = heldPodsOf(config, walk, new Set(entries.map((e) => e.name)));
   const claimed = new Set(pods.flatMap((p) => p.names));
 
@@ -192,6 +221,7 @@ export function secretPlacementsOf(
   const warnings: string[] = [];
   const secrets: EffectSecret[] = [];
   const values: Record<string, string> = {};
+  const hookTokens: HookTokenSecret[] = [];
   for (const e of entries) {
     const named = namedBy.get(e.name) ?? [];
     if (named.length > 0) {
@@ -215,10 +245,21 @@ export function secretPlacementsOf(
         )})`,
     );
     const where = [...(heldIn.length ? [`Held in ${heldIn.join(", ")}`] : []), ...effectIn];
+    // A `token` Hook names its secret: the Orchestrator gets its digest, never its value (ADR-0078).
+    const byToken = tokenHooks.get(e.name);
+    if (byToken !== undefined) {
+      const source = sourceOf(e, lookups);
+      hookTokens.push(
+        source.kind === "literal"
+          ? { name: e.name, value: e.value as string }
+          : { name: e.name, secret: source.secret, key: source.key },
+      );
+      where.push(`a digest in the Orchestrator (${byToken.map((h) => `hook ${h}`).join(", ")})`);
+    }
     if (where.length === 0) {
       warnings.push(
         `${e.at} (${e.name}) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider ` +
-          "reads it, and no Effect names it (ADR-0059, ADR-0068)",
+          "reads it, and no Effect or Hook names it (ADR-0059, ADR-0068)",
       );
       continue;
     }
@@ -231,21 +272,32 @@ export function secretPlacementsOf(
     );
   }
   for (const p of pods) {
-    const holds = p.names.map((n) => (p.byProvider.includes(n) ? `${n} (provider)` : n));
+    const holds = p.names.map((n) =>
+      p.byProvider.includes(n)
+        ? `${n} (provider)`
+        : p.byServer?.[n] !== undefined
+          ? `${n} (mcp ${p.byServer[n]!.join(", ")})`
+          : n,
+    );
     report.push(`${p.label}: Custodian holds ${holds.length ? holds.join(", ") : "nothing"}`);
   }
   for (const { label, name } of redundant) {
     report.push(`${label}: secrets lists ${name}, which its Agents' provider claims already — redundant`);
   }
 
-  const instanceSecrets = new Set(instancePlaced.flatMap((p) => p.effect.secrets));
+  const instanceSecrets = new Set([
+    ...instancePlaced.flatMap((p) => effectSecretsOf(config, p.effect)),
+    ...hooks.flatMap((h) => (h.secret === undefined ? [] : [h.secret])),
+  ]);
   const instance =
-    instancePlaced.length === 0
+    instancePlaced.length === 0 && hooks.length === 0
       ? undefined
       : effectorPlan(
           instancePlaced,
+          hooks,
           secrets.filter((s) => instanceSecrets.has(s.name)),
           values,
+          config,
         );
   if (instance) {
     report.push(
@@ -275,7 +327,7 @@ export function secretPlacementsOf(
         `${pushes.length ? `; pushes ${pushes.join(", ")}` : ""}`,
     );
   }
-  return { held: pods, claimed, ...(instance ? { instance } : {}), sandbox, report, warnings };
+  return { held: pods, claimed, ...(instance ? { instance } : {}), sandbox, hookTokens, report, warnings };
 }
 
 /** A Workspace's Sandbox Effector: the secrets its Effects name, the targets its file-body https call, its
@@ -354,34 +406,123 @@ function pushesOf(config: JR2Config, ws: PlacedWorkspace): SandboxPush[] {
   return out;
 }
 
-function effectorPlan(placed: InstancePlaced[], secrets: EffectSecret[], values: Record<string, string>): EffectorPlan {
+function effectorPlan(
+  placed: InstancePlaced[],
+  hooks: InstanceHook[],
+  secrets: EffectSecret[],
+  values: Record<string, string>,
+  config: JR2Config,
+): EffectorPlan {
   const targets: EffectorTargetConfig[] = [];
+  const add = (t: EffectorTargetConfig): void => {
+    const same = (x: EffectorTargetConfig) =>
+      x.scheme === t.scheme && x.host === t.host && x.port === t.port && x.secrets.join() === t.secrets.join();
+    if (!targets.some(same)) targets.push(t);
+  };
+  const mcp: Record<string, EffectorMcpServer> = {};
+  const timeouts: number[] = [];
   for (const { effect } of placed) {
+    if (effect.kind === "mcp") {
+      // The server's url and secret are the config's (ADR-0079). An Open server, and one the block
+      // does not declare as a remote server, are refused before this (`mcpRefusals`).
+      const server = remoteServerOf(config, effect.server);
+      if (server === undefined) continue;
+      const timeoutMs = mcpTimeoutMs(server.timeout) ?? 0;
+      mcp[effect.server!] = { url: server.url, ...(server.secret ? { secret: server.secret } : {}), timeoutMs };
+      add({ ...originOf(server.url), secrets: server.secret ? [server.secret] : [] });
+      timeouts.push(effect.timeoutMs > 0 ? effect.timeoutMs : timeoutMs);
+      continue;
+    }
+    if (effect.kind === "http") timeouts.push(effect.timeoutMs);
     // An Open url or an Open dispatch target has no target, so it allows nothing: `jr2 up` refuses
     // it before this (ADR-0054). A dispatch's target is its origin, its one secret the token
     // (ADR-0071).
     if (effect.target === undefined) continue;
-    const t = { ...effect.target, secrets: [...effect.secrets].sort() };
-    const same = (x: EffectorTargetConfig) =>
-      x.scheme === t.scheme && x.host === t.host && x.port === t.port && x.secrets.join() === t.secrets.join();
-    if (!targets.some(same)) targets.push(t);
+    add({ ...effect.target, secrets: [...effect.secrets].sort() });
   }
+  // A Hook's follow-up is one `http` call with no secret, to a host its kind declares (ADR-0068).
+  for (const hook of hooks) for (const post of hook.posts) add({ ...post, secrets: [] });
   return {
     placement: "instance",
     secrets,
     values,
     targets,
-    // The grace a rollout gives a replica covers the http Effects alone (ADR-0071): a dispatch is
-    // idempotent by construction, so a `wait` a rollout cuts is sent again under its key and its
-    // poll resumes, and a wait of hours never stretches the Effector's grace.
-    longestTimeoutMs: Math.max(0, ...placed.flatMap((p) => (p.effect.kind === "http" ? [p.effect.timeoutMs] : []))),
+    mcp,
+    // The grace a rollout gives a replica covers the http and mcp Effects alone (ADR-0071): a
+    // dispatch is idempotent by construction, so a `wait` a rollout cuts is sent again under its
+    // key and its poll resumes, and a wait of hours never stretches the Effector's grace. An mcp
+    // Effect with no timeout of its own waits for its server's (ADR-0079).
+    longestTimeoutMs: Math.max(0, ...timeouts),
     effects: placed.map((p) => `${p.workflow}/${p.effect.name}`),
+    hooks: hooks.map((h) => h.name),
   };
 }
 
-/** An Effect the Instance Effector runs: an http one with no Worktree file, or a dispatch with a
- * target (ADR-0068, ADR-0071). */
-type InstancePlaced = { workflow: string; effect: Extract<CarriedEffect, { kind: "http" | "dispatch" }> };
+/** A Hook the Instance Effector serves (ADR-0068): its `mac` secret's name, when its verifier is
+ * `mac`, and the targets of its kind's `posts`. */
+type InstanceHook = { name: string; secret?: string; posts: Array<Omit<EffectorTargetConfig, "secrets">> };
+
+/**
+ * The Hooks the Instance Effector serves (ADR-0068, ADR-0078): each one with a `mac` verifier, whose
+ * secret only that Effector holds, and each one whose kind declares `posts`, whose follow-up it
+ * sends. A `token` Hook's secret is a digest in the Orchestrator, and an `ed25519` Hook holds a
+ * public key: neither needs the Effector unless its kind posts.
+ */
+function instanceHooksOf(config: JR2Config): InstanceHook[] {
+  const out: InstanceHook[] = [];
+  for (const [name, hook] of Object.entries(config.hooks ?? {})) {
+    const { kind, credential } = hookParts(hook);
+    const secret = "mac" in kind.verify && "secret" in credential ? credential.secret.secret : undefined;
+    const posts = (kind.posts ?? []).map((prefix) => {
+      const url = new URL(prefix);
+      return { scheme: "https" as const, host: url.hostname, port: url.port === "" ? 443 : Number(url.port) };
+    });
+    if (secret === undefined && posts.length === 0) continue;
+    out.push({ name, ...(secret !== undefined ? { secret } : {}), posts });
+  }
+  return out;
+}
+
+/** The Hooks with a `token` verifier, by the name of the secret each names (ADR-0078). */
+function tokenHooksOf(config: JR2Config): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const [name, hook] of Object.entries(config.hooks ?? {})) {
+    const { kind, credential } = hookParts(hook);
+    if (!("token" in kind.verify) || !("secret" in credential)) continue;
+    const secret = credential.secret.secret;
+    out.set(secret, [...(out.get(secret) ?? []), name]);
+  }
+  return out;
+}
+
+/** An Effect the Instance Effector runs: an http one with no Worktree file, a dispatch with a
+ * target, or an mcp one (ADR-0068, ADR-0071, ADR-0079). */
+type InstancePlaced = { workflow: string; effect: Extract<CarriedEffect, { kind: "http" | "dispatch" | "mcp" }> };
+
+/** The remote server of the `mcp` block that an `mcp` Effect names, or undefined: an Open server,
+ * one the block does not declare, or a stdio one (ADR-0079). */
+function remoteServerOf(config: JR2Config, name: string | undefined): McpRemoteServer | undefined {
+  if (name === undefined || !Object.hasOwn(config.mcp ?? {}, name)) return undefined;
+  const server = config.mcp![name]!;
+  return isStdioServer(server) ? undefined : server;
+}
+
+/** The secrets an Effect names, as the placement reads them: its own, or for an `mcp` Effect its
+ * server's, from the config (ADR-0079). */
+function effectSecretsOf(config: JR2Config, effect: CarriedEffect): string[] {
+  if (effect.kind !== "mcp") return [...(effect.secrets ?? [])];
+  const secret = remoteServerOf(config, effect.server)?.secret;
+  return secret === undefined ? [] : [secret];
+}
+
+/** An MCP server url's origin as the Effector's fence reads it: scheme, host, port. `jr2 up` has
+ * checked the url (`mcpUrlRefusals`), so it parses. */
+function originOf(url: string): { scheme: "http" | "https"; host: string; port: number } {
+  const u = new URL(url);
+  const scheme = u.protocol === "http:" ? "http" : "https";
+  const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  return { scheme, host, port: u.port ? Number(u.port) : scheme === "http" ? 80 : 443 };
+}
 
 /** A Workspace as a human reads it: its workflow and the placement route to it, an inline hop as
  * `invoked inline in state <id>`. */
@@ -424,6 +565,19 @@ function heldPodsOf(
   };
   const pods: HeldPodPlan[] = [];
   const redundant: Array<{ label: string; name: string }> = [];
+  // The secret of each remote MCP server that the pod's Agents name (ADR-0079), with the servers:
+  // the Agent claims it by naming the server, as it claims a model key by naming a model. A name
+  // the `mcp` block does not declare is refused by the walk's own check (`mcpRefusals`), not here.
+  const serverClaims = (servers: Iterable<string>): Record<string, string[]> => {
+    const out: Record<string, string[]> = {};
+    for (const server of new Set(servers)) {
+      const declared = config.mcp?.[server];
+      const secret = declared && !isStdioServer(declared) ? declared.secret : undefined;
+      if (secret === undefined) continue;
+      out[secret] = [...(out[secret] ?? []), server].sort();
+    }
+    return out;
+  };
   for (const ws of walk.workspaces) {
     const label = workspaceLabel(ws);
     for (const name of ws.pod.secrets) {
@@ -435,18 +589,27 @@ function heldPodsOf(
     }
     const byProvider = providerClaims(config, ws.pod.models);
     for (const name of ws.pod.secrets) if (byProvider.includes(name)) redundant.push({ label, name });
+    const byServer = serverClaims((ws.pod.mcp ?? []).map((m) => m.entry.server));
     const plan: HeldPodPlan = {
       pod: workspaceHeldPod({ workflow: ws.workflow, route: ws.pod.route }),
       label,
-      names: ordered([...ws.pod.secrets, ...byProvider]),
+      names: ordered([...ws.pod.secrets, ...byProvider, ...Object.keys(byServer)]),
       byProvider: ordered(byProvider),
+      ...(Object.keys(byServer).length ? { byServer } : {}),
     };
     if (pods.some((p) => p.pod === plan.pod)) throw sharedPodKey(plan.pod, label);
     pods.push(plan);
   }
   if (walk.instanceHarness) {
     const byProvider = ordered(providerClaims(config, walk.instanceHarness.models));
-    pods.push({ pod: INSTANCE_HARNESS_HELD_POD, label: "the Instance Harness", names: byProvider, byProvider });
+    const byServer = serverClaims(walk.instanceHarness.servers ?? []);
+    pods.push({
+      pod: INSTANCE_HARNESS_HELD_POD,
+      label: "the Instance Harness",
+      names: ordered([...byProvider, ...Object.keys(byServer)]),
+      byProvider,
+      ...(Object.keys(byServer).length ? { byServer } : {}),
+    });
   }
   return { pods, redundant };
 }
@@ -469,7 +632,8 @@ function namesOf(config: JR2Config, walk: PlacementWalk) {
   const namedBy = new Map<string, Array<{ label: string; where: string }>>();
   const instancePlaced = walk.effects.filter(
     (p): p is InstancePlaced =>
-      (p.effect.kind === "http" || p.effect.kind === "dispatch") && p.effect.placement === "instance",
+      (p.effect.kind === "http" || p.effect.kind === "dispatch" || p.effect.kind === "mcp") &&
+      p.effect.placement === "instance",
   );
   // Keyed by the Effect's placement route and slot name, as workspacePodsOf keys a pod's Effects:
   // two slots of one name in one workflow — one in a workspace(), one outside it — are two Effects,
@@ -489,23 +653,52 @@ function namesOf(config: JR2Config, walk: PlacementWalk) {
         "workspace()'s body, or send a json or text body (ADR-0068)",
     );
   }
+  // A Hook with a `mac` verifier names its secret as an Effect names one, and it is placed in the
+  // Instance Effector alone (ADR-0068).
+  const hooks = instanceHooksOf(config);
+  const tokenHooks = tokenHooksOf(config);
+  for (const [secret, names] of tokenHooks) {
+    if (byName.has(secret)) continue;
+    throw new Error(
+      `hooks.${names[0]} names secret("${secret}"), which the \`secrets\` list does not hold — add it: ` +
+        `secrets: [{ name: "${secret}", value: process.env.${envish(secret)} }] (ADR-0078)`,
+    );
+  }
+  for (const hook of hooks) {
+    if (hook.secret === undefined) continue;
+    if (!byName.has(hook.secret)) {
+      throw new Error(
+        `hooks.${hook.name} names secret("${hook.secret}"), which the \`secrets\` list does not hold — add it: ` +
+          `secrets: [{ name: "${hook.secret}", value: process.env.${envish(hook.secret)} }] (ADR-0068)`,
+      );
+    }
+    namedBy.set(hook.secret, [
+      ...(namedBy.get(hook.secret) ?? []),
+      { label: `hook ${hook.name}`, where: "the Instance Effector" },
+    ]);
+  }
   for (const { workflow, effect } of walk.effects) {
     const label = `${workflow}/${effect.name}`;
     const where =
       effect.placement === "instance"
         ? "the Instance Effector"
         : (sandboxOf.get(keyOf(workflow, effect)) ?? "the Sandbox Effector of the Workspace that invokes it");
-    for (const name of effect.secrets ?? []) {
+    for (const name of effectSecretsOf(config, effect)) {
       if (!byName.has(name)) {
+        // An mcp Effect never writes secret(): the server it calls, in the `mcp` block, names it.
+        const names =
+          effect.kind === "mcp"
+            ? `calls the MCP server "${effect.server}", whose secret "${name}"`
+            : `names secret("${name}"), which`;
         throw new Error(
-          `workflow "${workflow}": the ${effect.kind} Effect "${effect.name}" names secret("${name}"), which the ` +
+          `workflow "${workflow}": the ${effect.kind} Effect "${effect.name}" ${names} the ` +
             `\`secrets\` list does not hold — add it: secrets: [{ name: "${name}", value: process.env.${envish(name)} }] (ADR-0068)`,
         );
       }
       namedBy.set(name, [...(namedBy.get(name) ?? []), { label, where }]);
     }
   }
-  return { entries, namedBy, instancePlaced };
+  return { entries, namedBy, instancePlaced, hooks, tokenHooks };
 }
 
 /** An Effect secret shorter than 8 characters is refused, and the refusal says why. */
@@ -515,10 +708,23 @@ function namesOf(config: JR2Config, walk: PlacementWalk) {
  * length leaves; `jr2 up` keeps no value of the user's Secret (ADR-0068).
  */
 export function storedValueLength(base64: string): number {
+  return storedBytes(base64).length;
+}
+
+/**
+ * The sha-256, in hex, of a value a Kubernetes Secret holds, trimmed as `storedValueLength` trims
+ * it: what `jr2-hook-digests` holds for a `token` Hook whose secret is a key of the user's Secret
+ * (ADR-0078). Only the digest leaves.
+ */
+export function storedValueSha256(base64: string): string {
+  return createHash("sha256").update(storedBytes(base64)).digest("hex");
+}
+
+function storedBytes(base64: string): Buffer {
   let bytes = Buffer.from(base64, "base64");
   if (bytes.at(-1) === 0x0a) bytes = bytes.subarray(0, -1);
   if (bytes.at(-1) === 0x0d) bytes = bytes.subarray(0, -1);
-  return bytes.length;
+  return bytes;
 }
 
 function shortRefusal(e: { at: string; name: string }, length: number): void {

package/src/server.ts

@@ -16,6 +16,17 @@
 //                      a publish door anyone outside it can open.
 //   JR2_SIGNING_KEY     base64 key Sandbox tokens are signed with; from the Secret so live Sandboxes
 //                      survive a pod restart. Absent → minted into `<dir>/.jr2/secret` (dev-grade).
+//   JR2_CALLER_DIGESTS  the file of the named Caller tokens' digests (ADR-0078). Default, deployed:
+//                      the `jr2-caller-digests` mount; host-booted: none. Read again when it
+//                      changes, so a rotation needs no restart.
+//   JR2_HOOK_DIGESTS    the file of the `token` Hooks' secrets' digests (ADR-0078). Default,
+//                      deployed: the `jr2-hook-digests` mount; host-booted: none. Read again when
+//                      it changes.
+//   JR2_INSTANCE_EFFECTOR  the Instance Effector's address, `host:port` (ADR-0068). Default,
+//                      deployed: its Service; host-booted: none. A host-booted fixture names its
+//                      own, which speaks the same signed wire (the e2e tier's `mac` Hook check).
+//   JR2_STATE_VOLUME    the size of the state volume claim that `jr2 up` applied (ADR-0065): the
+//                      space guard measures against it. Absent: `runs.volume`, or `5Gi`.
 //   JR2_NAMESPACE       the pod's own namespace (Deployment fieldRef) — presence = "deployed":
 //                      Sandboxes are driven in it, and the Custodians' route home is Service DNS.
 //
@@ -46,7 +57,7 @@ import { join } from "node:path";
 import { resolveAssembly, type ResolvedAssembly } from "./assembly.ts";
 import { KIT_VERSION, loadConfig, type JR2Config } from "./config.ts";
 import { readImageRefs } from "./images.ts";
-import { readMountDigests } from "./mount-digest.ts";
+import { loadedDigests, readMountDigests } from "./mount-digest.ts";
 import { GIT_CLONE_MANIFEST_KEY, readGitCloneManifest } from "./git-clone.ts";
 import { loadWorkflows, startInstance, type RunningInstance } from "./instance.ts";
 import {
@@ -60,6 +71,12 @@ import {
   INSTANCE_HARNESS_SERVICE,
   INSTANCE_EFFECTOR,
   EFFECTOR_PORT,
+  CALLER_DIGESTS_KEY,
+  CALLER_DIGESTS_MOUNT,
+  CALLER_DIGESTS_SECRET,
+  HOOK_DIGESTS_KEY,
+  HOOK_DIGESTS_MOUNT,
+  HOOK_DIGESTS_SECRET,
 } from "./names.ts";
 import type { AnyStateMachine } from "xstate";
 import { partsOf, type CarriedRepo } from "./parts.ts";
@@ -69,7 +86,7 @@ import { kubeRepos, type RepoResources } from "./repos.ts";
 import { SANDBOX_EFFECTOR_PORT, kubeSandbox } from "./sandbox-kube.ts";
 import { sandboxEffectorService } from "./sandbox-effector.ts";
 import { watchSandboxes, type SandboxWatch } from "./sandbox-watch.ts";
-import { loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import { loadSigningKey, mintInstanceToken, watchCallerDigests } from "./tokens.ts";
 import type { SandboxPort } from "./workspace.ts";
 
 export type ServerMainOptions = {
@@ -100,6 +117,18 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
   // From the instance Secret when deployed; per-boot for a host-booted fixture.
   const instanceToken = env.JR2_INSTANCE_TOKEN ?? mintInstanceToken();
   const publishToken = env.JR2_PUBLISH_TOKEN ?? mintInstanceToken();
+  // The named Callers' digests (ADR-0078), from the mount `jr2 up` writes. A host-booted process
+  // has none unless the env names a file.
+  const digestsPath =
+    env.JR2_CALLER_DIGESTS ?? (namespace !== undefined ? join(CALLER_DIGESTS_MOUNT, CALLER_DIGESTS_KEY) : undefined);
+  const digests = digestsPath !== undefined ? watchCallerDigests(digestsPath) : undefined;
+  // The `token` Hooks' digests (ADR-0078): the same form, another mount.
+  const hookDigestsPath =
+    env.JR2_HOOK_DIGESTS ?? (namespace !== undefined ? join(HOOK_DIGESTS_MOUNT, HOOK_DIGESTS_KEY) : undefined);
+  const hookDigests = hookDigestsPath !== undefined ? watchCallerDigests(hookDigestsPath) : undefined;
+  const instanceEffector =
+    env.JR2_INSTANCE_EFFECTOR ??
+    (namespace !== undefined ? `${INSTANCE_EFFECTOR}.${namespace}.svc:${EFFECTOR_PORT}` : undefined);
 
   // The current Assembly (ADR-0069), and its config and Workflows read from its ROOT, never from
   // the folder directly. A published Assembly that does not load (a Kit bump that broke an import,
@@ -247,15 +276,27 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
     assembly: resolved,
     port,
     hostname: env.HOST ?? "0.0.0.0",
+    ...(env.JR2_STATE_VOLUME ? { stateVolume: env.JR2_STATE_VOLUME } : {}),
     instanceToken,
     publishToken,
+    ...(digests ? { callerDigests: digests.current } : {}),
+    ...(hookDigests ? { hookDigests: hookDigests.current } : {}),
     signingKey,
     sandbox,
     dataPlane,
     // The door reads the same image map a provision reads (ADR-0069): a `file:` context whose
     // digest it lacks is refused at the publish rather than at the first provision.
     ...(dataPlane
-      ? { imageMap: () => readImageRefs(join(IMAGES_MOUNT, IMAGES_KEY)), mounts: () => readMountDigests() }
+      ? {
+          imageMap: () => readImageRefs(join(IMAGES_MOUNT, IMAGES_KEY)),
+          // The ConfigMaps as the mounts hold them, and the digests Secrets as this process LOADED
+          // them (ADR-0078): a token works when the authenticator holds its digest, not when the
+          // file has it.
+          mounts: async () => ({
+            ...(await readMountDigests()),
+            ...loadedDigests({ [CALLER_DIGESTS_SECRET]: digests, [HOOK_DIGESTS_SECRET]: hookDigests }),
+          }),
+        }
       : {}),
     // A publish landed (ADR-0069): its config is the one that applies from now on, and its
     // Machines may bind other Repos, so the Repo pass runs again. Synchronous: the walk is over
@@ -300,7 +341,7 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
     ...(namespace ? { orchestratorName: namespace } : {}),
     // Where an http Effect runs (ADR-0068): the Instance Effector's headless Service. `jr2 up`
     // converges it whenever a registered Machine carries an http Effect.
-    ...(namespace ? { instanceEffector: `${INSTANCE_EFFECTOR}.${namespace}.svc:${EFFECTOR_PORT}` } : {}),
+    ...(instanceEffector !== undefined ? { instanceEffector } : {}),
     // Where a push, a file-body http or a credentialed command runs (ADR-0068): a Sandbox's Effector, by
     // the headless Service the provision writes beside it when `jr2 up` placed an Effect there.
     ...(namespace
@@ -311,6 +352,14 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
       : {}),
   });
   held = inst.heldMachines;
+  for (const watched of [digests, hookDigests]) {
+    if (!watched) continue;
+    const close = inst.close;
+    inst.close = async () => {
+      watched.stop();
+      await close();
+    };
+  }
   // The watch ends with the instance: its stream is the one thing here that never settles alone.
   if (watch) {
     const close = inst.close;