sello 0.1.2 → 0.1.4

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,13 +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 --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` |
@@ -81,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:
@@ -98,6 +133,8 @@ 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`.
 
+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
 
 If you are implementing Sello, start with one local loop:
@@ -180,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

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 import { createServer,                                           } from "node:http";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { generateEd25519KeyPair } from "../cose/sign1.js";
 import { deriveTokenIdentifiers, sha256, toHex } from "../crypto/identifiers.js";
 import { generateHpkeKeyPair } from "../hpke/receipt.js";
 import { MockTransparencyLog } from "../log/mock-log.js";
+import { canonicalJsonBytes } from "../mcp/middleware.js";
 import { verifyReceipts } from "../owner/verify.js";
 import {
   loadSignedRegistry,
@@ -25,10 +26,12 @@ import {
 } from "../sdk/keys.js";
 import {
   deserializeEntry,
+  http as httpLog,
   queryHttpLogByTokenRef,
   serializeEntry,
   toCanonicalLogUrl,
 } from "../sdk/logs.js";
+import { createSelloService } from "../sdk/service.js";
 
                  
                     
@@ -56,6 +59,12 @@ try {
     case "dev":
       await devCommand(process.argv.slice(3));
       break;
+    case "emit-demo":
+      await emitDemoCommand(process.argv.slice(3));
+      break;
+    case "init-demo":
+      initDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -156,6 +165,75 @@ async function devCommand(args          )                {
   });
 }
 
+async function emitDemoCommand(args          )                {
+  const state = loadDevStateOrThrow(
+    "missing local Sello dev state. Run `sello dev` first, then run `sello emit-demo` in another terminal from the same directory.",
+  );
+  const title = readFlag(args, "--title") ?? "Test Sello receipt";
+  const receipts = createSelloService({
+    service: state.serviceId,
+    serviceKey: state.serviceKey,
+    tokenIssuer: state.tokenIssuerPublicKey,
+    log: httpLog(state.logUrl, { endpoint: state.logEndpoint }),
+    submit: { mode: "await" },
+  });
+  const createEvent = receipts.tool                                     (
+    "calendar.create_event",
+    async (request) => ({
+      id: `evt_${slug(request.title)}`,
+      calendarId: request.calendarId,
+      title: request.title,
+      status: "created",
+      createdAt: new Date().toISOString(),
+    }),
+    {
+      canonicalizeInput: (request) => canonicalJsonBytes({
+        calendarId: request.calendarId,
+        title: request.title,
+        start: request.start,
+        attendees: request.attendees,
+      }),
+    },
+  );
+  const response = await createEvent({
+    authorizationToken: state.agentToken,
+    calendarId: "demo-calendar",
+    title,
+    start: "2026-06-05T17:00:00Z",
+    attendees: ["ada@example.com", "grace@example.com"],
+  });
+
+  await receipts.flush();
+
+  console.log("Emitted demo Sello receipt.");
+  console.log(JSON.stringify(response, null, 2));
+  console.log("");
+  console.log("View verified actions with:");
+  console.log("  sello actions");
+  console.log("");
+  console.log("Or open:");
+  console.log(`  ${actionViewerUrl(state)}`);
+}
+
+function initDemoCommand(args          )       {
+  const output = readFlag(args, "--output") ?? "emit-receipt.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, demoEmitterSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Run:");
+  console.log("  npm install sello");
+  console.log("  npx sello dev");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+}
+
 function keysCommand(args          )       {
   const subcommand = args[0] ?? "service";
   if (subcommand !== "service") {
@@ -338,6 +416,14 @@ function loadDevStateIfPresent()                       {
   }
 }
 
+function loadDevStateOrThrow(message        )           {
+  const state = loadDevStateIfPresent();
+  if (!state) {
+    throw new TypeError(message);
+  }
+  return state;
+}
+
 function devStatePath()         {
   return join(process.cwd(), ".sello", "dev.json");
 }
@@ -477,6 +563,8 @@ function isRecord(value         )                                   {
 function printHelp()       {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]
+  sello emit-demo [--title title]
+  sello init-demo [--output emit-receipt.mjs] [--force]
   sello actions [--token agent-token]
   sello keys service
   sello inspect-env
@@ -513,3 +601,79 @@ function enforceNodeVersion()       {
     );
   }
 }
