sello 0.1.15 → 0.1.17

package/docs/mcp.md

@@ -0,0 +1,149 @@
+# Add Sello to an MCP Server
+
+Sello belongs around the tool callback: after your MCP server has identified the tool, before your business logic runs.
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+server.registerTool(
+  "calendar.create_event",
+  { inputSchema: createEventInputSchema },
+  receipts.mcpTool("calendar.create_event", async (args) => {
+    const event = await calendar.events.create(args);
+    return {
+      content: [{ type: "text", text: event.id }],
+    };
+  }),
+);
+```
+
+Some MCP SDK versions call this registration method `tool` instead of `registerTool`. Use the same callback slot either way.
+
+## What It Does
+
+`receipts.mcpTool(...)` returns a normal MCP tool callback. When the agent calls the tool, Sello:
+
+1. Reads the agent authorization token from the MCP context.
+2. Verifies the token before your callback runs.
+3. Runs your callback unchanged.
+4. Emits a `success`, `error`, or `denied` receipt.
+5. Preserves the callback return value and rethrows callback errors.
+
+The default receipt action type is:
+
+```text
+mcp.tools/call.<tool-name>
+```
+
+For `calendar.create_event`, the action type is:
+
+```text
+mcp.tools/call.calendar.create_event
+```
+
+## Token Source
+
+By default, Sello looks for `Authorization: Bearer ...` in common MCP context shapes, including:
+
+```ts
+context.headers.authorization
+context.requestInfo.headers.authorization
+context.request.headers.authorization
+```
+
+Fetch-style `Headers` objects are supported too.
+
+If your transport stores the token somewhere else, pass an extractor:
+
+```ts
+receipts.mcpTool("calendar.create_event", handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
+The token should be the same authorization token the agent used for the tool call. Sello hashes the exact token bytes into `sello_token_ref`; do not parse and reserialize it first.
+
+## What Gets Hashed
+
+The default MCP input hash covers only the stable MCP action shape:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "calendar.create_event",
+    "arguments": {}
+  }
+}
+```
+
+Sello does not hash:
+
+- The bearer token.
+- Transport headers.
+- Connection/session objects.
+- Other context that may vary across runtimes.
+
+That keeps receipts stable without leaking secrets or transport details.
+
+If you need a different hash boundary, pass `canonicalizeInput`.
+
+## Unknown Tools
+
+Only wrap tools you actually execute. If a request names an unknown tool, return your normal MCP `method not found` or `tool not found` error without emitting a Sello receipt.
+
+The minimal example does this:
+
+```ts
+if (request.body.params.name !== "calendar.create_event") {
+  return {
+    jsonrpc: "2.0",
+    id: request.body.id,
+    error: { code: -32601, message: "tool not found" },
+  };
+}
+```
+
+## View Actions
+
+In local development:
+
+```bash
+npx sello dev
+```
+
+Run your MCP tool call, then view verified actions:
+
+```bash
+npx sello actions
+```
+
+Or open:
+
+```text
+http://localhost:8787/actions
+```
+
+For a specific agent token:
+
+```bash
+npx sello actions --token <agent-token>
+```
+
+## Runnable Demo
+
+To generate a tiny MCP-shaped demo in your project:
+
+```bash
+npx --yes sello init-mcp-demo
+node sello-mcp-demo.mjs
+npx --yes sello actions
+```
+
+Keep `npx sello dev` running in another terminal while you run the generated file.
+
+## Example
+
+See [`sdks/typescript/examples/mcp-minimal-server.ts`](../sdks/typescript/examples/mcp-minimal-server.ts) for a dependency-free MCP-shaped example. It wraps one `tools/call` handler and leaves unknown tools unreceipted.

package/docs/release-checklist.md

@@ -16,6 +16,9 @@ Use this checklist before publishing a Sello release.
 
 ```bash
 node --run test
