@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/src/bootstrap/enrollment/enroll.ts

@@ -0,0 +1,226 @@
+// `machine enroll`: the canonical device-code enrollment of this machine. It needs no harness. It reuses the spoke
+// SDK's flow (POST /spoke/enroll, then /spoke/enroll/poll until the user approves on the hub) and stores the one
+// machine identity every spoke and `hub node` here share (ConfigCredentialStore, the spoke's config.json).
+//
+// Policy:
+// - The hub URL is https (plain http only for a loopback hub); redirects are refused, never followed.
+// - The approval link shown is on the hub's own origin (approvalURL).
+// - The wait is bounded by the hub's expiry and by maxWaitMs; `signal` cancels it.
+// - The hub hands out the credential once: the store is checked before the code is redeemed, an approving poll in
+//   flight is never aborted, a failed save is retried, and when it still fails the credential stays in memory
+//   only (retryPersist) and the output names the machine ID so the user can revoke it. It is never written
+//   anywhere else and never printed.
+// - v1.1: the outcomes have their own codes: enrollment_denied (exit 5), enrollment_expired and cancelled (exit 4),
+//   the same exits as before.
+import { hostname } from "node:os"
+import type { EnrollStart } from "../../../../protocol/src/index.ts"
+import { EnrollmentRefused, pollEnrollment, startEnrollment } from "../../../../spoke-sdk/src/enroll.ts"
+import type { CredentialStore, MachineCredential, MachineEnrollment } from "../contracts/index.ts"
+import { approvalURL, checkServerURL, isUserCode } from "./policy.ts"
+import { failure, line, success, type MachineResult } from "./result.ts"
+import { CredentialStoreError, type SharingMode, type StoreContents } from "./store.ts"
+import { probeCredential, statusOf, storeFailure } from "./status.ts"
+
+/** The longest a single enrollment waits for approval, whatever the hub says (the hub's own expiry is 10 minutes). */
+export const ENROLL_MAX_WAIT_MS = 15 * 60_000
+const MIN_INTERVAL_MS = 500
+const MAX_INTERVAL_MS = 30_000
+const PERSIST_ATTEMPTS = 3
+const PERSIST_DELAY_MS = 250
+const MACHINE_NAME = /^[A-Za-z0-9._ -]{1,64}$/
+const COMMAND = "machine enroll"
+
+/** What to show the user while waiting: the code to confirm and where to approve it. Never a credential. */
+export interface EnrollPrompt {
+  readonly userCode: string
+  readonly approveURL: string
+  readonly expiresAt: number
+  /** A local hub approved this first machine by itself. */
+  readonly autoApproved: boolean
+  /** Set when the hub's own approval link was not used. */
+  readonly warning?: string
+}
+
+export type EnrollStore = CredentialStore & { preflight?(): Promise<void>; inspect?(): StoreContents; sharingMode?(): SharingMode; enableSharing?(): boolean }
+
+/** Why an enrolled machine's OpenCode spoke stays disconnected: the user's explicit `mode: "off"`. */
+export function sharingOffWarning(location: string): string {
+  return `sharing is off for this machine (mode is "off" in ${location}), so the OpenCode spoke will not connect; turn it on with /hub → Mode in OpenCode, or set "mode" to "always"`
+}
+
+/**
+ * The sharing notes of an enrolled machine. With `repair`, a config with no `mode` at all (written by an older
+ * hubctl) gets the default; an explicit mode is never changed. Best effort: a store that cannot say adds nothing.
+ */
+function sharingNotes(store: EnrollStore, repair: boolean): string[] {
+  try {
+    if (repair && store.enableSharing?.()) return [`turned sharing on for this machine (mode "always" in ${store.location}), so the OpenCode spoke connects`]
+    return store.sharingMode?.() === "off" ? [sharingOffWarning(store.location)] : []
+  } catch {
+    return []
+  }
+}
+
+export interface MachineEnrollOptions {
+  readonly server: string
+  /** Default: defaultMachineName(hostname()). */
+  readonly machineName?: string
+  readonly store: EnrollStore
+  /** Replace an existing machine identity (otherwise enrolling twice is a no-op, and another hub is refused). */
+  readonly reenroll?: boolean
+  /** Check the new credential with the hub afterwards (default true). */
+  readonly verify?: boolean
+  readonly signal?: AbortSignal
+  readonly fetch?: typeof fetch
+  readonly now?: () => number
+  readonly onPrompt?: (prompt: EnrollPrompt) => void
+  readonly maxWaitMs?: number
+  /** Floor of the poll interval the hub asks for (default 500 ms). */
+  readonly minIntervalMs?: number
+  readonly persistAttempts?: number
+  readonly persistDelayMs?: number
+  readonly probeTimeoutMs?: number
+  /** The device-code flow (default: the spoke SDK's, with redirects refused and redeem-safe polling). */
+  readonly enrollment?: MachineEnrollment
+}
+
+export interface MachineEnrollResult extends MachineResult {
+  /**
+   * Only when the hub approved the machine but its credential could not be saved: saves it again (no new code is
+   * redeemed). The credential lives in this closure only; it is not part of the result's data.
+   */
+  readonly retryPersist?: () => Promise<MachineEnrollResult>
+}
+
+/** A machine name the hub and the status contract accept, from a hostname. */
+export function defaultMachineName(host: string): string {
+  const name = host
+    .replace(/\.local$/i, "")
+    .replace(/[^A-Za-z0-9._ -]/g, "-")
+    .trim()
+    .slice(0, 64)
+  return name || "machine"
+}
+
+/** The spoke SDK's device-code flow under the enrollment policy. */
+export function deviceCodeEnrollment(options: { fetch?: typeof fetch; now?: () => number } = {}): MachineEnrollment {
+  const base = { ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.now ? { now: options.now } : {}), redirect: "error" as const }
+  return {
+    start: (server, machineName, signal) => startEnrollment(server, machineName, { ...base, ...(signal ? { signal } : {}) }),
+    poll: (server, start, signal) => pollEnrollment(server, start, { ...base, ...(signal ? { signal } : {}), keepRedeemed: true }),
+  }
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+const errnoOf = (cause: unknown) => (cause instanceof CredentialStoreError ? cause.errno : (cause as NodeJS.ErrnoException | undefined)?.code)
+
+function validStart(value: EnrollStart): boolean {
+  return isUserCode(value.userCode) && Number.isFinite(value.expiresAt) && Number.isFinite(value.intervalMs)
+}
+
+export async function machineEnroll(options: MachineEnrollOptions): Promise<MachineEnrollResult> {
+  const now = options.now ?? Date.now
+  const { store, signal } = options
+  const server = checkServerURL(options.server)
+  if (!server) {
+    return failure(COMMAND, "usage", `The hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${line(String(options.server), 200)}`)
+  }
+  const machineName = options.machineName ?? defaultMachineName(hostname())
+  if (!MACHINE_NAME.test(machineName)) return failure(COMMAND, "usage", "The machine name must be 1–64 letters, digits, spaces, dots, dashes or underscores")
+  const cancelled = () => failure(COMMAND, "cancelled", "Enrollment cancelled; nothing was stored", { hint: "Run hubctl machine enroll again" })
+  if (signal?.aborted) return cancelled()
+
+  let existing: MachineCredential | undefined
+  try {
+    existing = await store.read()
+  } catch (cause) {
+    return storeFailure(COMMAND, cause, store.location)
+  }
+  if (existing && !options.reenroll) {
+    if (checkServerURL(existing.server) !== server) {
+      return failure(COMMAND, "needs_user", `This machine is already enrolled with ${line(existing.server, 200)} as ${existing.machineID}`, {
+        hint: `Pass --reenroll to replace its identity with a new one from ${server}`,
+      })
+    }
+    const probe = options.verify === false ? undefined : await probeCredential(existing, probeOptions(options))
+    const status = statusOf(existing, probe?.reachable ? probe : undefined, now())
+    if (status.state === "revoked") return failure(COMMAND, "revoked", "The hub rejected this machine's stored credential", { data: status, hint: "Pass --reenroll to enroll it again" })
+    return success(COMMAND, status, [`already enrolled as ${existing.machineID}; pass --reenroll to replace this machine's identity`, ...sharingNotes(store, true)])
+  }
+
+  try {
+    await store.preflight?.()
+  } catch (cause) {
+    return storeFailure(COMMAND, cause, store.location)
+  }
+
+  const flow = options.enrollment ?? deviceCodeEnrollment({ ...(options.fetch ? { fetch: options.fetch } : {}), now })
+  let start: EnrollStart
+  try {
+    start = await flow.start(server, machineName, signal)
+  } catch (cause) {
+    if (signal?.aborted) return cancelled()
+    if (cause instanceof EnrollmentRefused) return failure(COMMAND, "internal", `${server} redirected the enrollment request; enrollment does not follow redirects`, { hint: "Use the hub's final https URL" })
+    const message = cause instanceof Error ? cause.message : ""
+    if (/invalid enrollment reply/i.test(message)) return failure(COMMAND, "internal", `${server} sent an invalid enrollment reply`)
+    return failure(COMMAND, "offline", `Could not start enrollment with ${server}${/HTTP \d{3}/.test(message) ? ` (${/HTTP \d{3}/.exec(message)![0]})` : ""}`)
+  }
+  if (!validStart(start)) return failure(COMMAND, "internal", `${server} sent an invalid enrollment reply`)
+
+  const link = approvalURL(server, start.approveURL, start.userCode)
+  const warnings = link.warning ? [link.warning] : []
+  const expiresAt = Math.min(start.expiresAt, now() + (options.maxWaitMs ?? ENROLL_MAX_WAIT_MS))
+  options.onPrompt?.({ userCode: start.userCode, approveURL: link.url, expiresAt, autoApproved: start.autoApproved === true, ...(link.warning ? { warning: link.warning } : {}) })
+
+  const intervalMs = Math.min(Math.max(start.intervalMs, options.minIntervalMs ?? MIN_INTERVAL_MS), MAX_INTERVAL_MS)
+  let outcome: Awaited<ReturnType<MachineEnrollment["poll"]>>
+  try {
+    outcome = await flow.poll(server, { ...start, expiresAt, intervalMs }, signal)
+  } catch (cause) {
+    if (cause instanceof EnrollmentRefused) return failure(COMMAND, "internal", `${server} redirected the enrollment poll; enrollment does not follow redirects`, { warnings })
+    return failure(COMMAND, "offline", `Enrollment with ${server} failed`, { warnings })
+  }
+  if (outcome.status === "cancelled") return cancelled()
+  if (outcome.status === "denied") return failure(COMMAND, "enrollment_denied", `The enrollment of ${machineName} was denied on the hub`, { warnings })
+  if (outcome.status !== "approved") return failure(COMMAND, "enrollment_expired", "The enrollment code expired before it was approved; nothing was stored", { hint: "Run hubctl machine enroll again and approve the code on the hub", warnings })
+
+  const credential: MachineCredential = { server, machineID: outcome.machineID, machineName, token: outcome.machineToken }
+  return persist(credential, options, warnings, options.persistAttempts ?? PERSIST_ATTEMPTS)
+}
+
+const probeOptions = (options: MachineEnrollOptions) => ({
+  ...(options.fetch ? { fetch: options.fetch } : {}),
+  ...(options.signal ? { signal: options.signal } : {}),
+  ...(options.probeTimeoutMs ? { timeoutMs: options.probeTimeoutMs } : {}),
+})
+
+/** Saves a redeemed credential (retrying), then reports its status. Never aborted: the code cannot be redeemed again. */
+async function persist(credential: MachineCredential, options: MachineEnrollOptions, warnings: string[], attempts: number): Promise<MachineEnrollResult> {
+  const now = options.now ?? Date.now
+  let last: unknown
+  for (let attempt = 1; attempt <= Math.max(1, attempts); attempt++) {
+    try {
+      await options.store.write(credential)
+      last = undefined
+      break
+    } catch (cause) {
+      last = cause
+      if (attempt < attempts) await sleep(options.persistDelayMs ?? PERSIST_DELAY_MS)
+    }
+  }
+  if (last !== undefined) {
+    const errno = errnoOf(last)
+    const result = failure(COMMAND, "internal", `The hub approved this machine as ${credential.machineID}, but its credential could not be saved to ${options.store.location}${errno ? ` (${errno})` : ""}`, {
+      hint: `Fix the problem and retry while this command runs; otherwise revoke machine ${credential.machineID} on the hub and run hubctl machine enroll again`,
+      warnings,
+    })
+    return { ...result, retryPersist: () => persist(credential, options, warnings, 1) }
+  }
+  warnings = [...warnings, ...sharingNotes(options.store, false)]
+  if (options.verify === false) return success(COMMAND, statusOf(credential, undefined, now()), warnings)
+  const probe = await probeCredential(credential, probeOptions(options))
+  if (probe && !probe.reachable) return success(COMMAND, statusOf(credential, undefined, now()), [...warnings, `enrolled, but not verified: ${probe.detail}`])
+  const status = statusOf(credential, probe, now())
+  if (status.state === "revoked") return failure(COMMAND, "revoked", "The hub rejected the credential it just issued", { data: status, warnings })
+  return success(COMMAND, status, warnings)
+}

