@jr2/orchestrator 0.4.1 → 0.6.0

package/src/custodian.lua

@@ -10,15 +10,18 @@
 --
 -- Four roles, one per route family, read from the route's metadata:
 --
---   control    the Harness's Menu and the ask, plain HTTP on loopback, toward the Orchestrator
+--   control    toward the Orchestrator, plain HTTP: the agent routes on the control socket, and
+--              the ask on the loopback fetch listener (ADR-0076). Each listener has only its own
+--              routes, so a route of the other one gets the deny route's 404
 --   egress     the CONNECT listener: dial guard, then tunnel or hand to an intercept listener
 --   intercept  one bound host, TLS already ended: swap the Stand-in, strip the rest
 --   health     the kubelet's probe
 
 local VALUES = "/etc/jr2/custodian/values/"
 
--- The value of one held secret, read once. One trailing line end is taken off, because
--- `kubectl create secret --from-file` writes one; anything else a header cannot carry stops us.
+-- The value of one held secret, or its Stand-in, read once. One trailing line end is taken off,
+-- because `kubectl create secret --from-file` writes one; anything else a header cannot carry stops
+-- us. The line names the file, never what it holds.
 local function load(name)
   local f = io.open(VALUES .. name, "rb")
   if f == nil then
@@ -36,13 +39,20 @@ local function load(name)
   return v
 end
 
+-- Every Stand-in is secret but the fetch Stand-in (ADR-0059, ADR-0076): the pod's maker minted it,
+-- and it is a value too, read from `<NAME>.standin` beside the secret's own. The one public Stand-in
+-- rides the table (`standIn`), because `jr2-upload-pack` holds it as a constant.
 local STAND_IN = {}
 local VALUE = {}
 for _, s in ipairs(HELD.secrets) do
-  STAND_IN[s.name] = "jr2-held-" .. s.name
+  STAND_IN[s.name] = s.standIn or load(s.name .. ".standin")
   VALUE[s.name] = load(s.name)
 end
 
+-- The slot the Harness states on a control request (ADR-0076). It goes to the Orchestrator on a
+-- control route, unchanged, and to no other host.
+local SLOT_HEADER = "x-jr2-slot"
+
 -- The headers every bound target treats as a credential (`CREDENTIAL_HEADERS`, held-secrets.ts).
 local CREDENTIAL = {}
 for _, h in ipairs(HELD.credential) do CREDENTIAL[h] = true end
@@ -258,7 +268,7 @@ local function intercept(handle, headers, target)
   if path:lower():find("%%2[ef]") then
     return refuse(handle, 400, "path", "an encoded / or . in the path")
   end
-  for _, h in ipairs({ "te", "trailer", "keep-alive", "proxy-connection" }) do headers:remove(h) end
+  for _, h in ipairs({ "te", "trailer", "keep-alive", "proxy-connection", SLOT_HEADER }) do headers:remove(h) end
   return hold(handle, headers, HELD.targets[target], target, path)
 end
 
@@ -273,6 +283,8 @@ local function control(handle, headers, route)
         '{"error":"this pod serves no Sandbox, so it mounts no Repo to fetch (ADR-0053)"}')
     end
     headers:replace(":path", "/sandboxes/" .. sandbox .. "/fetch")
+    -- The fetch acts for the Sandbox, not for an Agent: no slot rides it.
+    headers:remove(SLOT_HEADER)
   end
   return hold(handle, headers, HELD.control, "orchestrator", headers:get(":path"))
 end

package/src/custodian.ts

@@ -21,14 +21,17 @@
 //                             so the two pod shapes cannot drift
 //
 // The Custodian is a separate container from the Harness, and that is the point: the Agent
