@blockula/mcp 0.2.0 → 0.5.1

package/dist/network.d.ts

@@ -0,0 +1,101 @@
+export type NetworkKey = "mainnet" | "testnet" | "local" | "custom";
+/** What the node must report in `/api/status`. */
+export interface Pin {
+    chainId?: string;
+    genesisHash?: string;
+    prefix?: string;
+}
+export interface Network {
+    key: NetworkKey;
+    label: string;
+    rpc: string;
+    pin: Pin;
+    /** Real money: the copy and the defaults get stricter. */
+    mainnet: boolean;
+    /** Remember the first chain this node reports (TOFU) across restarts. Off for local dev chains, which `--reset` replaces. */
+    remember: boolean;
+    /**
+     * Independent nodes of the same chain (BLOCKULA_WITNESSES, comma-separated): names that end up
+     * in a signature are proven against them (audit gap-7-1). Empty: a name is the node's word.
+     */
+    witnesses: string[];
+}
+export declare const LOCAL_RPC = "http://localhost:7070";
+export declare const TESTNET_RPC = "https://blockula-testnet.fly.dev";
+/** Public mainnet RPC endpoints, run by independent operators. Empty until launch: set BLOCKULA_RPC. */
+export declare const MAINNET_RPCS: string[];
+/**
+ * Chains whose genesis is known: any node claiming one of these chain ids must report this
+ * genesis hash, whatever network it was configured as. `blockula-1`'s hash is added here once the
+ * genesis ceremony has produced it (docs/GENESIS_CEREMONY.md).
+ */
+export declare const KNOWN_GENESIS: Record<string, string>;
+/**
+ * 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 declare const KNOWN_CLOCKS: Record<string, GenesisClock>;
+/** A chain's genesis clock: its genesis.json's `created_at_ms` and `block_time_ms`. */
+export interface GenesisClock {
+    createdAtMs: number;
+    blockTimeMs: number;
+}
+/**
+ * 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 declare function clockFrom(genesis: unknown, chainId: string): GenesisClock | undefined;
+/** The networks the MCP knows by name. */
+export declare const KNOWN_NETWORKS: Record<Exclude<NetworkKey, "custom">, Omit<Network, "rpc" | "witnesses"> & {
+    rpc?: string;
+}>;
+/** A node URL: http(s) without credentials; plain http only on this machine or a private network. */
+export declare function checkRpcUrl(u: string, what?: string): string;
+/** `--network <name>` or `--network=<name>` from the command line. */
+export declare function networkArg(argv: string[]): string | 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 declare function resolveNetwork(env: Record<string, string | undefined>, argv?: string[]): Network;
+/** 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 declare function mismatch(pin: Pin, status: {
+    chain_id?: unknown;
+    genesis_hash?: unknown;
+    address_prefix?: unknown;
+}): string | null;
+/** The pin after a first status: every field the node reported that wasn't pinned yet. */
+export declare function completePin(pin: Pin, status: {
+    chain_id?: unknown;
+    genesis_hash?: unknown;
+    address_prefix?: unknown;
+}): Pin;
+/** Chains remembered on first use, by network and node URL (BLOCKULA_HOME/known-chains.json). */
+export declare class KnownChains {
+    readonly file: string;
+    constructor(file: string);
+    private all;
+    static id(net: Network): string;
+    get(net: Network): Pin | undefined;
+    save(net: Network, pin: Pin): void;
+    /** Genesis clocks are a property of the chain (its id and genesis hash), whichever node reported them. */
+    static clockId(chainId: string, genesisHash: string): string;
+    /** The genesis clock remembered for this chain (`clockFrom` of the first `/api/genesis` read for it). */
+    clock(net: Network, chainId: string, genesisHash: string): GenesisClock | undefined;
+    saveClock(net: Network, chainId: string, genesisHash: string, clock: GenesisClock): void;
+    private write;
+}
+/**
+ * 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 declare function effectivePin(net: Network, remembered?: Pin): Pin;
+/** The error an agent sees when a node is on the wrong chain: what happened and what the user can do. */
+export declare function mismatchError(net: Network, why: string, knownChainsFile: string): Error;