+node --run package:test
+node --run package:a2a-test
+node --run package:mcp-test
 npm pack --dry-run
 ```
 
@@ -28,6 +31,8 @@ cd "$tmpdir/sello"
 node -v # must be v22.7.0 or newer
 node --run test
 node --run package:test
+node --run package:a2a-test
+node --run package:mcp-test
 npm pack --dry-run
 node --experimental-strip-types sdks/typescript/src/cli/sello.ts --help
 node --experimental-strip-types sdks/typescript/src/cli/sello.ts dev --dry-run
@@ -67,6 +72,8 @@ git push origin main --tags
 After publishing:
 
 - Confirm `npm view sello version` shows the new version.
+- Confirm `SELLO_PACKAGE_SPEC=sello@$(node -p "require('./package.json').version") node --run package:a2a-test` passes against the published npm package.
+- Confirm `SELLO_PACKAGE_SPEC=sello@$(node -p "require('./package.json').version") node --run package:mcp-test` passes against the published npm package.
 - Publish a GitHub Release for the pushed tag so PyPI trusted publishing runs.
 - Confirm `python -m pip index versions sello` shows the new version after PyPI publishing.
 - Confirm `npx sello --help` works from a clean temp directory.

package/docs/sdk-quickstart.md

@@ -72,18 +72,43 @@ npx --yes sello call-http-demo
 npx --yes sello actions
 ```
 
+To try the same local loop around MCP or A2A-shaped handlers:
+
+```bash
+npx --yes sello init-mcp-demo
+node sello-mcp-demo.mjs
+npx --yes sello actions
+```
+
+```bash
+npx --yes sello init-a2a-demo
+node sello-a2a-demo.mjs
+npx --yes sello actions
+```
+
 ## What Just Happened?
 
-`sello dev` created local development keys, a demo authorization token, a service registry, and a local transparency log. The wrapped tool or route verified the token before running your handler. After the handler returned, Sello signed an encrypted receipt for the observed action and submitted it to the local log. The log stored encrypted receipt data, not plaintext action details. `sello actions` used the owner key from local dev state to fetch, verify, decrypt, and print the action.
+`sello dev` created local development keys, a demo authorization token, a service registry, and a local transparency log. The wrapped function, route, MCP tool, or A2A message callback verified the token before running your code. After your code returned, Sello signed an encrypted receipt for the observed action and submitted it to the local log. The log stored encrypted receipt data, not plaintext action details. `sello actions` used the owner key from local dev state to fetch, verify, decrypt, and print the action.
 
 Local dev state lives under `.sello/`. The encrypted dev log is stored in `.sello/dev-log.jsonl`, so receipts survive restarting `sello dev` without being committed to git.
 
+## Which Wrapper?
+
+| Existing boundary | Use |
+| --- | --- |
+| Plain function or HTTP route | `receipts.tool("calendar.create_event", handler)` |
+| MCP `tools/call` callback | `receipts.mcpTool("calendar.create_event", handler)` |
+| A2A JSON-RPC message handler | `receipts.a2aMessage(handler)` |
+| Owner action viewing | `npx sello actions` |
+
 ## Troubleshooting
 
 - **Port already in use:** run `npx sello dev --port 8791`.
 - **No actions found:** make sure `sello dev` is running from the same project folder where you emitted the receipt.
 - **Missing token:** run `npx sello dev` first so `.sello/dev.json` exists.
 
+## Contributing From This Repo
+
 Inside this repo, start the local log and action viewer:
 
 ```bash
@@ -126,6 +151,30 @@ receipts.mcpTool("calendar.create_event", handler, {
 });
 ```
 
