@huynle/hub 0.6.1 → 0.7.2

package/src/central/mcp-http.ts

@@ -0,0 +1,116 @@
+// POST /mcp: the hub's MCP tools over MCP Streamable HTTP, for MCP clients and gateways (Brain decision txznll2f).
+// Stateless: one JSON-RPC message per POST, answered as application/json (no SSE stream, no Mcp-Session-Id);
+// notifications and client responses get 202. Batches are refused (-32600, as in protocol 2025-06-18).
+//
+// Auth: `Authorization: Bearer <token>`, any credential the agent API accepts (app, device, session and act
+// tokens), checked up front with the agent API's resolver: none or invalid → 401 with `WWW-Authenticate: Bearer
+// realm="hub"` (no OAuth resource metadata, so gateways detect plain bearer auth). The tools are `hub mcp`'s
+// (packages/cli/src/mcp.ts) and call /api/agent with the caller's bearer, dispatched in process: scopes, grants,
+// tenancy, kill switches and the audit are exactly the HTTP API's. A browser Origin other than the hub's own is
+// refused (DNS rebinding); requests without one (servers, gateways) are fine. Tokens are never echoed.
+import { createMcpServer, MCP_PROTOCOL_VERSIONS, NOT_FROM_USER, RPC, rpcError, type RpcResponse } from "../../packages/cli/src/mcp"
+import { readCredentials } from "./agent/actor"
+
+export const MCP_PATH = "/mcp"
+
+/** Largest request body (bytes). */
+export const MCP_MAX_BODY_BYTES = 1 << 20
+
+export const MCP_INSTRUCTIONS =
+  "Hub: see and steer your AI agent sessions. Tools read sessions (status, sessions, show, log, who), message them (msg, ask, reply, decline, inbox), act within your grants (approve, deny, answer, prompt, stop) and launch sessions (launch, launches, launch_show, launch_stop), as this bearer token. " +
+  NOT_FROM_USER
+
+export interface McpHttpDeps {
+  /** The hub's public URL (the tools' base URL; requests never leave the process). */
+  publicURL(): string
+  /** Whether a request's Origin is the hub's own. */
+  isOwnOrigin(origin: string): boolean
+  /** Whether the agent API accepts this bearer token. */
+  verify(token: string): Promise<boolean>
+  /** The hub's own request handler (the tools' /api/agent calls). */
+  dispatch(request: Request): Promise<Response>
+  readonly version: string
+  readonly maxBodyBytes?: number
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+
+const failure = (status: number, code: string, message: string, headers: Record<string, string> = {}) =>
+  Response.json({ error: { code, message } }, { status, headers: { ...NO_STORE, ...headers } })
+
+const unauthorized = (message: string) => failure(401, "unauthorized", message, { "www-authenticate": 'Bearer realm="hub"' })
+
+const answer = (response: RpcResponse) =>
+  // A message the server could not take (parse error, not a request, a batch) carries no id: HTTP 400.
+  Response.json(response, { status: response.error && response.id === null ? 400 : 200, headers: NO_STORE })
+
+/** The body as text, or undefined when it is over `max` bytes (read no further). */
+async function readCapped(request: Request, max: number): Promise<string | undefined> {
+  const length = Number(request.headers.get("content-length") ?? "")
+  if (Number.isFinite(length) && length > max) return undefined
+  if (!request.body) return ""
+  const reader = request.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) {
+      void reader.cancel().catch(() => {})
+      return undefined
+    }
+    chunks.push(value)
+  }
+  return new TextDecoder().decode(Buffer.concat(chunks))
+}
+
+const acceptsJSON = (accept: string | null) => {
+  if (accept === null || !accept.trim()) return true
+  return accept.split(",").some((part) => {
+    const type = part.split(";")[0]!.trim().toLowerCase()
+    return type === "application/json" || type === "*/*" || type === "application/*"
+  })
+}
+
+/** Answers a request to /mcp (any method). */
+export function mcpHttp(deps: McpHttpDeps): (request: Request) => Promise<Response> {
+  const max = deps.maxBodyBytes ?? MCP_MAX_BODY_BYTES
+  return async (request) => {
+    if (request.method !== "POST") return failure(405, "method_not_allowed", "POST JSON-RPC messages to /mcp (no SSE stream, no sessions)", { allow: "POST" })
+    const origin = request.headers.get("origin")
+    if (origin !== null && !deps.isOwnOrigin(origin)) return failure(403, "forbidden", "Cross-origin request refused")
+    // The bearer only: a cookie never authenticates /mcp.
+    const token = readCredentials(request, "").bearer
+    if (token === undefined) return unauthorized("Send Authorization: Bearer <hub token>")
+    if (!token || !(await deps.verify(token))) return unauthorized("Invalid, expired or revoked token")
+    const version = request.headers.get("mcp-protocol-version")
+    if (version !== null && !MCP_PROTOCOL_VERSIONS.includes(version)) return failure(400, "invalid", `Unsupported MCP-Protocol-Version (supported: ${MCP_PROTOCOL_VERSIONS.join(", ")})`)
+    const type = (request.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase()
+    if (type !== "application/json") return failure(415, "invalid", "Content-Type must be application/json")
+    if (!acceptsJSON(request.headers.get("accept"))) return failure(406, "invalid", "Accept must allow application/json")
+    const text = await readCapped(request, max)
+    if (text === undefined) return failure(413, "invalid", `Request body over ${max} bytes`)
+    let message: unknown
+    try {
+      message = JSON.parse(text)
+    } catch {
+      return answer(rpcError(null, RPC.parse, "parse error: not JSON"))
+    }
+    const server = createMcpServer({
+      credentials: () => ({ url: deps.publicURL(), token, source: "http", fetch: (input, init) => deps.dispatch(new Request(input, init)) }),
+      version: deps.version,
+      instructions: MCP_INSTRUCTIONS,
+    })
+    // The client went away: its tool calls are aborted.
+    const close = () => server.close()
+    request.signal.addEventListener("abort", close, { once: true })
+    try {
+      const response = await server.handle(message)
+      return response ? answer(response) : new Response(null, { status: 202, headers: NO_STORE })
+    } finally {
+      request.signal.removeEventListener("abort", close)
+      server.close()
+    }
+  }
+}

package/src/central/nodes.ts

@@ -0,0 +1,314 @@
+// NodeRegistry: the hub's view of connected `hub node` daemons (design §6.3), one entry per node connection.
+// Kept apart from the spoke Registry on purpose: a node is never a process, never in the catalog and never makes
+// its machine "online"; it only reports runtimes, labels, capacity and launch progress. Placement (P4-T5) reads
+// list(ownerID); the launch engine (P4-T8) subscribes to progress and connect/disconnect events.
+// Cluster mode (design §9): each pod is the single writer of its own nodes and exports them per owner (clusterSlice);
+// ./cluster/view.ts applies other pods' slices (setRemote), so list/get/forMachine see every node of the cluster (a
+// node on another pod is reached through SpokeHub.requestNode). Events and count() stay local, except for
+// subscribers asking for remote events (the launch supervisor on the leader pod): they also get connected,
+// capacity, progress and disconnected derived from other pods' slice changes. A local node of a machine wins over a
+// remote one.
+import type { NodeCapacity, NodeCapacityFrame, NodeHello, NodeLaunchPhase, NodeLaunchReport, NodeProgress, NodeRuntimeInfo } from "../protocol"
+
+export interface NodeMachine {
+  readonly id: string
+  readonly name: string
+}
+
+/** A connected node, as seen by placement and the launch engine (a copy; changing it changes nothing). */
+export interface NodeView {
+  readonly connID: string
+  readonly machineID: string
+  readonly machineName: string
+  /** The machine's current owner, read live (ownership can move). */
+  readonly ownerID: string | undefined
+  readonly instanceID: string
+  readonly nodeVersion: string
+  readonly features: readonly string[]
+  readonly runtimes: readonly NodeRuntimeInfo[]
+  readonly labels: Readonly<Record<string, string>>
+  readonly capacity: NodeCapacity
+  readonly used: NodeCapacity
+  /** capacity − used, never below zero; memoryMB only when the node reports both. */
+  readonly free: NodeCapacity
+  readonly workspaceRoots: readonly string[]
+  readonly draining: boolean
+  /** Launches the node carries, with their latest phase (cleaned and cancelled ones are dropped). */
+  readonly launches: readonly NodeLaunchReport[]
+  readonly connectedAt: number
+  readonly lastSeen: number
+}
+
+export type NodeEvent =
+  | { readonly type: "connected"; readonly node: NodeView }
+  | { readonly type: "capacity"; readonly node: NodeView }
+  | { readonly type: "progress"; readonly node: NodeView; readonly launchID: string; readonly phase: NodeLaunchPhase; readonly message?: string }
+  | { readonly type: "disconnected"; readonly node: NodeView }
+
+export type NodeListener = (event: NodeEvent) => void
+
+/** One owner's nodes on one pod, as other pods mirror them (JSON-compatible). */
+export interface NodeSlice {
+  readonly nodes: NodeView[]
+}
+
+/** Phases after which the node no longer carries the launch. */
+const GONE: ReadonlySet<NodeLaunchPhase> = new Set(["cleaned", "cancelled"])
+
+interface Entry {
+  readonly connID: string
+  readonly machine: NodeMachine
+  readonly hello: NodeHello
+  labels: Record<string, string>
+  capacity: NodeCapacity
+  used: NodeCapacity
+  draining: boolean
+  readonly launches: Map<string, NodeLaunchReport>
+  readonly connectedAt: number
+  lastSeen: number
+}
+
+export class NodeRegistry {
+  private readonly entries = new Map<string, Entry>()
+  private readonly listeners = new Set<NodeListener>()
+  /** Listeners that also get events derived from other pods' slices (the launch supervisor on the leader pod). */
+  private readonly remoteListeners = new Set<NodeListener>()
+  private readonly localChangeListeners = new Set<(owner: string | undefined) => void>()
+  /** Other pods' nodes: pod → owner → slice. */
+  private readonly remote = new Map<string, Map<string, NodeSlice>>()
+
+  constructor(
+    private readonly ownerOf: (machineID: string) => string | undefined,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  connect(connID: string, machine: NodeMachine, hello: NodeHello): NodeView {
+    const at = this.now()
+    const entry: Entry = {
+      connID,
+      machine: { id: machine.id, name: machine.name },
+      hello,
+      labels: { ...hello.labels },
+      capacity: { ...hello.capacity },
+      used: { ...hello.used },
+      draining: hello.draining,
+      launches: new Map(hello.launches.map((l) => [l.launchID, { ...l }])),
+      connectedAt: at,
+      lastSeen: at,
+    }
+    this.entries.set(connID, entry)
+    const node = this.view(entry)
+    this.emit({ type: "connected", node })
+    return node
+  }
+
+  setCapacity(connID: string, frame: NodeCapacityFrame): void {
+    const entry = this.entries.get(connID)
+    if (!entry) return
+    entry.capacity = { ...frame.capacity }
+    entry.used = { ...frame.used }
+    entry.draining = frame.draining
+    if (frame.labels) entry.labels = { ...frame.labels }
+    this.emit({ type: "capacity", node: this.view(entry) })
+  }
+
+  progress(connID: string, frame: NodeProgress): void {
+    const entry = this.entries.get(connID)
+    if (!entry) return
+    if (GONE.has(frame.phase)) entry.launches.delete(frame.launchID)
+    else {
+      const previous = entry.launches.get(frame.launchID)
+      entry.launches.set(frame.launchID, { ...previous, launchID: frame.launchID, phase: frame.phase })
+    }
+    this.emit({
+      type: "progress",
+      node: this.view(entry),
+      launchID: frame.launchID,
+      phase: frame.phase,
+      ...(frame.message !== undefined ? { message: frame.message } : {}),
+    })
+  }
+
+  touch(connID: string): void {
+    const entry = this.entries.get(connID)
+    if (entry) entry.lastSeen = this.now()
+  }
+
+  disconnect(connID: string): void {
+    const entry = this.entries.get(connID)
+    if (!entry) return
+    this.entries.delete(connID)
+    this.emit({ type: "disconnected", node: this.view(entry) })
+  }
+
+  get(connID: string): NodeView | undefined {
+    const entry = this.entries.get(connID)
+    return entry ? this.view(entry) : this.remoteNodes().find((node) => node.connID === connID)
+  }
+
+  /** The node connection of a machine (at most one: the hub turns away a second one); this pod's first. */
+  forMachine(machineID: string): NodeView | undefined {
+    return this.localForMachine(machineID) ?? this.remoteNodes().find((node) => node.machineID === machineID)
+  }
+
+  /** The node connection of a machine held by this pod. */
+  localForMachine(machineID: string): NodeView | undefined {
+    for (const entry of this.entries.values()) if (entry.machine.id === machineID) return this.view(entry)
+    return undefined
+  }
+
+  /** Connected nodes of `ownerID` (all owned nodes when omitted); a node whose machine has no owner is never listed. */
+  list(ownerID?: string): NodeView[] {
+    const out: NodeView[] = []
+    for (const node of [...[...this.entries.values()].map((entry) => this.view(entry)), ...this.remoteNodes()]) {
+      if (node.ownerID !== undefined && (ownerID === undefined || node.ownerID === ownerID)) out.push(node)
+    }
+    return out
+  }
+
+  // ---------- cluster (design §9) ----------
+
+  /** Listens for changes to this pod's nodes of an owner. */
+  onLocalChange(listener: (owner: string | undefined) => void): () => void {
+    this.localChangeListeners.add(listener)
+    return () => this.localChangeListeners.delete(listener)
+  }
+
+  /** Owners of this pod's nodes. */
+  clusterTenants(): string[] {
+    const owners = new Set<string>()
+    for (const entry of this.entries.values()) {
+      const owner = this.ownerOf(entry.machine.id)
+      if (owner !== undefined) owners.add(owner)
+    }
+    return [...owners]
+  }
+
+  /** This pod's nodes of an owner for other pods (undefined when none). */
+  clusterSlice(owner: string): NodeSlice | undefined {
+    const nodes = [...this.entries.values()].map((entry) => this.view(entry)).filter((node) => node.ownerID === owner)
+    return nodes.length ? { nodes } : undefined
+  }
+
+  /** Applies another pod's nodes of an owner (undefined: it has none any more). */
+  setRemote(pod: string, owner: string, slice: NodeSlice | undefined): void {
+    let slices = this.remote.get(pod)
+    const before = slices?.get(owner)?.nodes ?? []
+    if (slice) {
+      if (!slices) this.remote.set(pod, (slices = new Map()))
+      slices.set(owner, slice)
+    } else if (slices?.delete(owner) && !slices.size) this.remote.delete(pod)
+    if (this.remoteListeners.size) this.emitRemote(before, slice?.nodes ?? [])
+  }
+
+  /**
+   * Events for remote listeners from a change of another pod's slice: nodes connecting and leaving, capacity, and
+   * per launch its new phase, or (gone from the slice) cancelled while preparing, else cleaned.
+   */
+  private emitRemote(before: readonly NodeView[], after: readonly NodeView[]): void {
+    const view = (node: NodeView): NodeView => ({ ...structuredClone(node), ownerID: this.ownerOf(node.machineID) })
+    const old = new Map(before.map((node) => [node.connID, node]))
+    const events: NodeEvent[] = []
+    for (const node of after) {
+      const previous = old.get(node.connID)
+      old.delete(node.connID)
+      if (!previous) {
+        events.push({ type: "connected", node: view(node) })
+        continue
+      }
+      const capacity = (n: NodeView) => JSON.stringify([n.capacity, n.used, n.draining, n.labels])
+      if (capacity(previous) !== capacity(node)) events.push({ type: "capacity", node: view(node) })
+      const phases = new Map(previous.launches.map((l) => [l.launchID, l.phase]))
+      const current = new Set(node.launches.map((l) => l.launchID))
+      // Released launches first, then the new phases.
+      for (const [launchID, phase] of phases) {
+        if (!current.has(launchID)) events.push({ type: "progress", node: view(node), launchID, phase: phase === "preparing" ? "cancelled" : "cleaned" })
+      }
+      for (const launch of node.launches) {
+        if (phases.get(launch.launchID) !== launch.phase) events.push({ type: "progress", node: view(node), launchID: launch.launchID, phase: launch.phase })
+      }
+    }
+    for (const node of old.values()) events.push({ type: "disconnected", node: view(node) })
+    for (const event of events) this.notify(this.remoteListeners, event)
+  }
+
+  /** Other pods' nodes (owner read live), one per machine (the newest), none for a machine with a local node. */
+  private remoteNodes(): NodeView[] {
+    if (!this.remote.size) return []
+    const local = new Set([...this.entries.values()].map((entry) => entry.machine.id))
+    const byMachine = new Map<string, NodeView>()
+    for (const slices of this.remote.values()) {
+      for (const slice of slices.values()) {
+        for (const node of slice.nodes ?? []) {
+          if (local.has(node.machineID) || this.entries.has(node.connID)) continue
+          const known = byMachine.get(node.machineID)
+          if (!known || node.connectedAt > known.connectedAt) byMachine.set(node.machineID, node)
+        }
+      }
+    }
+    return [...byMachine.values()].map((node) => ({ ...structuredClone(node), ownerID: this.ownerOf(node.machineID) }))
+  }
+
+  /** Connected node connections (for /healthz). */
+  count(): number {
+    return this.entries.size
+  }
+
+  /** Events of this pod's nodes; with `remote`, also of other pods' nodes (derived from their slices). */
+  subscribe(listener: NodeListener, options: { readonly remote?: boolean } = {}): () => void {
+    this.listeners.add(listener)
+    if (options.remote) this.remoteListeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+      this.remoteListeners.delete(listener)
+    }
+  }
+
+  private emit(event: NodeEvent): void {
+    for (const listener of [...this.localChangeListeners]) {
+      try {
+        listener(event.node.ownerID)
+      } catch (cause) {
+        console.error("[hub] node change listener failed:", cause instanceof Error ? cause.message : cause)
+      }
+    }
+    this.notify(this.listeners, event)
+  }
+
+  private notify(listeners: ReadonlySet<NodeListener>, event: NodeEvent): void {
+    for (const listener of [...listeners]) {
+      try {
+        listener(event)
+      } catch (cause) {
+        console.error("[hub] node listener failed:", cause instanceof Error ? cause.message : cause)
+      }
+    }
+  }
+
+  private view(entry: Entry): NodeView {
+    const { hello, capacity, used } = entry
+    const free: NodeCapacity = {
+      slots: Math.max(0, capacity.slots - used.slots),
+      ...(capacity.memoryMB !== undefined && used.memoryMB !== undefined ? { memoryMB: Math.max(0, capacity.memoryMB - used.memoryMB) } : {}),
+    }
+    return {
+      connID: entry.connID,
+      machineID: entry.machine.id,
+      machineName: entry.machine.name,
+      ownerID: this.ownerOf(entry.machine.id),
+      instanceID: hello.instanceID,
+      nodeVersion: hello.nodeVersion,
+      features: [...(hello.features ?? [])],
+      runtimes: hello.runtimes.map((r) => structuredClone(r)),
+      labels: { ...entry.labels },
+      capacity: { ...capacity },
+      used: { ...used },
+      free,
+      workspaceRoots: [...hello.workspaceRoots],
+      draining: entry.draining,
+      launches: [...entry.launches.values()].map((l) => ({ ...l })),
+      connectedAt: entry.connectedAt,
+      lastSeen: entry.lastSeen,
+    }
+  }
+}

package/src/central/oidc.ts

@@ -1,8 +1,12 @@
 // OpenID Connect sign-in (authorization code flow with PKCE S256, state and nonce) for multi-user hubs.
 // The ID token comes straight from the token endpoint over TLS (confidential client, client_secret_post),
-// so its signature is not checked (OIDC Core 3.1.3.7, item 6); its claims are. Pending sign-ins live in
-// memory only (a restart invalidates them) and are single use.
+// so its signature is not checked (OIDC Core 3.1.3.7, item 6); its claims are. Pending sign-ins live in the Kv
+// backend (process memory by default, so a restart invalidates them; Valkey in a cluster, so the callback may land
+// on any pod) and are single use (GETDEL).
 import { createHash, randomBytes } from "node:crypto"
+import { MemoryCounters } from "./backend/memory-counters"
+import { MemoryKv } from "./backend/memory-kv"
+import type { Counters, Kv } from "./backend/types"
 import type { OidcConfig } from "./config"
 
 export const OIDC_COOKIE = "voice_oidc"
@@ -11,8 +15,10 @@ export const OIDC_PENDING_TTL_MS = 10 * 60_000
 export const DISCOVERY_CACHE_MS = 60 * 60_000
 /** Clock skew tolerated on `exp`. */
 const SKEW_SECONDS = 60
-/** Most pending sign-ins kept (the oldest are dropped): /auth/login is public. */
-const MAX_PENDING = 1000
+/** Most sign-ins started per pending lifetime (every pod together); /auth/login is public. */
+const MAX_PENDING = 10_000
+const PENDING_KEY = (state: string) => `oidc:pending:${state}`
+const STARTED_KEY = "oidc:started"
 const FETCH_TIMEOUT_MS = 10_000
 const MAX_NEXT_CHARS = 1024
 
@@ -56,6 +62,10 @@ export interface OidcClientOptions {
   readonly publicURL: string
   readonly fetch?: typeof globalThis.fetch
   readonly now?: () => number
+  /** Pending sign-ins (default: in this process, on `now`). */
+  readonly kv?: Kv
+  /** The cap on sign-ins started (default: in this process, on `now`). */
+  readonly counters?: Counters
 }
 
 const random = () => randomBytes(32).toString("base64url")
@@ -129,7 +139,8 @@ export class OidcClient {
   private readonly config: OidcConfig
   private readonly fetch: typeof globalThis.fetch
   private readonly now: () => number
-  private readonly pending = new Map<string, Pending>()
+  private readonly kv: Kv
+  private readonly counters: Counters
   private discovery?: { at: number; doc: Discovery }
   readonly redirectURI: string
 
@@ -137,18 +148,22 @@ export class OidcClient {
     this.config = options.config
     this.fetch = options.fetch ?? globalThis.fetch
     this.now = options.now ?? Date.now
+    this.kv = options.kv ?? new MemoryKv({ now: this.now })
+    this.counters = options.counters ?? new MemoryCounters({ now: this.now })
     this.redirectURI = `${options.publicURL}/auth/callback`
   }
 
   /** Starts a sign-in: the provider URL to redirect to and the state for the voice_oidc cookie. */
   async login(next: string | null): Promise<{ location: string; state: string }> {
     const doc = await this.discover()
-    this.sweep()
+    if ((await this.counters.incr(STARTED_KEY, OIDC_PENDING_TTL_MS)) > MAX_PENDING) {
+      throw new OidcError(429, "Too many sign-ins are in progress. Please try again in a few minutes.", "too many pending sign-ins")
+    }
     const state = random()
     const nonce = random()
     const verifier = random()
-    while (this.pending.size >= MAX_PENDING) this.pending.delete(this.pending.keys().next().value!)
-    this.pending.set(state, { nonce, verifier, next: safeNext(next), expiresAt: this.now() + OIDC_PENDING_TTL_MS })
+    const pending: Pending = { nonce, verifier, next: safeNext(next), expiresAt: this.now() + OIDC_PENDING_TTL_MS }
+    await this.kv.set(PENDING_KEY(state), JSON.stringify(pending), { px: OIDC_PENDING_TTL_MS })
     const url = new URL(doc.authorization_endpoint)
     url.searchParams.set("response_type", "code")
     url.searchParams.set("client_id", this.config.clientId)
@@ -166,13 +181,11 @@ export class OidcClient {
    * pending entry is consumed whatever the outcome once the state matches the cookie.
    */
   async callback(params: URLSearchParams, cookieState: string | undefined): Promise<{ identity: OidcIdentity; next: string }> {
-    this.sweep()
     const state = params.get("state") ?? ""
-    const pending = state && cookieState === state ? this.pending.get(state) : undefined
+    const pending = state && cookieState === state ? await this.consume(state) : undefined
     if (!pending) {
       throw new OidcError(400, "This sign-in has expired or was already used. Please sign in again.", "state invalid")
     }
-    this.pending.delete(state)
     const providerError = params.get("error")
     if (providerError) {
       const description = params.get("error_description")
@@ -270,9 +283,16 @@ export class OidcClient {
     }
   }
 
-  private sweep(): void {
-    const t = this.now()
-    for (const [state, entry] of this.pending) if (entry.expiresAt <= t) this.pending.delete(state)
+  /** Takes a pending sign-in out of the Kv (GETDEL: one callback wins, on any pod); undefined when unknown or expired. */
+  private async consume(state: string): Promise<Pending | undefined> {
+    const raw = await this.kv.getdel(PENDING_KEY(state))
+    if (raw === undefined) return undefined
+    try {
+      const pending = JSON.parse(raw) as Pending
+      return pending.expiresAt > this.now() ? pending : undefined
+    } catch {
+      return undefined
+    }
   }
 }