@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/bootstrap/release/cli.ts

@@ -0,0 +1,332 @@
+// The hubctl release tool (`bun scripts/hubctl-release.ts <command>`), used by .github/workflows/release.yml and by
+// maintainers. It is not part of the hub/hubctl command surface.
+//
+//   build [TARGET…] [--outdir dist] [--trust-root FILE] [--require-trust-root]
+//       Compiles packages/cli/src/main.ts into dist/hubctl-<target> for the supported targets (all by default),
+//       embedding the trust root (public keys only). --require-trust-root refuses a build without one.
+//   manifest --minimum-version V --out FILE [--dist dist] [--pins FILE] [--release V] [--issued-at MS] [--targets T,…]
+//       Writes the unsigned manifest body: every dist/hubctl-<target> with its size and sha256, and the reviewed
+//       harness pins after re-downloading and digesting every pinned file.
+//   sign --in FILE --out FILE [--trust-root FILE] [--key-id ID] [--targets T,…]
+//       Signs the body with the key in $HUB_RELEASE_SIGNING_KEY (never printed) and verifies the result against
+//       the trust root the binaries embed. Writes nothing unless it verifies.
+//   verify --manifest FILE [--trust-root FILE] (--dist DIR [--targets T,…] | --target T --file BIN)
+//          [--installed V --installed-sha256 D] [--floor V] [--allow-downgrade]
+//       Runs the installer's checks (verify.ts) on one or every artifact.
+//
+// --targets (comma-separated) makes a partial release: exactly the listed targets, each still required and checked
+// in full. Without it every supported target is required. sign needs the same list to sign a partial body, so a
+// partial release is never signed by accident.
+//   trust-root [--key-id ID]
+//       Prints the v1 trust root (public key only) for the key in $HUB_RELEASE_SIGNING_KEY, for the maintainer
+//       who sets up the release key (README.md next to this file).
+//
+// Exit codes: 0 ok, 1 other, 2 usage, 11 artifact rejected (contracts §3.11).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import pkg from "../../../package.json" with { type: "json" }
+import {
+  BOOTSTRAP_EXIT,
+  SUPPORTED_TARGETS,
+  canonicalJSON,
+  checkTarget,
+  exitFor,
+  isRecord,
+  supportedTarget,
+  type Issue,
+  type Result,
+  type TrustRoot,
+} from "../contracts/index.ts"
+import { buildManifestBody, manifestJSON, parseSigningKey, signVerified, trustRootFor } from "./manifest.ts"
+import { PIN_LIST_FILE, validatePinList, verifyPinDownloads, type Downloader } from "./pins.ts"
+import { shippedTrustRoot, trustRootDefine } from "./trust-root.ts"
+import { digestBytes, parseManifest, verifyHubctlRelease } from "./verify.ts"
+
+/** The environment variable holding the release signing key (a GitHub Actions secret; decision Q5). */
+export const SIGNING_KEY_ENV = "HUB_RELEASE_SIGNING_KEY"
+/** The trust root the release binaries embed, relative to the repository root (checked in once the key exists). */
+export const TRUST_ROOT_FILE = "packages/cli/src/bootstrap/release/trust-root.json"
+/** The program compiled into hubctl (I3). */
+export const HUBCTL_ENTRY = "packages/cli/src/main.ts"
+export const DEFAULT_KEY_ID = "hub-release-1"
+/** The version hubctl --version prints, and the release the manifest names. */
+export const HUBCTL_VERSION: string = pkg.version
+
+export interface ReleaseIo {
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** The repository root; relative paths resolve against it. */
+  readonly cwd: string
+  readonly stdout: (s: string) => void
+  readonly stderr: (s: string) => void
+  /** Runs a word list (no shell) in `cwd`; resolves to its exit code. */
+  readonly run: (argv: string[]) => Promise<number>
+  readonly download: Downloader
+  readonly now: () => number
+}
+
+const EXIT_USAGE = BOOTSTRAP_EXIT.usage
+const EXIT_OTHER = BOOTSTRAP_EXIT.other
+
+class Usage extends Error {}
+class Failure extends Error {
+  constructor(
+    message: string,
+    readonly code: number,
+  ) {
+    super(message)
+  }
+}
+
+interface Parsed {
+  readonly values: Map<string, string>
+  readonly flags: Set<string>
+  readonly positional: string[]
+}
+
+function parseArgs(argv: readonly string[], valued: readonly string[], booleans: readonly string[], positional = false): Parsed {
+  const values = new Map<string, string>()
+  const flags = new Set<string>()
+  const rest: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    const word = argv[i]!
+    if (valued.includes(word)) {
+      const value = argv[++i]
+      if (value === undefined || value.startsWith("--")) throw new Usage(`${word} needs a value`)
+      values.set(word, value)
+    } else if (booleans.includes(word)) flags.add(word)
+    else if (word.startsWith("-") || !positional) throw new Usage(`unknown argument ${word}`)
+    else rest.push(word)
+  }
+  return { values, flags, positional: rest }
+}
+
+const required = (p: Parsed, flag: string): string => {
+  const value = p.values.get(flag)
+  if (value === undefined) throw new Usage(`${flag} is required`)
+  return value
+}
+
+const describe = (issues: readonly Issue[]) => issues.map((i) => `  ${i.code} ${i.path || "/"}: ${i.message}`).join("\n")
+
+/** Throws a Failure carrying the exit code of the first issue. */
+function unwrap<T>(r: Result<T>, what: string): T {
+  if (r.ok) return r.value
+  throw new Failure(`${what}:\n${describe(r.issues)}`, exitFor(r.issues[0]?.code ?? "internal"))
+}
+
+function readJSON(file: string, what: string): unknown {
+  let text: string
+  try {
+    text = readFileSync(file, "utf8")
+  } catch {
+    throw new Failure(`cannot read ${what} ${file}`, EXIT_OTHER)
+  }
+  const r = parseManifest(text)
+  if (!r.ok) throw new Failure(`${what} ${file} is not JSON`, EXIT_OTHER)
+  return r.value
+}
+
+function loadTrustRoot(file: string): TrustRoot {
+  const value = readJSON(file, "trust root")
+  const r = shippedTrustRoot(JSON.stringify(value))
+  if (!r.ok) throw new Failure(`trust root ${file}:\n${describe(r.issues)}`, EXIT_OTHER)
+  return r.value
+}
+
+function signingKey(io: ReleaseIo) {
+  const secret = io.env[SIGNING_KEY_ENV]
+  if (!secret) throw new Usage(`${SIGNING_KEY_ENV} is not set (the release signing key; a GitHub Actions secret)`)
+  try {
+    return parseSigningKey(secret)
+  } catch (error) {
+    throw new Failure((error as Error).message, EXIT_OTHER)
+  }
+}
+
+/** The --targets list: supported targets, each named once; undefined when not given (every supported target). */
+function targetsArg(p: Parsed): string[] | undefined {
+  const text = p.values.get("--targets")
+  if (text === undefined) return undefined
+  const list = text.split(",").map((t) => t.trim())
+  if (list.some((t) => t === "")) throw new Usage("--targets takes a comma-separated list of targets (e.g. linux-x64,darwin-arm64)")
+  for (const target of list) {
+    const r = checkTarget(target)
+    if (!r.ok) throw new Usage(r.issues[0]!.message)
+  }
+  if (new Set(list).size !== list.length) throw new Usage("--targets names a target twice")
+  return SUPPORTED_TARGETS.map((t) => t.target).filter((t) => list.includes(t))
+}
+
+/** The `bun build --compile` words for one target's hubctl. */
+export function hubctlBuildArgv(target: string, options: { readonly bun: string; readonly outdir: string; readonly root?: TrustRoot }): string[] {
+  const t = supportedTarget(target)
+  if (!t) throw new Error(`${target} is not a supported target`)
+  return [
+    options.bun,
+    "build",
+    "--compile",
+    "--minify",
+    "--sourcemap",
+    `--target=${t.bunTarget}`,
+    ...(options.root ? trustRootDefine(options.root) : []),
+    HUBCTL_ENTRY,
+    "--outfile",
+    path.join(options.outdir, `hubctl-${t.target}`),
+  ]
+}
+
+async function build(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const p = parseArgs(argv, ["--outdir", "--trust-root", "--bun"], ["--require-trust-root"], true)
+  const targets = p.positional.length > 0 ? p.positional : SUPPORTED_TARGETS.map((t) => t.target)
+  for (const target of targets) {
+    const r = checkTarget(target)
+    if (!r.ok) throw new Usage(r.issues[0]!.message)
+  }
+  const rootFile = path.resolve(io.cwd, p.values.get("--trust-root") ?? TRUST_ROOT_FILE)
+  let root: TrustRoot | undefined
+  if (existsSync(rootFile)) root = loadTrustRoot(rootFile)
+  else if (p.flags.has("--require-trust-root")) throw new Failure(`no trust root at ${rootFile}: a release build must embed one (see README.md next to ${TRUST_ROOT_FILE})`, EXIT_OTHER)
+  else io.stderr(`warning: no trust root at ${rootFile}; this dev build cannot verify releases\n`)
+  const outdir = path.resolve(io.cwd, p.values.get("--outdir") ?? "dist")
+  mkdirSync(outdir, { recursive: true })
+  const bun = p.values.get("--bun") ?? process.execPath
+  for (const target of targets) {
+    const words = hubctlBuildArgv(target, { bun, outdir, ...(root ? { root } : {}) })
+    io.stderr(`==> ${words.at(-1)}\n`)
+    const code = await io.run(words)
+    if (code !== 0) throw new Failure(`bun build failed for ${target} (exit ${code})`, EXIT_OTHER)
+  }
+  return 0
+}
+
+async function manifest(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const p = parseArgs(argv, ["--dist", "--pins", "--minimum-version", "--release", "--issued-at", "--out", "--targets"], [])
+  const listed = targetsArg(p)
+  const targets = listed ?? SUPPORTED_TARGETS.map((t) => t.target)
+  const minimumVersion = required(p, "--minimum-version")
+  const out = path.resolve(io.cwd, required(p, "--out"))
+  const dist = path.resolve(io.cwd, p.values.get("--dist") ?? "dist")
+  const issuedText = p.values.get("--issued-at")
+  const issuedAt = issuedText === undefined ? io.now() : Number(issuedText)
+  if (!Number.isSafeInteger(issuedAt) || issuedAt < 0) throw new Usage("--issued-at takes milliseconds since the epoch")
+  const pins = unwrap(validatePinList(readJSON(path.resolve(io.cwd, p.values.get("--pins") ?? PIN_LIST_FILE), "pin list")), "the pin list is invalid")
+  const artifacts = targets.map((target) => {
+    const file = `hubctl-${target}`
+    let bytes: Uint8Array
+    try {
+      bytes = readFileSync(path.join(dist, file))
+    } catch {
+      throw new Failure(`missing ${path.join(dist, file)}: build ${listed ? "every listed target" : "every supported target (or name a subset with --targets)"} first`, EXIT_OTHER)
+    }
+    return { target, file, ...digestBytes(bytes) }
+  })
+  io.stderr(`re-downloading ${pins.pins.length} pinned harness file(s)\n`)
+  const harnesses = unwrap(await verifyPinDownloads(pins, io.download), "a pinned harness file does not match its pin")
+  const body = unwrap(
+    buildManifestBody({ release: p.values.get("--release") ?? HUBCTL_VERSION, minimumVersion, issuedAt, artifacts, harnesses, ...(listed ? { targets: listed } : {}) }),
+    "the manifest is invalid",
+  )
+  writeFileSync(out, `${canonicalJSON(body)}\n`)
+  io.stdout(`${out}: hubctl ${body.release} (${body.channel}), ${body.artifacts.length} artifacts (${body.artifacts.map((a) => a.target).join(", ")}), ${body.harnesses.length} harness pins\n`)
+  return 0
+}
+
+async function sign(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const p = parseArgs(argv, ["--in", "--out", "--trust-root", "--key-id", "--targets"], [])
+  const listed = targetsArg(p)
+  const input = path.resolve(io.cwd, required(p, "--in"))
+  const out = path.resolve(io.cwd, required(p, "--out"))
+  const root = loadTrustRoot(path.resolve(io.cwd, p.values.get("--trust-root") ?? TRUST_ROOT_FILE))
+  const body = readJSON(input, "manifest body")
+  if (!isRecord(body) || "signatures" in body) throw new Failure(`${input} is not an unsigned manifest body (it has signatures, or is not an object)`, EXIT_OTHER)
+  const rebuilt = unwrap(
+    buildManifestBody({
+      release: body.release as string,
+      minimumVersion: body.minimumVersion as string,
+      issuedAt: body.issuedAt as number,
+      artifacts: body.artifacts as never,
+      harnesses: body.harnesses as never,
+      ...(listed ? { targets: listed } : {}),
+    }),
+    "the manifest body is invalid (a partial release needs --targets naming its targets)",
+  )
+  if (canonicalJSON(rebuilt) !== canonicalJSON(body)) throw new Failure(`${input} is not a manifest body as \`manifest\` writes it`, EXIT_OTHER)
+  const privateKey = signingKey(io)
+  const active = root.keys.filter((k) => k.status === "active")
+  const keyID = p.values.get("--key-id") ?? (active.length === 1 ? active[0]!.keyID : DEFAULT_KEY_ID)
+  const verified = unwrap(signVerified(rebuilt, { keyID, privateKey }, root), "the signed manifest does not verify against the trust root (is the secret the key the binaries embed?)")
+  writeFileSync(out, manifestJSON(verified))
+  io.stdout(`${out}: signed by ${keyID}, verified against trust root v${root.version}\n`)
+  return 0
+}
+
+async function verify(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const p = parseArgs(argv, ["--manifest", "--trust-root", "--dist", "--target", "--file", "--installed", "--installed-sha256", "--floor", "--targets"], ["--allow-downgrade"])
+  const listed = targetsArg(p)
+  const root = loadTrustRoot(path.resolve(io.cwd, p.values.get("--trust-root") ?? TRUST_ROOT_FILE))
+  const document = readJSON(path.resolve(io.cwd, required(p, "--manifest")), "manifest")
+  const dist = p.values.get("--dist")
+  if (listed && !dist) throw new Usage("--targets goes with --dist")
+  const jobs: { target: string; file: string }[] = dist
+    ? (listed ?? SUPPORTED_TARGETS.map((t) => t.target)).map((target) => ({ target, file: path.resolve(io.cwd, dist, `hubctl-${target}`) }))
+    : [{ target: required(p, "--target"), file: path.resolve(io.cwd, required(p, "--file")) }]
+  const installedVersion = p.values.get("--installed")
+  const installedSha = p.values.get("--installed-sha256")
+  if ((installedVersion === undefined) !== (installedSha === undefined)) throw new Usage("--installed and --installed-sha256 go together")
+  const floor = p.values.get("--floor")
+  for (const job of jobs) {
+    let bytes: Uint8Array
+    try {
+      bytes = readFileSync(job.file)
+    } catch {
+      throw new Failure(`cannot read ${job.file}`, EXIT_OTHER)
+    }
+    const accepted = unwrap(
+      verifyHubctlRelease({
+        manifest: document,
+        root,
+        target: job.target,
+        bytes: digestBytes(bytes),
+        ...(installedVersion !== undefined && installedSha !== undefined ? { installed: { version: installedVersion, sha256: installedSha } } : {}),
+        ...(floor !== undefined ? { floor } : {}),
+        allowDowngrade: p.flags.has("--allow-downgrade"),
+      }),
+      `${job.target}: rejected`,
+    )
+    io.stdout(`ok ${job.target} hubctl ${accepted.manifest.release} ${accepted.kind} ${accepted.artifact.sha256}\n`)
+  }
+  return 0
+}
+
+async function trustRoot(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const p = parseArgs(argv, ["--key-id"], [])
+  io.stdout(`${JSON.stringify(trustRootFor(signingKey(io), p.values.get("--key-id") ?? DEFAULT_KEY_ID), null, 2)}\n`)
+  return 0
+}
+
+const COMMANDS: Record<string, (argv: readonly string[], io: ReleaseIo) => Promise<number>> = { build, manifest, sign, verify, "trust-root": trustRoot }
+
+const USAGE = "usage: hubctl-release <build|manifest|sign|verify|trust-root> [options] (see packages/cli/src/bootstrap/release/cli.ts)\n"
+
+export async function runRelease(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const [name, ...rest] = argv
+  const command = name !== undefined && Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined
+  if (!command) {
+    io.stderr(USAGE)
+    return EXIT_USAGE
+  }
+  try {
+    return await command(rest, io)
+  } catch (error) {
+    if (error instanceof Usage) {
+      io.stderr(`${error.message}\n${USAGE}`)
+      return EXIT_USAGE
+    }
+    if (error instanceof Failure) {
+      io.stderr(`${error.message}\n`)
+      return error.code
+    }
+    io.stderr(`internal error: ${error instanceof Error ? error.message : String(error)}\n`)
+    return EXIT_OTHER
+  }
+}

