@runuai/host 0.9.113 → 0.9.115

package/lib/token-broker.ts

@@ -0,0 +1,218 @@
+/**
+ * Token broker core (ADR-135, docs/token-broker.md).
+ *
+ * One cycle: list the credentials a storage adapter holds, pick the lane for
+ * each, decide whether a refresh is due (expiry lead, cadence, backoff,
+ * terminal state, or forced by the reactive path), perform at most one
+ * refresh per credential, and persist the outcome with the broker-owned
+ * `RefreshMeta`. The same function runs inside the host process (local
+ * storage) and inside the broker Lambda (Parameter Store storage). It never
+ * logs material; the audit line is name, lane, outcome, timing.
+ */
+
+import { TOKEN_LANES } from "./token-lanes/registry";
+import {
+  emptyRefreshMeta,
+  type CredentialFiles,
+  type CredentialHeader,
+  type LaneHttp,
+  type LaneHttpResponse,
+  type RefreshMeta,
+  type TokenLane,
+} from "./token-lanes/types";
+
+export interface BrokerCredential {
+  /** Storage-specific identity (a parameter name, or a local dir path). */
+  name: string;
+  header: CredentialHeader;
+  files: CredentialFiles;
+  refresh: RefreshMeta | null;
+}
+
+export interface BrokerStorage {
+  list(): Promise<BrokerCredential[]>;
+  /** Persist new material and/or new meta. `files` is null when only the
+   *  meta changed (a failed attempt, a terminal answer). */
+  save(credential: BrokerCredential, files: CredentialFiles | null, refresh: RefreshMeta): Promise<void>;
+}
+
+export interface BrokerCycleOptions {
+  storage: BrokerStorage;
+  lanes?: readonly TokenLane[];
+  http?: LaneHttp;
+  now?: () => number;
+  /** Credential names to refresh regardless of schedule (reactive path). */
+  force?: ReadonlySet<string>;
+  /** Audit sink; one line per decision. Never carries material. */
+  log?: (line: string) => void;
+  /** Reactive dedupe: skip a forced refresh when the last successful one is
+   *  younger than this (a burst from many tasks). */
+  forceDedupeMs?: number;
+}
+
+export interface BrokerCycleSummary {
+  checked: number;
+  due: number;
+  refreshed: number;
+  failed: number;
+  terminal: number;
+}
+
+/** Retry spacing after failed attempts: 5 min, 30 min, 2 h, then every 6 h. */
+export function backoffMs(attempts: number): number {
+  if (attempts <= 0) return 0;
+  if (attempts === 1) return 5 * 60_000;
+  if (attempts === 2) return 30 * 60_000;
+  if (attempts === 3) return 2 * 60 * 60_000;
+  return 6 * 60 * 60_000;
+}
+
+export function isRefreshDue(
+  lane: TokenLane,
+  files: CredentialFiles,
+  meta: RefreshMeta | null,
+  now: number,
+  forced = false,
+): boolean {
+  if (meta?.needsSignIn) return false;
+  if (forced) return true;
+  if (meta && meta.attempts > 0 && meta.lastAttemptAt !== null) {
+    if (now - meta.lastAttemptAt < backoffMs(meta.attempts)) return false;
+  }
+  const expiresAt = lane.expiresAt(files) ?? meta?.expiresAt ?? null;
+  if (expiresAt !== null && lane.schedule.leadMs !== undefined) {
+    return expiresAt - now <= lane.schedule.leadMs;
+  }
+  if (lane.schedule.everyMs !== undefined) {
+    return now - (meta?.refreshedAt ?? 0) >= lane.schedule.everyMs;
+  }
+  return false;
+}
+
+/**
+ * An http client that refuses every URL outside `allowed`. Built per lane so
+ * a poisoned credential value can never steer the broker elsewhere.
+ */
+export function createLaneHttp(
+  allowed: readonly string[],
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 20_000,
+): LaneHttp {
+  const guard = (url: string): void => {
+    if (!allowed.includes(url)) throw new Error(`lane may not call ${url}`);
+  };
+  const send = async (url: string, headers: Record<string, string>, body: string): Promise<LaneHttpResponse> => {
+    guard(url);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers: { accept: "application/json", ...headers },
+        body,
+        signal: controller.signal,
+        redirect: "error",
+      });
+      let json: unknown = null;
+      try {
+        json = await res.json();
+      } catch {
+        json = null;
+      }
+      return { status: res.status, json };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  return {
+    postJson: (url, body) =>
+      send(url, { "content-type": "application/json" }, JSON.stringify(body)),
+    postForm: (url, form) =>
+      send(
+        url,
+        { "content-type": "application/x-www-form-urlencoded" },
+        new URLSearchParams(form).toString(),
+      ),
+  };
+}
+
+export async function runBrokerCycle(opts: BrokerCycleOptions): Promise<BrokerCycleSummary> {
+  const lanes = opts.lanes ?? TOKEN_LANES;
+  const now = opts.now ?? Date.now;
+  const log = opts.log ?? (() => undefined);
+  const forceDedupeMs = opts.forceDedupeMs ?? 60_000;
+  const summary: BrokerCycleSummary = { checked: 0, due: 0, refreshed: 0, failed: 0, terminal: 0 };
+  const credentials = await opts.storage.list();
+  for (const credential of credentials) {
+    const lane = lanes.find((l) => l.matches(credential.header, credential.files)) ?? null;
+    if (!lane) continue;
+    summary.checked += 1;
+    const at = now();
+    const meta = credential.refresh?.lane === lane.id ? credential.refresh : null;
+    let forced = opts.force?.has(credential.name) === true;
+    if (forced && meta?.refreshedAt !== null && meta?.refreshedAt !== undefined && at - meta.refreshedAt < forceDedupeMs) {
+      log(`skip ${credential.name} lane=${lane.id} reason=just-refreshed`);
+      forced = false;
+      if (!isRefreshDue(lane, credential.files, meta, at, false)) continue;
+    }
+    if (!isRefreshDue(lane, credential.files, meta, at, forced)) continue;
+    summary.due += 1;
+    const http = opts.http ?? createLaneHttp(lane.endpoints);
+    const started = at;
+    const outcome = await lane.refresh(credential.files, http, at);
+    const finished = now();
+    const base = meta ?? emptyRefreshMeta(lane.id);
+    if (outcome.ok) {
+      summary.refreshed += 1;
+      await opts.storage.save(credential, outcome.files, {
+        ...base,
+        expiresAt: outcome.expiresAt ?? lane.expiresAt(outcome.files),
+        refreshedAt: finished,
+        attempts: 0,
+        lastAttemptAt: finished,
+        lastError: null,
+        needsSignIn: false,
+      });
+      log(
+        `refreshed ${credential.name} lane=${lane.id} ms=${finished - started} expiresAt=${
+          outcome.expiresAt ? new Date(outcome.expiresAt).toISOString() : "unknown"
+        }`,
+      );
+      continue;
+    }
+    if (outcome.terminal) {
+      summary.terminal += 1;
+      await opts.storage.save(credential, null, {
+        ...base,
+        attempts: base.attempts + 1,
+        lastAttemptAt: finished,
+        lastError: outcome.reason,
+        needsSignIn: true,
+      });
+      log(`terminal ${credential.name} lane=${lane.id} reason=${outcome.reason} → needs sign-in`);
+      continue;
+    }
+    summary.failed += 1;
+    await opts.storage.save(credential, null, {
+      ...base,
+      attempts: base.attempts + 1,
+      lastAttemptAt: finished,
+      lastError: outcome.reason,
+    });
+    log(
+      `failed ${credential.name} lane=${lane.id} attempt=${base.attempts + 1} reason=${outcome.reason} retryIn=${Math.round(backoffMs(base.attempts + 1) / 60_000)}m`,
+    );
+  }
+  return summary;
+}
+
+/** The copy a task may receive for a credential, or the files unchanged when
+ *  no lane owns them (static credentials). */
+export function brokeredFilesFor(
+  header: CredentialHeader,
+  files: CredentialFiles,
+  lanes: readonly TokenLane[] = TOKEN_LANES,
+): CredentialFiles {
+  const lane = lanes.find((l) => l.matches(header, files));
+  return lane ? lane.brokeredCopy(files) : files;
+}

