@forestrie/mcp-register 0.0.0-stage → 0.1.1

package/src/net/write.ts

@@ -0,0 +1,124 @@
+/**
+ * The write path's requests. Thin: each builds one request, returns the
+ * raw response, and leaves reading it to `src/core/scrapi.ts` or
+ * `src/core/delegation.ts`. Every function takes `fetchImpl` through
+ * `opts`.
+ *
+ * Endpoints, all public and none needing an operator token:
+ *
+ *  - canopy `POST /register/{R}/entries`, the statement as
+ *    `application/cose`, authorised by `Forestrie-Grant <base64>`;
+ *  - canopy `POST /register/{R}/grants`, the child grant as
+ *    `Forestrie-Grant <base64>`, the parent grant in a CBOR body, and an
+ *    `X-PAYMENT` when paying canopy's 402;
+ *  - canopy `POST /api/forest/{childLogId}/prepare`, no body, the same
+ *    grant: publishes the child log's public root to the delegation
+ *    coordinator when register-grant's auto-forward did not;
+ *  - coordinator `GET /api/logs/{logId}/pending-delegation`;
+ *  - coordinator `POST /api/delegations/certificate`, JSON.
+ */
+import type { FetchOptions, RawResponse } from "@forestrie/mcp-resolve/net";
+import type { CertificateSubmission } from "../core/delegation.js";
+import { rawRequest, trimBase } from "./http.js";
+
+export function postStatement(
+  input: {
+    baseUrl: string;
+    rootLogId: string;
+    statement: Uint8Array;
+    grantB64: string;
+  },
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  return rawRequest(
+    `${trimBase(input.baseUrl)}/register/${encodeURIComponent(input.rootLogId)}/entries`,
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/cose",
+        authorization: `Forestrie-Grant ${input.grantB64}`,
+      },
+      body: input.statement,
+    },
+    opts,
+  );
+}
+
+/** The URL `postGrant` POSTs: also the x402 resource a payment is for. */
+export function registerGrantUrl(baseUrl: string, rootLogId: string): string {
+  return `${trimBase(baseUrl)}/register/${encodeURIComponent(rootLogId)}/grants`;
+}
+
+export function postGrant(
+  input: {
+    baseUrl: string;
+    rootLogId: string;
+    grantB64: string;
+    /** `registerGrantBody(parentGrant)`: canonical CBOR `{parentGrant}`. */
+    body: Uint8Array;
+    /** The `X-PAYMENT` header value, when paying. */
+    payment?: string;
+  },
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  return rawRequest(
+    registerGrantUrl(input.baseUrl, input.rootLogId),
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/cbor",
+        authorization: `Forestrie-Grant ${input.grantB64}`,
+        ...(input.payment !== undefined ? { "x-payment": input.payment } : {}),
+      },
+      body: input.body,
+    },
+    opts,
+  );
+}
+
+export function getRegistrationStatus(
+  input: { statusUrl: string },
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  return rawRequest(input.statusUrl, { method: "GET" }, opts);
+}
+
+export function prepareChildLog(
+  input: { baseUrl: string; logId: string; grantB64: string },
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  return rawRequest(
+    `${trimBase(input.baseUrl)}/api/forest/${encodeURIComponent(input.logId)}/prepare`,
+    {
+      method: "POST",
+      headers: { authorization: `Forestrie-Grant ${input.grantB64}` },
+    },
+    opts,
+  );
+}
+
+export function getPendingDelegation(
+  input: { coordinatorUrl: string; logId: string },
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  return rawRequest(
+    `${trimBase(input.coordinatorUrl)}/api/logs/${encodeURIComponent(input.logId)}/pending-delegation`,
+    { method: "GET", headers: { accept: "application/json" } },
+    opts,
+  );
+}
+
+export function postDelegationCertificate(
+  input: { coordinatorUrl: string; submission: CertificateSubmission },
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  return rawRequest(
+    `${trimBase(input.coordinatorUrl)}/api/delegations/certificate`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(input.submission),
+    },
+    opts,
+  );
+}

