@blockula/mcp 0.3.0 → 1.0.0

package/dist/network.js

@@ -0,0 +1,361 @@
+// Which chain the MCP talks to, and how it makes sure it stays on it (WAL-4).
+//
+// The network is chosen once, at startup, by the user: `--network <name>` / BLOCKULA_NETWORK, or
+// BLOCKULA_RPC. Nothing switches it later (no probing localhost, no tool that changes it). Each
+// network pins a chain id and, where known, a genesis hash; BLOCKULA_CHAIN_ID and
+// BLOCKULA_GENESIS_HASH pin them for any node. Whatever isn't pinned is pinned from the first
+// status the node reports (trust on first use) and, except for throwaway local dev chains,
+// remembered in BLOCKULA_HOME/known-chains.json, so a node that later reports another chain is
+// refused, across restarts too. A node that says it's on blockula-1 is refused unless
+// BLOCKULA_CHAIN_ID=blockula-1 pins that chain (`unpinnedBlockula1`).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * The chain id Blockula's mainnet was to have: no chain runs under it, so nothing is used under it
+ * by accident (`unpinnedBlockula1`), and where an address is needed an unproven name isn't signed
+ * on it (index.ts `onBlockula1`).
+ */
+export const BLOCKULA_1 = "blockula-1";
+export const LOCAL_RPC = "http://localhost:7070";
+export const TESTNET_RPC = "https://blockula-testnet.fly.dev";
+/**
+ * Nothing reads this: the MCP has no mainnet network. It stays because
+ * `scripts/pin-network.sh --mainnet --rpc` writes it and `scripts/test-pin-network.sh` checks
+ * that; it goes when that mode does.
+ */
+export const MAINNET_RPCS = [];
+/**
+ * Chains whose genesis is known: any node claiming one of these chain ids must report this
+ * genesis hash, whatever network it was configured as. A release adds a chain's here
+ * (scripts/pin-network.sh).
+ */
+export const KNOWN_GENESIS = { "blockula-testnet-2": "b004e2f91b63429fc009088b16ec02b6d5388a03642699ae3dc6e325939f19b2" };
+/**
+ * The genesis clock of chains whose genesis is known (`created_at_ms` and `block_time_ms` of the
+ * genesis.json that hashes to `KNOWN_GENESIS[id]`), added with the hash. With it the client
+ * refuses a node reporting a height the chain can't have reached by this machine's clock, before
+ * anything is signed (audit review-r3-clients-2; `Client.checkSigningHeight`).
+ */
+export const KNOWN_CLOCKS = { "blockula-testnet-2": { createdAtMs: 1792328803000, blockTimeMs: 1000 } };
+/**
+ * The genesis clock in a node's `/api/genesis` answer for chain `chainId`, or `undefined` when it
+ * isn't one (another chain's genesis, missing or malformed fields). The node's word: the MCP takes
+ * it on first use, as it does the genesis hash, and remembers it with that hash.
+ */
+export function clockFrom(genesis, chainId) {
+    const g = genesis && typeof genesis === "object" ? genesis : {};
+    const { created_at_ms: createdAtMs, block_time_ms: blockTimeMs } = g;
+    if (g.chain_id !== chainId || !Number.isSafeInteger(createdAtMs) || createdAtMs < 0 || !Number.isSafeInteger(blockTimeMs) || blockTimeMs < 1)
+        return undefined;
+    return { createdAtMs: createdAtMs, blockTimeMs: blockTimeMs };
+}
+/** The networks the MCP knows by name. */
+export const KNOWN_NETWORKS = {
+    // The protocol v1 public testnet (deploy/launch.sh): its own chain id (never reused) and the
+    // testnet prefix (DEC-7). Its genesis hash exists only once it launches: until a release adds it
+    // to KNOWN_GENESIS, the first status the node reports pins it (trust on first use, remembered).
+    testnet: { key: "testnet", label: "public testnet", rpc: TESTNET_RPC, pin: { chainId: "blockula-testnet-2", prefix: "tboo" }, remember: true },
+    local: { key: "local", label: "local dev node", rpc: LOCAL_RPC, pin: {}, remember: false },
+};
+/** The public RPCs of the chains whose public RPCs are built in, by chain id. */
+const PUBLIC_RPCS = { "blockula-testnet-2": [TESTNET_RPC] };
+/**
+ * The witnesses a node of `chainId` gets when BLOCKULA_WITNESSES is unset: the chain's public RPCs,
+ * unless the node is one of them. So your own node's answers about names and heights are checked
+ * against the public ones (OPERATOR-6). None for chains without public RPCs (dev chains, and the
+ * chains people launch themselves: there, BLOCKULA_WITNESSES lists other nodes).
+ */
+export function defaultWitnesses(chainId, rpc) {
+    const rpcs = ((chainId && PUBLIC_RPCS[chainId]) || []).map(canonicalUrl);
+    // The same node however `rpc` is spelled: a node is never its own witness (audit MCK-1).
+    return rpcs.includes(canonicalUrl(rpc)) ? [] : rpcs;
+}
+/** The public network a chain id is, when it's one (for labels). */
+const PUBLIC_LABEL = { "blockula-testnet-2": "the public testnet" };
+/**
+ * What `status` calls the network: once the node's chain is known, a node on this machine that
+ * is on a public network is "your node on <it>", never a "local dev node".
+ */
+export function networkLabel(net, chainId) {
+    const pub = chainId ? PUBLIC_LABEL[chainId] : undefined;
+    return pub && isLocalUrl(net.rpc) ? `your node on ${pub}` : net.label;
+}
+const isLocalUrl = (u) => {
+    try {
+        return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(u).hostname);
+    }
+    catch {
+        return false;
+    }
+};
+/** This machine, or a private network (where plain http can't be intercepted from the internet). */
+const isPrivateUrl = (u) => {
+    if (isLocalUrl(u))
+        return true;
+    const h = new URL(u).hostname;
+    return /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(h) || /\.(internal|local|lan)$/.test(h);
+};
+/**
+ * A node URL in one spelling: the scheme and host lowercased, a default port and dot segments
+ * dropped (the URL parser's own normalization), no trailing dot on the host and no trailing
+ * slash. So a node compares equal however it's written: `https://Blockula-Testnet.fly.dev:443/.`
+ * is the public RPC, and is never its own witness (audit MCK-1). What isn't an http(s) URL comes
+ * back as it is.
+ */
+export function canonicalUrl(u) {
+    try {
+        const url = new URL(u);
+        if (!/^https?:$/.test(url.protocol))
+            return u;
+        // `host` carries the port; a fully qualified name's trailing dot comes before it, or ends it.
+        const host = url.host.replace(/\.(?=:\d+$|$)/, "");
+        return `${url.protocol}//${host}${url.pathname.replace(/\/+$/, "")}`;
+    }
+    catch {
+        return u;
+    }
+}
+/**
+ * A node URL, spelled canonically (canonicalUrl): http(s) without credentials, a query or a
+ * fragment (the client appends /api/… to it); plain http only on this machine or a private network.
+ */
+export function checkRpcUrl(u, what = "BLOCKULA_RPC") {
+    let url;
+    try {
+        url = new URL(u);
+    }
+    catch {
+        throw new Error(`${what} isn't a URL: ${u}`);
+    }
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password)
+        throw new Error(`${what} must be an http(s) URL without credentials: ${u}`);
+    if (url.search || url.hash)
+        throw new Error(`${what} must be a node's URL, without a query or a fragment: ${u}`);
+    if (url.protocol === "http:" && !isPrivateUrl(u))
+        throw new Error(`${what} must use https unless the node is on this machine or a private network: ${u}`);
+    return canonicalUrl(u);
+}
+/**
+ * The chain ids this MCP pins, and keys its ledger (spend.ts `chainKey`), lock and nonce records
+ * and grant files by: 1 to 64 letters, digits, '-', '_' and '.'. A genesis built for a public
+ * network has letters, digits and '-' (node/src/genesis_builder.rs, at most 64: MAX_CHAIN_ID), so
+ * every real chain fits. A node reporting anything else (a path separator, a space) is refused
+ * when its chain is pinned (`unusableChain`), so nothing it names is ever used as a file name or
+ * a ledger key (audit MCK-3).
+ */
+export const CHAIN_ID = /^[A-Za-z0-9._-]{1,64}$/;
+/**
+ * Why a node's chain can't be pinned at all, or null: a chain id outside CHAIN_ID, or a genesis
+ * hash that isn't 64 hex characters, can't key what this MCP keeps per chain. (A node that reports
+ * no genesis hash is pinned by its chain id alone, as before; it can't sign, and `use_account`
+ * says that's why.)
+ */
+export function unusableChain(status) {
+    const id = status.chain_id;
+    if (typeof id === "string" && !CHAIN_ID.test(id))
+        return `the node reports the chain id ${JSON.stringify(id.length > 80 ? `${id.slice(0, 80)}…` : id)}, and a chain id here is 1 to 64 letters, digits, '-', '_' or '.'`;
+    const g = status.genesis_hash;
+    if (g !== undefined && g !== null && (typeof g !== "string" || !/^[0-9a-fA-F]{64}$/.test(g)))
+        return "the node reports a genesis hash that isn't 64 hex characters";
+    return null;
+}
+/** `--network <name>` or `--network=<name>` from the command line. */
+export function networkArg(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--network")
+            return argv[i + 1];
+        if (argv[i].startsWith("--network="))
+            return argv[i].slice("--network=".length);
+    }
+    return undefined;
+}
+/**
+ * The network from the configuration: `--network` (or BLOCKULA_NETWORK) names one, BLOCKULA_RPC
+ * gives the node, BLOCKULA_CHAIN_ID / BLOCKULA_GENESIS_HASH add pins. With none of them, the
+ * public testnet. Contradictions are errors, never guesses.
+ */
+export function resolveNetwork(env, argv = []) {
+    const named = (networkArg(argv) ?? env.BLOCKULA_NETWORK)?.trim().toLowerCase() || undefined;
+    if (named !== undefined && !["testnet", "local", "custom"].includes(named)) {
+        const hint = named === "mainnet" ? `: there's no mainnet network, and a node that says it's on ${BLOCKULA_1} is used only with BLOCKULA_CHAIN_ID=${BLOCKULA_1}` : "";
+        throw new Error(`unknown network "${named}" (testnet, local or custom)${hint}`);
+    }
+    const rpc = env.BLOCKULA_RPC?.trim() ? checkRpcUrl(env.BLOCKULA_RPC.trim()) : undefined;
+    let key;
+    if (named)
+        key = named;
+    else if (rpc)
+        key = Object.values(KNOWN_NETWORKS).find((n) => n.rpc && canonicalUrl(n.rpc) === rpc)?.key ?? (isLocalUrl(rpc) ? "local" : "custom");
+    else
+        key = "testnet";
+    const base = key === "custom" ? { key, label: "custom node", pin: {}, remember: true } : KNOWN_NETWORKS[key];
+    const url = rpc ?? (base.rpc ? canonicalUrl(base.rpc) : undefined);
+    if (!url)
+        throw new Error("the custom network needs BLOCKULA_RPC");
+    if (key === "local" && !isLocalUrl(url))
+        throw new Error(`the local network is a node on this machine, not ${url}`);
+    const pin = { ...base.pin };
+    const chainId = env.BLOCKULA_CHAIN_ID?.trim() || undefined;
+    const genesisHash = env.BLOCKULA_GENESIS_HASH?.trim().toLowerCase() || undefined;
+    if (chainId) {
+        if (!CHAIN_ID.test(chainId))
+            throw new Error(`BLOCKULA_CHAIN_ID must be a chain id: 1 to 64 letters, digits, '-', '_' or '.' (got ${JSON.stringify(chainId.slice(0, 80))})`);
+        if (pin.chainId && pin.chainId !== chainId)
+            throw new Error(`BLOCKULA_CHAIN_ID=${chainId} contradicts the ${base.label} (${pin.chainId})`);
+        pin.chainId = chainId;
+    }
+    if (genesisHash) {
+        if (!/^[0-9a-f]{64}$/.test(genesisHash))
+            throw new Error("BLOCKULA_GENESIS_HASH must be 64 hex characters");
+        pin.genesisHash = genesisHash;
+    }
+    const known = pin.chainId ? KNOWN_GENESIS[pin.chainId] : undefined;
+    if (known && pin.genesisHash && known !== pin.genesisHash)
+        throw new Error(`BLOCKULA_GENESIS_HASH contradicts ${pin.chainId}'s known genesis ${known}`);
+    pin.genesisHash ??= known;
+    // `none` opts out of the default witnesses; unset, a node that isn't its network's public RPC
+    // gets them (defaultWitnesses; a node whose chain isn't known yet, once it's pinned).
+    const listed = (env.BLOCKULA_WITNESSES ?? "").trim();
+    const witnessesSet = listed !== "";
+    const witnesses = listed.toLowerCase() === "none" ? [] : witnessesSet ? listed.split(",").map((w) => w.trim()).filter(Boolean).map((w) => checkRpcUrl(w, "BLOCKULA_WITNESSES")) : defaultWitnesses(pin.chainId, url);
+    // Every URL here is canonical (checkRpcUrl), so a node spelled two ways is still one node.
+    if (witnesses.includes(url))
+        throw new Error("BLOCKULA_WITNESSES must be other nodes than BLOCKULA_RPC's");
+    if (new Set(witnesses).size !== witnesses.length)
+        throw new Error("BLOCKULA_WITNESSES lists a node twice");
+    return { key, label: base.label, rpc: url, pin, remember: base.remember, witnesses, witnessesSet };
+}
+/** Why a node's status doesn't match a pin, or null if it does. Known chain ids must come with their known genesis. */
+export function mismatch(pin, status) {
+    const chainId = typeof status.chain_id === "string" ? status.chain_id : undefined;
+    const genesis = typeof status.genesis_hash === "string" ? status.genesis_hash.toLowerCase() : undefined;
+    const prefix = typeof status.address_prefix === "string" ? status.address_prefix : undefined;
+    if (!chainId)
+        return "the node doesn't report a chain id";
+    if (pin.chainId && chainId !== pin.chainId)
+        return `the node is on chain "${chainId}", not "${pin.chainId}"`;
+    const wantGenesis = pin.genesisHash ?? KNOWN_GENESIS[chainId];
+    if (wantGenesis && genesis !== wantGenesis)
+        return `the node's "${chainId}" starts from genesis ${genesis ?? "(none reported)"}, not ${wantGenesis}`;
+    if (pin.prefix && prefix && prefix !== pin.prefix)
+        return `the node uses "${prefix}1…" addresses, not "${pin.prefix}1…"`;
+    return null;
+}
+/**
+ * Why a node that says it's on blockula-1 is refused, or null: the pin (configured, or remembered
+ * from a configuration that named it) isn't that chain. A node that reports blockula-1 is never
+ * trusted on first use, as the CLI doesn't (`cli_net`): set BLOCKULA_CHAIN_ID=blockula-1 to mean it.
+ * (A pin on another chain is refused by `mismatch` first, in its own words.)
+ */
+export function unpinnedBlockula1(pin, status) {
+    if (status.chain_id !== BLOCKULA_1 || pin.chainId === BLOCKULA_1)
+        return null;
+    return `the node says it's on ${BLOCKULA_1}, and this MCP isn't pinned to that chain. If that's the chain you mean, the user sets BLOCKULA_CHAIN_ID=${BLOCKULA_1}`;
+}
+/** The pin after a first status: every field the node reported that wasn't pinned yet. */
+export function completePin(pin, status) {
+    return {
+        chainId: pin.chainId ?? (typeof status.chain_id === "string" ? status.chain_id : undefined),
+        genesisHash: pin.genesisHash ?? (typeof status.genesis_hash === "string" ? status.genesis_hash.toLowerCase() : undefined),
+        prefix: pin.prefix ?? (typeof status.address_prefix === "string" ? status.address_prefix : undefined),
+    };
+}
+/** Chains remembered on first use, by network and node URL (BLOCKULA_HOME/known-chains.json). */
+export class KnownChains {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    all() {
+        try {
+            return existsSync(this.file) ? JSON.parse(readFileSync(this.file, "utf8")) : {};
+        }
+        catch {
+            throw new Error(`${this.file} is corrupt; fix or delete it (it pins which chain each node must be on)`);
+        }
+    }
+    static id(net) {
+        return `${net.key} ${net.rpc}`;
+    }
+    get(net) {
+        if (!net.remember)
+            return undefined;
+        const all = this.all();
+        const id = KnownChains.id(net);
+        if (all[id] !== undefined)
+            return all[id];
+        // A release before canonicalUrl kept a node's URL as it was typed (`custom https://Rpc.Example`):
+        // that entry is this node's under another spelling. Its pin holds, and moves to this spelling,
+        // so the node isn't pinned afresh on trust, and the entry an error names is the only one.
+        const old = Object.keys(all).filter((k) => {
+            const at = k.indexOf(" ");
+            return k !== id && at > 0 && k.slice(0, at) === net.key && canonicalUrl(k.slice(at + 1)) === net.rpc;
+        });
+        if (old.length === 0)
+            return undefined;
+        const pin = all[old[0]];
+        try {
+            this.write(id, pin, old);
+        }
+        catch {
+            /* the file can't be written: the pin still holds this session */
+        }
+        return pin;
+    }
+    save(net, pin) {
+        if (!net.remember)
+            return;
+        this.write(KnownChains.id(net), pin);
+    }
+    /** Genesis clocks are a property of the chain (its id and genesis hash), whichever node reported them. */
+    static clockId(chainId, genesisHash) {
+        return `clock ${chainId} ${genesisHash}`;
+    }
+    /** The genesis clock remembered for this chain (`clockFrom` of the first `/api/genesis` read for it). */
+    clock(net, chainId, genesisHash) {
+        if (!net.remember)
+            return undefined;
+        const c = this.all()[KnownChains.clockId(chainId, genesisHash)];
+        return clockFrom(c && typeof c === "object" ? { ...c, chain_id: chainId } : undefined, chainId);
+    }
+    saveClock(net, chainId, genesisHash, clock) {
+        if (!net.remember)
+            return;
+        this.write(KnownChains.clockId(chainId, genesisHash), { created_at_ms: clock.createdAtMs, block_time_ms: clock.blockTimeMs });
+    }
+    /** Sets one entry (and drops the entries `drop` names, in the same write). */
+    write(key, value, drop = []) {
+        const all = this.all();
+        for (const k of drop)
+            delete all[k];
+        all[key] = value;
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileSync(this.file, JSON.stringify(all, null, 2), { mode: 0o600 });
+    }
+}
+/**
+ * The pin to enforce for a network: its configured pin, filled from what was remembered for it.
+ * A remembered field never overrides a configured one; a contradiction means the configuration
+ * changed, and the configuration wins. What was remembered for another chain id (the network was
+ * relaunched under a new one, which this release pins) isn't used at all: the new chain is
+ * pinned on first use instead of refused for the old one's genesis.
+ */
+export function effectivePin(net, remembered) {
+    const r = remembered && (!net.pin.chainId || !remembered.chainId || remembered.chainId === net.pin.chainId) ? remembered : undefined;
+    return { chainId: net.pin.chainId ?? r?.chainId, genesisHash: net.pin.genesisHash ?? r?.genesisHash, prefix: net.pin.prefix ?? r?.prefix };
+}
+/**
+ * The error an agent sees when a node is on the wrong chain: what happened and what the user can
+ * do. `relaunched` is false for a node whose chain can't be pinned at all (`unusableChain`):
+ * forgetting what was remembered wouldn't help there.
+ */
+export function mismatchError(net, why, knownChainsFile, relaunched = true) {
+    const fix = !relaunched
+        ? ""
+        : net.remember
+            ? ` If this network was relaunched on purpose, the user can remove its entry ("${KnownChains.id(net)}") from ${knownChainsFile}, or set BLOCKULA_GENESIS_HASH.`
+            : net.key === "local"
+                ? " A reset dev chain starts from a new genesis: call start_dev_node to use the one running now."
+                : "";
+    return new Error(`Refusing ${net.rpc} (${net.label}): ${why}. Nothing was signed or sent.${fix}`);
+}

