@jr2/orchestrator 0.5.1 → 0.7.0

package/src/held-secrets.ts

@@ -9,7 +9,8 @@
 //
 // This module is the pure half, shared by every seat that needs it:
 //
-//   standIn(name)        the value the Harness sees — deterministic and public
+//   heldStandIn(...)     a held secret's Stand-in, minted per pod by the pod's maker — secret
+//   standIn(name)        the fetch Stand-in's form — deterministic and public, for that one alone
 //   heldSecretsOf(...)   `jr2 up`'s normalization of the claimed entries: every refusal (R1–R13),
 //                        every warning, and the engine-neutral bindings each pod's manifest
 //                        (`held-<pod>.json`) takes its own from
@@ -22,24 +23,47 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { isIP } from "node:net";
-import type { JR2Config, HarnessEnvVar } from "./config.ts";
-import { MODEL_KEYS, MODEL_KEY_PROVIDERS, SIGNING_CREDENTIALS } from "./model-keys.ts";
-import { HELD_CA_SECRET, HELD_SECRETS_SECRET, HELD_TLS_SECRET, INSTANCE_EFFECTOR, INSTANCE_SECRET } from "./names.ts";
+import { isStdioServer, type JR2Config, type HarnessEnvVar } from "./config.ts";
+import {
+  CREDENTIAL_FILES,
+  DOMAIN_WRITABLE_ROOTS,
+  MODEL_KEYS,
+  MODEL_KEY_PROVIDERS,
+  SIGNING_CREDENTIALS,
+} from "./model-keys.ts";
+import {
+  HELD_CA_SECRET,
+  HELD_SECRETS_SECRET,
+  HELD_TLS_SECRET,
+  INSTANCE_EFFECTOR,
+  INSTANCE_HARNESS_SERVICE,
+  INSTANCE_SECRET,
+} from "./names.ts";
 import type { PlacementRoute } from "./parts.ts";
+import { sign } from "./tokens.ts";
 
 /** The kit's Secrets no Harness container may read (R13): the Instance token and signing key, each
  * pod's literal held values, the leaves, the CA, and every Effector's (ADR-0068) — the Instance
  * Effector's Effect secrets and key, each Workspace's Sandbox Effector Secret (`jr2-effector-<pod>`),
  * each Sandbox's Effector key (`<sandbox>-effector`), and each `git.credentials` entry's clone and
- * push Secrets (`jr2-git-<hash>`, `jr2-git-push-<hash>`, ADR-0051). */
-const KIT_SECRETS: readonly string[] = [INSTANCE_SECRET, HELD_TLS_SECRET, HELD_CA_SECRET, INSTANCE_EFFECTOR];
+ * push Secrets (`jr2-git-<hash>`, `jr2-git-push-<hash>`, ADR-0051) — and each pod's own credentials
+ * (ADR-0076): the Instance Harness's (`jr2-instance-harness-token`) and each Sandbox's
+ * (`<sandbox>-token`), which hold the real control token beside the Stand-ins. */
+const KIT_SECRETS: readonly string[] = [
+  INSTANCE_SECRET,
+  HELD_TLS_SECRET,
+  HELD_CA_SECRET,
+  INSTANCE_EFFECTOR,
+  `${INSTANCE_HARNESS_SERVICE}-token`,
+];
 const KIT_SECRET_PREFIXES: readonly string[] = [`${HELD_SECRETS_SECRET}-`, "jr2-effector-", "jr2-git-"];
 const isKitSecret = (name: string): boolean =>
   KIT_SECRETS.includes(name) ||
   name === HELD_SECRETS_SECRET ||
   KIT_SECRET_PREFIXES.some((p) => name.startsWith(p)) ||
