@ainra/mcp 0.4.1

package/README.md

@@ -0,0 +1,66 @@
+<!-- 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
+real verifier, the public record, and — only if you point it at a registrar you control — the ability to issue,
+renew, and revoke.
+
+> **Not published to a registry.** This package is run from the repository. See `packages/mcp/` in
+> [github.com/JacobJandon/ainra](https://github.com/JacobJandon/ainra).
+
+## Configure
+
+```json
+{
+  "mcpServers": {
+    "ainra": {
+      "command": "node",
+      "args": ["packages/mcp/src/server.mjs"],
+      "env": { "AINRA_TARGET": "genesis-out" }
+    }
+  }
+}
+```
+
+`AINRA_TARGET` selects one thing and one thing only:
+
+| Value | Means |
+|---|---|
+| `genesis-out` (default) | a **local** registrar directory — what `make genesis-local` or `ainra init` produced — driven through the CLI |
+| `http://127.0.0.1:8091` | a running AINRA network you control (`make stage-up`) |
+
+There is no hosted default and no fallback. If the target isn't reachable the tools say so and stop.
+
+## 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);
+`ainra_lookup` resolves a name to its public record; `ainra_status` reports the target's head — network, root label,
+registrar count, freshness window.
+
+**Write, and each requires an explicit `confirm: true`** — `ainra_issue`, `ainra_renew`, and `ainra_revoke`.
+`ainra_revoke` is destructive: it fails a live credential closed everywhere inside the freshness window. An agent
+cannot reach any of the three by accident, and none of them targets a registrar you do not hold the write token for.
+
+## Zero telemetry
+
+The only outbound calls this server makes are to the `AINRA_TARGET` you set. Nothing is reported anywhere, by
+design and by inspection — it is a few hundred lines with no dependencies.
+
+Licensed Apache-2.0 OR MIT.
+
+### Verifying a running copy (ADR-019)
+
+`ainra_verify` takes an optional **`audience`** — yours. It is never read from the bundle, and an empty audience
+refuses every instance credential (fail-closed). The result gains an `instance` object that reports the layer
+distinctly:
+
+```json
+{ "verdict": "invalid", "reason": "instance_expired",
+  "instance": { "presented": true, "iid": "i-0794", "expires": 2600, "layer": "instance",
+                "note": "the RUNNING COPY is not entitled — the passport may be fine; mint a fresh instance credential" } }
+```
+
+`layer` is `"instance"`, `"passport"` or `"ok"`, because the remedies differ: renew the copy, or stop trusting the
+lineage. Minting is **not** an MCP tool — it needs a passport's control key, and that key belongs outside any
+agent-reachable surface.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ainra/mcp",
+  "version": "0.4.1",
+  "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",
+  "bin": {
+    "ainra-mcp": "src/server.mjs"
+  },
+  "exports": {
+    ".": "./src/tools.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@ainra/sdk": "*"
+  },
+  "peerDependencies": {
+    "@ainra/sdk": "*"
+  },
+  "homepage": "https://ainra.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobJandon/ainra.git"
+  },
+  "mcpName": "io.github.JacobJandon/ainra"
+}

package/src/reasons.json