+For the complete MCP placement notes, see [MCP Integration](mcp.md).
+
+For an A2A agent, wrap the message handler you already expose:
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const sendMessage = receipts.a2aMessage(async (request, context) => {
+  return agent.handleMessage(request, context);
+});
+```
+
+`receipts.a2aMessage(...)` uses action type `a2a.<method>`, for example `a2a.message/send`, and hashes only the A2A JSON-RPC method and params. It excludes request ids, headers, bearer tokens, and runtime context. If your transport stores the token somewhere else, pass an extractor:
+
+```ts
+receipts.a2aMessage(handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
+For the complete A2A placement notes, see [A2A Integration](a2a.md).
+
 Or run the matching Python example:
 
 ```bash

package/docs/sdk-security-audit.md

@@ -30,6 +30,7 @@ These notes cover the first Stripe-style SDK implementation pass. They are writt
 - Success, error, and denied paths emit receipts without including plaintext request or response bodies.
 - The wrapper uses the configured service identity and key for every receipt.
 - `receipts.mcpTool(...)` reuses the same wrapper path. It defaults to hashing the MCP `tools/call` method, tool name, and arguments, while excluding bearer tokens and transport context from the action input hash.
+- `receipts.a2aMessage(...)` reuses the same wrapper path. It defaults to hashing the A2A JSON-RPC method and params, while excluding bearer tokens, request ids, headers, and runtime context from the action input hash.
 
 ## Phase 4: Logs And Action Viewing
 
@@ -44,6 +45,7 @@ These notes cover the first Stripe-style SDK implementation pass. They are writt
 - The example uses `submit: { mode: "await" }` so the command succeeds only after the receipt append completes.
 - The example canonicalizes only tool input fields and excludes the authorization token wrapper from the action input hash.
 - The MCP-style example reads the bearer token from the transport header, but hashes only the `tools/call` method and params.
+- The A2A-style example reads the bearer token from the transport header, but hashes only the JSON-RPC method and params.
 - README and quickstart docs keep self-hosting first-class and describe `sello.build` as optional convenience.
 
 ## Residual Risks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -31,10 +31,13 @@
     "bench": "node --experimental-strip-types sdks/typescript/src/cli/bench.ts",
     "demo": "node --experimental-strip-types sdks/typescript/src/cli/demo.ts",
     "dev": "node --experimental-strip-types sdks/typescript/src/cli/sello.ts dev",
+    "example:a2a:minimal": "node --test --experimental-strip-types sdks/typescript/test/examples/a2a-minimal-server.test.ts",
     "example:mcp:minimal": "node --test --experimental-strip-types sdks/typescript/test/examples/mcp-minimal-server.test.ts",
     "example:mcp": "node --experimental-strip-types sdks/typescript/examples/mcp-tool-server.ts",
     "example:tool": "node --experimental-strip-types sdks/typescript/examples/quickstart-tool.ts",
     "build": "node --disable-warning=ExperimentalWarning sdks/typescript/scripts/build-dist.mjs",
+    "package:a2a-test": "node sdks/typescript/scripts/package-a2a-smoke.mjs",
+    "package:mcp-test": "node sdks/typescript/scripts/package-mcp-smoke.mjs",
     "package:test": "node sdks/typescript/scripts/package-smoke.mjs",
     "pack:check": "node sdks/typescript/scripts/pack-check.mjs",
     "prepack": "node --disable-warning=ExperimentalWarning sdks/typescript/scripts/build-dist.mjs",
@@ -49,7 +52,8 @@
     "transparency-log",
     "cose",
     "hpke",
-    "mcp"
+    "mcp",
+    "a2a"
   ],
   "publishConfig": {
     "access": "public"

package/sdks/README.md

@@ -2,7 +2,7 @@
 
 The protocol, paper, and project docs live at the repository root. Language SDKs live here:
 
-- [`typescript/`](typescript/): npm package source, CLI, examples, fixtures, and Node tests.
+- [`typescript/`](typescript/): npm package source, CLI, MCP/A2A helpers, examples, fixtures, and Node tests.
 - [`python/`](python/): Python package source and tests.
 
 Root commands still work from the repository top level:

package/sdks/typescript/examples/a2a-minimal-server.ts

@@ -0,0 +1,85 @@
+import { sello, type SelloReceipts } from "../src/index.ts";
+
+export type MinimalA2aRequest = {
+  headers: {
+    authorization?: string;
+    Authorization?: string;
+  };
+  body: {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    method: string;
+    params: {
+      message: {
+        role: "user" | "agent";
+        parts: { kind: "text"; text: string }[];
+      };
+    };
+  };
+};
+
+export type MinimalA2aResponse = {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: {
+    kind: "message";
+    messageId: string;
+    role: "agent";
+    parts: { kind: "text"; text: string }[];
+  };
+  error?: {
+    code: number;
+    message: string;
+  };
+};
+
+export function createCalendarA2aAgent(
+  receipts: SelloReceipts = sello.service(),
+) {
+  const sendMessage = receipts.a2aMessage<
+    MinimalA2aRequest["body"],
+    MinimalA2aResponse,
+    MinimalA2aRequest
+  >(async (body) => {
+    const text = body.params.message.parts
+      .filter((part) => part.kind === "text")
+      .map((part) => part.text)
+      .join(" ");
+    const title = text || "untitled";
+
+    return {
+      jsonrpc: "2.0",
+      id: body.id,
+      result: {
+        kind: "message",
+        messageId: "calendar-reply-1",
+        role: "agent",
+        parts: [
+          {
+            kind: "text",
+            text: `created ${title}`,
+          },
+        ],
+      },
+    };
+  });
+
+  return {
+    async handle(request: MinimalA2aRequest): Promise<MinimalA2aResponse> {
+      if (request.body.method !== "message/send") {
+        return {
+          jsonrpc: "2.0",
+          id: request.body.id,
+          error: {
+            code: -32601,
+            message: "method not found",
+          },
+        };
+      }
+
+      return await sendMessage(request.body, request);
+    },
+
+    flush: () => receipts.flush(),
+  };
+}

package/sdks/typescript/src/cli/sello.ts

@@ -97,6 +97,12 @@ try {
     case "init-http-demo":
       initHttpDemoCommand(process.argv.slice(3));
       break;
+    case "init-mcp-demo":
+      initMcpDemoCommand(process.argv.slice(3));
+      break;
+    case "init-a2a-demo":
+      initA2aDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -338,13 +344,13 @@ function initDemoCommand(args: string[]): void {
   console.log(`Created ${output}`);
   console.log("");
   console.log("Terminal 1: keep the local dev log running");
-  console.log("  npx sello dev");
+  console.log(`  ${devCommandHint()}`);
   console.log("");
   console.log("Terminal 2: emit and view a receipt");
   console.log(`  node ${output}`);
   console.log("  npx sello actions");
   console.log("");
-  console.log("Then open http://localhost:8787/actions");
+  console.log(`Then open ${actionViewerUrlHint()}`);
 }
 
 function initHttpDemoCommand(args: string[]): void {
@@ -360,7 +366,7 @@ function initHttpDemoCommand(args: string[]): void {
   console.log(`Created ${output}`);
   console.log("");
   console.log("Terminal 1: keep the local dev log running");
-  console.log("  npx sello dev");
+  console.log(`  ${devCommandHint()}`);
   console.log("");
   console.log("Terminal 2: start the route");
   console.log(`  node ${output}`);
@@ -369,7 +375,51 @@ function initHttpDemoCommand(args: string[]): void {
   console.log("  npx sello call-http-demo");
   console.log("  npx sello actions");
   console.log("");
-  console.log("Then open http://localhost:8787/actions");
+  console.log(`Then open ${actionViewerUrlHint()}`);
+}
+
+function initMcpDemoCommand(args: string[]): void {
+  const output = readFlag(args, "--output") ?? "sello-mcp-demo.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, mcpDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log(`  ${devCommandHint()}`);
+  console.log("");
+  console.log("Terminal 2: run the MCP-shaped tool call and view the receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  console.log(`Then open ${actionViewerUrlHint()}`);
+}
+
+function initA2aDemoCommand(args: string[]): void {
+  const output = readFlag(args, "--output") ?? "sello-a2a-demo.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, a2aDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log(`  ${devCommandHint()}`);
+  console.log("");
+  console.log("Terminal 2: run the A2A-shaped message and view the receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  console.log(`Then open ${actionViewerUrlHint()}`);
 }
 
 function keysCommand(args: string[]): void {
@@ -852,6 +902,8 @@ function printHelp(): void {
   sello call-http-demo [--url http://localhost:8790/calendar/events] [--title title]
   sello init-demo [--output emit-receipt.mjs] [--force]
   sello init-http-demo [--output sello-http-route.mjs] [--force]
+  sello init-mcp-demo [--output sello-mcp-demo.mjs] [--force]
+  sello init-a2a-demo [--output sello-a2a-demo.mjs] [--force]
   sello actions [--token agent-token]
   sello keys service
   sello inspect-env
@@ -918,6 +970,25 @@ function formatHttpDemoResponse(responseText: string): string {
   }
 }
 
+function devCommandHint(): string {
+  const state = loadDevStateIfPresent();
+  const port = state ? portFromDevState(state) : undefined;
+  return port && port !== "8787" ? `npx sello dev --port ${port}` : "npx sello dev";
+}
+
+function actionViewerUrlHint(): string {
+  const state = loadDevStateIfPresent();
+  return state ? actionViewerUrl(state) : "http://localhost:8787/actions";
+}
+
+function portFromDevState(state: DevState): string | undefined {
+  try {
+    return new URL(state.logEndpoint).port;
+  } catch {
+    return undefined;
+  }
+}
+
 function slug(value: string): string {
   return value
     .toLowerCase()
@@ -1081,3 +1152,124 @@ function slug(value) {
 }
 `;
 }
