@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/bootstrap/contracts/journal.ts

@@ -0,0 +1,198 @@
+// The transaction journal, ownership records, recovery rules and the apply lock.
+//
+// apply takes the lock (O_EXCL create of state:hub/bootstrap/apply.lock), writes the journal before each action
+// ("pending", with the file's state before and a backup reference), performs the action, then marks it "done"
+// with the state after. The journal holds digests and modes, never contents (backups are separate owner-only
+// files) and never credentials. After a crash, recovery walks the entries newest first and decides per entry
+// (recoveryDecision): undo what is still exactly as we left it, keep anything the user changed since, and never
+// restore a stale credential (a rolled-back enrollment is cleared, not reverted to the previous token).
+import { ACTION_KINDS, type ActionKind } from "./actions.ts"
+import { checkPathRef, type PathRef } from "./paths.ts"
+import { findSecrets } from "./secrets.ts"
+import { bool, Checker, digest, header, instant, int, isRecord, list, oneOf, pointer, shape, text, type Result } from "./validate.ts"
+
+export const JOURNAL_SCHEMA = "hub.transaction-journal"
+export const JOURNAL_STATES = ["prepared", "applying", "committed", "rolling-back", "rolled-back", "failed"] as const
+export type JournalState = (typeof JOURNAL_STATES)[number]
+export const ENTRY_CLASSES = ["file", "config", "credential", "service", "artifact", "harness", "link", "directory", "external"] as const
+/** harness: an installed harness binary/version (rollback restores the previous one). external: a step with no local file (verify, launch, service activation); nothing to undo on disk. */
+export type EntryClass = (typeof ENTRY_CLASSES)[number]
+
+export interface FileState {
+  readonly exists: boolean
+  readonly sha256?: string
+  readonly mode?: number
+  readonly symlink?: boolean
+}
+
+/** One owned change. `before`/`after` are what the file was and what we made it; ownership is "we wrote `after`". */
+export interface JournalEntry {
+  readonly seq: number
+  readonly actionID: string
+  readonly kind: ActionKind
+  readonly class: EntryClass
+  readonly path?: PathRef
+  readonly before: FileState
+  readonly after?: FileState
+  /** The owner-only copy of `before` (never for credentials). */
+  readonly backup?: { readonly id: string }
+  readonly status: "pending" | "done" | "undone" | "skipped"
+}
+
+export interface TransactionJournal {
+  readonly schema: typeof JOURNAL_SCHEMA
+  readonly version: 1
+  readonly txID: string
+  readonly planDigest: string
+  readonly hostFingerprint: string
+  /** The preview nonce this apply consumed (replays are refused). */
+  readonly nonce: string
+  readonly state: JournalState
+  readonly startedAt: number
+  readonly updatedAt: number
+  readonly entries: readonly JournalEntry[]
+}
+
+/** Classes whose previous content must be backed up before they are changed. */
+const BACKED_UP: readonly EntryClass[] = ["file", "config", "service", "artifact", "harness", "link"]
+const TX_ID = /^tx_[A-Za-z0-9]{1,64}$/
+const BACKUP_ID = /^bk_[A-Za-z0-9]{1,64}$/
+const NONCE = /^[A-Za-z0-9_-]{16,128}$/
+
+function checkFileState(c: Checker, path: string, v: unknown) {
+  const r = shape(c, path, v, ["exists"], ["sha256", "mode", "symlink"])
+  if (!r) return
+  bool(c, pointer(path, "exists"), r.exists)
+  if (r.sha256 !== undefined) digest(c, pointer(path, "sha256"), r.sha256)
+  if (r.mode !== undefined) int(c, pointer(path, "mode"), r.mode, 0, 0o7777)
+  if (r.symlink !== undefined) bool(c, pointer(path, "symlink"), r.symlink)
+  if (r.exists === false && (r.sha256 !== undefined || r.mode !== undefined)) c.add(path, "inconsistent", "a missing file has no digest or mode")
+}
+
+export function validateJournal(value: unknown): Result<TransactionJournal> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "txID", "planDigest", "hostFingerprint", "nonce", "state", "startedAt", "updatedAt", "entries"])
+  if (!r) return c.result(value)
+  header(c, "", r, JOURNAL_SCHEMA, 1)
+  text(c, "/txID", r.txID, 67, TX_ID)
+  digest(c, "/planDigest", r.planDigest)
+  digest(c, "/hostFingerprint", r.hostFingerprint)
+  text(c, "/nonce", r.nonce, 128, NONCE)
+  oneOf(c, "/state", r.state, JOURNAL_STATES)
+  if (instant(c, "/startedAt", r.startedAt) && instant(c, "/updatedAt", r.updatedAt) && (r.updatedAt as number) < (r.startedAt as number))
+    c.add("/updatedAt", "inconsistent", "updated before it started")
+  list(c, "/entries", r.entries, 256, (p, v) => {
+    const e = shape(c, p, v, ["seq", "actionID", "kind", "class", "before", "status"], ["path", "after", "backup"])
+    if (!e) return
+    const index = Number(p.slice(p.lastIndexOf("/") + 1))
+    if (int(c, pointer(p, "seq"), e.seq, 1, 256) && e.seq !== index + 1) c.add(pointer(p, "seq"), "inconsistent", "entries are numbered 1, 2, 3, … in order")
+    text(c, pointer(p, "actionID"), e.actionID, 64, /^[a-z0-9][a-z0-9-]{0,63}$/)
+    oneOf(c, pointer(p, "kind"), e.kind, ACTION_KINDS)
+    oneOf(c, pointer(p, "class"), e.class, ENTRY_CLASSES)
+    oneOf(c, pointer(p, "status"), e.status, ["pending", "done", "undone", "skipped"] as const)
+    if (e.path !== undefined) checkPathRef(c, pointer(p, "path"), e.path)
+    else if (e.class !== "external") c.add(pointer(p, "path"), "missing_field", "a local change names its path")
+    checkFileState(c, pointer(p, "before"), e.before)
+    if (e.after !== undefined) checkFileState(c, pointer(p, "after"), e.after)
+    if (e.backup !== undefined) {
+      const b = shape(c, pointer(p, "backup"), e.backup, ["id"])
+      if (b) text(c, pointer(pointer(p, "backup"), "id"), b.id, 67, BACKUP_ID)
+    }
+    const before = isRecord(e.before) ? e.before : {}
+    if (e.class === "credential" && e.backup !== undefined) c.add(pointer(p, "backup"), "inconsistent", "credentials are never backed up (a stale credential is never restored)")
+    // v1.1: a skipped entry changed nothing, so it has nothing to back up.
+    if (BACKED_UP.includes(e.class as EntryClass) && before.exists === true && e.backup === undefined && e.status !== "skipped")
+      c.add(pointer(p, "backup"), "inconsistent", "an existing file is backed up before it is changed")
+    if ((e.status === "done" || e.status === "undone") && e.after === undefined && e.class !== "external") c.add(pointer(p, "after"), "inconsistent", "a done entry records the state it left")
+  })
+  for (const p of findSecrets(value)) c.add(p, "secret", "journals never carry credentials")
+  return c.result(value)
+}
+
+export type RecoveryDecision = "nothing-to-do" | "remove-created" | "restore-backup" | "clear-credential" | "keep-user-edit"
+
+const sameState = (a: FileState, b: FileState) =>
+  a.exists === b.exists && (a.sha256 ?? null) === (b.sha256 ?? null) && (a.mode === undefined || b.mode === undefined || a.mode === b.mode) && Boolean(a.symlink) === Boolean(b.symlink)
+
+/**
+ * What recovery does for one entry, given the file's state now. Anything not exactly as we left it is a user edit
+ * and is kept (reported as a conflict), never overwritten.
+ */
+export function recoveryDecision(entry: JournalEntry, current: FileState): RecoveryDecision {
+  if (entry.status === "undone" || entry.status === "skipped" || entry.class === "external") return "nothing-to-do"
+  const ours = entry.after !== undefined && sameState(current, entry.after)
+  if (entry.status === "pending" && sameState(current, entry.before)) return "nothing-to-do"
+  // v1.1: an enrollment interrupted before it was journaled done records no `after`. The credential store writes
+  // atomically, so a changed file means the interrupted enrollment stored its credential: clear it (never restore).
+  if (entry.class === "credential" && entry.status === "pending" && entry.after === undefined) return "clear-credential"
+  if (!ours) return "keep-user-edit"
+  if (entry.class === "credential") return "clear-credential"
+  if (entry.before.exists) return entry.backup ? "restore-backup" : "keep-user-edit"
+  return "remove-created"
+}
+
+export interface RecoveryStep {
+  readonly seq: number
+  readonly actionID: string
+  readonly decision: RecoveryDecision
+}
+
+/** Recovery for an interrupted transaction, newest entry first; finished transactions need none. */
+export function recoveryPlan(journal: TransactionJournal, stateOf: (entry: JournalEntry) => FileState): RecoveryStep[] {
+  if (journal.state === "committed" || journal.state === "rolled-back") return []
+  return [...journal.entries].reverse().map((entry) => ({ seq: entry.seq, actionID: entry.actionID, decision: recoveryDecision(entry, stateOf(entry)) }))
+}
+
+/** Hooks the applier calls around each step (logging, progress, tests). They observe; they cannot change actions. */
+export interface JournalHooks {
+  beforeAction?(entry: JournalEntry, journal: TransactionJournal): void | Promise<void>
+  afterAction?(entry: JournalEntry, journal: TransactionJournal): void | Promise<void>
+  onConflict?(entry: JournalEntry, current: FileState): void | Promise<void>
+  onRecover?(journal: TransactionJournal, steps: readonly RecoveryStep[]): void | Promise<void>
+}
+
+// ---------- apply lock ----------
+
+export const LOCK_SCHEMA = "hub.apply-lock"
+/** The longest an apply may hold the lock before it is considered stale. */
+export const LOCK_MAX_MS = 60 * 60_000
+/** Where the lock lives (state root). */
+export const LOCK_PATH: PathRef = { root: "state", rel: "hub/bootstrap/apply.lock" }
+
+export interface ApplyLock {
+  readonly schema: typeof LOCK_SCHEMA
+  readonly version: 1
+  readonly pid: number
+  readonly hostFingerprint: string
+  readonly txID: string
+  readonly acquiredAt: number
+  readonly expiresAt: number
+}
+
+export function validateApplyLock(value: unknown): Result<ApplyLock> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "pid", "hostFingerprint", "txID", "acquiredAt", "expiresAt"])
+  if (!r) return c.result(value)
+  header(c, "", r, LOCK_SCHEMA, 1)
+  int(c, "/pid", r.pid, 1, 2 ** 31)
+  digest(c, "/hostFingerprint", r.hostFingerprint)
+  text(c, "/txID", r.txID, 67, TX_ID)
+  if (instant(c, "/acquiredAt", r.acquiredAt) && instant(c, "/expiresAt", r.expiresAt)) {
+    const span = (r.expiresAt as number) - (r.acquiredAt as number)
+    if (span <= 0 || span > LOCK_MAX_MS) c.add("/expiresAt", "invalid_value", `a lock is held for 1 ms..${LOCK_MAX_MS / 60_000} minutes`)
+  }
+  return c.result(value)
+}
+
+export type LockState = "free" | "held" | "stale" | "foreign"
+
+/**
+ * free: take it. held: another apply runs (refuse: exit locked). stale: same host, the holder died or overran
+ * (recover its journal, then take it). foreign: another host's lock (a shared home): never broken automatically.
+ */
+export function lockState(lock: ApplyLock | undefined, context: { readonly now: number; readonly hostFingerprint: string; readonly isAlive: (pid: number) => boolean }): LockState {
+  if (!lock) return "free"
+  if (lock.hostFingerprint !== context.hostFingerprint) return "foreign"
+  if (context.now >= lock.expiresAt || !context.isAlive(lock.pid)) return "stale"
+  return "held"
+}

