sello 0.1.15 → 0.1.17

package/README.md

@@ -16,16 +16,10 @@
 <p align="center">
   <a href="#try-it">Quickstart</a> &middot;
   <a href="#add-sello-to-a-tool">Add Sello</a> &middot;
-  <a href="#add-sello-to-an-mcp-server">MCP</a> &middot;
+  <a href="docs/mcp.md">MCP</a> &middot;
   <a href="sdks/README.md">SDKs</a> &middot;
-  <a href="#see-logged-actions">Actions</a> &middot;
-  <a href="#how-it-works">How It Works</a> &middot;
-  <a href="#learn-more">Learn More</a> &middot;
   <a href="SPEC.md">Protocol</a> &middot;
-  <a href="https://arxiv.org/abs/2606.04193">Paper</a> &middot;
-  <a href="SECURITY.md">Security</a> &middot;
-  <a href="CONTRIBUTING.md">Contributing</a> &middot;
-  <a href="#license">License</a>
+  <a href="https://arxiv.org/abs/2606.04193">Paper</a>
 </p>
 
 Sello is a protocol for independently-verifiable records of AI agent actions.
@@ -110,11 +104,13 @@ SELLO_SUBMIT_MODE=background
 
 Sello works with your own log server. Using `sello.build` is an optional convenience, not a protocol requirement.
 
-To scaffold a tiny emitter or HTTP route:
+To scaffold a tiny demo for each boundary:
 
 ```bash
 npx --yes sello init-demo
 npx --yes sello init-http-demo
+npx --yes sello init-mcp-demo
+npx --yes sello init-a2a-demo
 ```
 
 ## Add Sello to an MCP Server
@@ -150,6 +146,37 @@ receipts.mcpTool("calendar.create_event", handler, {
 });
 ```
 
+See [docs/mcp.md](docs/mcp.md) for token handling, hash boundaries, unknown-tool behavior, and action viewing.
+
+## Add Sello to an A2A Agent
+
+If your service receives Agent2Agent messages, wrap the message handler:
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const sendMessage = receipts.a2aMessage(async (request, context) => {
+  return agent.handleMessage(request, context);
+});
+```
+
+`a2aMessage` verifies the agent token before your handler runs, preserves the handler's return value, rethrows handler errors, and emits a receipt with action type `a2a.<method>`, such as `a2a.message/send`.
+
+By default, Sello hashes the A2A JSON-RPC `method` and `params`, excluding request ids, headers, bearer tokens, and runtime context.
+
+See [docs/a2a.md](docs/a2a.md) for token handling, hash boundaries, unknown-method behavior, and action viewing.
+
+## Examples
+
+| What you want to wire | Start here |
+| --- | --- |
+| A normal tool handler | [SDK Quickstart](docs/sdk-quickstart.md) and [`quickstart-tool.ts`](sdks/typescript/examples/quickstart-tool.ts) |
+| An MCP tool | `npx --yes sello init-mcp-demo`, [MCP Integration](docs/mcp.md), and [`mcp-minimal-server.ts`](sdks/typescript/examples/mcp-minimal-server.ts) |
+| An A2A message handler | `npx --yes sello init-a2a-demo`, [A2A Integration](docs/a2a.md), and [`a2a-minimal-server.ts`](sdks/typescript/examples/a2a-minimal-server.ts) |
+| Verified action viewing | `npx sello actions` or `http://localhost:8787/actions` |
+
 ## See Logged Actions
 
 ```bash
@@ -184,15 +211,16 @@ Sello does not prove that the agent called every service it should have called,
 ## Learn More
 
 - [SDK Quickstart](docs/sdk-quickstart.md): local dev, HTTP demo, self-hosted config, and hosted config.
+- [MCP Integration](docs/mcp.md): where Sello wraps MCP tool callbacks.
+- [A2A Integration](docs/a2a.md): where Sello wraps Agent2Agent message handlers.
 - [SDKs](sdks/README.md): TypeScript and Python package layout.
 - [Python SDK](sdks/python/README.md): Python package install command, scope, and test command.
 - [Protocol Walkthrough](docs/protocol-walkthrough.md): the primitive receipt loop for implementers.
 - [SPEC.md](SPEC.md): the Sello protocol draft.
 - [Notarized Agents paper](https://arxiv.org/abs/2606.04193): design rationale, threat model, and prior art.
-- [sdks/typescript/examples/mcp-minimal-server.ts](sdks/typescript/examples/mcp-minimal-server.ts): a small MCP integration.
 - [docs/security-review.md](docs/security-review.md) and [docs/sdk-security-audit.md](docs/sdk-security-audit.md): current review notes.
 
-The TypeScript SDK is published on [npm](https://www.npmjs.com/package/sello) and lives in [`sdks/typescript/`](sdks/typescript/). The Python SDK is published on [PyPI](https://pypi.org/project/sello/) and lives in [`sdks/python/`](sdks/python/). Both SDKs support the same service-side `sello.service()` flow; Python uses the `@receipts.tool(...)` decorator. Live Rekor proof verification and production identity operations are still future work.
+The TypeScript SDK is published on [npm](https://www.npmjs.com/package/sello) and lives in [`sdks/typescript/`](sdks/typescript/). The Python SDK is published on [PyPI](https://pypi.org/project/sello/) and lives in [`sdks/python/`](sdks/python/). Both SDKs support the same service-side `sello.service()` flow; Python uses the `@receipts.tool(...)` decorator. MCP and A2A helpers are currently TypeScript-first. Live Rekor proof verification and production identity operations are still future work.
 
 ## Core Terms
 

package/dist/cli/sello.js

@@ -96,6 +96,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;
@@ -337,13 +343,13 @@ function initDemoCommand(args          )       {
   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          )       {
@@ -359,7 +365,7 @@ function initHttpDemoCommand(args          )       {
   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}`);
