@forestrie/mcp-register 0.0.0-stage → 0.1.1

package/src/core/x402.ts

@@ -0,0 +1,314 @@
+/**
+ * x402 over already-decoded JSON: read canopy's payment requirements, pick
+ * the one option this server may pay, and refuse anything outside its caps.
+ *
+ * canopy's register-grant gate (canopy `scrapi/register-grant-payment.ts`)
+ * answers a payment-gated child grant with 402 and an `X-PAYMENT-REQUIRED`
+ * header: base64 of x402 v2 `PaymentRequirements`
+ * (`{x402Version: 2, accepts: [{scheme: "exact", network, amount, asset,
+ * payTo, maxTimeoutSeconds, extra}], resource: {url, …}}`), priced as a
+ * unit price × the child grant's `maxHeight`. The retry carries
+ * `X-PAYMENT`: base64 of the x402 v2 `PaymentPayload` (an EIP-3009
+ * authorisation for the exact amount).
+ *
+ * The caps are the server's configuration, never a tool argument: a model
+ * (or whatever prompt-injected it) cannot raise them. Every amount is in the
+ * asset's atomic units.
+ */
+
+export class PaymentError extends Error {
+  constructor(
+    readonly code:
+      "invalid_payment_requirements" | "invalid_payment" | CapRefusalCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export type CapRefusalCode =
+  | "cap_network"
+  | "cap_asset"
+  | "cap_testnet_only"
+  | "cap_payee"
+  | "cap_resource"
+  | "cap_per_call"
+  | "cap_per_day";
+
+export interface PaymentOption {
+  scheme: "exact";
+  network: string;
+  amount: string;
+  asset: string;
+  payTo: string;
+  maxTimeoutSeconds?: number;
+  extra?: Record<string, unknown>;
+}
+
+export interface PaymentRequired {
+  x402Version: 2;
+  accepts: PaymentOption[];
+  resource?: { url: string; description?: string; mimeType?: string };
+  error?: string;
+}
+
+/** Hard limits from the server's configuration. */
+export interface PaymentCaps {
+  /** The one CAIP-2 network this server pays on, e.g. `eip155:84532`. */
+  network: string;
+  /** The one asset contract it pays in, lowercase `0x…`. */
+  asset: string;
+  maxPerCallAtomic: bigint;
+  maxPerDayAtomic: bigint;
+  /** When set, the only payee it pays. */
+  payTo?: string;
+  /** Pay on a network outside {@link TESTNETS}. Off by default. */
+  allowMainnet: boolean;
+}
+
+/** EVM testnets x402 facilitators settle on. Anything else is mainnet money. */
+export const TESTNETS: ReadonlySet<string> = new Set([
+  "eip155:84532", // Base Sepolia
+  "eip155:11155111", // Ethereum Sepolia
+  "eip155:421614", // Arbitrum Sepolia
+  "eip155:11155420", // OP Sepolia
+  "eip155:80002", // Polygon Amoy
+  "eip155:43113", // Avalanche Fuji
+]);
+
+/** Base Sepolia, and Circle's USDC on it: the network and asset canopy prices in. */
+export const DEFAULT_PAY_NETWORK = "eip155:84532";
+export const DEFAULT_PAY_ASSET = "0x036cbd53842c5426634e7929541ec2318f3dcf7e";
+
+const ATOMIC = /^[0-9]{1,78}$/;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Validate decoded `X-PAYMENT-REQUIRED` JSON. Throws `PaymentError`. */
+export function readPaymentRequired(json: unknown): PaymentRequired {
+  const bad = (why: string) =>
+    new PaymentError(
+      "invalid_payment_requirements",
+      `canopy's X-PAYMENT-REQUIRED is not x402 v2 payment requirements: ${why}`,
+    );
+  if (!isObject(json)) throw bad("not a JSON object");
+  if (json["x402Version"] !== 2) throw bad("x402Version is not 2");
+  const accepts = json["accepts"];
+  if (!Array.isArray(accepts) || accepts.length === 0)
+    throw bad("accepts is empty");
+  const options: PaymentOption[] = [];
+  for (const a of accepts) {
+    if (!isObject(a)) throw bad("an accepts entry is not an object");
+    const { scheme, network, amount, asset, payTo } = a;
+    if (
+      typeof scheme !== "string" ||
+      typeof network !== "string" ||
+      typeof amount !== "string" ||
+      typeof asset !== "string" ||
+      typeof payTo !== "string"
+    )
+      throw bad(
+        "an accepts entry lacks scheme, network, amount, asset or payTo",
+      );
+    if (!ATOMIC.test(amount))
+      throw bad(`amount ${amount} is not an atomic-unit integer`);
+    if (!ADDRESS.test(asset) || !ADDRESS.test(payTo))
+      throw bad("asset and payTo must be 0x-prefixed 20-byte addresses");
+    if (scheme !== "exact") continue; // the only scheme canopy offers
+    options.push({
+      scheme,
+      network,
+      amount,
+      asset,
+      payTo,
+      ...(typeof a["maxTimeoutSeconds"] === "number"
+        ? { maxTimeoutSeconds: a["maxTimeoutSeconds"] }
+        : {}),
+      ...(isObject(a["extra"]) ? { extra: a["extra"] } : {}),
+    });
+  }
+  if (options.length === 0) throw bad('no accepts entry has scheme "exact"');
+  const resource = json["resource"];
+  return {
+    x402Version: 2,
+    accepts: options,
+    ...(isObject(resource) && typeof resource["url"] === "string"
+      ? {
+          resource: {
+            url: resource["url"],
+            ...(typeof resource["description"] === "string"
+              ? { description: resource["description"] }
+              : {}),
+            ...(typeof resource["mimeType"] === "string"
+              ? { mimeType: resource["mimeType"] }
+              : {}),
+          },
+        }
+      : {}),
+    ...(typeof json["error"] === "string" ? { error: json["error"] } : {}),
+  };
+}
+
+export interface CapContext {
+  /** The URL the payment is for: the register-grant URL this server POSTed. */
+  resourceUrl: string;
+  /** Atomic units already committed today (UTC), on this network and asset. */
+  spentTodayAtomic: bigint;
+}
+
+/**
+ * The one option this server may pay, or a `PaymentError` naming the cap
+ * that refuses it. Checked in the order a reader would ask: where, in what,
+ * to whom, for what, how much now, how much today.
+ */
+export function selectWithinCaps(
+  required: PaymentRequired,
+  caps: PaymentCaps,
+  ctx: CapContext,
+): PaymentOption {
+  const offered = (f: (o: PaymentOption) => string) =>
+    [...new Set(required.accepts.map(f))].join(", ");
+  if (!TESTNETS.has(caps.network) && !caps.allowMainnet)
+    throw new PaymentError(
+      "cap_testnet_only",
+      `the configured network ${caps.network} is not a testnet, and paying on a mainnet is off (set MCP_REGISTER_PAY_ALLOW_MAINNET=1 to allow it)`,
+    );
+  const onNetwork = required.accepts.filter((o) => o.network === caps.network);
+  if (onNetwork.length === 0)
+    throw new PaymentError(
+      "cap_network",
+      `canopy asks for payment on ${offered((o) => o.network)}; this server pays only on ${caps.network}`,
+    );
+  const option = onNetwork.find((o) => o.asset.toLowerCase() === caps.asset);
+  if (option === undefined)
+    throw new PaymentError(
+      "cap_asset",
+      `canopy asks for payment in ${offered((o) => o.asset)}; this server pays only in ${caps.asset}`,
+    );
+  if (
+    caps.payTo !== undefined &&
+    option.payTo.toLowerCase() !== caps.payTo.toLowerCase()
+  )
+    throw new PaymentError(
+      "cap_payee",
+      `canopy asks for payment to ${option.payTo}; this server pays only ${caps.payTo}`,
+    );
+  if (
+    required.resource !== undefined &&
+    stripQuery(required.resource.url) !== stripQuery(ctx.resourceUrl)
+  )
+    throw new PaymentError(
+      "cap_resource",
+      `the payment requirements are for ${required.resource.url}, not the request this server made (${ctx.resourceUrl})`,
+    );
+  const amount = BigInt(option.amount);
+  if (amount > caps.maxPerCallAtomic)
+    throw new PaymentError(
+      "cap_per_call",
+      `canopy asks ${option.amount} atomic units; this server's per-call cap is ${caps.maxPerCallAtomic}. Issue a grant with a smaller maxHeight, or pay in relay mode from a wallet you control`,
+    );
+  if (ctx.spentTodayAtomic + amount > caps.maxPerDayAtomic)
+    throw new PaymentError(
+      "cap_per_day",
+      `paying ${option.amount} would bring today's (UTC) spend to ${ctx.spentTodayAtomic + amount} atomic units; this server's daily cap is ${caps.maxPerDayAtomic}`,
+    );
+  return option;
+}
+
+function stripQuery(url: string): string {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return url;
+  }
+}
+
+/** What an `X-PAYMENT` authorises, for reporting. Never includes the signature. */
+export interface PaymentSummary {
+  network: string;
+  asset?: string;
+  from: string;
+  to: string;
+  value: string;
+  nonce: string;
+  validBefore: string;
+}
+
+/** Read decoded `X-PAYMENT` JSON (x402 v2 exact EVM). Throws `PaymentError`. */
+export function readPaymentPayload(json: unknown): PaymentSummary {
+  const bad = (why: string) =>
+    new PaymentError(
+      "invalid_payment",
+      `the payment is not an x402 v2 exact EVM payment payload: ${why}`,
+    );
+  if (!isObject(json)) throw bad("not a JSON object");
+  if (json["x402Version"] !== 2 && json["x402Version"] !== 1)
+    throw bad("x402Version is not 1 or 2");
+  const accepted = isObject(json["accepted"]) ? json["accepted"] : json;
+  const payload = json["payload"];
+  if (!isObject(payload)) throw bad("payload is missing");
+  const auth = payload["authorization"];
+  if (!isObject(auth)) throw bad("payload.authorization is missing");
+  const field = (k: string): string => {
+    const v = auth[k];
+    if (typeof v !== "string") throw bad(`authorization.${k} is missing`);
+    return v;
+  };
+  const network = accepted["network"];
+  if (typeof network !== "string") throw bad("network is missing");
+  return {
+    network,
+    ...(typeof accepted["asset"] === "string"
+      ? { asset: accepted["asset"] }
+      : {}),
+    from: field("from"),
+    to: field("to"),
+    value: field("value"),
+    nonce: field("nonce"),
+    validBefore: field("validBefore"),
+  };
+}
+
+const NONCE_TAG = new TextEncoder().encode(
+  "forestrie/mcp-register x402 grant payment nonce v1",
+);
+
+/**
+ * The EIP-3009 nonce for paying for one grant: SHA-256 over a domain tag,
+ * the grant's content (its grant v0 CBOR, so a re-signed copy of the same
+ * grant gets the same nonce) and the payer's 20-byte address.
+ *
+ * EIP-3009 lets a token contract execute at most one authorisation per
+ * (payer, nonce), and canopy's claim and its settlement de-duplication are
+ * keyed by the nonce too. So every authorisation this payer ever signs for
+ * this grant shares one nonce, and at most one of them can settle: two
+ * overlapping calls, a retry after a lost answer, or a second process
+ * sharing the same payer cannot pay for the grant twice.
+ */
+export async function grantPaymentNonce(
+  grantContent: Uint8Array,
+  payerAddress: Uint8Array,
+): Promise<string> {
+  if (payerAddress.length !== 20)
+    throw new PaymentError(
+      "invalid_payment",
+      `the payer address must be 20 bytes (got ${payerAddress.length})`,
+    );
+  const content = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", grantContent as BufferSource),
+  );
+  const material = new Uint8Array(NONCE_TAG.length + 1 + 32 + 20);
+  material.set(NONCE_TAG, 0);
+  material.set(content, NONCE_TAG.length + 1);
+  material.set(payerAddress, NONCE_TAG.length + 33);
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", material as BufferSource),
+  );
+  let hex = "0x";
+  for (const b of digest) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}