package/src/node/cli.ts

@@ -0,0 +1,170 @@
+/**
+ * The bin entry, reached via `bin/mcp-register.mjs`.
+ *
+ *   <no args>          → StdioServerTransport; this is what
+ *                        `npx -y @forestrie/mcp-register` does.
+ *   --help | --version → text on stdout, exit 0.
+ *
+ * TWO RULES, both silent-corruption bugs if broken:
+ *
+ * 1. **Nothing may write to stdout in stdio mode except the transport.** A
+ *    stray `console.log` does not produce a warning — it produces a malformed
+ *    JSON-RPC frame and an MCP client that mysteriously fails to initialise.
+ *    All logging goes to stderr. `scripts/check-stdio-clean.mjs` proves it
+ *    against a real spawned process on every CI run.
+ *
+ * 2. **`main` returns an exit code; it does not call `process.exit`.** Killing
+ *    the process mid-write truncates whatever the stdio transport had
+ *    buffered. The wrapper sets `process.exitCode` and lets node drain.
+ *
+ * Serves the tools `createServer()` (`server.ts`) registers. It is
+ * called with no `deps`, so it reads `process.env` and calls the real
+ * `globalThis.fetch` — exactly what `npx -y @forestrie/mcp-register` should do.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  PACKAGE_VERSION,
+  RESOLVE_VERSION,
+  VERIFIER_VERSION,
+} from "../core/index.js";
+import { createServer } from "./server.js";
+import {
+  PROMPT_NAMES,
+  PROMPT_TITLES,
+  TOOL_NAMES,
+  TOOL_TITLES,
+} from "./text.js";
+
+/** One line per tool, generated from the same list the server registers
+ *  from — never a hand-typed block. */
+const TOOLS_BLOCK = TOOL_NAMES.map(
+  (name) => `  ${name.padEnd(26)} ${TOOL_TITLES[name]}`,
+).join("\n");
+
+const PROMPTS_BLOCK = PROMPT_NAMES.map(
+  (name) => `  ${name.padEnd(26)} ${PROMPT_TITLES[name]}`,
+).join("\n");
+
+export const HELP = `forestrie-mcp-register ${PACKAGE_VERSION}
+
+  MCP server that signs statements with a log key, registers them on a
+  Forestrie transparency log under a grant you hold, delegates sealing for
+  your data log, and verifies the receipt by composing @forestrie/mcp-resolve
+  and @forestrie/mcp-verify. Signature bytes never cross the MCP boundary.
+
+USAGE
+  forestrie-mcp-register                start the MCP server on stdio (the default)
+  forestrie-mcp-register --help
+  forestrie-mcp-register --version
+
+TOOLS
+${TOOLS_BLOCK}
+
+PROMPTS
+${PROMPTS_BLOCK}
+
+CONFIGURATION (each overridable per call)
+  FORESTRIE_BASE_URL          canopy SCRAPI base URL
+  FORESTRIE_ROOT_LOG_ID       the forest's root log id (R in /register/{R}/entries)
+  FORESTRIE_GRANT             your Forestrie-Grant: base64, or a file path
+  FORESTRIE_AUTHORITY_GRANT   your authority log's grant, for issue_grant and register_grant
+  FORESTRIE_COORDINATOR_URL   delegation coordinator, for delegate_sealing
+  FORESTRIE_KNOWN_SEALER_KEY  registrar voucher key, base64 x‖y, for delegate_sealing
+  MCP_REGISTER_HOME           key files, grants, registrations, spend ledger
+                              (default ~/.config/forestrie/mcp-register)
+  MCP_REGISTER_KEY_FILE       the log key file (default $MCP_REGISTER_HOME/log-key.jwk)
+  MCP_REGISTER_AUTHORITY_KEY_FILE
+                              the authority key file (default $MCP_REGISTER_HOME/authority-key.jwk)
+
+PAYMENT (configuration only; never a tool argument)
+  MCP_REGISTER_PAYER_KEY_FILE     EVM private key (0x + 64 hex, mode 600) that pays canopy's
+                                  x402 402; unset means relay mode
+  MCP_REGISTER_PAY_MAX_PER_CALL   cap per payment, atomic units (required with a payer)
+  MCP_REGISTER_PAY_MAX_PER_DAY    cap per UTC day, atomic units (required with a payer)
+  MCP_REGISTER_PAY_NETWORK        the one network (default eip155:84532, Base Sepolia)
+  MCP_REGISTER_PAY_ASSET          the one asset (default USDC on Base Sepolia)
+  MCP_REGISTER_PAY_TO             optional: the only payee
+  MCP_REGISTER_PAY_ALLOW_MAINNET  1 to pay on a network that is not a testnet (off)
+
+CLIENT CONFIG
+  {"mcpServers": {"forestrie-register":
+    {"command": "npx", "args": ["-y", "@forestrie/mcp-register"]}}}
+
+  Verifier: @forestrie/mcp-verify ${VERIFIER_VERSION}
+  Resolver: @forestrie/mcp-resolve ${RESOLVE_VERSION}
+  Docs:     https://github.com/forestrie/mcp-register#readme
+`;
+
+/** stdout is the transport in stdio mode; everything else is stderr. */
+const out = (line: string): void => {
+  process.stdout.write(`${line}\n`);
+};
+
+export async function main(argv: readonly string[]): Promise<number> {
+  const args = [...argv];
+
+  if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+    out(HELP);
+    return 0;
+  }
+  if (args.includes("--version") || args.includes("-v")) {
+    out(PACKAGE_VERSION);
+    return 0;
+  }
+
+  const verb = args[0];
+  if (verb !== undefined && !verb.startsWith("-")) {
+    process.stderr.write(
+      `forestrie-mcp-register: unknown command '${verb}'. Try --help.\n`,
+    );
+    return 1;
+  }
+
+  // Default: speak MCP on stdio. From here on, stdout belongs to the
+  // transport and nothing else may touch it.
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Wait for the client to go away (stdin ends, the transport closes) or
+  // for a signal. `server.server.onclose`, not `transport.onclose`: connect()
+  // installed the latter and overwriting it would skip the SDK's own
+  // cleanup. Listeners are removed afterwards so nothing here keeps the
+  // event loop alive.
+  let finish: () => void = () => {};
+  const ended = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  const onSignal = (): void => finish();
+  server.server.onclose = finish;
+  process.stdin.once("end", finish);
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  await ended;
+  process.off("SIGINT", onSignal);
+  process.off("SIGTERM", onSignal);
+  process.stdin.off("end", finish);
+
+  // A signal leaves the transport open, and its stdin listener keeps the
+  // process alive for as long as the client holds the pipe. Close it so the
+  // event loop drains; the wrapper sets the exit code, never process.exit.
+  await server.close();
+  return 0;
+}
+
+/**
+ * Entry point. `process.exitCode` rather than `process.exit()`: node then
+ * drains stdout before exiting, which a hard exit would not.
+ */
+export async function run(): Promise<void> {
+  try {
+    process.exitCode = await main(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(
+      `forestrie-mcp-register: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+await run();

package/src/node/grant-store.ts

@@ -0,0 +1,154 @@
+/**
+ * Where child grants are kept between issue_grant and register_grant:
+ * `<home>/grants/<logId>/` holding `record.json`, `grant.cose` (as signed),
+ * `parent.cose` (the requester's authority grant, when known),
+ * `receipt.cose` and `completed.cose` (the grant with its receipt: the
+ * credential).
+ *
+ * The record is keyed by the child log id, so register_grant resumes from
+ * whatever state the last call reached. Nothing here is secret.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PaymentRequired, PaymentSummary } from "../core/x402.js";
+import { StoreError } from "./store.js";
+
+export type GrantState =
+  /** Signed (or supplied), not yet accepted by canopy. */
+  | "issued"
+  /** canopy answered 402; waiting for a payment (relay mode). */
+  | "payment_required"
+  /** canopy answered 303: enqueued for sequencing under the owner log. */
+  | "accepted"
+  /** Sealed, and completed with its receipt. */
+  | "complete";
+
+export interface GrantRecord {
+  logId: string;
+  ownerLogId: string;
+  state: GrantState;
+  /** True when issue_grant signed it here. */
+  issuedHere: boolean;
+  /** The key the grant names, hex x‖y. */
+  granteeHex: string;
+  maxHeight?: number;
+  flagsHex: string;
+  /** Whether the parent grant carries GF_CHILD_PAYMENT_REQUIRED. */
+  parentRequiresPayment?: boolean;
+  issuedAt: string;
+  baseUrl?: string;
+  rootLogId?: string;
+  paymentRequired?: PaymentRequired;
+  payment?: PaymentSummary & { via: "payer" | "relay"; at: string };
+  statusUrl?: string;
+  acceptedAt?: string;
+  firstPendingAt?: string;
+  entryId?: string;
+  massifHeight?: number;
+  receiptUrl?: string;
+  completedAt?: string;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const STATES: GrantState[] = [
+  "issued",
+  "payment_required",
+  "accepted",
+  "complete",
+];
+
+function io<T>(what: string, run: () => T): T {
+  try {
+    return run();
+  } catch (err) {
+    throw new StoreError(
+      "store_failed",
+      `${what}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export class GrantStore {
+  constructor(readonly root: string) {}
+
+  dir(logId: string): string {
+    if (!UUID.test(logId))
+      throw new StoreError(
+        "unknown_registration",
+        `logId must be a lowercase UUID (the child log id issue_grant returned); got ${logId}`,
+      );
+    return join(this.root, "grants", logId);
+  }
+
+  path(logId: string, file: string): string {
+    return join(this.dir(logId), file);
+  }
+
+  has(logId: string): boolean {
+    try {
+      readFileSync(this.path(logId, "record.json"));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  save(record: GrantRecord, files: Record<string, Uint8Array> = {}): void {
+    io(`cannot save grant ${record.logId} under ${this.root}`, () => {
+      mkdirSync(this.dir(record.logId), { recursive: true, mode: 0o700 });
+      for (const [name, bytes] of Object.entries(files))
+        writeFileSync(this.path(record.logId, name), bytes);
+      writeFileSync(
+        this.path(record.logId, "record.json"),
+        JSON.stringify(record, null, 2) + "\n",
+      );
+    });
+  }
+
+  load(logId: string): GrantRecord {
+    const path = this.path(logId, "record.json");
+    let text: string;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT")
+        throw new StoreError(
+          "unknown_registration",
+          `no grant for log ${logId} in ${this.root}: issue_grant records each grant it signs there, or pass the grant itself`,
+        );
+      throw new StoreError(
+        "store_failed",
+        `cannot read ${path}: ${(err as Error).message}`,
+      );
+    }
+    let record: Partial<GrantRecord> | undefined;
+    try {
+      record = JSON.parse(text) as Partial<GrantRecord>;
+    } catch {
+      record = undefined;
+    }
+    if (
+      record === undefined ||
+      record.logId !== logId ||
+      typeof record.ownerLogId !== "string" ||
+      !STATES.includes(record.state as GrantState)
+    )
+      throw new StoreError(
+        "corrupt_record",
+        `${path} is not a grant record for ${logId}`,
+      );
+    return record as GrantRecord;
+  }
+
+  read(logId: string, file: string): Uint8Array | undefined {
+    try {
+      return new Uint8Array(readFileSync(this.path(logId, file)));
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw new StoreError(
+        "store_failed",
+        `cannot read ${file} for grant ${logId}: ${(err as Error).message}`,
+      );
+    }
+  }
+}