@chrischall/mcp-host-cli 0.0.0-stage → 2.33.1

package/src/lib.mjs

@@ -0,0 +1,654 @@
+// Pure helpers for the mcp-host CLI — kept separate from the entry so tests
+// import them without executing main().
+
+import { createHmac } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * @param {string} spec e.g. "setlist-mcp", "setlist-mcp@1.2.3", "@scope/pkg@latest"
+ * @returns {{ type: 'npm', pkg: string, version?: string }}
+ */
+export function parseNpmSpec(spec) {
+  const at = spec.lastIndexOf('@');
+  if (at > 0) {
+    return { type: 'npm', pkg: spec.slice(0, at), version: spec.slice(at + 1) };
+  }
+  return { type: 'npm', pkg: spec };
+}
+
+/**
+ * A PyPI project, spelled the way pip spells one: `pkg` or `pkg==version`
+ * (docs/PYPI-SOURCE.md). `==` rather than npm's `@`, because that is the
+ * separator a person reading Python packaging has in their hands — and because
+ * a PEP 440 version legitimately contains no `@` to disambiguate against.
+ *
+ * The NAME is normalised here (PEP 503: lower case, runs of `-`, `_` and `.`
+ * collapsed to one `-`), so `mcp-host register --pypi MarkItDown-MCP` works.
+ * The API refuses a non-normalised name outright, for a reason that would
+ * otherwise land on a person as an unexplained 3xx from PyPI: the JSON API
+ * answers a non-canonical name with a 301 and every pinning fetch refuses
+ * redirects. Normalising in the CLI is a convenience over that refusal, never a
+ * replacement for it.
+ *
+ * @param {string} spec e.g. "markitdown-mcp", "markitdown-mcp==0.0.1a4"
+ * @returns {{ type: 'pypi', pkg: string, version?: string }}
+ */
+export function parsePypiSpec(spec) {
+  const at = spec.indexOf('==');
+  const rawPkg = at > 0 ? spec.slice(0, at) : spec;
+  const version = at > 0 ? spec.slice(at + 2) : undefined;
+  const pkg = rawPkg.trim().replace(/[-_.]+/g, '-').toLowerCase();
+  if (pkg === '' || version === '') {
+    throw new Error(`--pypi expects <pkg> or <pkg>==<version>, got ${JSON.stringify(spec)}`);
+  }
+  return { type: 'pypi', pkg, ...(version !== undefined ? { version } : {}) };
+}
+
+/**
+ * @param {string} spec e.g. "owner/repo", "owner/repo#main", "owner/repo#<sha>"
+ * @returns {{ type: 'github', repo: string, ref?: string, commit?: string }}
+ */
+export function parseGithubSpec(spec) {
+  const [repo, ref] = spec.split('#');
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo ?? '')) {
+    throw new Error(`--github expects owner/repo[#ref], got ${JSON.stringify(spec)}`);
+  }
+  const out = { type: 'github', repo };
+  if (ref) {
+    if (/^[0-9a-f]{40}$/.test(ref)) out.commit = ref;
+    else out.ref = ref;
+  }
+  return out;
+}
+
+/** The three spellings `--mcpb` takes, quoted in the usage line and in every refusal. */
+export const MCPB_USAGE = '--mcpb <path|https-url|sha256:hex>';
+
+/**
+ * `--mcpb <spec>`: WHICH of the three things it names, decided here and
+ * nowhere else so `register`, `preview` and the wizard cannot read one
+ * spelling three ways.
+ *
+ * Judged in this order, because the forms overlap: an `https://` URL first
+ * (nothing on disk is named that); then a file that EXISTS, checked before
+ * the hash shapes so a bundle saved under its own hash as a filename is
+ * still the file; then `sha256:<64hex>` or a bare 64-hex, which names a
+ * bundle already uploaded (`mcp-host bundles upload` prints it). `http://`
+ * is refused rather than passed on: the gateway's input schema refuses it
+ * too, and the CLI's sentence can say "https" where a 400 says "invalid".
+ *
+ * Nothing is READ here: a path is only checked for existence, so the parser
+ * stays pure enough to test with an injected `exists` and the upload stays
+ * the one place the bytes are touched.
+ *
+ * @param {string} spec
+ * @param {(file: string) => boolean} exists
+ * @returns {{kind:'url', url:string} | {kind:'path', path:string} | {kind:'sha256', sha256:string}}
+ */
+export function parseMcpbSpec(spec, exists = existsSync) {
+  if (!spec) throw new Error(`${MCPB_USAGE} names nothing`);
+  if (spec.startsWith('https://')) return { kind: 'url', url: spec };
+  if (spec.startsWith('http://')) throw new Error(`--mcpb: a bundle URL must be https, got ${JSON.stringify(spec)}`);
+  if (exists(spec)) return { kind: 'path', path: spec };
+  if (spec.startsWith('sha256:')) {
+    const hex = spec.slice('sha256:'.length);
+    if (!/^[0-9a-f]{64}$/.test(hex)) throw new Error(`--mcpb sha256: expected 64 hex characters (lower-case sha256), got ${JSON.stringify(hex)}`);
+    return { kind: 'sha256', sha256: hex };
+  }
+  if (/^[0-9a-f]{64}$/.test(spec)) return { kind: 'sha256', sha256: spec };
+  throw new Error(`--mcpb: no such file ${spec} (a bundle is a .mcpb on disk, an https:// URL, or sha256:<hex> of one already uploaded)`);
+}
+
+/** The one spelling of the flag, quoted in the refusal it is the way out of. */
+export const INSECURE_FLAG = '--insecure';
+
+/**
+ * Is `MCP_HOST_URL` somewhere the deployment's admin bearer may be sent?
+ *
+ * Every request this CLI makes carries `Authorization: Bearer
+ * <MCP_HOST_ADMIN_TOKEN>`, the break-glass credential for the whole
+ * deployment, so the URL's SCHEME decides whether that credential crosses the
+ * wire in clear. An `http://` gateway — a typo, or a captive portal answering
+ * for one — hands it to anyone on the path, and the 301 to https a real
+ * gateway then sends is too late: the first request already carried it (beta
+ * review 2026-09-10, admin-ui-cli LOW-3).
+ *
+ * `localhost` is NOT special-cased, deliberately. A loopback exception is read
+ * off the HOST, and the host is the part an attacker chooses — a name
+ * resolving to 127.0.0.1 is one DNS record — so the exception would be a
+ * shape the tool trusts rather than a decision somebody made. `--insecure` is
+ * the one way out, and it is what a development gateway on
+ * `http://localhost:8787` passes: a statement per invocation.
+ *
+ * Returns the sentence to refuse with, or null to go ahead.
+ *
+ * @param {string} base the gateway URL, trailing slash already stripped
+ * @param {boolean} insecure was `--insecure` passed
+ * @returns {string | null}
+ */
+export function insecureGatewayRefusal(base, insecure) {
+  let url;
+  try {
+    url = new URL(base);
+  } catch {
+    return `MCP_HOST_URL is not a URL: ${JSON.stringify(base)} (expected https://<host>)`;
+  }
+  if (url.protocol === 'https:') return null;
+  if (url.protocol !== 'http:') {
+    return `MCP_HOST_URL must be an https:// URL, got ${url.protocol}// — the admin token is sent to whatever it names`;
+  }
+  if (insecure) return null;
+  return (
+    `MCP_HOST_URL is ${url.protocol}//${url.host}: the admin token would cross the wire in clear. ` +
+    `Use https://, or pass ${INSECURE_FLAG} for a development gateway.`
+  );
+}
+
+/** The `--dep` grammar, quoted in every refusal so the fix is in the error. */
+export const DEP_GRAMMAR =
+  '--dep github:<owner/repo>[@<tag|latest>]:<asset-name-or-glob>#<bin>[,<bin>…] | --dep npm:<pkg>[@<version|dist-tag>]';
+
+function badDep(spec, why) {
+  return new Error(`--dep ${why}, got ${JSON.stringify(spec)}; expected ${DEP_GRAMMAR}`);
+}
+
+/**
+ * One `--dep` flag into the control API's unresolved dependency input
+ * (core `dependencyInputSchema`): the field names here ARE the wire's.
+ *
+ * Parsed from the RIGHT, because every delimiter also occurs inside the parts
+ * it separates: a scoped npm package carries an `@`, an asset glob may carry
+ * `.`/`+`, and a bin path carries `/`. So the last `#` splits the bins off,
+ * the last `:` before it splits the asset off, and only then is the `@` in
+ * what is left the tag. Nothing here is validated beyond the shape — the
+ * server's schema owns the grammar of each part (asset alphabet, bin path
+ * rules), and a copy of those rules would be a second source of truth.
+ *
+ * @param {string} spec
+ * @returns {{kind:'github-release', repo:string, tag:string, asset:string, bin:string[]}
+ *         | {kind:'npm', pkg:string, version?:string}}
+ */
+export function parseDepSpec(spec) {
+  const colon = spec.indexOf(':');
+  const kind = colon > 0 ? spec.slice(0, colon) : '';
+  const remainder = spec.slice(colon + 1);
+  if (kind === 'npm') {
+    if (remainder === '') throw badDep(spec, 'names no package');
+    const { pkg, version } = parseNpmSpec(remainder);
+    if (pkg === '' || version === '') throw badDep(spec, 'has an empty package or version');
+    return { kind: 'npm', pkg, ...(version !== undefined ? { version } : {}) };
+  }
+  if (kind !== 'github') throw badDep(spec, 'must start with github: or npm:');
+  const hash = remainder.lastIndexOf('#');
+  if (hash < 0) throw badDep(spec, 'names no bin (missing #<bin>)');
+  const bin = remainder.slice(hash + 1).split(',');
+  if (bin.some((b) => b === '')) throw badDep(spec, 'has an empty bin name');
+  const head = remainder.slice(0, hash);
+  const assetAt = head.lastIndexOf(':');
+  if (assetAt < 0) throw badDep(spec, 'names no asset (missing :<asset>)');
+  const asset = head.slice(assetAt + 1);
+  if (asset === '') throw badDep(spec, 'has an empty asset name');
+  const repoPart = head.slice(0, assetAt);
+  const at = repoPart.indexOf('@');
+  const repo = at < 0 ? repoPart : repoPart.slice(0, at);
+  const tag = at < 0 ? 'latest' : repoPart.slice(at + 1);
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) throw badDep(spec, 'needs an owner/repo');
+  if (tag === '') throw badDep(spec, 'has an empty tag');
+  return { kind: 'github-release', repo, tag, asset, bin };
+}
+
+/**
+ * Every `--dep` in order, with each `--dep-sha256 <asset>=<64hex>` attached to
+ * the github-release dep that names that asset. The sha256 is a separate flag
+ * rather than a fifth field in the spec because it is needed only when GitHub
+ * reports no digest — the common case never types it — and a 64-hex tail
+ * would make the one-line form unreadable. One that matches nothing is an
+ * error: silently dropping it would let a pin the owner typed go unchecked.
+ *
+ * @param {string[]} depArgs
+ * @param {string[]} depSha256Args
+ */
+export function buildDependencies(depArgs, depSha256Args) {
+  const dependencies = depArgs.map(parseDepSpec);
+  for (const pair of depSha256Args) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) throw new Error(`--dep-sha256 expects <asset-name-or-glob>=<64hex>, got ${JSON.stringify(pair)}`);
+    const asset = pair.slice(0, eq);
+    const sha256 = pair.slice(eq + 1);
+    if (!/^[0-9a-f]{64}$/.test(sha256)) {
+      throw new Error(`--dep-sha256 ${asset}: expected 64 hex characters (lower-case sha256)`);
+    }
+    const dep = dependencies.find((d) => d.kind === 'github-release' && d.asset === asset);
+    if (!dep) throw new Error(`--dep-sha256 ${asset} matches no --dep github-release asset`);
+    dep.sha256 = sha256;
+  }
+  return dependencies;
+}
+
+/**
+ * The slug rule, for a proposed slug: a MIRROR of the validity rule in
+ * `packages/core/src/slug.ts` (the regex and the reserved list). The CLI has
+ * no workspace dependency on core (it is plain ESM with no build), so the
+ * rule is restated here; a change to core's rule is a change to this one.
+ */
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const RESERVED_SLUGS = new Set([
+  'api', 'c', 'mcp', 'sse', 'messages', 'authorize', 'token', 'register', 'admin', 'healthz',
+  'media', 'static', 'assets', 'www', 'oauth', 'well-known', 'all',
+]);
+
+/**
+ * How a registration takes part in its account's aggregate connector (`set
+ * --aggregate`, plan task G4): a MIRROR of `AGGREGATE_MODES` in
+ * `packages/core/src/aggregate.ts`, for the slug rule's reason above, held to
+ * it by `tests/aggregate-mirror.test.ts`.
+ */
+export const AGGREGATE_MODES = Object.freeze(['inline', 'search', 'exclude']);
+
+/**
+ * A slug proposed from a source name: `@scope/foo-mcp` → `foo`,
+ * `owner/gogcli-mcp` → `gogcli`. The portal's register wizard carries the
+ * same suggestion rule (`packages/admin-ui/src/slug.ts`), so the two propose
+ * the same name for the same package; core's validity rule is what both are
+ * checked against. Last path segment, lowercased, the `mcp-`/`-mcp` affixes dropped,
+ * anything outside the slug alphabet turned into a dash. Returns '' rather than
+ * a reserved or empty result: a suggestion the API would refuse is worse than
+ * none, because the field looks filled.
+ *
+ * @param {string} source
+ */
+export function suggestSlug(source) {
+  const segment = source.slice(source.lastIndexOf('/') + 1).toLowerCase();
+  let slug = segment.replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  slug = slug.replace(/^mcp-+/, '').replace(/-+mcp$/, '');
+  slug = slug.replace(/-{2,}/g, '-').replace(/^-+|-+$/g, '');
+  slug = slug.slice(0, 63).replace(/-+$/, '');
+  return SLUG_RE.test(slug) && !RESERVED_SLUGS.has(slug) ? slug : '';
+}
+
+/**
+ * Whether `mcp-host register` is the interactive wizard: a terminal AND no
+ * argv at all. A single flag — even one that names no slug or source, like
+ * `--account x` — is the flags path, because a wizard that silently dropped
+ * it would register under the default account without saying so; the flags
+ * path answers with the error (`--slug is required`) that names the fix.
+ *
+ * @param {string[]} argv everything after `register`
+ * @param {boolean | undefined} isTTY
+ */
+export function wantsWizard(argv, isTTY) {
+  return Boolean(isTTY) && argv.length === 0;
+}
+
+/**
+ * Turns repeated --env K=V and --secret-env K=NAME flags into the control
+ * API's env map ({literal} | {secret: name}).
+ * @param {string[]} envArgs
+ * @param {string[]} secretEnvArgs
+ */
+export function buildEnvMap(envArgs, secretEnvArgs) {
+  /** @type {Record<string, string | {secret: string}>} */
+  const env = {};
+  for (const pair of envArgs) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) throw new Error(`--env expects K=V, got ${JSON.stringify(pair)}`);
+    env[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  for (const pair of secretEnvArgs) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) throw new Error(`--secret-env expects VAR=SECRET_NAME, got ${JSON.stringify(pair)}`);
+    env[pair.slice(0, eq)] = { secret: pair.slice(eq + 1) };
+  }
+  return env;
+}
+
+/**
+ * Minimal flag parser: `--key value` (repeatable), `--flag` booleans,
+ * `--flag [value]` optionals, and positionals.
+ *
+ * An OPTIONAL-value flag takes the next token only when there is one and it
+ * does not itself look like a flag, so `--from-env` and `--from-env VAR` are
+ * both legal and `--from-env --value x` does not silently eat `--value`. When
+ * it appears without a value it lands in `booleans`, so `flagPresent` can
+ * answer "was it passed at all" without conflating the two spellings.
+ *
+ * @param {string[]} argv
+ * @param {Set<string>} booleans flag names that take no value
+ * @param {Set<string>} optionalValue flag names whose value may be omitted
+ */
+export function parseArgs(argv, booleans = new Set(), optionalValue = new Set()) {
+  /** @type {{ positionals: string[], flags: Record<string, string[]>, booleans: Set<string> }} */
+  const out = { positionals: [], flags: {}, booleans: new Set() };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const name = arg.slice(2);
+      if (booleans.has(name)) {
+        out.booleans.add(name);
+      } else if (optionalValue.has(name)) {
+        const next = argv[i + 1];
+        // A leading '-' means the next token is another flag, not our value.
+        // No environment variable is named like that, so nothing legitimate is
+        // lost by refusing to read one as a value.
+        if (next !== undefined && !next.startsWith('-')) {
+          (out.flags[name] ??= []).push(argv[++i]);
+        } else {
+          out.booleans.add(name);
+        }
+      } else {
+        const value = argv[++i];
+        if (value === undefined) throw new Error(`--${name} needs a value`);
+        (out.flags[name] ??= []).push(value);
+      }
+    } else {
+      out.positionals.push(arg);
+    }
+  }
+  return out;
+}
+
+export function firstFlag(parsed, name) {
+  return parsed.flags[name]?.[0];
+}
+
+/** Was `--name` passed at all — with a value or without one? */
+export function flagPresent(parsed, name) {
+  return parsed.booleans.has(name) || parsed.flags[name] !== undefined;
+}
+
+/**
+ * Resolve a secret's value out of the environment for `secret set --from-env`.
+ *
+ * `varName` is what `--from-env VAR` supplied; omitted, the variable named
+ * after the SECRET is read, which is the common case (`KIA_PASSWORD` from
+ * `$KIA_PASSWORD`) and the reason the flag can be passed bare.
+ *
+ * Reading it here rather than in the shell is the point: the value never
+ * appears in argv, so it stays out of the shell history and out of `ps`.
+ *
+ * The value is passed through byte-for-byte. Trimming would be the friendly
+ * thing right up until it truncated a secret that legitimately ends in
+ * whitespace, and a corrupted credential fails later, elsewhere, as an
+ * authentication error nobody connects back to here. Surrounding whitespace is
+ * warned about instead, because a stray newline is the likelier reading of it.
+ *
+ * @param {string} secretName the secret being set
+ * @param {string | undefined} varName explicit variable name, if given
+ * @param {Record<string, string | undefined>} env
+ */
+export function readSecretEnv(secretName, varName, env = process.env) {
+  const key = varName ?? secretName;
+  const value = env[key];
+  if (value === undefined) {
+    throw new Error(
+      `--from-env: $${key} is not set` +
+        (varName ? '' : ' (pass --from-env <VAR> to read a differently-named variable)'),
+    );
+  }
+  if (value === '') throw new Error(`--from-env: $${key} is empty`);
+  const warning =
+    value !== value.trim()
+      // `characters`, not `bytes`: .length counts UTF-16 code units, so a
+      // secret with any non-ASCII in it would be reported at the wrong size —
+      // and a size is exactly what someone reads to decide whether the
+      // whitespace they are being warned about is the whole value.
+      ? `$${key} has leading or trailing whitespace; storing it verbatim (${value.length} characters)`
+      : undefined;
+  return { key, value, warning };
+}
+
+/**
+ * Turns `--tools a,b` into the enabledTools allowlist, or null when the flag is
+ * absent (which means "no narrowing").
+ *
+ * Blank entries are dropped rather than sent: a trailing comma used to ship a
+ * '' tool name, and `--tools ""` an allowlist of one empty name. Both matter
+ * more than they look — enabledTools is a capability gate, and a narrowed one
+ * also switches off prompts and resources, so a shell mishap must not quietly
+ * become a registration. A flag that names nothing at all is an error, not an
+ * empty allowlist and not a silent widening back to null.
+ *
+ * @param {string | undefined} value
+ * @param {string} [flag] the flag the value came from, for the refusal
+ * @returns {string[] | null}
+ */
+export function parseToolList(value, flag = '--tools') {
+  if (value === undefined) return null;
+  const tools = value
+    .split(',')
+    .map((name) => name.trim())
+    .filter((name) => name !== '');
+  if (tools.length === 0) throw new Error(`${flag} names no tools, got ${JSON.stringify(value)}`);
+  return tools;
+}
+
+/** Mirror of core `TOOL_POLICY_DENY_CLASSES`: what `--deny` may name. */
+export const TOOL_POLICY_DENY_CLASSES = ['destructive', 'non-read-only'];
+
+/**
+ * What `set`'s policy flags ask to change, half by half, or null when none was
+ * passed. `--deny` (repeatable, or comma-separated) REPLACES the deny classes
+ * and `--allow-all` clears them; `--ask a,b` (repeatable) REPLACES the
+ * ask-me-first list and `--no-ask` clears it. A half no flag named is absent
+ * from the answer, so `mergeToolPolicy` keeps the stored one: the PUT takes the
+ * policy WHOLE, and `--deny destructive` must not empty an ask list nobody
+ * mentioned. Naming both flags of a pair is a mistake, not a precedence
+ * question — the `--dep`/`--no-deps` rule.
+ *
+ * @param {{ flags: Record<string, string[]>, booleans: Set<string> }} parsed
+ * @returns {{ deny?: string[], ask?: string[] } | null}
+ */
+export function toolPolicyChange(parsed) {
+  /** @type {{ deny?: string[], ask?: string[] }} */
+  const change = {};
+  const denyValues = parsed.flags['deny'];
+  const allowAll = parsed.booleans.has('allow-all');
+  if (denyValues !== undefined && allowAll) throw new Error('pass --deny or --allow-all, not both');
+  if (denyValues !== undefined) {
+    const named = denyValues.flatMap((value) => value.split(',')).map((cls) => cls.trim());
+    for (const cls of named) {
+      if (!TOOL_POLICY_DENY_CLASSES.includes(cls)) {
+        throw new Error(`--deny takes destructive or non-read-only (comma-separate for both), got ${JSON.stringify(cls)}`);
+      }
+    }
+    change.deny = [...new Set(named)];
+  } else if (allowAll) {
+    change.deny = [];
+  }
+  const askValues = parsed.flags['ask'];
+  const noAsk = parsed.booleans.has('no-ask');
+  if (askValues !== undefined && noAsk) throw new Error('pass --ask or --no-ask, not both');
+  if (askValues !== undefined) {
+    change.ask = [...new Set(askValues.flatMap((value) => parseToolList(value, '--ask') ?? []))];
+  } else if (noAsk) {
+    change.ask = [];
+  }
+  return Object.keys(change).length === 0 ? null : change;
+}
+
+/**
+ * The whole policy a PUT sends: the halves `change` names, over the stored
+ * policy (the registration view's `toolPolicy`). A stored half that is not a
+ * string array — absent on an older gateway — reads as empty.
+ *
+ * @param {unknown} stored
+ * @param {{ deny?: string[], ask?: string[] }} change
+ * @returns {{ deny: string[], ask: string[] }}
+ */
+export function mergeToolPolicy(stored, change) {
+  const half = (value) =>
+    Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? [...value] : [];
+  const current = typeof stored === 'object' && stored !== null ? stored : {};
+  return {
+    deny: change.deny ?? half(current.deny),
+    ask: change.ask ?? half(current.ask),
+  };
+}
+
+/** How much of an approval's argument preview a summary line shows. */
+const ARGS_PREVIEW_CHARS = 80;
+
+/** `4m`, `20s`, `1h 5m`: the time left in an approval window, coarsely. */
+function timeLeft(ms) {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+
+/**
+ * One line per approval row, for a person deciding (`mcp-host approvals`):
+ * which MCP, which tool, the argument preview the gateway kept (already
+ * bounded and redacted server-side; shortened again here to fit a line), and
+ * for a request still open the time left in its window. A decided row says
+ * who decided it. Stdout stays the JSON; these lines are stderr's.
+ *
+ * @param {Array<Record<string, any>>} approvals
+ * @param {number} now  epoch ms
+ * @returns {string[]}
+ */
+export function approvalLines(approvals, now = Date.now()) {
+  return approvals.map((a) => {
+    const { where, preview, when } = describeApproval(a, now);
+    return `  ${String(a.id).padEnd(14)} ${String(a.status).padEnd(9)} ${where}  ${preview}  ${when}`;
+  });
+}
+
+/**
+ * One approval's parts as a person reads them — which MCP and tool, the
+ * argument preview (shortened), and the time left or who decided — shared by
+ * the `approvals` listing and the echo `approvals approve` prints first.
+ */
+export function describeApproval(a, now = Date.now()) {
+  const where = `${a.registrationSlug ?? a.registrationId} · ${a.tool}`;
+  const preview =
+    typeof a.argsPreview === 'string' && a.argsPreview.length > ARGS_PREVIEW_CHARS
+      ? `${a.argsPreview.slice(0, ARGS_PREVIEW_CHARS - 1)}…`
+      : (a.argsPreview ?? '');
+  let when;
+  if (a.status === 'pending' || a.status === 'approved') {
+    const left = Date.parse(a.expiresAt) - now;
+    when = Number.isFinite(left) && left > 0 ? `expires in ${timeLeft(left)}` : 'expired';
+    if (a.status === 'approved') when = `approved${a.decidedBy ? ` by ${a.decidedBy}` : ''}, ${when}`;
+  } else {
+    when = a.decidedBy ? `${a.status} by ${a.decidedBy}` : String(a.status);
+  }
+  return { where, preview, when };
+}
+
+/**
+ * `on`/`off` (or `true`/`false`, `yes`/`no`) as a boolean, for a switch flag
+ * that must be able to say false — a bare boolean flag can only say true.
+ *
+ * @param {string} value
+ * @param {string} flag  for the refusal
+ */
+export function parseOnOff(value, flag) {
+  const v = value.trim().toLowerCase();
+  if (v === 'on' || v === 'true' || v === 'yes') return true;
+  if (v === 'off' || v === 'false' || v === 'no') return false;
+  throw new Error(`${flag} takes on or off, got ${JSON.stringify(value)}`);
+}
+
+/**
+ * A nested JSON document named by a flag, e.g. `--auth-flow ./kia-flow.json`.
+ *
+ * A path rather than an inline string, because the documents this reads are
+ * nested: an authFlow is steps, arguments, `{from:}` references and prompts,
+ * all quotes and braces, and a shell is the worst possible place to assemble
+ * one. A file is also reviewable and diffable, which a login definition
+ * deserves — it decides what a person is asked for their password.
+ *
+ * The GRAMMAR is not checked here. The one schema that owns it lives in
+ * packages/core and runs on the write, so a copy of its rules in the CLI would
+ * be a second source of truth that drifts. What is checked is only what the
+ * server's error could not explain as well from here: which file, and that it
+ * held an object at all — a bare steps array (the `{ "steps": ... }` wrapper
+ * forgotten) is the near-miss worth naming plainly.
+ *
+ * @param {string} file path to the document
+ * @param {string} flag the flag that named it, for the error message
+ * @param {(path: string, encoding: 'utf8') => string} read
+ */
+export function readJsonDocument(file, flag, read = readFileSync) {
+  let text;
+  try {
+    text = read(file, 'utf8');
+  } catch (error) {
+    throw new Error(`${flag}: cannot read ${file}: ${error.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${flag}: ${file} is not valid JSON: ${error.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${flag}: ${file} must contain a JSON object`);
+  }
+  return parsed;
+}
+
+/**
+ * The LEGACY builder key: `HMAC(RUNNER_KEY, 'builder')`, which is what the
+ * builder was recognised by until the 2026-09-01 audit (finding 3) and what an
+ * un-migrated builder app still holds as its own `RUNNER_KEY`. It kept the
+ * master off the build machine but not the build machine's authority off the
+ * pool — every pool machine holds the master and could mint this — so the
+ * builder now has its own `BUILDER_KEY`, derived from nothing, and the gateway
+ * REFUSES this value once that secret is set. Printed for debugging a 401 on a
+ * builder that has not been migrated; never a value to set `BUILDER_KEY` to
+ * (the gateway refuses that too, docs/DEPLOY.md §6).
+ *
+ * A re-derivation of the gateway's `deriveLegacyBuilderKey` (src/builder-key.ts),
+ * not an import: this package has no workspace dependency and the gateway is
+ * Worker code. The label, the newline separator and the base64url encoding are
+ * therefore duplicated by hand, and a drift between the two would not error
+ * anywhere — the builder would simply present a key the gateway answers 401 to.
+ * The shared test vector in tests/builder-key.test.ts and the gateway's
+ * builder-key-vector.test.ts is what turns that silence into a failing test.
+ *
+ * It lived in the gateway's `runtime/machine-key.ts` and minted one key per
+ * ISOLATED machine until that tier was retired (2026-09-11). `builder` is the
+ * one name it was ever derived for that was not a machine, which is why this
+ * function outlived the tier and still takes a name.
+ * @param {string} masterKey the gateway's RUNNER_KEY
+ * @param {string} machineName
+ */
+export function deriveMachineKey(masterKey, machineName) {
+  return createHmac('sha256', masterKey)
+    .update(`mcp-host/runner-machine-key/v1\n${machineName}`)
+    .digest('base64url');
+}
+
+/**
+ * An uploaded bundle (the API's `bundleView`), as the lines a person reads
+ * after `bundles upload`, `register --mcpb <path>` and the wizard — ONE
+ * rendering so the three cannot describe the same row differently. Warnings
+ * are what the summary is FOR: a `user_config` key this host cannot deliver
+ * (referenced only in args) is exactly the thing to read before registering,
+ * and the bindings say which env vars the manifest expects.
+ *
+ * @param {{ sha256: string, name: string, version: string, serverType: string, manifestVersion: string,
+ *           signature: string, size: number, warnings?: string[],
+ *           userConfigBindings?: { key: string, envVar?: string, required: boolean, hasDefault: boolean, sensitive: boolean }[],
+ *           existed?: boolean }} view
+ * @returns {string[]}
+ */
+export function bundleSummaryLines(view) {
+  const lines = [
+    `Bundle: ${view.name}@${view.version} (${view.serverType}, manifest ${view.manifestVersion}, ${view.size} bytes)`,
+    `  sha256: ${view.sha256}${view.existed ? ' (already uploaded)' : ''}`,
+    // Presence only: the gateway records that a PKCS#7 block is appended and
+    // verifies nothing about it (docs/SECURITY.md), so this line must not
+    // read as "signed by someone".
+    `  signature: ${view.signature}${view.signature === 'present' ? ' (recorded, not verified)' : ''}`,
+  ];
+  for (const b of view.userConfigBindings ?? []) {
+    const via = b.envVar ? `env ${b.envVar}` : 'no env binding';
+    lines.push(`  config ${b.key}: ${via}${b.required ? ', required' : ''}${b.hasDefault ? ', has default' : ''}${b.sensitive ? ', sensitive' : ''}`);
+  }
+  for (const w of view.warnings ?? []) lines.push(`  warning: ${w}`);
+  return lines;
+}