package/packages/cli/src/bootstrap/release/harness-pins.json

@@ -0,0 +1,94 @@
+{
+  "schema": "hub.harness-pin-list",
+  "version": 1,
+  "pins": [
+    {
+      "pin": {
+        "harness": "opencode",
+        "version": "2.2.0",
+        "target": "darwin-arm64",
+        "url": "https://github.com/anomalyco/opencode/releases/download/v2.2.0/opencode-darwin-arm64.zip",
+        "file": "opencode-darwin-arm64.zip",
+        "size": 102507526,
+        "sha256": "sha256:c71b1cd96541539ad38e2a75377d2f43d2a27567289a14371a182e9a0800db3d",
+        "evidence": [],
+        "minimumVersion": "2.0.0"
+      },
+      "review": {
+        "by": "huynle",
+        "on": "2026-10-30",
+        "checked": [
+          "upstream-release",
+          "digest-redownloaded",
+          "evidence-listed"
+        ]
+      }
+    },
+    {
+      "pin": {
+        "harness": "opencode",
+        "version": "2.2.0",
+        "target": "darwin-x64",
+        "url": "https://github.com/anomalyco/opencode/releases/download/v2.2.0/opencode-darwin-x64-baseline.zip",
+        "file": "opencode-darwin-x64-baseline.zip",
+        "size": 107678258,
+        "sha256": "sha256:bda15562402475e891d39de5938de7ce052a245f9fd926ab72d32f55b1e26ac3",
+        "evidence": [],
+        "minimumVersion": "2.0.0"
+      },
+      "review": {
+        "by": "huynle",
+        "on": "2026-10-30",
+        "checked": [
+          "upstream-release",
+          "digest-redownloaded",
+          "evidence-listed"
+        ]
+      }
+    },
+    {
+      "pin": {
+        "harness": "opencode",
+        "version": "2.2.0",
+        "target": "linux-x64",
+        "url": "https://github.com/anomalyco/opencode/releases/download/v2.2.0/opencode-linux-x64-baseline.tar.gz",
+        "file": "opencode-linux-x64-baseline.tar.gz",
+        "size": 115841183,
+        "sha256": "sha256:6d597970a8cc448f1b9a9f645532584b339dd3ab9583bb5f063f13d83e54768f",
+        "evidence": [],
+        "minimumVersion": "2.0.0"
+      },
+      "review": {
+        "by": "huynle",
+        "on": "2026-10-30",
+        "checked": [
+          "upstream-release",
+          "digest-redownloaded",
+          "evidence-listed"
+        ]
+      }
+    },
+    {
+      "pin": {
+        "harness": "opencode",
+        "version": "2.2.0",
+        "target": "linux-arm64",
+        "url": "https://github.com/anomalyco/opencode/releases/download/v2.2.0/opencode-linux-arm64.tar.gz",
+        "file": "opencode-linux-arm64.tar.gz",
+        "size": 114522206,
+        "sha256": "sha256:1f1ce0fc07b9245a815ffa9d652dbb80e6b0f07e5bf74ea87d2b1c0339fbac52",
+        "evidence": [],
+        "minimumVersion": "2.0.0"
+      },
+      "review": {
+        "by": "huynle",
+        "on": "2026-10-30",
+        "checked": [
+          "upstream-release",
+          "digest-redownloaded",
+          "evidence-listed"
+        ]
+      }
+    }
+  ]
+}