@@ -368,7 +374,51 @@ function initHttpDemoCommand(args          )       {
   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          )       {
+  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          )       {
+  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          )       {
@@ -851,6 +901,8 @@ function printHelp()       {
   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
@@ -917,6 +969,25 @@ function formatHttpDemoResponse(responseText        )         {
   }
 }
 
+function devCommandHint()         {
+  const state = loadDevStateIfPresent();
+  const port = state ? portFromDevState(state) : undefined;
+  return port && port !== "8787" ? `npx sello dev --port ${port}` : "npx sello dev";
+}
+
+function actionViewerUrlHint()         {
+  const state = loadDevStateIfPresent();
+  return state ? actionViewerUrl(state) : "http://localhost:8787/actions";
+}
+
+function portFromDevState(state          )                     {
+  try {
+    return new URL(state.logEndpoint).port;
+  } catch {
+    return undefined;
+  }
+}
+
 function slug(value        )         {
   return value
     .toLowerCase()
@@ -1080,3 +1151,124 @@ function slug(value) {
 }
 `;
 }
+
+function mcpDemoSource()         {
+  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()         {
+  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";
+}
+`;
+}

package/dist/sdk/service.js

@@ -25,6 +25,8 @@ import {
          
                                   
 
+                                                                               
+
                                                      
                              
                         
@@ -71,6 +73,35 @@ import {
                                     
   
 
+                                                                     
+                   
+                   
+  
+
+                                                                            
+                   
+                   
+                                  
+
+                                                                            
+                                                                            
+                                          
+                                                
+                       
+    
+                       
+                                                            
+                  
+                                                          
+                                                     
+              
+                                                            
+                                  
+                    
+                                                            
+                                    
+  
+
                                   
                    
                                
@@ -100,6 +131,10 @@ import {
                                                           
                                                            
                                                   
+                                                   
+                                                                
+                                                                 
+                                                        
                          
   
 
@@ -150,11 +185,14 @@ export function createSelloService(input                    )                {
   }
 
   function wrapTool                   (
-    actionType        ,
+    actionType                          ,
     handler                                     ,
     options                                      = {},
   )                                      {
-    if (typeof actionType !== "string" || actionType.length === 0) {
+    if (
+      (typeof actionType === "string" && actionType.length === 0) ||
+      (typeof actionType !== "string" && typeof actionType !== "function")
+    ) {
       throw new TypeError("Sello action type must be a non-empty string");
     }
 
@@ -174,6 +212,7 @@ export function createSelloService(input                    )                {
         resolved.fallbackSelloLogs,
         resolved.log.logUrl,
       );
+      const resolvedActionType = resolveActionType(actionType, request);
       const base = {
         authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
         ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
@@ -182,7 +221,7 @@ export function createSelloService(input                    )                {
         servicePrivateKey: resolved.servicePrivateKey,
         serviceIdentifier: resolved.service,
         logUrl: resolved.log.logUrl,
-        actionType,
+        actionType: resolvedActionType,
         actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
         timestamp: resolved.now(),
       };
@@ -271,6 +310,32 @@ export function createSelloService(input                    )                {
         return await wrapped({ name, arguments: args, context });
       };
     },
+    a2aMessage                                      (
+      handler                                                    ,
+      options                                                     = {},
+    )                                                     {
+      const wrapped = wrapTool 
+                                                    
+                
+       (
+        options.actionType ?? defaultA2aActionType,
+        async (invocation) => handler(invocation.request, invocation.context),
+        {
+          authorizationToken:
+            options.authorizationToken ?? defaultA2aAuthorizationToken,
+          canonicalizeInput:
+            options.canonicalizeInput ?? defaultA2aCanonicalizeInput,
+          canonicalizeOutput: options.canonicalizeOutput,
+          canonicalizeError: options.canonicalizeError,
+          isDenied: options.isDenied,
+          deniedResponse: options.deniedResponse,
+        },
+      );
+
+      return async (request         , context         )                    => {
+        return await wrapped({ request, context });
+      };
+    },
     async flush()                {
       await publisher?.flush();
     },
@@ -587,6 +652,53 @@ function defaultMcpCanonicalizeInput(
   });
 }
 
+function defaultA2aAuthorizationToken(
+  invocation                                             ,
+)                      {
+  const fromContext = authorizationTokenFromUnknown(invocation.context);
+  if (fromContext) {
+    return fromContext;
+  }
+
+  const fromRequest = authorizationTokenFromUnknown(invocation.request);
+  if (fromRequest) {
+    return fromRequest;
+  }
+
+  throw new TypeError(
+    "Sello A2A authorization token not found. Pass authorizationToken or include an Authorization header in the A2A context.",
+  );
+}
+
+function defaultA2aActionType(
+  invocation                                             ,
+)         {
+  const method = methodFromA2aRequest(invocation.request);
+  return method ? `a2a.${method}` : "a2a.message/send";
+}
+
+function defaultA2aCanonicalizeInput(
+  invocation                                             ,
+)             {
+  if (isRecord(invocation.request) && typeof invocation.request.method === "string") {
+    return canonicalJsonBytes({
+      method: invocation.request.method,
+      params: invocation.request.params ?? null,
+    });
+  }
+
+  return canonicalJsonBytes(invocation.request);
+}
+
+function methodFromA2aRequest(request         )                     {
+  if (!isRecord(request)) {
+    return undefined;
+  }
+
+  const method = request.method;
+  return typeof method === "string" && method.length > 0 ? method : undefined;
+}
+
 function authorizationTokenFromUnknown(value         )                                  {
   if (!isRecord(value)) {
     return undefined;
@@ -692,6 +804,20 @@ function resolveValue                (
   return value;
 }
 
+function resolveActionType         (
+  actionType                          ,
+  request         ,
+)         {
+  const resolved =
+    typeof actionType === "function" ? actionType(request) : actionType;
+
+  if (typeof resolved !== "string" || resolved.length === 0) {
+    throw new TypeError("Sello action type must be a non-empty string");
+  }
+
+  return resolved;
+}
+
 function envSubmitMode(env             )                                              {
   const mode = env.SELLO_SUBMIT_MODE;
   if (mode === undefined) {

package/docs/a2a.md

@@ -0,0 +1,139 @@
+# Add Sello to an A2A Agent
+
+Sello belongs around the handler that receives an A2A message: after your server has accepted the request and before your agent logic runs.
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const sendMessage = receipts.a2aMessage(async (request, context) => {
+  return agent.handleMessage(request, context);
+});
+```
+
+## What It Does
+
+`receipts.a2aMessage(...)` returns a normal A2A message handler. When another agent sends a message, Sello:
+
+1. Reads the agent authorization token from the A2A context.
+2. Verifies the token before your handler runs.
+3. Runs your handler unchanged.
+4. Emits a `success`, `error`, or `denied` receipt.
+5. Preserves the handler return value and rethrows handler errors.
+
+For JSON-RPC requests, the default receipt action type is:
+
+```text
+a2a.<method>
+```
+
+For `message/send`, the action type is:
+
+```text
+a2a.message/send
+```
+
+## Token Source
+
+By default, Sello looks for `Authorization: Bearer ...` in common context or request shapes, including:
+
+```ts
+context.headers.authorization
+context.requestInfo.headers.authorization
+context.request.headers.authorization
+request.headers.authorization
+```
+
+Fetch-style `Headers` objects are supported too.
+
+If your A2A runtime stores the token somewhere else, pass an extractor:
+
+```ts
+receipts.a2aMessage(handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
+The token should be the same authorization token the calling agent used for the A2A request. Sello hashes the exact token bytes into `sello_token_ref`; do not parse and reserialize it first.
+
+## What Gets Hashed
+
+For JSON-RPC-shaped A2A requests, the default input hash covers only the stable method boundary:
+
+```json
+{
+  "method": "message/send",
+  "params": {}
+}
+```
+
+Sello does not hash:
+
+- The bearer token.
+- Transport headers.
+- JSON-RPC request ids.
+- 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 Methods
+
+Only wrap A2A methods you actually execute. If a request names an unknown method, return your normal JSON-RPC method-not-found error without emitting a Sello receipt.
+
+The minimal example does this:
+
+```ts
+if (request.body.method !== "message/send") {
+  return {
+    jsonrpc: "2.0",
+    id: request.body.id,
+    error: { code: -32601, message: "method not found" },
+  };
+}
+```
+
+## View Actions
+
+In local development:
+
+```bash
+npx sello dev
+```
+
+Run your A2A message 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 A2A-shaped demo in your project:
+
+```bash
+npx --yes sello init-a2a-demo
+node sello-a2a-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/a2a-minimal-server.ts`](../sdks/typescript/examples/a2a-minimal-server.ts) for a dependency-free A2A-shaped example. It wraps one `message/send` handler and leaves unknown methods unreceipted.