package/src/net/delegate.ts

@@ -0,0 +1,274 @@
+/**
+ * Delegate sealing for the caller's data log, falling back to `prepare`.
+ *
+ *   1. GET pending-delegation. A standing entry means the coordinator knows
+ *      the log's public root and has a vouched sealer key for it.
+ *   2. No standing entry: the coordinator never learned the root. canopy
+ *      forwards it at register-grant, best effort; `POST
+ *      /api/forest/{child}/prepare` under the same creation grant does it
+ *      explicitly. Then poll pending-delegation again, a bounded number of
+ *      times.
+ *   3. Verify the registrar voucher against the pinned sealer key, build the
+ *      certificate and on-chain proof with the log key, and submit them.
+ *
+ * Each failure names its stage, so the caller can tell "prepare refused the
+ * grant" from "the coordinator rejected the certificate".
+ */
+import type { FetchOptions } from "@forestrie/mcp-resolve/net";
+import {
+  buildCertificateSubmission,
+  checkVoucher,
+  type CertificateSubmission,
+  DelegationError,
+  findStandingEntry,
+  type StandingEntry,
+} from "../core/delegation.js";
+import { prepareGrantProblems, type GrantView } from "../core/grant.js";
+import { readProblem, type Problem } from "../core/scrapi.js";
+import type { Es256Signer } from "../core/signer.js";
+import {
+  getPendingDelegation,
+  postDelegationCertificate,
+  prepareChildLog,
+} from "./write.js";
+
+export type DelegateStage =
+  "pending_delegation" | "prepare" | "voucher" | "certificate";
+
+export interface DelegateSealingInput {
+  baseUrl: string;
+  coordinatorUrl: string;
+  /** The registrar's voucher key, 64 bytes x‖y, pinned out of band. */
+  knownSealerKeyXY: Uint8Array;
+  grantB64: string;
+  grant: GrantView;
+  mmrEnd?: number;
+  ttlSeconds?: number;
+  /** Polls of pending-delegation after a successful prepare. Default 5. */
+  pollsAfterPrepare?: number;
+  /** Wait between those polls, ms. Default 2000. */
+  pollIntervalMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export type DelegateSealingOutcome =
+  | {
+      kind: "delegated";
+      logId: string;
+      sealerId: string;
+      epoch: number;
+      mmrEnd: number;
+      issuedAt: number;
+      expiresAt: number;
+      /** True when this call had to run prepare first. */
+      prepared: boolean;
+      certificateKey?: string;
+    }
+  | {
+      kind: "problem";
+      stage: DelegateStage;
+      message: string;
+      problem?: Problem;
+      prepared: boolean;
+    };
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function delegateSealing(
+  input: DelegateSealingInput,
+  signer: Es256Signer,
+  opts?: FetchOptions,
+): Promise<DelegateSealingOutcome> {
+  const logId = input.grant.logId;
+  let prepared = false;
+
+  const readStanding = async (): Promise<
+    | { ok: true; standing: StandingEntry | undefined }
+    | { ok: false; outcome: DelegateSealingOutcome }
+  > => {
+    const res = await getPendingDelegation(
+      { coordinatorUrl: input.coordinatorUrl, logId },
+      opts,
+    );
+    if (res.status !== 200)
+      return {
+        ok: false,
+        outcome: {
+          kind: "problem",
+          stage: "pending_delegation",
+          message: `pending-delegation answered HTTP ${res.status}`,
+          problem: readJsonProblem(res.status, res.body),
+          prepared,
+        },
+      };
+    let body: unknown;
+    try {
+      body = JSON.parse(new TextDecoder().decode(res.body));
+    } catch {
+      return {
+        ok: false,
+        outcome: {
+          kind: "problem",
+          stage: "pending_delegation",
+          message: "pending-delegation did not return JSON",
+          prepared,
+        },
+      };
+    }
+    try {
+      return { ok: true, standing: findStandingEntry(body) };
+    } catch (err) {
+      return {
+        ok: false,
+        outcome: {
+          kind: "problem",
+          stage:
+            err instanceof DelegationError && err.code === "voucher_rejected"
+              ? "voucher"
+              : "pending_delegation",
+          message: (err as Error).message,
+          prepared,
+        },
+      };
+    }
+  };
+
+  let read = await readStanding();
+  if (!read.ok) return read.outcome;
+
+  if (read.standing === undefined) {
+    const refusals = prepareGrantProblems(input.grant);
+    if (refusals.length > 0)
+      return {
+        kind: "problem",
+        stage: "prepare",
+        message: `the coordinator has no standing sealer key for log ${logId} (its public root was never forwarded), and prepare cannot fix that with this grant: ${refusals.join("; ")}`,
+        prepared,
+      };
+    const res = await prepareChildLog(
+      { baseUrl: input.baseUrl, logId, grantB64: input.grantB64 },
+      opts,
+    );
+    if (res.status < 200 || res.status >= 300)
+      return {
+        kind: "problem",
+        stage: "prepare",
+        message: `prepare answered HTTP ${res.status}`,
+        problem: readProblem(res),
+        prepared,
+      };
+    prepared = true;
+    const sleep = input.sleep ?? defaultSleep;
+    const polls = input.pollsAfterPrepare ?? 5;
+    for (let i = 0; i < polls; i++) {
+      await sleep(input.pollIntervalMs ?? 2000);
+      read = await readStanding();
+      if (!read.ok) return read.outcome;
+      if (read.standing !== undefined) break;
+    }
+    if (read.standing === undefined)
+      return {
+        kind: "problem",
+        stage: "pending_delegation",
+        message: `prepare succeeded, but after ${polls} polls the coordinator still offers no standing sealer key for log ${logId}; try delegate_sealing again shortly`,
+        prepared,
+      };
+  }
+  const standing = read.standing;
+
+  try {
+    await checkVoucher(standing, input.knownSealerKeyXY);
+  } catch (err) {
+    return {
+      kind: "problem",
+      stage: "voucher",
+      message: (err as Error).message,
+      prepared,
+    };
+  }
+
+  let submission: CertificateSubmission;
+  try {
+    submission = await buildCertificateSubmission(
+      {
+        logId,
+        standing,
+        ...(input.mmrEnd !== undefined ? { mmrEnd: input.mmrEnd } : {}),
+        ...(input.ttlSeconds !== undefined
+          ? { ttlSeconds: input.ttlSeconds }
+          : {}),
+      },
+      signer,
+    );
+  } catch (err) {
+    // A malformed standing key, a bad ttl or a signer failure: report it
+    // at its stage rather than as a raw throw.
+    return {
+      kind: "problem",
+      stage: "certificate",
+      message: `could not build the delegation certificate: ${err instanceof Error ? err.message : String(err)}`,
+      prepared,
+    };
+  }
+  const res = await postDelegationCertificate(
+    { coordinatorUrl: input.coordinatorUrl, submission },
+    opts,
+  );
+  if (res.status < 200 || res.status >= 300)
+    return {
+      kind: "problem",
+      stage: "certificate",
+      message: `the coordinator rejected the delegation certificate: HTTP ${res.status}`,
+      problem: readJsonProblem(res.status, res.body),
+      prepared,
+    };
+  let certificateKey: string | undefined;
+  try {
+    const body = JSON.parse(new TextDecoder().decode(res.body)) as {
+      certificateKey?: unknown;
+    };
+    if (typeof body.certificateKey === "string")
+      certificateKey = body.certificateKey;
+  } catch {
+    // A 2xx without a JSON body still means accepted.
+  }
+  return {
+    kind: "delegated",
+    logId,
+    sealerId: standing.sealerId,
+    epoch: standing.epoch,
+    mmrEnd: submission.mmrEnd,
+    issuedAt: submission.issuedAt,
+    expiresAt: submission.expiresAt,
+    prepared,
+    ...(certificateKey !== undefined ? { certificateKey } : {}),
+  };
+}
+
+function readJsonProblem(status: number, body: Uint8Array): Problem {
+  const text = new TextDecoder().decode(body);
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    const title =
+      typeof parsed.title === "string"
+        ? parsed.title
+        : typeof parsed.error === "string"
+          ? parsed.error
+          : `HTTP ${status}`;
+    const detail =
+      typeof parsed.detail === "string"
+        ? parsed.detail
+        : typeof parsed.message === "string"
+          ? parsed.message
+          : undefined;
+    return { status, title, ...(detail !== undefined ? { detail } : {}) };
+  } catch {
+    const printable = text.replace(/[^\x20-\x7e]+/g, " ").trim();
+    return {
+      status,
+      title: `HTTP ${status}`,
+      ...(printable ? { detail: printable.slice(0, 500) } : {}),
+    };
+  }
+}

