sello 0.1.3 → 0.1.5

package/README.md

@@ -15,6 +15,33 @@ agent calls service
   -> owner fetches, verifies, decrypts
 ```
 
+## Try It
+
+Requires Node.js 22.7 or newer.
+
+From a new project or temporary folder:
+
+```bash
+# Terminal 1
+npx --yes sello dev
+
+# Terminal 2
+npx --yes sello emit-demo
+npx --yes sello actions
+```
+
+Then open:
+
+```text
+http://localhost:8787/actions
+```
+
+To see the tiny wrapped-tool source:
+
+```bash
+npx --yes sello init-demo
+```
+
 ## Why Sello?
 
 Most agent logs are written by the same system whose behavior they describe. If the agent, runtime, or operator is compromised, those logs can be incomplete or false.
@@ -48,14 +75,13 @@ The implementation includes a local end-to-end demo, compact JWS token verificat
 
 ## Start Here
 
-Sello currently requires Node.js 22.7 or newer.
-
 | Goal | Read |
 |------|------|
 | Add Sello in a few lines | [SDK Quickstart](docs/sdk-quickstart.md) |
-| Emit your first receipt | `npx sello dev`, then `npx sello emit-demo` |
+| Emit your first receipt | `npx --yes sello dev`, then `npx --yes sello emit-demo` |
 | Try a wrapped tool locally | `node --run dev`, then `node --run example:tool` |
 | Try an MCP-style tool call | `node --run dev`, then `node --run example:mcp` |
+| See a minimal MCP integration | [examples/mcp-minimal-server.ts](examples/mcp-minimal-server.ts) |
 | Understand the protocol | [SPEC.md](SPEC.md) Quick Start |
 | Run the local demo | `node --run demo` |
 | Run the test suite | `node --run test` |
@@ -82,6 +108,14 @@ Then inspect verified actions:
 npx sello actions --token <agent-token>
 ```
 
+In local dev, `sello dev` prints and saves a demo token:
+
+```bash
+SELLO_ACTION_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
+```
+
+You usually do not need to copy it. `npx sello actions` reads the latest dev token from `.sello/dev.json`. Use `--token` when you want to inspect receipts for a specific agent authorization token from your own system.
+
 Sello works with your own log server. `sello.build` is optional convenience, not a protocol requirement.
 
 To try the repo's local loop:
@@ -99,22 +133,7 @@ The example wraps a fake calendar tool, emits a service-signed encrypted receipt
 
 For an MCP-shaped `tools/call` boundary, run `node --run example:mcp` instead of `node --run example:tool`.
 
-To try the published package from a fresh project:
-
-```bash
-# Terminal 1
-npx sello dev
-
-# Terminal 2
-npx sello emit-demo
-npx sello actions
-```
-
-To see the tiny emitter code:
-
-```bash
-npx sello init-demo
-```
+For a smaller production-shaped MCP example, see [examples/mcp-minimal-server.ts](examples/mcp-minimal-server.ts). It wraps one `tools/call` handler with `sello.service()` and leaves unknown tools unreceipted.
 
 ## The First 10 Minutes
 
@@ -198,18 +217,10 @@ Much of this prior work surfaced after Sello's design had already converged on s
 - Use verifiable log integrated time for revocation decisions, not the receipt timestamp.
 - Deduplicate only on the full spec key, including action type and input/output hashes.
 
-## License
-
-Apache 2.0. See [LICENSE](LICENSE).
-
 ## Feedback
 
 Issues and pull requests are welcome. This is an early draft; adversarial review is the point.
 
-## Development
-
-The current dependency-free test command is:
+## License
 
-```bash
-node --run test
-```
+Apache 2.0. See [LICENSE](LICENSE).

package/dist/cli/sello.js

@@ -44,6 +44,25 @@ import { createSelloService } from "../sdk/service.js";
                  
                       
                        
+  
+
+                         
+             
+                           
+                              
+                       
+                         
+                   
+                   
+                            
+                                
+      
+             
+                 
+                    
+                    
+                            
+      
   
 
 const textEncoder = new TextEncoder();
