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

package/src/prompt.mjs

@@ -0,0 +1,126 @@
+// Terminal prompts for the register wizard and `secret set`.
+//
+// Every prompt writes to STDERR (the default `output`), never stdout: the
+// CLI's stdout is JSON a script may be parsing, and a question printed into
+// it would turn `mcp-host register | jq` into a parse error the moment
+// someone ran it from a terminal. Streams are injectable so tests drive the
+// prompter over a PassThrough and a collector without a TTY.
+
+import { createInterface } from 'node:readline/promises';
+
+/**
+ * @typedef {{ value: string, label?: string }} Choice
+ * @typedef {{
+ *   ask(question: string, opts?: { default?: string, hint?: string }): Promise<string>,
+ *   confirm(question: string, def?: boolean): Promise<boolean>,
+ *   choose(question: string, options: Choice[]): Promise<string>,
+ *   secret(question: string): Promise<string>,
+ *   close(): void,
+ * }} Prompter
+ */
+
+/**
+ * @param {{ input?: NodeJS.ReadableStream & { isTTY?: boolean, setRawMode?: (on: boolean) => unknown, resume?: () => unknown, pause?: () => unknown },
+ *           output?: { write(s: string): unknown }, exit?: (code: number) => void }} [opts]
+ * @returns {Prompter}
+ */
+export function makePrompter({ input = process.stdin, output = process.stderr, exit = (code) => process.exit(code) } = {}) {
+  /**
+   * One readline interface PER QUESTION rather than one for the prompter's
+   * life: an open interface keeps its own 'data' listener on the input, and
+   * `secret()` needs to be the ONLY reader of the stream while it runs —
+   * otherwise readline would buffer the keystrokes it saw and hand the
+   * secret back as the answer to the NEXT question. `terminal: false` so
+   * readline never echoes or redraws; the tty's own cooked mode handles
+   * line editing for the ordinary prompts.
+   */
+  async function line(prompt) {
+    const rl = createInterface({ input, output, terminal: false });
+    try {
+      return (await rl.question(prompt)).trim();
+    } finally {
+      rl.close();
+    }
+  }
+
+  /** @type {Prompter} */
+  const prompter = {
+    async ask(question, { default: def, hint } = {}) {
+      if (hint) output.write(`  ${hint}\n`);
+      const suffix = def !== undefined && def !== '' ? ` [${def}]` : '';
+      const answer = await line(`${question}${suffix}: `);
+      return answer === '' && def !== undefined ? def : answer;
+    },
+
+    async confirm(question, def = false) {
+      for (;;) {
+        const answer = (await line(`${question} ${def ? '[Y/n]' : '[y/N]'}: `)).toLowerCase();
+        if (answer === '') return def;
+        if (answer === 'y' || answer === 'yes') return true;
+        if (answer === 'n' || answer === 'no') return false;
+        output.write('  answer y or n\n');
+      }
+    },
+
+    async choose(question, options) {
+      output.write(`${question}\n`);
+      options.forEach((o, i) => output.write(`  ${i + 1}) ${o.label ?? o.value}\n`));
+      for (;;) {
+        const answer = await line(`> `);
+        const byNumber = /^\d+$/.test(answer) ? options[Number(answer) - 1] : undefined;
+        const byValue = options.find((o) => o.value === answer);
+        const picked = byNumber ?? byValue;
+        if (picked) return picked.value;
+        output.write(`  pick 1-${options.length}\n`);
+      }
+    },
+
+    /**
+     * Read a value with NOTHING echoed. Raw mode (when the input is a TTY)
+     * is what stops the terminal itself from echoing; the rest is one
+     * character at a time: Enter ends it, backspace edits it, Ctrl-C is the
+     * conventional 130 (128 + SIGINT) because raw mode swallows the signal
+     * the terminal would otherwise have sent.
+     */
+    secret(question) {
+      output.write(`${question}: `);
+      return new Promise((resolve) => {
+        const raw = Boolean(input.isTTY && typeof input.setRawMode === 'function');
+        if (raw) input.setRawMode(true);
+        let value = '';
+        const done = (result) => {
+          input.off('data', onData);
+          if (raw) input.setRawMode(false);
+          input.pause?.();
+          output.write('\n');
+          resolve(result);
+        };
+        const onData = (chunk) => {
+          for (const ch of chunk.toString('utf8')) {
+            if (ch === '') {
+              done('');
+              exit(130);
+              return;
+            }
+            if (ch === '\r' || ch === '\n') {
+              done(value);
+              return;
+            }
+            if (ch === '' || ch === '\b') {
+              value = value.slice(0, -1);
+              continue;
+            }
+            value += ch;
+          }
+        };
+        input.on('data', onData);
+        input.resume?.();
+      });
+    },
+
+    close() {
+      input.pause?.();
+    },
+  };
+  return prompter;
+}