+
+                         
+                             
+                     
+                
+                
+                      
+  
+
+                          
+             
+                     
+                
+                    
+                    
+  
+
+function actionViewerUrl(state          )         {
+  const endpoint = new URL(state.logEndpoint);
+  return `${endpoint.origin}/actions`;
+}
+
+function slug(value        )         {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 40);
+}
+
+function demoEmitterSource()         {
+  return `import { readFileSync } from "node:fs";
+import { canonicalJsonBytes, 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.tool(
+  "calendar.create_event",
+  async (request) => ({
+    id: "evt_test_sello_receipt",
+    calendarId: request.calendarId,
+    title: request.title,
+    status: "created",
+    createdAt: new Date().toISOString(),
+  }),
+  {
+    canonicalizeInput: (request) =>
+      canonicalJsonBytes({
+        calendarId: request.calendarId,
+        title: request.title,
+        start: request.start,
+        attendees: request.attendees,
+      }),
+  },
+);
+
+const result = await createEvent({
+  authorizationToken: state.agentToken,
+  calendarId: "demo-calendar",
+  title: "Test Sello receipt",
+  start: "2026-06-05T17:00:00Z",
+  attendees: ["ada@example.com", "grace@example.com"],
+});
+
+await receipts.flush();
+console.log(result);
+`;
+}

package/docs/sdk-quickstart.md

@@ -18,6 +18,23 @@ The service process emits receipts. It does not need the owner private key.
 
 ## Local Development
 
