@huynle/hub 0.6.0 → 0.7.1

package/packages/sdk/src/webhook.ts

@@ -0,0 +1,102 @@
+// Webhook verification for receivers (design §6.1; decision znbg8xa5 #8). The hub signs every webhook POST with
+//   Hub-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
+// (format: packages/protocol/src/webhook.ts). verifyWebhook checks it against the receiver's secret(s) in constant
+// time and refuses timestamps outside the tolerance (replay). Verify the raw body bytes as received, before parsing.
+import { createHmac, timingSafeEqual } from "node:crypto"
+
+// The format, as in packages/protocol/src/webhook.ts (the SDK imports nothing outside its package; the tests check
+// the two agree).
+export const WEBHOOK_SIGNATURE_HEADER = "Hub-Signature"
+export const WEBHOOK_EVENT_HEADER = "Hub-Event"
+export const WEBHOOK_DELIVERY_HEADER = "Hub-Delivery"
+/** Largest gap, either way, between a signature's timestamp and the receiver's clock. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300
+const SCHEME = "v1"
+const ALGORITHM = "sha256"
+const HEADER_MAX = 2048
+const HEX_SHA256 = /^[0-9a-f]{64}$/
+
+/** A Hub-Signature header's timestamp (unix seconds) and v1 signatures, or undefined when it is malformed. */
+function parseSignature(value: string): { t: number; v1: string[] } | undefined {
+  if (value.length > HEADER_MAX) return undefined
+  let t: number | undefined
+  const v1: string[] = []
+  for (const part of value.split(",")) {
+    const eq = part.indexOf("=")
+    if (eq < 0) return undefined
+    const key = part.slice(0, eq).trim()
+    const v = part.slice(eq + 1).trim()
+    if (key === "t") {
+      if (t !== undefined || !/^\d{1,12}$/.test(v)) return undefined
+      t = Number(v)
+    } else if (key === SCHEME) {
+      if (!HEX_SHA256.test(v)) return undefined
+      v1.push(v)
+    }
+  }
+  return t !== undefined && v1.length > 0 ? { t, v1 } : undefined
+}
+
+/** Request headers: a Headers, or a plain object such as node's IncomingMessage.headers (any key case). */
+export type WebhookHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>
+
+export interface VerifyWebhookInput {
+  /** The raw request body, exactly as received. */
+  readonly body: string | Uint8Array
+  /** The Hub-Signature header value (or give `headers`). */
+  readonly signature?: string | null
+  /** The request's headers: Hub-Signature, and Hub-Event / Hub-Delivery for the answer. */
+  readonly headers?: WebhookHeaders
+  /** The registration's secret; several while one rotates (any may match). */
+  readonly secret: string | readonly string[]
+  /** The receiver's clock in ms (default Date.now()). */
+  readonly now?: number
+  /** Seconds a timestamp may be off either way (default WEBHOOK_TOLERANCE_SECONDS). */
+  readonly tolerance?: number
+}
+
+export type WebhookVerification =
+  | { readonly ok: true; readonly timestamp: number; readonly event?: string; readonly delivery?: string }
+  | { readonly ok: false; readonly reason: "missing" | "malformed" | "stale" | "mismatch" }
+
+function header(headers: WebhookHeaders | undefined, name: string): string | undefined {
+  if (!headers) return undefined
+  if (typeof (headers as Headers).get === "function") return (headers as Headers).get(name) ?? undefined
+  const wanted = name.toLowerCase()
+  for (const [key, value] of Object.entries(headers as Record<string, string | readonly string[] | undefined>)) {
+    if (key.toLowerCase() !== wanted || value === undefined) continue
+    return typeof value === "string" ? value : value[0]
+  }
+  return undefined
+}
+
+const text = (body: string | Uint8Array) => (typeof body === "string" ? body : new TextDecoder().decode(body))
+
+const hmac = (secret: string, t: number, body: string): Buffer => createHmac(ALGORITHM, secret).update(`${t}.${body}`).digest()
+
+/** Whether a Hub-Signature matches the body under one of the secrets, and is fresh. */
+export function verifyWebhook(input: VerifyWebhookInput): WebhookVerification {
+  const raw = input.signature ?? header(input.headers, WEBHOOK_SIGNATURE_HEADER)
+  if (raw === undefined || raw === null || raw === "") return { ok: false, reason: "missing" }
+  const parsed = parseSignature(raw)
+  if (!parsed) return { ok: false, reason: "malformed" }
+  if (Math.abs((input.now ?? Date.now()) / 1000 - parsed.t) > (input.tolerance ?? WEBHOOK_TOLERANCE_SECONDS)) return { ok: false, reason: "stale" }
+  const body = text(input.body)
+  const secrets = (typeof input.secret === "string" ? [input.secret] : input.secret).filter((s) => s.length > 0)
+  const given = parsed.v1.map((hex) => Buffer.from(hex, "hex"))
+  // Every comparison runs (no early exit), each in constant time.
+  let match = false
+  for (const secret of secrets) {
+    const expected = hmac(secret, parsed.t, body)
+    for (const signature of given) if (signature.length === expected.length && timingSafeEqual(signature, expected)) match = true
+  }
+  if (!match) return { ok: false, reason: "mismatch" }
+  const event = header(input.headers, WEBHOOK_EVENT_HEADER)
+  const delivery = header(input.headers, WEBHOOK_DELIVERY_HEADER)
+  return { ok: true, timestamp: parsed.t, ...(event !== undefined ? { event } : {}), ...(delivery !== undefined ? { delivery } : {}) }
+}
+
+/** The Hub-Signature header the hub would send for `body` (for testing receivers); `t` in unix seconds, default now. */
+export function signWebhook(body: string | Uint8Array, secret: string, t: number = Math.floor(Date.now() / 1000)): string {
+  return `t=${t},${SCHEME}=${hmac(secret, t, text(body)).toString("hex")}`
+}