package/lib/token-lanes/openai-oauth.ts

@@ -0,0 +1,119 @@
+/**
+ * Lane `openai-oauth` — Codex and opencode ChatGPT sign-ins (`auth.json`,
+ * `auth_mode: chatgpt`, `tokens: { access_token (JWT ~10 days), refresh_token
+ * (single-use, rotating), id_token, account_id }`).
+ *
+ * Refresh is `grant_type=refresh_token` against OpenAI's OIDC token endpoint
+ * with Codex's public client (no secret) — the same call `codex login` makes.
+ * Facts and the 2026-07-28 incident: docs/token-broker.md, PR #45.
+ */
+
+import {
+  BROKER_REFRESH_PLACEHOLDER,
+  isTerminalOAuthError,
+  jwtExpiryMs,
+  parseObjectFile,
+  type CredentialFiles,
+  type CredentialHeader,
+  type LaneHttp,
+  type RefreshOutcome,
+  type TokenLane,
+} from "./types";
+
+export const OPENAI_TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
+export const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function tokensOf(files: CredentialFiles): {
+  doc: Record<string, unknown>;
+  tokens: Record<string, unknown>;
+} | null {
+  const doc = parseObjectFile(files["auth.json"]);
+  if (!doc) return null;
+  const tokens = doc.tokens;
+  if (!tokens || typeof tokens !== "object" || Array.isArray(tokens)) return null;
+  return { doc, tokens: tokens as Record<string, unknown> };
+}
+
+export const openaiOAuthLane: TokenLane = {
+  id: "openai-oauth",
+  endpoints: [OPENAI_TOKEN_ENDPOINT],
+  schedule: { leadMs: 2 * DAY_MS },
+  reactiveSignals: [
+    /refresh token was revoked/i,
+    /refresh_token_reused/i,
+    /invalid_grant/i,
+    /log out and sign in again/i,
+  ],
+
+  matches(header: CredentialHeader, files: CredentialFiles): boolean {
+    if (header.authKind !== "config-dir") return false;
+    if (header.kind !== "codex" && header.kind !== "opencode") return false;
+    const t = tokensOf(files);
+    // API-key mode has no tokens block; nothing rotates.
+    return t !== null && typeof t.tokens.refresh_token === "string";
+  },
+
+  expiresAt(files: CredentialFiles): number | null {
+    const t = tokensOf(files);
+    return t ? jwtExpiryMs(t.tokens.access_token) : null;
+  },
+
+  brokeredCopy(files: CredentialFiles): CredentialFiles {
+    const t = tokensOf(files);
+    if (!t || typeof t.tokens.refresh_token !== "string") return files;
+    if (t.tokens.refresh_token === BROKER_REFRESH_PLACEHOLDER) return files;
+    t.tokens.refresh_token = BROKER_REFRESH_PLACEHOLDER;
+    return { ...files, "auth.json": `${JSON.stringify(t.doc, null, 2)}\n` };
+  },
+
+  async refresh(files: CredentialFiles, http: LaneHttp, now: number): Promise<RefreshOutcome> {
+    const t = tokensOf(files);
+    const current = t?.tokens.refresh_token;
+    if (!t || typeof current !== "string" || current === BROKER_REFRESH_PLACEHOLDER) {
+      return { ok: false, terminal: true, reason: "no refresh token to use" };
+    }
+    let res;
+    try {
+      res = await http.postJson(OPENAI_TOKEN_ENDPOINT, {
+        client_id: CODEX_CLIENT_ID,
+        grant_type: "refresh_token",
+        refresh_token: current,
+        scope: "openid profile email",
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        terminal: false,
+        reason: `request failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+    if (res.status < 200 || res.status >= 300) {
+      return {
+        ok: false,
+        terminal: isTerminalOAuthError(res.status, res.json),
+        reason: `HTTP ${res.status}`,
+      };
+    }
+    const body =
+      res.json && typeof res.json === "object" && !Array.isArray(res.json)
+        ? (res.json as Record<string, unknown>)
+        : null;
+    const access = body?.access_token;
+    const refresh = body?.refresh_token;
+    // Require BOTH before touching the credential — a partial answer must not
+    // half-rotate it.
+    if (typeof access !== "string" || typeof refresh !== "string") {
+      return { ok: false, terminal: false, reason: "response missing access_token/refresh_token" };
+    }
+    t.tokens.access_token = access;
+    t.tokens.refresh_token = refresh;
+    if (typeof body?.id_token === "string") t.tokens.id_token = body.id_token;
+    t.doc.last_refresh = new Date(now).toISOString();
+    return {
+      ok: true,
+      files: { ...files, "auth.json": `${JSON.stringify(t.doc, null, 2)}\n` },
+      expiresAt: jwtExpiryMs(access),
+    };
+  },
+};

package/lib/token-lanes/registry.ts

@@ -0,0 +1,45 @@
+/**
+ * The lane registry (ADR-135). Add a provider here and nowhere else; the
+ * host loop, the brokered-copy staging, the reactive matcher, and the broker
+ * Lambda all read this list.
+ */
+
+import { openaiOAuthLane } from "./openai-oauth";
+import { xaiOAuthLane } from "./xai-oauth";
+import type { CredentialFiles, CredentialHeader, TokenLane } from "./types";
+
+export const TOKEN_LANES: readonly TokenLane[] = [openaiOAuthLane, xaiOAuthLane];
+
+/** The lane that owns a credential, or null for static credentials. */
+export function laneFor(
+  header: CredentialHeader,
+  files: CredentialFiles,
+  lanes: readonly TokenLane[] = TOKEN_LANES,
+): TokenLane | null {
+  for (const lane of lanes) {
+    if (lane.matches(header, files)) return lane;
+  }
+  return null;
+}
+
+export function laneById(id: string, lanes: readonly TokenLane[] = TOKEN_LANES): TokenLane | null {
+  return lanes.find((lane) => lane.id === id) ?? null;
+}
+
+/** Lanes that can own credentials of an engine kind (for reactive matching
+ *  before the material is known). */
+export function lanesForKind(kind: string, lanes: readonly TokenLane[] = TOKEN_LANES): TokenLane[] {
+  return lanes.filter((lane) =>
+    lane.matches({ kind, authKind: "config-dir", id: "probe", scope: "host" }, PROBE_FILES[kind] ?? {}),
+  );
+}
+
+// Minimal material per kind that makes `matches` answer on kind alone.
+const PROBE_FILES: Record<string, CredentialFiles> = {
+  codex: { "auth.json": JSON.stringify({ tokens: { refresh_token: "x" } }) },
+  opencode: { "auth.json": JSON.stringify({ tokens: { refresh_token: "x" } }) },
+  grok: { "auth.json": JSON.stringify({ "https://auth.x.ai::c": { refresh_token: "x" } }) },
+};
+
+export { BROKER_REFRESH_PLACEHOLDER } from "./types";
+export type { CredentialFiles, CredentialHeader, TokenLane } from "./types";

package/lib/token-lanes/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Token lanes (ADR-135, docs/token-broker.md).
+ *
+ * A lane is everything the broker needs to know about ONE kind of rotating
+ * credential: which stored credentials it owns, the only endpoints it may
+ * talk to, how to read expiry, when to refresh, how to perform one refresh,
+ * what a task is allowed to receive (the brokered copy), and which engine
+ * error strings mean "the access token just died". The host loop and the
+ * broker Lambda load the same registry; a new provider is a new lane file.
+ *
+ * Lanes never log material. Everything they return is written by the broker
+ * core; nothing here touches storage or the network directly.
+ */
+
+/** Identity of a stored credential (the engine-account envelope fields). */
+export interface CredentialHeader {
+  kind: string;
+  authKind: "env" | "config-dir";
+  id: string;
+  scope: string;
+}
+
+/** A config-dir credential's files by basename (today: `auth.json`). */
+export type CredentialFiles = Record<string, string>;
+
+/** The broker-owned block stored beside the credential (`refresh` in the
+ *  store value, `uai-broker.json` beside a local dir). */
+export interface RefreshMeta {
+  lane: string;
+  expiresAt: number | null;
+  refreshedAt: number | null;
+  attempts: number;
+  lastAttemptAt: number | null;
+  lastError: string | null;
+  /** Terminal: the provider said the refresh token is dead. The broker stops;
+   *  the Engines page says "Sign in again"; the wizard replaces the credential. */
+  needsSignIn: boolean;
+}
+
+export type RefreshOutcome =
+  | { ok: true; files: CredentialFiles; expiresAt: number | null }
+  | { ok: false; terminal: true; reason: string }
+  | { ok: false; terminal: false; reason: string };
+
+export interface LaneHttpResponse {
+  status: number;
+  /** Parsed JSON body, or null when the body was not JSON. */
+  json: unknown;
+}
+
+/** The only network a lane gets. The broker core builds it with the lane's
+ *  endpoint allowlist; any other URL throws before a byte is sent. */
+export interface LaneHttp {
+  postJson(url: string, body: Record<string, unknown>): Promise<LaneHttpResponse>;
+  postForm(url: string, form: Record<string, string>): Promise<LaneHttpResponse>;
+}
+
+export interface LaneSchedule {
+  /** Refresh this long before the known expiry. */
+  leadMs?: number;
+  /** Refresh on this cadence when expiry cannot be read. */
+  everyMs?: number;
+}
+
+export interface TokenLane {
+  /** Stable id, stored in `RefreshMeta.lane`. */
+  readonly id: string;
+  /** Whether this lane owns a credential with this header and material. */
+  matches(header: CredentialHeader, files: CredentialFiles): boolean;
+  /** Every URL the lane may POST to. Enforced by the broker's http client. */
+  readonly endpoints: readonly string[];
+  /** When the access token expires (ms epoch), or null when unreadable. */
+  expiresAt(files: CredentialFiles): number | null;
+  readonly schedule: LaneSchedule;
+  /** Perform ONE refresh. Never writes; the core persists the outcome. */
+  refresh(files: CredentialFiles, http: LaneHttp, now: number): Promise<RefreshOutcome>;
+  /** The copy a task receives: access token kept, refresh token replaced.
+   *  Returns the input unchanged when there is nothing rotating in it. */
+  brokeredCopy(files: CredentialFiles): CredentialFiles;
+  /** Engine output that means the access token is dead now (reactive path). */
+  readonly reactiveSignals: readonly RegExp[];
+}
+
+/**
+ * What replaces a refresh token in a task's copy. A non-token string: a
+ * container that tries to rotate gets a benign `invalid_grant`, never a
+ * family revocation. Codex requires the FIELD to exist (deleting it fails with
+ * `missing field refresh_token`; validated 2026-07-28), hence replace, not
+ * remove.
+ */
+export const BROKER_REFRESH_PLACEHOLDER = "uai-broker-managed-no-refresh";
+
+export function emptyRefreshMeta(lane: string): RefreshMeta {
+  return {
+    lane,
+    expiresAt: null,
+    refreshedAt: null,
+    attempts: 0,
+    lastAttemptAt: null,
+    lastError: null,
+    needsSignIn: false,
+  };
+}
+
+/** Parse a stored `refresh` block; null when absent or malformed. */
+export function refreshMetaFrom(value: unknown): RefreshMeta | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const o = value as Record<string, unknown>;
+  if (typeof o.lane !== "string") return null;
+  const numOrNull = (v: unknown): number | null =>
+    typeof v === "number" && Number.isFinite(v) ? v : null;
+  return {
+    lane: o.lane,
+    expiresAt: numOrNull(o.expiresAt),
+    refreshedAt: numOrNull(o.refreshedAt),
+    attempts: typeof o.attempts === "number" && o.attempts >= 0 ? Math.floor(o.attempts) : 0,
+    lastAttemptAt: numOrNull(o.lastAttemptAt),
+    lastError: typeof o.lastError === "string" ? o.lastError : null,
+    needsSignIn: o.needsSignIn === true,
+  };
+}
+
+/** `exp` (ms epoch) of a JWT access token, or null when it is not one. */
+export function jwtExpiryMs(token: unknown): number | null {
+  if (typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length < 2 || !parts[1]) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as {
+      exp?: unknown;
+    };
+    return typeof payload.exp === "number" && Number.isFinite(payload.exp)
+      ? payload.exp * 1000
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a JSON object file; null for anything that is not a plain object. */
+export function parseObjectFile(text: string | undefined): Record<string, unknown> | null {
+  if (typeof text !== "string") return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** Provider answers that mean the refresh token itself is dead. */
+export function isTerminalOAuthError(status: number, json: unknown): boolean {
+  const error =
+    json && typeof json === "object" && !Array.isArray(json)
+      ? (json as Record<string, unknown>).error
+      : undefined;
+  const text = typeof error === "string" ? error : "";
+  return (
+    /invalid_grant|refresh_token_reused|revoked|unauthorized_client|invalid_client/i.test(text) ||
+    ((status === 400 || status === 401 || status === 403) && text.length > 0)
+  );
+}