-  // A Sandbox's own Effector key: every Sandbox's name starts `ws-` (`workspaceName`).
-  (name.startsWith("ws-") && name.endsWith("-effector"));
+  // A Sandbox's own Effector key and its credentials: every Sandbox's name starts `ws-`
+  // (`workspaceName`).
+  (name.startsWith("ws-") && (name.endsWith("-effector") || name.endsWith("-token")));
 
 /**
  * The pod key of one Workspace (ADR-0059): its registered workflow and the placement route to its
@@ -70,18 +94,36 @@ export function providerClaims(config: JR2Config, models: readonly string[]): st
 }
 
 /**
- * The Stand-in for one held secret: what its env var holds in the Harness container.
- *
- * Deterministic and public — it is not a secret, the Agent reads it from its env, and it means
- * something only to the Custodian and only toward a bound host. Unique per name, so one request can
- * carry two secrets' Stand-ins and the Custodian can tell them apart. ASCII letters, digits, `-`
- * and `_` only, so it is a valid header and env value; and it never contains `sk-ant-oat`, which pi
- * reads as an Anthropic OAuth token and answers with different auth headers.
+ * The PUBLIC Stand-in form, `jr2-held-<NAME>`. Since ADR-0076 one Stand-in alone takes it: the fetch
+ * Stand-in, `standIn("JR2_SANDBOX_TOKEN")`, which `jr2-upload-pack` holds as a constant and the
+ * Custodian swaps on the fetch route alone. Every other Stand-in is secret ({@link heldStandIn}).
  */
 export function standIn(name: string): string {
   return `jr2-held-${name}`;
 }
 
+/** What a Stand-in must never contain (ADR-0059): pi reads a key with it as an Anthropic OAuth
+ * token, and answers with different auth headers. */
+const OAUTH_MARK = "sk-ant-oat";
+
+/**
+ * The SECRET Stand-in of one held secret in one pod (ADR-0059, ADR-0076): what the Harness process
+ * holds for it, as the file `/run/jr2/standins/<NAME>`, and what the Custodian of that pod swaps for
+ * the value. `jr2-held-<NAME>.<hmac>` — the readable prefix keeps a log scrub's pattern, and the
+ * HMAC under the signing key makes it unguessable, so Workspace code can spend only the secrets its
+ * `workspace()` grants. `pod` is the Sandbox's name, or `instance` for the Instance Harness. The
+ * pod's maker mints it: the Orchestrator for a Sandbox, `jr2 up` for the Instance Harness and a
+ * check pod. ASCII letters, digits, `-`, `_` and `.` only, so it is a valid header and env value,
+ * and it never contains `sk-ant-oat`: a signature that would is signed again under a counter.
+ */
+export function heldStandIn(key: Buffer, pod: string, name: string): string {
+  for (let n = 0; ; n++) {
+    const domain = `held-standin:${pod}/${name}${n === 0 ? "" : `#${n}`}`;
+    const value = `${standIn(name)}.${sign(key, domain)}`;
+    if (!value.includes(OAUTH_MARK)) return value;
+  }
+}
+
 /** The request headers a Stand-in is swapped in when a held secret names none — the four places a
  * model API carries its key: `Authorization: Bearer` (OpenAI-compatible, `ANTHROPIC_AUTH_TOKEN`),
  * `x-api-key` (Anthropic), `x-goog-api-key` (Gemini), `api-key` (Azure). */