@@ -0,0 +1,24 @@
+{
+  "_note": "The 20 frozen INVALID reasons, in verify order, each in plain words. Single source for the CLI/SDK/MCP/console legends and docs. The strings themselves are frozen (they match crates/ainra-core/src/verify.rs and packages/sdk-ts Reason); only these glosses are editorial. tools/reasons-check.mjs fails the build if this list and ainra-core's Reason::ALL ever diverge.",
+  "valid": "All nine checks passed — genuine, in-window, in-scope, logged, and not revoked.",
+  "schema_violation": "Not a well-formed passport, or it carries a forbidden (identity/score/money) field.",
+  "name_malformed": "The subject or issuer name doesn't fit the AINRA name grammar.",
+  "unknown_registrar": "The issuing registrar isn't in the signed directory (not accredited).",
+  "not_yet_valid": "Presented before its validity window opens (now < nbf).",
+  "expired": "Its validity window has closed (now >= exp) — no grace, no skew.",
+  "sig_invalid": "An issuer signature failed to verify.",
+  "alg_downgrade": "Only one of the two required signatures (Ed25519 + ML-DSA-65) was present or valid.",
+  "ceiling_exceeded": "The capabilities claimed exceed the scope ceiling.",
+  "chain_widening": "A delegation hop granted more than it held — delegation may only narrow.",
+  "chain_expired": "A delegation hop is outside its own validity window.",
+  "stale_status": "The revocation status is too old for the required freshness class (fails closed).",
+  "revoked": "The lineage's revocation bit is set — it has been revoked.",
+  "mandate_revoked": "A mandate in the signed permission path has been revoked.",
+  "not_logged": "The credential can't be proven present in the transparency log (logged-before-valid failed).",
+  "registrar_distrusted": "The registrar was distrusted from this point in its log onward — everything it logged before the published cutoff still verifies (D-044).",
+  "checkpoint_invalid": "The log checkpoint isn't signed by a currently-valid delegate.",
+  "instance_expired": "The running copy's instance credential is outside its window, or its lifetime exceeds the one-hour ADR-019 ceiling. The passport is fine — the copy needs a fresh credential.",
+  "instance_scope_exceeds": "The instance credential asks for a capability its passport does not hold. A running copy may only narrow, never widen (ADR-019).",
+  "instance_sig_invalid": "The instance credential was not minted by this passport's control key, or is not bound to this passport (wrong subject or wrong logged leaf).",
+  "instance_pop_invalid": "The presenter did not prove it holds the instance key: wrong audience, a timestamp outside tolerance, or a bad proof-of-possession signature."
+}

