@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/src/bootstrap/adapters/claude/adapter.ts

@@ -0,0 +1,250 @@
+// The Claude Code HarnessAdapter (contracts §3.10): a pure planner over the discovery snapshot and the verified hub
+// manifest, discovery of the claude binary through the read-only DiscoveryProbe, and verification through real
+// probes (verify.ts). It never gets a shell.
+//
+// Plan (in planSetup's phase order):
+//   install-harness         the artifact hub's signed manifest pins for this target, into its own immutable
+//                           directory data:hub/harnesses/claude-code/<version> (downgrade policy: decideHarnessInstall)
+//   select-harness-version  makes that version current (rollback: the previous version is current again)
+//   merge-config            hub's own config:hub/claude-code.json gets {"binary": <current/claude>}, the one
+//                           hub-owned entry that points the existing spoke (daemon, `hub claude`, the plugin it
+//                           writes) at the hub-installed binary. Created by hub, so a rollback removes it; a
+//                           symlinked hub config dir becomes a manual edit (planSetup).
+//   verify-harness          version-exec, provider-auth, spoke-connected (install is never readiness)
+//
+// ~/.claude and ~/.claude.json are never planned: the existing integration loads the hub plugin with --plugin-dir
+// and never edits the user's Claude Code files (docs/harnesses.md). A Claude Code the user installed themselves is
+// kept and only verified, unless the caller prefers a hub-managed install.
+import {
+  checkHarnessPin,
+  decideHarnessInstall,
+  executionContextOf,
+  fail,
+  harnessCurrentRef,
+  harnessVersionRef,
+  ok,
+  REQUIRED_PROBES,
+  resolvePathRef,
+  rootPathIn,
+  type Action,
+  type DiscoverySnapshot,
+  type ExecutionContext,
+  type HarnessAdapter,
+  type HarnessPresence,
+  type InstallHarness,
+  type MergeConfig,
+  type PathRef,
+  type PlanInput,
+  type Precondition,
+  type Result,
+  type RootMapping,
+  type SelectHarnessVersion,
+  type VerifiedManifest,
+  type VerifyHarness,
+} from "../../contracts/index.ts"
+import { classifyExecutable, HARNESS_BINARIES, installOf, pathDirs, which } from "../../discovery/executables.ts"
+import { discoverRoots } from "../../discovery/host.ts"
+import type { DiscoveryProbe } from "../../discovery/probe.ts"
+import type { ProbeRunner } from "./ports.ts"
+import { verifyClaude, type ClaudeBinary, type ClaudeProbes } from "./verify.ts"
+
+const HARNESS = "claude-code" as const
+const BINARY = HARNESS_BINARIES[HARNESS]
+
+/** Hub's own Claude Code integration config (hub-owned; never a Claude Code file). */
+export const CLAUDE_CONFIG_REF: PathRef = Object.freeze({ root: "config", rel: "hub/claude-code.json" })
+/** The key in it naming the claude binary the spoke runs. */
+export const CLAUDE_CONFIG_POINTER = "/binary"
+/** The hub-installed binary, inside the `current` link. */
+export const currentBinaryRel = `${harnessCurrentRef(HARNESS).rel}/${BINARY}`
+
+export type ClaudeDecision = "none" | "user-managed" | "keep" | "select" | "install" | "upgrade" | "downgrade"
+
+export interface ClaudePlan {
+  readonly decision: ClaudeDecision
+  readonly actions: readonly Action[]
+}
+
+export interface ClaudeAdapterOptions {
+  /** The hub release manifest, verified against the shipped trust root. Without it nothing is installed. */
+  readonly manifest?: VerifiedManifest
+  /** What hub installed before, from the history (installedHarnesses). */
+  readonly installed?: { readonly version: string; readonly sha256: string }
+  /** The highest Claude Code floor this machine has seen. */
+  readonly floor?: string
+  /** Explicit --allow-downgrade. */
+  readonly allowDowngrade?: boolean
+  /** existing (default): keep a Claude Code the user installed; hub: install the pinned one beside it. */
+  readonly prefer?: "existing" | "hub"
+  /** The state of a config file discovery does not record (config:hub/claude-code.json), by its path. */
+  readonly configState?: (path: string) => Precondition | undefined
+  /** Read-only host access for discover() and the binary readiness runs against. */
+  readonly probe?: DiscoveryProbe
+  /** The roots (default: discovered through the probe) and where hubctl runs (default host). */
+  readonly roots?: readonly RootMapping[]
+  readonly context?: ExecutionContext
+  /** Real probes (verify.ts); without a runner nothing can be verified. */
+  readonly probes?: { readonly runner: ProbeRunner } & Pick<ClaudeProbes, "spoke" | "conformance">
+}
+
+const VERB = { install: "Install", upgrade: "Upgrade", downgrade: "Downgrade" } as const
+
+const verifyAction = (): VerifyHarness => ({
+  id: `verify-${HARNESS}`,
+  kind: "verify-harness",
+  escalation: "user",
+  summary: "Verify Claude Code runs, is logged in, and its spoke connects to the hub",
+  harness: HARNESS,
+  probes: REQUIRED_PROBES[HARNESS].filter((p): p is Exclude<typeof p, "presence"> => p !== "presence"),
+})
+
+function selectAction(version: string, previous?: { readonly version: string; readonly sha256: string }): SelectHarnessVersion {
+  return {
+    id: `select-${HARNESS}`,
+    kind: "select-harness-version",
+    escalation: "user",
+    summary: `Make Claude Code ${version} the current version`,
+    harness: HARNESS,
+    version,
+    path: harnessCurrentRef(HARNESS),
+    target: harnessVersionRef(HARNESS, version),
+    ...(previous ? { previous: { ...previous } } : {}),
+  }
+}
+
+/** Where a root is for the context the plan runs in. */
+function rootPath(snapshot: DiscoverySnapshot, id: string): string | undefined {
+  const root = snapshot.roots.find((r) => r.id === id)
+  return root ? rootPathIn(root, executionContextOf(snapshot)) : undefined
+}
+
+function configAction(snapshot: DiscoverySnapshot, options: ClaudeAdapterOptions): Result<MergeConfig> {
+  const data = rootPath(snapshot, "data")
+  const where = resolvePathRef(CLAUDE_CONFIG_REF, snapshot.roots, executionContextOf(snapshot))
+  if (!data || !where.ok) return fail("/roots", "unmapped_root", "this host has no data or config root for the hub-installed Claude Code")
+  const known = snapshot.configs.find((c) => c.path === where.value)
+  const precondition: Precondition = known ? (known.sha256 ? { exists: true, sha256: known.sha256 } : { exists: false }) : (options.configState?.(where.value) ?? { exists: false })
+  return ok({
+    id: `${HARNESS}-config`,
+    kind: "merge-config",
+    escalation: "user",
+    summary: "Point hub's Claude Code spoke at the hub-installed claude",
+    path: CLAUDE_CONFIG_REF,
+    format: "json",
+    owner: "hub",
+    precondition,
+    set: [{ pointer: CLAUDE_CONFIG_POINTER, value: `${data}/${currentBinaryRel}` }],
+    preserveUnknown: true,
+  })
+}
+
+/** Plans Claude Code for this snapshot and profile, with the reason when it cannot. Pure and deterministic. */
+export function planClaude(input: PlanInput, options: ClaudeAdapterOptions): Result<ClaudePlan> {
+  const { snapshot, profile } = input
+  if (!profile.harnesses.includes(HARNESS)) return ok({ decision: "none", actions: [] })
+  const presence = snapshot.harnesses.find((h) => h.id === HARNESS)
+  const verify = verifyAction()
+  if (presence?.installed && presence.installMethod !== "hub" && options.prefer !== "hub") return ok({ decision: "user-managed", actions: [verify] })
+  const target = snapshot.host.target
+  const manifest = options.manifest
+  const pin = manifest?.harnesses.find((p) => p.harness === HARNESS && p.target === target)
+  if (!manifest || !pin) return fail("/harnesses/claude-code", "unpinned_artifact", manifest ? `hub ${manifest.release} pins no Claude Code for ${target}` : "no verified hub manifest to install Claude Code from")
+  const decided = decideHarnessInstall(pin, { ...(options.installed ? { installed: options.installed } : {}), ...(options.floor ? { floor: options.floor } : {}), allowDowngrade: options.allowDowngrade })
+  if (!decided.ok) return decided
+  const config = configAction(snapshot, options)
+  if (!config.ok) return config
+  const currentIsPinned = presence?.installed === true && presence.installMethod === "hub" && presence.version === pin.version
+  if (decided.value === "reinstall" || (currentIsPinned && !options.installed)) {
+    if (currentIsPinned) return ok({ decision: "keep", actions: [verify] })
+    return ok({ decision: "select", actions: [selectAction(pin.version), config.value, verify] })
+  }
+  const previous = options.installed
+  const install: InstallHarness = {
+    id: `install-${HARNESS}`,
+    kind: "install-harness",
+    escalation: "user",
+    summary: `${VERB[decided.value]} Claude Code ${pin.version} for ${pin.target} (pinned by hub ${manifest.release})`,
+    harness: HARNESS,
+    version: pin.version,
+    target: pin.target,
+    source: { manifest: manifest.release, url: pin.url, file: pin.file },
+    size: pin.size,
+    sha256: pin.sha256,
+    evidence: [...pin.evidence],
+    path: harnessVersionRef(HARNESS, pin.version),
+    owner: "hub",
+    rollback: "restore-previous",
+    ...(previous ? { previous: { ...previous } } : {}),
+  }
+  const pinned = checkHarnessPin(manifest, install)
+  if (!pinned.ok) return pinned
+  return ok({ decision: decided.value, actions: [install, selectAction(pin.version, previous), config.value, verify] })
+}
+
+export interface ClaudeAdapter extends HarnessAdapter {
+  /** The binary readiness runs against (hub's current version, else the program `claude` on PATH resolves to). */
+  binary(): ClaudeBinary
+}
+
+export function createClaudeAdapter(options: ClaudeAdapterOptions): ClaudeAdapter {
+  const context = options.context ?? "host"
+  const roots = (): readonly RootMapping[] => options.roots ?? (options.probe ? (discoverRoots(options.probe) ?? []) : [])
+  const at = (id: string) => {
+    const r = roots().find((x) => x.id === id)
+    return r ? rootPathIn(r, context) : undefined
+  }
+  const current = () => {
+    const data = at("data")
+    return data ? `${data}/${currentBinaryRel}` : undefined
+  }
+
+  /** `claude` on PATH (or in upstream's own install directories), as discovery finds it. */
+  const onPath = (probe: DiscoveryProbe, home: string) => {
+    const dirs = pathDirs(probe)
+    const known = [`${home}/.local/bin`, `${home}/.claude/local`].filter((d) => !dirs.includes(d))
+    const path = which(probe, [...dirs, ...known], BINARY)
+    return path ? classifyExecutable(probe, BINARY, path) : undefined
+  }
+
+  const adapter: ClaudeAdapter = {
+    id: HARNESS,
+    async discover(ctx): Promise<HarnessPresence> {
+      const none: HarnessPresence = { id: HARNESS, installed: false, health: { state: "unverified", probes: [] } }
+      const probe = options.probe
+      if (!probe) return none
+      const home = at("home") ?? ctx.home
+      const shim = onPath(probe, home)
+      const hub = current()
+      const found = shim ?? (hub && probe.executable(hub) ? classifyExecutable(probe, BINARY, hub) : undefined)
+      if (!found) return none
+      const install = installOf(probe, HARNESS, found, roots(), context)
+      return { id: HARNESS, installed: true, path: found.path, ...(install.version ? { version: install.version } : {}), installMethod: install.installMethod, health: { state: "unverified", probes: [] } }
+    },
+    plan(input) {
+      const planned = planClaude(input, options)
+      // Unplannable (unpinned, refused downgrade): verify only, so the setup reports Claude Code as not ready.
+      return planned.ok ? planned.value.actions : input.profile.harnesses.includes(HARNESS) ? [verifyAction()] : []
+    },
+    async verify(ctx) {
+      const probes = options.probes
+      if (!probes) return verifyClaude({ runner: { run: async () => ({ kind: "error", message: "no runner" }) }, binary: () => ({ problem: "this hubctl has no probe runner" }) }, ctx)
+      return verifyClaude({ ...probes, binary: () => adapter.binary() }, ctx)
+    },
+    binary(): ClaudeBinary {
+      const probe = options.probe
+      if (!probe) return { problem: "no read-only host probe to find claude" }
+      const hub = current()
+      if (hub && probe.executable(hub)) {
+        const version = installOf(probe, HARNESS, classifyExecutable(probe, BINARY, hub), roots(), context).version
+        return { path: hub, ...(version ? { version } : {}) }
+      }
+      const shim = onPath(probe, at("home") ?? probe.home)
+      if (!shim) return { problem: "Claude Code is not installed (no claude on PATH or in hub's harness directory)" }
+      if (shim.kind === "container-shim") return { problem: `${shim.path} is a shim into a container; readiness is checked against a binary on this host` }
+      const path = shim.resolvesTo ?? shim.path
+      const version = installOf(probe, HARNESS, shim, roots(), context).version
+      return { path, ...(version ? { version } : {}) }
+    },
+  }
+  return adapter
+}