package/dist/network.js

@@ -0,0 +1,231 @@
+// 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.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export const LOCAL_RPC = "http://localhost:7070";
+export const TESTNET_RPC = "https://blockula-testnet.fly.dev";
+/** Public mainnet RPC endpoints, run by independent operators. Empty until launch: set BLOCKULA_RPC. */
+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. `blockula-1`'s hash is added here once the
+ * genesis ceremony has produced it (docs/GENESIS_CEREMONY.md).
+ */
+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 = {
+    mainnet: { key: "mainnet", label: "Blockula mainnet", rpc: MAINNET_RPCS[0], pin: { chainId: "blockula-1", prefix: "boo" }, mainnet: true, remember: true },
+    // 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" }, mainnet: false, remember: true },
+    local: { key: "local", label: "local dev node", rpc: LOCAL_RPC, pin: {}, mainnet: false, remember: false },
+};
+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: http(s) without credentials; 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.protocol === "http:" && !isPrivateUrl(u))
+        throw new Error(`${what} must use https unless the node is on this machine or a private network: ${u}`);
+    return u.replace(/\/+$/, "");
+}
+/** `--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 && !["mainnet", "testnet", "local", "custom"].includes(named))
+        throw new Error(`unknown network "${named}" (mainnet, testnet, local or custom)`);
+    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 && n.rpc === rpc)?.key ?? (isLocalUrl(rpc) ? "local" : "custom");
+    else
+        key = "testnet";
+    const base = key === "custom" ? { key, label: "custom node", pin: {}, mainnet: false, remember: true } : KNOWN_NETWORKS[key];
+    const url = rpc ?? base.rpc;
+    if (!url) {
+        throw new Error(key === "mainnet" ? "no public mainnet RPC is built in yet: set BLOCKULA_RPC to a mainnet node you trust" : "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 (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;
+    // A real-money chain is never the local or a custom network by accident.
+    const mainnet = base.mainnet || pin.chainId === KNOWN_NETWORKS.mainnet.pin.chainId;
+    const witnesses = (env.BLOCKULA_WITNESSES ?? "").split(",").map((w) => w.trim()).filter(Boolean).map((w) => checkRpcUrl(w, "BLOCKULA_WITNESSES"));
+    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, mainnet, remember: base.remember, witnesses };
+}
+/** 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;
+}
+/** 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) {
+        return net.remember ? this.all()[KnownChains.id(net)] : undefined;
+    }
+    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 });
+    }
+    write(key, value) {
+        const all = this.all();
+        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. */
+export function mismatchError(net, why, knownChainsFile) {
+    const fix = 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.",
+    };
+}

package/dist/signed.d.ts

@@ -0,0 +1,31 @@
+/** What tx_status needs about a tx this MCP signed. */
+export interface SignedTx {
+    /** The last height it can execute at, as signed. */
+    valid_until: number;
+    /** The account it acts from, and its nonce: at most one tx per (account, nonce) executes. */
+    account: string;
+    nonce: number;
+    /** The chain it was signed for (the tx's chain_id and genesis_hash). Records written before these were kept have neither. */
+    chain_id?: string;
+    genesis_hash?: string;
+}
+/** How many signed txs are kept (oldest dropped first). */
+export declare const MAX_SIGNED = 500;
+/** Whether a record was signed for this chain: a record that doesn't name its chain never is. */
+export declare function onChain(tx: SignedTx, chain: {
+    chainId?: string;
+    genesisHash?: string;
+}): boolean;
+export declare class SignedTxs {
+    readonly file: string;
+    readonly max: number;
+    constructor(file: string, max?: number);
+    private read;
+    private static copy;
+    /** The record of a tx this MCP signed, if it's still kept. */
+    get(id: string): SignedTx | undefined;
+    /** The other txs this MCP signed for the same chain with the same (account, nonce), oldest first: at most one of them all executes. */
+    sameSlot(mine: SignedTx, except: string): string[];
+    /** Records a tx about to be submitted. Written whole (temp file, then rename). */
+    add(id: string, tx: SignedTx): void;
+}