+
+function mcpDemoSource(): string {
+  return `import { readFileSync } from "node:fs";
+import { sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+
+const receipts = sello.service({
+  service: state.serviceId,
+  serviceKey: state.serviceKey,
+  tokenIssuer: state.tokenIssuerPublicKey,
+  log: sello.logs.http(state.logUrl, { endpoint: state.logEndpoint }),
+  submit: { mode: "await" },
+});
+
+const createEvent = receipts.mcpTool("calendar.create_event", async (args) => {
+  const title = readString(args.title, "title");
+  return {
+    content: [
+      {
+        type: "text",
+        text: "created " + title,
+      },
+    ],
+  };
+});
+
+const response = await createEvent(
+  {
+    title: "MCP launch checklist",
+  },
+  {
+    requestInfo: {
+      headers: new Headers({
+        authorization: "Bearer " + state.agentToken,
+      }),
+    },
+  },
+);
+
+await receipts.flush();
+
+console.log("MCP tool response:");
+console.log(JSON.stringify(response, null, 2));
+
+function readString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(name + " must be a non-empty string");
+  }
+  return value;
+}
+`;
+}
+
+function a2aDemoSource(): string {
+  return `import { readFileSync } from "node:fs";
+import { sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+
+const receipts = sello.service({
+  service: state.serviceId,
+  serviceKey: state.serviceKey,
+  tokenIssuer: state.tokenIssuerPublicKey,
+  log: sello.logs.http(state.logUrl, { endpoint: state.logEndpoint }),
+  submit: { mode: "await" },
+});
+
+const sendMessage = receipts.a2aMessage(async (request) => ({
+  jsonrpc: "2.0",
+  id: request.id,
+  result: {
+    kind: "message",
+    messageId: "calendar-reply-1",
+    role: "agent",
+    parts: [
+      {
+        kind: "text",
+        text: "created " + readMessageText(request),
+      },
+    ],
+  },
+}));
+
+const response = await sendMessage(
+  {
+    jsonrpc: "2.0",
+    id: "a2a-demo-1",
+    method: "message/send",
+    params: {
+      message: {
+        role: "user",
+        parts: [
+          {
+            kind: "text",
+            text: "A2A launch checklist",
+          },
+        ],
+      },
+    },
+  },
+  {
+    headers: new Headers({
+      authorization: "Bearer " + state.agentToken,
+    }),
+  },
+);
+
+await receipts.flush();
+
+console.log("A2A message response:");
+console.log(JSON.stringify(response, null, 2));
+
+function readMessageText(request) {
+  return request.params.message.parts
+    .filter((part) => part.kind === "text")
+    .map((part) => part.text)
+    .join(" ") || "untitled";
+}
+`;
+}