package/packages/cli/src/bootstrap/release/manifest.ts

@@ -0,0 +1,118 @@
+// Building and signing the hubctl release manifest (contracts §3.6, I5, decision Q5).
+//   - The body lists one hubctl artifact for every supported target (in matrix order) and the reviewed harness
+//     pins (pins.ts), so the same inputs always give the same bytes.
+//   - The signature is a detached ed25519 signature over manifestPayload (canonical JSON without `signatures`),
+//     by the single release key (threshold 1), held as a GitHub Actions secret.
+//   - signVerified signs and then verifies with the contract's verifyManifest against the trust root the hubctl
+//     binaries embed: a secret that does not match the shipped root never produces a publishable manifest.
+// Only node:crypto and the contracts are used, so the signing job runs with no npm dependencies installed.
+import { createPrivateKey, createPublicKey, sign, type KeyObject } from "node:crypto"
+import {
+  Checker,
+  SEMVER,
+  SUPPORTED_TARGETS,
+  TRUST_ROOT_SCHEMA,
+  canonicalJSON,
+  manifestPayload,
+  validateArtifactManifest,
+  verifyManifest,
+  type ArtifactManifest,
+  type HarnessPin,
+  type Result,
+  type TrustRoot,
+  type VerifiedManifest,
+} from "../contracts/index.ts"
+
+export type ManifestBody = Omit<ArtifactManifest, "signatures">
+
+export interface ManifestInput {
+  readonly release: string
+  /** The security floor (≤ release). */
+  readonly minimumVersion: string
+  readonly issuedAt: number
+  readonly artifacts: readonly { readonly target: string; readonly file: string; readonly size: number; readonly sha256: string }[]
+  /** The manifest's harness pins (verifyPinDownloads / harnessPins). */
+  readonly harnesses: readonly HarnessPin[]
+  /**
+   * The targets this release ships, listed explicitly (a partial release, e.g. one target for testing): each must
+   * be supported and have exactly one artifact, and no artifact may be for another target. Default: every
+   * supported target.
+   */
+  readonly targets?: readonly string[]
+}
+
+export interface SigningKey {
+  readonly keyID: string
+  readonly privateKey: KeyObject
+}
+
+/** A pre-release (x.y.z-…) goes to `next`, everything else to `stable`. */
+export const channelFor = (release: string): "stable" | "next" => (SEMVER.exec(release)?.[4] ? "next" : "stable")
+
+const ORDER = SUPPORTED_TARGETS.map((t) => t.target)
+const rank = (target: string) => {
+  const i = ORDER.indexOf(target)
+  return i < 0 ? ORDER.length : i
+}
+
+/**
+ * The unsigned manifest for a release: validated, every supported target (or every listed target) present and
+ * nothing else, artifacts in matrix order.
+ */
+export function buildManifestBody(input: ManifestInput): Result<ManifestBody> {
+  const body: ManifestBody = {
+    schema: "hub.artifact-manifest",
+    version: 1,
+    product: "hubctl",
+    release: input.release,
+    channel: channelFor(input.release),
+    minimumVersion: input.minimumVersion,
+    issuedAt: input.issuedAt,
+    artifacts: [...input.artifacts].map(({ target, file, size, sha256 }) => ({ target, file, size, sha256 })).sort((a, b) => rank(a.target) - rank(b.target)),
+    harnesses: [...input.harnesses],
+  }
+  const c = new Checker()
+  c.merge("", validateArtifactManifest({ ...body, signatures: [] }))
+  const targets = input.targets ?? ORDER
+  if (input.targets) {
+    if (targets.length === 0) c.add("/artifacts", "invalid_value", "a release lists at least one target")
+    if (new Set(targets).size !== targets.length) c.add("/artifacts", "duplicate", "a target is listed twice")
+    for (const target of targets) if (!ORDER.includes(target)) c.add("/artifacts", "unsupported_platform", `${target} is not a supported target`)
+    for (const a of body.artifacts) if (ORDER.includes(a.target) && !targets.includes(a.target)) c.add("/artifacts", "inconsistent", `the release has a hubctl for ${a.target}, which is not one of the listed targets (${targets.join(", ")})`)
+  }
+  for (const target of targets) if (!body.artifacts.some((a) => a.target === target)) c.add("/artifacts", "missing_field", `the release has no hubctl for ${target}`)
+  return c.result(body)
+}
+
+/** The release key from the secret's text: PKCS#8 PEM or base64 PKCS#8 DER, ed25519 only. Errors never quote it. */
+export function parseSigningKey(secret: string): KeyObject {
+  const text = secret.trim()
+  let key: KeyObject
+  try {
+    key = text.startsWith("-----BEGIN") ? createPrivateKey({ key: text, format: "pem" }) : createPrivateKey({ key: Buffer.from(text, "base64"), format: "der", type: "pkcs8" })
+  } catch {
+    throw new Error("the release signing key is not a PKCS#8 ed25519 private key (PEM or base64 DER)")
+  }
+  if (key.asymmetricKeyType !== "ed25519") throw new Error(`the release signing key must be ed25519, not ${key.asymmetricKeyType ?? "unknown"}`)
+  return key
+}
+
+/** Adds the detached ed25519 signature over manifestPayload. */
+export function signManifest(body: ManifestBody, key: SigningKey): ArtifactManifest {
+  const value = sign(null, Buffer.from(manifestPayload(body), "utf8"), key.privateKey).toString("base64")
+  return { ...body, signatures: [{ keyID: key.keyID, algorithm: "ed25519", value }] }
+}
+
+/** Signs, then verifies against the shipped trust root; a key the root does not list never yields a manifest. */
+export function signVerified(body: ManifestBody, key: SigningKey, root: TrustRoot): Result<VerifiedManifest> {
+  return verifyManifest(signManifest(body, key), root)
+}
+
+/** The v1 trust root (one active key, threshold 1) for the public half of a release key. */
+export function trustRootFor(privateKey: KeyObject, keyID: string): TrustRoot {
+  const publicKey = createPublicKey(privateKey).export({ format: "der", type: "spki" }).toString("base64")
+  return { schema: TRUST_ROOT_SCHEMA, version: 1, threshold: 1, keys: [{ keyID, algorithm: "ed25519", publicKey, status: "active" }] }
+}
+
+/** The bytes published as hubctl-manifest.json. */
+export const manifestJSON = (manifest: ArtifactManifest): string => `${canonicalJSON(manifest)}\n`