@@ -285,16 +304,17 @@ async function handleDevRequest(input
   const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
 
   if (request.method === "GET" && (url.pathname === "/" || url.pathname === "/actions")) {
-    const result = verifyReceipts({
-      authorizationTokenBytes: textEncoder.encode(state.agentToken),
-      trustedLogs: [log],
-      registry,
-      ownerPrivateKey: normalizeHpkePrivateKey(state.ownerKey),
-    });
+    const result = verifyDevActions({ log, state, registry });
     sendHtml(response, renderActionsHtml(result));
     return;
   }
 
+  if (request.method === "GET" && url.pathname === "/api/actions") {
+    const result = verifyDevActions({ log, state, registry });
+    sendJson(response, 200, actionsViewModel(result));
+    return;
+  }
+
   if (request.method === "POST" && url.pathname === "/api/entries") {
     const body = await readJson(request);
     if (!isRecord(body) || typeof body.envelope !== "string") {
@@ -326,6 +346,19 @@ async function handleDevRequest(input
   sendJson(response, 404, { error: "not found" });
 }
 
+function verifyDevActions(input   
+                           
+                  
+                                             
+ )                                    {
+  return verifyReceipts({
+    authorizationTokenBytes: textEncoder.encode(input.state.agentToken),
+    trustedLogs: [input.log],
+    registry: input.registry,
+    ownerPrivateKey: normalizeHpkePrivateKey(input.state.ownerKey),
+  });
+}
+
 async function loadViewerRegistry(devState                      ) {
   if (process.env.SELLO_REGISTRY_PATH) {
     return parseRegistry(readFileBytes(process.env.SELLO_REGISTRY_PATH));
@@ -461,16 +494,38 @@ function printActions(result                                   )       {
   }
 }
 
+function actionsViewModel(result                                   )                   {
+  return {
+    receipts: result.receipts.map((record) => ({
+      integratedTime: record.integratedTime,
+      serviceIdentifier: record.serviceIdentifier,
+      actionType: record.receipt["action-type"],
+      resultStatus: record.receipt["result-status"],
+      status: record.status,
+      logUrl: record.logUrl,
+      logCompleteness: record.logCompleteness,
+      sameSecondActivity: record.sameSecondActivity,
+    })),
+    rejected: result.rejected.map((record) => ({
+      code: record.code,
+      message: record.message,
+      ...(record.logUrl === undefined ? {} : { logUrl: record.logUrl }),
+      ...(record.integratedTime === undefined ? {} : { integratedTime: record.integratedTime }),
+    })),
+  };
+}
+
 function renderActionsHtml(result                                   )         {
-  const rows = result.receipts.map((record) => `
+  const view = actionsViewModel(result);
+  const rows = view.receipts.map((record) => `
     <tr>
       <td>${escapeHtml(record.integratedTime)}</td>
       <td>${escapeHtml(record.serviceIdentifier)}</td>
-      <td>${escapeHtml(record.receipt["action-type"])}</td>
-      <td>${escapeHtml(record.receipt["result-status"])}</td>
+      <td>${escapeHtml(record.actionType)}</td>
+      <td>${escapeHtml(record.resultStatus)}</td>
       <td>${escapeHtml(record.status)}</td>
     </tr>`).join("");
-  const rejected = result.rejected.map((record) => `
+  const rejected = view.rejected.map((record) => `
     <li><strong>${escapeHtml(record.code)}</strong>: ${escapeHtml(record.message)}</li>`).join("");
 
   return `<!doctype html>

package/docs/sdk-quickstart.md

@@ -22,17 +22,17 @@ From a new project, the shortest loop is:
 
 ```bash
 # Terminal 1
-npx sello dev
+npx --yes sello dev
 
 # Terminal 2
-npx sello emit-demo
-npx sello actions
+npx --yes sello emit-demo
+npx --yes sello actions
 ```
 
 To write the tiny emitter file into your project:
 
 ```bash
-npx sello init-demo
+npx --yes sello init-demo
 ```
 
 Inside this repo, start the local log and action viewer:
@@ -63,6 +63,8 @@ http://localhost:8787/actions
 
 Both examples read `.sello/dev.json`, wrap a fake calendar handler, submit one encrypted receipt, and let the owner verify it locally.
 
+For the smallest production-shaped MCP boundary, see [`examples/mcp-minimal-server.ts`](../examples/mcp-minimal-server.ts). It wraps one `tools/call` handler with `sello.service()` and leaves unknown tools unreceipted.
+
 For your own tool server, copy the printed service env:
 
 ```bash
@@ -80,6 +82,14 @@ Call your wrapped tool with the printed dev token. Then view actions:
 npx sello actions
 ```
 
+In local dev, `sello dev` prints and saves the token:
+
+```bash
+SELLO_ACTION_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
+```
+
+`npx sello actions` reads that token from `.sello/dev.json`. Pass `--token` only when you want to inspect receipts for a specific agent authorization token.
+
 ## Self-Hosted Production
 
 Use your own Sello-compatible log server:

package/examples/mcp-minimal-server.ts

@@ -0,0 +1,95 @@
+import {
+  canonicalJsonBytes,
+  sello,
+  type SelloReceipts,
+} from "../src/index.ts";
+
+export type MinimalMcpRequest = {
+  headers: {
+    authorization?: string;
+    Authorization?: string;
+  };
+  body: {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    method: "tools/call";
+    params: {
+      name: string;
+      arguments: Record<string, unknown>;
+    };
+  };
+};
+
+export type MinimalMcpResponse = {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: {
+    content: { type: "text"; text: string }[];
+  };
+  error?: {
+    code: number;
+    message: string;
+  };
+};
+
+export function createCalendarMcpServer(
+  receipts: SelloReceipts = sello.service(),
+) {
+  const createEvent = receipts.tool<MinimalMcpRequest, MinimalMcpResponse>(
+    "mcp.tools/call.calendar.create_event",
+    async (request) => {
+      const args = request.body.params.arguments;
+      const title = readString(args.title, "title");
+
+      return {
+        jsonrpc: "2.0",
+        id: request.body.id,
+        result: {
+          content: [
+            {
+              type: "text",
+              text: `created ${title}`,
+            },
+          ],
+        },
+      };
+    },
+    {
+      canonicalizeInput: (request) => canonicalJsonBytes({
+        method: request.body.method,
+        params: request.body.params,
+      }),
+      canonicalizeOutput: (response) => canonicalJsonBytes(response),
+    },
+  );
+
+  return {
+    async handle(request: MinimalMcpRequest): Promise<MinimalMcpResponse> {
+      if (
+        request.body.method !== "tools/call" ||
+        request.body.params.name !== "calendar.create_event"
+      ) {
+        return {
+          jsonrpc: "2.0",
+          id: request.body.id,
+          error: {
+            code: -32601,
+            message: "tool not found",
+          },
+        };
+      }
+
+      return await createEvent(request);
+    },
+
+    flush: () => receipts.flush(),
+  };
+}
+
+function readString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+
+  return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -31,6 +31,7 @@
     "bench": "node --experimental-strip-types src/cli/bench.ts",
     "demo": "node --experimental-strip-types src/cli/demo.ts",
     "dev": "node --experimental-strip-types src/cli/sello.ts dev",
+    "example:mcp:minimal": "node --test --experimental-strip-types test/examples/mcp-minimal-server.test.ts",
     "example:mcp": "node --experimental-strip-types examples/mcp-tool-server.ts",
     "example:tool": "node --experimental-strip-types examples/quickstart-tool.ts",
     "build": "node --disable-warning=ExperimentalWarning scripts/build-dist.mjs",

package/src/cli/sello.ts

@@ -47,6 +47,25 @@ type DevState = {
   registryJson: string;
 };
 
+type ActionsViewModel = {
+  receipts: {
+    integratedTime: string;
+    serviceIdentifier: string;
+    actionType: string;
+    resultStatus: string;
+    status: string;
+    logUrl: string;
+    logCompleteness: string;
+    sameSecondActivity: boolean;
+  }[];
+  rejected: {
+    code: string;
+    message: string;
+    logUrl?: string;
+    integratedTime?: string;
+  }[];
+};
+
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 const command = process.argv[2] ?? "help";
@@ -286,16 +305,17 @@ async function handleDevRequest(input: {
   const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
 
   if (request.method === "GET" && (url.pathname === "/" || url.pathname === "/actions")) {
-    const result = verifyReceipts({
-      authorizationTokenBytes: textEncoder.encode(state.agentToken),
-      trustedLogs: [log],
-      registry,
-      ownerPrivateKey: normalizeHpkePrivateKey(state.ownerKey),
-    });
+    const result = verifyDevActions({ log, state, registry });
     sendHtml(response, renderActionsHtml(result));
     return;
   }
 
+  if (request.method === "GET" && url.pathname === "/api/actions") {
+    const result = verifyDevActions({ log, state, registry });
+    sendJson(response, 200, actionsViewModel(result));
+    return;
+  }
+
   if (request.method === "POST" && url.pathname === "/api/entries") {
     const body = await readJson(request);
     if (!isRecord(body) || typeof body.envelope !== "string") {
@@ -327,6 +347,19 @@ async function handleDevRequest(input: {
   sendJson(response, 404, { error: "not found" });
 }
 
+function verifyDevActions(input: {
+  log: MockTransparencyLog;
+  state: DevState;
+  registry: ReturnType<typeof parseRegistry>;
+}): ReturnType<typeof verifyReceipts> {
+  return verifyReceipts({
+    authorizationTokenBytes: textEncoder.encode(input.state.agentToken),
+    trustedLogs: [input.log],
+    registry: input.registry,
+    ownerPrivateKey: normalizeHpkePrivateKey(input.state.ownerKey),
+  });
+}
+
 async function loadViewerRegistry(devState: DevState | undefined) {
   if (process.env.SELLO_REGISTRY_PATH) {
     return parseRegistry(readFileBytes(process.env.SELLO_REGISTRY_PATH));
@@ -462,16 +495,38 @@ function printActions(result: ReturnType<typeof verifyReceipts>): void {
   }
 }
 
+function actionsViewModel(result: ReturnType<typeof verifyReceipts>): ActionsViewModel {
+  return {
+    receipts: result.receipts.map((record) => ({
+      integratedTime: record.integratedTime,
+      serviceIdentifier: record.serviceIdentifier,
+      actionType: record.receipt["action-type"],
+      resultStatus: record.receipt["result-status"],
+      status: record.status,
+      logUrl: record.logUrl,
+      logCompleteness: record.logCompleteness,
+      sameSecondActivity: record.sameSecondActivity,
+    })),
+    rejected: result.rejected.map((record) => ({
+      code: record.code,
+      message: record.message,
+      ...(record.logUrl === undefined ? {} : { logUrl: record.logUrl }),
+      ...(record.integratedTime === undefined ? {} : { integratedTime: record.integratedTime }),
+    })),
+  };
+}
+
 function renderActionsHtml(result: ReturnType<typeof verifyReceipts>): string {
-  const rows = result.receipts.map((record) => `
+  const view = actionsViewModel(result);
+  const rows = view.receipts.map((record) => `
     <tr>
       <td>${escapeHtml(record.integratedTime)}</td>
       <td>${escapeHtml(record.serviceIdentifier)}</td>
-      <td>${escapeHtml(record.receipt["action-type"])}</td>
-      <td>${escapeHtml(record.receipt["result-status"])}</td>
+      <td>${escapeHtml(record.actionType)}</td>
+      <td>${escapeHtml(record.resultStatus)}</td>
       <td>${escapeHtml(record.status)}</td>
     </tr>`).join("");
-  const rejected = result.rejected.map((record) => `
+  const rejected = view.rejected.map((record) => `
     <li><strong>${escapeHtml(record.code)}</strong>: ${escapeHtml(record.message)}</li>`).join("");
 
   return `<!doctype html>