package/packages/cli/src/bootstrap/adapters/claude/index.ts

@@ -0,0 +1,42 @@
+// The Claude Code bootstrap adapter (HBS-08): planning and discovery (adapter.ts), the pinned-artifact source with
+// optional upstream evidence (source.ts, openpgp.ts), real readiness probes (verify.ts), and the injected ports
+// (ports.ts) with their default Node implementations (node.ts). Integration into the CLI is HBS-13's.
+import type { HarnessVerification } from "../../contracts/index.ts"
+import { installHarnessExecutor, type HarnessSource } from "../../transaction/builtin.ts"
+import type { ActionExecutor } from "../../transaction/executor.ts"
+import type { ReadinessGate } from "../readiness.ts"
+import { claudeVerifyExecutor } from "./verify.ts"
+
+export * from "./adapter.ts"
+export * from "./node.ts"
+export * from "./openpgp.ts"
+export * from "./ports.ts"
+export * from "./source.ts"
+export * from "./verify.ts"
+
+export interface ClaudeExecutorOptions extends ReadinessGate {
+  /** createClaudeHarnessSource(...) */
+  readonly source: HarnessSource
+  /** adapter.verify(context) */
+  readonly verify: () => Promise<HarnessVerification>
+  readonly now: () => number
+  readonly onVerified?: (verification: HarnessVerification) => void
+}
+
+/**
+ * The executors the Claude Code plan needs beyond the built-in local ones: install-harness from the Claude Code
+ * source, and verify-harness for claude-code. The engine has one executor per kind, so with several harnesses the
+ * integrator dispatches these by `action.harness` (HBS-13).
+ */
+export function claudeExecutors(options: ClaudeExecutorOptions): { readonly "install-harness": ActionExecutor<"install-harness">; readonly "verify-harness": ActionExecutor<"verify-harness"> } {
+  return {
+    "install-harness": installHarnessExecutor(options.source),
+    "verify-harness": claudeVerifyExecutor({
+      verify: options.verify,
+      now: options.now,
+      ...(options.onVerified ? { onVerified: options.onVerified } : {}),
+      ...(options.requireReady !== undefined ? { requireReady: options.requireReady } : {}),
+      ...(options.onReadiness ? { onReadiness: options.onReadiness } : {}),
+    }),
+  }
+}