package/packages/cli/src/bootstrap/enrollment/index.ts

@@ -0,0 +1,7 @@
+// Canonical machine enrollment (`hubctl machine enroll`, `hubctl machine status`): the device-code flow of the
+// spoke SDK, the config.json credential store, and secret-free status. See docs/bootstrap-contracts.md §3.8.
+export * from "./store.ts"
+export * from "./policy.ts"
+export * from "./result.ts"
+export * from "./status.ts"
+export * from "./enroll.ts"

package/packages/cli/src/bootstrap/enrollment/policy.ts

@@ -0,0 +1,54 @@
+// The network policy of machine enrollment: which hub URLs a machine credential may be sent to, and which approval
+// link may be shown to the user.
+
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"])
+const MAX_URL = 2048
+
+/**
+ * The normalized hub URL (origin + path, no trailing slash), or undefined when it is not allowed: https only, plain
+ * http only for a loopback hub (a local hub, and the tests); no user info, query, fragment or whitespace. Matches the
+ * contract's hubURL check, and what src/config.ts normalize() keeps.
+ */
+export function checkServerURL(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_URL) return undefined
+  if (/[\s?#]/.test(value)) return undefined
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return undefined
+  }
+  if (url.username || url.password) return undefined
+  if (!(url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK.has(url.hostname)))) return undefined
+  if (!/^https?:\/\/[^\s/]+/.test(value)) return undefined
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`
+}
+
+export const isLoopbackServer = (server: string): boolean => {
+  try {
+    return LOOPBACK.has(new URL(server).hostname)
+  } catch {
+    return false
+  }
+}
+
+const USER_CODE = /^[A-Za-z0-9-]{4,32}$/
+
+export const isUserCode = (value: unknown): value is string => typeof value === "string" && USER_CODE.test(value)
+
+/**
+ * The approval link to show. The hub's own link is used only when it is on the hub's origin (scheme, host and port)
+ * and passes the URL policy: anything else could send the user (and their hub login) to a phishing page. Otherwise
+ * the link is rebuilt on the hub URL, with a warning.
+ */
+export function approvalURL(server: string, approveURL: unknown, userCode: string): { url: string; warning?: string } {
+  const own = `${server}/approve?code=${encodeURIComponent(userCode)}`
+  if (typeof approveURL !== "string" || approveURL.length > MAX_URL || /\s/.test(approveURL)) return { url: own, warning: "the hub sent no usable approval link; showing one on the hub URL" }
+  try {
+    const link = new URL(approveURL)
+    const base = new URL(server)
+    const allowed = checkServerURL(`${link.origin}${link.pathname}`) !== undefined && !link.username && !link.password
+    if (allowed && link.origin === base.origin) return { url: link.href }
+  } catch {}
+  return { url: own, warning: "the hub's approval link is on another origin; showing one on the hub URL instead" }
+}

package/packages/cli/src/bootstrap/enrollment/result.ts

@@ -0,0 +1,63 @@
+// The output of `machine enroll` / `machine status`: one hub.bootstrap.result envelope (for --json) and its exit
+// code, plus a text rendering for people. Every envelope is validated before it is returned: one that fails (for
+// instance because a credential slipped into it) is withheld and replaced by an internal error.
+import { ENVELOPE_SCHEMA, exitFor, validateEnvelope, type EnrollmentStatus, type ErrorCode, type ResultEnvelope } from "../contracts/index.ts"
+
+export type MachineCommand = "machine enroll" | "machine status"
+
+export interface MachineResult<T = EnrollmentStatus> {
+  readonly envelope: ResultEnvelope<T>
+  /** The process exit code (contracts envelope.ts exitFor; 0 on success). */
+  readonly exit: number
+}
+
+const clip = (s: string, max: number) => (s.length <= max ? s : `${s.slice(0, max - 1)}…`)
+/** One line, at most `max` characters (contract text fields are single-line). */
+export const line = (s: string, max = 200) => clip(s.replace(/[\u0000-\u001f\u007f]+/g, " ").trim(), max)
+
+function checked<T>(envelope: ResultEnvelope<T>): ResultEnvelope<T> {
+  if (validateEnvelope(envelope).ok) return envelope
+  return { schema: ENVELOPE_SCHEMA, version: 1, command: envelope.command, ok: false, error: { code: "internal", message: "The result failed validation and was withheld" } }
+}
+
+export function success<T>(command: MachineCommand, data: T, warnings: readonly string[] = []): MachineResult<T> {
+  const envelope = checked<T>({ schema: ENVELOPE_SCHEMA, version: 1, command, ok: true, data, ...(warnings.length ? { warnings: warnings.map((w) => line(w, 500)) } : {}) })
+  return { envelope, exit: envelope.ok ? 0 : exitFor(envelope.error!.code) }
+}
+
+export function failure<T = EnrollmentStatus>(
+  command: MachineCommand,
+  code: ErrorCode,
+  message: string,
+  extra: { hint?: string; data?: T; warnings?: readonly string[] } = {},
+): MachineResult<T> {
+  const envelope = checked<T>({
+    schema: ENVELOPE_SCHEMA,
+    version: 1,
+    command,
+    ok: false,
+    ...(extra.data !== undefined ? { data: extra.data } : {}),
+    error: { code, message: line(message, 500), ...(extra.hint ? { hint: line(extra.hint, 500) } : {}) },
+    ...(extra.warnings?.length ? { warnings: extra.warnings.map((w) => line(w, 500)) } : {}),
+  })
+  return { envelope, exit: exitFor(envelope.error!.code) }
+}
+
+const isStatus = (v: unknown): v is EnrollmentStatus => typeof v === "object" && v !== null && (v as { schema?: unknown }).schema === "hub.enrollment-status"
+
+/** Text for people: the machine's state, then any error, hint and warnings. */
+export function renderMachineResult(envelope: ResultEnvelope): string {
+  const lines: string[] = []
+  if (isStatus(envelope.data)) {
+    const s = envelope.data
+    const who = s.machineID ? ` as ${s.machineID}${s.machineName ? ` (${s.machineName})` : ""}` : ""
+    lines.push(s.server ? `machine: ${s.state}, enrolled with ${s.server}${who}` : `machine: ${s.state}`)
+    if (s.detail) lines.push(`  ${s.detail}`)
+  }
+  if (envelope.error) {
+    lines.push(`error: ${envelope.error.message}`)
+    if (envelope.error.hint) lines.push(`hint: ${envelope.error.hint}`)
+  }
+  for (const w of envelope.warnings ?? []) lines.push(`warning: ${w}`)
+  return `${lines.join("\n")}\n`
+}

package/packages/cli/src/bootstrap/enrollment/status.ts

@@ -0,0 +1,119 @@
+// `machine status`: what the credential store holds and, unless told not to, whether the hub still accepts it.
+// The check is a GET /spoke/ws with the machine token and no WebSocket upgrade: the hub authenticates before it
+// upgrades, so it answers 426 (Expected a WebSocket upgrade) to a token it accepts and 401 to one it rejects. No
+// central change is needed; nothing is opened. The token goes only to a hub URL that passes checkServerURL, never
+// across a redirect, and never into the output. v1.1: a credential already stored for a plain-http hub that is not on
+// loopback is reported as `insecure`, with a warning, and never sent there (a new enrollment to it stays refused).
+import { enrollmentStatusFrom, isInsecureHubURL, validateEnrollmentStatus, type CredentialProbe, type CredentialStore, type EnrollmentStatus, type MachineCredential } from "../contracts/index.ts"
+import { checkServerURL } from "./policy.ts"
+import { failure, line, success, type MachineResult } from "./result.ts"
+import { CredentialStoreError, type StoreContents } from "./store.ts"
+
+export const PROBE_TIMEOUT_MS = 10_000
+
+export interface ProbeOptions {
+  readonly fetch?: typeof fetch
+  readonly signal?: AbortSignal
+  readonly timeoutMs?: number
+}
+
+export interface ProbeResult extends CredentialProbe {
+  /** One line for people (HTTP status or error kind); never the response body or a credential. */
+  readonly detail: string
+}
+
+function reason(cause: unknown, signal?: AbortSignal): string {
+  if (signal?.aborted) return "cancelled"
+  const e = cause as { name?: string; code?: string } | undefined
+  if (e?.name === "TimeoutError") return "timed out"
+  return e?.code ?? e?.name ?? "error"
+}
+
+/** Asks the hub whether it accepts the credential. Undefined: not checked (the hub URL fails the policy). */
+export async function probeCredential(credential: MachineCredential, options: ProbeOptions = {}): Promise<ProbeResult | undefined> {
+  const server = checkServerURL(credential.server)
+  if (!server) return undefined
+  const doFetch = options.fetch ?? fetch
+  const signals = [AbortSignal.timeout(options.timeoutMs ?? PROBE_TIMEOUT_MS), ...(options.signal ? [options.signal] : [])]
+  let response: Response
+  try {
+    response = await doFetch(`${server}/spoke/ws`, {
+      method: "GET",
+      headers: { authorization: `Bearer ${credential.token}` },
+      redirect: "manual",
+      signal: AbortSignal.any(signals),
+    })
+  } catch (cause) {
+    return { reachable: false, detail: `could not reach ${server}: ${reason(cause, options.signal)}` }
+  }
+  void response.body?.cancel().catch(() => {})
+  if (response.status === 426) return { reachable: true, accepted: true, detail: `${server} accepts this machine` }
+  if (response.status === 401 || response.status === 403) return { reachable: true, accepted: false, detail: `${server} rejected the machine credential (revoked or unknown)` }
+  if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+    return { reachable: false, detail: `${server} redirected the check (HTTP ${response.status}); redirects are not followed` }
+  }
+  return { reachable: false, detail: `${server} could not check the credential (HTTP ${response.status})` }
+}
+
+/** A store that can also tell an incomplete entry (a token without a machine ID) from an empty one. */
+export type InspectableStore = CredentialStore & { inspect?(): StoreContents }
+
+export interface MachineStatusOptions extends ProbeOptions {
+  readonly store: InspectableStore
+  /** Check the credential with the hub (default true); false reports `configured` without any network access. */
+  readonly verify?: boolean
+  readonly now?: () => number
+}
+
+const COMMAND = "machine status"
+const MACHINE_NAME = /^[A-Za-z0-9._ -]{1,64}$/
+
+export function storeFailure(command: "machine status" | "machine enroll", cause: unknown, location: string): MachineResult {
+  if (cause instanceof CredentialStoreError && (cause.reason === "not_object" || cause.reason === "symlink")) {
+    return failure(command, "conflict", cause.message, { hint: `Fix ${location} by hand; hubctl does not replace it` })
+  }
+  return failure(command, "internal", cause instanceof CredentialStoreError ? cause.message : `Cannot read ${location}`)
+}
+
+/** The secret-free status of a credential, with an optional probe result. Drops a machine name the contract refuses. */
+export function statusOf(credential: MachineCredential | undefined, probe: ProbeResult | undefined, now: number, detail?: string): EnrollmentStatus {
+  const named = credential?.machineName && !MACHINE_NAME.test(credential.machineName) ? { ...credential, machineName: undefined } : credential
+  const status = enrollmentStatusFrom(named, probe, now)
+  const text = detail ?? probe?.detail
+  return text ? { ...status, detail: line(text) } : status
+}
+
+export async function machineStatus(options: MachineStatusOptions): Promise<MachineResult> {
+  const now = options.now ?? Date.now
+  const { store } = options
+  let credential: MachineCredential | undefined
+  let contents: StoreContents | undefined
+  try {
+    credential = await store.read()
+    contents = store.inspect?.()
+  } catch (cause) {
+    return storeFailure(COMMAND, cause, store.location)
+  }
+  if (!credential) {
+    const detail = contents?.state === "incomplete" ? `${store.location} has no machine ID for its credential; run hubctl machine enroll --reenroll` : undefined
+    return success(COMMAND, statusOf(undefined, undefined, now(), detail))
+  }
+  if (isInsecureHubURL(credential.server)) {
+    const status = statusOf(credential, undefined, now())
+    if (!validateEnrollmentStatus(status).ok) return failure(COMMAND, "internal", `${store.location} holds a machine identity this hubctl cannot report`)
+    return success(COMMAND, status, [
+      `the stored hub URL ${line(credential.server, 300)} is plain http and not on loopback, so the credential was not checked (it is never sent over plain http); enroll again with an https hub URL: hubctl machine enroll --server https://<hub> --reenroll`,
+    ])
+  }
+  if (!checkServerURL(credential.server)) {
+    return failure(COMMAND, "invalid", `The stored hub URL ${line(credential.server, 300)} is not https (plain http is allowed only for a loopback hub), so it was not checked`, {
+      hint: "Enroll again with an https hub URL: hubctl machine enroll --server https://<hub> --reenroll",
+    })
+  }
+  const probe = options.verify === false ? undefined : await probeCredential(credential, options)
+  const status = statusOf(credential, probe, now())
+  if (!validateEnrollmentStatus(status).ok) return failure(COMMAND, "internal", `${store.location} holds a machine identity this hubctl cannot report`)
+  if (status.state === "revoked") return failure(COMMAND, "revoked", "The hub rejected this machine's credential", { data: status, hint: "Enroll the machine again: hubctl machine enroll --reenroll" })
+  if (status.state === "offline") return failure(COMMAND, "offline", `Could not check the credential with ${credential.server}`, { data: status })
+  return success(COMMAND, status)
+}