package/packages/spoke-sdk/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@huynle/hub-spoke-sdk",
+  "version": "0.7.1",
+  "private": true,
+  "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  }
+}

package/packages/spoke-sdk/src/activity.ts

@@ -0,0 +1,3 @@
+// Activity compaction (tool inputs cut to short summaries, no outputs) is part of the wire format and lives in the
+// protocol package; the spoke SDK re-exports it so a spoke needs one import.
+export { compactActivity, compactStatus, jobFromInfo, summarizeToolInput } from "../../protocol/src/index.ts"

package/packages/spoke-sdk/src/connection.ts

@@ -0,0 +1,295 @@
+// The spoke's single outbound WebSocket to the central server: hello/welcome handshake, request/
+// response correlation in both directions, and reconnect with jittered exponential backoff. A bye carrying
+// retryAfterMs (a hub pod draining, design §10) is followed by one short jittered reconnect (0–retryAfterMs) instead.
+import {
+  encode,
+  MAX_FRAME,
+  parseServerMessage,
+  PROTOCOL_VERSION,
+  type Hello,
+  type ResultFor,
+  type ServerRequest,
+  type SpokeMessage,
+  type SpokeRequest,
+  type Welcome,
+} from "../../protocol/src/index.ts"
+
+export type ConnectionState = "off" | "connecting" | "connected" | "revoked" | "error"
+
+export interface Backoff {
+  readonly minMs: number
+  readonly maxMs: number
+  readonly random?: () => number
+}
+
+/** Minimal WebSocket surface used here (Bun's WebSocket accepts `{ headers }` as a 2nd argument). */
+export interface SocketLike {
+  readonly readyState: number
+  onopen: ((ev: unknown) => void) | null
+  onmessage: ((ev: { data: unknown }) => void) | null
+  onclose: ((ev: { code?: number; reason?: string }) => void) | null
+  onerror: ((ev: unknown) => void) | null
+  send(data: string): void
+  close(code?: number, reason?: string): void
+}
+
+export interface ConnectionOptions {
+  readonly server: string
+  readonly token: string
+  /** Hello fields, computed per attempt so mode/directory are current. */
+  readonly hello: () => Omit<Hello, "t" | "v">
+  /** Executes a server request; a thrown error becomes `{ ok: false, error }`. */
+  readonly handle: (req: ServerRequest) => Promise<unknown>
+  readonly onWelcome?: (welcome: Welcome) => void
+  readonly onState?: (state: ConnectionState, error?: string) => void
+  readonly backoff?: Backoff
+  readonly requestTimeoutMs?: number
+  readonly socket?: (url: string, headers: Record<string, string>) => SocketLike
+}
+
+export function backoffDelay(attempt: number, backoff: Backoff): number {
+  const base = Math.min(backoff.maxMs, backoff.minMs * 2 ** Math.min(attempt, 30))
+  const random = (backoff.random ?? Math.random)()
+  return Math.round(base * (0.5 + 0.5 * random))
+}
+
+/** The reconnect delay a bye's retryAfterMs asks for: uniformly jittered over 0–retryAfterMs, so peers spread out. */
+export function retryAfterDelay(retryAfterMs: number, random: () => number = Math.random): number {
+  return Math.round(retryAfterMs * random())
+}
+
+export function wsURL(server: string): string {
+  return `${server.replace(/\/+$/, "").replace(/^http/, "ws")}/spoke/ws`
+}
+
+const defaultSocket = (url: string, headers: Record<string, string>): SocketLike =>
+  new (WebSocket as unknown as new (url: string, options: { headers: Record<string, string> }) => SocketLike)(url, { headers })
+
+const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+
+interface Pending {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export class SpokeConnection {
+  state: ConnectionState = "off"
+  lastError?: string
+  publicURL?: string
+  machineID?: string
+
+  private socket?: SocketLike
+  private welcomed = false
+  /** Features the hub listed in its welcome on the current socket (none before a welcome or from an old hub). */
+  private hubFeatures: ReadonlySet<string> = new Set()
+  private stopped = true
+  private attempt = 0
+  private retry?: ReturnType<typeof setTimeout>
+  /** The last bye's retryAfterMs (a draining hub): the next reconnect waits about this instead of the backoff. */
+  private retryAfterMs?: number
+  private nextID = 0
+  private readonly pending = new Map<string, Pending>()
+  private readonly backoff: Backoff
+
+  constructor(private readonly options: ConnectionOptions) {
+    this.backoff = options.backoff ?? { minMs: 1000, maxMs: 60_000 }
+  }
+
+  start(): void {
+    if (!this.stopped) return
+    this.stopped = false
+    this.open()
+  }
+
+  stop(): void {
+    this.stopped = true
+    clearTimeout(this.retry)
+    this.drop(1000, "stop")
+    this.failPending("disconnected")
+    this.setState("off")
+  }
+
+  /** Whether the connected hub announced `feature`; send a request a newer hub added only when it did. */
+  hubSupports(feature: string): boolean {
+    return this.hubFeatures.has(feature)
+  }
+
+  /** Reconnects at once (e.g. after a local hub was started) instead of waiting out the backoff. */
+  retryNow(): void {
+    if (this.stopped || this.state === "connected" || this.state === "revoked" || this.socket) return
+    clearTimeout(this.retry)
+    this.attempt = 0
+    this.open()
+  }
+
+  /** Sends a frame once the server has welcomed us. Returns false when it could not be sent. */
+  send(frame: SpokeMessage): boolean {
+    if (!this.socket || !this.welcomed || this.socket.readyState !== 1) return false
+    try {
+      let text = encode(frame)
+      if (text.length > MAX_FRAME) {
+        // The hub drops the connection on an oversize frame; answer a request with an error instead.
+        if (frame.t !== "res") return false
+        text = encode({ t: "res", id: frame.id, ok: false, error: `Result too large to send (${text.length} characters, limit ${MAX_FRAME})` })
+      }
+      this.socket.send(text)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  request<R extends SpokeRequest>(req: R): Promise<ResultFor[R["op"]]> {
+    const id = `s${++this.nextID}`
+    return new Promise((resolve, reject) => {
+      if (this.state !== "connected") return reject(new Error("Not connected to the hub"))
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error("The hub timed out"))
+      }, this.options.requestTimeoutMs ?? 15_000)
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer })
+      if (!this.send({ t: "req", id, req })) {
+        clearTimeout(timer)
+        this.pending.delete(id)
+        reject(new Error("Not connected to the hub"))
+      }
+    })
+  }
+
+  private open(): void {
+    if (this.stopped) return
+    this.setState(this.state === "error" ? "error" : "connecting")
+    let socket: SocketLike
+    try {
+      socket = (this.options.socket ?? defaultSocket)(wsURL(this.options.server), {
+        Authorization: `Bearer ${this.options.token}`,
+      })
+    } catch (cause) {
+      this.fail(message(cause))
+      return
+    }
+    this.socket = socket
+    this.welcomed = false
+    socket.onopen = () => {
+      try {
+        socket.send(encode({ t: "hello", v: PROTOCOL_VERSION, ...this.options.hello() }))
+      } catch (cause) {
+        this.lastError = message(cause)
+      }
+    }
+    socket.onmessage = (ev) => this.receive(ev.data)
+    socket.onerror = () => {
+      this.lastError = this.welcomed ? "Connection error" : "Could not connect to the hub"
+    }
+    socket.onclose = (ev) => {
+      if (this.socket !== socket) return
+      this.socket = undefined
+      const wasWelcomed = this.welcomed
+      this.welcomed = false
+      this.hubFeatures = new Set()
+      this.failPending("disconnected")
+      if (this.stopped || this.state === "revoked") return
+      this.fail(wasWelcomed ? `Connection closed${ev.reason ? `: ${ev.reason}` : ""}` : (this.lastError ?? "Could not connect"))
+    }
+  }
+
+  private receive(data: unknown): void {
+    const text = typeof data === "string" ? data : data instanceof ArrayBuffer ? Buffer.from(data).toString("utf8") : String(data)
+    const frame = parseServerMessage(text)
+    if (!frame) return
+    switch (frame.t) {
+      case "welcome":
+        this.welcomed = true
+        this.hubFeatures = new Set(frame.features ?? [])
+        this.attempt = 0
+        this.publicURL = frame.publicURL
+        this.machineID = frame.machineID
+        this.lastError = undefined
+        this.setState("connected")
+        try {
+          this.options.onWelcome?.(frame)
+        } catch (cause) {
+          console.error("[hub] welcome handler failed", cause)
+        }
+        return
+      case "bye":
+        if (frame.reason === "revoked") {
+          this.stopped = true
+          clearTimeout(this.retry)
+          this.lastError = "This machine was revoked on the hub"
+          this.setState("revoked")
+          this.drop(1000, "revoked")
+          this.failPending("revoked")
+        } else if (frame.retryAfterMs !== undefined) {
+          this.retryAfterMs = frame.retryAfterMs
+        }
+        return
+      case "res": {
+        const pending = this.pending.get(frame.id)
+        if (!pending) return
+        this.pending.delete(frame.id)
+        clearTimeout(pending.timer)
+        if (frame.ok) pending.resolve(frame.result)
+        else pending.reject(new Error(frame.error ?? "Request failed"))
+        return
+      }
+      case "req":
+        void this.answer(frame.id, frame.req)
+        return
+    }
+  }
+
+  private async answer(id: string, req: ServerRequest): Promise<void> {
+    let reply: SpokeMessage
+    try {
+      reply = { t: "res", id, ok: true, result: await this.options.handle(req) }
+    } catch (cause) {
+      reply = { t: "res", id, ok: false, error: message(cause) }
+    }
+    this.send(reply)
+  }
+
+  private fail(error: string): void {
+    this.lastError = error
+    this.setState("error")
+    if (this.stopped) return
+    clearTimeout(this.retry)
+    const retryAfterMs = this.retryAfterMs
+    this.retryAfterMs = undefined
+    const delay = retryAfterMs !== undefined ? retryAfterDelay(retryAfterMs, this.backoff.random) : backoffDelay(this.attempt++, this.backoff)
+    this.retry = setTimeout(() => this.open(), delay)
+  }
+
+  private drop(code: number, reason: string): void {
+    const socket = this.socket
+    this.socket = undefined
+    this.welcomed = false
+    this.hubFeatures = new Set()
+    if (!socket) return
+    socket.onopen = socket.onmessage = socket.onerror = socket.onclose = null
+    try {
+      socket.close(code, reason)
+    } catch {
+      // already closed
+    }
+  }
+
+  private failPending(reason: string): void {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer)
+      pending.reject(new Error(`Hub ${reason}`))
+      this.pending.delete(id)
+    }
+  }
+
+  private setState(state: ConnectionState): void {
+    if (state === this.state) return
+    this.state = state
+    try {
+      this.options.onState?.(state, this.lastError)
+    } catch {
+      // observers must not break the connection
+    }
+  }
+}