package/packages/cli/src/bootstrap/contracts/paths.ts

@@ -0,0 +1,91 @@
+// Where the bootstrap may touch the filesystem. Plans never carry absolute paths: every path is a PathRef, a named
+// root plus a relative path inside it. Discovery maps each root to this host's absolute directory; a relative path
+// can never climb out of its root ("..", absolute, backslashes, NUL), and the applier refuses to write through any
+// symlink between the root and the target (checkNoSymlinkEscape), so a planted link cannot redirect a write.
+import { Checker, fail, isAbsolutePath, ok, oneOf, pointer, shape, type Result } from "./validate.ts"
+
+export const ROOT_IDS = ["home", "config", "state", "data", "user-bin", "launch-agents", "systemd-user", "system-bin"] as const
+export type RootID = (typeof ROOT_IDS)[number]
+
+/**
+ * Roots that need explicit escalation to write. Everything else is the user's own directories; the default
+ * install is unprivileged.
+ */
+export const ELEVATED_ROOTS: readonly RootID[] = ["system-bin"]
+
+export interface PathRef {
+  readonly root: RootID
+  /** Relative, "/"-separated, inside the root. */
+  readonly rel: string
+}
+
+/** A root as discovery found it on this host (and where a container sees it, when the host is a container). */
+export interface RootMapping {
+  readonly id: RootID
+  readonly path: string
+  readonly containerPath?: string
+}
+
+// eslint-disable-next-line no-control-regex
+const BAD_REL = /[\u0000-\u001f\u007f\\]/
+
+export function isSafeRel(rel: unknown): rel is string {
+  if (typeof rel !== "string" || rel.length === 0 || rel.length > 1024 || rel.startsWith("/") || BAD_REL.test(rel)) return false
+  return rel.split("/").every((s) => s !== "" && s !== "." && s !== ".." && s.length <= 255)
+}
+
+export function checkPathRef(c: Checker, path: string, value: unknown): value is PathRef {
+  const r = shape(c, path, value, ["root", "rel"])
+  if (!r) return false
+  const rootOK = oneOf(c, pointer(path, "root"), r.root, ROOT_IDS)
+  const relOK = isSafeRel(r.rel)
+  if (!relOK && r.rel !== undefined) c.add(pointer(path, "rel"), "invalid_path", "expected a relative path inside the root (no '..', '/', '\\' or control characters)")
+  return rootOK && relOK
+}
+
+export function validatePathRef(value: unknown): Result<PathRef> {
+  const c = new Checker()
+  checkPathRef(c, "", value)
+  return c.result(value)
+}
+
+/**
+ * v1.1: where the code that resolves a path runs. `path` is always the host's view of a root; `containerPath` is
+ * what a process inside the container sees (discovery records it only when it ran inside one). hubctl resolves
+ * paths for the context it runs in: inside the container, a root is `containerPath ?? path`; on the host, `path`.
+ */
+export const EXECUTION_CONTEXTS = ["host", "container"] as const
+export type ExecutionContext = (typeof EXECUTION_CONTEXTS)[number]
+
+/** The absolute directory of `root` as seen from `context`. */
+export const rootPathIn = (root: RootMapping, context: ExecutionContext): string => (context === "container" ? (root.containerPath ?? root.path) : root.path)
+
+/** The absolute path of `ref` on a host with these roots, as seen from `context` (default: the host). */
+export function resolvePathRef(ref: PathRef, roots: readonly RootMapping[], context: ExecutionContext = "host"): Result<string> {
+  const checked = validatePathRef(ref)
+  if (!checked.ok) return checked as Result<string>
+  const root = roots.find((r) => r.id === ref.root)
+  const base = root ? rootPathIn(root, context) : undefined
+  if (!base || !isAbsolutePath(base)) return fail("/root", "unmapped_root", `this host has no ${ref.root} root`)
+  return ok(base === "/" ? `/${ref.rel}` : `${base}/${ref.rel}`)
+}
+
+export type EntryKind = "file" | "directory" | "symlink" | "missing" | "other"
+
+/**
+ * Walks from `rootAbs` to `rootAbs/rel` with `lstat` (which must not follow links) and fails at the first symlink. A missing component ends the walk: the rest would be created. The root itself is the
+ * mapping discovery reported and is not checked here.
+ */
+export function checkNoSymlinkEscape(rootAbs: string, rel: string, lstat: (path: string) => EntryKind): Result<string> {
+  if (!isAbsolutePath(rootAbs)) return fail("", "invalid_path", "the root must be an absolute, normalized path")
+  if (!isSafeRel(rel)) return fail("", "invalid_path", "expected a relative path inside the root")
+  const parts = rel.split("/")
+  let current = rootAbs === "/" ? "" : rootAbs
+  for (const part of parts) {
+    current = `${current}/${part}`
+    const kind = lstat(current)
+    if (kind === "symlink") return fail("", "symlink", `${current} is a symbolic link; refusing to write through it`)
+    if (kind === "missing") break
+  }
+  return ok(rootAbs === "/" ? `/${rel}` : `${rootAbs}/${rel}`)
+}