package/packages/cli/src/bootstrap/enrollment/store.ts

@@ -0,0 +1,173 @@
+// The machine credential store: the spoke's config.json (src/config.ts), the one file every spoke and `hub node` on
+// this machine read their identity from. Writes merge into the raw JSON (every key the file holds survives, I4),
+// atomically (private temp file + rename) with mode 0600 in a 0700 directory. A symlinked config.json or config
+// directory is refused: a machine token must never be written into a dotfiles repository (T23).
+import { randomBytes } from "node:crypto"
+import { closeSync, lstatSync, mkdirSync, openSync, rmSync } from "node:fs"
+import { hostname } from "node:os"
+import path from "node:path"
+import { configPath, normalize, prepareConfigPath, readRawConfig, updateRawConfig, type Mode } from "../../../../../src/config.ts"
+import type { CredentialStore, MachineCredential } from "../contracts/index.ts"
+
+export type CredentialStoreFailure = "symlink" | "not_object" | "invalid" | "io"
+
+/** Why the store refused or failed. The message names the file and the reason, never a credential. */
+export class CredentialStoreError extends Error {
+  override readonly name = "CredentialStoreError"
+  constructor(
+    readonly reason: CredentialStoreFailure,
+    message: string,
+    /** The errno code of an I/O failure (EACCES, ENOSPC, …). */
+    readonly errno?: string,
+  ) {
+    super(message)
+  }
+}
+
+/**
+ * The spoke's sharing mode in config.json: `unset` when the file has no `mode` key (the spoke then treats it as
+ * "off"), else what the spoke reads (a value it does not understand reads as "off").
+ */
+export type SharingMode = Mode | "unset"
+
+/** The mode an enrollment turns on when the user never chose one: the OpenCode spoke connects only when it is not "off". */
+export const DEFAULT_SHARING: Mode = "always"
+
+/** What the file holds, without the credential: `incomplete` is a token without a machine ID (enroll again). */
+export type StoreContents = { readonly state: "empty" | "credential" | "incomplete" }
+
+const errnoOf = (cause: unknown) => (cause as NodeJS.ErrnoException | undefined)?.code
+
+function ioError(file: string, doing: string, cause: unknown): CredentialStoreError {
+  if (cause instanceof CredentialStoreError) return cause
+  const errno = errnoOf(cause)
+  return new CredentialStoreError("io", `Cannot ${doing} ${file}${errno ? ` (${errno})` : ""}`, errno)
+}
+
+const isLink = (p: string) => {
+  try {
+    return lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+export class ConfigCredentialStore implements CredentialStore {
+  readonly location: string
+
+  constructor(file: string) {
+    this.location = file
+  }
+
+  /** The raw config object ({} when there is none); throws a CredentialStoreError when it is not a JSON object. */
+  private raw(): Record<string, unknown> {
+    try {
+      return readRawConfig(this.location) ?? {}
+    } catch (cause) {
+      if (errnoOf(cause)) throw ioError(this.location, "read", cause)
+      throw new CredentialStoreError("not_object", `${this.location} is not a JSON object; fix or remove it first`)
+    }
+  }
+
+  private refuseLinks(): void {
+    for (const p of [path.dirname(this.location), this.location]) {
+      if (isLink(p)) throw new CredentialStoreError("symlink", `${p} is a symlink; hubctl never writes a machine credential through one (keep config.json out of dotfiles)`)
+    }
+  }
+
+  /**
+   * Checks, before a one-time enrollment code is redeemed, that write() can succeed: no symlink, a JSON object (or
+   * no file), and a writable private directory (created 0700 if missing). Leaves no file behind.
+   */
+  async preflight(): Promise<void> {
+    this.refuseLinks()
+    this.raw()
+    const dir = path.dirname(this.location)
+    const probe = path.join(dir, `.${path.basename(this.location)}.${process.pid}.${randomBytes(6).toString("hex")}.probe`)
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 })
+      closeSync(openSync(probe, "wx", 0o600))
+    } catch (cause) {
+      throw ioError(dir, "write to", cause)
+    } finally {
+      rmSync(probe, { force: true })
+    }
+    this.refuseLinks()
+  }
+
+  inspect(): StoreContents {
+    const config = normalize(this.raw(), hostname())
+    if (!config.token) return { state: "empty" }
+    return { state: config.machineID ? "credential" : "incomplete" }
+  }
+
+  sharingMode(): SharingMode {
+    const raw = this.raw()
+    return "mode" in raw ? normalize({ mode: raw.mode }, "x").mode : "unset"
+  }
+
+  /**
+   * Turns sharing on (`mode: "always"`) when config.json has no `mode` at all, so an enrolled machine's spoke
+   * connects. An explicit value, "off" included, is the user's and is never changed. True when it wrote.
+   */
+  enableSharing(): boolean {
+    this.refuseLinks()
+    if ("mode" in this.raw()) return false
+    try {
+      updateRawConfig(this.location, (raw) => ("mode" in raw ? raw : { ...raw, mode: DEFAULT_SHARING }))
+    } catch (cause) {
+      throw ioError(this.location, "write", cause)
+    }
+    return true
+  }
+
+  async read(): Promise<MachineCredential | undefined> {
+    const raw = this.raw()
+    const config = normalize(raw, hostname())
+    if (!config.token || !config.machineID) return undefined
+    const machineName = typeof raw.machineName === "string" && raw.machineName ? raw.machineName : undefined
+    return { server: config.server, machineID: config.machineID, ...(machineName ? { machineName } : {}), token: config.token }
+  }
+
+  async write(credential: MachineCredential): Promise<void> {
+    const server = credential.server.replace(/\/+$/, "")
+    // normalize() falls back to the default server for a URL it cannot keep; the token must never end up paired with it.
+    if (normalize({ server }, "x").server !== server) throw new CredentialStoreError("invalid", `Refusing to store a credential for an unusable server URL`)
+    if (!credential.token || !credential.machineID) throw new CredentialStoreError("invalid", "Refusing to store an incomplete credential")
+    this.refuseLinks()
+    this.raw()
+    try {
+      updateRawConfig(this.location, (raw) => ({
+        ...raw,
+        server,
+        machineID: credential.machineID,
+        ...(credential.machineName ? { machineName: credential.machineName } : {}),
+        token: credential.token,
+        // An enrolled machine shares by default (the /hub dialog asks; hubctl cannot): only when the user never chose.
+        ...("mode" in raw ? {} : { mode: DEFAULT_SHARING }),
+      }))
+    } catch (cause) {
+      throw ioError(this.location, "write", cause)
+    }
+  }
+
+  async clear(): Promise<void> {
+    this.refuseLinks()
+    const raw = this.raw()
+    if (!("token" in raw) && !("machineID" in raw)) return
+    try {
+      updateRawConfig(this.location, ({ token: _token, machineID: _machineID, ...rest }) => rest)
+    } catch (cause) {
+      throw ioError(this.location, "write", cause)
+    }
+  }
+}
+
+/**
+ * The machine's credential store: $HUB_SPOKE_CONFIG, else ~/.config/hub/config.json (the file the spoke and
+ * `hub node` read). With `migrate` (for enroll), a legacy config is copied to the default location first, as the
+ * spoke does; status reads without side effects.
+ */
+export function credentialStoreFor(env: Readonly<Record<string, string | undefined>>, home: string, options: { migrate?: boolean } = {}): ConfigCredentialStore {
+  return new ConfigCredentialStore(options.migrate ? prepareConfigPath(env, home) : configPath(env, home))
+}

package/packages/cli/src/bootstrap/preview/index.ts

@@ -0,0 +1,5 @@
+// Deterministic setup previews (HBS-03): planSetup, previewSetup, revalidateApply, renderPreview.
+export * from "./plan.ts"
+export * from "./links.ts"
+export * from "./preview.ts"
+export * from "./render.ts"