package/src/seal.mjs

@@ -0,0 +1,226 @@
+// The CLI's sealing half of docs/SEALED-SECRETS.md — a hand-written ESM
+// MIRROR of `packages/core/src/seal.ts`, which is THE implementation. The CLI
+// runs as plain Node on `.mjs` with no TypeScript loader, so it cannot import
+// core; what it can do is be held against the same known-answer vectors
+// (`core/tests/fixtures/seal-vectors.json`) by `tests/seal-mirror.test.ts`,
+// which fails the moment the two drift by a byte.
+//
+// Deliberately MINIMAL: seal, fingerprint, and the encoding helpers. There is
+// no unseal here and must never be — the CLI seals values it is handed and
+// compares fingerprints; opening a sealed value is the runner's job alone.
+//
+// WebCrypto ONLY (`globalThis.crypto`), never `node:crypto`: the construction
+// has to produce identical bytes from a browser, Node 26 and workerd, and
+// keeping to the one API all three share is how the mirror stays a mirror.
+//
+//   e      = fresh X25519 keypair per seal
+//   shared = X25519(e_priv, pk_a)
+//   key    = HKDF-SHA256(ikm = shared, salt = e_pub ‖ pk_a, info = "mcp-host/seal/v1")
+//   aad    = scope ‖ "\0" ‖ accountId ‖ "\0" ‖ name            (UTF-8)
+//   wire   = "sealed:v1:" + kid + ":" + b64url(e_pub) + ":" + b64url(iv ‖ ct ‖ tag)
+//   fp     = base32(SHA-256("mcp-host/fp/v1" ‖ salt ‖ value))[0:10]   as xxxxx-xxxxx
+
+export const SEAL_PREFIX = 'sealed:v1:';
+const SEAL_INFO = 'mcp-host/seal/v1';
+const FINGERPRINT_DOMAIN = 'mcp-host/fp/v1';
+
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KID_HEX_CHARS = 16;
+export const FINGERPRINT_SALT_BYTES = 16;
+
+const SCOPE_RE = /^(account|principal:[^\0:]+|user:[^\0:]+:[^\0:]+)$/;
+export const FINGERPRINT_RE = /^[a-z2-7]{5}-[a-z2-7]{5}$/;
+
+// ---------------------------------------------------------------------------
+// Encoding
+
+const B64URL = /^[A-Za-z0-9_-]*$/;
+
+/** @param {Uint8Array} bytes */
+export function toBase64Url(bytes) {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Strict: unpadded, URL alphabet only — the same refusal core makes. @param {string} text */
+export function fromBase64Url(text) {
+  if (!B64URL.test(text) || text.length % 4 === 1) throw new Error('malformed base64url (must be unpadded, URL alphabet)');
+  const padded = text.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (text.length % 4)) % 4);
+  const binary = atob(padded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+/** @param {Uint8Array} bytes */
+export function bytesToHex(bytes) {
+  return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** @param {string} hex */
+export function hexToBytes(hex) {
+  if (!/^([0-9a-f]{2})*$/i.test(hex)) throw new Error('not hex');
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/** @param {string} text */
+function utf8(text) {
+  return new TextEncoder().encode(text);
+}
+
+/** @param {Uint8Array[]} parts */
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+const subtle = () => globalThis.crypto.subtle;
+
+// ---------------------------------------------------------------------------
+// X25519 via WebCrypto
+
+/** PKCS#8 prefix for a raw 32-byte X25519 scalar (OID 1.3.101.110) — a constant, not a parser. */
+const X25519_PKCS8_PREFIX = hexToBytes('302e020100300506032b656e04220420');
+
+/** @param {Uint8Array} privateKey @param {boolean} [extractable] */
+async function importPrivate(privateKey, extractable = false) {
+  if (privateKey.length !== KEY_BYTES) throw new Error(`X25519 private key must be ${KEY_BYTES} bytes`);
+  return subtle().importKey('pkcs8', concat(X25519_PKCS8_PREFIX, privateKey), { name: 'X25519' }, extractable, ['deriveBits']);
+}
+
+/** @param {Uint8Array} publicKey */
+async function importPublic(publicKey) {
+  if (publicKey.length !== KEY_BYTES) throw new Error(`X25519 public key must be ${KEY_BYTES} bytes`);
+  return subtle().importKey('raw', publicKey, { name: 'X25519' }, true, []);
+}
+
+/** The public half of a raw X25519 private key. @param {Uint8Array} privateKey */
+async function sealPublicKey(privateKey) {
+  const key = await importPrivate(privateKey, true);
+  const jwk = /** @type {{ x?: string }} */ (await subtle().exportKey('jwk', key));
+  if (!jwk.x) throw new Error('X25519 export yielded no public coordinate');
+  return fromBase64Url(jwk.x);
+}
+
+/** @param {Uint8Array} privateKey @param {Uint8Array} publicKey */
+async function x25519(privateKey, publicKey) {
+  const priv = await importPrivate(privateKey);
+  const pub = await importPublic(publicKey);
+  return new Uint8Array(await subtle().deriveBits({ name: 'X25519', public: pub }, priv, KEY_BYTES * 8));
+}
+
+/** @param {Uint8Array} ikm @param {Uint8Array} salt @param {string} info */
+async function hkdf(ikm, salt, info) {
+  const key = await subtle().importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+  return new Uint8Array(await subtle().deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info: utf8(info) }, key, KEY_BYTES * 8));
+}
+
+/** `kid` = the first 16 hex characters of SHA-256(publicKey). @param {Uint8Array} publicKey */
+export async function deriveKid(publicKey) {
+  if (publicKey.length !== KEY_BYTES) throw new Error(`X25519 public key must be ${KEY_BYTES} bytes`);
+  const digest = new Uint8Array(await subtle().digest('SHA-256', publicKey));
+  return bytesToHex(digest).slice(0, KID_HEX_CHARS);
+}
+
+// ---------------------------------------------------------------------------
+// Seal
+
+/** @param {string} scope @param {string} accountId @param {string} name */
+function aadFor(scope, accountId, name) {
+  for (const [label, part] of [
+    ['scope', scope],
+    ['accountId', accountId],
+    ['name', name],
+  ]) {
+    if (!part) throw new Error(`${label} is required for the AAD`);
+    if (part.includes('\0')) throw new Error(`${label} must not contain NUL`);
+  }
+  if (!SCOPE_RE.test(scope)) throw new Error(`scope ${scope} is not one of the three AAD scopes`);
+  return utf8(`${scope}\0${accountId}\0${name}`);
+}
+
+/**
+ * Seal `value` to the account public key `publicKey` (kid `kid`) under the
+ * AAD (scope, accountId, name). `ephemeral` is test-vector injection ONLY —
+ * a fresh key and iv per seal is what makes IV reuse impossible.
+ *
+ * @param {{ publicKey: Uint8Array, kid: string, scope: string, accountId: string, name: string, value: string,
+ *           ephemeral?: { privateKey: Uint8Array, iv: Uint8Array } }} args
+ * @returns {Promise<string>} the wire form
+ */
+export async function sealSecret(args) {
+  const { publicKey, kid, scope, accountId, name, value } = args;
+  const aad = aadFor(scope, accountId, name);
+  const actualKid = await deriveKid(publicKey);
+  if (actualKid !== kid) throw new Error(`public key is kid ${actualKid}, caller asked to seal to kid ${kid}`);
+  const ePriv = args.ephemeral?.privateKey ?? globalThis.crypto.getRandomValues(new Uint8Array(KEY_BYTES));
+  const iv = args.ephemeral?.iv ?? globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  if (iv.length !== IV_BYTES) throw new Error(`iv must be ${IV_BYTES} bytes`);
+  const ePub = await sealPublicKey(ePriv);
+  const shared = await x25519(ePriv, publicKey);
+  const raw = await hkdf(shared, concat(ePub, publicKey), SEAL_INFO);
+  const key = await subtle().importKey('raw', raw, { name: 'AES-GCM' }, false, ['encrypt']);
+  const ct = new Uint8Array(
+    await subtle().encrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: TAG_BYTES * 8 }, key, utf8(value)),
+  );
+  return `${SEAL_PREFIX}${kid}:${toBase64Url(ePub)}:${toBase64Url(concat(iv, ct))}`;
+}
+
+/**
+ * The wire form's parts, for a caller that wants to check what it sealed
+ * (the kid, the 32-byte ephemeral key). Never opens anything.
+ * @param {string} sealed
+ */
+export function parseSealed(sealed) {
+  if (typeof sealed !== 'string' || !sealed.startsWith(SEAL_PREFIX)) throw new Error('not a sealed value (expected the sealed:v1: prefix)');
+  const parts = sealed.split(':');
+  if (parts.length !== 5) throw new Error('malformed sealed value: expected sealed:v1:<kid>:<ePub>:<body>');
+  const [, , kid, ePubText, bodyText] = parts;
+  if (!/^[0-9a-f]{16}$/.test(kid)) throw new Error('malformed sealed value: kid must be 16 lowercase hex characters');
+  const ePub = fromBase64Url(ePubText);
+  if (ePub.length !== KEY_BYTES) throw new Error('malformed sealed value: ephemeral public key must be 32 bytes');
+  const body = fromBase64Url(bodyText);
+  if (body.length < IV_BYTES + TAG_BYTES) throw new Error('malformed sealed value: body shorter than iv + tag');
+  return { kid, ePub, body };
+}
+
+// ---------------------------------------------------------------------------
+// Fingerprints
+
+const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
+
+export function newFingerprintSalt() {
+  return globalThis.crypto.getRandomValues(new Uint8Array(FINGERPRINT_SALT_BYTES));
+}
+
+/**
+ * `base32(SHA-256("mcp-host/fp/v1" ‖ salt ‖ value))[0:10]` as `xxxxx-xxxxx`.
+ * Compared locally and only locally: no server route answers "is this the value".
+ * @param {string} value @param {Uint8Array} salt
+ */
+export async function computeFingerprint(value, salt) {
+  if (salt.length !== FINGERPRINT_SALT_BYTES) throw new Error(`fingerprint salt must be ${FINGERPRINT_SALT_BYTES} bytes`);
+  const digest = new Uint8Array(await subtle().digest('SHA-256', concat(utf8(FINGERPRINT_DOMAIN), salt, utf8(value))));
+  let bits = 0;
+  let acc = 0;
+  let out = '';
+  for (const byte of digest.subarray(0, 7)) {
+    acc = (acc << 8) | byte;
+    bits += 8;
+    while (bits >= 5 && out.length < 10) {
+      out += BASE32[(acc >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  return `${out.slice(0, 5)}-${out.slice(5, 10)}`;
+}

package/src/secrets.mjs

@@ -0,0 +1,100 @@
+// Storing and checking account secrets over the control API, sealed by default
+// (docs/SEALED-SECRETS.md). ONE path for every place the CLI creates a secret
+// — `secret set`, the wizard's "a new secret" row — so there is exactly one
+// place a value is sealed and exactly one that could get it wrong.
+//
+// The value arrives as a string and leaves as a `sealed:v1:…` wire string and
+// a fingerprint. It is never logged, never returned to stdout, and never
+// written into a message: every sentence this module prints names the SECRET
+// (by name), the fingerprint and the kid, which are the three things a person
+// needs afterwards and the three things that are safe to print.
+
+import { computeFingerprint, fromBase64Url, newFingerprintSalt, sealSecret, toBase64Url } from './seal.mjs';
+
+/** A `say` over a stderr-like sink. @param {{ write(s: string): unknown }} stderr */
+const sayTo = (stderr) => (/** @type {string} */ s) => stderr.write(`${s}\n`);
+
+/** `?account=<slug>` when one is named, else nothing. @param {string | undefined} account */
+const accountQuery = (account) => (account ? `?account=${encodeURIComponent(account)}` : '');
+
+/**
+ * `GET /api/v1/secrets/public-key` — the caller's account seal key. A 503
+ * here is the gateway saying there is no key to seal to (no runner, no root);
+ * its sentence is the thing to show, verbatim, so it propagates untouched.
+ * @param {(method: string, path: string, body?: unknown) => Promise<any>} api
+ */
+async function fetchPublicKey(api, account) {
+  // The key of the account NAMED, and its id comes back with it: the seal's
+  // AAD binds `res.account`, so an operator sealing into `--account acme`
+  // seals to acme's key under acme's id, never their own.
+  const res = await api('GET', `/api/v1/secrets/public-key${accountQuery(account)}`);
+  const publicKey = fromBase64Url(res.publicKey);
+  if (publicKey.length !== 32) throw new Error('the gateway answered a public key that is not 32 bytes');
+  return { accountId: res.account, kid: res.kid, publicKey };
+}
+
+/**
+ * Seal `value` for account secret `name` and PUT it. A 409 is the gateway
+ * refusing a kid that is no longer current (a rotation landed between the
+ * key fetch and the write): the key is fetched again and the seal retried
+ * ONCE — twice would be a loop against a gateway that keeps moving.
+ *
+ * `legacy` sends the deprecated `{value}` body: the gateway encrypts (and can
+ * read) the value itself. Kept for the migration and says so every time.
+ *
+ * @param {(method: string, path: string, body?: unknown) => Promise<any>} api  the THROWING variant: a non-2xx must reject, or the 409 retry cannot see it
+ * @param {string} name
+ * @param {string} value
+ * @param {{ legacy?: boolean, account?: string, stderr?: { write(s: string): unknown } }} [opts]
+ * @returns {Promise<{ stored: any, fingerprint: string | null, kid: string | null }>}
+ */
+export async function storeSecretSealed(api, name, value, { legacy = false, account, stderr = process.stderr } = {}) {
+  const say = sayTo(stderr);
+  const path = `/api/v1/secrets/${encodeURIComponent(name)}${accountQuery(account)}`;
+  if (legacy) {
+    const stored = await api('PUT', path, { value });
+    say(`mcp-host: warning: --legacy stored ${name} gateway-readable; the {"value"} body is deprecated — drop --legacy to seal it to the account key`);
+    return { stored, fingerprint: null, kid: null };
+  }
+  const salt = newFingerprintSalt();
+  const fingerprint = await computeFingerprint(value, salt);
+  const fingerprintSalt = toBase64Url(salt);
+  let key = await fetchPublicKey(api, account);
+  for (let attempt = 0; ; attempt++) {
+    const sealed = await sealSecret({ publicKey: key.publicKey, kid: key.kid, scope: 'account', accountId: key.accountId, name, value });
+    try {
+      const stored = await api('PUT', path, { sealed, kid: key.kid, fingerprint, fingerprintSalt });
+      say(`stored ${name} — fingerprint ${fingerprint} (sealed to kid ${key.kid}); compare later with: mcp-host secret fingerprint ${name}`);
+      return { stored, fingerprint, kid: key.kid };
+    } catch (error) {
+      if (attempt === 0 && error?.status === 409) {
+        say(`mcp-host: the seal key moved (${error.message}); fetching the current key and sealing again`);
+        key = await fetchPublicKey(api, account);
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+/**
+ * Recompute `name`'s fingerprint from a value the caller supplies and the
+ * salt the listing returns, and compare LOCALLY. The value is hashed here and
+ * nowhere else: the only request is the listing, and it carries nothing.
+ *
+ * @param {(method: string, path: string, body?: unknown) => Promise<any>} api
+ * @param {string} name
+ * @param {string} value
+ * @param {{ account?: string }} [opts]
+ * @returns {Promise<{ match: boolean, stored: string, yours: string }>}
+ */
+export async function compareFingerprint(api, name, value, { account } = {}) {
+  const listed = await api('GET', `/api/v1/secrets${accountQuery(account)}`);
+  const row = (listed.secrets ?? []).find((/** @type {{ name: string }} */ s) => s.name === name);
+  if (!row) throw new Error(`no secret named ${name}`);
+  if (!row.fingerprint || !row.fingerprintSalt) {
+    throw new Error(`${name} has no fingerprint stored (a legacy row, or one stored without); \`mcp-host secret set ${name}\` re-stores it sealed with one`);
+  }
+  const yours = await computeFingerprint(value, fromBase64Url(row.fingerprintSalt));
+  return { match: yours === row.fingerprint, stored: row.fingerprint, yours };
+}