+From a new project, the shortest loop is:
+
+```bash
+# Terminal 1
+npx --yes sello dev
+
+# Terminal 2
+npx --yes sello emit-demo
+npx --yes sello actions
+```
+
+To write the tiny emitter file into your project:
+
+```bash
+npx --yes sello init-demo
+```
+
 Inside this repo, start the local log and action viewer:
 
 ```bash
@@ -46,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
@@ -63,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.2",
+  "version": "0.1.4",
   "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

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S node --experimental-strip-types
 
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { generateEd25519KeyPair } from "../cose/sign1.ts";
@@ -9,6 +9,7 @@ import { deriveTokenIdentifiers, sha256, toHex } from "../crypto/identifiers.ts"
 import { generateHpkeKeyPair } from "../hpke/receipt.ts";
 import { type CanonicalLogUrl } from "../log/canonical-url.ts";
 import { MockTransparencyLog } from "../log/mock-log.ts";
+import { canonicalJsonBytes } from "../mcp/middleware.ts";
 import { verifyReceipts } from "../owner/verify.ts";
 import {
   loadSignedRegistry,
@@ -26,10 +27,12 @@ import {
 } from "../sdk/keys.ts";
 import {
   deserializeEntry,
+  http as httpLog,
   queryHttpLogByTokenRef,
   serializeEntry,
   toCanonicalLogUrl,
 } from "../sdk/logs.ts";
+import { createSelloService } from "../sdk/service.ts";
 
 type DevState = {
   serviceId: string;
@@ -57,6 +60,12 @@ try {
     case "dev":
       await devCommand(process.argv.slice(3));
       break;
+    case "emit-demo":
+      await emitDemoCommand(process.argv.slice(3));
+      break;
+    case "init-demo":
+      initDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -157,6 +166,75 @@ async function devCommand(args: string[]): Promise<void> {
   });
 }
 
+async function emitDemoCommand(args: string[]): Promise<void> {
+  const state = loadDevStateOrThrow(
+    "missing local Sello dev state. Run `sello dev` first, then run `sello emit-demo` in another terminal from the same directory.",
+  );
+  const title = readFlag(args, "--title") ?? "Test Sello receipt";
+  const receipts = createSelloService({
+    service: state.serviceId,
+    serviceKey: state.serviceKey,
+    tokenIssuer: state.tokenIssuerPublicKey,
+    log: httpLog(state.logUrl, { endpoint: state.logEndpoint }),
+    submit: { mode: "await" },
+  });
+  const createEvent = receipts.tool<DemoEventRequest, DemoEventResponse>(
+    "calendar.create_event",
+    async (request) => ({
+      id: `evt_${slug(request.title)}`,
+      calendarId: request.calendarId,
+      title: request.title,
+      status: "created",
+      createdAt: new Date().toISOString(),
+    }),
+    {
+      canonicalizeInput: (request) => canonicalJsonBytes({
+        calendarId: request.calendarId,
+        title: request.title,
+        start: request.start,
+        attendees: request.attendees,
+      }),
+    },
+  );
+  const response = await createEvent({
+    authorizationToken: state.agentToken,
+    calendarId: "demo-calendar",
+    title,
+    start: "2026-06-05T17:00:00Z",
+    attendees: ["ada@example.com", "grace@example.com"],
+  });
+
+  await receipts.flush();
+
+  console.log("Emitted demo Sello receipt.");
+  console.log(JSON.stringify(response, null, 2));
+  console.log("");
+  console.log("View verified actions with:");
+  console.log("  sello actions");
+  console.log("");
+  console.log("Or open:");
+  console.log(`  ${actionViewerUrl(state)}`);
+}
+
+function initDemoCommand(args: string[]): void {
+  const output = readFlag(args, "--output") ?? "emit-receipt.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, demoEmitterSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Run:");
+  console.log("  npm install sello");
+  console.log("  npx sello dev");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+}
+
 function keysCommand(args: string[]): void {
   const subcommand = args[0] ?? "service";
   if (subcommand !== "service") {
@@ -339,6 +417,14 @@ function loadDevStateIfPresent(): DevState | undefined {
   }
 }
 
+function loadDevStateOrThrow(message: string): DevState {
+  const state = loadDevStateIfPresent();
+  if (!state) {
+    throw new TypeError(message);
+  }
+  return state;
+}
+
 function devStatePath(): string {
   return join(process.cwd(), ".sello", "dev.json");
 }
@@ -478,6 +564,8 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function printHelp(): void {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]
+  sello emit-demo [--title title]
+  sello init-demo [--output emit-receipt.mjs] [--force]
   sello actions [--token agent-token]
   sello keys service
   sello inspect-env
@@ -514,3 +602,79 @@ function enforceNodeVersion(): void {
     );
   }
 }
+
+type DemoEventRequest = {
+  authorizationToken: string;
+  calendarId: string;
+  title: string;
+  start: string;
+  attendees: string[];
+};
+
+type DemoEventResponse = {
+  id: string;
+  calendarId: string;
+  title: string;
+  status: "created";
+  createdAt: string;
+};
+
+function actionViewerUrl(state: DevState): string {
+  const endpoint = new URL(state.logEndpoint);
+  return `${endpoint.origin}/actions`;
+}
+
+function slug(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 40);
+}
+
+function demoEmitterSource(): string {
+  return `import { readFileSync } from "node:fs";
+import { canonicalJsonBytes, 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.tool(
+  "calendar.create_event",
+  async (request) => ({
+    id: "evt_test_sello_receipt",
+    calendarId: request.calendarId,
+    title: request.title,
+    status: "created",
+    createdAt: new Date().toISOString(),
+  }),
+  {
+    canonicalizeInput: (request) =>
+      canonicalJsonBytes({
+        calendarId: request.calendarId,
+        title: request.title,
+        start: request.start,
+        attendees: request.attendees,
+      }),
+  },
+);
+
+const result = await createEvent({
+  authorizationToken: state.agentToken,
+  calendarId: "demo-calendar",
+  title: "Test Sello receipt",
+  start: "2026-06-05T17:00:00Z",
+  attendees: ["ada@example.com", "grace@example.com"],
+});
+
+await receipts.flush();
+console.log(result);
+`;
+}