package/packages/cli/src/bootstrap/adapters/claude/node.ts

@@ -0,0 +1,99 @@
+// Default Node implementations of the Claude Code adapter's ports (ports.ts). The integrator (HBS-13) passes them;
+// tests inject fakes.
+//
+//   nodeRunner       spawn(file, args) with shell: false, exactly the given environment, stdin closed, stderr
+//                    dropped, stdout capped, and a hard timeout (SIGKILL). The only process starter here.
+//   httpsDownloader  https only (also after redirects), non-2xx refused, the body streamed and capped
+//                    (DownloadTooLarge, as soon as it runs past the limit).
+//   tempScratch      a 0700 directory under the system temp dir with one 0600 file (written as its content
+//                    streams), removed afterwards.
+import { spawn } from "node:child_process"
+import { closeSync, mkdtempSync, openSync, rmSync, writeSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { chunksOf, responseChunks } from "../../transaction/stream.ts"
+import { DownloadTooLarge, type Downloader, type ProbeRunner, type RunResult, type Scratch } from "./ports.ts"
+
+export function nodeRunner(): ProbeRunner {
+  return {
+    run: (file, args, options) =>
+      new Promise<RunResult>((resolve) => {
+        let settled = false
+        const done = (r: RunResult) => {
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          resolve(r)
+        }
+        let child: ReturnType<typeof spawn>
+        try {
+          child = spawn(file, [...args], { shell: false, env: { ...options.env }, stdio: ["ignore", "pipe", "ignore"], windowsHide: true })
+        } catch (error) {
+          return resolve({ kind: "error", message: error instanceof Error ? error.message : String(error) })
+        }
+        const timer = setTimeout(() => {
+          child.kill("SIGKILL")
+          done({ kind: "timeout" })
+        }, options.timeoutMs)
+        const chunks: Buffer[] = []
+        let size = 0
+        child.stdout?.on("data", (chunk: Buffer) => {
+          if (size >= options.maxOutputBytes) return
+          const part = chunk.subarray(0, options.maxOutputBytes - size)
+          chunks.push(part)
+          size += part.length
+        })
+        child.on("error", (error: NodeJS.ErrnoException) => done(error.code === "ENOENT" ? { kind: "not-found" } : { kind: "error", message: error.code ?? "spawn failed" }))
+        // Settle once the process exited and its stdout ended (whichever comes last), or on "close".
+        let exitCode: number | undefined
+        let ended = !child.stdout
+        const finish = () => {
+          if (exitCode !== undefined && ended) done({ kind: "exited", code: exitCode, stdout: Buffer.concat(chunks).toString("utf8") })
+        }
+        child.stdout?.on("end", () => ((ended = true), finish()))
+        child.stdout?.on("close", () => ((ended = true), finish()))
+        child.on("exit", (code, signal) => ((exitCode = code ?? (signal ? -1 : 0)), finish()))
+        child.on("close", (code) => ((exitCode ??= code ?? -1), (ended = true), finish()))
+      }),
+  }
+}
+
+export interface DownloaderOptions {
+  /** The fetch implementation (default: the global fetch). */
+  readonly fetch?: (url: string, init: RequestInit) => Promise<Response>
+}
+
+export function httpsDownloader(options: DownloaderOptions = {}): Downloader {
+  const doFetch = options.fetch ?? ((url: string, init: RequestInit) => fetch(url, init))
+  return {
+    async get(url, maxBytes) {
+      if (!url.startsWith("https://")) throw new Error(`refusing a non-https download: ${url}`)
+      const response = await doFetch(url, { redirect: "follow" })
+      if (response.url && !response.url.startsWith("https://")) throw new Error(`${url} redirected away from https`)
+      if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`)
+      const declared = Number(response.headers.get("content-length") ?? NaN)
+      if (Number.isFinite(declared) && declared > maxBytes) throw new DownloadTooLarge(url, maxBytes)
+      return responseChunks(response, maxBytes, () => new DownloadTooLarge(url, maxBytes))
+    },
+  }
+}
+
+export function tempScratch(base: string = tmpdir()): Scratch {
+  return {
+    async withFile(content, use) {
+      const dir = mkdtempSync(join(base, "hubctl-claude-"))
+      try {
+        const file = join(dir, "claude")
+        const fd = openSync(file, "wx", 0o600)
+        try {
+          for await (const chunk of chunksOf(content)) for (let at = 0; at < chunk.byteLength; ) at += writeSync(fd, chunk, at)
+        } finally {
+          closeSync(fd)
+        }
+        return await use(file)
+      } finally {
+        rmSync(dir, { recursive: true, force: true })
+      }
+    },
+  }
+}

package/packages/cli/src/bootstrap/adapters/claude/openpgp.ts

@@ -0,0 +1,221 @@
+// An in-house check of one OpenPGP detached signature (RFC 4880 v4, RSA), enough to verify Claude Code's signed
+// per-release manifest.json without a hard dependency on gpg (contracts §5, decision Q3). It is deliberately
+// narrow: a v4 RSA public key pinned by its fingerprint, a v4 binary-document signature, SHA-2 hashes. Every
+// outcome is one of
+//   verified     the pinned key signed exactly these bytes;
+//   unavailable  this check cannot vouch either way (another or unpinned key, a format this verifier does not
+//                read): recorded, never a pass;
+//   failed       checked and wrong (a bad signature in the pinned key's name, a malformed signature packet).
+// It never throws, and its detail is one short line with no input bytes in it.
+import { createHash, createPublicKey, constants, verify, type KeyObject } from "node:crypto"
+
+/** Anthropic's Claude Code release-signing key (upstream docs: `gpg --fingerprint security@anthropic.com`). */
+export const CLAUDE_SIGNING_FINGERPRINT = "31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE"
+
+export interface PgpOutcome {
+  readonly status: "verified" | "unavailable" | "failed"
+  readonly detail: string
+}
+
+export interface DetachedSignatureInput {
+  /** The signed bytes (manifest.json, exactly as downloaded). */
+  readonly data: Uint8Array
+  /** The detached signature, ASCII-armored or binary. */
+  readonly signature: string | Uint8Array
+  /** The signer's transferable public key, ASCII-armored or binary. */
+  readonly publicKey: string | Uint8Array
+  /** The pinned v4 fingerprint (40 hex digits) the key must have. */
+  readonly fingerprint: string
+}
+
+class Malformed extends Error {}
+
+const RSA_ALGORITHMS = new Set([1, 2, 3])
+/** OpenPGP hash IDs this verifier accepts (SHA-1 and MD5 are not accepted). */
+const HASHES: Readonly<Record<number, string>> = { 8: "sha256", 9: "sha384", 10: "sha512", 11: "sha224" }
+const BASE64_LINE = /^[A-Za-z0-9+/]*={0,2}$/
+
+const outcome = (status: PgpOutcome["status"], detail: string): PgpOutcome => ({ status, detail: detail.slice(0, 200) })
+
+/** The binary packets of an armored or binary OpenPGP message. */
+function bytesOf(input: string | Uint8Array): Uint8Array {
+  const text = typeof input === "string" ? input : input[0] === 0x2d ? new TextDecoder().decode(input) : undefined
+  if (text === undefined) return input as Uint8Array
+  const lines = text.split(/\r?\n/)
+  let i = lines.findIndex((l) => /^-----BEGIN PGP [A-Z ]+-----$/.test(l.trim()))
+  if (i < 0) throw new Malformed("not an armored OpenPGP block")
+  // Armor headers end at the first blank line.
+  for (i++; i < lines.length && lines[i]!.trim() !== ""; i++) if (!lines[i]!.includes(":")) break
+  if (lines[i]?.trim() === "") i++
+  const body: string[] = []
+  for (; i < lines.length; i++) {
+    const line = lines[i]!.trim()
+    if (line.startsWith("-----END ")) break
+    if (line.startsWith("=") && line.length === 5) continue // the armor checksum
+    if (!BASE64_LINE.test(line)) throw new Malformed("the armor is not base64")
+    body.push(line)
+  }
+  const bytes = Buffer.from(body.join(""), "base64")
+  if (bytes.length === 0) throw new Malformed("the armor is empty")
+  return new Uint8Array(bytes)
+}
+
+interface Packet {
+  readonly tag: number
+  readonly body: Uint8Array
+}
+
+/** Packets (RFC 4880 §4.2), old and new format; partial lengths are not used by keys or signatures. */
+function packets(b: Uint8Array): Packet[] {
+  const out: Packet[] = []
+  let i = 0
+  const need = (n: number) => {
+    if (i + n > b.length) throw new Malformed("a packet is truncated")
+  }
+  while (i < b.length) {
+    const h = b[i]!
+    if (!(h & 0x80)) throw new Malformed("not an OpenPGP packet")
+    let tag: number
+    let len: number
+    let head: number
+    if (h & 0x40) {
+      tag = h & 0x3f
+      need(2)
+      const o = b[i + 1]!
+      if (o < 192) [len, head] = [o, 2]
+      else if (o < 224) {
+        need(3)
+        ;[len, head] = [((o - 192) << 8) + b[i + 2]! + 192, 3]
+      } else if (o === 255) {
+        need(6)
+        ;[len, head] = [((b[i + 2]! << 24) >>> 0) + (b[i + 3]! << 16) + (b[i + 4]! << 8) + b[i + 5]!, 6]
+      } else throw new Malformed("partial packet lengths are not used here")
+    } else {
+      tag = (h >> 2) & 0x0f
+      const type = h & 3
+      if (type === 3) throw new Malformed("indeterminate packet lengths are not used here")
+      head = [2, 3, 5][type]!
+      need(head)
+      len = type === 0 ? b[i + 1]! : type === 1 ? (b[i + 1]! << 8) + b[i + 2]! : ((b[i + 1]! << 24) >>> 0) + (b[i + 2]! << 16) + (b[i + 3]! << 8) + b[i + 4]!
+    }
+    need(head + len)
+    out.push({ tag, body: b.subarray(i + head, i + head + len) })
+    i += head + len
+  }
+  return out
+}
+
+/** Reads MPIs from `body` starting at `at`. */
+function mpis(body: Uint8Array, at: number, count: number): { values: Uint8Array[]; end: number } {
+  const values: Uint8Array[] = []
+  let p = at
+  for (let k = 0; k < count; k++) {
+    if (p + 2 > body.length) throw new Malformed("an MPI is truncated")
+    const bytes = Math.ceil(((body[p]! << 8) + body[p + 1]!) / 8)
+    if (bytes === 0 || p + 2 + bytes > body.length) throw new Malformed("an MPI is truncated")
+    values.push(body.subarray(p + 2, p + 2 + bytes))
+    p += 2 + bytes
+  }
+  return { values, end: p }
+}
+
+const hex = (b: Uint8Array) => Buffer.from(b).toString("hex").toUpperCase()
+
+interface PublicKey {
+  readonly fingerprint: string
+  readonly key?: KeyObject
+  readonly modulusBytes: number
+  readonly problem?: string
+}
+
+function readPublicKey(input: string | Uint8Array): PublicKey | undefined {
+  try {
+    const primary = packets(bytesOf(input)).find((p) => p.tag === 6)
+    if (!primary) return undefined
+    const body = primary.body
+    const fingerprint = createHash("sha1")
+      .update(Buffer.concat([Buffer.from([0x99, (body.length >> 8) & 0xff, body.length & 0xff]), body]))
+      .digest("hex")
+      .toUpperCase()
+    if (body[0] !== 4) return { fingerprint, modulusBytes: 0, problem: `a v${body[0]} key is not supported` }
+    if (body.length < 6) throw new Malformed("the key is truncated")
+    if (!RSA_ALGORITHMS.has(body[5]!)) return { fingerprint, modulusBytes: 0, problem: `key algorithm ${body[5]} is not supported (RSA only)` }
+    const [n, e] = mpis(body, 6, 2).values as [Uint8Array, Uint8Array]
+    const key = createPublicKey({ key: { kty: "RSA", n: Buffer.from(n).toString("base64url"), e: Buffer.from(e).toString("base64url") }, format: "jwk" })
+    return { fingerprint, key, modulusBytes: n.length }
+  } catch {
+    return undefined
+  }
+}
+
+/** The v4 fingerprint of a public key (40 hex digits), or undefined when it cannot be read. */
+export function publicKeyFingerprint(input: string | Uint8Array): string | undefined {
+  return readPublicKey(input)?.fingerprint
+}
+
+/** Issuer fingerprint (33) and issuer key ID (16) subpackets. */
+function issuers(area: Uint8Array): { fingerprint?: string; keyID?: string } {
+  const found: { fingerprint?: string; keyID?: string } = {}
+  let r = 0
+  while (r < area.length) {
+    let len = area[r]!
+    let o = 1
+    if (len >= 192 && len < 255) {
+      if (r + 1 >= area.length) throw new Malformed("a subpacket is truncated")
+      len = ((len - 192) << 8) + area[r + 1]! + 192
+      o = 2
+    } else if (len === 255) {
+      if (r + 5 > area.length) throw new Malformed("a subpacket is truncated")
+      len = ((area[r + 1]! << 24) >>> 0) + (area[r + 2]! << 16) + (area[r + 3]! << 8) + area[r + 4]!
+      o = 5
+    }
+    if (len < 1 || r + o + len > area.length) throw new Malformed("a subpacket is truncated")
+    const type = area[r + o]! & 0x7f
+    const value = area.subarray(r + o + 1, r + o + len)
+    if (type === 33 && value[0] === 4 && value.length === 21) found.fingerprint = hex(value.subarray(1))
+    if (type === 16 && value.length === 8) found.keyID = hex(value)
+    r += o + len
+  }
+  return found
+}
+
+/** Verifies a detached signature over `data` by the pinned key. */
+export function verifyDetachedSignature(input: DetachedSignatureInput): PgpOutcome {
+  const pinned = input.fingerprint.replace(/\s+/g, "").toUpperCase()
+  const key = readPublicKey(input.publicKey)
+  if (!key) return outcome("unavailable", "the published signing key cannot be read")
+  if (key.fingerprint !== pinned) return outcome("unavailable", `the published signing key ${key.fingerprint} is not the pinned key ${pinned}`)
+  if (!key.key) return outcome("unavailable", `the signing key cannot be used here: ${key.problem}`)
+  try {
+    const sig = packets(bytesOf(input.signature)).find((p) => p.tag === 2)?.body
+    if (!sig) throw new Malformed("no signature packet")
+    if (sig[0] !== 4) return outcome("unavailable", `a v${sig[0]} signature is not supported`)
+    if (sig.length < 6) throw new Malformed("the signature is truncated")
+    const [, type, algorithm, hashID] = sig as unknown as [number, number, number, number]
+    const hashedLen = (sig[4]! << 8) + sig[5]!
+    if (6 + hashedLen + 2 > sig.length) throw new Malformed("the signature is truncated")
+    const hashed = sig.subarray(6, 6 + hashedLen)
+    const unhashedLen = (sig[6 + hashedLen]! << 8) + sig[7 + hashedLen]!
+    const unhashedAt = 8 + hashedLen
+    if (unhashedAt + unhashedLen + 2 > sig.length) throw new Malformed("the signature is truncated")
+    const unhashed = sig.subarray(unhashedAt, unhashedAt + unhashedLen)
+    const [value] = mpis(sig, unhashedAt + unhashedLen + 2, 1).values as [Uint8Array]
+    if (type !== 0x00) return outcome("unavailable", `signature type 0x${type.toString(16).padStart(2, "0")} is not supported (binary documents only)`)
+    if (!RSA_ALGORITHMS.has(algorithm)) return outcome("unavailable", `signature algorithm ${algorithm} is not supported (RSA only)`)
+    const hash = HASHES[hashID]
+    if (!hash) return outcome("unavailable", `hash algorithm ${hashID} is not accepted`)
+    const ids = { ...issuers(unhashed), ...issuers(hashed) }
+    if (ids.fingerprint && ids.fingerprint !== pinned) return outcome("unavailable", `signed by another key ${ids.fingerprint}`)
+    if (!ids.fingerprint && ids.keyID && ids.keyID !== pinned.slice(-16)) return outcome("unavailable", `signed by another key ${ids.keyID}`)
+    const trailer = Buffer.alloc(6)
+    trailer[0] = 4
+    trailer[1] = 0xff
+    trailer.writeUInt32BE(6 + hashedLen, 2)
+    const signed = Buffer.concat([input.data, sig.subarray(0, 6 + hashedLen), trailer])
+    const padded = Buffer.concat([Buffer.alloc(Math.max(0, key.modulusBytes - value.length)), value])
+    const good = verify(hash, signed, { key: key.key, padding: constants.RSA_PKCS1_PADDING }, padded)
+    return good ? outcome("verified", `good signature by ${pinned}`) : outcome("failed", `the signature by ${pinned} does not match these bytes`)
+  } catch (error) {
+    return outcome("failed", `the signature is malformed: ${error instanceof Malformed ? error.message : "unreadable"}`)
+  }
+}

package/packages/cli/src/bootstrap/adapters/claude/ports.ts

@@ -0,0 +1,44 @@
+// The Claude Code adapter's only ways to reach outside itself, all injected: an https downloader, a fixed-argv
+// process runner (never a shell) and a private scratch file. node.ts has the default implementations; tests
+// inject fakes. Bodies and scratch content are ByteSources: the ~200 MB binary streams, it is never held whole.
+import type { ByteSource } from "../../transaction/stream.ts"
+
+/** Thrown by a Downloader when the body is longer than allowed. */
+export class DownloadTooLarge extends Error {
+  constructor(url: string, maxBytes: number) {
+    super(`${url} is larger than ${maxBytes} bytes`)
+    this.name = "DownloadTooLarge"
+  }
+}
+
+/**
+ * Fetches an https URL's body, refusing more than `maxBytes` (DownloadTooLarge, also while it streams); throws on
+ * any failure. The body is whole (small things, fakes) or chunks as they arrive.
+ */
+export interface Downloader {
+  get(url: string, maxBytes: number): Promise<ByteSource>
+}
+
+/** How a fixed-argv probe ended. `stdout` is the probe's to parse and drop; it is never recorded. */
+export type RunResult =
+  | { readonly kind: "exited"; readonly code: number; readonly stdout: string }
+  | { readonly kind: "not-found" }
+  | { readonly kind: "timeout" }
+  | { readonly kind: "error"; readonly message: string }
+
+export interface RunOptions {
+  /** The child's whole environment (nothing else is inherited). */
+  readonly env: Readonly<Record<string, string>>
+  readonly timeoutMs: number
+  readonly maxOutputBytes: number
+}
+
+/** Runs one program with an argument list (never a shell). The only way this adapter starts a process. */
+export interface ProbeRunner {
+  run(file: string, args: readonly string[], options: RunOptions): Promise<RunResult>
+}
+
+/** A private (0700) scratch copy of some content (written as it streams) for the duration of `use`, removed afterwards. */
+export interface Scratch {
+  withFile<T>(content: ByteSource, use: (path: string) => Promise<T>): Promise<T>
+}