sello 0.1.2 → 0.1.3

package/README.md

@@ -53,6 +53,7 @@ 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` |
 | 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` |
 | Understand the protocol | [SPEC.md](SPEC.md) Quick Start |
@@ -98,6 +99,23 @@ 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
+```
+
 ## The First 10 Minutes
 
 If you are implementing Sello, start with one local loop:

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 sello dev
+
+# Terminal 2
+npx sello emit-demo
+npx sello actions
+```
+
+To write the tiny emitter file into your project:
+
+```bash
+npx sello init-demo
+```
+
 Inside this repo, start the local log and action viewer:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",

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);
+`;
+}