@moondeck/station 0.0.1 → 1.0.0

package/lib/token-broker-local.ts

@@ -0,0 +1,392 @@
+/**
+ * Local storage adapter + the owned-host refresh loop (ADR-135).
+ *
+ * On a host the operator owns, the credentials live on disk: the default
+ * slots (`~/.codex`, `~/.grok`) and every config-dir engine account
+ * (`~/.<kind>-acct-<id>`). This adapter lists them for the broker core,
+ * writes refreshed material back atomically, and keeps the broker's meta in
+ * a sidecar file (`uai-broker.json`) that never travels to a task and never
+ * mirrors to the store.
+ *
+ * The loop runs ONLY on owned hosts (`configuredCredentialStore() === null`).
+ * A Uai-operated host must not refresh — the broker Lambda does — it picks
+ * up refreshed parameters instead (credential-store-pickup.ts).
+ *
+ * ADR-154 §7: and only while the runner is on its own credentials. No runner
+ * refreshes once it leaves them: the loop stops, a cycle under way ends, and
+ * no reactive request refreshes or invokes the broker Lambda (a leased
+ * account's refresh goes through the cloud).
+ */
+
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+import { onOwnCredentials, whileOnOwnCredentials } from "./cloud-credential-host";
+import { configuredCredentialStore, credentialStorePrefix } from "./credential-store";
+import { getDb, schema } from "./db";
+import {
+  BROKER_SIDECAR_FILE,
+  engineAccountParameterName,
+  mirrorEngineAccount,
+} from "./engine-accounts";
+import { runBrokerCycle, type BrokerCredential, type BrokerStorage } from "./token-broker";
+import { lanesForKind } from "./token-lanes/registry";
+import { refreshMetaFrom, type CredentialFiles, type RefreshMeta } from "./token-lanes/types";
+import { env } from "./env";
+
+/** Hourly: Grok tokens live six hours (observed 2026-09-09); the lanes'
+ *  leads decide what is actually refreshed, so most runs do nothing. */
+const CYCLE_INTERVAL_MS = 60 * 60 * 1000;
+/** Kinds whose default slot lives in a home dir the broker may rewrite. */
+const DEFAULT_SLOTS: Record<string, (home: string) => string> = {
+  codex: (home) => join(home, ".codex"),
+  grok: (home) => join(home, ".grok"),
+};
+
+export interface LocalBrokerSeams {
+  ownerHome?: () => string;
+  /** Rows to consider (tests inject); defaults to every stored account. */
+  accounts?: () => Array<{ id: string; kind: string; scope: string; configDir: string | null; authKind: string }>;
+  now?: () => number;
+}
+
+function ownerHome(seams: LocalBrokerSeams): string {
+  return (seams.ownerHome ?? (() => process.env.UAI_OWNER_HOME?.trim() || homedir()))();
+}
+
+function readDirFiles(dir: string): CredentialFiles | null {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const files: CredentialFiles = {};
+  for (const name of names) {
+    if (name === BROKER_SIDECAR_FILE || name !== "auth.json") continue;
+    try {
+      const path = join(dir, name);
+      if (!statSync(path).isFile()) continue;
+      files[name] = readFileSync(path, "utf8");
+    } catch {
+      /* unreadable file: the lane will not match */
+    }
+  }
+  return files;
+}
+
+function readSidecar(dir: string): RefreshMeta | null {
+  try {
+    return refreshMetaFrom(JSON.parse(readFileSync(join(dir, BROKER_SIDECAR_FILE), "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+/** temp + rename in the same dir, 0600: a crash never leaves a torn file. */
+export function writeFileAtomic(path: string, content: string): void {
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, content, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** A local credential name the reactive path and tests can address. */
+export function localCredentialName(kind: string, accountId: string | null): string {
+  return accountId ? `account:${kind}:${accountId}` : `default:${kind}`;
+}
+
+export class LocalBrokerStorage implements BrokerStorage {
+  private readonly dirs = new Map<string, { dir: string; accountId: string | null; kind: string }>();
+
+  constructor(private readonly seams: LocalBrokerSeams = {}) {}
+
+  async list(): Promise<BrokerCredential[]> {
+    const out: BrokerCredential[] = [];
+    const home = ownerHome(this.seams);
+    for (const [kind, dirOf] of Object.entries(DEFAULT_SLOTS)) {
+      const dir = dirOf(home);
+      if (!existsSync(join(dir, "auth.json"))) continue;
+      const files = readDirFiles(dir);
+      if (!files) continue;
+      const name = localCredentialName(kind, null);
+      this.dirs.set(name, { dir, accountId: null, kind });
+      out.push({
+        name,
+        header: { kind, authKind: "config-dir", id: "default", scope: "host" },
+        files,
+        refresh: readSidecar(dir),
+      });
+    }
+    const rows =
+      this.seams.accounts?.() ??
+      getDb()
+        .select()
+        .from(schema.engineAccounts)
+        .all()
+        .map((r) => ({
+          id: r.id,
+          kind: r.kind,
+          scope: r.scope ?? "host",
+          configDir: r.configDir,
+          authKind: r.authKind,
+        }));
+    for (const row of rows) {
+      if (row.authKind !== "config-dir" || !row.configDir) continue;
+      const files = readDirFiles(row.configDir);
+      if (!files) continue;
+      const name = localCredentialName(row.kind, row.id);
+      this.dirs.set(name, { dir: row.configDir, accountId: row.id, kind: row.kind });
+      out.push({
+        name,
+        header: { kind: row.kind, authKind: "config-dir", id: row.id, scope: row.scope },
+        files,
+        refresh: readSidecar(row.configDir),
+      });
+    }
+    return out;
+  }
+
+  async save(credential: BrokerCredential, files: CredentialFiles | null, refresh: RefreshMeta): Promise<void> {
+    const target = this.dirs.get(credential.name);
+    if (!target) throw new Error(`unknown local credential ${credential.name}`);
+    if (files) {
+      for (const [name, content] of Object.entries(files)) {
+        if (name.includes("/") || name === BROKER_SIDECAR_FILE) continue;
+        writeFileAtomic(join(target.dir, name), content);
+      }
+    }
+    writeFileAtomic(join(target.dir, BROKER_SIDECAR_FILE), `${JSON.stringify(refresh, null, 2)}\n`);
+    // Mirrors are no-ops without a store; on a Uai-operated host this
+    // adapter does not run at all, so this only matters in tests.
+    if (target.accountId && files) mirrorEngineAccount(target.accountId);
+  }
+
+  kindsRefreshed(names: Iterable<string>): Set<string> {
+    const kinds = new Set<string>();
+    for (const name of names) {
+      const t = this.dirs.get(name);
+      if (t) kinds.add(t.kind);
+    }
+    return kinds;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Loop + reactive entry points.
+// ---------------------------------------------------------------------------
+
+export interface TokenBrokerHooks {
+  /** Re-push brokered copies of `kind` into running tasks. */
+  repush: (kind: string) => Promise<void>;
+  log?: (line: string) => void;
+}
+
+let hooks: TokenBrokerHooks | null = null;
+let timer: ReturnType<typeof setInterval> | null = null;
+let running: Promise<void> | null = null;
+const reactiveLastAt = new Map<string, number>();
+const REACTIVE_MIN_INTERVAL_MS = 10 * 60_000;
+
+export function configureTokenBroker(next: TokenBrokerHooks): void {
+  hooks = next;
+}
+
+/** Whether this host is the refresher for its own credentials. */
+export function ownedHostRefreshes(): boolean {
+  return configuredCredentialStore() === null;
+}
+
+function log(line: string): void {
+  (hooks?.log ?? ((l: string) => console.log(`[token-broker] ${l}`)))(line);
+}
+
+/**
+ * One local cycle: refresh what is due (or forced) and re-push the kinds
+ * that changed into running tasks. Serialized — a reactive request during a
+ * scheduled run waits for it.
+ */
+export async function runLocalBrokerCycle(opts: { force?: ReadonlySet<string>; seams?: LocalBrokerSeams } = {}): Promise<void> {
+  const work = async (): Promise<void> => {
+    // A cycle queued behind the one leaving waits for refreshes nothing.
+    if (!onOwnCredentials()) return;
+    const storage = new LocalBrokerStorage(opts.seams);
+    const refreshedNames = new Set<string>();
+    const summary = await runBrokerCycle({
+      storage,
+      force: opts.force,
+      now: opts.seams?.now,
+      log: (line) => {
+        if (line.startsWith("refreshed ")) refreshedNames.add(line.split(" ")[1]!);
+        log(line);
+      },
+    });
+    if (summary.checked > 0) {
+      log(`local cycle: ${summary.checked} checked, ${summary.due} due, ${summary.refreshed} refreshed, ${summary.failed} failed, ${summary.terminal} need sign-in`);
+    }
+    for (const kind of storage.kindsRefreshed(refreshedNames)) {
+      try {
+        await hooks?.repush(kind);
+      } catch (err) {
+        log(`re-push of ${kind} copies failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  };
+  const previous = running ?? Promise.resolve();
+  const current = previous.then(work, work);
+  running = current;
+  try {
+    await current;
+  } finally {
+    if (running === current) running = null;
+  }
+}
+
+/** Owned hosts on their own credentials only: refresh now, then hourly.
+ *  Idempotent. */
+export function startTokenBrokerLoop(): void {
+  if (timer || !ownedHostRefreshes() || !onOwnCredentials()) return;
+  void runLocalBrokerCycle().catch((err) => log(`cycle failed: ${err instanceof Error ? err.message : String(err)}`));
+  timer = setInterval(() => {
+    void runLocalBrokerCycle().catch((err) => log(`cycle failed: ${err instanceof Error ? err.message : String(err)}`));
+  }, CYCLE_INTERVAL_MS);
+  timer.unref?.();
+}
+
+/** Stop the loop at once (ADR-154 §7: the runner leaves its own
+ *  credentials); resolves once a cycle under way has ended. */
+export async function stopTokenBrokerLoop(): Promise<void> {
+  if (timer) clearInterval(timer);
+  timer = null;
+  while (running !== null) await running.catch(() => undefined);
+}
+
+/** Whether an engine's error output means its access token is dead now. */
+export function isCredentialInvalidSignal(kind: string, message: string): boolean {
+  return lanesForKind(kind).some((lane) => lane.reactiveSignals.some((re) => re.test(message)));
+}
+
+/**
+ * Reactive path: a task reported a dead token for `kind` (account `accountId`,
+ * or the default slot). Owned host: one forced local refresh + re-push.
+ * Uai-operated host: invoke the broker Lambda for that parameter, then pick
+ * up the new version. Rate-limited per credential; returns whether a refresh
+ * was requested.
+ */
+export async function requestCredentialRefresh(input: {
+  kind: string;
+  accountId: string | null;
+  scope: string;
+}): Promise<boolean> {
+  // ADR-154 §7: off its own credentials the runner refreshes nothing and
+  // invokes no broker; the cloud refreshes, through the task's lease. A
+  // request on them is counted whole (its cycle or its Lambda invocation,
+  // and the pickup after): leaving them waits for it.
+  return (await whileOnOwnCredentials(() => refreshOnOwnCredentials(input))) ?? false;
+}
+
+async function refreshOnOwnCredentials(input: {
+  kind: string;
+  accountId: string | null;
+  scope: string;
+}): Promise<boolean> {
+  const key = `${input.kind}:${input.accountId ?? "default"}`;
+  const now = Date.now();
+  const last = reactiveLastAt.get(key) ?? 0;
+  if (now - last < REACTIVE_MIN_INTERVAL_MS) return false;
+  reactiveLastAt.set(key, now);
+  if (ownedHostRefreshes()) {
+    await runLocalBrokerCycle({ force: new Set([localCredentialName(input.kind, input.accountId)]) });
+    return true;
+  }
+  if (!input.accountId) return false;
+  const name = engineAccountParameterName({ id: input.accountId, kind: input.kind, scope: input.scope });
+  if (!name) return false;
+  const invoked = await invokeBrokerLambda([name]);
+  if (invoked) {
+    try {
+      await pickupNow?.();
+    } catch (err) {
+      log(`pickup after reactive refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return invoked;
+}
+
+let pickupNow: (() => Promise<void>) | null = null;
+/** credential-store-pickup.ts registers its immediate poll here. */
+export function setPickupNow(fn: (() => Promise<void>) | null): void {
+  pickupNow = fn;
+}
+
+/** `aws lambda invoke` on the broker function named by UAI_TOKEN_BROKER_FUNCTION. */
+async function invokeBrokerLambda(names: string[]): Promise<boolean> {
+  const fn = env.UAI_TOKEN_BROKER_FUNCTION;
+  const region = env.UAI_AWS_REGION;
+  if (!fn || !region) {
+    log("reactive refresh requested but UAI_TOKEN_BROKER_FUNCTION/UAI_AWS_REGION are not set");
+    return false;
+  }
+  const prefix = credentialStorePrefix();
+  const safe = names.filter((n) => n.startsWith(`${prefix}/`));
+  if (safe.length === 0) return false;
+  const outDir = mkdtempSync(join(tmpdir(), "uai-broker-invoke-"));
+  const outFile = join(outDir, "out.json");
+  try {
+    const result = await new Promise<{ status: number | null; stderr: string }>((resolve) => {
+      const child = spawn(
+        "aws",
+        [
+          "--region",
+          region,
+          "--output",
+          "json",
+          "lambda",
+          "invoke",
+          "--function-name",
+          fn,
+          "--cli-binary-format",
+          "raw-in-base64-out",
+          "--payload",
+          JSON.stringify({ names: safe }),
+          outFile,
+        ],
+        { stdio: ["ignore", "ignore", "pipe"] },
+      );
+      let stderr = "";
+      const timer = setTimeout(() => child.kill("SIGKILL"), 150_000);
+      timer.unref?.();
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (c: string) => (stderr += c));
+      child.once("error", () => resolve({ status: null, stderr }));
+      child.once("close", (code) => {
+        clearTimeout(timer);
+        resolve({ status: code, stderr });
+      });
+    });
+    if (result.status !== 0) {
+      log(`lambda invoke failed (exit ${result.status ?? "none"}): ${result.stderr.split("\n")[0] ?? ""}`);
+      return false;
+    }
+    let summary = "";
+    try {
+      summary = readFileSync(outFile, "utf8").trim().slice(0, 300);
+    } catch {
+      /* no body */
+    }
+    log(`lambda refreshed on request: ${summary}`);
+    return true;
+  } finally {
+    rmSync(outDir, { recursive: true, force: true });
+  }
+}

package/lib/token-broker-revision.ts

@@ -0,0 +1,310 @@
+/**
+ * ADR-154 §7: the broker's exact-name entry point.
+ *
+ * The cloud is the only scheduler: it knows which revisions are active, so it
+ * names one revision — its broker-only part under `/uai-broker` and its
+ * lease-readable part under `/uai/lease` — and the broker refreshes exactly
+ * that one. It never lists `/uai-broker`, so a retired revision is never
+ * refreshed.
+ *
+ * Every invoke, holding the credential's lock:
+ * 1. makes the lease-readable copy agree with the broker-only material,
+ *    rewriting it if a crash left it behind;
+ * 2. refreshes when due (or when the cloud forces it, for a runner's
+ *    credential-invalid report), writing the broker-only part first and the
+ *    lease-readable copy second, so a crash between them keeps the new
+ *    refresh token and leaves the previous access token valid;
+ * 3. answers for that one credential, never with material: `refreshed` or
+ *    `fresh` with the lease-readable parameter's version and the expiry,
+ *    `needs_sign_in`, `busy`, or `unavailable`.
+ *
+ * An adopted revision (`legacyParameter`, owner answer 3) also keeps today's
+ * parameter it came from agreeing with it, the brokered copy only, until the
+ * fleet audit (token-broker-adopt.ts).
+ *
+ * Storage is an interface; the Lambda binds it to SSM (token-broker-ssm.ts).
+ */
+
+import {
+  brokerErrorKind,
+  CREDENTIAL_LANE_SCHEDULES,
+  parseBrokerParameterName,
+  parseLeasedValue,
+  serializeLeasedValue,
+  type BrokerRevisionAnswer,
+  type BrokerRevisionRequest,
+  type CredentialLocation,
+} from "../src/cloud-credentials";
+import { parseBrokerEngineValue, type BrokerEngineValue } from "./capture-flow";
+import { syncLegacyCopy, type LegacySync } from "./token-broker-adopt";
+import { MCP_OAUTH_LANE, parseBrokerMcpValue, postTokenEndpoint, type BrokerMcpValue, oauthFailure } from "./mcp-capture";
+import type { SafeHttpDeps } from "./safe-http";
+import { backoffMs, createLaneHttp, isRefreshDue } from "./token-broker";
+import { laneById } from "./token-lanes/registry";
+import { isTerminalOAuthError, type CredentialFiles, type LaneHttp, type TokenLane } from "./token-lanes/types";
+
+export interface StoredParameter {
+  value: string;
+  version: number;
+}
+
+/** The storage one invoke needs: read and overwrite two named parameters,
+ *  and a lock per credential. */
+export interface RevisionStore {
+  get(name: string): Promise<StoredParameter | null>;
+  /** Overwrite a parameter this invoke has just read; the new version. */
+  overwrite(name: string, value: string): Promise<number>;
+  /** The credential's lock, or null while another invoke holds a fresh one. */
+  lock(credentialId: string): Promise<(() => Promise<void>) | null>;
+}
+
+const MAX_ERROR_CHARS = 512;
+
+function leaseCopy(location: CredentialLocation, lane: TokenLane, files: CredentialFiles): string {
+  return serializeLeasedValue({
+    v: 1,
+    part: "lease",
+    location,
+    class: "engine",
+    authKind: "config-dir",
+    files: lane.brokeredCopy(files),
+    expiresAt: lane.expiresAt(files),
+  });
+}
+
+function sameFiles(a: CredentialFiles, b: CredentialFiles): boolean {
+  const keys = Object.keys(a).sort();
+  const other = Object.keys(b).sort();
+  return keys.length === other.length && keys.every((k, i) => k === other[i] && a[k] === b[k]);
+}
+
+/** Refresh one named revision. Never throws for a provider or storage
+ *  failure: the answer says what happened. */
+export async function refreshRevision(
+  request: BrokerRevisionRequest,
+  store: RevisionStore,
+  options: {
+    now?: () => number;
+    http?: (lane: TokenLane) => LaneHttp;
+    /** The SSRF rule's seams, for an MCP server's token endpoint. */
+    safeHttp?: SafeHttpDeps;
+    /** ADR-134 root of an adopted compatibility copy. */
+    legacyPrefix?: string;
+  } = {},
+): Promise<BrokerRevisionAnswer> {
+  const now = options.now ?? Date.now;
+  const location = parseBrokerParameterName(request.brokerParameter)!;
+  if (location.class === "mcp") return refreshMcpRevision(request, store, location, options);
+  let release: (() => Promise<void>) | null = null;
+  try {
+    release = await store.lock(request.credentialId);
+    if (!release) return { outcome: "busy" };
+
+    const brokerPart = await store.get(request.brokerParameter);
+    const broker = brokerPart ? parseBrokerEngineValue(brokerPart.value, location) : null;
+    if (!broker) return { outcome: "unavailable", error: "the revision's broker part is missing or unreadable" };
+    const lane = laneById(broker.lane);
+    if (!lane) return { outcome: "unavailable", error: `no lane ${broker.lane}` };
+
+    // 1. The lease-readable copy agrees with the broker-only material. It is
+    // rewritten, never created: a missing one was deleted with its retired
+    // revision, which must not come back.
+    const leasePart = await store.get(request.leaseParameter);
+    if (!leasePart) return { outcome: "unavailable", error: "the revision's lease-readable part is missing" };
+    const current = parseLeasedValue(leasePart.value, location);
+    const expected = lane.brokeredCopy(broker.files);
+    let version = leasePart.version;
+    if (
+      !current ||
+      current.class !== "engine" ||
+      current.authKind !== "config-dir" ||
+      !sameFiles(current.files, expected)
+    ) {
+      version = await store.overwrite(request.leaseParameter, leaseCopy(location, lane, broker.files));
+    }
+    // An adopted revision: today's parameter agrees with it too.
+    let legacy = request.legacyParameter
+      ? await syncLegacyCopy(store, request.legacyParameter, lane, broker.files, options.legacyPrefix)
+      : null;
+    const withLegacy = <T extends object>(answer: T): T & { legacy?: LegacySync } =>
+      legacy === null ? answer : { ...answer, legacy };
+
+    if (broker.refresh.needsSignIn) return { outcome: "needs_sign_in" };
+    const at = now();
+    if (!isRefreshDue(lane, broker.files, broker.refresh, at, request.force)) {
+      return withLegacy({
+        outcome: "fresh" as const,
+        version,
+        expiresAt: lane.expiresAt(broker.files) ?? broker.refresh.expiresAt,
+      });
+    }
+
+    // 2. Refresh: the broker-only part first.
+    const http = options.http?.(lane) ?? createLaneHttp(lane.endpoints);
+    const result = await lane.refresh(broker.files, http, at);
+    if (!result.ok) {
+      const next: BrokerEngineValue = {
+        ...broker,
+        refresh: {
+          ...broker.refresh,
+          attempts: broker.refresh.attempts + 1,
+          lastAttemptAt: at,
+          lastError: result.reason.slice(0, MAX_ERROR_CHARS),
+          needsSignIn: result.terminal,
+        },
+      };
+      await store.overwrite(request.brokerParameter, JSON.stringify(next));
+      return result.terminal
+        ? { outcome: "needs_sign_in" }
+        : { outcome: "unavailable", error: result.reason.slice(0, MAX_ERROR_CHARS) };
+    }
+    const refreshed: BrokerEngineValue = {
+      ...broker,
+      files: { ...result.files },
+      refresh: {
+        ...broker.refresh,
+        expiresAt: result.expiresAt,
+        refreshedAt: at,
+        attempts: 0,
+        lastAttemptAt: at,
+        lastError: null,
+        needsSignIn: false,
+      },
+    };
+    await store.overwrite(request.brokerParameter, JSON.stringify(refreshed));
+    version = await store.overwrite(request.leaseParameter, leaseCopy(location, lane, result.files));
+    if (request.legacyParameter) {
+      legacy = await syncLegacyCopy(store, request.legacyParameter, lane, result.files, options.legacyPrefix);
+    }
+    return withLegacy({ outcome: "refreshed" as const, version, expiresAt: result.expiresAt });
+  } catch (error) {
+    // The error's kind only: a message can quote what a request carried.
+    return { outcome: "unavailable", error: brokerErrorKind(error) };
+  } finally {
+    if (release) await release();
+  }
+}
+
+function mcpLeaseCopy(location: CredentialLocation, broker: BrokerMcpValue): string {
+  return serializeLeasedValue({
+    v: 1,
+    part: "lease",
+    location,
+    class: "mcp",
+    authKind: "oauth",
+    accessToken: broker.accessToken,
+    tokenType: "Bearer",
+    expiresAt: broker.refresh.expiresAt,
+  });
+}
+
+function mcpRefreshDue(broker: BrokerMcpValue, now: number, forced: boolean): boolean {
+  if (broker.refresh.needsSignIn) return false;
+  if (forced) return true;
+  const { attempts, lastAttemptAt } = broker.refresh;
+  if (attempts > 0 && lastAttemptAt !== null && now - lastAttemptAt < backoffMs(attempts)) return false;
+  const schedule = CREDENTIAL_LANE_SCHEDULES[MCP_OAUTH_LANE]!;
+  if (broker.refresh.expiresAt !== null) return broker.refresh.expiresAt - now <= schedule.leadMs;
+  return now - (broker.refresh.refreshedAt ?? 0) >= (schedule.everyMs ?? schedule.leadMs);
+}
+
+/**
+ * ADR-154 §11: an MCP connection's sign-in, refreshed at its token endpoint
+ * through the SSRF rule. The same order as an engine's: the lease-readable
+ * copy agrees with the broker-only material first, then a due refresh writes
+ * the broker-only part before the copy. A sign-in that gave no refresh token,
+ * or that the provider calls dead, needs a new sign-in.
+ */
+async function refreshMcpRevision(
+  request: BrokerRevisionRequest,
+  store: RevisionStore,
+  location: CredentialLocation,
+  options: { now?: () => number; safeHttp?: SafeHttpDeps },
+): Promise<BrokerRevisionAnswer> {
+  const now = options.now ?? Date.now;
+  let release: (() => Promise<void>) | null = null;
+  try {
+    release = await store.lock(request.credentialId);
+    if (!release) return { outcome: "busy" };
+    const brokerPart = await store.get(request.brokerParameter);
+    const broker = brokerPart ? parseBrokerMcpValue(brokerPart.value, location) : null;
+    if (!broker) return { outcome: "unavailable", error: "the revision's broker part is missing or unreadable" };
+    const leasePart = await store.get(request.leaseParameter);
+    if (!leasePart) return { outcome: "unavailable", error: "the revision's lease-readable part is missing" };
+    const current = parseLeasedValue(leasePart.value, location);
+    let version = leasePart.version;
+    if (
+      !current ||
+      current.class !== "mcp" ||
+      current.authKind !== "oauth" ||
+      current.accessToken !== broker.accessToken ||
+      current.expiresAt !== broker.refresh.expiresAt
+    ) {
+      version = await store.overwrite(request.leaseParameter, mcpLeaseCopy(location, broker));
+    }
+    if (broker.refresh.needsSignIn) return { outcome: "needs_sign_in" };
+    const at = now();
+    if (!mcpRefreshDue(broker, at, request.force)) {
+      return { outcome: "fresh", version, expiresAt: broker.refresh.expiresAt };
+    }
+    const markFailed = async (reason: string, terminal: boolean): Promise<void> => {
+      const next: BrokerMcpValue = {
+        ...broker,
+        refresh: {
+          ...broker.refresh,
+          attempts: broker.refresh.attempts + 1,
+          lastAttemptAt: at,
+          lastError: reason.slice(0, MAX_ERROR_CHARS),
+          needsSignIn: terminal,
+        },
+      };
+      await store.overwrite(request.brokerParameter, JSON.stringify(next));
+    };
+    if (broker.refreshToken === null) {
+      await markFailed("the server gave no refresh token", true);
+      return { outcome: "needs_sign_in" };
+    }
+    const { status, json } = await postTokenEndpoint(
+      broker.tokenEndpoint,
+      {
+        grant_type: "refresh_token",
+        refresh_token: broker.refreshToken,
+        client_id: broker.clientId,
+        resource: broker.resource,
+      },
+      { clientId: broker.clientId, clientSecret: broker.clientSecret },
+      { http: options.safeHttp },
+    );
+    if (status < 200 || status >= 300 || typeof json.access_token !== "string") {
+      const terminal = status >= 400 && isTerminalOAuthError(status, json);
+      // A standard OAuth error code or the status: never the endpoint's own text.
+      const reason = oauthFailure(json, status);
+      await markFailed(reason, terminal);
+      return terminal ? { outcome: "needs_sign_in" } : { outcome: "unavailable", error: reason.slice(0, MAX_ERROR_CHARS) };
+    }
+    const expiresAt = typeof json.expires_in === "number" ? at + json.expires_in * 1000 : null;
+    const refreshed: BrokerMcpValue = {
+      ...broker,
+      accessToken: json.access_token,
+      // Rotating servers send a new one; the rest keep the old.
+      refreshToken: typeof json.refresh_token === "string" ? json.refresh_token : broker.refreshToken,
+      refresh: {
+        ...broker.refresh,
+        expiresAt,
+        refreshedAt: at,
+        attempts: 0,
+        lastAttemptAt: at,
+        lastError: null,
+        needsSignIn: false,
+      },
+    };
+    await store.overwrite(request.brokerParameter, JSON.stringify(refreshed));
+    version = await store.overwrite(request.leaseParameter, mcpLeaseCopy(location, refreshed));
+    return { outcome: "refreshed", version, expiresAt };
+  } catch (error) {
+    // The error's kind only: a message can quote what a request carried.
+    return { outcome: "unavailable", error: brokerErrorKind(error) };
+  } finally {
+    if (release) await release();
+  }
+}