@runuai/host 0.9.150 → 0.9.151

package/src/cloud-credentials.ts

@@ -0,0 +1,2399 @@
+/**
+ * ADR-154 — the shared contract for cloud-only credentials.
+ *
+ * Every repository env value, AI account, MCP connection, GitHub sign-in and
+ * SSH key has one copy, in Parameter Store. A runner (owned or task machine)
+ * reads what one live task needs under that task's lease and keeps it in
+ * memory only. This module is what the cloud and the runner agree on:
+ *
+ *  - the parameter layout: lease-readable copies under `/uai/lease`, the
+ *    broker-only OAuth material under the disjoint root `/uai-broker`, each
+ *    credential's material in immutable revisions;
+ *  - the v1 grant: the task's credential manifest (names and versions, never
+ *    values) and the STS sessions that read it;
+ *  - the frames that renew, narrow, refresh and activate it.
+ *
+ * It holds no I/O and imports nothing, so the cloud, the runner and the
+ * sign-in box can all load it. Every parser is exact: unknown keys, wrong
+ * types and out-of-bound sizes are refused, never dropped or repaired.
+ */
+
+/** Advertised by a runner that reads credentials only through v1 leases. */
+export const HOST_CLOUD_CREDENTIALS_FEATURE = "host-cloud-credentials-v1";
+
+// ---------------------------------------------------------------------------
+// Parameter layout
+// ---------------------------------------------------------------------------
+
+/** What a task may receive: a static key, or an OAuth login's brokered copy. */
+export const LEASE_PARAMETER_ROOT = "/uai/lease";
+/**
+ * The full OAuth material only the broker reads. Outside `/uai` altogether:
+ * `GetParametersByPath` returns every descendant of a path its caller may
+ * read, even one a Deny names, so containment comes from the root alone.
+ */
+export const BROKER_PARAMETER_ROOT = "/uai-broker";
+
+export type CredentialClass = "engine" | "mcp" | "github" | "ssh";
+export type CredentialScope = "org" | "user";
+
+/** Where one revision of one credential lives. */
+export interface CredentialLocation {
+  class: CredentialClass;
+  /** `github` and `ssh` are always `user`: one per person. */
+  scope: CredentialScope;
+  /** The org id for `org` scope, the user id for `user` scope. */
+  ownerId: string;
+  /** `engine` only: the engine kind (`codex`, `claude`, …). */
+  engineKind?: string;
+  /** `engine` and `mcp` only: the credential's stable id. */
+  credentialId?: string;
+  /** One immutable revision of the material. */
+  revision: string;
+}
+
+/** SSM allows `[A-Za-z0-9_.-]` in a path segment. An id that already fits,
+ *  starts with a letter or digit and has no dot is used as it is; any other
+ *  id is `-` followed by the hex of its UTF-8 bytes. No plain id starts with
+ *  `-`, so the mapping is injective. Legacy workspace ids
+ *  (`personal:<user>`) take the second form. */
+const PLAIN_ID_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const ENCODED_ID_SEGMENT = /^-(?:[0-9a-f]{2})+$/;
+const ENGINE_KIND = /^[a-z][a-z0-9-]{0,31}$/;
+export const MAX_CREDENTIAL_ID_CHARS = 128;
+/** SSM's limit for a parameter name, its ARN included. */
+export const MAX_PARAMETER_NAME_CHARS = 1011;
+
+function isIdValue(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_CREDENTIAL_ID_CHARS &&
+    !/[\u0000-\u001f\u007f]/.test(value)
+  );
+}
+
+function utf8Hex(value: string): string {
+  let out = "";
+  for (const byte of new TextEncoder().encode(value)) {
+    out += byte.toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+function fromUtf8Hex(hex: string): string | null {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** The path segment for an id (see `PLAIN_ID_SEGMENT`). Throws on an id no
+ *  segment may carry: empty, too long, or containing control characters. */
+export function idPathSegment(id: string): string {
+  if (!isIdValue(id)) throw new Error("invalid credential path id");
+  return PLAIN_ID_SEGMENT.test(id) ? id : `-${utf8Hex(id)}`;
+}
+
+/** Inverse of `idPathSegment`; null for a segment it never produces. */
+export function parseIdPathSegment(segment: string): string | null {
+  if (PLAIN_ID_SEGMENT.test(segment)) {
+    return segment.length <= MAX_CREDENTIAL_ID_CHARS ? segment : null;
+  }
+  if (!ENCODED_ID_SEGMENT.test(segment)) return null;
+  const id = fromUtf8Hex(segment.slice(1));
+  if (id === null || !isIdValue(id) || PLAIN_ID_SEGMENT.test(id)) return null;
+  return id;
+}
+
+export function isEngineKind(value: unknown): value is string {
+  return typeof value === "string" && ENGINE_KIND.test(value);
+}
+
+function locationSegments(location: CredentialLocation): string[] {
+  const owner = location.scope === "org" ? "orgs" : "users";
+  const segments = [owner, idPathSegment(location.ownerId)];
+  switch (location.class) {
+    case "engine": {
+      if (!isEngineKind(location.engineKind)) {
+        throw new Error("invalid engine kind");
+      }
+      if (location.credentialId === undefined) {
+        throw new Error("an engine credential needs its id");
+      }
+      segments.push(
+        "engines",
+        location.engineKind,
+        idPathSegment(location.credentialId),
+      );
+      break;
+    }
+    case "mcp": {
+      if (location.engineKind !== undefined) {
+        throw new Error("an MCP credential has no engine kind");
+      }
+      if (location.credentialId === undefined) {
+        throw new Error("an MCP credential needs its id");
+      }
+      segments.push("mcp", idPathSegment(location.credentialId));
+      break;
+    }
+    case "github":
+    case "ssh": {
+      if (location.scope !== "user") {
+        throw new Error(`${location.class} credentials belong to a user`);
+      }
+      if (
+        location.engineKind !== undefined ||
+        location.credentialId !== undefined
+      ) {
+        throw new Error(`${location.class} has one credential per person`);
+      }
+      segments.push(location.class);
+      break;
+    }
+    default:
+      throw new Error("invalid credential class");
+  }
+  segments.push(idPathSegment(location.revision));
+  return segments;
+}
+
+function nameUnder(root: string, location: CredentialLocation): string {
+  const name = `${root}/${locationSegments(location).join("/")}`;
+  if (name.length > MAX_PARAMETER_NAME_CHARS) {
+    throw new Error("credential parameter name too long");
+  }
+  return name;
+}
+
+/** The lease-readable parameter of one revision. */
+export function leaseParameterName(location: CredentialLocation): string {
+  return nameUnder(LEASE_PARAMETER_ROOT, location);
+}
+
+/** The broker-only parameter of one revision of an OAuth credential. GitHub
+ *  tokens and SSH keys are static and have none. */
+export function brokerParameterName(location: CredentialLocation): string {
+  if (location.class === "github" || location.class === "ssh") {
+    throw new Error(`${location.class} credentials have no broker part`);
+  }
+  return nameUnder(BROKER_PARAMETER_ROOT, location);
+}
+
+function parseUnder(root: string, name: string): CredentialLocation | null {
+  if (
+    typeof name !== "string" ||
+    name.length > MAX_PARAMETER_NAME_CHARS ||
+    !name.startsWith(`${root}/`)
+  ) {
+    return null;
+  }
+  const parts = name.slice(root.length + 1).split("/");
+  const [ownerKind, ownerSegment] = parts;
+  const scope: CredentialScope | null =
+    ownerKind === "orgs" ? "org" : ownerKind === "users" ? "user" : null;
+  if (scope === null || ownerSegment === undefined) return null;
+  const ownerId = parseIdPathSegment(ownerSegment);
+  if (ownerId === null) return null;
+  const revisionOf = (segment: string | undefined): string | null =>
+    segment === undefined ? null : parseIdPathSegment(segment);
+
+  if (parts[2] === "engines" && parts.length === 6) {
+    const credentialId = parseIdPathSegment(parts[4]!);
+    const revision = revisionOf(parts[5]);
+    if (!isEngineKind(parts[3]) || credentialId === null || revision === null) {
+      return null;
+    }
+    return {
+      class: "engine",
+      scope,
+      ownerId,
+      engineKind: parts[3],
+      credentialId,
+      revision,
+    };
+  }
+  if (parts[2] === "mcp" && parts.length === 5) {
+    const credentialId = parseIdPathSegment(parts[3]!);
+    const revision = revisionOf(parts[4]);
+    if (credentialId === null || revision === null) return null;
+    return { class: "mcp", scope, ownerId, credentialId, revision };
+  }
+  if (
+    (parts[2] === "github" || parts[2] === "ssh") &&
+    parts.length === 4 &&
+    scope === "user"
+  ) {
+    const revision = revisionOf(parts[3]);
+    if (revision === null) return null;
+    return { class: parts[2], scope, ownerId, revision };
+  }
+  return null;
+}
+
+export function parseLeaseParameterName(
+  name: string,
+): CredentialLocation | null {
+  return parseUnder(LEASE_PARAMETER_ROOT, name);
+}
+
+export function parseBrokerParameterName(
+  name: string,
+): CredentialLocation | null {
+  const location = parseUnder(BROKER_PARAMETER_ROOT, name);
+  return location && (location.class === "engine" || location.class === "mcp")
+    ? location
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// Lease-readable values
+// ---------------------------------------------------------------------------
+
+/** An Advanced-tier parameter holds 8 KiB; every envelope must fit. */
+export const MAX_CREDENTIAL_VALUE_BYTES = 8 * 1024;
+
+/** The env vars an env-token engine's account may set, per engine kind. A
+ *  value naming any other variable is refused, so a stored account can never
+ *  set `LD_PRELOAD` or `PATH` on an agent's spawn. */
+export const ENGINE_ENV_CREDENTIAL_KEYS: Readonly<Record<string, readonly string[]>> = {
+  claude: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+  cursor: ["CURSOR_API_KEY"],
+  grok: ["XAI_API_KEY"],
+};
+
+/** The files a config-directory engine's account may carry, per engine kind:
+ *  only what the lane owns, written into the engine's home, nothing else. */
+export const ENGINE_CREDENTIAL_FILES: Readonly<Record<string, readonly string[]>> = {
+  codex: ["auth.json"],
+  grok: ["auth.json"],
+  opencode: ["auth.json"],
+};
+
+interface LeasedValueBase {
+  v: 1;
+  part: "lease";
+  /** The parameter this value belongs to, which the reader checks: a value
+   *  copied to another credential's or revision's parameter is refused. */
+  location: CredentialLocation;
+}
+
+export type LeasedValue =
+  | (LeasedValueBase & { class: "engine"; authKind: "env"; env: Record<string, string> })
+  | (LeasedValueBase & {
+      class: "engine";
+      authKind: "config-dir";
+      /** The brokered copy: access token in, refresh token replaced by the
+       *  broker's placeholder. */
+      files: Record<string, string>;
+      expiresAt: number | null;
+    })
+  | (LeasedValueBase & { class: "mcp"; authKind: "token"; header: { name: string; value: string } })
+  | (LeasedValueBase & {
+      class: "mcp";
+      authKind: "oauth";
+      accessToken: string;
+      tokenType: "Bearer";
+      expiresAt: number | null;
+    })
+  | (LeasedValueBase & { class: "github"; token: string })
+  | (LeasedValueBase & { class: "ssh"; privateKey: string; publicKey: string });
+
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+/** Hop-by-hop and routing headers a stored connection may not set. */
+const FORBIDDEN_HEADER_NAMES = new Set([
+  "connection",
+  "content-length",
+  "host",
+  "keep-alive",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+function sameLocation(a: CredentialLocation, b: CredentialLocation): boolean {
+  return (
+    a.class === b.class &&
+    a.scope === b.scope &&
+    a.ownerId === b.ownerId &&
+    a.engineKind === b.engineKind &&
+    a.credentialId === b.credentialId &&
+    a.revision === b.revision
+  );
+}
+
+function parseLocationField(value: unknown): CredentialLocation | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const o = value as WireObject;
+  const keys = Object.keys(o);
+  const allowed = new Set(["class", "scope", "ownerId", "engineKind", "credentialId", "revision"]);
+  if (keys.some((key) => !allowed.has(key))) return null;
+  if (
+    (o.class !== "engine" && o.class !== "mcp" && o.class !== "github" && o.class !== "ssh") ||
+    !isScope(o.scope) ||
+    !isIdValue(o.ownerId) ||
+    !isIdValue(o.revision) ||
+    !(o.engineKind === undefined || isEngineKind(o.engineKind)) ||
+    !(o.credentialId === undefined || isIdValue(o.credentialId))
+  ) {
+    return null;
+  }
+  const location: CredentialLocation = {
+    class: o.class,
+    scope: o.scope,
+    ownerId: o.ownerId,
+    ...(o.engineKind !== undefined ? { engineKind: o.engineKind as string } : {}),
+    ...(o.credentialId !== undefined ? { credentialId: o.credentialId as string } : {}),
+    revision: o.revision,
+  };
+  try {
+    leaseParameterName(location);
+  } catch {
+    return null;
+  }
+  return location;
+}
+
+function parseStringMap(
+  value: unknown,
+  allowedKeys: readonly string[],
+  maxChars: number,
+): Record<string, string> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const entries = Object.entries(value as WireObject);
+  if (entries.length === 0) return null;
+  const out: Record<string, string> = {};
+  for (const [key, item] of entries) {
+    if (!allowedKeys.includes(key) || !isBoundedString(item, maxChars)) return null;
+    out[key] = item;
+  }
+  return out;
+}
+
+/** The JSON a writer stores in a lease-readable parameter. */
+export function serializeLeasedValue(value: LeasedValue): string {
+  const json = canonicalJson(value);
+  if (new TextEncoder().encode(json).length > MAX_CREDENTIAL_VALUE_BYTES) {
+    throw new Error("credential value too large for one parameter");
+  }
+  return json;
+}
+
+/**
+ * A lease-readable value, read from the parameter at `expected`, or null.
+ * Exact like every parser here, and bound to its parameter: the envelope's
+ * location must be the one the reader asked for, so a value copied into
+ * another credential's or revision's parameter is refused, not used.
+ */
+export function parseLeasedValue(
+  raw: string,
+  expected: CredentialLocation,
+): LeasedValue | null {
+  if (
+    typeof raw !== "string" ||
+    new TextEncoder().encode(raw).length > MAX_CREDENTIAL_VALUE_BYTES
+  ) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const o = parsed as WireObject;
+  if (o.v !== 1 || o.part !== "lease") return null;
+  const location = parseLocationField(o.location);
+  if (!location || !sameLocation(location, expected) || o.class !== location.class) {
+    return null;
+  }
+  const base = { v: 1 as const, part: "lease" as const, location };
+  switch (location.class) {
+    case "engine": {
+      const kind = location.engineKind!;
+      if (o.authKind === "env") {
+        const env = exactObject(o, ["v", "part", "location", "class", "authKind", "env"])
+          ? parseStringMap(o.env, ENGINE_ENV_CREDENTIAL_KEYS[kind] ?? [], 4096)
+          : null;
+        return env ? { ...base, class: "engine", authKind: "env", env } : null;
+      }
+      if (o.authKind === "config-dir") {
+        if (
+          !exactObject(o, ["v", "part", "location", "class", "authKind", "files", "expiresAt"]) ||
+          !(o.expiresAt === null || isEpochMs(o.expiresAt))
+        ) {
+          return null;
+        }
+        const files = parseStringMap(o.files, ENGINE_CREDENTIAL_FILES[kind] ?? [], MAX_CREDENTIAL_VALUE_BYTES);
+        return files
+          ? { ...base, class: "engine", authKind: "config-dir", files, expiresAt: o.expiresAt }
+          : null;
+      }
+      return null;
+    }
+    case "mcp": {
+      if (o.authKind === "token") {
+        const header = exactObject(o.header, ["name", "value"]);
+        if (
+          !exactObject(o, ["v", "part", "location", "class", "authKind", "header"]) ||
+          !header ||
+          typeof header.name !== "string" ||
+          !HEADER_NAME.test(header.name) ||
+          FORBIDDEN_HEADER_NAMES.has(header.name.toLowerCase()) ||
+          !isBoundedString(header.value, 4096) ||
+          /[\r\n]/.test(header.value)
+        ) {
+          return null;
+        }
+        return {
+          ...base,
+          class: "mcp",
+          authKind: "token",
+          header: { name: header.name, value: header.value },
+        };
+      }
+      if (o.authKind === "oauth") {
+        if (
+          !exactObject(o, ["v", "part", "location", "class", "authKind", "accessToken", "tokenType", "expiresAt"]) ||
+          !isBoundedString(o.accessToken, 4096) ||
+          /[\r\n]/.test(o.accessToken) ||
+          o.tokenType !== "Bearer" ||
+          !(o.expiresAt === null || isEpochMs(o.expiresAt))
+        ) {
+          return null;
+        }
+        return {
+          ...base,
+          class: "mcp",
+          authKind: "oauth",
+          accessToken: o.accessToken,
+          tokenType: "Bearer",
+          expiresAt: o.expiresAt,
+        };
+      }
+      return null;
+    }
+    case "github":
+      return exactObject(o, ["v", "part", "location", "class", "token"]) &&
+        isBoundedString(o.token, 512) &&
+        !/\s/.test(o.token)
+        ? { ...base, class: "github", token: o.token }
+        : null;
+    case "ssh":
+      return exactObject(o, ["v", "part", "location", "class", "privateKey", "publicKey"]) &&
+        isBoundedString(o.privateKey, 4096) &&
+        isBoundedString(o.publicKey, 1024)
+        ? { ...base, class: "ssh", privateKey: o.privateKey, publicKey: o.publicKey }
+        : null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Capture flows (cloud ↔ sign-in box)
+// ---------------------------------------------------------------------------
+
+/** Advertised by a sign-in box that writes captures as ADR-154 revisions. */
+export const SIGNIN_BOX_CAPTURE_FLOWS_FEATURE = "signin-box-capture-flows-v1";
+
+/**
+ * What the cloud tells the sign-in box to write for one capture: the
+ * revision's parameters (the box never chooses a name) and the ids it tags
+ * them with. The box checks every field against the others before it writes.
+ */
+export interface CaptureFlowWire {
+  credentialId: string;
+  revision: string;
+  leaseParameter: string;
+  /** Null for a static credential. */
+  brokerParameter: string | null;
+  /** The workspace tag: required except for GitHub and SSH. */
+  orgId: string | null;
+  /** The person, for a personal credential. */
+  userId: string | null;
+}
+
+/** What the box answers once both parts are written: never material. */
+export interface CaptureResultWire {
+  credentialId: string;
+  revision: string;
+  /** The lease-readable parameter's Parameter Store version. */
+  leaseVersion: number;
+  /** The access token's expiry when the box could read it. */
+  expiresAt: number | null;
+}
+
+/**
+ * A capture flow, rebuilt and checked, with the location its parameters name,
+ * or null. The two parameters must name the same credential and revision under
+ * their own roots, and the tags must be the parameter's owner: a workspace
+ * credential's `orgId` is its owner and it has no `userId`; a personal AI
+ * account or MCP connection names both its person and its workspace; GitHub
+ * and SSH name their person alone.
+ */
+export function parseCaptureFlowWire(
+  value: unknown,
+): (CaptureFlowWire & { location: CredentialLocation }) | null {
+  const o = exactObject(value, [
+    "credentialId",
+    "revision",
+    "leaseParameter",
+    "brokerParameter",
+    "orgId",
+    "userId",
+  ]);
+  if (
+    !o ||
+    !isIdValue(o.credentialId) ||
+    !isIdValue(o.revision) ||
+    typeof o.leaseParameter !== "string" ||
+    !(o.brokerParameter === null || typeof o.brokerParameter === "string") ||
+    !(o.orgId === null || (isIdValue(o.orgId) && isTagValue(o.orgId))) ||
+    !(o.userId === null || (isIdValue(o.userId) && isTagValue(o.userId)))
+  ) {
+    return null;
+  }
+  const location = parseLeaseParameterName(o.leaseParameter);
+  if (!location || location.revision !== o.revision) return null;
+  const isPerson = location.class === "github" || location.class === "ssh";
+  if (!isPerson && location.credentialId !== o.credentialId) return null;
+  if (o.brokerParameter !== null) {
+    const broker = parseBrokerParameterName(o.brokerParameter);
+    if (!broker || !sameLocation(broker, location)) return null;
+  }
+  if (isPerson && o.brokerParameter !== null) return null;
+  const ownerOk =
+    location.scope === "org"
+      ? o.orgId === location.ownerId && o.userId === null
+      : o.userId === location.ownerId && (isPerson ? o.orgId === null : o.orgId !== null);
+  if (!ownerOk) return null;
+  return {
+    credentialId: o.credentialId,
+    revision: o.revision,
+    leaseParameter: o.leaseParameter,
+    brokerParameter: o.brokerParameter,
+    orgId: o.orgId,
+    userId: o.userId,
+    location,
+  };
+}
+
+export function parseCaptureResultWire(value: unknown): CaptureResultWire | null {
+  const o = exactObject(value, ["credentialId", "revision", "leaseVersion", "expiresAt"]);
+  return o &&
+    isIdValue(o.credentialId) &&
+    isIdValue(o.revision) &&
+    isPositiveInteger(o.leaseVersion) &&
+    (o.expiresAt === null || isEpochMs(o.expiresAt))
+    ? {
+        credentialId: o.credentialId,
+        revision: o.revision,
+        leaseVersion: o.leaseVersion,
+        expiresAt: o.expiresAt,
+      }
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// Session tags
+// ---------------------------------------------------------------------------
+
+/**
+ * Every v1 `credentials` session carries `lease=v1`, and every role statement
+ * that grants `/uai/lease` requires it, so the statements v1 adds never widen
+ * a v0 session (which carries no such tag).
+ */
+export const LEASE_V1_SESSION_TAG = { key: "lease", value: "v1" } as const;
+/** The session tag the role policy puts into `/uai/lease/orgs/${…}` paths:
+ *  the workspace id as `idPathSegment` writes it. `org` keeps the raw id,
+ *  which resource-tag conditions compare. */
+export const ORG_PATH_SESSION_TAG_KEY = "orgseg";
+
+const TAG_VALUE = /^[\p{L}\p{Z}\p{N}_.:/=+\-@]{1,256}$/u;
+
+/** STS session tag and SSM resource tag values: the same grammar, refused
+ *  rather than rewritten, so a principal tag and a resource tag written for
+ *  one id always compare equal. */
+export function isTagValue(value: unknown): value is string {
+  return typeof value === "string" && TAG_VALUE.test(value);
+}
+
+// ---------------------------------------------------------------------------
+// The v1 grant and its manifest
+// ---------------------------------------------------------------------------
+
+export const MAX_LEASE_SESSIONS = 5;
+export const MAX_LEASE_CREDENTIAL_SESSIONS = 4;
+export const MAX_MANIFEST_PROJECTS = 32;
+export const MAX_MANIFEST_ENGINES = 64;
+export const MAX_MANIFEST_MCP = 64;
+export const MAX_MANIFEST_LABEL_CHARS = 64;
+export const MAX_MANIFEST_URL_CHARS = 2048;
+export const MAX_MANIFEST_SLUG_CHARS = 64;
+export const MAX_LEASE_ERROR_CHARS = 512;
+const MAX_LEASE_OP_ID_CHARS = 128;
+const MAX_SESSION_SECRET_CHARS = 4096;
+const MAX_REGION_CHARS = 32;
+const MAX_BUCKET_CHARS = 63;
+const MAX_PREFIX_CHARS = 512;
+const DIGEST = /^[0-9a-f]{64}$/;
+const OP_ID = /^[A-Za-z0-9_-]+$/;
+
+export type LeaseSessionPurpose = "files" | "credentials";
+
+/** One STS session. A task machine's grant has exactly one `files` session,
+ *  which only Mountpoint uses; an owned runner's has none. */
+export interface LeaseSession {
+  id: string;
+  purpose: LeaseSessionPurpose;
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+  /** Epoch ms. */
+  expiresAt: number;
+}
+
+export interface LeaseManifestProject {
+  projectId: string;
+  /** The session whose policy names this project's env values. */
+  sessionId: string;
+}
+
+export interface LeaseManifestEngine {
+  credentialId: string;
+  revision: string;
+  /** The revision's lease-readable parameter. */
+  parameter: string;
+  /** Its Parameter Store version as the cloud last recorded it. */
+  version: number;
+  expiresAt: number | null;
+  sessionId: string;
+  engineKind: string;
+  scope: CredentialScope;
+  label: string;
+  authKind: "env" | "config-dir";
+  /** Position within its scope; the list itself is already in try order. */
+  position: number;
+}
+
+export interface LeaseManifestMcp {
+  credentialId: string;
+  slug: string;
+  url: string;
+  scope: CredentialScope;
+  authKind: "oauth" | "token" | "none";
+  /** Null exactly when `authKind` is `none`: nothing secret to read. */
+  revision: string | null;
+  parameter: string | null;
+  version: number | null;
+  expiresAt: number | null;
+  sessionId: string | null;
+}
+
+export interface LeaseManifestStatic {
+  credentialId: string;
+  revision: string;
+  parameter: string;
+  version: number;
+  sessionId: string;
+}
+
+/** What a task may read, by name and version — never a value. */
+export interface CredentialManifest {
+  /** The task's projects, lead first. */
+  projects: LeaseManifestProject[];
+  /** Per engine kind: the owner's personal accounts, then the workspace's. */
+  engines: LeaseManifestEngine[];
+  mcp: LeaseManifestMcp[];
+  github: LeaseManifestStatic | null;
+  ssh: LeaseManifestStatic | null;
+}
+
+export interface LeaseFiles {
+  bucket: string;
+  orgPrefix: string | null;
+  userPrefix: string;
+}
+
+/** ADR-154 §4: the grant a v1 runner installs for one live task. */
+export interface TaskLeaseV1 {
+  v: 1;
+  leaseId: string;
+  taskId: string;
+  orgId: string;
+  userId: string;
+  /** The task's run epoch: advanced by the cloud at every start, resume and
+   *  wake. With the runner the task is assigned to, it is the assignment a
+   *  grant, a replica frame and the cleanup inventory are fenced to. */
+  runEpoch: number;
+  /** Only grows per task. */
+  manifestRevision: number;
+  /** sha256 (lowercase hex) of `canonicalManifestJson(manifest)`. */
+  manifestDigest: string;
+  region: string;
+  sessions: LeaseSession[];
+  /** Present exactly when a `files` session is. */
+  files: LeaseFiles | null;
+  manifest: CredentialManifest;
+}
+
+/**
+ * A task command's run epoch (`TaskCommandTask.runEpoch`): undefined when
+ * absent, since a cloud that predates ADR-154 sends none. A present value that
+ * is not a positive safe integer throws; it is never read as absent.
+ */
+export function runEpochFromWire(
+  value: unknown,
+  field = "runEpoch",
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (!isPositiveInteger(value)) throw new Error(`invalid ${field}`);
+  return value;
+}
+
+/** A grant expires with its earliest session. */
+export function taskLeaseV1ExpiresAt(lease: TaskLeaseV1): number {
+  return Math.min(...lease.sessions.map((session) => session.expiresAt));
+}
+
+/**
+ * The bytes `manifestDigest` covers: JSON with every object's keys sorted,
+ * arrays in order, no whitespace. Callers hash it with their own crypto, so
+ * this module stays loadable everywhere.
+ */
+export function canonicalManifestJson(manifest: CredentialManifest): string {
+  return canonicalJson(manifest);
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record)
+    .filter((key) => record[key] !== undefined)
+    .sort();
+  return `{${keys
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+    .join(",")}}`;
+}
+
+// ---------------------------------------------------------------------------
+// Frames
+// ---------------------------------------------------------------------------
+
+/** Runner → cloud: a v1 lease request for one exact task run. */
+export interface LeaseRequestV1Frame {
+  kind: "lease.request";
+  opId: string;
+  taskId: string;
+  runEpoch: number;
+}
+
+/** Cloud → runner: a v1 grant answering `lease.request`. A separate kind from
+ *  ADR-133's `lease.grant`, so a runner that predates v1 drops it unread. */
+export interface LeaseGrantV1Frame {
+  kind: "lease.grant.v1";
+  opId: string;
+  lease: TaskLeaseV1;
+}
+
+/** Cloud → runner: STS or the network failed; ask again later. Not a denial:
+ *  the runner keeps an unexpired grant that is not below `minRevision`. */
+export interface LeaseUnavailableFrame {
+  kind: "lease.unavailable";
+  opId: string;
+  error: string;
+}
+
+/**
+ * Cloud → runner: the task's credentials changed. Renew until a grant at or
+ * above `wantedRevision` is installed. With `minRevision`, grants below it are
+ * unusable at once and `removed` names the credentials that left, whose
+ * cleanup runs before the next grant is installed.
+ */
+export interface LeaseStaleFrame {
+  kind: "lease.stale";
+  taskId: string;
+  runEpoch: number;
+  wantedRevision: number;
+  minRevision: number | null;
+  removed: string[];
+}
+
+/** Cloud → runner: a credential the task's manifest names has a new version
+ *  of its lease-readable parameter (a broker refresh). */
+export interface CredentialChangedFrame {
+  kind: "credential.changed";
+  taskId: string;
+  runEpoch: number;
+  credentialId: string;
+  revision: string;
+  version: number;
+}
+
+/** Runner → cloud: a credential-invalid signal or an MCP 401. */
+export interface CredentialRefreshFrame {
+  kind: "credential.refresh";
+  opId: string;
+  taskId: string;
+  runEpoch: number;
+  credentialId: string;
+  revision: string;
+}
+
+export type CredentialRefreshOutcome =
+  | "refreshed"
+  | "fresh"
+  | "needs_sign_in"
+  | "busy"
+  | "unavailable";
+
+/** Cloud → runner: the broker's typed answer, never material. `version` and
+ *  `expiresAt` accompany `refreshed` and `fresh` only. */
+export interface CredentialRefreshResultFrame {
+  kind: "credential.refresh.result";
+  opId: string;
+  outcome: CredentialRefreshOutcome;
+  version: number | null;
+  expiresAt: number | null;
+}
+
+export type CredentialsActivationPhase = "prepare" | "commit";
+
+/** Runner → cloud: ADR-154 §13's prepare and commit steps. */
+export interface CredentialsActivateFrame {
+  kind: "credentials.activate";
+  opId: string;
+  phase: CredentialsActivationPhase;
+}
+
+export interface CredentialsActivateResultFrame {
+  kind: "credentials.activate.result";
+  opId: string;
+  phase: CredentialsActivationPhase;
+  ok: boolean;
+  error: string | null;
+}
+
+/** Runner → cloud: the purge is complete; the runner now advertises v1. */
+export interface CredentialsActivatedFrame {
+  kind: "credentials.activated";
+  opId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Parsers
+// ---------------------------------------------------------------------------
+
+type WireObject = Record<string, unknown>;
+
+function exactObject(
+  value: unknown,
+  required: readonly string[],
+): WireObject | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const object = value as WireObject;
+  const keys = Object.keys(object);
+  if (
+    keys.length !== required.length ||
+    required.some((key) => !Object.hasOwn(object, key))
+  ) {
+    return null;
+  }
+  return object;
+}
+
+function isBoundedString(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+
+function isOpId(value: unknown): value is string {
+  return isBoundedString(value, MAX_LEASE_OP_ID_CHARS) && OP_ID.test(value);
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) > 0;
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+
+function isEpochMs(value: unknown): value is number {
+  return isPositiveInteger(value);
+}
+
+function isScope(value: unknown): value is CredentialScope {
+  return value === "org" || value === "user";
+}
+
+function uniqueBy<T>(items: readonly T[], key: (item: T) => string): boolean {
+  return new Set(items.map(key)).size === items.length;
+}
+
+function parseSession(value: unknown): LeaseSession | null {
+  const o = exactObject(value, [
+    "id",
+    "purpose",
+    "accessKeyId",
+    "secretAccessKey",
+    "sessionToken",
+    "expiresAt",
+  ]);
+  if (
+    !o ||
+    !isOpId(o.id) ||
+    (o.purpose !== "files" && o.purpose !== "credentials") ||
+    !isBoundedString(o.accessKeyId, 128) ||
+    !isBoundedString(o.secretAccessKey, MAX_SESSION_SECRET_CHARS) ||
+    !isBoundedString(o.sessionToken, MAX_SESSION_SECRET_CHARS) ||
+    !isEpochMs(o.expiresAt)
+  ) {
+    return null;
+  }
+  return {
+    id: o.id,
+    purpose: o.purpose,
+    accessKeyId: o.accessKeyId,
+    secretAccessKey: o.secretAccessKey,
+    sessionToken: o.sessionToken,
+    expiresAt: o.expiresAt,
+  };
+}
+
+/** The owner a lease parameter must belong to, for a grant's org and user. */
+function belongsTo(
+  location: CredentialLocation,
+  grant: { orgId: string; userId: string },
+): boolean {
+  return location.scope === "org"
+    ? location.ownerId === grant.orgId
+    : location.ownerId === grant.userId;
+}
+
+function parseEngine(
+  value: unknown,
+  grant: { orgId: string; userId: string },
+  credentialSessions: ReadonlySet<string>,
+): LeaseManifestEngine | null {
+  const o = exactObject(value, [
+    "credentialId",
+    "revision",
+    "parameter",
+    "version",
+    "expiresAt",
+    "sessionId",
+    "engineKind",
+    "scope",
+    "label",
+    "authKind",
+    "position",
+  ]);
+  if (
+    !o ||
+    !isIdValue(o.credentialId) ||
+    !isIdValue(o.revision) ||
+    typeof o.parameter !== "string" ||
+    !isPositiveInteger(o.version) ||
+    !(o.expiresAt === null || isEpochMs(o.expiresAt)) ||
+    typeof o.sessionId !== "string" ||
+    !credentialSessions.has(o.sessionId) ||
+    !isEngineKind(o.engineKind) ||
+    !isScope(o.scope) ||
+    !isBoundedString(o.label, MAX_MANIFEST_LABEL_CHARS) ||
+    (o.authKind !== "env" && o.authKind !== "config-dir") ||
+    !isNonNegativeInteger(o.position)
+  ) {
+    return null;
+  }
+  const location = parseLeaseParameterName(o.parameter);
+  if (
+    !location ||
+    location.class !== "engine" ||
+    location.scope !== o.scope ||
+    location.engineKind !== o.engineKind ||
+    location.credentialId !== o.credentialId ||
+    location.revision !== o.revision ||
+    !belongsTo(location, grant)
+  ) {
+    return null;
+  }
+  return {
+    credentialId: o.credentialId,
+    revision: o.revision,
+    parameter: o.parameter,
+    version: o.version,
+    expiresAt: o.expiresAt,
+    sessionId: o.sessionId,
+    engineKind: o.engineKind,
+    scope: o.scope,
+    label: o.label,
+    authKind: o.authKind,
+    position: o.position,
+  };
+}
+
+function isMcpUrl(value: unknown): value is string {
+  if (!isBoundedString(value, MAX_MANIFEST_URL_CHARS)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.username === "" && url.password === "";
+  } catch {
+    return false;
+  }
+}
+
+function parseMcp(
+  value: unknown,
+  grant: { orgId: string; userId: string },
+  credentialSessions: ReadonlySet<string>,
+): LeaseManifestMcp | null {
+  const o = exactObject(value, [
+    "credentialId",
+    "slug",
+    "url",
+    "scope",
+    "authKind",
+    "revision",
+    "parameter",
+    "version",
+    "expiresAt",
+    "sessionId",
+  ]);
+  if (
+    !o ||
+    !isIdValue(o.credentialId) ||
+    !isBoundedString(o.slug, MAX_MANIFEST_SLUG_CHARS) ||
+    !/^[a-z0-9][a-z0-9-]*$/.test(o.slug) ||
+    !isMcpUrl(o.url) ||
+    !isScope(o.scope) ||
+    (o.authKind !== "oauth" && o.authKind !== "token" && o.authKind !== "none")
+  ) {
+    return null;
+  }
+  const authKind: LeaseManifestMcp["authKind"] = o.authKind;
+  const base = {
+    credentialId: o.credentialId,
+    slug: o.slug,
+    url: o.url,
+    scope: o.scope,
+    authKind,
+  };
+  if (authKind === "none") {
+    return o.revision === null &&
+      o.parameter === null &&
+      o.version === null &&
+      o.expiresAt === null &&
+      o.sessionId === null
+      ? {
+          ...base,
+          revision: null,
+          parameter: null,
+          version: null,
+          expiresAt: null,
+          sessionId: null,
+        }
+      : null;
+  }
+  if (
+    !isIdValue(o.revision) ||
+    typeof o.parameter !== "string" ||
+    !isPositiveInteger(o.version) ||
+    !(o.expiresAt === null || isEpochMs(o.expiresAt)) ||
+    typeof o.sessionId !== "string" ||
+    !credentialSessions.has(o.sessionId)
+  ) {
+    return null;
+  }
+  const location = parseLeaseParameterName(o.parameter);
+  if (
+    !location ||
+    location.class !== "mcp" ||
+    location.scope !== o.scope ||
+    location.credentialId !== o.credentialId ||
+    location.revision !== o.revision ||
+    !belongsTo(location, grant)
+  ) {
+    return null;
+  }
+  return {
+    ...base,
+    revision: o.revision,
+    parameter: o.parameter,
+    version: o.version,
+    expiresAt: o.expiresAt,
+    sessionId: o.sessionId,
+  };
+}
+
+function parseStatic(
+  value: unknown,
+  credentialClass: "github" | "ssh",
+  grant: { orgId: string; userId: string },
+  credentialSessions: ReadonlySet<string>,
+): LeaseManifestStatic | null {
+  const o = exactObject(value, [
+    "credentialId",
+    "revision",
+    "parameter",
+    "version",
+    "sessionId",
+  ]);
+  if (
+    !o ||
+    !isIdValue(o.credentialId) ||
+    !isIdValue(o.revision) ||
+    typeof o.parameter !== "string" ||
+    !isPositiveInteger(o.version) ||
+    typeof o.sessionId !== "string" ||
+    !credentialSessions.has(o.sessionId)
+  ) {
+    return null;
+  }
+  const location = parseLeaseParameterName(o.parameter);
+  if (
+    !location ||
+    location.class !== credentialClass ||
+    location.revision !== o.revision ||
+    location.ownerId !== grant.userId
+  ) {
+    return null;
+  }
+  return {
+    credentialId: o.credentialId,
+    revision: o.revision,
+    parameter: o.parameter,
+    version: o.version,
+    sessionId: o.sessionId,
+  };
+}
+
+function parseManifest(
+  value: unknown,
+  grant: { orgId: string; userId: string },
+  credentialSessions: ReadonlySet<string>,
+): CredentialManifest | null {
+  const o = exactObject(value, ["projects", "engines", "mcp", "github", "ssh"]);
+  if (
+    !o ||
+    !Array.isArray(o.projects) ||
+    o.projects.length > MAX_MANIFEST_PROJECTS ||
+    !Array.isArray(o.engines) ||
+    o.engines.length > MAX_MANIFEST_ENGINES ||
+    !Array.isArray(o.mcp) ||
+    o.mcp.length > MAX_MANIFEST_MCP
+  ) {
+    return null;
+  }
+  const projects: LeaseManifestProject[] = [];
+  for (const item of o.projects) {
+    const p = exactObject(item, ["projectId", "sessionId"]);
+    if (
+      !p ||
+      !isIdValue(p.projectId) ||
+      typeof p.sessionId !== "string" ||
+      !credentialSessions.has(p.sessionId)
+    ) {
+      return null;
+    }
+    projects.push({ projectId: p.projectId, sessionId: p.sessionId });
+  }
+  const engines: LeaseManifestEngine[] = [];
+  for (const item of o.engines) {
+    const engine = parseEngine(item, grant, credentialSessions);
+    if (!engine) return null;
+    engines.push(engine);
+  }
+  const mcp: LeaseManifestMcp[] = [];
+  for (const item of o.mcp) {
+    const connection = parseMcp(item, grant, credentialSessions);
+    if (!connection) return null;
+    mcp.push(connection);
+  }
+  const github =
+    o.github === null
+      ? null
+      : parseStatic(o.github, "github", grant, credentialSessions);
+  const ssh =
+    o.ssh === null ? null : parseStatic(o.ssh, "ssh", grant, credentialSessions);
+  if ((o.github !== null && !github) || (o.ssh !== null && !ssh)) return null;
+  if (
+    !uniqueBy(projects, (p) => p.projectId) ||
+    !uniqueBy(engines, (e) => e.credentialId) ||
+    !uniqueBy(mcp, (m) => m.credentialId) ||
+    !uniqueBy(mcp, (m) => m.slug)
+  ) {
+    return null;
+  }
+  return { projects, engines, mcp, github, ssh };
+}
+
+function parseFiles(value: unknown): LeaseFiles | null {
+  const o = exactObject(value, ["bucket", "orgPrefix", "userPrefix"]);
+  if (
+    !o ||
+    !isBoundedString(o.bucket, MAX_BUCKET_CHARS) ||
+    !(o.orgPrefix === null || isBoundedString(o.orgPrefix, MAX_PREFIX_CHARS)) ||
+    !isBoundedString(o.userPrefix, MAX_PREFIX_CHARS)
+  ) {
+    return null;
+  }
+  return { bucket: o.bucket, orgPrefix: o.orgPrefix, userPrefix: o.userPrefix };
+}
+
+/**
+ * The exact v1 grant, rebuilt field by field, or null. Beyond shapes it
+ * checks the grant is self-consistent: one to four `credentials` sessions
+ * and at most one `files` session, `files` present exactly with that
+ * session, unique session ids, every manifest entry read by a `credentials`
+ * session, and every parameter a lease-readable name owned by the grant's
+ * workspace or user.
+ */
+export function parseTaskLeaseV1(value: unknown): TaskLeaseV1 | null {
+  const o = exactObject(value, [
+    "v",
+    "leaseId",
+    "taskId",
+    "orgId",
+    "userId",
+    "runEpoch",
+    "manifestRevision",
+    "manifestDigest",
+    "region",
+    "sessions",
+    "files",
+    "manifest",
+  ]);
+  if (
+    !o ||
+    o.v !== 1 ||
+    !isOpId(o.leaseId) ||
+    !isIdValue(o.taskId) ||
+    !isIdValue(o.orgId) ||
+    !isIdValue(o.userId) ||
+    !isPositiveInteger(o.runEpoch) ||
+    !isPositiveInteger(o.manifestRevision) ||
+    typeof o.manifestDigest !== "string" ||
+    !DIGEST.test(o.manifestDigest) ||
+    !isBoundedString(o.region, MAX_REGION_CHARS) ||
+    !Array.isArray(o.sessions) ||
+    o.sessions.length === 0 ||
+    o.sessions.length > MAX_LEASE_SESSIONS
+  ) {
+    return null;
+  }
+  const sessions: LeaseSession[] = [];
+  for (const item of o.sessions) {
+    const session = parseSession(item);
+    if (!session) return null;
+    sessions.push(session);
+  }
+  const credentialSessions = new Set(
+    sessions.filter((s) => s.purpose === "credentials").map((s) => s.id),
+  );
+  const filesSessions = sessions.filter((s) => s.purpose === "files").length;
+  if (
+    !uniqueBy(sessions, (s) => s.id) ||
+    credentialSessions.size === 0 ||
+    credentialSessions.size > MAX_LEASE_CREDENTIAL_SESSIONS ||
+    filesSessions > 1 ||
+    (filesSessions === 1) !== (o.files !== null)
+  ) {
+    return null;
+  }
+  const files = o.files === null ? null : parseFiles(o.files);
+  if (o.files !== null && !files) return null;
+  const grant = { orgId: o.orgId, userId: o.userId };
+  const manifest = parseManifest(o.manifest, grant, credentialSessions);
+  if (!manifest) return null;
+  return {
+    v: 1,
+    leaseId: o.leaseId,
+    taskId: o.taskId,
+    orgId: o.orgId,
+    userId: o.userId,
+    runEpoch: o.runEpoch,
+    manifestRevision: o.manifestRevision,
+    manifestDigest: o.manifestDigest,
+    region: o.region,
+    sessions,
+    files,
+    manifest,
+  };
+}
+
+export function parseLeaseGrantV1Frame(value: unknown): LeaseGrantV1Frame | null {
+  const o = exactObject(value, ["kind", "opId", "lease"]);
+  if (!o || o.kind !== "lease.grant.v1" || !isOpId(o.opId)) return null;
+  const lease = parseTaskLeaseV1(o.lease);
+  return lease ? { kind: "lease.grant.v1", opId: o.opId, lease } : null;
+}
+
+export function parseLeaseRequestV1Frame(
+  value: unknown,
+): LeaseRequestV1Frame | null {
+  const o = exactObject(value, ["kind", "opId", "taskId", "runEpoch"]);
+  return o &&
+    o.kind === "lease.request" &&
+    isOpId(o.opId) &&
+    isIdValue(o.taskId) &&
+    isPositiveInteger(o.runEpoch)
+    ? {
+        kind: "lease.request",
+        opId: o.opId,
+        taskId: o.taskId,
+        runEpoch: o.runEpoch,
+      }
+    : null;
+}
+
+export function parseLeaseUnavailableFrame(
+  value: unknown,
+): LeaseUnavailableFrame | null {
+  const o = exactObject(value, ["kind", "opId", "error"]);
+  return o &&
+    o.kind === "lease.unavailable" &&
+    isOpId(o.opId) &&
+    isBoundedString(o.error, MAX_LEASE_ERROR_CHARS)
+    ? { kind: "lease.unavailable", opId: o.opId, error: o.error }
+    : null;
+}
+
+export function parseLeaseStaleFrame(value: unknown): LeaseStaleFrame | null {
+  const o = exactObject(value, [
+    "kind",
+    "taskId",
+    "runEpoch",
+    "wantedRevision",
+    "minRevision",
+    "removed",
+  ]);
+  if (
+    !o ||
+    o.kind !== "lease.stale" ||
+    !isIdValue(o.taskId) ||
+    !isPositiveInteger(o.runEpoch) ||
+    !isPositiveInteger(o.wantedRevision) ||
+    !(o.minRevision === null || isPositiveInteger(o.minRevision)) ||
+    !Array.isArray(o.removed) ||
+    o.removed.length > MAX_MANIFEST_ENGINES + MAX_MANIFEST_MCP + 2 ||
+    !o.removed.every(isIdValue) ||
+    new Set(o.removed).size !== o.removed.length
+  ) {
+    return null;
+  }
+  // Removing a credential is what makes older grants unusable, so the two
+  // travel together: `removed` without `minRevision` (or a floor above the
+  // revision the runner is told to want) is refused.
+  if (o.minRevision === null && o.removed.length > 0) return null;
+  if (o.minRevision !== null && o.minRevision > o.wantedRevision) return null;
+  return {
+    kind: "lease.stale",
+    taskId: o.taskId,
+    runEpoch: o.runEpoch,
+    wantedRevision: o.wantedRevision,
+    minRevision: o.minRevision,
+    removed: [...(o.removed as string[])],
+  };
+}
+
+export function parseCredentialChangedFrame(
+  value: unknown,
+): CredentialChangedFrame | null {
+  const o = exactObject(value, [
+    "kind",
+    "taskId",
+    "runEpoch",
+    "credentialId",
+    "revision",
+    "version",
+  ]);
+  return o &&
+    o.kind === "credential.changed" &&
+    isIdValue(o.taskId) &&
+    isPositiveInteger(o.runEpoch) &&
+    isIdValue(o.credentialId) &&
+    isIdValue(o.revision) &&
+    isPositiveInteger(o.version)
+    ? {
+        kind: "credential.changed",
+        taskId: o.taskId,
+        runEpoch: o.runEpoch,
+        credentialId: o.credentialId,
+        revision: o.revision,
+        version: o.version,
+      }
+    : null;
+}
+
+export function parseCredentialRefreshFrame(
+  value: unknown,
+): CredentialRefreshFrame | null {
+  const o = exactObject(value, [
+    "kind",
+    "opId",
+    "taskId",
+    "runEpoch",
+    "credentialId",
+    "revision",
+  ]);
+  return o &&
+    o.kind === "credential.refresh" &&
+    isOpId(o.opId) &&
+    isIdValue(o.taskId) &&
+    isPositiveInteger(o.runEpoch) &&
+    isIdValue(o.credentialId) &&
+    isIdValue(o.revision)
+    ? {
+        kind: "credential.refresh",
+        opId: o.opId,
+        taskId: o.taskId,
+        runEpoch: o.runEpoch,
+        credentialId: o.credentialId,
+        revision: o.revision,
+      }
+    : null;
+}
+
+const REFRESH_OUTCOMES: readonly CredentialRefreshOutcome[] = [
+  "refreshed",
+  "fresh",
+  "needs_sign_in",
+  "busy",
+  "unavailable",
+];
+
+export function parseCredentialRefreshResultFrame(
+  value: unknown,
+): CredentialRefreshResultFrame | null {
+  const o = exactObject(value, [
+    "kind",
+    "opId",
+    "outcome",
+    "version",
+    "expiresAt",
+  ]);
+  if (
+    !o ||
+    o.kind !== "credential.refresh.result" ||
+    !isOpId(o.opId) ||
+    !(REFRESH_OUTCOMES as readonly unknown[]).includes(o.outcome)
+  ) {
+    return null;
+  }
+  const outcome = o.outcome as CredentialRefreshOutcome;
+  const carriesVersion = outcome === "refreshed" || outcome === "fresh";
+  if (carriesVersion) {
+    if (
+      !isPositiveInteger(o.version) ||
+      !(o.expiresAt === null || isEpochMs(o.expiresAt))
+    ) {
+      return null;
+    }
+  } else if (o.version !== null || o.expiresAt !== null) {
+    return null;
+  }
+  return {
+    kind: "credential.refresh.result",
+    opId: o.opId,
+    outcome,
+    version: o.version as number | null,
+    expiresAt: o.expiresAt as number | null,
+  };
+}
+
+function isPhase(value: unknown): value is CredentialsActivationPhase {
+  return value === "prepare" || value === "commit";
+}
+
+export function parseCredentialsActivateFrame(
+  value: unknown,
+): CredentialsActivateFrame | null {
+  const o = exactObject(value, ["kind", "opId", "phase"]);
+  return o &&
+    o.kind === "credentials.activate" &&
+    isOpId(o.opId) &&
+    isPhase(o.phase)
+    ? { kind: "credentials.activate", opId: o.opId, phase: o.phase }
+    : null;
+}
+
+export function parseCredentialsActivateResultFrame(
+  value: unknown,
+): CredentialsActivateResultFrame | null {
+  const o = exactObject(value, ["kind", "opId", "phase", "ok", "error"]);
+  if (
+    !o ||
+    o.kind !== "credentials.activate.result" ||
+    !isOpId(o.opId) ||
+    !isPhase(o.phase) ||
+    typeof o.ok !== "boolean"
+  ) {
+    return null;
+  }
+  if (o.ok ? o.error !== null : !isBoundedString(o.error, MAX_LEASE_ERROR_CHARS)) {
+    return null;
+  }
+  return {
+    kind: "credentials.activate.result",
+    opId: o.opId,
+    phase: o.phase,
+    ok: o.ok,
+    error: o.error as string | null,
+  };
+}
+
+export function parseCredentialsActivatedFrame(
+  value: unknown,
+): CredentialsActivatedFrame | null {
+  const o = exactObject(value, ["kind", "opId"]);
+  return o && o.kind === "credentials.activated" && isOpId(o.opId)
+    ? { kind: "credentials.activated", opId: o.opId }
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// ADR-154 §7: the broker's exact-name entry point
+// ---------------------------------------------------------------------------
+
+const HOUR_MS = 60 * 60_000;
+
+/**
+ * When the cloud's scheduler names a lane's revision to the broker: this
+ * long before its access token's known expiry, or on this cadence when the
+ * expiry cannot be read. The broker's lanes keep the same numbers; the broker
+ * decides from the material itself and answers `fresh` when not due.
+ */
+export const CREDENTIAL_LANE_SCHEDULES: Readonly<
+  Record<string, { leadMs: number; everyMs?: number }>
+> = {
+  "openai-oauth": { leadMs: 48 * HOUR_MS },
+  "xai-oauth": { leadMs: 3 * HOUR_MS, everyMs: 4 * HOUR_MS },
+  // ADR-154 §11: MCP access tokens are often an hour long; one that names no
+  // expiry is refreshed on a cadence below that.
+  "mcp-oauth": { leadMs: 10 * 60_000, everyMs: 45 * 60_000 },
+};
+
+/** Cloud → broker: refresh exactly this revision of this credential. */
+export interface BrokerRevisionRequest {
+  v: 1;
+  credentialId: string;
+  revision: string;
+  brokerParameter: string;
+  leaseParameter: string;
+  /** A runner reported the credential invalid: refresh even if not due. */
+  force: boolean;
+  /**
+   * An adopted revision only (owner answer 3): today's parameter it was
+   * adopted from, which the broker keeps agreeing with the revision (the
+   * brokered copy, never the refresh token) for the runners still reading
+   * it, until the fleet audit. Never created when it is gone.
+   */
+  legacyParameter?: string;
+}
+
+/** Broker → cloud: the answer for that one credential, never material.
+ *  For an adopted revision (a request with `legacyParameter`), `legacy`
+ *  says whether today's parameter now agrees with it: `behind` when its
+ *  write did not land, which the cloud asks the broker to repair soon. */
+export type BrokerRevisionAnswer =
+  | { outcome: "refreshed" | "fresh"; version: number; expiresAt: number | null; legacy?: "synced" | "behind" }
+  | { outcome: "needs_sign_in" }
+  | { outcome: "busy" }
+  | { outcome: "unavailable"; error: string };
+
+/** The request, exactly, or null: both parameters must name the same
+ *  revision of the same credential, of a class the broker refreshes. */
+export function parseBrokerRevisionRequest(
+  value: unknown,
+  legacyPrefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): BrokerRevisionRequest | null {
+  const fields = ["v", "credentialId", "revision", "brokerParameter", "leaseParameter", "force"];
+  const o = exactObject(value, fields) ?? exactObject(value, [...fields, "legacyParameter"]);
+  if (
+    !o ||
+    o.v !== 1 ||
+    !isIdValue(o.credentialId) ||
+    !isIdValue(o.revision) ||
+    typeof o.brokerParameter !== "string" ||
+    typeof o.leaseParameter !== "string" ||
+    typeof o.force !== "boolean"
+  ) {
+    return null;
+  }
+  const broker = parseBrokerParameterName(o.brokerParameter);
+  const lease = parseLeaseParameterName(o.leaseParameter);
+  if (
+    !broker ||
+    !lease ||
+    !sameLocation(broker, lease) ||
+    (broker.class !== "engine" && broker.class !== "mcp") ||
+    broker.credentialId !== o.credentialId ||
+    broker.revision !== o.revision
+  ) {
+    return null;
+  }
+  if (o.legacyParameter !== undefined && !adoptedFrom(o.legacyParameter, broker, legacyPrefix)) return null;
+  return {
+    v: 1,
+    credentialId: o.credentialId,
+    revision: o.revision,
+    brokerParameter: o.brokerParameter,
+    leaseParameter: o.leaseParameter,
+    force: o.force,
+    ...(o.legacyParameter !== undefined ? { legacyParameter: o.legacyParameter as string } : {}),
+  };
+}
+
+/** The broker's answer, exactly, or null. */
+export function parseBrokerRevisionAnswer(value: unknown): BrokerRevisionAnswer | null {
+  const outcome = (value as { outcome?: unknown } | null)?.outcome;
+  if (outcome === "refreshed" || outcome === "fresh") {
+    const fields = ["outcome", "version", "expiresAt"];
+    const o = exactObject(value, fields) ?? exactObject(value, [...fields, "legacy"]);
+    if (
+      !o ||
+      !isPositiveInteger(o.version) ||
+      !(o.expiresAt === null || isEpochMs(o.expiresAt)) ||
+      !(o.legacy === undefined || o.legacy === "synced" || o.legacy === "behind")
+    ) {
+      return null;
+    }
+    return {
+      outcome,
+      version: o.version,
+      expiresAt: o.expiresAt,
+      ...(o.legacy !== undefined ? { legacy: o.legacy as "synced" | "behind" } : {}),
+    };
+  }
+  if (outcome === "needs_sign_in" || outcome === "busy") {
+    return exactObject(value, ["outcome"]) ? { outcome } : null;
+  }
+  if (outcome === "unavailable") {
+    const o = exactObject(value, ["outcome", "error"]);
+    return o && isBoundedString(o.error, MAX_LEASE_ERROR_CHARS)
+      ? { outcome, error: o.error }
+      : null;
+  }
+  return null;
+}
+
+/**
+ * What a broker answer may say about a failure: the error's kind (an AWS or
+ * Node error's name), never its message, which can quote a value a request
+ * carried.
+ */
+export function brokerErrorKind(error: unknown): string {
+  const name = error instanceof Error ? error.name : "";
+  return /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(name) ? name : "Error";
+}
+
+// ---------------------------------------------------------------------------
+// ADR-154, owner answer 3: Uai Cloud's workspace AI accounts adopted in place
+// ---------------------------------------------------------------------------
+
+/** ADR-134's default root. Installed Uai-operated tiers may configure a
+ *  different root; the cloud and broker must agree on the exact value. */
+export const DEFAULT_CREDENTIAL_STORE_PREFIX = "/uai";
+const CREDENTIAL_STORE_PREFIX = /^\/[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/;
+
+/** A credential-store root in the same form accepted by the host setting. */
+export function parseCredentialStorePrefix(value: unknown): string | null {
+  return typeof value === "string" && CREDENTIAL_STORE_PREFIX.test(value) ? value : null;
+}
+
+function credentialStoreRoot(prefix: string, suffix: string): string {
+  const parsed = parseCredentialStorePrefix(prefix);
+  if (!parsed) throw new Error("invalid credential-store prefix");
+  return `${parsed}/${suffix}`;
+}
+
+/** Today's layout (ADR-134) for workspace AI accounts. */
+export function legacyEngineParameterRoot(prefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX): string {
+  return credentialStoreRoot(prefix, "orgs");
+}
+
+/** Where the broker records adoption, with the legacy path below it. */
+export function legacyAdoptedRoot(prefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX): string {
+  return credentialStoreRoot(prefix, "adopted");
+}
+
+/** Default-root aliases retained for callers describing the standard layout. */
+export const LEGACY_ENGINE_PARAMETER_ROOT = legacyEngineParameterRoot();
+export const LEGACY_ADOPTED_ROOT = legacyAdoptedRoot();
+/** At most this many accounts in one listing page. */
+export const MAX_LEGACY_ACCOUNTS = 500;
+const MAX_LEGACY_LABEL_CHARS = 256;
+/** ADR-134's segment rule, as its ids are actually minted (no dots). */
+const LEGACY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+/** A parameter under today's layout the cloud adopts: a workspace AI
+ *  account. People's MCP connections wait for a fence against the v0 task
+ *  machines that refresh them themselves. */
+export type LegacyParameter = { kind: "engine"; orgId: string; engineKind: string; accountId: string };
+
+export type LegacyEngineParameter = Extract<LegacyParameter, { kind: "engine" }>;
+
+/** A parameter under today's layout the cloud adopts, or null. */
+export function parseLegacyParameterName(
+  name: unknown,
+  prefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): LegacyParameter | null {
+  const parsedPrefix = parseCredentialStorePrefix(prefix);
+  if (typeof name !== "string" || !parsedPrefix) return null;
+  const engineRoot = `${parsedPrefix}/orgs`;
+  if (name.startsWith(`${engineRoot}/`)) {
+    const parts = name.slice(engineRoot.length + 1).split("/");
+    if (parts.length !== 4 || parts[1] !== "engines") return null;
+    const [orgId, , engineKind, accountId] = parts as [string, string, string, string];
+    if (!LEGACY_SEGMENT.test(orgId) || !isEngineKind(engineKind) || !LEGACY_SEGMENT.test(accountId)) return null;
+    return { kind: "engine", orgId, engineKind, accountId };
+  }
+  return null;
+}
+
+/** A workspace AI account's parameter under today's layout, or null. */
+export function parseLegacyEngineParameterName(
+  name: unknown,
+  prefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): LegacyEngineParameter | null {
+  const legacy = parseLegacyParameterName(name, prefix);
+  return legacy?.kind === "engine" ? legacy : null;
+}
+
+/** The adoption marker for a legacy parameter: the same path under that
+ *  store's adopted root (`<prefix>/adopted/orgs/…`). */
+export function legacyAdoptionMarkerName(
+  legacyParameter: string,
+  prefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): string {
+  if (!parseLegacyParameterName(legacyParameter, prefix)) {
+    throw new Error("not a legacy parameter the cloud adopts");
+  }
+  return `${legacyAdoptedRoot(prefix)}${legacyParameter.slice(prefix.length)}`;
+}
+
+/** A parameter under today's layout may be adopted into (and be kept
+ *  agreeing with) exactly this credential's location: a workspace AI account
+ *  into that workspace's account of the same kind. */
+function adoptedFrom(
+  legacyParameter: unknown,
+  location: CredentialLocation,
+  prefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): boolean {
+  const legacy = parseLegacyParameterName(legacyParameter, prefix);
+  if (legacy?.kind === "engine") {
+    return (
+      location.class === "engine" &&
+      location.scope === "org" &&
+      location.ownerId === legacy.orgId &&
+      location.engineKind === legacy.engineKind
+    );
+  }
+  return false;
+}
+
+/** Cloud → broker: one page of today's workspace AI accounts, metadata
+ *  only, by parameter name, after `after` (null: from the first). */
+export interface BrokerLegacyListRequest {
+  v: 1;
+  op: "legacy.list";
+  after: string | null;
+}
+
+export interface BrokerLegacyAccount {
+  parameter: string;
+  orgId: string;
+  engineKind: string;
+  accountId: string;
+  label: string;
+  authKind: "env" | "config-dir";
+  position: number;
+  /** The lane that refreshes it; null for a key that does not rotate. */
+  lane: string | null;
+  /** The revision it was adopted into, once it was. */
+  adopted: { credentialId: string; revision: string } | null;
+  /** Why it cannot be adopted as it is (a fixed reason code), or null. */
+  unsupported: string | null;
+}
+
+export type BrokerLegacyListAnswer =
+  /** `next`: the name to list after for the following page, or null. */
+  | { outcome: "listed"; accounts: BrokerLegacyAccount[]; next: string | null }
+  | { outcome: "unavailable"; error: string };
+
+/** Cloud → broker: adopt one parameter under today's layout as this
+ *  revision, which the cloud has opened for it in `orgId` (and for `userId`,
+ *  a person's). */
+export interface BrokerAdoptRequest {
+  v: 1;
+  op: "legacy.adopt";
+  legacyParameter: string;
+  credentialId: string;
+  revision: string;
+  leaseParameter: string;
+  /** The broker-only part, exactly when the material rotates. */
+  brokerParameter: string | null;
+  orgId: string;
+  userId: string | null;
+}
+
+export type BrokerAdoptAnswer =
+  /** Both parts exist; `version` is the lease-readable part's. */
+  | { outcome: "adopted"; version: number; expiresAt: number | null }
+  /** Today's parameter is gone: there is nothing to adopt. */
+  | { outcome: "absent" }
+  /** It cannot be adopted as it is, ever (a fixed reason code). */
+  | { outcome: "unsupported"; reason: string }
+  | { outcome: "busy" }
+  | { outcome: "unavailable"; error: string };
+
+const isReasonCode = (value: unknown): value is string =>
+  typeof value === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(value);
+
+export function parseBrokerLegacyListRequest(
+  value: unknown,
+  legacyPrefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): BrokerLegacyListRequest | null {
+  const o = exactObject(value, ["v", "op", "after"]);
+  if (!o || o.v !== 1 || o.op !== "legacy.list") return null;
+  if (o.after !== null && !parseLegacyEngineParameterName(o.after, legacyPrefix)) return null;
+  return { v: 1, op: "legacy.list", after: o.after as string | null };
+}
+
+export function parseBrokerAdoptRequest(
+  value: unknown,
+  legacyPrefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): BrokerAdoptRequest | null {
+  const o = exactObject(value, [
+    "v",
+    "op",
+    "legacyParameter",
+    "credentialId",
+    "revision",
+    "leaseParameter",
+    "brokerParameter",
+    "orgId",
+    "userId",
+  ]);
+  if (
+    !o ||
+    o.v !== 1 ||
+    o.op !== "legacy.adopt" ||
+    typeof o.legacyParameter !== "string" ||
+    !isIdValue(o.credentialId) ||
+    !isIdValue(o.revision) ||
+    typeof o.leaseParameter !== "string" ||
+    (o.brokerParameter !== null && typeof o.brokerParameter !== "string") ||
+    !isIdValue(o.orgId) ||
+    (o.userId !== null && !isIdValue(o.userId))
+  ) {
+    return null;
+  }
+  const lease = parseLeaseParameterName(o.leaseParameter);
+  if (
+    !lease ||
+    !adoptedFrom(o.legacyParameter, lease, legacyPrefix) ||
+    lease.credentialId !== o.credentialId ||
+    lease.revision !== o.revision ||
+    // The flow's owners: a workspace's account is the workspace's alone; a
+    // person's connection is theirs, in a workspace.
+    (lease.scope === "org" ? o.userId !== null || o.orgId !== lease.ownerId : o.userId !== lease.ownerId)
+  ) {
+    return null;
+  }
+  if (o.brokerParameter !== null) {
+    const broker = parseBrokerParameterName(o.brokerParameter);
+    if (!broker || !sameLocation(broker, lease)) return null;
+  }
+  return {
+    v: 1,
+    op: "legacy.adopt",
+    legacyParameter: o.legacyParameter,
+    credentialId: o.credentialId,
+    revision: o.revision,
+    leaseParameter: o.leaseParameter,
+    brokerParameter: o.brokerParameter as string | null,
+    orgId: o.orgId,
+    userId: o.userId as string | null,
+  };
+}
+
+function parseLegacyAccount(
+  value: unknown,
+  legacyPrefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): BrokerLegacyAccount | null {
+  const o = exactObject(value, [
+    "parameter",
+    "orgId",
+    "engineKind",
+    "accountId",
+    "label",
+    "authKind",
+    "position",
+    "lane",
+    "adopted",
+    "unsupported",
+  ]);
+  const legacy = o ? parseLegacyEngineParameterName(o.parameter, legacyPrefix) : null;
+  if (
+    !o ||
+    !legacy ||
+    legacy.orgId !== o.orgId ||
+    legacy.engineKind !== o.engineKind ||
+    legacy.accountId !== o.accountId ||
+    !isBoundedString(o.label, MAX_LEGACY_LABEL_CHARS) ||
+    (o.authKind !== "env" && o.authKind !== "config-dir") ||
+    typeof o.position !== "number" ||
+    !Number.isSafeInteger(o.position) ||
+    (o.lane !== null && !isBoundedString(o.lane, 64)) ||
+    (o.unsupported !== null && !isReasonCode(o.unsupported))
+  ) {
+    return null;
+  }
+  let adopted: BrokerLegacyAccount["adopted"] = null;
+  if (o.adopted !== null) {
+    const a = exactObject(o.adopted, ["credentialId", "revision"]);
+    if (!a || !isIdValue(a.credentialId) || !isIdValue(a.revision)) return null;
+    adopted = { credentialId: a.credentialId, revision: a.revision };
+  }
+  return {
+    parameter: o.parameter as string,
+    orgId: legacy.orgId,
+    engineKind: legacy.engineKind,
+    accountId: legacy.accountId,
+    label: o.label,
+    authKind: o.authKind,
+    position: o.position,
+    lane: o.lane as string | null,
+    adopted,
+    unsupported: o.unsupported as string | null,
+  };
+}
+
+/** The broker's listing page, exactly, or null. */
+export function parseBrokerLegacyListAnswer(
+  value: unknown,
+  legacyPrefix: string = DEFAULT_CREDENTIAL_STORE_PREFIX,
+): BrokerLegacyListAnswer | null {
+  const outcome = (value as { outcome?: unknown } | null)?.outcome;
+  if (outcome === "listed") {
+    const o = exactObject(value, ["outcome", "accounts", "next"]);
+    if (!o || !Array.isArray(o.accounts) || o.accounts.length > MAX_LEGACY_ACCOUNTS) return null;
+    if (o.next !== null && !parseLegacyEngineParameterName(o.next, legacyPrefix)) return null;
+    const accounts: BrokerLegacyAccount[] = [];
+    for (const entry of o.accounts) {
+      const account = parseLegacyAccount(entry, legacyPrefix);
+      if (!account) return null;
+      accounts.push(account);
+    }
+    return { outcome, accounts, next: o.next as string | null };
+  }
+  if (outcome === "unavailable") {
+    const o = exactObject(value, ["outcome", "error"]);
+    return o && isBoundedString(o.error, MAX_LEASE_ERROR_CHARS) ? { outcome, error: o.error } : null;
+  }
+  return null;
+}
+
+/** The broker's answer to an adoption, exactly, or null. */
+export function parseBrokerAdoptAnswer(value: unknown): BrokerAdoptAnswer | null {
+  const outcome = (value as { outcome?: unknown } | null)?.outcome;
+  if (outcome === "adopted") {
+    const o = exactObject(value, ["outcome", "version", "expiresAt"]);
+    return o && isPositiveInteger(o.version) && (o.expiresAt === null || isEpochMs(o.expiresAt))
+      ? { outcome, version: o.version, expiresAt: o.expiresAt }
+      : null;
+  }
+  if (outcome === "absent" || outcome === "busy") {
+    return exactObject(value, ["outcome"]) ? { outcome } : null;
+  }
+  if (outcome === "unsupported") {
+    const o = exactObject(value, ["outcome", "reason"]);
+    return o && isReasonCode(o.reason) ? { outcome, reason: o.reason } : null;
+  }
+  if (outcome === "unavailable") {
+    const o = exactObject(value, ["outcome", "error"]);
+    return o && isBoundedString(o.error, MAX_LEASE_ERROR_CHARS) ? { outcome, error: o.error } : null;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// ADR-154 §11: an MCP connection's handshake on the sign-in box
+// ---------------------------------------------------------------------------
+
+/** Advertised by a sign-in box that runs MCP handshakes as capture flows. */
+export const SIGNIN_BOX_MCP_CAPTURE_FEATURE = "signin-box-mcp-capture-v1";
+
+const MAX_MCP_URL_CHARS = 2048;
+const MAX_MCP_STATE_CHARS = 512;
+const MAX_MCP_CODE_CHARS = 4096;
+const MAX_MCP_CLIENT_CHARS = 1024;
+const MAX_MCP_SCOPES = 64;
+
+/** Cloud → box: probe an MCP server for a connection being added. */
+export interface McpCaptureProbeFrame {
+  kind: "mcp.capture.probe";
+  opId: string;
+  flow: CaptureFlowWire;
+  url: string;
+  /** A static header the server takes, when the person gave one. */
+  header: { name: string; value: string } | null;
+  /** A client the person (or the catalog) brings, when the authorization
+   *  server cannot register one. */
+  clientId: string | null;
+  clientSecret: string | null;
+  redirectUri: string;
+  state: string;
+  /** The scopes to ask for (a catalog entry's); null asks for none and
+   *  takes the authorization server's default. Never its whole
+   *  `scopes_supported`, which is a capability list, not a need. */
+  scopes: string[] | null;
+}
+
+/** Cloud → box: the authorization server redirected back. */
+export interface McpCaptureCompleteFrame {
+  kind: "mcp.capture.complete";
+  opId: string;
+  flow: CaptureFlowWire;
+  code: string;
+  state: string;
+  /** RFC 9207: the issuer the redirect named, when it named one. */
+  iss: string | null;
+}
+
+/** Cloud → box: the cloud ended this sign-in (expired, cancelled): forget its
+ *  verifier and client secret now. No answer. */
+export interface McpCaptureCancelFrame {
+  kind: "mcp.capture.cancel";
+  opId: string;
+  flow: CaptureFlowWire;
+  state: string;
+}
+
+export type McpCaptureOutcome = "none" | "token" | "auth_required" | "connected" | "error";
+
+/** Box → cloud: what the handshake came to. `capture` is the revision it
+ *  wrote (`token`, `connected`); `authorizeUrl` where the person signs in
+ *  (`auth_required`); `error` why it failed. Never material. */
+export interface McpCaptureAckFrame {
+  kind: "mcp.capture.ack";
+  opId: string;
+  outcome: McpCaptureOutcome;
+  capture: CaptureResultWire | null;
+  authorizeUrl: string | null;
+  scopes: string[] | null;
+  error: string | null;
+}
+
+function isHttpsUrl(value: unknown): value is string {
+  if (!isBoundedString(value, MAX_MCP_URL_CHARS)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.username === "" && url.password === "" && url.hostname !== "";
+  } catch {
+    return false;
+  }
+}
+
+function isMcpFlow(value: unknown): value is CaptureFlowWire {
+  const flow = parseCaptureFlowWire(value);
+  return flow !== null && flow.location.class === "mcp";
+}
+
+function isOptionalClient(value: unknown): value is string | null {
+  return value === null || isBoundedString(value, MAX_MCP_CLIENT_CHARS);
+}
+
+/** RFC 6749 scope tokens: printable ASCII but space, `"` and `\\`. */
+const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]{1,128}$/;
+
+export function isScopeList(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= MAX_MCP_SCOPES &&
+    value.every((scope) => typeof scope === "string" && SCOPE_TOKEN.test(scope))
+  );
+}
+
+export function parseMcpCaptureProbeFrame(value: unknown): McpCaptureProbeFrame | null {
+  const o = exactObject(value, [
+    "kind",
+    "opId",
+    "flow",
+    "url",
+    "header",
+    "clientId",
+    "clientSecret",
+    "redirectUri",
+    "state",
+    "scopes",
+  ]);
+  if (
+    !o ||
+    o.kind !== "mcp.capture.probe" ||
+    !isOpId(o.opId) ||
+    !isMcpFlow(o.flow) ||
+    !isHttpsUrl(o.url) ||
+    !isOptionalClient(o.clientId) ||
+    !isOptionalClient(o.clientSecret) ||
+    !isHttpsUrl(o.redirectUri) ||
+    !isBoundedString(o.state, MAX_MCP_STATE_CHARS) ||
+    !(o.scopes === null || isScopeList(o.scopes))
+  ) {
+    return null;
+  }
+  let header: { name: string; value: string } | null = null;
+  if (o.header !== null) {
+    const h = exactObject(o.header, ["name", "value"]);
+    if (
+      !h ||
+      typeof h.name !== "string" ||
+      !HEADER_NAME.test(h.name) ||
+      FORBIDDEN_HEADER_NAMES.has(h.name.toLowerCase()) ||
+      !isBoundedString(h.value, 4096) ||
+      /[\r\n]/.test(h.value)
+    ) {
+      return null;
+    }
+    header = { name: h.name, value: h.value };
+  }
+  return {
+    kind: "mcp.capture.probe",
+    opId: o.opId,
+    flow: o.flow as CaptureFlowWire,
+    url: o.url,
+    header,
+    clientId: o.clientId,
+    clientSecret: o.clientSecret,
+    redirectUri: o.redirectUri,
+    state: o.state,
+    scopes: o.scopes === null ? null : [...(o.scopes as string[])],
+  };
+}
+
+export function parseMcpCaptureCompleteFrame(value: unknown): McpCaptureCompleteFrame | null {
+  const o = exactObject(value, ["kind", "opId", "flow", "code", "state", "iss"]);
+  return o &&
+    o.kind === "mcp.capture.complete" &&
+    isOpId(o.opId) &&
+    isMcpFlow(o.flow) &&
+    isBoundedString(o.code, MAX_MCP_CODE_CHARS) &&
+    isBoundedString(o.state, MAX_MCP_STATE_CHARS) &&
+    (o.iss === null || isBoundedString(o.iss, MAX_MCP_URL_CHARS))
+    ? {
+        kind: "mcp.capture.complete",
+        opId: o.opId,
+        flow: o.flow as CaptureFlowWire,
+        code: o.code,
+        state: o.state,
+        iss: o.iss,
+      }
+    : null;
+}
+
+export function parseMcpCaptureCancelFrame(value: unknown): McpCaptureCancelFrame | null {
+  const o = exactObject(value, ["kind", "opId", "flow", "state"]);
+  return o &&
+    o.kind === "mcp.capture.cancel" &&
+    isOpId(o.opId) &&
+    isMcpFlow(o.flow) &&
+    isBoundedString(o.state, MAX_MCP_STATE_CHARS)
+    ? { kind: "mcp.capture.cancel", opId: o.opId, flow: o.flow as CaptureFlowWire, state: o.state }
+    : null;
+}
+
+export function parseMcpCaptureAckFrame(value: unknown): McpCaptureAckFrame | null {
+  const o = exactObject(value, ["kind", "opId", "outcome", "capture", "authorizeUrl", "scopes", "error"]);
+  if (!o || o.kind !== "mcp.capture.ack" || !isOpId(o.opId)) return null;
+  const outcome = o.outcome;
+  const capture = o.capture === null ? null : parseCaptureResultWire(o.capture);
+  if (o.capture !== null && !capture) return null;
+  const scopes = o.scopes === null ? null : isScopeList(o.scopes) ? [...o.scopes] : undefined;
+  if (scopes === undefined) return null;
+  const base = { kind: "mcp.capture.ack" as const, opId: o.opId, scopes };
+  switch (outcome) {
+    case "none":
+      return capture === null && o.authorizeUrl === null && o.error === null
+        ? { ...base, outcome, capture: null, authorizeUrl: null, error: null }
+        : null;
+    case "token":
+    case "connected":
+      return capture !== null && o.authorizeUrl === null && o.error === null
+        ? { ...base, outcome, capture, authorizeUrl: null, error: null }
+        : null;
+    case "auth_required":
+      return capture === null && isHttpsUrl(o.authorizeUrl) && o.error === null
+        ? { ...base, outcome, capture: null, authorizeUrl: o.authorizeUrl, error: null }
+        : null;
+    case "error":
+      return capture === null && o.authorizeUrl === null && isBoundedString(o.error, MAX_LEASE_ERROR_CHARS)
+        ? { ...base, outcome, capture: null, authorizeUrl: null, error: o.error }
+        : null;
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GitHub sign-ins and SSH keys on the sign-in box (ADR-154 §12)
+// ---------------------------------------------------------------------------
+
+/** Advertised by a sign-in box that writes GitHub and SSH revisions, lists a
+ *  person's GitHub installations from the revision the cloud names, and
+ *  revokes a retired GitHub token. */
+export const SIGNIN_BOX_PERSON_CREDENTIALS_FEATURE = "signin-box-person-credentials-v1";
+
+const MAX_GITHUB_TOKEN_CHARS = 512;
+const MAX_GITHUB_CLIENT_ID_CHARS = 128;
+const MAX_GITHUB_CLIENT_SECRET_CHARS = 256;
+export const MAX_SSH_PUBLIC_KEY_CHARS = 1024;
+
+/** Cloud → box: write the GitHub user token the cloud's callback obtained as
+ *  this revision. This frame is the token's only trip past the cloud. */
+export interface GithubCaptureFrame {
+  kind: "github.capture";
+  opId: string;
+  flow: CaptureFlowWire;
+  token: string;
+}
+
+/** Cloud → box: mint an SSH key as this revision. The private half goes to
+ *  the revision's parameter and nowhere else. */
+export interface SshMintFrame {
+  kind: "ssh.mint";
+  opId: string;
+  flow: CaptureFlowWire;
+}
+
+/** Box → cloud: the revision written (with an SSH key's public half), or why
+ *  not. Never material. */
+export interface PersonCaptureAckFrame {
+  kind: "person.capture.ack";
+  opId: string;
+  capture: CaptureResultWire | null;
+  publicKey: string | null;
+  error: string | null;
+}
+
+/** Cloud → box: revoke a retired GitHub revision's token at GitHub. The App's
+ *  client id and secret ride the frame; the box keeps neither. */
+export interface GithubRevokeFrame {
+  kind: "github.revoke";
+  opId: string;
+  /** The retired revision's lease-readable parameter. */
+  parameter: string;
+  clientId: string;
+  clientSecret: string;
+}
+
+/** `revoked`: GitHub confirmed; `absent`: the token, or its parameter, is
+ *  gone already; `retry`: ask again later. */
+export type GithubRevokeOutcome = "revoked" | "absent" | "retry";
+
+export interface GithubRevokeAckFrame {
+  kind: "github.revoke.ack";
+  opId: string;
+  outcome: GithubRevokeOutcome;
+  error: string | null;
+}
+
+function isPersonFlow(value: unknown, credentialClass: "github" | "ssh"): value is CaptureFlowWire {
+  const flow = parseCaptureFlowWire(value);
+  return flow !== null && flow.location.class === credentialClass;
+}
+
+/** A GitHub token as the leased value holds it: bounded, one word. */
+export function isGithubToken(value: unknown): value is string {
+  return isBoundedString(value, MAX_GITHUB_TOKEN_CHARS) && !/\s/.test(value);
+}
+
+export function parseGithubCaptureFrame(value: unknown): GithubCaptureFrame | null {
+  const o = exactObject(value, ["kind", "opId", "flow", "token"]);
+  return o &&
+    o.kind === "github.capture" &&
+    isOpId(o.opId) &&
+    isPersonFlow(o.flow, "github") &&
+    isGithubToken(o.token)
+    ? { kind: "github.capture", opId: o.opId, flow: o.flow as CaptureFlowWire, token: o.token }
+    : null;
+}
+
+export function parseSshMintFrame(value: unknown): SshMintFrame | null {
+  const o = exactObject(value, ["kind", "opId", "flow"]);
+  return o && o.kind === "ssh.mint" && isOpId(o.opId) && isPersonFlow(o.flow, "ssh")
+    ? { kind: "ssh.mint", opId: o.opId, flow: o.flow as CaptureFlowWire }
+    : null;
+}
+
+export function parsePersonCaptureAckFrame(value: unknown): PersonCaptureAckFrame | null {
+  const o = exactObject(value, ["kind", "opId", "capture", "publicKey", "error"]);
+  if (!o || o.kind !== "person.capture.ack" || !isOpId(o.opId)) return null;
+  const capture = o.capture === null ? null : parseCaptureResultWire(o.capture);
+  if (o.capture !== null && !capture) return null;
+  if (!(o.publicKey === null || (isBoundedString(o.publicKey, MAX_SSH_PUBLIC_KEY_CHARS) && !/[\r\n]/.test(o.publicKey)))) {
+    return null;
+  }
+  if (capture !== null) {
+    return o.error === null
+      ? { kind: "person.capture.ack", opId: o.opId, capture, publicKey: o.publicKey, error: null }
+      : null;
+  }
+  return o.publicKey === null && isBoundedString(o.error, MAX_LEASE_ERROR_CHARS)
+    ? { kind: "person.capture.ack", opId: o.opId, capture: null, publicKey: null, error: o.error }
+    : null;
+}
+
+export function parseGithubRevokeFrame(value: unknown): GithubRevokeFrame | null {
+  const o = exactObject(value, ["kind", "opId", "parameter", "clientId", "clientSecret"]);
+  if (
+    !o ||
+    o.kind !== "github.revoke" ||
+    !isOpId(o.opId) ||
+    typeof o.parameter !== "string" ||
+    parseLeaseParameterName(o.parameter)?.class !== "github" ||
+    !isBoundedString(o.clientId, MAX_GITHUB_CLIENT_ID_CHARS) ||
+    !isBoundedString(o.clientSecret, MAX_GITHUB_CLIENT_SECRET_CHARS)
+  ) {
+    return null;
+  }
+  return {
+    kind: "github.revoke",
+    opId: o.opId,
+    parameter: o.parameter,
+    clientId: o.clientId,
+    clientSecret: o.clientSecret,
+  };
+}
+
+export function parseGithubRevokeAckFrame(value: unknown): GithubRevokeAckFrame | null {
+  const o = exactObject(value, ["kind", "opId", "outcome", "error"]);
+  if (!o || o.kind !== "github.revoke.ack" || !isOpId(o.opId)) return null;
+  if (o.outcome === "revoked" || o.outcome === "absent") {
+    return o.error === null ? { kind: "github.revoke.ack", opId: o.opId, outcome: o.outcome, error: null } : null;
+  }
+  return o.outcome === "retry" && isBoundedString(o.error, MAX_LEASE_ERROR_CHARS)
+    ? { kind: "github.revoke.ack", opId: o.opId, outcome: "retry", error: o.error }
+    : null;
+}
+
+/** A GitHub revision the cloud names for the repository picker: it must be
+ *  that person's own. */
+export function isPersonGithubParameter(parameter: unknown, userId: string): parameter is string {
+  if (typeof parameter !== "string") return false;
+  const location = parseLeaseParameterName(parameter);
+  return location !== null && location.class === "github" && location.ownerId === userId;
+}