@mikeargento/bitgraph-mcp 0.1.1

package/src/__tests__/format.test.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { createHash } from "node:crypto";
+import { toUrlSafeB64 } from "../encoding.js";
+import { capJson, proofUrl, renderProofMarkdown, renderRecordMarkdown } from "../format.js";
+import type { ProofDetailResponse } from "../types.js";
+
+const DIGEST = createHash("sha256").update("bitgraph").digest("base64");
+const EPOCH = createHash("sha256").update("epoch").digest("base64");
+
+test("proofUrl pins a position with url-safe encodings", () => {
+  const url = proofUrl("https://bitgraph.ing", DIGEST, "42", EPOCH);
+  assert.ok(url.startsWith(`https://bitgraph.ing/proof/${encodeURIComponent(toUrlSafeB64(DIGEST))}`));
+  assert.ok(url.includes("counter=42"));
+  assert.ok(url.includes(`epoch=${encodeURIComponent(toUrlSafeB64(EPOCH))}`));
+  assert.ok(!url.includes("+") && !url.includes("=="), "no raw standard-b64 leaks into the URL");
+});
+
+test("proofUrl without a position has no query string", () => {
+  assert.ok(!proofUrl("https://bitgraph.ing", DIGEST).includes("?"));
+});
+
+test("record markdown mentions again=true only when something was already on record", () => {
+  const base = {
+    digest: toUrlSafeB64(DIGEST),
+    counter: "7",
+    epoch: toUrlSafeB64(EPOCH),
+    total_positions: 1,
+    proof_url: "https://bitgraph.ing/proof/x",
+  };
+  const fresh = renderRecordMarkdown([{ ...base, path: "/a", outcome: "recorded" }]);
+  assert.ok(!fresh.includes("again=true"));
+  const mixed = renderRecordMarkdown([
+    { ...base, path: "/a", outcome: "recorded" },
+    { ...base, path: "/b", outcome: "on record" },
+  ]);
+  assert.ok(mixed.includes("again=true"));
+  assert.ok(mixed.startsWith("1 recorded, 1 already on record."));
+});
+
+test("proof markdown states the window as between lower and upper", () => {
+  const detail: ProofDetailResponse = {
+    proofs: [{ proof: { artifact: { digestB64: DIGEST }, commit: { counter: "42", epochId: EPOCH } } }],
+    positions: [{ counter: "42", epoch: toUrlSafeB64(EPOCH), lowerTime: null, upperTime: null }],
+    causalWindow: {
+      anchorBefore: { blockTime: "2026-07-01T00:00:00.000Z", blockNumber: 100 },
+      anchorAfter: { blockTime: "2026-07-01T00:00:12.000Z", blockNumber: 101 },
+    },
+  };
+  const md = renderProofMarkdown(detail, "https://bitgraph.ing");
+  assert.ok(
+    md.includes("BitGraphed between 2026-07-01T00:00:00.000Z (Ethereum block 100) and 2026-07-01T00:00:12.000Z (block 101)"),
+    md
+  );
+  assert.ok(md.includes("# BitGraph #42"));
+});
+
+test("capJson elides large attestation reports before truncating", () => {
+  const value = {
+    proof: { environment: { attestation: { reportB64: "A".repeat(40_000) } }, note: "keep me" },
+  };
+  const { text, truncated } = capJson(value);
+  assert.ok(truncated);
+  assert.ok(text.includes("elided 40000 base64 chars"));
+  assert.ok(text.includes("keep me"));
+  assert.ok(text.length <= 25_000 + 200);
+});

package/src/__tests__/tools.test.ts