@@ -99,10 +141,15 @@ export const CREDENTIAL_HEADERS: readonly string[] = [...DEFAULT_CREDENTIAL_HEAD
 /** The env var the custom provider's key rides as (ADR-0018) — held since ADR-0059, and the kit's. */
 export const PROVIDER_KEY_NAME = "JR2_PROVIDER_API_KEY";
 
-/** The Sandbox token's env var (ADR-0013) — a held secret of the kit's own, bound to the
- * Orchestrator (ADR-0059). The Harness container holds its Stand-in; the Custodian holds the token. */
+/** The fetch token's held name (ADR-0013, ADR-0076) — a held secret of the kit's own, bound to the
+ * Orchestrator's fetch route (ADR-0059). Its Stand-in is the public `jr2-held-JR2_SANDBOX_TOKEN`,
+ * which `jr2-upload-pack` holds; the Custodian holds the token. */
 export const SANDBOX_TOKEN_NAME = "JR2_SANDBOX_TOKEN";
 
+/** The control token's held name (ADR-0076) — the kit's own, bound to the agent routes. Its Stand-in
+ * is secret: the Harness process alone holds it, as `/run/jr2/control/standin`. */
+export const CONTROL_TOKEN_NAME = "JR2_CONTROL_TOKEN";
+
 /** The env names the mechanism owns on a Harness container (ADR-0059): the proxy, the trust
  * bundles, and every `JR2_` name. A held secret may not choose them, and while a held secret exists,
  * `harness.env` may not either — the Custodian cannot chain to a second proxy yet (R11). */
@@ -233,6 +280,52 @@ export function heldSecretsOf(
     catalogHosts.set(id, target.port === 443 ? target.host : `${target.host}:${target.port}`);
   }
 
+  // R7 for an MCP server (ADR-0079): one with a `secret` needs an https url, because the Custodian
+  // carries TLS only. Its url's host is the default binding of the secret it names (`hostsOf`).
+  const serverHosts = new Map<string, Array<{ server: string; host: string; port: number; path: string }>>();
+  for (const [server, declared] of Object.entries(config.mcp ?? {})) {
+    if (isStdioServer(declared) || declared.secret === undefined || !claimed.has(declared.secret)) continue;
+    const target = httpsTarget(declared.url);
+    if (!target) {
+      throw new Error(
+        `mcp.${server}.url must be an https:// URL — the server has a secret, ${declared.secret}, and the Custodian ` +
+          "carries TLS only (ADR-0059, ADR-0079). Read it from .env: " +
+          `mcp: { "${server}": { url: process.env.${server.toUpperCase().replace(/-/g, "_")}_URL ?? "", secret: "${declared.secret}" } }`,
+      );
+    }
+    const path = new URL(declared.url).pathname || "/";
+    serverHosts.set(declared.secret, [...(serverHosts.get(declared.secret) ?? []), { server, ...target, path }]);
+  }
+
+  // jr2's own names (ADR-0076): the Harness's start takes a `JR2_` name from jr2's composition alone,
+  // and refuses to start on an envFrom key that starts with `JR2_` (`effector nocore --harness-env`).
+  // A user's `JR2_MENU_ONLY` or `JR2_START_ENV` would turn the domain off or replace its env.
+  for (const [i, v] of env.entries()) {
+    if (v.name.startsWith("JR2_")) {
+      throw new Error(
+        `harness.env[${i}] sets ${v.name}: JR2_ names are jr2's own, and the Harness takes them from jr2 alone ` +
+          "(ADR-0076). Name the env var your program reads.",
+      );
+    }
+  }
+  for (const [i, ref] of (harness.envFrom ?? []).entries()) {
+    const lookup = ref.secretRef
+      ? `secret/${ref.secretRef.name}`
+      : ref.configMapRef
+        ? `configmap/${ref.configMapRef.name}`
+        : "";
+    const own = (lookups.envFromKeys?.get(lookup) ?? [])
+      .map((key) => (ref.prefix ?? "") + key)
+      .find((key) => key.startsWith("JR2_"));
+    if (own !== undefined) {
+      const where = ref.secretRef ? `Secret "${ref.secretRef.name}"` : `ConfigMap "${ref.configMapRef?.name}"`;
+      throw new Error(
+        `harness.envFrom[${i}] loads ${where}, which carries ${own}: JR2_ names are jr2's own, and the Harness ` +
+          "does not start with one from envFrom (ADR-0076). Drop the key, or give the source a prefix.",
+      );
+    }
+  }
+
   // R1: a known model key the Agent could read.
   for (const [i, v] of env.entries()) {
     if (!(v.name in MODEL_KEYS)) continue;
@@ -268,6 +361,39 @@ export function heldSecretsOf(
     }
   }
 
+  // A credential file that the Harness process reads (ADR-0076): never one that the domain writes.
+  for (const [i, v] of env.entries()) {
+    if (!CREDENTIAL_FILES.includes(v.name)) continue;
+    const path = v.value;
+    if (path !== undefined) {
+      const writable = DOMAIN_WRITABLE_ROOTS.find((root) => path === root || path.startsWith(`${root}/`));
+      if (!path.startsWith("/") || writable !== undefined || path.split("/").includes("..")) {
+        throw new Error(
+          `harness.env[${i}] sets ${v.name} to "${path}", ${writable !== undefined ? `which is in ${writable}, a folder the Agent's code writes` : "which is not an absolute path"}: the Harness process reads that file, and code that writes it acts outside the Agent's confinement (ADR-0076). Point it at a file of the image that the Sandbox's user cannot write.`,
+        );
+      }
+    }
+    warnings.push(
+      `harness.env sets ${v.name}: the Harness process reads ${path !== undefined ? `"${path}"` : "the file it names"}, ` +
+        "so the Sandbox's user must not be able to write it — a folder of the image that the user owns is one the " +
+        "Agent's code writes (ADR-0076)",
+    );
+  }
+  for (const [i, ref] of (harness.envFrom ?? []).entries()) {
+    const lookup = ref.secretRef
+      ? `secret/${ref.secretRef.name}`
+      : ref.configMapRef
+        ? `configmap/${ref.configMapRef.name}`
+        : "";
+    for (const key of (lookups.envFromKeys?.get(lookup) ?? []).map((k) => (ref.prefix ?? "") + k)) {
+      if (!CREDENTIAL_FILES.includes(key)) continue;
+      warnings.push(
+        `harness.envFrom[${i}] sets ${key}: the Harness process reads the file it names, so the Sandbox's user must ` +
+          "not be able to write it — a folder of the image that the user owns is one the Agent's code writes (ADR-0076)",
+      );
+    }
+  }
+
   type Entry = {
     at: string;
     name: string;
@@ -344,8 +470,10 @@ export function heldSecretsOf(
     const source = sourceOf(e, lookups);
     if (source.kind === "literal") values[e.name] = e.value as string;
 
-    // R6
-    const headers = [...(e.headers ?? DEFAULT_CREDENTIAL_HEADERS)];
+    // R6. An MCP server's secret with no binding goes in `authorization` alone (ADR-0079): the
+    // Harness sends `Authorization: Bearer <Stand-in>`.
+    const mcpDefault = e.hosts === undefined && e.headers === undefined && serverHosts.has(e.name);
+    const headers = [...(e.headers ?? (mcpDefault ? ["authorization"] : DEFAULT_CREDENTIAL_HEADERS))];
     const seenHeader = new Set<string>();
     for (const [j, header] of headers.entries()) {
       if (!HEADER_TOKEN.test(header) || FRAMING_HEADERS.has(header) || header.startsWith("proxy-")) {
@@ -358,6 +486,16 @@ export function heldSecretsOf(
       if (seenHeader.has(header)) throw new Error(`${e.at}.headers lists "${header}" twice (ADR-0059)`);
       seenHeader.add(header);
     }
+    // R6 for an MCP server's secret (ADR-0079): the Harness sends its Stand-in in `authorization`
+    // alone, so a binding without that header removes it on each call.
+    for (const s of serverHosts.get(e.name) ?? []) {
+      if (headers.includes("authorization")) break;
+      throw new Error(
+        `${e.at}.headers leaves out "authorization", where the Harness sends the Stand-in of ${e.name} to ` +
+          `mcp.${s.server}.url — each call of that server would arrive with no credential. Add it, or drop headers ` +
+          "to take that default (ADR-0059, ADR-0079)",
+      );
+    }
 
     // R12
     const paths = e.paths === undefined ? undefined : [...e.paths];
@@ -369,9 +507,18 @@ export function heldSecretsOf(
         );
       }
     }
+    // R12 for an MCP server's secret (ADR-0079): every call goes to the url's path, so `paths` must
+    // cover it, by the prefix rule the Custodian applies.
+    for (const s of serverHosts.get(e.name) ?? []) {
+      if (paths === undefined || paths.some((p) => pathCovers(p, s.path))) continue;
+      throw new Error(
+        `${e.at}.paths does not cover ${s.path}, the path of mcp.${s.server}.url, whose secret ${e.name} is — ` +
+          `each call of that server would be refused with 403. Add "${s.path}", or drop paths (ADR-0059, ADR-0079)`,
+      );
+    }
 
     // R5 (+ the §3.4 default and R9)
-    const hosts = hostsOf(e, catalogHosts, lookups.models ?? []);
+    const hosts = hostsOf(e, catalogHosts, lookups.models ?? [], serverHosts.get(e.name) ?? []);
     secrets.push({
       name: e.name,
       source,
@@ -429,24 +576,6 @@ export function heldSecretsOf(
     }
   }
 
-  // R5: one header on one host names one secret.
-  const byTarget = new Map<string, { name: string; headers: string[] }[]>();
-  for (const s of secrets) {
-    for (const h of s.hosts) {
-      const key = `${h.host}:${h.port}`;
-      for (const other of byTarget.get(key) ?? []) {
-        const shared = s.headers.filter((header) => other.headers.includes(header));
-        if (shared.length > 0) {
-          throw new Error(
-            `${s.name} and ${other.name} are both bound to ${key} in header ${shared.join(", ")} — one header on ` +
-              "one host carries one secret; give each its own `headers` (ADR-0059)",
-          );
-        }
-      }
-      byTarget.set(key, [...(byTarget.get(key) ?? []), { name: s.name, headers: s.headers }]);
-    }
-  }
-
   return { manifest: { version: 1, secrets }, values, warnings };
 }
 
@@ -495,16 +624,31 @@ export function sourceOf(
 
 /** R5 and R9: where one secret may go. A known model key with no `hosts` goes where its provider's
  * calls go — the catalog override's host, else the table's — so the key and the calls read one
- * config and cannot drift. */
+ * config and cannot drift. An MCP server's secret with no `hosts` goes to the host of the url of
+ * each server that names it (ADR-0079), for the same reason. */
 function hostsOf(
   e: { at: string; name: string; hosts?: readonly string[] },
   catalogHosts: ReadonlyMap<string, string>,
   models: readonly string[],
+  servers: ReadonlyArray<{ server: string; host: string; port: number }>,
 ): Array<{ host: string; port: number }> {
   const known = MODEL_KEYS[e.name];
   const effective = new Map<string, string | undefined>();
   for (const provider of known?.providers ?? []) effective.set(provider, catalogHosts.get(provider) ?? known?.host);
 
+  if (e.hosts === undefined && servers.length > 0) {
+    const out: Array<{ host: string; port: number }> = [];
+    const add = (t: { host: string; port: number }) => {
+      if (!out.some((o) => o.host === t.host && o.port === t.port)) out.push({ host: t.host, port: t.port });
+    };
+    for (const s of servers) add(s);
+    // A model key that an MCP server also names keeps its provider's host beside the servers'.
+    const defaults = new Set(effective.values());
+    const only = defaults.size === 1 ? [...defaults][0] : undefined;
+    if (only !== undefined) add(parseTarget(`${e.at}.hosts`, only));
+    return out;
+  }
+
   if (e.hosts === undefined || e.hosts.length === 0) {
     const defaults = new Set(effective.values());
     const only = defaults.size === 1 ? [...defaults][0] : undefined;
@@ -527,9 +671,23 @@ function hostsOf(
         `or drop hosts to take that default (ADR-0059)`,
     );
   }
+  for (const s of servers) {
+    if (targets.some((t) => t.host === s.host && t.port === s.port)) continue;
+    throw new Error(
+      `${e.at}.hosts leaves out ${s.host}${s.port === 443 ? "" : `:${s.port}`}, the host of mcp.${s.server}.url, ` +
+        `whose secret ${e.name} is — each call of that server would arrive with the Stand-in and fail with 401. ` +
+        "Add it, or drop hosts to take that default (ADR-0059, ADR-0079)",
+    );
+  }
   return targets;
 }
 
+/** Whether the `paths` entry `prefix` lets a request to `path` through: the Custodian's rule — the
+ * same path, or `prefix` and then a `/` (or `prefix` ends in `/`). */
+function pathCovers(prefix: string, path: string): boolean {
+  return path === prefix || (path.startsWith(prefix) && (prefix.endsWith("/") || path.charAt(prefix.length) === "/"));
+}
+
 /** An `https://` URL's host and port, or undefined for anything else. */
 function httpsTarget(url: string): { host: string; port: number } | undefined {
   let parsed: URL;

package/src/holds.ts

@@ -31,13 +31,16 @@ export type Hold = {
   deliveryId: string;
   /** The pick's event name. */
   pick: string;
-  /** The Agent slot that picked — the Console's "held since" names it. */
+  /** The Agent slot that picked — the Console's "outstanding since" names it. */
   agent: string;
-  /** ISO time the pick was delivered: the Console's "held since". */
+  /** ISO time the pick was delivered: the Console's "outstanding since". */
   since: string;
   /** The Sandbox whose token may read the answer (ADR-0013) — the registration's, kept because the
    * answer outlives a registration that a route out of the Agent's state ends. */
   sandbox?: string;
+  /** The slot whose stated control requests may read the answer (ADR-0076) — the registration's,
+   * kept with `sandbox` for the same reason. */
+  slot?: string;
   /** The invoke id of the Agent's state when the pick was made: a re-registration of the same
    * address by another state is another Turn. */
   invokeId?: string;

package/src/hook-kinds/discord.ts

@@ -0,0 +1,92 @@
+// `@jr2/orchestrator/hooks/discord`: jr2's Discord kind, for an application's Interactions Endpoint URL.
+
+import { z } from "zod";
+import { at, defineHookKind, json } from "./index.ts";
+
+const user = z.looseObject({ id: z.string() });
+
+/** The schema of each event key. A command's name is part of its key, so `.*` covers them all. */
+export const discordEvents = {
+  "application_command.*": z.looseObject({
+    channel_id: z.string(),
+    /** In a guild. */
+    member: z.looseObject({ user }).optional(),
+    /** In a direct message. */
+    user: user.optional(),
+    data: z.looseObject({
+      name: z.string(),
+      options: z
+        .array(z.looseObject({ name: z.string(), value: z.union([z.string(), z.number(), z.boolean()]).optional() }))
+        .optional(),
+    }),
+  }),
+  message_component: z.looseObject({
+    member: z.looseObject({ user }).optional(),
+    user: user.optional(),
+    data: z.looseObject({ custom_id: z.string() }),
+    message: z.looseObject({ id: z.string() }),
+  }),
+};
+
+const text = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
+
+/** The interaction types that this kind reads (Discord's numbers). */
+const PING = 1;
+const APPLICATION_COMMAND = 2;
+const MESSAGE_COMPONENT = 3;
+
+/**
+ * - verifier: `ed25519` over `<X-Signature-Timestamp><raw body>`, `X-Signature-Ed25519` in hex,
+ *   checked against the application's PUBLIC key in the Orchestrator. The signature covers the
+ *   timestamp, so the kind gives it as `at`. Discord states no window; the door's 300 s window
+ *   applies to each signed `at`, so it applies here too.
+ * - handshake: `PING` (type 1) gets `{ type: 1 }` (PONG).
+ * - event keys: `application_command.<data.name>` (type 2), `message_component` (type 3). Another
+ *   type (an autocomplete, a modal) gets the key `interaction.<type>`, which has no schema, so it
+ *   reaches nothing.
+ * - delivery id: the interaction's `id`. `onBehalfOf`: `member.user.id`, or `user.id` in a direct
+ *   message. (Discord's docs do not say that Discord sends an interaction again.)
+ * - who reads the answer: a person, always.
+ * - answer: `{ type: 4, data: { content, flags: 64 } }`, an ephemeral message. Discord shows
+ *   markdown, not HTML, so the text needs no escape. Text limit: 2000 characters.
+ */
+export const discord = defineHookKind({
+  api: 1,
+  id: "discord",
+  events: discordEvents,
+  verify: {
+    ed25519: {
+      signed: (req) => {
+        const ts = req.headers["x-signature-timestamp"];
+        const sig = req.headers["x-signature-ed25519"];
+        if (ts === undefined || !/^\d+$/.test(ts) || sig === undefined) {
+          return { unsigned: "no Discord signature or timestamp" };
+        }
+        return { bytes: [ts, req.body], signature: { hex: sig }, at: Number(ts) };
+      },
+    },
+  },
+  read: (req) => {
+    const p = json(req);
+    const type = at(p, "type");
+    if (type === PING) return { handshake: { body: { type: 1 } } };
+    const id = text(at(p, "id"));
+    if (id === undefined) throw new Error("the interaction has no id");
+    const by = text(at(p, "member.user.id")) ?? text(at(p, "user.id"));
+    const key =
+      type === APPLICATION_COMMAND
+        ? `application_command.${text(at(p, "data.name")) ?? ""}`
+        : type === MESSAGE_COMPONENT
+          ? "message_component"
+          : `interaction.${String(type)}`;
+    return { key, id, payload: p, ...(by ? { onBehalfOf: by } : {}), readBy: "person" };
+  },
+  answer: (t) => ({ body: { type: 4, data: { content: t, flags: 64 } } }),
+  maxText: 2000,
+});
+
+declare module "./index.ts" {
+  interface HookKinds {
+    discord: typeof discord;
+  }
+}

package/src/hook-kinds/door.ts

@@ -0,0 +1,107 @@
+// `hook-kinds/door.ts`: what the Hook's door reads from a Hook and a kind. The package does not
+// export it, because it is NOT part of a kind's interface: a kind imports `@jr2/orchestrator/hooks` only. It is here because
+// `defineHookKind` decides the shape of a Hook, so the code that reads a Hook is beside it.
+
+import type { z } from "zod";
+import { HOOK } from "./hook.ts";
+import { HOOK_KIND_APIS, type Hook, type HookKind, type HookParts, type HookRequest, type Signed } from "./index.ts";
+
+/** True when `value` is a Hook that a kind's constructor made. */
+export function isHook(value: unknown): value is Hook {
+  return typeof value === "object" && value !== null && Object.hasOwn(value, HOOK);
+}
+
+/** The kind, the credential and `may` of a Hook. It throws when `hook` is not a Hook. */
+export function hookParts<K extends HookKind>(hook: Hook<K>): HookParts<K> {
+  if (!isHook(hook)) throw new Error("not a Hook: make it with its kind, such as github({ secret, may })");
+  return hook[HOOK];
+}
+
+/**
+ * The request that the door gives a kind. Header names become lowercase. A header with more than
+ * one value keeps them joined by ", ", as `Headers` does. `strip` names a header that the door
+ * removes (the `token` verifier's header), so no code of the kind can read it.
+ */
+export function hookRequest(
+  headers: Headers | { readonly [name: string]: string | readonly string[] | undefined },
+  body: Uint8Array,
+  strip?: string,
+): HookRequest {
+  const out: { [name: string]: string } = Object.create(null) as { [name: string]: string };
+  const entries: Iterable<[string, string | readonly string[] | undefined]> =
+    headers instanceof Headers ? headers.entries() : Object.entries(headers);
+  for (const [name, value] of entries) {
+    if (value === undefined) continue;
+    const lower = name.toLowerCase();
+    const text = typeof value === "string" ? value : value.join(", ");
+    out[lower] = Object.hasOwn(out, lower) ? `${out[lower]}, ${text}` : text;
+  }
+  if (strip !== undefined) delete out[strip.toLowerCase()];
+  const bytes = new Uint8Array(body);
+  return Object.freeze({
+    headers: Object.freeze(out),
+    body: bytes,
+    text: new TextDecoder("utf-8").decode(bytes),
+  });
+}
+
+/**
+ * The schema of an event key: the exact key, else the longest `prefix.*` key that the event key
+ * starts with (`block_actions.*` for `block_actions.approve`). `undefined` when the kind names no
+ * schema for the key: the door does not parse such a delivery, and it reaches nothing.
+ */
+export function schemaFor(kind: HookKind, key: string): z.ZodType | undefined {
+  if (Object.hasOwn(kind.events, key)) return kind.events[key];
+  let best: { readonly length: number; readonly schema: z.ZodType } | undefined;
+  for (const [k, schema] of Object.entries(kind.events)) {
+    if (!k.endsWith(".*")) continue;
+    const prefix = k.slice(0, -1); // keeps the "."
+    if (key.length > prefix.length && key.startsWith(prefix) && (!best || prefix.length > best.length)) {
+      best = { length: prefix.length, schema };
+    }
+  }
+  return best?.schema;
+}
+
+/** The bytes that the service signed, joined. A string part is UTF-8. */
+export function signedBytes(signed: Signed): Uint8Array {
+  const parts = signed.bytes.map((b) => (typeof b === "string" ? new TextEncoder().encode(b) : b));
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let i = 0;
+  for (const p of parts) {
+    out.set(p, i);
+    i += p.length;
+  }
+  return out;
+}
+
+/** The signature as bytes, or `undefined` when its hex or base64 is not well formed. */
+export function signatureBytes(signed: Signed): Uint8Array | undefined {
+  const s = signed.signature;
+  if ("hex" in s) {
+    if (!/^(?:[0-9a-fA-F]{2})+$/.test(s.hex)) return undefined;
+    return Uint8Array.from(Buffer.from(s.hex, "hex"));
+  }
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(s.base64) || s.base64.length % 4 !== 0) return undefined;
+  return Uint8Array.from(Buffer.from(s.base64, "base64"));
+}
+
+/**
+ * The kinds of one Assembly, by id. It throws when two different kinds give one id, or when a kind
+ * states an `api` that this copy of `@jr2/orchestrator/hooks` does not know. One kind that two Hooks use is one
+ * entry.
+ */
+export function kindsById(kinds: Iterable<HookKind>): ReadonlyMap<string, HookKind> {
+  const out = new Map<string, HookKind>();
+  for (const kind of kinds) {
+    if (!HOOK_KIND_APIS.includes(kind.api)) {
+      throw new Error(`Hook kind ${kind.id} states api ${String(kind.api)}; this jr2 knows api 1 only`);
+    }
+    const had = out.get(kind.id);
+    if (had !== undefined && had !== kind) {
+      throw new Error(`two different Hook kinds have the id ${kind.id}: one id is one kind in an Assembly`);
+    }
+    out.set(kind.id, kind);
+  }
+  return out;
+}

package/src/hook-kinds/github.ts

@@ -0,0 +1,89 @@
+// `@jr2/orchestrator/hooks/github`: jr2's GitHub kind. It imports `@jr2/orchestrator/hooks` and nothing more of jr2, as a
+// kind from another package does.
+
+import { z } from "zod";
+import { defineHookKind, json, type HookRequest } from "./index.ts";
+
+const user = z.looseObject({ login: z.string() });
+
+/**
+ * The schema of each event key. Each names only the fields that handlers read; a loose object keeps
+ * the rest. A value that GitHub can extend (a review's `state`) is a string, not an enum, so a new
+ * value fails no parse.
+ */
+export const githubEvents = {
+  "pull_request_review.submitted": z.looseObject({
+    review: z.looseObject({
+      /** Lowercase in a webhook: `approved`, `changes_requested`, `commented`. */
+      state: z.string(),
+      body: z.string().nullable(),
+      user,
+      commit_id: z.string(),
+    }),
+    pull_request: z.looseObject({ html_url: z.string() }),
+  }),
+  "issue_comment.created": z.looseObject({
+    comment: z.looseObject({ body: z.string(), user, author_association: z.string() }),
+    issue: z.looseObject({
+      /** Only when the issue is a pull request. */
+      pull_request: z.looseObject({ html_url: z.string() }).optional(),
+    }),
+  }),
+  "check_suite.completed": z.looseObject({
+    check_suite: z.looseObject({
+      head_sha: z.string(),
+      /** `success`, `failure`, `neutral`, `cancelled`, `timed_out`, …; `null` while it runs. */
+      conclusion: z.string().nullable(),
+    }),
+  }),
+};
+
+const header = (req: HookRequest, name: string): string => {
+  const v = req.headers[name];
+  if (v === undefined || v === "") throw new Error(`no ${name} header`);
+  return v;
+};
+
+/**
+ * A GitHub repository, organization or App webhook, with the content type `application/json`. (A
+ * webhook with the content type `application/x-www-form-urlencoded` gets 400.)
+ * - verifier: `mac`, HMAC-SHA256 of the raw body, `X-Hub-Signature-256: sha256=<hex>`.
+ * - handshake: the `ping` event (sent when the webhook is made) gets an empty 200.
+ * - event key: `<X-GitHub-Event>.<action>`, or `<X-GitHub-Event>` when the body has no action.
+ * - delivery id: `X-GitHub-Delivery`. `onBehalfOf`: `sender.login`.
+ * - answer: the outcome (the default). No person reads it.
+ */
+export const github = defineHookKind({
+  api: 1,
+  id: "github",
+  events: githubEvents,
+  verify: {
+    mac: {
+      alg: "sha256",
+      signed: (req) => {
+        const sig = req.headers["x-hub-signature-256"];
+        if (!sig?.startsWith("sha256=")) return { unsigned: "no X-Hub-Signature-256 header" };
+        return { bytes: [req.body], signature: { hex: sig.slice("sha256=".length) } };
+      },
+    },
+  },
+  read: (req) => {
+    const event = header(req, "x-github-event");
+    if (event === "ping") return { handshake: { body: null } };
+    const p = json(req) as { readonly action?: unknown; readonly sender?: { readonly login?: unknown } } | null;
+    const action = typeof p?.action === "string" && p.action !== "" ? p.action : undefined;
+    const by = p?.sender?.login;
+    return {
+      key: action ? `${event}.${action}` : event,
+      id: header(req, "x-github-delivery"),
+      payload: p,
+      ...(typeof by === "string" && by !== "" ? { onBehalfOf: by } : {}),
+    };
+  },
+});
+
+declare module "./index.ts" {
+  interface HookKinds {
+    github: typeof github;
+  }
+}