-// executes code in the Harness container and nothing here (ADR-0005). What it holds — the
-// Sandbox token and every held secret its pod claims — is mounted into this container alone, and
-// `shareProcessNamespace` stays off, so the Agent cannot read its env, its files or its `/proc`.
+// executes code in the Harness container and nothing here (ADR-0005). What it holds — the pod's
+// control and fetch tokens and every held secret its pod claims — is mounted into this container
+// alone, and `shareProcessNamespace` stays off, so the Agent cannot read its env, its files or its
+// `/proc`. The Harness container gets the Stand-ins, every one but the public fetch Stand-in
+// secret, as files under `/run/jr2/` that no child the Harness confines can read (ADR-0076).
 
 import { readFileSync } from "node:fs";
 import type { HarnessEnvVar } from "./config.ts";
 import type { ResourceRequirements } from "./size.ts";
 import {
+  CONTROL_TOKEN_NAME,
   CREDENTIAL_HEADERS,
   SANDBOX_TOKEN_NAME,
   standIn,
@@ -37,10 +40,12 @@ import {
 } from "./held-secrets.ts";
 import {
   CA_CONFIGMAP,
-  CUSTODIAN_CONTROL_PORT,
+  CUSTODIAN_CONTROL_SOCKET,
+  CUSTODIAN_FETCH_PORT,
   CUSTODIAN_HEALTH_PORT,
   CUSTODIAN_PORT,
   CUSTODIAN_PROGRAM_KEY,
+  CUSTODIAN_SOCKET_DIR,
   HELD_CONFIGMAP,
   HELD_TLS_SECRET,
   heldSecretsSecret,
@@ -96,8 +101,60 @@ export const CUSTODIAN_ARGS: readonly string[] = [
   "warning",
 ];
 
-/** The address the Harness reaches the Custodian's control listener at: its Menu and the ask. */
-export const CUSTODIAN_URL = `http://127.0.0.1:${CUSTODIAN_CONTROL_PORT}`;
+/** The address of the Custodian's fetch listener: the ask alone (ADR-0053), which
+ * `jr2-upload-pack` makes from the domain. The Harness container gets it as `JR2_CUSTODIAN_URL`,
+ * the one `JR2_*` name that a confined process keeps (ADR-0076). The agent routes are not here. */
+export const CUSTODIAN_URL = `http://127.0.0.1:${CUSTODIAN_FETCH_PORT}`;
+
+/** The Harness env that names the Custodian's control socket ({@link CUSTODIAN_CONTROL_SOCKET}):
+ * where the Harness sends each control request — the surface read, a pick, a delivery's poll and a
+ * notice's acknowledgment (ADR-0076). A path, never a value; the domain's env does not keep it. */
+export const CUSTODIAN_SOCKET_ENV = "JR2_CUSTODIAN_SOCKET";
+/** The volume of the control socket's folder ({@link CUSTODIAN_SOCKET_DIR}): an emptyDir in the
+ * Harness container and the Custodian container, and in no other container of the pod. */
+export const CUSTODIAN_SOCKET_VOLUME = "custodian-socket";
+
+/** Where the Harness container holds its Stand-ins (ADR-0059, ADR-0076): a read-only mount that no
+ * child the Harness confines can read — the confiner denies all of `/run/jr2`. Never env. */
+export const HARNESS_CREDENTIALS = "/run/jr2";
+/** The secret control Stand-in, as the Harness reads it once at start (C1). */
+export const CONTROL_STANDIN_FILE = `${HARNESS_CREDENTIALS}/control/standin`;
+/** The directory of the held secrets' Stand-ins, one file per name: `<dir>/<NAME>`. */
+export const STANDINS_DIR = `${HARNESS_CREDENTIALS}/standins`;
+/** The Harness env that names the control Stand-in's file; its default is {@link CONTROL_STANDIN_FILE}. */
+export const CONTROL_STANDIN_FILE_ENV = "JR2_CONTROL_STANDIN_FILE";
+/** The Harness env that names the held secrets the `workspace()` grants a confined child (its
+ * `secrets` list, ADR-0076), comma-separated: names, never a value. Absent → none is granted. */
+export const GRANTED_SECRETS_ENV = "JR2_GRANTED_SECRETS";
+
+/**
+ * The keys of a pod's credentials Secret (a Sandbox's `<sandbox>-token`): the fetch token, the
+ * control token, the secret control Stand-in, and one secret Stand-in per held secret
+ * ({@link heldStandInKey}). The pod's maker mints them all. The tokens are projected into the
+ * Custodian alone; each Stand-in into the Custodian, for its swap, and the Harness container.
+ */
+export const CREDENTIAL_KEYS = {
+  fetchToken: "token",
+  controlToken: "control-token",
+  controlStandIn: "control-standin",
+} as const;
+
+/** The key of one held secret's secret Stand-in in its pod's credentials Secret. */
+export function heldStandInKey(name: string): string {
+  return `standin-${name}`;
+}
+
+/** The file of a Stand-in among the Custodian's values: beside its value, `<NAME>.standin`. A held
+ * name is an env var's, so it holds no `.` and never meets another value's file. */
+export function standInValueFile(name: string): string {
+  return `${name}.standin`;
+}
+
+/** The path prefixes each control credential may ride, after the control listener's rewrite
+ * (ADR-0076, C3): the control token on the agent routes alone, the fetch token on the fetch route
+ * alone. The program's path guard refuses either one elsewhere, before any swap. */
+export const CONTROL_PATHS = "/agents/";
+export const FETCH_PATHS = "/sandboxes/";
 
 /** Where the Orchestrator's Service is, from inside a Harness pod. */
 export type OrchestratorAddress = { host: string; port: number };
@@ -217,30 +274,72 @@ function meta(fields: Record<string, string>): Json {
   return { filter_metadata: { [LUA_FILTER]: fields } };
 }
 
-/** An upstream that never answered, said as the Custodian's own 502 (§5.4) — the host and Envoy's
- * reason, never a retry without verification. */
-function unreachable(target: string): Json {
+/** Envoy's flags for a request it did not send to the target (ADR-0059): the connection failed, no
+ * host was healthy, the DNS lookup failed. */
+export const NOT_SENT_FLAGS = ["UF", "UH", "DF"] as const;
+
+/** Envoy's flags for a request that may have reached the target before the stream ended (ADR-0059):
+ * the target closed the connection or reset the stream, Envoy reset it, a protocol error on either
+ * side (a body framing error can come after the headers went). `UMSDR` (the maximum stream
+ * duration) ends a stream that was sent. `URX` (the retry limit) comes with the last attempt's own
+ * flag (`UF,URX`, `UC,URX`), so alone it says nothing of the send; the mapper for
+ * {@link NOT_SENT_FLAGS} comes first, so `UF,URX` still reads "could not be reached". These routes
+ * set no retry policy and no `max_stream_duration`, so Envoy sets neither flag on them; they keep
+ * the union equal to ORCHESTRATOR_UNREACHABLE's. */
+export const MAY_HAVE_SENT_FLAGS = ["UC", "DPE", "UMSDR", "URX", "UPE", "UR", "LR"] as const;
+
+/** One of the Custodian's own 502s for a target that gave no answer (§5.4): the target, what
+ * jr2 knows about the request, and Envoy's reason — never a retry without verification. */
+function noAnswer(target: string, flags: readonly string[], words: string): Json {
   return {
-    mappers: [
-      {
-        filter: { response_flag_filter: { flags: ["UF", "URX", "UH", "UC", "DF", "DPE", "UMSDR"] } },
-        status_code: 502,
-        body_format_override: {
-          text_format_source: {
-            inline_string: `jr2 custodian: ${target} could not be reached: %RESPONSE_CODE_DETAILS% %UPSTREAM_TRANSPORT_FAILURE_REASON%\n`,
-          },
-        },
+    filter: { response_flag_filter: { flags: [...flags] } },
+    status_code: 502,
+    body_format_override: {
+      text_format_source: {
+        inline_string: `jr2 custodian: ${target} ${words}: %RESPONSE_CODE_DETAILS% %UPSTREAM_TRANSPORT_FAILURE_REASON%\n`,
       },
-    ],
+    },
   };
 }
 
+const NOT_REACHED = "could not be reached";
+const MAY_HAVE_REACHED = "did not answer; the request may have reached it";
+
+/**
+ * An intercepted target that gave no answer (ADR-0059). Two mappers, because the words must be
+ * true: after a `NOT_SENT_FLAGS` failure the target did not get the request, and after a
+ * `MAY_HAVE_SENT_FLAGS` one it may have it — so an Agent that sends a POST again can write twice,
+ * and the text must not tell it the first one went nowhere. One reply can carry several flags,
+ * and Envoy uses the first mapper that matches, in order: the `NOT_SENT_FLAGS` mapper is first, so
+ * a reply with `UF`, `UH` or `DF` reads "could not be reached" whatever else it carries. Without
+ * the mappers, Envoy answers each of these flags itself (503 for most, 502 for `UPE`) with a body
+ * that names no target, which a caller can read as the target's answer. No caller reads the flags;
+ * the Orchestrator route's go to the Harness, which tells "never reached" from "not known"
+ * (ADR-0002).
+ */
+function unreachable(target: string): Json {
+  return {
+    mappers: [noAnswer(target, NOT_SENT_FLAGS, NOT_REACHED), noAnswer(target, MAY_HAVE_SENT_FLAGS, MAY_HAVE_REACHED)],
+  };
+}
+
+/** The tunnel's 502 (ADR-0059): every flag, one text. Envoy answers a `CONNECT` with 200 only after
+ * its TCP connection to the target is up, and no byte of the Agent's request goes before that 200.
+ * So a 502 on the tunnel always comes before the request reached the target, whatever its flag. */
+function tunnelUnreachable(target: string): Json {
+  return { mappers: [noAnswer(target, [...NOT_SENT_FLAGS, ...MAY_HAVE_SENT_FLAGS], NOT_REACHED)] };
+}
+
 /** The Orchestrator unreachable, said so the Harness can tell it from an answer and retry the
  * surface read the way ADR-0042 asks — the one route on this pod that retries. */
 const ORCHESTRATOR_UNREACHABLE: Json = {
   mappers: [
     {
-      filter: { response_flag_filter: { flags: ["UF", "URX", "UH", "UC", "DF", "DPE", "UMSDR"] } },
+      // Envoy's own answers for a stream it reset (`UPE`, `UR`, `LR`: 503, or 502 for `UPE`) are said
+      // here too, so the Harness reads them as "not known" and not as a stopping Orchestrator's 503
+      // (ADR-0002). One text for
+      // both lists: the Harness reads the flags, not the words.
+      filter: { response_flag_filter: { flags: [...NOT_SENT_FLAGS, ...MAY_HAVE_SENT_FLAGS] } },
       status_code: 502,
       headers_to_add: [
         { header: { key: "x-jr2-custodian", value: "unreachable" }, append_action: "OVERWRITE_IF_EXISTS_OR_ADD" },
@@ -333,7 +432,7 @@ function egressReplies(): Json {
           },
         },
       },
-      ...(unreachable("%REQ(:AUTHORITY)%").mappers as Json[]),
+      ...(tunnelUnreachable("%REQ(:AUTHORITY)%").mappers as Json[]),
     ],
   };
 }
@@ -367,9 +466,14 @@ function isIpLiteral(host: string): boolean {
  * The Custodian's static bootstrap (ADR-0059): Envoy's whole configuration, rendered once per
  * converge by `jr2 up`, identical for every Harness pod of the Instance.
  *
- *   control   127.0.0.1:8081   the Menu, a pick's answer and the ask, plain HTTP, to the Orchestrator's Service —
- *                              four routes and nothing else, each swapping the Sandbox token's
- *                              Stand-in for the token (ADR-0013, ADR-0053)
+ *   control   /run/jr2/custodian/control.sock
+ *                              the four agent routes — the Menu, a pick, a delivery's poll and a
+ *                              notice's acknowledgment — plain HTTP, to the Orchestrator's Service.
+ *                              They swap the control Stand-in for the control token. A Unix socket
+ *                              in a folder that no confined process can write, so no process in
+ *                              the domain can take this listener's place (ADR-0013, ADR-0076)
+ *   fetch     127.0.0.1:8081   the ask alone, plain HTTP, to the same Service: it swaps the public
+ *                              fetch Stand-in for the fetch token (ADR-0053, ADR-0076)
  *   health    0.0.0.0:15021    GET /healthz, for the kubelet, which cannot reach loopback
  *   egress    127.0.0.1:15001  CONNECT only — present when a held secret exists; a bound target
  *                              goes to its intercept listener, every other one is tunneled
@@ -386,55 +490,76 @@ export function custodianBootstrap(manifest: HeldManifest, orchestrator: Orchest
     metadata: meta({ role: "control", route: name }),
   });
 
+  // One listener toward the Orchestrator, with its routes and the deny route after them: a route
+  // of the other listener gets the deny route's 404 here.
+  const toOrchestrator = (name: string, address: Json, routes: Json[]): Json => ({
+    name,
+    address,
+    filter_chains: [
+      {
+        filters: [
+          hcm(name, {
+            target: orchestratorTarget,
+            idleSeconds: 3600,
+            lua: true,
+            local: ORCHESTRATOR_UNREACHABLE,
+            routes: {
+              virtual_hosts: [
+                {
+                  name: "orchestrator",
+                  domains: ["*"],
+                  routes: [
+                    ...routes,
+                    {
+                      name: "deny",
+                      match: { prefix: "/" },
+                      direct_response: { status: 404 },
+                      metadata: meta({ role: "deny" }),
+                    },
+                  ],
+                },
+              ],
+            },
+          }),
+        ],
+      },
+    ],
+  });
+
   const listeners: Json[] = [
-    {
-      name: "control",
-      address: { socket_address: { address: "127.0.0.1", port_value: CUSTODIAN_CONTROL_PORT } },
-      filter_chains: [
-        {
-          filters: [
-            hcm("control", {
-              target: orchestratorTarget,
-              idleSeconds: 3600,
-              lua: true,
-              local: ORCHESTRATOR_UNREACHABLE,
-              routes: {
-                virtual_hosts: [
-                  {
-                    name: "orchestrator",
-                    domains: ["*"],
-                    routes: [
-                      // A read retries any reset. A pick or an ask retries only a reset before
-                      // it was sent: one the Orchestrator may have read is not sent twice.
-                      route("surface", "GET", "/agents/[^/]+/surface", {
-                        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
-                      }),
-                      route("events", "POST", "/agents/[^/]+/events", {
-                        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
-                      }),
-                      // An outstanding pick's answer, long-polled (ADR-0024): a read, so any reset
-                      // is retried — an Orchestrator restart mid-poll costs a retry, not the pick.
-                      route("deliveries", "GET", "/agents/[^/]+/deliveries/[^/]+", {
-                        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
-                      }),
-                      route("fetch", "POST", "/fetch", {
-                        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
-                      }),
-                      {
-                        name: "deny",
-                        match: { prefix: "/" },
-                        direct_response: { status: 404 },
-                        metadata: meta({ role: "deny" }),
-                      },
-                    ],
-                  },
-                ],
-              },
-            }),
-          ],
-        },
-      ],
-    },
+    // The agent routes, on the control socket (ADR-0076). A Unix socket, not a loopback port: a
+    // confined process can bind a free loopback port while the Custodian restarts, and it then gets
+    // the control Stand-in on the Harness's next request. It cannot make a socket under `/run/jr2`.
+    // Envoy removes a socket that a stopped Envoy left, before it binds. Mode 0666, because the
+    // Harness runs as a uid that is not Envoy's: the folder, not the mode, keeps the domain out.
+    toOrchestrator("control", { pipe: { path: CUSTODIAN_CONTROL_SOCKET, mode: 0o666 } }, [
+      // A read retries any reset. A pick retries only a reset before it was sent: one the
+      // Orchestrator may have read is not sent twice.
+      route("surface", "GET", "/agents/[^/]+/surface", {
+        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
+      }),
+      route("events", "POST", "/agents/[^/]+/events", {
+        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
+      }),
+      // An outstanding pick's answer, long-polled (ADR-0024): a read, so any reset is retried — an
+      // Orchestrator restart mid-poll costs a retry, not the pick.
+      route("deliveries", "GET", "/agents/[^/]+/deliveries/[^/]+", {
+        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
+      }),
+      // The acknowledgment of the notices a step boundary appended (ADR-0062, ADR-0076): marking
+      // them heard twice changes nothing, so any reset is retried.
+      route("notices", "POST", "/agents/[^/]+/notices", {
+        retry_policy: { retry_on: "reset,connect-failure", num_retries: 2 },
+      }),
+    ]),
+    // The ask (ADR-0053), on loopback: `jr2-upload-pack` runs in the domain, and the fetch Stand-in
+    // is public, so a process that takes this port gets nothing secret. Like a pick, it retries only
+    // a reset before it was sent.
+    toOrchestrator("fetch", { socket_address: { address: "127.0.0.1", port_value: CUSTODIAN_FETCH_PORT } }, [
+      route("fetch", "POST", "/fetch", {
+        retry_policy: { retry_on: "reset-before-request,connect-failure", num_retries: 2 },
+      }),
+    ]),
     {
       name: "health",
       address: { socket_address: { address: "0.0.0.0", port_value: CUSTODIAN_HEALTH_PORT } },
@@ -750,24 +875,40 @@ function luaList(values: readonly string[]): string {
 /**
  * The script the Custodian runs: a generated `HELD` table, then `dofile` of the fixed program
  * (`CUSTODIAN_PROGRAM`, mounted beside it from `jr2-held`). The table names every secret this pod
- * holds — the Sandbox token first, then the manifest's — with the headers and paths each may ride
- * and the targets each is bound to. It never holds a value: the program reads those from the
- * mounted files at start.
+ * holds — the control credentials first, then the manifest's — with the headers and paths each may
+ * ride and the targets each is bound to. It never holds a value, and never a secret Stand-in: the
+ * program reads both from the mounted files at start (ADR-0059).
+ *
+ * The control credentials (ADR-0076, C3): the control token, path-restricted to the agent routes,
+ * whose secret Stand-in the program reads from its values; and, on a pod that serves a Sandbox
+ * (`fetch`), the fetch token, path-restricted to the fetch route, whose Stand-in is the one public
+ * one and so rides the table. The Instance Harness and a check pod serve no fetch, and hold the
+ * control token alone.
  */
-export function custodianScript(manifest: HeldManifest): string {
+export function custodianScript(manifest: HeldManifest, opts: { fetch: boolean }): string {
+  const control = [
+    `{ name = ${lua(CONTROL_TOKEN_NAME)}, headers = { "authorization" }, paths = ${luaList([CONTROL_PATHS])} }`,
+    ...(opts.fetch
+      ? [
+          `{ name = ${lua(SANDBOX_TOKEN_NAME)}, headers = { "authorization" }, standIn = ${lua(standIn(SANDBOX_TOKEN_NAME))}, ` +
+            `paths = ${luaList([FETCH_PATHS])} }`,
+        ]
+      : []),
+  ];
   const lines = [
     "-- Generated by `jr2 up` from its pod's held manifest (ADR-0059). Names, headers, paths, targets; never a value.",
     `HELD = { secrets = {}, targets = {}, hosts = ${targetsOf(manifest).length} }`,
     `HELD.credential = ${luaList(CREDENTIAL_HEADERS)}`,
-    `HELD.secrets[1] = { name = ${lua(SANDBOX_TOKEN_NAME)}, headers = { "authorization" } }`,
-    "HELD.control = { HELD.secrets[1] }",
+    ...control.map((entry, i) => `HELD.secrets[${i + 1}] = ${entry}`),
+    `HELD.control = { ${control.map((_, i) => `HELD.secrets[${i + 1}]`).join(", ")} }`,
   ];
+  const offset = control.length + 1;
   manifest.secrets.forEach((s, i) => {
     const paths = s.paths ? `, paths = ${luaList(s.paths)}` : "";
-    lines.push(`HELD.secrets[${i + 2}] = { name = ${lua(s.name)}, headers = ${luaList(s.headers)}${paths} }`);
+    lines.push(`HELD.secrets[${i + offset}] = { name = ${lua(s.name)}, headers = ${luaList(s.headers)}${paths} }`);
   });
   for (const t of targetsOf(manifest)) {
-    const refs = t.secrets.map((s) => `HELD.secrets[${manifest.secrets.indexOf(s) + 2}]`);
+    const refs = t.secrets.map((s) => `HELD.secrets[${manifest.secrets.indexOf(s) + offset}]`);
     lines.push(`HELD.targets[${lua(t.key)}] = { ${refs.join(", ")} }`);
   }
   // `dofile`, not a copy: Envoy's Lua opens the standard libraries (the program already reads its
@@ -788,12 +929,32 @@ export type CustodianCompositionOptions = {
    * makes the pod: the Orchestrator at provision (`sandboxCustodianConfigMap`, owned by the CR),
    * `jr2 up` for the Instance Harness (`INSTANCE_CUSTODIAN_CONFIGMAP`). */
   config: string;
-  /** Where the Sandbox token lives: a Sandbox's `<name>-token` Secret, or the Instance Harness's key
-   * of `jr2-instance`. Mounted into the Custodian alone (ADR-0013). */
-  token: { secret: string; key: string };
-  /** This pod's Sandbox — the name the ask is addressed by (ADR-0053). Absent on the Instance
-   * Harness, which mounts no Repo and answers an ask by saying so. */
+  /**
+   * The pod's credentials Secret (ADR-0076): its control token, its secret control Stand-in, its
+   * fetch token (a Sandbox alone) and one secret Stand-in per held secret, under
+   * {@link CREDENTIAL_KEYS} and {@link heldStandInKey} — a key may be renamed here. The pod's maker
+   * mints them: the Orchestrator a Sandbox's (`<sandbox>-token`), `jr2 up` the Instance Harness's
+   * and a check pod's. The tokens are mounted into the Custodian alone (ADR-0013); each Stand-in
+   * into the Custodian and the Harness container, as files.
+   */
+  credentials: {
+    secret: string;
+    keys?: Partial<Record<keyof typeof CREDENTIAL_KEYS, string>>;
+  };
+  /** This pod's Sandbox — the name the ask is addressed by (ADR-0053), and the reason the pod holds
+   * a fetch token. Absent on the Instance Harness and a check pod, which mount no Repo and answer an
+   * ask by saying so. */
   sandbox?: string;
+  /** The held secrets the `workspace()` grants its confined children (its `secrets` list, ADR-0076):
+   * the Harness puts their Stand-ins, and only theirs, in a child's env. Names the manifest does not
+   * hold are left out. Absent → none. */
+  granted?: readonly string[];
+  /** The names of the Instance objects that this Custodian reads in place of the defaults. The
+   * defaults are the Instance's own: `pod`'s literal values (`heldSecretsSecret(pod)`),
+   * `jr2-held-tls`, `jr2-ca`, and the program in `jr2-held`.
+   * The check pod (ADR-0019) reads its own copies, so a check pod writes nothing that a running pod
+   * of the Instance reads. */
+  reads?: { literals: string; tls: string; trust: string; program: string };
   /** The Instance ships a `harness.caBundle` (ADR-0020). */
   caBundle: boolean;
   /** The Custodian container's resources (ADR-0060) — the placement's to choose: a Sandbox's fixed
@@ -802,15 +963,24 @@ export type CustodianCompositionOptions = {
 };
 
 type Container = Record<string, unknown>;
+
+/** The Harness container's credentials volume: its Stand-ins, mounted at {@link HARNESS_CREDENTIALS}. */
+export const HARNESS_CREDENTIALS_VOLUME = "harness-credentials";
 type Volume = Record<string, unknown>;
 type VolumeMount = { name: string; mountPath: string; readOnly?: boolean };
 
 /** What one Harness pod gains from the Custodian. */
 export type CustodianComposition = {
-  /** The Harness container's env — in `env`, after `harness.env`, before the wire's gate (§5.1). In
-   * Kubernetes `env` wins over `envFrom`, so a Stand-in overrides a same-named key of any `envFrom`
-   * Secret, even one that changes after the converge. */
+  /** The Harness container's env — in `env`, after `harness.env`, before the wire's gate (§5.1):
+   * the Custodian's fetch address and control socket, the control Stand-in's file, the granted
+   * names, the proxy and the
+   * trust. Never a Stand-in: those are files ({@link HARNESS_CREDENTIALS}), so no `envFrom` key is
+   * hidden by one, and `jr2 up` refuses a held name that is a key of an `envFrom` Secret (R14). */
   harnessEnv: HarnessEnvVar[];
+  /** The Harness container's mounts: the trust bundles, its Stand-ins at {@link HARNESS_CREDENTIALS},
+   * and the control socket's folder below it. Each is read-only. A placement mounts the
+   * conversations' volume at `/run/jr2/conversations`, below the Stand-ins too: the kubelet makes
+   * the mount point of a volume that is below a projected volume (ADR-0076). */
   harnessMounts: VolumeMount[];
   custodianContainer: Container;
   volumes: Volume[];
@@ -837,16 +1007,29 @@ const CUSTODIAN_SECURITY = {
 export function custodianComposition(manifest: HeldManifest, opts: CustodianCompositionOptions): CustodianComposition {
   const held = manifest.secrets.length > 0;
   const literal = manifest.secrets.filter((s) => s.source.kind === "literal").map((s) => s.name);
+  const {
+    literals = heldSecretsSecret(opts.pod),
+    tls = HELD_TLS_SECRET,
+    trust: trustMap = CA_CONFIGMAP,
+    program = HELD_CONFIGMAP,
+  } = opts.reads ?? {};
+
+  const keys = { ...CREDENTIAL_KEYS, ...opts.credentials.keys };
+  const fetch = opts.sandbox !== undefined;
+  const heldNames = new Set(manifest.secrets.map((s) => s.name));
+  const granted = (opts.granted ?? []).filter((n) => heldNames.has(n));
 
+  // No Stand-in rides env (ADR-0059, ADR-0076): each is a file under `/run/jr2/`, below.
   const harnessEnv: HarnessEnvVar[] = [
     { name: "JR2_CUSTODIAN_URL", value: CUSTODIAN_URL },
-    { name: SANDBOX_TOKEN_NAME, value: standIn(SANDBOX_TOKEN_NAME) },
+    { name: CUSTODIAN_SOCKET_ENV, value: CUSTODIAN_CONTROL_SOCKET },
+    { name: CONTROL_STANDIN_FILE_ENV, value: CONTROL_STANDIN_FILE },
+    ...(granted.length ? [{ name: GRANTED_SECRETS_ENV, value: granted.join(",") }] : []),
   ];
   if (held) {
     const proxy = `http://127.0.0.1:${CUSTODIAN_PORT}`;
     const noProxy = "localhost,127.0.0.1,::1";
     harnessEnv.push(
-      ...manifest.secrets.map((s) => ({ name: s.name, value: standIn(s.name) })),
       { name: "HTTPS_PROXY", value: proxy },
       { name: "https_proxy", value: proxy },
       { name: "NO_PROXY", value: noProxy },
@@ -869,10 +1052,21 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
         // Group-readable, for the pod's fsGroup: the Custodian runs as Envoy's own uid.
         defaultMode: 0o440,
         sources: [
-          { secret: { name: opts.token.secret, items: [{ key: opts.token.key, path: SANDBOX_TOKEN_NAME }] } },
-          ...(literal.length
-            ? [{ secret: { name: heldSecretsSecret(opts.pod), items: literal.map((n) => ({ key: n, path: n })) } }]
-            : []),
+          // The control credentials (ADR-0076): the control token beside its secret Stand-in, and
+          // on a Sandbox the fetch token, whose Stand-in is public and rides the script. Then each
+          // held secret's secret Stand-in, beside the value the Custodian swaps it for.
+          {
+            secret: {
+              name: opts.credentials.secret,
+              items: [
+                { key: keys.controlToken, path: CONTROL_TOKEN_NAME },
+                { key: keys.controlStandIn, path: standInValueFile(CONTROL_TOKEN_NAME) },
+                ...(fetch ? [{ key: keys.fetchToken, path: SANDBOX_TOKEN_NAME }] : []),
+                ...manifest.secrets.map((s) => ({ key: heldStandInKey(s.name), path: standInValueFile(s.name) })),
+              ],
+            },
+          },
+          ...(literal.length ? [{ secret: { name: literals, items: literal.map((n) => ({ key: n, path: n })) } }] : []),
           ...manifest.secrets.flatMap((s) =>
             s.source.kind === "secret"
               ? [{ secret: { name: s.source.secret, items: [{ key: s.source.key, path: s.name }] } }]
@@ -896,20 +1090,45 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
               ],
             },
           },
-          { configMap: { name: HELD_CONFIGMAP, items: [{ key: CUSTODIAN_PROGRAM_KEY, path: CUSTODIAN_PROGRAM_KEY }] } },
+          { configMap: { name: program, items: [{ key: CUSTODIAN_PROGRAM_KEY, path: CUSTODIAN_PROGRAM_KEY }] } },
         ],
       },
     },
     ...(held
       ? [
-          { name: "custodian-tls", secret: { secretName: HELD_TLS_SECRET, defaultMode: 0o440 } },
+          { name: "custodian-tls", secret: { secretName: tls, defaultMode: 0o440 } },
           {
             name: "custodian-trust",
-            configMap: { name: CA_CONFIGMAP, items: [{ key: "upstream.crt", path: "upstream.crt" }] },
+            configMap: { name: trustMap, items: [{ key: "upstream.crt", path: "upstream.crt" }] },
           },
         ]
       : []),
-    ...(trust ? [{ name: "ca", configMap: { name: CA_CONFIGMAP } }] : []),
+    ...(trust ? [{ name: "ca", configMap: { name: trustMap } }] : []),
+    // The control socket's folder (ADR-0076): the Custodian makes the socket, and the Harness
+    // connects to it. It goes with the pod, and it outlives a restart of either container, so the
+    // socket's path never changes.
+    { name: CUSTODIAN_SOCKET_VOLUME, emptyDir: {} },
+    // The Harness container's Stand-ins (ADR-0076): the secret control Stand-in and each held
+    // secret's, as files under `/run/jr2/`, which the confiner denies to every child the Harness
+    // starts. Group-readable for the pod's fsGroup — the Harness runs as no fixed uid, and the
+    // kubelet writes the files as root — so 0440 is the least mode the Harness can read.
+    {
+      name: HARNESS_CREDENTIALS_VOLUME,
+      projected: {
+        defaultMode: 0o440,
+        sources: [
+          {
+            secret: {
+              name: opts.credentials.secret,
+              items: [
+                { key: keys.controlStandIn, path: "control/standin" },
+                ...manifest.secrets.map((s) => ({ key: heldStandInKey(s.name), path: `standins/${s.name}` })),
+              ],
+            },
+          },
+        ],
+      },
+    },
   ];
 
   const custodianContainer: Container = {
@@ -922,6 +1141,8 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
     volumeMounts: [
       { name: "custodian-values", mountPath: CUSTODIAN_VALUES, readOnly: true },
       { name: "custodian-config", mountPath: CUSTODIAN_CONFIG, readOnly: true },
+      // The one folder that the Custodian writes: where it makes its control socket.
+      { name: CUSTODIAN_SOCKET_VOLUME, mountPath: CUSTODIAN_SOCKET_DIR },
       ...(held
         ? [
             { name: "custodian-tls", mountPath: CUSTODIAN_TLS, readOnly: true },
@@ -944,7 +1165,12 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
 
   return {
     harnessEnv,
-    harnessMounts: trust ? [{ name: "ca", mountPath: CA_MOUNT, readOnly: true }] : [],
+    harnessMounts: [
+      ...(trust ? [{ name: "ca", mountPath: CA_MOUNT, readOnly: true }] : []),
+      { name: HARNESS_CREDENTIALS_VOLUME, mountPath: HARNESS_CREDENTIALS, readOnly: true },
+      // Read-only: the Harness connects to the socket, and nothing in its container writes here.
+      { name: CUSTODIAN_SOCKET_VOLUME, mountPath: CUSTODIAN_SOCKET_DIR, readOnly: true },
+    ],
     custodianContainer,
     volumes,
   };