package/packages/cli/src/bootstrap/contracts/plan.ts

@@ -0,0 +1,155 @@
+// SetupPlan and PreviewToken. A plan is a pure function of (discovery snapshot, profile): no timestamps, no
+// randomness, so the same host and choices always produce the same plan and the same digest. `hubctl setup
+// preview` shows the plan and issues a preview token bound to the host fingerprint, the snapshot digest and the
+// plan digest, with a short expiry and a single-use nonce. `apply` never trusts the token's content: it rediscovers,
+// re-plans, and applies only when the fresh plan's digest equals the previewed one (revalidatePreview), so a stale,
+// foreign, expired or replayed preview applies nothing.
+import { checkAction, type Action } from "./actions.ts"
+import { digestOf } from "./canonical.ts"
+import { PLAN_PROFILE_VERSIONS, PROFILE_IDS, type PlanProfileVersion, type ProfileID } from "./profile.ts"
+import { checkTarget } from "./platform.ts"
+import { bool, Checker, digest, fail, header, instant, isRecord, list, ok, oneOf, shape, text, type Result } from "./validate.ts"
+
+export const PLAN_SCHEMA = "hub.setup-plan"
+export const PLAN_VERSION = 1
+export const PLAN_MAX_ACTIONS = 256
+
+export interface SetupPlan {
+  readonly schema: typeof PLAN_SCHEMA
+  readonly version: typeof PLAN_VERSION
+  readonly hostFingerprint: string
+  /** digestOf the DiscoverySnapshot the plan was made from. */
+  readonly snapshotDigest: string
+  readonly target: string
+  /** v1.1: the profile version it was planned from (1 for plans made by a v1.0 hubctl). */
+  readonly profile: { readonly id: ProfileID; readonly version: PlanProfileVersion }
+  /** True iff some action is elevated; apply then needs explicit consent (--escalate). */
+  readonly requiresEscalation: boolean
+  /** True iff the plan activates a service; apply then needs explicit consent. */
+  readonly activatesServices: boolean
+  /** In execution order. */
+  readonly actions: readonly Action[]
+}
+
+export function validateSetupPlan(value: unknown): Result<SetupPlan> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "hostFingerprint", "snapshotDigest", "target", "profile", "requiresEscalation", "activatesServices", "actions"])
+  if (!r) return c.result(value)
+  header(c, "", r, PLAN_SCHEMA, PLAN_VERSION)
+  digest(c, "/hostFingerprint", r.hostFingerprint)
+  digest(c, "/snapshotDigest", r.snapshotDigest)
+  if (typeof r.target !== "string" || !checkTarget(r.target).ok) c.add("/target", "unsupported_platform", `cannot plan for ${String(r.target)}`)
+  const profile = shape(c, "/profile", r.profile, ["id", "version"])
+  if (profile) {
+    oneOf(c, "/profile/id", profile.id, PROFILE_IDS)
+    if (!(PLAN_PROFILE_VERSIONS as readonly unknown[]).includes(profile.version)) c.add("/profile/version", "unsupported_version", `profile version must be one of ${PLAN_PROFILE_VERSIONS.join(", ")}`)
+  }
+  bool(c, "/requiresEscalation", r.requiresEscalation)
+  bool(c, "/activatesServices", r.activatesServices)
+  if (!list(c, "/actions", r.actions, PLAN_MAX_ACTIONS, (p, v) => checkAction(c, p, v), (v) => (isRecord(v) && typeof v.id === "string" ? v.id : undefined))) return c.result(value)
+
+  const actions = (r.actions as unknown[]).filter(isRecord)
+  const elevated = actions.some((a) => a.escalation === "elevated")
+  if (r.requiresEscalation !== elevated) c.add("/requiresEscalation", "inconsistent", "requiresEscalation must say exactly whether an action is elevated")
+  const activates = actions.some((a) => a.kind === "activate-service")
+  if (r.activatesServices !== activates) c.add("/activatesServices", "inconsistent", "activatesServices must say exactly whether a service is activated")
+  const installed = new Set<string>()
+  const verified = new Set<string>()
+  const unverifiedInstalls = new Map<string, number>()
+  // v1.1: an installed version is made current (select-harness-version) before it is verified.
+  const awaitingSelect = new Map<string, { version: string; index: number }>()
+  const removed = new Set<string>()
+  const installAt = (harness: string, version: string) => actions.findIndex((a) => a.kind === "install-harness" && a.harness === harness && a.version === version)
+  let enrollments = 0
+  actions.forEach((a, i) => {
+    const at = `/actions/${i}`
+    const service = `${String(a.service)}@${String(a.manager)}`
+    if (a.kind === "install-service") installed.add(service)
+    if (a.kind === "install-harness") {
+      unverifiedInstalls.set(String(a.harness), i)
+      awaitingSelect.set(String(a.harness), { version: String(a.version), index: i })
+    }
+    if (a.kind === "select-harness-version") {
+      const pending = awaitingSelect.get(String(a.harness))
+      if (pending?.version === a.version) awaitingSelect.delete(String(a.harness))
+      else if (installAt(String(a.harness), String(a.version)) > i) c.add(at, "inconsistent", "a harness version is installed before it is made current")
+      unverifiedInstalls.set(String(a.harness), i)
+    }
+    if (a.kind === "verify-harness") {
+      if (awaitingSelect.has(String(a.harness))) c.add(at, "inconsistent", "a harness is verified after its installed version is made current")
+      verified.add(String(a.harness))
+      unverifiedInstalls.delete(String(a.harness))
+    }
+    if (a.kind === "remove-service") removed.add(service)
+    if (a.kind === "deactivate-service" && removed.has(service)) c.add(at, "inconsistent", "a service is deactivated before it is removed")
+    if (a.kind === "activate-service" && !installed.has(service)) c.add(at, "inconsistent", "a service is installed before it is activated")
+    if (a.kind === "launch-session" && !verified.has(String(a.harness))) c.add(at, "inconsistent", "a harness is verified before a session is launched on it")
+    if (a.kind === "enroll-machine" && ++enrollments > 1) c.add(at, "duplicate", "a plan enrolls the machine at most once")
+  })
+  for (const i of unverifiedInstalls.values()) c.add(`/actions/${i}`, "inconsistent", "an installed harness is verified afterwards (install is not readiness)")
+  for (const { index } of awaitingSelect.values()) c.add(`/actions/${index}`, "inconsistent", "an installed harness version is made current afterwards (select-harness-version)")
+  return c.result(value)
+}
+
+/** The digest previews and journals pin. */
+export const planDigest = (plan: SetupPlan): string => digestOf(plan)
+
+export const PREVIEW_SCHEMA = "hub.preview-token"
+export const PREVIEW_VERSION = 1
+export const PREVIEW_MAX_TTL_MS = 15 * 60_000
+/** How far a preview's issue time may be ahead of this clock. */
+export const PREVIEW_CLOCK_SKEW_MS = 60_000
+const NONCE = /^[A-Za-z0-9_-]{16,128}$/
+
+export interface PreviewToken {
+  readonly schema: typeof PREVIEW_SCHEMA
+  readonly version: typeof PREVIEW_VERSION
+  readonly planDigest: string
+  readonly hostFingerprint: string
+  readonly snapshotDigest: string
+  readonly issuedAt: number
+  readonly expiresAt: number
+  /** Single use: apply records it in the journal and refuses it again. */
+  readonly nonce: string
+}
+
+export function validatePreviewToken(value: unknown): Result<PreviewToken> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "planDigest", "hostFingerprint", "snapshotDigest", "issuedAt", "expiresAt", "nonce"])
+  if (!r) return c.result(value)
+  header(c, "", r, PREVIEW_SCHEMA, PREVIEW_VERSION)
+  digest(c, "/planDigest", r.planDigest)
+  digest(c, "/hostFingerprint", r.hostFingerprint)
+  digest(c, "/snapshotDigest", r.snapshotDigest)
+  if (instant(c, "/issuedAt", r.issuedAt) && instant(c, "/expiresAt", r.expiresAt)) {
+    const ttl = (r.expiresAt as number) - (r.issuedAt as number)
+    if (ttl <= 0 || ttl > PREVIEW_MAX_TTL_MS) c.add("/expiresAt", "invalid_value", `a preview lives 1 ms..${PREVIEW_MAX_TTL_MS / 60_000} minutes`)
+  }
+  text(c, "/nonce", r.nonce, 128, NONCE)
+  return c.result(value)
+}
+
+export interface RevalidationContext {
+  readonly now: number
+  /** This host's fingerprint, computed fresh. */
+  readonly hostFingerprint: string
+  /** The plan made fresh from a new discovery. */
+  readonly plan: SetupPlan
+  /** Nonces already consumed by earlier applies (from the journals). */
+  readonly usedNonces: ReadonlySet<string>
+}
+
+/** Whether `apply` may proceed with this preview. Checked in this order; the first failure is the answer. */
+export function revalidatePreview(token: unknown, context: RevalidationContext): Result<PreviewToken> {
+  const checked = validatePreviewToken(token)
+  if (!checked.ok) return checked
+  const t = checked.value
+  if (t.hostFingerprint !== context.hostFingerprint || context.plan.hostFingerprint !== context.hostFingerprint)
+    return fail("/hostFingerprint", "preview_foreign", "this preview was made for another host or account")
+  if (context.now >= t.expiresAt) return fail("/expiresAt", "preview_expired", "the preview expired; run the preview again")
+  if (t.issuedAt > context.now + PREVIEW_CLOCK_SKEW_MS) return fail("/issuedAt", "preview_not_yet_valid", "the preview is from the future (clock skew?)")
+  if (context.usedNonces.has(t.nonce)) return fail("/nonce", "preview_replayed", "this preview was already applied")
+  if (t.snapshotDigest !== context.plan.snapshotDigest || t.planDigest !== planDigest(context.plan))
+    return fail("/planDigest", "preview_stale", "the host or the plan changed since the preview; run the preview again")
+  return ok(t)
+}