package/dist/release.d.ts

@@ -0,0 +1,79 @@
+export declare const REPO = "jackdishman/blockula";
+/**
+ * BLAKE3 of the release public key (docs/OPERATIONS.md "The release key"). Empty until the key
+ * ceremony fills it in, together with scripts/install.sh's and node/src/release_cli.rs's
+ * BUILTIN_KEY_ID (a test keeps the three equal); BLOCKULA_RELEASE_KEY_ID sets it meanwhile.
+ */
+export declare const RELEASE_KEY_ID = "";
+/** The release key id pin `blockula release install` writes (release_cli.rs PIN_FILE), in $BLOCKULA_HOME. */
+export declare const PIN_FILE = "release-key-id";
+/** Where install_node puts the node binary, and where `blockula release install` and install.sh put theirs (never overwritten by install_node). */
+export declare function binPaths(home: string): {
+    mcp: string;
+    cli: string;
+};
+/** A node binary the MCP could run, and what its `--version` printed (undefined: it didn't run). */
+export interface NodeBinary {
+    path: string;
+    version?: string;
+}
+/**
+ * The node binary start_dev_node and summon_chain run when BLOCKULA_BIN isn't set (audit
+ * review-r4-supply-3). `found` lists the installed ones, `blockula release install`'s first (it was
+ * checked against the pinned key), then install_node's. The first whose `--version` is this MCP's
+ * wins; else the first that runs; else the first; with none, `blockula` from PATH. `matches` says
+ * whether it's this MCP's version, so a stale binary is never run without saying so.
+ */
+export declare function pickNodeBinary(found: NodeBinary[], mcpVersion: string): NodeBinary & {
+    matches: boolean;
+};
+/**
+ * The release key id pinned in `file` (`blockula release pin` / the first `release install`), or
+ * null if there's no pin. Same rules as release_cli.rs read_pin: one 64-hex key id (any case,
+ * surrounding whitespace ignored), never ignored when it's malformed, and refused when the group
+ * or others can write it (they could have swapped the key it vouches for).
+ */
+export declare function readReleasePin(file: string): string | null;
+/** A release tag. Only these are installed: `v*` tags are admin-only (deploy/github/ruleset-tags.json). */
+export declare const RELEASE_TAG: RegExp;
+/** The first line of a release's checksums.txt, before the tag (scripts/release-checksums.sh). */
+export declare const TAG_LINE_PREFIX = "# blockula-release ";
+/**
+ * The release key id to trust: the one pinned on this machine (`blockula release install`'s pin,
+ * `pinned`, read from `pinFile` by readReleasePin), BLOCKULA_RELEASE_KEY_ID (from an independent
+ * channel) or the one built in. Every one that's set must be the same key: a mismatch means one of
+ * them isn't genuine (or the pin moved by a rotation this MCP predates: update the MCP).
+ */
+export declare function releaseKeyIdFrom(given: string | undefined, builtIn: string, pinned?: string | null, pinFile?: string): string;
+/** The tag GitHub's /releases/latest redirected to (the final URL, …/releases/tag/<tag>). */
+export declare function latestTagFrom(finalUrl: string): string;
+/** Throws unless `blockula --version` printed release `tag`'s version. */
+export declare function checkBinaryVersion(versionOutput: string, tag: string): void;
+/** Throws unless checksums.txt names release `tag` on its first line. */
+export declare function checkTagLine(sums: Buffer, tag: string): void;
+export interface ReleaseDeps {
+    /** GET a release file; `null` if it doesn't exist (404). */
+    download(url: string): Promise<Buffer | null>;
+    /**
+     * Runs `gh attestation verify` on the archive's bytes, requiring provenance from `refs/tags/<tag>`:
+     * `"ok"`, `"failed"` (with the reason), or `"unavailable"` (no gh, or not logged in).
+     */
+    attest(archive: Buffer, name: string, tag: string): Promise<{
+        result: "ok" | "failed" | "unavailable";
+        detail?: string;
+    }>;
+}
+export interface VerifiedRelease {
+    archive: Buffer;
+    sha256: string;
+    /** What proved the release genuine (empty: only the checksum). */
+    verified: string[];
+    /** Shown to the user as-is. */
+    warning?: string;
+}
+/** Downloads `asset` from `base` (release `tag`'s download URL) and checks it as described above. Throws instead of returning anything unverified that must not be installed. The caller still checks the binary's `--version` (checkBinaryVersion). */
+export declare function fetchVerifiedRelease(base: string, asset: string, opts: {
+    releaseKeyId: string;
+    requireVerify: boolean;
+    tag: string;
+}, deps: ReleaseDeps): Promise<VerifiedRelease>;