package/packages/spoke-sdk/src/delivery.ts

@@ -0,0 +1,119 @@
+// Harness-neutral delivery helpers (the deliver op): the provenance envelope an agent's prompt (kind "prompt") is
+// rendered in, who put each inbox item into a session, and applying each hub message once (DeliveryLedger: the hub
+// retries a deliver with the same messageID; a harness may not deduplicate it, so the spoke must).
+import { sanitizeLabel, sanitizeText } from "../../sdk/src/envelope.ts"
+import type { DeliverMeta, DeliverResult, InboxOrigin } from "../../protocol/src/index.ts"
+import { PROMPT_SOURCE } from "./prompt-source.ts"
+
+/** Body lines that could pass for a header or boundary (or an escaped one): escaped with a leading backslash. */
+const FORGEABLE = /^\s*\\*(?:\[hub\]|-{3,}|↩)/i
+
+/**
+ * The text a session sees for an agent's prompt (kind "prompt"): a provenance header naming the sender and the
+ * grant, then the sanitised body between two boundaries (the same shape as the hub's message envelope, so
+ * timelines read the body back). The header comes from the hub's meta, never from the body.
+ */
+export function renderPromptEnvelope(input: { readonly messageID: string; readonly from: string; readonly grant: string; readonly text: string }): string {
+  const id = sanitizeLabel(input.messageID)
+  const boundary = `----- ${id} -----`
+  const body = sanitizeText(input.text)
+    .split("\n")
+    .map((line) => (FORGEABLE.test(line) ? `\\${line}` : line))
+    .join("\n")
+  return [`[hub] prompt from ${sanitizeLabel(input.from)} · grant ${sanitizeLabel(input.grant)} · ${id}`, boundary, body, boundary].join("\n")
+}
+
+/** What OpenCode gets for a deliver: a prompt wrapped in its provenance envelope, other kinds as the hub rendered them. */
+export function deliverText(req: { readonly messageID: string; readonly text: string; readonly meta: DeliverMeta }): string {
+  if (req.meta.kind !== "prompt") return req.text
+  return renderPromptEnvelope({ messageID: req.messageID, from: req.meta.from, grant: req.meta.grant ?? "", text: req.text })
+}
+
+const record = (v: unknown): Record<string, any> => (typeof v === "object" && v !== null ? (v as Record<string, any>) : {})
+
+/** A bounded insertion-ordered map: the oldest entry goes when it is full. */
+class Bounded<V> {
+  private readonly map = new Map<string, V>()
+  constructor(private readonly max: number) {}
+  get(key: string): V | undefined {
+    return this.map.get(key)
+  }
+  set(key: string, value: V): void {
+    this.map.delete(key)
+    this.map.set(key, value)
+    if (this.map.size > this.max) this.map.delete(this.map.keys().next().value!)
+  }
+  delete(key: string): void {
+    this.map.delete(key)
+  }
+}
+
+/**
+ * Who put each inbox item into a session, from OpenCode's session.inbox.enqueued events and the spoke's own
+ * deliveries: a user item is the user's (typed, or sent from the phone), a synthetic item with hub metadata is
+ * the hub's; anything else (OpenCode's own notes, compaction) has no origin.
+ */
+export class InboxOrigins {
+  private readonly origins: Bounded<InboxOrigin>
+  constructor(max = 1000) {
+    this.origins = new Bounded(max)
+  }
+
+  observe(event: { readonly type: string; readonly data?: unknown }): void {
+    if (event.type !== "session.inbox.enqueued") return
+    const data = record(event.data)
+    if (typeof data.inboxID !== "string" || this.origins.get(data.inboxID) === "hub") return
+    const item = record(data.item)
+    const metadata = record(record(item.payload).metadata)
+    // A hub message (hub metadata with its messageID) is never the user's, whatever item type OpenCode gives it.
+    if (metadata.source === PROMPT_SOURCE && typeof metadata.messageID === "string" && (item.type === "synthetic" || item.type === "user")) this.origins.set(data.inboxID, "hub")
+    else if (item.type === "user") this.origins.set(data.inboxID, "user")
+  }
+
+  /** Marks an inbox item the spoke delivered for the hub. */
+  hub(inboxID: string): void {
+    this.origins.set(inboxID, "hub")
+  }
+
+  /** The item's origin, when known; forgets it (an item is delivered once). */
+  take(inboxID: string): InboxOrigin | undefined {
+    const origin = this.origins.get(inboxID)
+    this.origins.delete(inboxID)
+    return origin
+  }
+}
+
+export interface Admission {
+  readonly result: DeliverResult
+  /** Whether it was sent with resume (could start a turn). */
+  readonly resumed: boolean
+}
+
+/**
+ * Applies each hub message once: a duplicate messageID (the hub's retry, in flight or done) gets the first
+ * result without another admission. Only a retry that asks to wake a message first admitted without waking is
+ * sent again (OpenCode keeps one message for the id and wakes the session). Failures are not remembered.
+ */
+export class DeliveryLedger {
+  private readonly entries: Bounded<Promise<Admission>>
+  constructor(max = 1000) {
+    this.entries = new Bounded(max)
+  }
+
+  async run(messageID: string, wake: boolean, send: () => Promise<Admission>): Promise<DeliverResult> {
+    const known = this.entries.get(messageID)
+    if (known) {
+      const admission = await known.catch(() => undefined)
+      if (admission && (!wake || admission.resumed)) return admission.result
+      if (this.entries.get(messageID) !== known) return this.run(messageID, wake, send)
+    }
+    const attempt = send()
+    this.entries.set(messageID, attempt)
+    try {
+      return (await attempt).result
+    } catch (cause) {
+      if (this.entries.get(messageID) === attempt) this.entries.delete(messageID)
+      throw cause
+    }
+  }
+}