@@ -0,0 +1,334 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * End-to-end tool tests: a real MCP client drives the real server over an
+ * in-memory transport, against a mock bitgraph.ing that asserts the exact
+ * wire shapes. No real ledger writes ever happen here.
+ */
+
+import { test, before, after } from "node:test";
+import { strict as assert } from "node:assert";
+import { createHash } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import { writeFile, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { buildServer } from "../server.js";
+import { toUrlSafeB64 } from "../encoding.js";
+
+interface Recorded {
+  method: string;
+  path: string;
+  headers: Record<string, string | string[] | undefined>;
+  body: unknown;
+}
+
+const requests: Recorded[] = [];
+let mock: Server;
+let fileA = "";
+let fileB = "";
+let fileC = "";
+let digestA = ""; // standard b64 of fileA bytes
+let digestB = "";
+let commitMode: "ok" | "429" | "short" = "ok";
+const EPOCH = createHash("sha256").update("test-epoch").digest("base64");
+let mintCounter = 100;
+
+function proofFor(digestB64: string): Record<string, unknown> {
+  mintCounter += 2; // slot consumes one position, commit lands on the next
+  return {
+    version: "bitgraph/1",
+    artifact: { hashAlg: "sha256", digestB64 },
+    commit: { counter: String(mintCounter), epochId: EPOCH },
+    signer: { publicKeyB64: "pk", signatureB64: "sig" },
+    environment: { enforcement: "measured-tee", measurement: "m" },
+  };
+}
+
+before(async () => {
+  const dir = await mkdtemp(join(tmpdir(), "bitgraph-mcp-e2e-"));
+  fileA = join(dir, "a.txt");
+  fileB = join(dir, "b.txt");
+  fileC = join(dir, "c.txt");
+  await writeFile(fileA, "alpha bytes");
+  await writeFile(fileB, "beta bytes");
+  await writeFile(fileC, "gamma bytes");
+  digestA = createHash("sha256").update("alpha bytes").digest("base64");
+  digestB = createHash("sha256").update("beta bytes").digest("base64");
+
+  mock = createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf8");
+      const body = raw.length > 0 ? JSON.parse(raw) : undefined;
+      const url = new URL(req.url ?? "/", "http://localhost");
+      requests.push({ method: req.method ?? "", path: url.pathname + url.search, headers: req.headers, body });
+
+      const send = (status: number, payload: unknown) => {
+        res.writeHead(status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(payload));
+      };
+
+      if (url.pathname === "/api/proofs/batch") {
+        // fileA is already on record (two positions); fileB is not.
+        const digests = (body as { digests: string[] }).digests;
+        const results: Record<string, { proofs: Array<{ proof: unknown }> }> = {};
+        for (const d of digests) {
+          if (d === toUrlSafeB64(digestA)) {
+            results[d] = {
+              proofs: [
+                { proof: { artifact: { digestB64: digestA }, commit: { counter: "10", epochId: EPOCH } } },
+                { proof: { artifact: { digestB64: digestA }, commit: { counter: "55", epochId: EPOCH } } },
+              ],
+            };
+          } else {
+            results[d] = { proofs: [] };
+          }
+        }
+        send(200, { results });
+      } else if (url.pathname === "/api/commit") {
+        if (commitMode === "429") {
+          res.writeHead(429, { "Content-Type": "application/json", "Retry-After": "30" });
+          res.end(JSON.stringify({ error: "Rate limit exceeded: per-client proof rate limit exceeded" }));
+          return;
+        }
+        const digests = (body as { digests: Array<{ digestB64: string }> }).digests;
+        if (commitMode === "short") {
+          send(200, digests.slice(1).map((d) => proofFor(d.digestB64)));
+          return;
+        }
+        send(200, digests.map((d) => proofFor(d.digestB64)));
+      } else if (url.pathname.startsWith("/api/proofs/digest/")) {
+        const digest = decodeURIComponent(url.pathname.split("/").pop() ?? "");
+        if (digest === toUrlSafeB64(digestA)) {
+          send(200, {
+            proofs: [{ proof: { artifact: { digestB64: digestA }, commit: { counter: "10", epochId: EPOCH } } }],
+            positions: [
+              { counter: "10", epoch: toUrlSafeB64(EPOCH), lowerTime: "2026-07-01T00:00:00.000Z", upperTime: "2026-07-01T00:00:12.000Z" },
+              { counter: "55", epoch: toUrlSafeB64(EPOCH), lowerTime: null, upperTime: null },
+            ],
+            causalWindow: {
+              anchorBefore: { blockTime: "2026-07-01T00:00:00.000Z", blockNumber: 1 },
+              anchorAfter: { blockTime: "2026-07-01T00:00:12.000Z", blockNumber: 2 },
+            },
+          });
+        } else {
+          send(200, { proofs: [] });
+        }
+      } else if (url.pathname === "/api/search") {
+        const q = url.searchParams.get("q") ?? "";
+        if (q.replace(/[#,\s]/g, "") === "10") {
+          send(200, { found: true, digest: toUrlSafeB64(digestA), counter: "10" });
+        } else {
+          send(200, { found: false });
+        }
+      } else {
+        send(404, { error: "not found" });
+      }
+    });
+  });
+  await new Promise<void>((resolve) => mock.listen(0, "127.0.0.1", resolve));
+  const address = mock.address();
+  if (address === null || typeof address === "string") throw new Error("no port");
+  process.env["BITGRAPH_API_URL"] = `http://127.0.0.1:${address.port}`;
+  process.env["BITGRAPH_API_KEY"] = "test-key-123";
+});
+
+after(() => {
+  mock.close();
+  delete process.env["BITGRAPH_API_URL"];
+  delete process.env["BITGRAPH_API_KEY"];
+});
+
+async function connectedClient(): Promise<Client> {
+  const server = buildServer();
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: "test-client", version: "0.0.0" });
+  await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+  return client;
+}
+
+test("lists the three tools", async () => {
+  const client = await connectedClient();
+  const tools = await client.listTools();
+  const names = tools.tools.map((t) => t.name).sort();
+  assert.deepEqual(names, ["bitgraph_check", "bitgraph_get_proof", "bitgraph_record"]);
+});
+
+test("record dedups on-record files and mints only fresh ones", async () => {
+  const client = await connectedClient();
+  requests.length = 0;
+  const result = await client.callTool({
+    name: "bitgraph_record",
+    arguments: { paths: [fileA, fileB] },
+  });
+  assert.ok(!result.isError, JSON.stringify(result.content));
+
+  const commit = requests.find((r) => r.path === "/api/commit");
+  if (!commit) throw new Error("no commit request was sent");
+  const commitBody = commit.body as { digests: Array<{ digestB64: string; hashAlg: string }>; chainId: string };
+  assert.equal(commitBody.chainId, "bitgraph:main");
+  assert.deepEqual(commitBody.digests, [{ digestB64: digestB, hashAlg: "sha256" }], "only fileB minted, standard b64");
+  assert.equal(commit.headers["authorization"], "Bearer test-key-123", "api key forwarded");
+
+  const batch = requests.find((r) => r.path === "/api/proofs/batch");
+  if (!batch) throw new Error("no batch check preceded the commit");
+  const batchBody = batch.body as { digests: string[] };
+  assert.ok(batchBody.digests.every((d) => !d.includes("+") && !d.includes("=")), "check uses url-safe digests");
+
+  const structured = result.structuredContent as {
+    results: Array<{ path: string; outcome: string; counter: string | null }>;
+    summary: { recorded: number; on_record: number };
+  };
+  assert.equal(structured.summary.recorded, 1);
+  assert.equal(structured.summary.on_record, 1);
+  const a = structured.results.find((r) => r.path === fileA);
+  const b = structured.results.find((r) => r.path === fileB);
+  assert.equal(a?.outcome, "on record");
+  assert.equal(a?.counter, "10", "on-record outcome reports the EARLIEST position");
+  assert.equal(b?.outcome, "recorded");
+});
+
+test("record with again=true mints even on-record digests", async () => {
+  const client = await connectedClient();
+  requests.length = 0;
+  const result = await client.callTool({
+    name: "bitgraph_record",
+    arguments: { paths: [fileA], again: true },
+  });
+  assert.ok(!result.isError, JSON.stringify(result.content));
+  const commit = requests.find((r) => r.path === "/api/commit");
+  const commitBody = commit?.body as { digests: Array<{ digestB64: string }> };
+  assert.deepEqual(commitBody.digests.map((d) => d.digestB64), [digestA]);
+  const structured = result.structuredContent as {
+    results: Array<{ outcome: string; total_positions: number }>;
+  };
+  assert.equal(structured.results[0]?.outcome, "recorded");
+  assert.equal(structured.results[0]?.total_positions, 3, "two prior positions plus the new one");
+});
+
+test("check reports positions without ever committing", async () => {
+  const client = await connectedClient();
+  requests.length = 0;
+  const result = await client.callTool({
+    name: "bitgraph_check",
+    arguments: { paths: [fileB], digests: [toUrlSafeB64(digestA)] },
+  });
+  assert.ok(!result.isError, JSON.stringify(result.content));
+  assert.ok(!requests.some((r) => r.path === "/api/commit"), "check never commits");
+  const structured = result.structuredContent as {
+    results: Array<{ input: string; on_record: boolean; positions: unknown[] }>;
+  };
+  const a = structured.results.find((r) => r.input === toUrlSafeB64(digestA));
+  const b = structured.results.find((r) => r.input === fileB);
+  assert.equal(a?.on_record, true);
+  assert.equal(a?.positions.length, 2);
+  assert.equal(b?.on_record, false);
+});
+
+test("check rejects malformed digests with an actionable error", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({
+    name: "bitgraph_check",
+    arguments: { digests: ["zzz"] },
+  });
+  assert.ok(result.isError);
+  const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+  assert.ok(text.includes("not a base64 SHA-256 digest"));
+});
+
+test("get_proof by number resolves through search and renders the window", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({
+    name: "bitgraph_get_proof",
+    arguments: { number: "#10" },
+  });
+  assert.ok(!result.isError, JSON.stringify(result.content));
+  const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+  assert.ok(text.includes("# BitGraph #10"));
+  assert.ok(text.includes("BitGraphed between 2026-07-01T00:00:00.000Z"));
+  assert.ok(text.includes("Causal positions (2)"));
+  assert.ok(text.includes("/proof/"), "includes the proof page url");
+});
+
+test("get_proof for an unknown digest fails with guidance", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({
+    name: "bitgraph_get_proof",
+    arguments: { digest: toUrlSafeB64(digestB) },
+  });
+  assert.ok(result.isError);
+  const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+  assert.ok(text.includes("Not on record"));
+});
+
+test("get_proof requires exactly one selector", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({
+    name: "bitgraph_get_proof",
+    arguments: { digest: toUrlSafeB64(digestA), number: "10" },
+  });
+  assert.ok(result.isError);
+});
+
+test("commit failure labels unminted files as 'not recorded', never 'on record'", async () => {
+  const client = await connectedClient();
+  commitMode = "429";
+  try {
+    const result = await client.callTool({
+      name: "bitgraph_record",
+      arguments: { paths: [fileC] },
+    });
+    assert.ok(result.isError, "partial failure must be an error result");
+    const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+    assert.ok(text.includes("Retry after 30 seconds"), text);
+    assert.ok(text.includes("0 of 1"), text);
+    const structured = result.structuredContent as {
+      results: Array<{ outcome: string; proof_url: string | null; counter: string | null }>;
+      summary: { recorded: number; on_record: number; not_recorded: number };
+    };
+    assert.equal(structured.results[0]?.outcome, "not recorded");
+    assert.equal(structured.results[0]?.proof_url, null);
+    assert.equal(structured.summary.not_recorded, 1);
+    assert.equal(structured.summary.recorded, 0);
+    assert.equal(structured.summary.on_record, 0);
+  } finally {
+    commitMode = "ok";
+  }
+});
+
+test("a 200 with fewer proofs than digests is treated as a partial failure", async () => {
+  const client = await connectedClient();
+  commitMode = "short";
+  try {
+    const result = await client.callTool({
+      name: "bitgraph_record",
+      arguments: { paths: [fileC] },
+    });
+    assert.ok(result.isError, "shortfall must not reach the success path");
+    const structured = result.structuredContent as {
+      results: Array<{ outcome: string }>;
+    };
+    assert.equal(structured.results[0]?.outcome, "not recorded");
+    const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+    assert.ok(text.includes("fewer proofs than digests"), text);
+  } finally {
+    commitMode = "ok";
+  }
+});
+
+test("record surfaces unreadable paths before any network call", async () => {
+  const client = await connectedClient();
+  requests.length = 0;
+  const result = await client.callTool({
+    name: "bitgraph_record",
+    arguments: { paths: [fileA, "/definitely/missing/file.bin"] },
+  });
+  assert.ok(result.isError);
+  assert.equal(requests.length, 0, "no API call happened; nothing was minted");
+  const text = (result.content as Array<{ text: string }>)[0]?.text ?? "";
+  assert.ok(text.includes("nothing was recorded"));
+});

