@ainra/mcp 0.4.1 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 <!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
 # @ainra/mcp
 
-[AINRA](https://ainra.vercel.app/) as native agent tools. A zero-dependency MCP server that hands an assistant the
+[AINRA](https://ainra.org/) as native agent tools. A zero-dependency MCP server that hands an assistant the
 real verifier, the public record, and — only if you point it at a registrar you control — the ability to issue,
 renew, and revoke.
 
@@ -33,8 +33,17 @@ There is no hosted default and no fallback. If the target isn't reachable the to
 
 ## Tools
 
-**Read-only** — `ainra_verify` runs the real `@ainra/sdk` verifier over a bundle and returns the verdict plus the
-named reason in plain words (the same code that agrees byte-for-byte in the four-way conformance differential);
+**Read-only** — `ainra_verify` decides whether a presentation someone handed you verifies, and says why in plain
+words. It takes the signed `directory` and the `roots` you trust (or fetches a URL target's own), checks the one
+against the other, authenticates the status list against the registrar's status key, and uses **your** clock,
+freshness class and audience. Nothing a presenter put in the bundle is believed. The result carries
+`decision: "accept" | "refuse"` and the policy that decided.
+
+> **In 0.4.1 this tool did not do that.** It replayed the bundle through the fixture-semantics verifier with the
+> bundle's own clock, freshness class and status list, so a revoked or expired presenter could be reported `valid`
+> (D-074). Upgrade. Replaying a conformance vector is still possible and is now a separate, labelled mode:
+> `anchors` plus `fixture: true`, which returns `decision: null`.
+
 `ainra_lookup` resolves a name to its public record; `ainra_status` reports the target's head — network, root label,
 registrar count, freshness window.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainra/mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "AINRA as native agent tools — a zero-dependency MCP server wrapping the published verifier, the public record, and the registrar you control.",
   "license": "Apache-2.0 OR MIT",
   "type": "module",
@@ -22,7 +22,7 @@
   "peerDependencies": {
     "@ainra/sdk": "*"
   },
-  "homepage": "https://ainra.vercel.app/",
+  "homepage": "https://ainra.org/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/JacobJandon/ainra.git"

package/src/server.mjs

@@ -17,7 +17,7 @@ const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, me
 async function handle(msg) {
   const { id, method, params } = msg;
   if (method === "initialize")
-    return reply(id, { protocolVersion: PROTOCOL, capabilities: { tools: { listChanged: false } }, serverInfo: { name: "ainra", version: VERSION }, instructions: `AINRA tools. Target: ${TARGET_INFO.target} (${TARGET_INFO.mode}). Read-only: ainra_verify/lookup/status. Write (need confirm:true): ainra_issue/renew/revoke. Never targets a registrar you don't control.` });
+    return reply(id, { protocolVersion: PROTOCOL, capabilities: { tools: { listChanged: false } }, serverInfo: { name: "ainra", version: VERSION }, instructions: `AINRA tools. Target: ${TARGET_INFO.target} (${TARGET_INFO.mode}). Read-only: ainra_verify/verify_link/lookup/status. Write (need confirm:true): ainra_issue/renew/revoke. Never targets a registrar you don't control.` });
   if (method === "notifications/initialized" || method === "notifications/cancelled") return; // no response to notifications
   if (method === "ping") return reply(id, {});
   if (method === "tools/list")

package/src/tools.mjs

@@ -9,7 +9,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
-import { runVector, verdictEvent, serializeVerdictEvent } from "@ainra/sdk";  // file:../sdk-ts in a checkout; ^x.y.z when published
+import { runVector, Verifier, verdictEvent, serializeVerdictEvent, linkFromIndex, jwkThumbprintEd25519, strictB64u } from "@ainra/sdk";  // file:../sdk-ts in a checkout; ^x.y.z when published
 export { verdictEvent, serializeVerdictEvent }; // one event shape across CLI, middleware, MCP (docs/PRESENTATION.md)
 
 const ROOT = fileURLToPath(new URL("../../../", import.meta.url));
@@ -100,50 +100,153 @@ export const TOOLS = [
   {
     name: "ainra_verify",
     title: "Verify an AINRA passport",
-    description: "Run the real @ainra/sdk verifier over a presentation bundle (with its trust anchors) and return the verdict plus the named reason in plain words. Read-only, offline, deterministic — the same code that agrees byte-for-byte in the conformance differential. If the bundle carries an ADR-019 instance credential (a RUNNING COPY of an agent rather than the agent itself), pass your own `audience`: it is never taken from the bundle, and an empty audience refuses every instance credential.",
+    description: "Decide whether a presentation someone handed you verifies. Pass the `presentation` with the signed `directory` and the two `roots` you trust (omit them and a URL target's own are fetched): the directory is checked against both roots, the status list against the registrar's status key, and the clock, the freshness class and the audience are YOURS — nothing a presenter put in the bundle is believed. Returns `decision` (accept or refuse), the verdict, and the named reason in plain words. Read-only. If the bundle carries an ADR-019 instance credential (a RUNNING COPY of an agent), pass your own `audience`; an empty audience refuses every instance credential. To replay a conformance VECTOR instead — which carries its own anchors, clock and status on purpose — pass `anchors` with `fixture: true`; that mode believes the bundle and decides nothing.",
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: "object",
       properties: {
-        anchors: { type: "object", description: "Trust anchors keyed by registrar id (issuer_key + log_root_key), as published in a directory/export." },
-        presentation: { type: "object", description: "The presentation bundle to verify." },
+        presentation: { type: "object", description: "The presentation bundle to verify, exactly as the presenter sent it." },
+        directory: { type: "object", description: "The dual-root-signed directory (directory.json) of the network you trust." },
+        roots: { type: "object", description: "The two ceremony root keys, { root_ed25519, root_slh } (roots.json). Obtain them out of band — never from the presenter." },
         audience: { type: "string", description: "YOUR audience (ADR-019), e.g. https://api.example. Required to accept an instance credential; a presenter can never supply it. Omit for plain passport bundles." },
+        freshness: { type: "string", enum: ["F1", "F2", "F3"], description: "How old a status publication you accept: F1 30 s, F2 5 min (default), F3 24 h. Yours, never the bundle's." },
+        now: { type: "integer", description: "Your clock, unix seconds. Defaults to this server's clock. Never read from the bundle." },
+        anchors: { type: "object", description: "FIXTURE MODE ONLY: a conformance vector's own trust anchors (issuer_key + log_root_key per registrar). Requires `fixture: true`." },
+        fixture: { type: "boolean", description: "Replay a conformance vector with fixture semantics: the bundle's own clock, freshness class and status list are believed. Decides nothing about a real presenter." },
       },
-      required: ["anchors", "presentation"],
+      required: ["presentation"],
     },
-    handler(input) {
-      // The audience is the CALLER's, exactly as `now` is. It is spliced over whatever the bundle claimed, which
-      // is the same override the TS Verifier and the Python Verifier apply — a presenter naming its own audience
-      // would defeat audience binding entirely.
-      const presentation = { ...input.presentation, audience: input.audience ?? "" };
-      const v = runVector({ name: "mcp", expect: {}, anchors: input.anchors, presentation });
-      const event = verdictEvent(presentation, v, presentation?.now ?? 0);
+    async handler(input) {
+      const INSTANCE_REASONS = ["instance_expired", "instance_scope_exceeds", "instance_sig_invalid", "instance_pop_invalid"];
       // Report the instance layer DISTINCTLY: an agent reading this must be able to tell "the running copy is not
       // entitled" from "the lineage is not trusted", because the two have different remedies — renew the copy, or
       // stop using the passport.
-      const INSTANCE_REASONS = ["instance_expired", "instance_scope_exceeds", "instance_sig_invalid", "instance_pop_invalid"];
-      const inst = presentation.instance ?? null;
+      const instanceReport = (presentation, v, audience) => {
+        const inst = presentation.instance ?? null;
+        if (!inst) return { presented: false };
+        const atInstance = Boolean(v.reason && INSTANCE_REASONS.includes(v.reason));
+        return {
+          presented: true,
+          iid: inst.iid ?? null,
+          expires: inst.exp ?? null,
+          audience: audience || null,
+          layer: atInstance ? "instance" : v.verdict === "valid" ? "ok" : "passport",
+          note: atInstance
+            ? "the RUNNING COPY is not entitled — the passport may be fine; mint a fresh instance credential"
+            : v.verdict === "valid" ? null
+            : "the failure is at the passport layer, not the running copy — the lineage itself did not verify",
+        };
+      };
+
+      // ── fixture mode: a conformance vector, replayed. Explicit, labelled, and never a decision (D-074). ──────
+      if (input.anchors !== undefined && input.directory === undefined && input.roots === undefined) {
+        if (input.fixture !== true)
+          throw new Error(
+            "ainra_verify with `anchors` replays a conformance vector: it believes the bundle's own clock, freshness " +
+            "class and status list, so a revoked or expired presenter could make it say valid. To decide whether to " +
+            "trust a presentation, pass the signed `directory` and the `roots` instead. To replay a vector on " +
+            "purpose, add `fixture: true`. Nothing was verified.");
+        // The audience is the CALLER's even here; everything else is the vector's, which is what a vector is for.
+        const presentation = { ...input.presentation, audience: input.audience ?? "" };
+        const v = runVector({ name: "mcp", expect: {}, anchors: input.anchors, presentation });
+        return {
+          mode: "fixture",
+          decision: null,
+          warning: "FIXTURE SEMANTICS: the bundle's own clock, freshness class and status list were believed. This replays a conformance vector; it does not decide whether to trust a presenter.",
+          verdict: v.verdict,
+          reason: v.reason ?? null,
+          explanation: gloss(v),
+          event: verdictEvent(presentation, v, presentation?.now ?? 0),
+          instance: instanceReport(presentation, v, presentation.audience),
+        };
+      }
+
+      // ── gate mode: what a verifier decides. The directory against both roots; the status against the registrar's
+      // status key; the clock, the class and the audience from the CALLER. ─────────────────────────────────────────
+      let { directory, roots } = input;
+      let trust = "the directory and roots you passed";
+      if (directory === undefined && roots === undefined) {
+        if (!isUrl(TARGET))
+          throw new Error("ainra_verify needs the trust to verify against: pass the signed `directory` and the `roots`, or set AINRA_TARGET to the URL of a network that publishes /directory.json and /roots.json. Nothing was verified.");
+        [directory, roots] = [await getJson("/directory.json"), await getJson("/roots.json")];
+        trust = `directory.json and roots.json fetched from AINRA_TARGET (${TARGET})`;
+      }
+      if (!directory || !roots || typeof roots.root_ed25519 !== "string" || typeof roots.root_slh !== "string")
+        throw new Error("ainra_verify needs BOTH `directory` and `roots` ({ root_ed25519, root_slh }). Nothing was verified.");
+      const freshness = input.freshness ?? "F2";
+      if (!["F1", "F2", "F3"].includes(freshness)) throw new Error("freshness must be F1, F2 or F3. Nothing was verified.");
+      const audience = input.audience ?? "";
+      const verifier = Verifier.fromDirectoryB64(directory, roots.root_ed25519, roots.root_slh, freshness, false, audience);
+      if (!verifier)
+        throw new Error("the directory does not verify against the roots — nothing in it can be trusted, so nothing was verified.");
+      const now = Number.isInteger(input.now) ? input.now : Math.floor(Date.now() / 1000);
+      const v = verifier.verify(input.presentation, now);
       return {
+        mode: "gate",
+        decision: v.verdict === "valid" ? "accept" : "refuse",
         verdict: v.verdict,
         reason: v.reason ?? null,
         explanation: gloss(v),
-        event,
-        instance: inst
-          ? {
-              presented: true,
-              iid: inst.iid ?? null,
-              expires: inst.exp ?? null,
-              audience: presentation.audience || null,
-              layer: v.reason && INSTANCE_REASONS.includes(v.reason) ? "instance" : v.verdict === "valid" ? "ok" : "passport",
-              note: v.reason && INSTANCE_REASONS.includes(v.reason)
-                ? "the RUNNING COPY is not entitled — the passport may be fine; mint a fresh instance credential"
-                : v.verdict === "valid" ? null
-                : "the failure is at the passport layer, not the running copy — the lineage itself did not verify",
-            }
-          : { presented: false },
+        event: verdictEvent(input.presentation, v, now),
+        policy: { now, freshness, audience: audience || null, trust },
+        instance: instanceReport(input.presentation, v, audience),
       };
     },
   },
+  {
+    name: "ainra_verify_link",
+    title: "Who stands behind this agent key?",
+    description: "AINRA Link (D-078): after you have verified a request's signature with an agent's Ed25519 key, ask which accountable operator stands behind that key and whether the link is still good. Pass the key (`key`, base64url), and either the `link` as a gate receives it, or the registrar's link `index` (GET /links) and its signed `status` publication (GET /status-list), from which the link for your key is found. Trust is YOURS: the signed `directory` and the two `roots` (omit both to use AINRA_TARGET's). The status list is authenticated before it is read; the clock, freshness class and capability are yours. Returns `decision` (accept or refuse), the operator and passport on accept, or the named reason. Read-only. A key with no link at all is refused as not_linked.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    inputSchema: {
+      type: "object",
+      properties: {
+        key: { type: "string", description: "The Ed25519 public key (base64url, 32 bytes) you ALREADY verified the request's signature with." },
+        link: { type: "object", description: "The link as a gate receives it (an index entry with the checkpoint and the signed status publication)." },
+        index: { type: "object", description: "Instead of `link`: the registrar's whole link index (GET /links)." },
+        status: { type: "object", description: "With `index`: the registrar's signed status publication (GET /status-list)." },
+        directory: { type: "object", description: "The dual-root-signed directory of the network you trust." },
+        roots: { type: "object", description: "The two ceremony root keys, { root_ed25519, root_slh }, obtained out of band." },
+        capability: { type: "string", description: "The capability the request exercises, if the link may be narrowed (e.g. read:invoices)." },
+        freshness: { type: "string", enum: ["F1", "F2", "F3"], description: "How old a status publication you accept: F1 30 s, F2 5 min (default), F3 24 h." },
+        now: { type: "integer", description: "Your clock, unix seconds. Defaults to this server's clock." },
+      },
+      required: ["key"],
+    },
+    async handler(input) {
+      const keyBytes = typeof input.key === "string" ? strictB64u(input.key) : null;
+      if (!keyBytes || keyBytes.length !== 32) throw new Error("`key` must be a base64url Ed25519 public key (32 bytes). Nothing was verified.");
+      let link = input.link;
+      if (link === undefined) {
+        if (!input.index || !input.status) throw new Error("pass either `link`, or both `index` (GET /links) and `status` (GET /status-list). Nothing was verified.");
+        link = linkFromIndex(input.index, input.status, jwkThumbprintEd25519(keyBytes));
+        if (!link)
+          return { decision: "refuse", verdict: "invalid", reason: "not_linked",
+                   explanation: "This key has no link at this registrar: a valid signature from it is not, by itself, an accountable operator." };
+      }
+      let { directory, roots } = input;
+      let trust = "the directory and roots you passed";
+      if (directory === undefined && roots === undefined) {
+        if (!isUrl(TARGET))
+          throw new Error("ainra_verify_link needs the trust to verify against: pass the signed `directory` and the `roots`, or set AINRA_TARGET to the URL of a network that publishes /directory.json and /roots.json. Nothing was verified.");
+        [directory, roots] = [await getJson("/directory.json"), await getJson("/roots.json")];
+        trust = `directory.json and roots.json fetched from AINRA_TARGET (${TARGET})`;
+      }
+      if (!directory || !roots || typeof roots.root_ed25519 !== "string" || typeof roots.root_slh !== "string")
+        throw new Error("ainra_verify_link needs BOTH `directory` and `roots` ({ root_ed25519, root_slh }). Nothing was verified.");
+      const freshness = input.freshness ?? "F2";
+      if (!["F1", "F2", "F3"].includes(freshness)) throw new Error("freshness must be F1, F2 or F3. Nothing was verified.");
+      const verifier = Verifier.fromDirectoryB64(directory, roots.root_ed25519, roots.root_slh, freshness);
+      if (!verifier) throw new Error("the directory does not verify against the roots — nothing in it can be trusted, so nothing was verified.");
+      const now = Number.isInteger(input.now) ? input.now : Math.floor(Date.now() / 1000);
+      const v = verifier.verifyLink(link, keyBytes, now, input.capability);
+      return v.verdict === "valid"
+        ? { decision: "accept", verdict: "valid", operator: v.operator, passport: v.passport, registrar: v.registrar, scope: v.scope,
+            explanation: `This key acts for operator "${v.operator}" under ${v.passport}, and the link has not been revoked.`,
+            policy: { now, freshness, capability: input.capability ?? null, trust } }
+        : { decision: "refuse", verdict: "invalid", reason: v.reason, explanation: gloss(v), policy: { now, freshness, capability: input.capability ?? null, trust } };
+    },
+  },
   {
     name: "ainra_lookup",
     title: "Look up a public record",