@forestrie/mcp-register 0.0.0-stage → 0.1.1

package/src/node/server.ts

@@ -0,0 +1,332 @@
+/**
+ * `createServer(deps?)` — the MCP adapter. No transport: the caller connects
+ * one (stdio from `cli.ts`, `InMemoryTransport` from the smoke test), which
+ * is also what lets an embedder mount tools on their own transport without
+ * the CLI.
+ *
+ * Tools register from `TOOL_NAMES` and prompts from `PROMPT_NAMES`
+ * (`text.ts`), in that order.
+ *
+ * The signers are seams: pass `deps.signer` (the log key) or
+ * `deps.authoritySigner` (the requester's authority key) to use a KMS or a
+ * remote signer. Without them, the defaults open local key files
+ * (`MCP_REGISTER_KEY_FILE`, else `log-key.jwk` in the home;
+ * `MCP_REGISTER_AUTHORITY_KEY_FILE`, else `authority-key.jwk`) at the first
+ * tool call that needs each, creating it then if it does not exist.
+ *
+ * The payer is a seam too: pass `deps.payer` for a hosted wallet. Without
+ * it, `MCP_REGISTER_PAYER_KEY_FILE` names a local EVM key file; with
+ * neither, register_grant runs in relay mode. The payer is never created.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { PACKAGE_VERSION } from "../core/index.js";
+import type { Es256Signer } from "../core/signer.js";
+import { join } from "node:path";
+import { GrantStore } from "./grant-store.js";
+import {
+  issueGrantInputShape,
+  makeIssueGrantTool,
+  makeRegisterGrantTool,
+  registerGrantInputShape,
+} from "./grant-tools.js";
+import { SpendLedger } from "./ledger.js";
+import { openKeyFilePayer, type PayerBackend } from "./payer.js";
+import {
+  openKeyFileSigner,
+  registerHome,
+  type KeyRole,
+} from "./signer-file.js";
+import { RegistrationStore } from "./store.js";
+import {
+  INSTRUCTIONS,
+  PROMPT_DESCRIPTIONS,
+  PROMPT_NAMES,
+  PROMPT_TITLES,
+  TOOL_DESCRIPTIONS,
+  TOOL_NAMES,
+  TOOL_TITLES,
+  auditPromptText,
+  issueAndPayPromptText,
+  registerPromptText,
+} from "./text.js";
+import {
+  checkRegistrationInputShape,
+  delegateSealingInputShape,
+  getLogKeyInputShape,
+  makeCheckRegistrationTool,
+  makeDelegateSealingTool,
+  makeGetLogKeyTool,
+  makeRegisterStatementTool,
+  makeVerifyRegistrationTool,
+  registerStatementInputShape,
+  verifyRegistrationInputShape,
+  type ResolvedDeps,
+} from "./tools.js";
+
+export const SERVER_NAME = "forestrie-mcp-register";
+
+export type { Es256Signer } from "../core/signer.js";
+export { openKeyFileSigner, publicKeyPem } from "./signer-file.js";
+export { evmPayer, openKeyFilePayer, readPaymentCaps } from "./payer.js";
+export type { PayerBackend } from "./payer.js";
+
+/** Every field optional; defaults to `process.env` / `globalThis.fetch` /
+ *  `() => new Date()` / the local key file, so tests can inject fakes
+ *  without touching the real network, environment or home directory. */
+export type Deps = {
+  fetchImpl?: typeof fetch;
+  env?: Record<string, string | undefined>;
+  now?: () => Date;
+  signer?: Es256Signer;
+  /** The requester's authority key; defaults to a local key file. */
+  authoritySigner?: Es256Signer;
+  /** Pays canopy's 402; defaults to MCP_REGISTER_PAYER_KEY_FILE, else none
+   *  (relay mode). */
+  payer?: PayerBackend;
+  /** Where registrations are kept; defaults to MCP_REGISTER_HOME. */
+  home?: string;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+/** Writes to the operator's log and to the local store; never destroys. */
+const WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true,
+} as const;
+
+export function createServer(deps: Deps = {}): McpServer {
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? registerHome(env);
+  const keyFile = env["MCP_REGISTER_KEY_FILE"] ?? join(home, "log-key.jwk");
+  const authorityKeyFile =
+    env["MCP_REGISTER_AUTHORITY_KEY_FILE"] ?? join(home, "authority-key.jwk");
+  const payerKeyFile = env["MCP_REGISTER_PAYER_KEY_FILE"];
+
+  /** A lazily opened key-file signer, unless the embedder passed one. */
+  const lazySigner = (
+    path: string,
+    role: KeyRole,
+    given: Es256Signer | undefined,
+  ): ResolvedDeps["signer"] => {
+    let opened: Promise<Es256Signer & { created?: boolean }> | undefined;
+    const open = (create: boolean) =>
+      openKeyFileSigner(path, { create, role }).catch((err: unknown) => {
+        opened = undefined;
+        throw err;
+      });
+    return (options) => {
+      if (given !== undefined) return Promise.resolve(given);
+      if (opened !== undefined) return opened;
+      // A no-create open is not remembered: a later call may create.
+      if (options?.create === false) return open(false);
+      return (opened = open(true));
+    };
+  };
+
+  let payer: PayerBackend | undefined = deps.payer;
+  const resolved: ResolvedDeps = {
+    fetchImpl: deps.fetchImpl ?? ((...a) => globalThis.fetch(...a)),
+    env,
+    now: deps.now ?? (() => new Date()),
+    signer: lazySigner(keyFile, "log", deps.signer),
+    authoritySigner: lazySigner(
+      authorityKeyFile,
+      "authority",
+      deps.authoritySigner,
+    ),
+    payer: () => {
+      if (payer === undefined && payerKeyFile)
+        payer = openKeyFilePayer(payerKeyFile);
+      return payer;
+    },
+    protectedPaths: [
+      keyFile,
+      authorityKeyFile,
+      ...(payerKeyFile ? [payerKeyFile] : []),
+      home,
+    ],
+    store: new RegistrationStore(home),
+    grants: new GrantStore(home),
+    ledger: new SpendLedger(home),
+    ...(deps.sleep !== undefined ? { sleep: deps.sleep } : {}),
+  };
+
+  const server = new McpServer(
+    { name: SERVER_NAME, version: PACKAGE_VERSION },
+    { instructions: INSTRUCTIONS },
+  );
+
+  server.registerTool(
+    TOOL_NAMES[0],
+    {
+      title: TOOL_TITLES.get_log_key,
+      description: TOOL_DESCRIPTIONS.get_log_key,
+      inputSchema: getLogKeyInputShape,
+      // May create the key file on first use; otherwise reads it.
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    makeGetLogKeyTool(resolved),
+  );
+
+  server.registerTool(
+    TOOL_NAMES[1],
+    {
+      title: TOOL_TITLES.register_statement,
+      description: TOOL_DESCRIPTIONS.register_statement,
+      inputSchema: registerStatementInputShape,
+      annotations: WRITE,
+    },
+    makeRegisterStatementTool(resolved),
+  );
+
+  server.registerTool(
+    TOOL_NAMES[2],
+    {
+      title: TOOL_TITLES.check_registration,
+      description: TOOL_DESCRIPTIONS.check_registration,
+      inputSchema: checkRegistrationInputShape,
+      // Reads canopy; saves the receipt locally once sealed.
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    makeCheckRegistrationTool(resolved),
+  );
+
+  server.registerTool(
+    TOOL_NAMES[3],
+    {
+      title: TOOL_TITLES.verify_registration,
+      description: TOOL_DESCRIPTIONS.verify_registration,
+      inputSchema: verifyRegistrationInputShape,
+      // Offline: reads the local store and the key's public half only; never
+      // creates a key.
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    makeVerifyRegistrationTool(resolved),
+  );
+
+  server.registerTool(
+    TOOL_NAMES[4],
+    {
+      title: TOOL_TITLES.delegate_sealing,
+      description: TOOL_DESCRIPTIONS.delegate_sealing,
+      inputSchema: delegateSealingInputShape,
+      annotations: WRITE,
+    },
+    makeDelegateSealingTool(resolved),
+  );
+
+  server.registerTool(
+    TOOL_NAMES[5],
+    {
+      title: TOOL_TITLES.issue_grant,
+      description: TOOL_DESCRIPTIONS.issue_grant,
+      inputSchema: issueGrantInputShape,
+      // Signs and saves locally; sends nothing.
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    makeIssueGrantTool(resolved),
+  );
+
+  server.registerTool(
+    TOOL_NAMES[6],
+    {
+      title: TOOL_TITLES.register_grant,
+      description: TOOL_DESCRIPTIONS.register_grant,
+      inputSchema: registerGrantInputShape,
+      // Writes to the operator's log, and may spend from the payer.
+      annotations: WRITE,
+    },
+    makeRegisterGrantTool(resolved),
+  );
+
+  server.registerPrompt(
+    PROMPT_NAMES[0],
+    {
+      title: PROMPT_TITLES.register,
+      description: PROMPT_DESCRIPTIONS.register,
+      argsSchema: {
+        what: z
+          .string()
+          .optional()
+          .describe("what to register, in a few words (optional)"),
+      },
+    },
+    (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: registerPromptText(args) },
+        },
+      ],
+    }),
+  );
+
+  server.registerPrompt(
+    PROMPT_NAMES[1],
+    {
+      title: PROMPT_TITLES.audit,
+      description: PROMPT_DESCRIPTIONS.audit,
+      argsSchema: {
+        contentHash: z
+          .string()
+          .optional()
+          .describe("the registration to audit (optional)"),
+      },
+    },
+    (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: auditPromptText(args) },
+        },
+      ],
+    }),
+  );
+
+  server.registerPrompt(
+    PROMPT_NAMES[2],
+    {
+      title: PROMPT_TITLES["issue-and-pay"],
+      description: PROMPT_DESCRIPTIONS["issue-and-pay"],
+      argsSchema: {
+        purpose: z
+          .string()
+          .optional()
+          .describe("what the grant is for, in a few words (optional)"),
+      },
+    },
+    (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: issueAndPayPromptText(args) },
+        },
+      ],
+    }),
+  );
+
+  return server;
+}

