@jr2/orchestrator 0.6.0 → 0.7.0

package/src/callers.ts

@@ -0,0 +1,245 @@
+// The JWT issuers of the Caller seam, and the record of a Caller on a run (ADR-0078).
+//
+// The seam itself (its order, the Instance token, the named `jr2c_` tokens) is in tokens.ts. This
+// file adds its third authenticator: a JWT from an identity provider that the config declares, which
+// the Orchestrator checks against the provider's published keys. That fetch is the Orchestrator's
+// one call out of the Instance, and it spends no secret (ADR-0068).
+//
+// It also holds what a run records of a Caller: the Caller without its scopes, because a run
+// records who acted, not what that credential could do then.
+
+import { createRemoteJWKSet, customFetch, decodeJwt, jwtVerify, type JWTPayload } from "jose";
+import { SCOPES, type AnswerGrant, type GateGrant, type JwtIssuer, type Scopes } from "./config.ts";
+import type { Caller, CallerAnswer, CallerAuthenticator } from "./tokens.ts";
+
+// ---- What a run records ------------------------------------------------------------------------
+
+/** A Caller as a run records it (ADR-0078): who acted, and the party it says it acted for. Never its
+ * scopes. */
+export type CallerRecord = {
+  via: Caller["via"];
+  name: string;
+  /** The name that jr2 shows, when it is not `name` (a JWT's `email`). */
+  shown?: string;
+  /** The Caller's claim about the party it acts for. jr2 records it and never checks it, except for
+   * a Hook, whose signature covers it. */
+  onBehalfOf?: string;
+};
+
+/**
+ * Who started a run (ADR-0078): a Caller on a guarded route; a run, through a local `dispatch`
+ * (ADR-0071); or jr2 itself, for a standing run (ADR-0017), at `boot`, at a `publish`, at a
+ * `hand-over`, or at a `resume`. A run that a foreign `dispatch` started records the Caller whose
+ * credential the other Instance sent.
+ */
+export type RunStarter =
+  | ({ kind: "caller" } & CallerRecord)
+  | { kind: "run"; run: string; slot: string }
+  | { kind: "jr2"; why: "boot" | "publish" | "hand-over" | "resume" };
+
+/** One answer to a Gate of a run, and the Caller that gave it (ADR-0011, ADR-0078). `delivery` is
+ * the Hook's delivery id when a Hook gave it: the run's `(delivery, gate)` pairs, so a restore never
+ * gives one delivery twice to one Gate. */
+export type GateAnswer = { gate: string; type: string; at: string; answeredBy: CallerRecord; delivery?: string };
+
+/** How many Gate answers a run keeps, the last ones: a standing run's Gate can take an answer for
+ * each delivery, and the run's blob is saved on each transition. */
+export const GATE_ANSWERS_KEPT = 100;
+
+/** The record of a Caller: the Caller without its scopes. */
+export function callerRecord(caller: Caller): CallerRecord {
+  return {
+    via: caller.via,
+    name: caller.name,
+    ...(caller.shown !== undefined ? { shown: caller.shown } : {}),
+    ...(caller.onBehalfOf !== undefined ? { onBehalfOf: caller.onBehalfOf } : {}),
+  };
+}
+
+/** A Caller as a line names it: `token/ci`, then the name that jr2 shows and the party it acts for. */
+export function callerText(caller: CallerRecord): string {
+  return (
+    `${caller.via}/${caller.name}` +
+    (caller.shown !== undefined ? ` (${caller.shown})` : "") +
+    (caller.onBehalfOf !== undefined ? ` on behalf of ${caller.onBehalfOf}` : "")
+  );
+}
+
+// ---- The JWT authenticator ---------------------------------------------------------------------
+
+/** The algorithms a JWT may be signed with: the asymmetric ones alone, because a published key
+ * must not be able to sign. */
+const ALGORITHMS = ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+
+/** How far the issuer's clock and ours may differ, for `exp` and `nbf`. */
+const CLOCK_TOLERANCE_S = 30;
+
+/** How long the keys are kept before a JWT makes a fetch again. */
+const KEYS_MAX_AGE_MS = 10 * 60_000;
+
+/** The shortest time between two fetches of the keys, for a JWT whose key is not known; also how
+ * long a failed fetch of the discovery document is kept before a JWT makes a fetch again. */
+const KEYS_COOLDOWN_MS = 30_000;
+
+/** How long one fetch of the discovery document or the keys may take. */
+const FETCH_TIMEOUT_MS = 5_000;
+
+/** The claims a {@link JwtIssuer} reads when its `claims` names no other. */
+const DEFAULT_CLAIMS = { name: "sub", shown: "email", groups: "groups" } as const;
+
+/** The fetch that the JWT authenticator uses: the global one, or a test's. */
+export type JwksFetch = (url: string, init: { signal?: AbortSignal }) => Promise<Response>;
+
+/** The options of {@link jwtAuthenticator}, for tests. */
+export type JwtAuthenticatorOptions = {
+  /** The fetch for the discovery document and the keys. Default: the global `fetch`. */
+  fetch?: JwksFetch;
+  /** The shortest time between two fetches of the keys, and of a discovery that failed. Default: 30 s. */
+  cooldownMs?: number;
+  /** The clock, in milliseconds, that measures the cooldown of a failed discovery. Default: `Date.now`. */
+  now?: () => number;
+};
+
+type KeySet = ReturnType<typeof createRemoteJWKSet>;
+
+/**
+ * The JWT issuers' authenticator (ADR-0078). It claims a bearer that is a JWT whose `iss` claim is
+ * the `issuer` of an entry in `issuers()`, which is read on each request, so a publish applies with
+ * no restart. A claimed JWT that fails a check is "mine, and bad" (401). A JWT of an issuer that no
+ * entry names is not claimed.
+ */
+export function jwtAuthenticator(
+  issuers: () => readonly JwtIssuer[],
+  opts: JwtAuthenticatorOptions = {},
+): CallerAuthenticator {
+  const doFetch: JwksFetch = opts.fetch ?? ((url, init) => fetch(url, init));
+  const cooldownMs = opts.cooldownMs ?? KEYS_COOLDOWN_MS;
+  const now = opts.now ?? Date.now;
+  // The key sets, by the issuer and its keys' URL: an entry that a publish changes gets a new one.
+  // `failedAt`: when its discovery failed. The failure is kept for the cooldown, so a flood of JWTs
+  // that name an issuer whose discovery fails makes at most one fetch in each cooldown.
+  const keySets = new Map<string, { keySet: Promise<KeySet>; failedAt?: number }>();
+  const idOf = (entry: JwtIssuer): string => JSON.stringify([entry.issuer, entry.jwks ?? null]);
+
+  const keySetOf = (entry: JwtIssuer): Promise<KeySet> => {
+    const id = idOf(entry);
+    const found = keySets.get(id);
+    if (found && (found.failedAt === undefined || now() - found.failedAt < cooldownMs)) return found.keySet;
+    const slot: { keySet: Promise<KeySet>; failedAt?: number } = {
+      keySet: (async () => {
+        const url = entry.jwks ?? (await discoverJwks(entry.issuer, doFetch));
+        return createRemoteJWKSet(new URL(url), {
+          cacheMaxAge: KEYS_MAX_AGE_MS,
+          cooldownDuration: cooldownMs,
+          timeoutDuration: FETCH_TIMEOUT_MS,
+          [customFetch]: (u, init) => doFetch(u, { signal: init.signal }),
+        });
+      })(),
+    };
+    slot.keySet.catch(() => {
+      slot.failedAt = now();
+    });
+    keySets.set(id, slot);
+    return slot.keySet;
+  };
+
+  /** Drop the key sets of each issuer and keys' URL that the config no longer names: the cache
+   * holds at most one entry for each entry of `issuers()`. */
+  const prune = (current: readonly JwtIssuer[]): void => {
+    if (keySets.size === 0) return;
+    const named = new Set(current.map(idOf));
+    for (const id of keySets.keys()) if (!named.has(id)) keySets.delete(id);
+  };
+
+  return async (bearer): Promise<CallerAnswer> => {
+    if (bearer.split(".").length !== 3) return undefined;
+    let unverified: JWTPayload;
+    try {
+      unverified = decodeJwt(bearer);
+    } catch {
+      return undefined;
+    }
+    const current = issuers();
+    prune(current);
+    const entry = current.find((i) => i.issuer === unverified.iss);
+    if (!entry) return undefined;
+
+    let payload: JWTPayload;
+    try {
+      ({ payload } = await jwtVerify(bearer, await keySetOf(entry), {
+        issuer: entry.issuer,
+        audience: entry.audience,
+        algorithms: ALGORITHMS,
+        clockTolerance: CLOCK_TOLERANCE_S,
+        requiredClaims: ["exp"],
+      }));
+    } catch (err) {
+      return { refused: `a JWT of ${entry.issuer} did not verify: ${err instanceof Error ? err.message : err}` };
+    }
+
+    const claims = { ...DEFAULT_CLAIMS, ...entry.claims };
+    const name = payload[claims.name];
+    if (typeof name !== "string" || name === "") {
+      return { refused: `a JWT of ${entry.issuer} has no "${claims.name}" claim, which names its Caller` };
+    }
+    const shown = payload[claims.shown];
+    return {
+      via: "jwt",
+      name,
+      ...(typeof shown === "string" && shown !== "" && shown !== name ? { shown } : {}),
+      may: joinScopes(
+        valuesOf(payload[claims.groups]).flatMap((v) => (Object.hasOwn(entry.groups, v) ? [entry.groups[v]!] : [])),
+      ),
+    };
+  };
+}
+
+/** The `jwks_uri` of an issuer's OIDC discovery document. */
+async function discoverJwks(issuer: string, doFetch: JwksFetch): Promise<string> {
+  const url = `${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`;
+  const res = await doFetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
+  const doc = (await res.json()) as { jwks_uri?: unknown };
+  if (typeof doc.jwks_uri !== "string") throw new Error(`${url} names no jwks_uri`);
+  return doc.jwks_uri;
+}
+
+/** The values of a groups claim: a list of strings, or one string. */
+function valuesOf(claim: unknown): string[] {
+  if (typeof claim === "string") return [claim];
+  if (Array.isArray(claim)) return claim.filter((v): v is string => typeof v === "string");
+  return [];
+}
+
+/** The scopes of each grant, joined: a scope that one gives for every Workflow is for every
+ * Workflow, and lists join. A JWT whose groups give one team's Gate and another team's Gate of one
+ * Workflow may answer both. */
+export function joinScopes(grants: readonly Scopes[]): Scopes {
+  const out: Record<string, AnswerGrant> = {};
+  for (const scope of SCOPES) {
+    let joined: AnswerGrant | undefined;
+    for (const may of grants) {
+      const grant: AnswerGrant | undefined = may[scope];
+      if (grant === undefined) continue;
+      if (grant === "all" || joined === "all") joined = "all";
+      else joined = joinItems(joined ?? [], grant);
+    }
+    if (joined !== undefined) out[scope] = joined;
+  }
+  return out as Scopes;
+}
+
+/** Two lists of one scope, joined: each Workflow name once, and each `answer` item that names Gates
+ * once (ADR-0078). An item that names Gates stays beside a bare name of its Workflow, which opens
+ * them anyway. */
+function joinItems(a: readonly (string | GateGrant)[], b: readonly (string | GateGrant)[]): (string | GateGrant)[] {
+  const seen = new Set<string>();
+  const out: (string | GateGrant)[] = [];
+  for (const item of [...a, ...b]) {
+    const key = typeof item === "string" ? item : JSON.stringify([item.workflow, [...item.gates].sort()]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}

package/src/chart.ts

@@ -25,6 +25,7 @@ import { defineEvent, type EventAudience, type EventDef } from "@jr2/agent-proto
 import type { AgentDefinition, ThinkingLevel, WorkspaceAccess } from "./agent.ts";
 import { inputKeysOf, inputShapeOf, isEffect, type InputShape } from "./effect.ts";
 import { FAILURE_GUARD } from "./fail.ts";
+import { isGateSlot } from "./gate.ts";
 import { compileChart, durationMs, type LentParts, type OpenBodyDeclaration } from "./open-body.ts";
 import { SENT_BY } from "./party.ts";
 import { loadWarningsOf } from "./vocabulary.ts";
@@ -673,6 +674,7 @@ function lendsOf(decl: OpenBodyDeclaration) {
     agents: decl.lends.agents ?? [],
     effects: decl.lends.effects ?? [],
     machines: decl.lends.machines ?? [],
+    gates: decl.lends.gates ?? [],
     guards: decl.lends.guards ?? [],
     actions: decl.lends.actions ?? [],
     delays: decl.lends.delays ?? [],
@@ -695,7 +697,14 @@ export function narrowedChartSchema(decl: OpenBodyDeclaration): Record<string, u
 function narrowOf(decl: OpenBodyDeclaration): Narrow {
   const l = lendsOf(decl);
   return {
-    srcs: [...l.agents, ...l.effects, ...l.machines, ...(l.gate ? ["gate"] : []), ...(l.fail ? ["fail"] : [])],
+    srcs: [
+      ...l.agents,
+      ...l.effects,
+      ...l.machines,
+      ...l.gates,
+      ...(l.gate ? ["gate"] : []),
+      ...(l.fail ? ["fail"] : []),
+    ],
     lentAgents: l.agents,
     lendsEffects: l.effects.length > 0,
     gate: l.gate,
@@ -853,6 +862,9 @@ export type AdmittedChart = {
   agents: Record<string, AgentDefinition>;
   /** The bytes of the text's canonical JSON. */
   size: number;
+  /** The invoke ids of the Chart's Gates (ADR-0011), as `jr2Setup` names them: the names that the
+   * `answer` scope can name them by (ADR-0078). */
+  gates: string[];
 };
 
 /**
@@ -1064,6 +1076,8 @@ class Door {
   private readonly invokeKinds = new Map<ChartInvoke, NonNullable<ReturnType<Door["srcKind"]>>>();
   /** Every `jr2.sentBy` id, for the party check. */
   private readonly sentBys: Array<{ id: string; path: string }> = [];
+  /** The Gates' invoke ids, which the party check finds. */
+  private readonly gateIds = new Set<string>();
 
   private readonly chart: ChartText;
   private readonly decl: OpenBodyDeclaration;
@@ -1126,7 +1140,14 @@ class Door {
     const events = Object.entries(this.chart.events ?? {}).map(([name, ev]) => this.eventDef(name, ev)!);
     const agents: Record<string, AgentDefinition> = {};
     for (const [slot, a] of Object.entries(this.chart.agents ?? {})) agents[slot] = { ...a };
-    const admitted: AdmittedChart = { text: this.chart, hash: chartHash(this.chart), events, agents, size };
+    const admitted: AdmittedChart = {
+      text: this.chart,
+      hash: chartHash(this.chart),
+      events,
+      agents,
+      size,
+      gates: [...this.gateIds],
+    };
     this.trialCompile(admitted);
     return admitted;
   }
@@ -1152,11 +1173,12 @@ class Door {
   // --- rule 3: names --------------------------------------------------------------------------------
 
   /** The lent actors by kind, as the lent set has them now. */
-  private lentActors(): Array<{ name: string; kind: "Agent" | "Effect" | "Machine" }> {
-    const out: Array<{ name: string; kind: "Agent" | "Effect" | "Machine" }> = [];
+  private lentActors(): Array<{ name: string; kind: "Agent" | "Effect" | "Machine" | "Gate slot" }> {
+    const out: Array<{ name: string; kind: "Agent" | "Effect" | "Machine" | "Gate slot" }> = [];
     for (const name of this.lends.agents) if (name in this.lent.actors) out.push({ name, kind: "Agent" });
     for (const name of this.lends.effects) if (name in this.lent.actors) out.push({ name, kind: "Effect" });
     for (const name of this.lends.machines) if (name in this.lent.actors) out.push({ name, kind: "Machine" });
+    for (const name of this.lends.gates) if (name in this.lent.actors) out.push({ name, kind: "Gate slot" });
     return out;
   }
 
@@ -1170,7 +1192,7 @@ class Door {
   /** What an invoke's `src` names, or undefined after a refusal line. */
   private srcKind(src: string, path: string): InvokeKind | undefined {
     const lentNow = (name: string) => name in this.lent.actors;
-    const declared = [...this.lends.agents, ...this.lends.effects, ...this.lends.machines];
+    const declared = [...this.lends.agents, ...this.lends.effects, ...this.lends.machines, ...this.lends.gates];
     if (declared.includes(src) && !lentNow(src)) {
       this.fail(
         3,
@@ -1181,6 +1203,22 @@ class Door {
     if (this.lends.agents.includes(src)) return "agent";
     if (this.lends.effects.includes(src)) return "effect";
     if (this.lends.machines.includes(src)) return "machine";
+    if (this.lends.gates.includes(src)) {
+      // A lent Gate slot (ADR-0011, ADR-0070): its handlers and its look give its `delivers`, which
+      // the Chart's Machine must take. One that is not in the Chart's Vocabulary could never arrive.
+      const slot = this.lent.actors[src];
+      const outside = isGateSlot(slot)
+        ? slot.gateSlot.delivers.map((d) => d.name).filter((name) => !this.eventSchemas.has(name))
+        : [];
+      if (outside.length) {
+        this.fail(
+          3,
+          `${path}: the Gate slot "${src}" delivers ${outside.map((n) => `"${n}"`).join(", ")}, which ${outside.length > 1 ? "are" : "is"} not in the Chart's \`events\` (events: ${names([...this.eventSchemas.keys()])}); declare ${outside.length > 1 ? "them" : "it"} in \`events\` and handle ${outside.length > 1 ? "them" : "it"} on this state`,
+        );
+        return undefined;
+      }
+      return "gate";
+    }
     if (src === "gate") {
       if (this.lends.gate) return "gate";
       this.fail(
@@ -1375,7 +1413,14 @@ class Door {
   // --- rule 5: minted Agents ------------------------------------------------------------------------
 
   private checkAgents(): void {
-    const lentNames = new Set([...this.lends.agents, ...this.lends.effects, ...this.lends.machines, "gate", "fail"]);
+    const lentNames = new Set([
+      ...this.lends.agents,
+      ...this.lends.effects,
+      ...this.lends.machines,
+      ...this.lends.gates,
+      "gate",
+      "fail",
+    ]);
     for (const [slot, a] of Object.entries(this.chart.agents ?? {})) {
       const path = `agents.${slot}`;
       if (lentNames.has(slot)) {
@@ -1719,7 +1764,7 @@ class Door {
   /** The parties' rules, as `jr2Setup` applies them (ADR-0015), each with its path in the Chart. */
   private checkParties(): void {
     const agents = new Set<string>();
-    const gates = new Set<string>();
+    const gates = this.gateIds;
     const slotStates = new Map<string, Node[]>();
     for (const node of this.nodes) {
       const invokes = listAt(node.state.invoke, `${node.doc}.invoke`);