package/src/net/http.ts

@@ -0,0 +1,71 @@
+/**
+ * The one request helper the write path uses. Same contract as
+ * `@forestrie/mcp-resolve/net`'s readers, whose `NetError` and
+ * `RawResponse` it reuses: `redirect: "manual"` (a 303 is the answer, not
+ * something to follow), every non-2xx returned rather than thrown, and
+ * `NetError` only when no response was obtained.
+ */
+import {
+  NetError,
+  type FetchOptions,
+  type RawResponse,
+} from "@forestrie/mcp-resolve/net";
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+export interface RequestInit {
+  method: "GET" | "POST";
+  headers?: Record<string, string>;
+  body?: Uint8Array | string;
+}
+
+export async function rawRequest(
+  url: string,
+  init: RequestInit,
+  opts?: FetchOptions,
+): Promise<RawResponse> {
+  const fetchImpl = opts?.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const at = new Date().toISOString();
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new NetError("timeout", `timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    const res = await Promise.race([
+      fetchImpl(url, {
+        method: init.method,
+        redirect: "manual",
+        signal: controller.signal,
+        ...(init.headers ? { headers: init.headers } : {}),
+        ...(init.body !== undefined ? { body: init.body as BodyInit } : {}),
+      }),
+      timeout,
+    ]);
+    const body = new Uint8Array(
+      await Promise.race([res.arrayBuffer(), timeout]),
+    );
+    const headers: Record<string, string> = {};
+    res.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+    return { url, status: res.status, headers, body, at };
+  } catch (err) {
+    if (err instanceof NetError) throw err;
+    throw new NetError(
+      "network",
+      `network error on ${init.method} ${url}: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function trimBase(url: string): string {
+  return url.replace(/\/+$/, "");
+}

package/src/net/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@forestrie/mcp-register/net` — the ONLY place `fetch` is called.
+ *
+ * Every function here takes `opts.fetchImpl` (defaulting to
+ * `globalThis.fetch`) and never calls a bare `fetch`, so unit tests inject a
+ * fake under the forbidden-fetch global. Reads that mcp-resolve already
+ * does (receipts, genesis) are imported from `@forestrie/mcp-resolve/net`,
+ * not reimplemented.
+ */
+
+export { DEFAULT_TIMEOUT_MS, rawRequest } from "./http.js";
+export {
+  getPendingDelegation,
+  getRegistrationStatus,
+  postDelegationCertificate,
+  postGrant,
+  postStatement,
+  registerGrantUrl,
+  prepareChildLog,
+} from "./write.js";
+export { delegateSealing } from "./delegate.js";
+export type {
+  DelegateSealingInput,
+  DelegateSealingOutcome,
+  DelegateStage,
+} from "./delegate.js";