package/packages/spoke-sdk/src/enroll.ts

@@ -0,0 +1,79 @@
+// Device-code enrollment of this machine with the central server (before it has a token).
+// POST /spoke/enroll → EnrollStart; then POST /spoke/enroll/poll until the user approves it.
+import type { EnrollPoll, EnrollStart } from "../../protocol/src/index.ts"
+
+export type EnrollOutcome =
+  | { readonly status: "approved"; readonly machineID: string; readonly machineToken: string }
+  | { readonly status: "denied" | "expired" | "cancelled" }
+
+export interface EnrollOptions {
+  readonly signal?: AbortSignal
+  readonly fetch?: typeof fetch
+  readonly now?: () => number
+}
+
+const REQUEST_TIMEOUT_MS = 15_000
+
+async function post(server: string, path: string, body: unknown, options: EnrollOptions): Promise<unknown> {
+  const doFetch = options.fetch ?? fetch
+  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(options.signal ? [options.signal] : [])]
+  const response = await doFetch(`${server.replace(/\/+$/, "")}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.any(signals),
+  })
+  if (!response.ok) throw new Error(`${path} failed: HTTP ${response.status}`)
+  return response.json()
+}
+
+function isStart(v: any): v is EnrollStart {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof v.userCode === "string" &&
+    typeof v.deviceCode === "string" &&
+    typeof v.approveURL === "string" &&
+    typeof v.intervalMs === "number" &&
+    typeof v.expiresAt === "number"
+  )
+}
+
+export async function startEnrollment(server: string, machineName: string, options: EnrollOptions = {}): Promise<EnrollStart> {
+  const body = await post(server, "/spoke/enroll", { machineName }, options)
+  if (!isStart(body)) throw new Error("Invalid enrollment reply from the hub")
+  return body
+}
+
+const sleep = (ms: number, signal?: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", done)
+      resolve()
+    }
+    signal?.addEventListener("abort", done, { once: true })
+  })
+
+/** Polls until approved, denied, expired, or aborted. Transient errors are retried until expiry. */
+export async function pollEnrollment(server: string, start: EnrollStart, options: EnrollOptions = {}): Promise<EnrollOutcome> {
+  const now = options.now ?? Date.now
+  const interval = Math.max(1, start.intervalMs)
+  for (;;) {
+    if (options.signal?.aborted) return { status: "cancelled" }
+    if (now() > start.expiresAt) return { status: "expired" }
+    await sleep(interval, options.signal)
+    if (options.signal?.aborted) return { status: "cancelled" }
+    let reply: Partial<EnrollPoll> & Record<string, unknown>
+    try {
+      reply = (await post(server, "/spoke/enroll/poll", { deviceCode: start.deviceCode }, options)) as typeof reply
+    } catch {
+      continue
+    }
+    if (reply?.status === "approved" && typeof reply.machineID === "string" && typeof reply.machineToken === "string") {
+      return { status: "approved", machineID: reply.machineID, machineToken: reply.machineToken }
+    }
+    if (reply?.status === "denied" || reply?.status === "expired") return { status: reply.status }
+  }
+}