package/src/node/signer-file.ts

@@ -0,0 +1,251 @@
+/**
+ * The default signer backend: an ES256 (P-256) private key in a local JWK
+ * file, created on first use.
+ *
+ * Proportionate custody for what the key can do: it owns one data log
+ * whose grant someone else issued and bounded, and it holds no funds. The
+ * file is written once, `0600` in a `0700` directory, atomically (written
+ * aside, then hard-linked into place), so two servers starting together
+ * cannot both write one and neither can read a half-written one. It is
+ * never overwritten: a key that signed a grant's `grantData` must not
+ * silently change under it.
+ *
+ * The private key is imported non-extractable for signing; nothing in this
+ * package reads the `d` field again after import, and no tool result or
+ * log line carries it.
+ */
+import { webcrypto } from "node:crypto";
+import {
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Es256Signer } from "../core/signer.js";
+
+const subtle = webcrypto.subtle;
+
+export class KeyFileError extends Error {
+  readonly code = "signer_unavailable" as const;
+}
+
+/** `$MCP_REGISTER_HOME`, else `$XDG_CONFIG_HOME/forestrie/mcp-register`, else `~/.config/…`. */
+export function registerHome(env: Record<string, string | undefined>): string {
+  if (env["MCP_REGISTER_HOME"]) return env["MCP_REGISTER_HOME"];
+  const config = env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+  return join(config, "forestrie", "mcp-register");
+}
+
+type P256Jwk = { kty: "EC"; crv: "P-256"; x: string; y: string; d: string };
+
+function b64urlToBytes(s: string): Uint8Array {
+  return new Uint8Array(Buffer.from(s, "base64url"));
+}
+
+function isP256PrivateJwk(v: unknown): v is P256Jwk {
+  const j = v as Partial<P256Jwk>;
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    j.kty === "EC" &&
+    j.crv === "P-256" &&
+    typeof j.x === "string" &&
+    typeof j.y === "string" &&
+    typeof j.d === "string"
+  );
+}
+
+/**
+ * Write a new key without ever exposing a half-written file: the JWK goes
+ * to a private temporary file first, then is hard-linked into place, which
+ * fails (EEXIST) if another process got there first, in which case its key
+ * is used. The temporary file is always removed.
+ */
+async function createKeyFile(path: string, note: string): Promise<void> {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const pair = (await subtle.generateKey(
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["sign", "verify"],
+  )) as CryptoKeyPair;
+  const jwk = await subtle.exportKey("jwk", pair.privateKey);
+  const record = {
+    kty: jwk.kty,
+    crv: jwk.crv,
+    x: jwk.x,
+    y: jwk.y,
+    d: jwk.d,
+    use: "sig",
+    alg: "ES256",
+    note,
+  };
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(record, null, 2) + "\n", {
+      flag: "wx",
+      mode: 0o600,
+    });
+    try {
+      linkSync(tmp, path);
+    } catch (err) {
+      // Lost a race to another process creating the same file: use theirs.
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/**
+ * The two ES256 keys this server can hold. The log key owns the performer's
+ * data log; the authority key owns the requester's authority log and signs
+ * the child grants issue_grant makes. They are separate files so that
+ * whoever can write to one log cannot issue grants under the other.
+ */
+export type KeyRole = "log" | "authority";
+
+const KEY_ROLES: Record<
+  KeyRole,
+  { label: string; note: string; createdBy: string }
+> = {
+  log: {
+    label: "log key",
+    note: "Forestrie log key for @forestrie/mcp-register. Grants name its public x‖y; keep this file private.",
+    createdBy: "get_log_key or register_statement",
+  },
+  authority: {
+    label: "authority key",
+    note: "Forestrie authority key for @forestrie/mcp-register: owns the requester's authority log and signs the child grants issue_grant makes. Keep this file private.",
+    createdBy: 'get_log_key with which: "authority", or issue_grant,',
+  },
+};
+
+export interface KeyFileSigner extends Es256Signer {
+  readonly path: string;
+  /** True when this process created the key file. */
+  readonly created: boolean;
+}
+
+/**
+ * Load the key at `path`. Lazy by design: the server opens the signer at the
+ * first tool call that needs it, so starting the server never writes a
+ * file. With `create` (the default) a missing key is created; without it a
+ * missing key is a `KeyFileError`, so a read-only tool never makes one.
+ *
+ * Refused, like ssh refuses a loose private key: a key path that is a
+ * symlink, or a key file readable or writable by group or others.
+ */
+export async function openKeyFileSigner(
+  path: string,
+  options: { create?: boolean; role?: KeyRole } = {},
+): Promise<KeyFileSigner> {
+  const role = options.role ?? "log";
+  const label = KEY_ROLES[role].label;
+  let created = false;
+  let stat = lstatOrUndefined(path);
+  if (stat === undefined) {
+    if (options.create === false)
+      throw new KeyFileError(
+        `no ${label} at ${path} yet: ${KEY_ROLES[role].createdBy} creates it`,
+      );
+    try {
+      await createKeyFile(path, KEY_ROLES[role].note);
+    } catch (err) {
+      throw new KeyFileError(
+        `cannot create the ${label} file ${path}: ${(err as Error).message}`,
+      );
+    }
+    created = true;
+    stat = lstatOrUndefined(path);
+  }
+  if (stat === undefined || stat.isSymbolicLink() || !stat.isFile())
+    throw new KeyFileError(
+      `the ${label} path ${path} is not a regular file (a symlink or directory is refused)`,
+    );
+  if ((stat.mode & 0o077) !== 0)
+    throw new KeyFileError(
+      `the ${label} file ${path} is accessible to other users (mode ${(stat.mode & 0o777).toString(8)}); chmod 600 it`,
+    );
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    throw new KeyFileError(
+      `cannot read the ${label} file ${path}: ${(err as Error).message}`,
+    );
+  }
+  let jwk: unknown;
+  try {
+    jwk = JSON.parse(text);
+  } catch {
+    throw new KeyFileError(`the ${label} file ${path} is not JSON`);
+  }
+  if (!isP256PrivateJwk(jwk))
+    throw new KeyFileError(
+      `the ${label} file ${path} is not a P-256 private JWK (kty EC, crv P-256, x, y, d)`,
+    );
+  let privateKey: CryptoKey;
+  try {
+    privateKey = await subtle.importKey(
+      "jwk",
+      { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y, d: jwk.d, ext: false },
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["sign"],
+    );
+  } catch {
+    throw new KeyFileError(
+      `the ${label} file ${path} holds an invalid P-256 key`,
+    );
+  }
+  const xy = new Uint8Array(64);
+  xy.set(b64urlToBytes(jwk.x), 0);
+  xy.set(b64urlToBytes(jwk.y), 32);
+
+  return {
+    path,
+    created,
+    description: `local ${label} file ${path}`,
+    publicKeyXY: async () => xy.slice(),
+    sign: async (message) =>
+      new Uint8Array(
+        await subtle.sign(
+          { name: "ECDSA", hash: "SHA-256" },
+          privateKey,
+          message as BufferSource,
+        ),
+      ),
+  };
+}
+
+/** SubjectPublicKeyInfo DER prefix for an uncompressed P-256 point. */
+const P256_SPKI_PREFIX = Buffer.from(
+  "3059301306072a8648ce3d020106082a8648ce3d030107034200",
+  "hex",
+);
+
+/** The public key as an SPKI PEM, the form forestrie-cli's `--signer-pem` reads. */
+export function publicKeyPem(xy: Uint8Array): string {
+  const der = Buffer.concat([P256_SPKI_PREFIX, Buffer.from([0x04]), xy]);
+  const b64 = der.toString("base64").replace(/(.{64})/g, "$1\n");
+  return `-----BEGIN PUBLIC KEY-----\n${b64}\n-----END PUBLIC KEY-----\n`;
+}
+
+function lstatOrUndefined(path: string) {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new KeyFileError(
+      `cannot stat the key path ${path}: ${(err as Error).message}`,
+    );
+  }
+}