package/packages/cli/src/bootstrap/contracts/platform.ts

@@ -0,0 +1,62 @@
+// The supported platform matrix: the only hosts a hubctl artifact is built for and a setup plan may target. Every
+// other host is named explicitly with the reason it is refused, so "unsupported" is a clear answer rather than a
+// guess at a nearby target.
+import { fail, ok, type Result } from "./validate.ts"
+
+export type Platform = "darwin" | "linux"
+export type Arch = "arm64" | "x64"
+/** "none" on macOS; "unknown" when a Linux host's C library could not be identified. */
+export type Libc = "none" | "glibc" | "musl" | "unknown"
+export type ServiceManager = "launchd" | "systemd-user"
+
+export interface SupportedTarget {
+  readonly target: string
+  readonly platform: Platform
+  readonly arch: Arch
+  readonly libc: Libc
+  /** The per-user service manager services are installed for on this target. */
+  readonly serviceManager: ServiceManager
+  /**
+   * The `bun build --compile --target` the release builds this target's hubctl with. x64 targets use Bun's
+   * `-baseline` runtime: the default x64 runtime needs AVX2 and dies with SIGILL (exit 132) on CPUs without it,
+   * including QEMU's default kvm64 model, before hubctl can even print --version.
+   */
+  readonly bunTarget: string
+}
+
+export const SUPPORTED_TARGETS: readonly SupportedTarget[] = Object.freeze([
+  { target: "darwin-arm64", platform: "darwin", arch: "arm64", libc: "none", serviceManager: "launchd", bunTarget: "bun-darwin-arm64" },
+  { target: "darwin-x64", platform: "darwin", arch: "x64", libc: "none", serviceManager: "launchd", bunTarget: "bun-darwin-x64-baseline" },
+  { target: "linux-x64", platform: "linux", arch: "x64", libc: "glibc", serviceManager: "systemd-user", bunTarget: "bun-linux-x64-baseline" },
+  { target: "linux-arm64", platform: "linux", arch: "arm64", libc: "glibc", serviceManager: "systemd-user", bunTarget: "bun-linux-arm64" },
+] as const)
+
+export interface UnsupportedTarget {
+  readonly target: string
+  readonly reason: string
+}
+
+export const UNSUPPORTED_TARGETS: readonly UnsupportedTarget[] = Object.freeze([
+  { target: "windows-x64", reason: "Windows bootstrap is out of scope (no launchd/systemd user services, different credential store)" },
+  { target: "windows-arm64", reason: "Windows bootstrap is out of scope (no launchd/systemd user services, different credential store)" },
+  { target: "linux-x64-musl", reason: "musl Linux (e.g. Alpine) has no hubctl build yet; the glibc build does not run there" },
+  { target: "linux-arm64-musl", reason: "musl Linux (e.g. Alpine) has no hubctl build yet; the glibc build does not run there" },
+] as const)
+
+const PLATFORM_NAME: Record<string, string> = { darwin: "darwin", linux: "linux", win32: "windows" }
+
+/** The target name of a host as Node reports it (process.platform, process.arch) plus its C library. */
+export function targetOf(platform: string, arch: string, libc: Libc): string {
+  const name = PLATFORM_NAME[platform] ?? platform
+  return `${name}-${arch}${name === "linux" && libc === "musl" ? "-musl" : ""}`
+}
+
+export const supportedTarget = (target: string): SupportedTarget | undefined => SUPPORTED_TARGETS.find((t) => t.target === target)
+
+/** The target's entry in the matrix, or `unsupported_platform` with the documented reason. */
+export function checkTarget(target: string): Result<SupportedTarget> {
+  const supported = supportedTarget(target)
+  if (supported) return ok(supported)
+  const known = UNSUPPORTED_TARGETS.find((t) => t.target === target)
+  return fail("", "unsupported_platform", known ? `${target} is not supported: ${known.reason}` : `${target} is not a supported target (supported: ${SUPPORTED_TARGETS.map((t) => t.target).join(", ")})`)
+}