package/src/server.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+// @ainra/mcp — a zero-dependency MCP server (JSON-RPC 2.0 over stdio, newline-delimited) exposing the AINRA tools.
+// Agents are the users now; this meets them natively. No new protocol semantics — every tool wraps an existing
+// surface (see tools.mjs). Zero telemetry: the only outbound calls are to the AINRA_TARGET the operator set.
+//   Run: node packages/mcp/src/server.mjs   (or the `ainra-mcp` bin)
+import { TOOLS, TOOL_BY_NAME, TARGET_INFO } from "./tools.mjs";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const VERSION = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
+const PROTOCOL = "2025-06-18"; // the MCP revision this server speaks
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+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.` });
+  if (method === "notifications/initialized" || method === "notifications/cancelled") return; // no response to notifications
+  if (method === "ping") return reply(id, {});
+  if (method === "tools/list")
+    return reply(id, { tools: TOOLS.map((t) => ({ name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema, annotations: { title: t.title, ...t.annotations } })) });
+  if (method === "tools/call") {
+    const tool = TOOL_BY_NAME[params?.name];
+    if (!tool) return fail(id, -32602, `unknown tool: ${params?.name}`);
+    try {
+      const result = await tool.handler(params.arguments || {});
+      return reply(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result, isError: false });
+    } catch (e) {
+      // Tool errors are reported IN-BAND (isError) so the agent sees the message and the next step, not a transport crash.
+      return reply(id, { content: [{ type: "text", text: String(e.message || e) }], isError: true });
+    }
+  }
+  if (id !== undefined) return fail(id, -32601, `method not found: ${method}`);
+}
+
+// newline-delimited JSON-RPC over stdin. Track in-flight async handlers so a closed stdin (one-shot pipes, some
+// agent runners) drains pending tool calls instead of dropping their responses on the floor.
+let buf = "";
+let inflight = 0;
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    inflight++;
+    Promise.resolve(handle(msg))
+      .catch((e) => { if (msg?.id !== undefined) fail(msg.id, -32603, String(e.message || e)); })
+      .finally(() => { inflight--; });
+  }
+});
+process.stdin.on("end", () => {
+  const deadline = Date.now() + 30000; // drain up to 30s of pending tool calls, then exit regardless
+  const t = setInterval(() => { if (inflight === 0 || Date.now() > deadline) { clearInterval(t); process.exit(0); } }, 15);
+});
+process.stderr.write(`[ainra-mcp] up — ${TOOLS.length} tools, target ${TARGET_INFO.target} (${TARGET_INFO.mode}), zero telemetry\n`);

package/src/tools.mjs

@@ -0,0 +1,254 @@
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+// @ainra/mcp — the AINRA tools an agent calls natively. Each tool maps 1:1 onto an EXISTING surface (the published
+// @ainra/sdk verifier, the registrar's public record, the ainra CLI / registrar write API) — NO new protocol
+// semantics. Read-only tools are marked; write/destructive tools require an explicit `confirm: true`. Zero telemetry:
+// the only network calls are to the AINRA_TARGET the operator configured. One config field selects the target:
+//   AINRA_TARGET=genesis-out           → a LOCAL registrar dir (genesis-local / `ainra init` output) via the CLI
+//   AINRA_TARGET=http://127.0.0.1:8091 → a network the operator controls (lookup/status read-only; issue/renew/revoke
+//                                        need AINRA_STAGE_ISSUE_TOKEN — never touch a registrar you don't hold keys for)
+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
+export { verdictEvent, serializeVerdictEvent }; // one event shape across CLI, middleware, MCP (docs/PRESENTATION.md)
+
+const ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+// Installed from a registry there is no monorepo around this file, so everything it needs at import time must
+// live inside the package. `src/reasons.json` is a committed copy of `docs/reasons.json`, held byte-identical by
+// `make reasons-check`; the canonical file still wins in a checkout so a working tree is never stale.
+const REASONS = JSON.parse(
+  readFileSync(
+    (() => {
+      const canonical = ROOT + "docs/reasons.json";
+      return existsSync(canonical) ? canonical : fileURLToPath(new URL("./reasons.json", import.meta.url));
+    })(),
+    "utf8",
+  ),
+);
+const TARGET = process.env.AINRA_TARGET || "genesis-out";
+const isUrl = (t) => /^https?:\/\//.test(t);
+// The CLI is a compiled binary and cannot ship inside an npm tarball, so it is LOCATED, not bundled, in the order
+// an operator would expect: an explicit path, then whatever `ainra` is on PATH, then a monorepo build. Absent all
+// three the URL target still serves every read-only tool — only the local-dir and write paths need a binary.
+const CLI_SOURCES = [
+  ["AINRA_CLI", process.env.AINRA_CLI || null],
+  ["PATH", (() => {
+    // stdio: stderr ignored — `which` prints "no ainra in ..." on a miss, and a miss is an ordinary outcome here,
+    // not an error worth putting on an MCP server's stderr at startup.
+    try { return execFileSync(process.platform === "win32" ? "where" : "which", ["ainra"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\n")[0].trim() || null; }
+    catch { return null; }
+  })()],
+  ["checkout", ROOT + "target/release/ainra"],
+];
+const BIN = (CLI_SOURCES.find(([, p]) => p && existsSync(p)) || [null, null])[1];
+const gloss = (v) => (v.verdict === "valid" ? REASONS.valid : REASONS[v.reason] || "");
+
+const NO_CLI =
+  'no ainra CLI found. This tool drives a LOCAL registrar directory, which needs the binary. Provide it in any of ' +
+  'three ways: set AINRA_CLI=/path/to/ainra, put `ainra` on PATH, or build it in a checkout ' +
+  '(`cargo build --release -p ainra-cli-rs`). Reads against a URL target need no binary — set ' +
+  'AINRA_TARGET=https://<your-network> instead.';
+
+function cli(args) {
+  if (!BIN) throw new Error(`${NO_CLI}\n(AINRA_TARGET is currently "${TARGET}")`);
+  try { return execFileSync(BIN, args, { encoding: "utf8", timeout: 15000 }); }
+  catch (e) {
+    const out = (e.stderr || e.stdout || e.message || "").toString().trim();
+    throw new Error(`${out}\n(ran the CLI at ${BIN}; AINRA_TARGET must be a registrar dir you control — currently "${TARGET}")`);
+  }
+}
+async function getJson(path) {
+  let r;
+  try {
+    r = await fetch(TARGET.replace(/\/$/, "") + path, { signal: AbortSignal.timeout(5000) });
+  } catch {
+    throw new Error(`cannot reach the target at ${TARGET} — is it up? Start one with \`make stage-up\` (staging) or set AINRA_TARGET to a running network / local registrar dir.`);
+  }
+  if (!r.ok) throw new Error(`target ${TARGET} returned HTTP ${r.status} for ${path} — check AINRA_TARGET points at a live AINRA network.`);
+  return r.json();
+}
+// One AINRA_TARGET, either shape: an artifact server publishes /registry.json (many registrars, read-only); a
+// registrar daemon serves /export (its own records) + the write API. Agents get the SAME read surface from both.
+async function readRegistry() {
+  try { return await getJson("/registry.json"); } catch { /* fall through to the registrar-daemon shape */ }
+  const ex = await getJson("/export");
+  return {
+    generated_window: { verified_at: ex.verified_at },
+    registrars: [ex],
+    totals: { registrars: 1, issued: (ex.records || []).length, revoked: (ex.records || []).filter((e) => e.record.revoked).length },
+  };
+}
+async function postJson(path, body, what) {
+  const token = process.env.AINRA_STAGE_ISSUE_TOKEN || "";
+  const r = await fetch(TARGET.replace(/\/$/, "") + path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(10000),
+  });
+  const text = await r.text();
+  if (!r.ok) throw new Error(`registrar ${what} returned HTTP ${r.status}: ${text.slice(0, 160)} — a write to a network registrar needs AINRA_STAGE_ISSUE_TOKEN (the operator's bearer token).`);
+  try { return JSON.parse(text); } catch { return { raw: text }; }
+}
+function requireConfirm(input, tool) {
+  if (input.confirm !== true)
+    throw new Error(`${tool} is a WRITE operation against a registrar you control. Re-call with \`confirm: true\` to proceed. Nothing was changed.`);
+}
+
+// ── the tools (def + handler). handler(input) → a plain object; the server wraps it as MCP content. ──
+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.",
+    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." },
+        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." },
+      },
+      required: ["anchors", "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);
+      // 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;
+      return {
+        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 },
+      };
+    },
+  },
+  {
+    name: "ainra_lookup",
+    title: "Look up a public record",
+    description: "Resolve an AINRA name to its public record (tier, authority, standing, carried verdict) from the configured target's directory + log. Read-only.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    inputSchema: { type: "object", properties: { name: { type: "string", description: "The subject name, e.g. ainra:registrar-07:acme:invoicing@4.2.1" } }, required: ["name"] },
+    async handler(input) {
+      if (isUrl(TARGET)) {
+        const reg = await readRegistry();
+        for (const R of reg.registrars) for (const e of R.records)
+          if (e.record.sub === input.name)
+            return { name: e.record.sub, registrar: R.registrar, tier: e.record.tier, authority: e.record.auth_class, standing: e.record.revoked ? "revoked" : "active", verdict: e.verdict.verdict, reason: e.verdict.reason ?? null };
+        throw new Error(`no record for "${input.name}" in the target's registry — list what exists with ainra_status, or issue it with ainra_issue.`);
+      }
+      const out = cli(["present", TARGET, input.name]);
+      const rec = JSON.parse(out);
+      return { name: rec.sub, registrar: rec.registrar, tier: rec.tier, authority: rec.auth_class, standing: rec.revoked ? "revoked" : "active" };
+    },
+  },
+  {
+    name: "ainra_status",
+    title: "Status / freshness of the target",
+    description: "Report the target's current head: network + root label, registrar count, and the verification window (freshness). Read-only.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    inputSchema: { type: "object", properties: {} },
+    async handler() {
+      if (isUrl(TARGET)) {
+        let health = null;
+        try { health = await getJson("/health"); } catch { /* artifact servers have no /health — registry totals still tell the story */ }
+        const reg = await readRegistry();
+        return {
+          target: TARGET,
+          network: health?.network ?? "staging", root: health?.root ?? "test-root",
+          registrar: health?.registrar, write_auth: health?.write_auth,
+          registrars: reg.totals.registrars, issued: reg.totals.issued, revoked: reg.totals.revoked,
+          lineages: reg.registrars.flatMap((R) => R.records.map((e) => e.record.sub)),
+          verified_at: reg.generated_window.verified_at, freshness: "F3", telemetry: "none",
+        };
+      }
+      return { target: TARGET, mode: "local registrar dir", note: "use ainra_lookup <name> to read a record; ainra_status is fullest against a network target.", telemetry: "none" };
+    },
+  },
+  {
+    name: "ainra_issue",
+    title: "Issue a passport (writes to a registrar you control)",
+    description: "Issue a new passport on the configured registrar (a LOCAL dir via the ainra CLI, or a network registrar you hold the write token for). WRITE operation: requires `confirm: true`.",
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        operator: { type: "string" }, lineage: { type: "string" }, version: { type: "string" },
+        tier: { type: "string", default: "L2" }, auth: { type: "string", default: "A2" },
+        capabilities: { type: "array", items: { type: "string" } },
+        confirm: { type: "boolean", description: "Must be true — this writes to your registrar." },
+      },
+      required: ["operator", "lineage", "version", "confirm"],
+    },
+    async handler(input) {
+      requireConfirm(input, "ainra_issue");
+      const caps = input.capabilities?.length ? input.capabilities : ["read:data"];
+      if (isUrl(TARGET)) {
+        const body = { operator: input.operator, lineage: input.lineage, version: input.version, tier: input.tier || "L2", auth_class: input.auth || "A2", principal_proof: "deadbeef" + input.lineage, capabilities: caps, scope_ceiling: caps, hops: [] };
+        const rec = await postJson("/issue", body, "issue");
+        return { issued: rec.sub ?? rec.record?.sub ?? `${input.operator}:${input.lineage}@${input.version}`, tier: rec.tier ?? body.tier, via: TARGET };
+      }
+      const args = ["issue", TARGET, "--operator", input.operator, "--lineage", input.lineage, "--version", input.version, "--tier", input.tier || "L2", "--auth", input.auth || "A2"];
+      for (const c of caps) args.push("--cap", c);
+      const out = cli(args).trim();
+      return { issued: out.split("\n")[0].replace(/^issued /, ""), detail: out };
+    },
+  },
+  {
+    name: "ainra_renew",
+    title: "Renew a passport (writes to a registrar you control)",
+    description: "Reissue a lineage with a fresh validity window (ADR-017 renewal, prev_leaf continuity). WRITE operation: requires `confirm: true`.",
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    inputSchema: { type: "object", properties: { sub: { type: "string" }, version: { type: "string" }, confirm: { type: "boolean" } }, required: ["sub", "version", "confirm"] },
+    async handler(input) {
+      requireConfirm(input, "ainra_renew");
+      if (isUrl(TARGET)) {
+        // ADR-017 reissue over the registrar's public door — fresh window, prev_leaf continuity, new status bit.
+        const out = await postJson("/renew", { sub: input.sub, new_version: input.version, now: Math.floor(Date.now() / 1000) }, "renew");
+        return { renewed: input.sub, new_generation: out.sub ?? out.record?.sub ?? input.sub.replace(/@.*$/, "@" + input.version), via: TARGET };
+      }
+      const out = cli(["renew", TARGET, input.sub, "--version", input.version]).trim();
+      return { renewed: input.sub, detail: out };
+    },
+  },
+  {
+    name: "ainra_revoke",
+    title: "Revoke a passport (DESTRUCTIVE — writes to a registrar you control)",
+    description: "Set a lineage's revocation bit; it fails closed everywhere within the freshness window. DESTRUCTIVE and requires `confirm: true`.",
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: { type: "object", properties: { sub: { type: "string" }, confirm: { type: "boolean", description: "Must be true — this revokes a live credential." } }, required: ["sub", "confirm"] },
+    async handler(input) {
+      requireConfirm(input, "ainra_revoke");
+      if (isUrl(TARGET)) {
+        await postJson("/revoke", { sub: input.sub, now: Math.floor(Date.now() / 1000) }, "revoke");
+        return { revoked: input.sub, via: TARGET, note: "fails closed everywhere within the freshness window" };
+      }
+      const out = cli(["revoke", TARGET, input.sub]).trim();
+      return { revoked: input.sub, detail: out.split("\n")[0] };
+    },
+  },
+];
+
+export const TOOL_BY_NAME = Object.fromEntries(TOOLS.map((t) => [t.name, t]));
+export const TARGET_INFO = { target: TARGET, mode: isUrl(TARGET) ? "network" : "local-dir" };