package/dist/release.js

@@ -0,0 +1,193 @@
+// install_node's checks on a release download, the same as scripts/install.sh (docs/OPERATIONS.md
+// "Releases"):
+//   0. The version (a vX.Y.Z tag; `latest` is resolved to its tag first) is bound to everything
+//      below: checksums.txt must name it on its first line ("# blockula-release vX.Y.Z", covered
+//      by the signature), provenance must come from its tag (--source-ref), and install_node checks
+//      the extracted binary's `--version` before it installs it. An older, genuinely signed
+//      release served as the one asked for is refused (audit supply-chain-B-2).
+//   1. SHA-256 against the release's checksums.txt. Always. It only catches a corrupted download:
+//      whoever can change the release can change checksums.txt too.
+//   2. SLSA build provenance with a logged-in GitHub CLI (`gh attestation verify`): the archive was
+//      built by this repo's release workflow. A failed check is fatal; no gh skips it.
+//   3. The offline ML-DSA-65 signature on checksums.txt (checksums.txt.sig), verified with the
+//      SDK against the release key id. Once a key id is known (pinned in
+//      $BLOCKULA_HOME/release-key-id by `blockula release install`, built in, or
+//      BLOCKULA_RELEASE_KEY_ID; all that are set must agree), every release must carry a valid
+//      signature: a missing or invalid .sig is fatal. Leaving the .sig out is exactly what a
+//      compromised GitHub account or release workflow would do, and it can't forge the offline
+//      signature (audit F69). With no key id (before the key ceremony, nothing pinned) there's
+//      nothing to check it against, so it's skipped.
+// install_node installs to a path of its own ($BLOCKULA_HOME/mcp-bin/blockula), never over the
+// binary `blockula release install` puts in $BLOCKULA_HOME/bin (audit
+// review-r3-integrate-compose-1).
+// The checks add up (AND): provenance and the signature each refuse a release they fail. If
+// neither ran, the result says so loudly. BLOCKULA_REQUIRE_VERIFY=1 refuses a release it can only
+// checksum, and once a key id is known it requires provenance too (both checks).
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { verifyReleaseSignature } from "@blockula/sdk";
+export const REPO = "jackdishman/blockula";
+/**
+ * BLAKE3 of the release public key (docs/OPERATIONS.md "The release key"). Empty until the key
+ * ceremony fills it in, together with scripts/install.sh's and node/src/release_cli.rs's
+ * BUILTIN_KEY_ID (a test keeps the three equal); BLOCKULA_RELEASE_KEY_ID sets it meanwhile.
+ */
+export const RELEASE_KEY_ID = "";
+/** The release key id pin `blockula release install` writes (release_cli.rs PIN_FILE), in $BLOCKULA_HOME. */
+export const PIN_FILE = "release-key-id";
+/** Where install_node puts the node binary, and where `blockula release install` and install.sh put theirs (never overwritten by install_node). */
+export function binPaths(home) {
+    return { mcp: join(home, "mcp-bin", "blockula"), cli: join(home, "bin", "blockula") };
+}
+/**
+ * The node binary start_dev_node and summon_chain run when BLOCKULA_BIN isn't set (audit
+ * review-r4-supply-3). `found` lists the installed ones, `blockula release install`'s first (it was
+ * checked against the pinned key), then install_node's. The first whose `--version` is this MCP's
+ * wins; else the first that runs; else the first; with none, `blockula` from PATH. `matches` says
+ * whether it's this MCP's version, so a stale binary is never run without saying so.
+ */
+export function pickNodeBinary(found, mcpVersion) {
+    const same = found.find((b) => b.version === `blockula ${mcpVersion}`);
+    if (same)
+        return { ...same, matches: true };
+    return { ...(found.find((b) => b.version !== undefined) ?? found[0] ?? { path: "blockula" }), matches: false };
+}
+/**
+ * The release key id pinned in `file` (`blockula release pin` / the first `release install`), or
+ * null if there's no pin. Same rules as release_cli.rs read_pin: one 64-hex key id (any case,
+ * surrounding whitespace ignored), never ignored when it's malformed, and refused when the group
+ * or others can write it (they could have swapped the key it vouches for).
+ */
+export function readReleasePin(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw new Error(`reading ${file}: ${e.message}`);
+    }
+    if (process.platform !== "win32") {
+        const mode = statSync(file).mode;
+        if (mode & 0o022)
+            throw new Error(`${file} is writable by others (mode ${(mode & 0o777).toString(8)}), so it can't vouch for a release key: chmod 644 it once you've checked it holds your key id; not installing`);
+    }
+    const k = text.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(k))
+        throw new Error(`${file} isn't a release key id pin: fix it or remove it; not installing`);
+    return k;
+}
+/** A release tag. Only these are installed: `v*` tags are admin-only (deploy/github/ruleset-tags.json). */
+export const RELEASE_TAG = /^v\d+\.\d+\.\d+$/;
+/** The first line of a release's checksums.txt, before the tag (scripts/release-checksums.sh). */
+export const TAG_LINE_PREFIX = "# blockula-release ";
+/**
+ * The release key id to trust: the one pinned on this machine (`blockula release install`'s pin,
+ * `pinned`, read from `pinFile` by readReleasePin), BLOCKULA_RELEASE_KEY_ID (from an independent
+ * channel) or the one built in. Every one that's set must be the same key: a mismatch means one of
+ * them isn't genuine (or the pin moved by a rotation this MCP predates: update the MCP).
+ */
+export function releaseKeyIdFrom(given, builtIn, pinned = null, pinFile = PIN_FILE) {
+    const norm = (k, what) => {
+        const v = (k ?? "").trim().toLowerCase();
+        if (v && !/^[0-9a-f]{64}$/.test(v))
+            throw new Error(`${what} must be 64 hex characters`);
+        return v;
+    };
+    const g = norm(given, "BLOCKULA_RELEASE_KEY_ID");
+    const b = norm(builtIn, "the built-in release key id");
+    const p = norm(pinned, `the release key id pinned in ${pinFile}`);
+    if (p && g && g !== p)
+        throw new Error(`the release key id pinned in ${pinFile} is ${p}, not BLOCKULA_RELEASE_KEY_ID (${g}); not installing. A new release key is accepted only through a rotation statement the pinned key signed (blockula release pin --key-id <new> --rotation …, docs/OPERATIONS.md "The release key").`);
+    if (p && b && b !== p)
+        throw new Error(`this MCP was built with release key ${b}, but ${pinFile} pins ${p}; not installing. One of them isn't genuine, or the key was rotated after this MCP was released: check the pin (blockula release pin) against SECURITY.md and your operators' channel, and update the MCP.`);
+    if (g && b && g !== b)
+        throw new Error(`this MCP trusts release key ${b}, which isn't BLOCKULA_RELEASE_KEY_ID (${g}); not installing. Check both against SECURITY.md and the website.`);
+    return p || g || b;
+}
+/** The tag GitHub's /releases/latest redirected to (the final URL, …/releases/tag/<tag>). */
+export function latestTagFrom(finalUrl) {
+    const m = /\/releases\/tag\/([^/?#]+)$/.exec(finalUrl);
+    const tag = m ? decodeURIComponent(m[1]) : "";
+    if (!RELEASE_TAG.test(tag))
+        throw new Error(`the latest release (${finalUrl}) isn't a release tag (vX.Y.Z); pass a version`);
+    return tag;
+}
+/** Throws unless `blockula --version` printed release `tag`'s version. */
+export function checkBinaryVersion(versionOutput, tag) {
+    const got = versionOutput.trim();
+    if (got !== `blockula ${tag.slice(1)}`)
+        throw new Error(`the downloaded binary is ${got || "unrunnable here"}, not ${tag.slice(1)}; not installing`);
+}
+/** Throws unless checksums.txt names release `tag` on its first line. */
+export function checkTagLine(sums, tag) {
+    const first = sums.toString("utf8").split("\n", 1)[0];
+    if (first === TAG_LINE_PREFIX + tag)
+        return;
+    if (first.startsWith(TAG_LINE_PREFIX))
+        throw new Error(`this checksums.txt is for ${first.slice(TAG_LINE_PREFIX.length)}, not ${tag}: an older or other release served as the one asked for; not installing`);
+    throw new Error(`this checksums.txt names no release (releases before v0.5.0 don't), so it can't be bound to ${tag}; not installing`);
+}
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+/** Downloads `asset` from `base` (release `tag`'s download URL) and checks it as described above. Throws instead of returning anything unverified that must not be installed. The caller still checks the binary's `--version` (checkBinaryVersion). */
+export async function fetchVerifiedRelease(base, asset, opts, deps) {
+    if (!RELEASE_TAG.test(opts.tag))
+        throw new Error(`a release is a vX.Y.Z tag, got ${opts.tag}`);
+    const [archive, sums] = await Promise.all([deps.download(`${base}/${asset}`), deps.download(`${base}/checksums.txt`)]);
+    if (!archive)
+        throw new Error(`${asset} isn't in this release`);
+    if (!sums)
+        throw new Error("this release has no checksums.txt; not installing");
+    // 0. The release checksums.txt names (signed with it, below).
+    checkTagLine(sums, opts.tag);
+    // 1. Checksum.
+    const expected = sums.toString("utf8").split("\n").map((l) => l.trim().split(/\s+/)).find(([, f]) => f === asset)?.[0];
+    const actual = sha256(archive);
+    if (!expected || expected !== actual)
+        throw new Error(`checksum mismatch for ${asset}; not installing`);
+    const verified = [];
+    // 2. Build provenance.
+    const att = await deps.attest(archive, asset, opts.tag);
+    if (att.result === "failed")
+        throw new Error(`build provenance check FAILED for ${asset} (not built by the release workflow from tag ${opts.tag}); not installing${att.detail ? ` (${att.detail.trim().split("\n")[0]})` : ""}. Releases up to v0.4.x predate provenance and have no attestation.`);
+    if (att.result === "ok")
+        verified.push(`build provenance (GitHub attestation, ${REPO} release workflow, tag ${opts.tag})`);
+    // 3. Release signature, against the pinned key id (never one taken from the download). Required
+    // once a key id is known.
+    if (opts.releaseKeyId) {
+        const sigFile = await deps.download(`${base}/checksums.txt.sig`);
+        if (!sigFile) {
+            throw new Error(`this release has no checksums.txt.sig, but releases are signed offline with the release key ${opts.releaseKeyId.slice(0, 16)}…; not installing. An unsigned release is what a compromised GitHub account or release workflow would publish.`);
+        }
+        let sig;
+        try {
+            sig = JSON.parse(sigFile.toString("utf8"));
+        }
+        catch {
+            throw new Error("checksums.txt.sig isn't valid JSON; not installing");
+        }
+        try {
+            verifyReleaseSignature(sig, new Uint8Array(sums), opts.releaseKeyId);
+        }
+        catch (e) {
+            throw new Error(`checksums.txt signature check FAILED: ${e.message}; not installing`);
+        }
+        verified.push(`release signature (ML-DSA-65 key ${opts.releaseKeyId.slice(0, 16)}…)`);
+        if (opts.requireVerify && att.result !== "ok") {
+            throw new Error("BLOCKULA_REQUIRE_VERIFY=1 requires build provenance as well as the release signature, and provenance couldn't be checked (log in to the GitHub CLI with `gh auth login`); not installing");
+        }
+    }
+    if (verified.length)
+        return { archive, sha256: actual, verified };
+    if (opts.requireVerify)
+        throw new Error("BLOCKULA_REQUIRE_VERIFY=1 and only the checksum could be verified (log in to the GitHub CLI with `gh auth login`, or set the release key id); not installing");
+    return {
+        archive,
+        sha256: actual,
+        verified,
+        warning: "ONLY THE CHECKSUM WAS VERIFIED. That proves the download wasn't corrupted, not that this release is genuine: anyone who can change the release can change checksums.txt too. " +
+            "To verify it, log in to the GitHub CLI (gh auth login) and install again, or check it by hand (docs/OPERATIONS.md \"Releases\"). Set BLOCKULA_REQUIRE_VERIFY=1 to refuse unverified installs. Don't run a validator on an unverified binary.",
+    };
+}