package/src/api.ts

@@ -0,0 +1,211 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * @mikeargento/bitgraph-mcp: HTTP client for the hosted BitGraph API.
+ *
+ * All recording goes through the website's /api/commit proxy rather than the
+ * TEE directly: the proxy is what maintains the per-position by-digest index
+ * that makes every causal position of a file discoverable afterward.
+ */
+
+import type {
+  BatchCheckResponse,
+  BitGraphProof,
+  ProofDetailResponse,
+  SearchResponse,
+} from "./types.js";
+
+export interface ApiConfig {
+  baseUrl: string;
+  apiKey?: string;
+}
+
+/** Read configuration from the environment at call time (testable via env). */
+export function configFromEnv(): ApiConfig {
+  const baseUrl = (process.env["BITGRAPH_API_URL"] ?? "https://bitgraph.ing").replace(/\/+$/, "");
+  const apiKey = process.env["BITGRAPH_API_KEY"];
+  return apiKey ? { baseUrl, apiKey } : { baseUrl };
+}
+
+/** Matches the website client: 50 digests per commit request (~1s of TEE work each). */
+export const COMMIT_CHUNK_SIZE = 50;
+/** Matches the batch endpoint's MAX_DIGESTS. */
+export const BATCH_CHECK_LIMIT = 500;
+
+const CHECK_TIMEOUT_MS = 30_000;
+const COMMIT_TIMEOUT_MS = 120_000;
+
+export class ApiError extends Error {
+  readonly status: number;
+  readonly retryAfterSec: number | null;
+
+  constructor(status: number, message: string, retryAfterSec: number | null = null) {
+    super(message);
+    this.status = status;
+    this.retryAfterSec = retryAfterSec;
+  }
+}
+
+async function parseError(res: Response): Promise<ApiError> {
+  let message = res.statusText || `HTTP ${res.status}`;
+  try {
+    const body = (await res.json()) as { error?: string };
+    if (typeof body.error === "string" && body.error.length > 0) message = body.error;
+  } catch {
+    /* non-JSON error body */
+  }
+  const retryAfterRaw = res.headers.get("retry-after");
+  const retryAfterSec = retryAfterRaw !== null ? Number.parseInt(retryAfterRaw, 10) : null;
+  return new ApiError(res.status, message, Number.isFinite(retryAfterSec) ? retryAfterSec : null);
+}
+
+/**
+ * Redirects are refused everywhere: an Authorization header must never follow
+ * one to a different host, and the canonical endpoint serves without them.
+ */
+function redirectHint(err: unknown): never {
+  if (err instanceof TypeError && /redirect/i.test(err.message)) {
+    throw new Error(
+      "The BitGraph endpoint redirected. Set BITGRAPH_API_URL to the canonical https://bitgraph.ing (apex, no www)."
+    );
+  }
+  throw err;
+}
+
+async function getJson<T>(config: ApiConfig, path: string, timeoutMs: number): Promise<T> {
+  const res = await fetch(`${config.baseUrl}${path}`, {
+    method: "GET",
+    redirect: "error",
+    signal: AbortSignal.timeout(timeoutMs),
+  }).catch(redirectHint);
+  if (!res.ok) throw await parseError(res);
+  return (await res.json()) as T;
+}
+
+async function postJson<T>(
+  config: ApiConfig,
+  path: string,
+  body: unknown,
+  timeoutMs: number,
+  authenticated: boolean
+): Promise<T> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (authenticated && config.apiKey) headers["Authorization"] = `Bearer ${config.apiKey}`;
+  const res = await fetch(`${config.baseUrl}${path}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    redirect: "error",
+    signal: AbortSignal.timeout(timeoutMs),
+  }).catch(redirectHint);
+  if (!res.ok) throw await parseError(res);
+  return (await res.json()) as T;
+}
+
+/**
+ * Look up which digests are on record. Input digests must be URL-safe base64;
+ * the response is keyed by the exact strings sent. Batches of up to 500.
+ */
+export async function batchCheck(
+  config: ApiConfig,
+  urlSafeDigests: readonly string[]
+): Promise<BatchCheckResponse> {
+  const merged: BatchCheckResponse = { results: {} };
+  for (let offset = 0; offset < urlSafeDigests.length; offset += BATCH_CHECK_LIMIT) {
+    const chunk = urlSafeDigests.slice(offset, offset + BATCH_CHECK_LIMIT);
+    const page = await postJson<BatchCheckResponse>(
+      config,
+      "/api/proofs/batch",
+      { digests: chunk },
+      CHECK_TIMEOUT_MS,
+      false
+    );
+    Object.assign(merged.results, page.results);
+  }
+  return merged;
+}
+
+/**
+ * Record digests at new causal positions. Input digests must be STANDARD
+ * base64 (as stored in proofs). Commits sequentially in chunks of 50, matching
+ * the website client; the TEE serializes commits anyway.
+ *
+ * On a mid-batch failure the error carries how many proofs were already
+ * minted (those are permanent); the caller must report partial results
+ * honestly rather than pretending all-or-nothing.
+ */
+export async function commitDigests(
+  config: ApiConfig,
+  standardDigests: readonly string[],
+  attribution?: { name?: string | undefined; title?: string | undefined; message?: string | undefined }
+): Promise<BitGraphProof[]> {
+  const proofs: BitGraphProof[] = [];
+  for (let offset = 0; offset < standardDigests.length; offset += COMMIT_CHUNK_SIZE) {
+    const chunk = standardDigests.slice(offset, offset + COMMIT_CHUNK_SIZE);
+    const body: Record<string, unknown> = {
+      digests: chunk.map((digestB64) => ({ digestB64, hashAlg: "sha256" })),
+      chainId: "bitgraph:main",
+    };
+    if (attribution) body["attribution"] = attribution;
+    try {
+      const raw = await postJson<BitGraphProof[] | BitGraphProof>(
+        config,
+        "/api/commit",
+        body,
+        COMMIT_TIMEOUT_MS,
+        true
+      );
+      proofs.push(...(Array.isArray(raw) ? raw : [raw]));
+    } catch (err) {
+      throw new PartialCommitError(proofs, standardDigests.length, err);
+    }
+  }
+  return proofs;
+}
+
+/** A commit batch failed partway: `minted` proofs are already permanent. */
+export class PartialCommitError extends Error {
+  readonly minted: BitGraphProof[];
+  readonly requested: number;
+  readonly cause2: unknown;
+
+  constructor(minted: BitGraphProof[], requested: number, cause: unknown) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(
+      `Recording stopped after ${minted.length} of ${requested} digests: ${reason}` +
+        (cause instanceof ApiError && cause.retryAfterSec !== null
+          ? ` (retry after ${cause.retryAfterSec}s)`
+          : "")
+    );
+    this.minted = minted;
+    this.requested = requested;
+    this.cause2 = cause;
+  }
+}
+
+/** Full detail for one digest: proof, all causal positions, anchor window. */
+export async function getProofDetail(
+  config: ApiConfig,
+  urlSafeDigest: string,
+  counter?: string,
+  urlSafeEpoch?: string
+): Promise<ProofDetailResponse> {
+  const params = new URLSearchParams();
+  if (counter !== undefined) params.set("counter", counter);
+  if (urlSafeEpoch !== undefined) params.set("epoch", urlSafeEpoch);
+  const query = params.size > 0 ? `?${params.toString()}` : "";
+  return getJson<ProofDetailResponse>(
+    config,
+    `/api/proofs/digest/${encodeURIComponent(urlSafeDigest)}${query}`,
+    CHECK_TIMEOUT_MS
+  );
+}
+
+/** Resolve a BitGraph number (or digest string) to a digest via /api/search. */
+export async function search(config: ApiConfig, q: string): Promise<SearchResponse> {
+  return getJson<SearchResponse>(
+    config,
+    `/api/search?q=${encodeURIComponent(q)}`,
+    CHECK_TIMEOUT_MS
+  );
+}

package/src/encoding.ts

@@ -0,0 +1,72 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * @mikeargento/bitgraph-mcp: digest encoding and file hashing.
+ *
+ * BitGraph uses two base64 forms for the same SHA-256 digest:
+ * standard base64 with padding inside proof objects and commit requests,
+ * URL-safe unpadded base64 in API lookups, S3 keys, and proof page URLs.
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+
+/** Standard base64 → URL-safe unpadded base64. */
+export function toUrlSafeB64(b64: string): string {
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * URL-safe base64 → standard base64 with padding.
+ * A no-op (apart from re-padding) when the input is already standard base64,
+ * so it is safe to call on either form.
+ */
+export function fromUrlSafeB64(urlSafe: string): string {
+  let b64 = urlSafe.replace(/-/g, "+").replace(/_/g, "/");
+  while (b64.length % 4 !== 0) b64 += "=";
+  return b64;
+}
+
+/** True if the string plausibly encodes 32 bytes of SHA-256 in either base64 form. */
+export function looksLikeDigest(s: string): boolean {
+  const normalized = fromUrlSafeB64(s.trim());
+  if (!/^[A-Za-z0-9+/]{43}=$/.test(normalized)) return false;
+  return Buffer.from(normalized, "base64").length === 32;
+}
+
+/**
+ * SHA-256 of a file's bytes as standard base64.
+ * Streams from disk, so file size is not a memory concern. Only this digest
+ * ever leaves the machine; file contents are never uploaded.
+ */
+export async function sha256FileB64(path: string): Promise<string> {
+  const info = await stat(path);
+  if (!info.isFile()) {
+    throw new Error(`Not a regular file: ${path}`);
+  }
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk as Buffer);
+  }
+  return hash.digest("base64");
+}
+
+/** Run an async mapper over items with bounded concurrency, preserving order. */
+export async function mapConcurrent<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index] as T, index);
+    }
+  }
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}