sello 0.1.8 → 0.1.10

package/README.md

@@ -46,8 +46,15 @@ To scaffold a small HTTP route that emits receipts:
 
 ```bash
 npx --yes sello init-http-demo
+npx --yes sello call-http-demo
 ```
 
+## What Just Happened?
+
+`sello dev` created a local owner key, service key, token, registry, and transparency log. The demo tool or route verified the token before running the handler. After the handler ran, the service signed an encrypted receipt for the action it observed. The local log stored the encrypted receipt, not plaintext action details. `sello actions` fetched the receipt, verified the log entry and service signature, decrypted it with the owner key, and printed the owner's view.
+
+Local dev state lives under `.sello/`. The dev log is stored as encrypted receipt entries in `.sello/dev-log.jsonl`, so receipts survive restarting `sello dev` while staying out of git.
+
 ## 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.
@@ -85,7 +92,7 @@ The implementation includes a local end-to-end demo, compact JWS token verificat
 |------|------|
 | 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` |
-| Wrap one HTTP route | `npx --yes sello init-http-demo` |
+| Wrap one HTTP route | `npx --yes sello init-http-demo`, then `npx --yes sello call-http-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) |
@@ -142,7 +149,7 @@ For an MCP-shaped `tools/call` boundary, run `node --run example:mcp` instead of
 
 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.
 
-For an installed-project bridge from demo to app, run `npx sello init-http-demo`. It writes a small dependency-free HTTP route that imports `sello`, reads the local dev config, verifies a bearer token, runs a handler, and emits a receipt.
+For an installed-project bridge from demo to app, run `npx sello init-http-demo`. It writes a small dependency-free HTTP route that imports `sello`, reads the local dev config, verifies a bearer token, runs a handler, and emits a receipt. With the local log and route running, `npx sello call-http-demo` sends the demo request for you.
 
 ## The First 10 Minutes
 

package/dist/cli/sello.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 
 import { createServer,                                           } from "node:http";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 
 import { generateEd25519KeyPair } from "../cose/sign1.js";
@@ -81,6 +87,9 @@ try {
     case "emit-demo":
       await emitDemoCommand(process.argv.slice(3));
       break;
+    case "call-http-demo":
+      await callHttpDemoCommand(process.argv.slice(3));
+      break;
     case "init-demo":
       initDemoCommand(process.argv.slice(3));
       break;
@@ -160,7 +169,7 @@ async function devCommand(args          )                {
     "calendar.example.com/mcp/v1";
   const logEndpoint = `http://localhost:${port}/api`;
   const logUrl = toCanonicalLogUrl(`http://localhost:${port}/api`);
-  const state = createDevState({ serviceId, logUrl, logEndpoint });
+  const state = loadOrCreateDevState({ serviceId, logUrl, logEndpoint });
   saveDevState(state);
 
   if (dryRun) {
@@ -171,10 +180,12 @@ async function devCommand(args          )                {
   }
 
   const log = new MockTransparencyLog(logUrl);
+  const logPath = devLogPath();
+  const loadedEntries = loadDevLogEntries(log, logPath);
   const registry = parseRegistry(textEncoder.encode(state.registryJson));
   const server = createServer(async (request, response) => {
     try {
-      await handleDevRequest({ request, response, log, state, registry });
+      await handleDevRequest({ request, response, log, logPath, state, registry });
     } catch (error) {
       sendJson(response, 500, {
         error: error instanceof Error ? error.message : String(error),
@@ -184,6 +195,9 @@ async function devCommand(args          )                {
 
   server.listen(port, () => {
     printDevConfig(port, state);
+    console.log("");
+    console.log(`Local dev log: ${logPath}`);
+    console.log(`Loaded ${devLogEntryCountLabel(loadedEntries)}.`);
   });
 }
 
@@ -237,6 +251,38 @@ async function emitDemoCommand(args          )                {
   console.log(`  ${actionViewerUrl(state)}`);
 }
 
+async function callHttpDemoCommand(args          )                {
+  const state = loadDevStateOrThrow(
+    "missing local Sello dev state. Run `sello dev` first, then run `sello call-http-demo` in another terminal from the same directory.",
+  );
+  const url = readFlag(args, "--url") ?? "http://localhost:8790/calendar/events";
+  const title = readFlag(args, "--title") ?? "Ship Sello";
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${state.agentToken}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ title }),
+  });
+  const responseText = await response.text();
+
+  if (!response.ok) {
+    throw new TypeError(
+      `HTTP route demo failed with HTTP ${response.status}: ${responseText.trim()}`,
+    );
+  }
+
+  console.log("Called Sello HTTP route demo.");
+  console.log(formatHttpDemoResponse(responseText));
+  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");
@@ -278,8 +324,7 @@ function initHttpDemoCommand(args          )       {
   console.log(`  node ${output}`);
   console.log("");
   console.log("Terminal 3: call the route and view the receipt");
-  console.log("  TOKEN=$(node -e 'console.log(JSON.parse(require(\"fs\").readFileSync(\".sello/dev.json\", \"utf8\")).agentToken)')");
-  console.log("  curl -sS -X POST http://localhost:8790/calendar/events -H \"authorization: Bearer $TOKEN\" -H \"content-type: application/json\" -d '{\"title\":\"Ship Sello\"}'");
+  console.log("  npx sello call-http-demo");
   console.log("  npx sello actions");
   console.log("");
   console.log("Then open http://localhost:8787/actions");
@@ -330,9 +375,10 @@ async function handleDevRequest(input
                            
                            
                   
+                  
                                              
  )                {
-  const { request, response, log, state, registry } = input;
+  const { request, response, log, logPath, state, registry } = input;
   const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
 
   if (request.method === "GET" && (url.pathname === "/" || url.pathname === "/actions")) {
@@ -357,6 +403,7 @@ async function handleDevRequest(input
       decodeBase64url(body.envelope, "envelope"),
       typeof body.integratedTime === "string" ? body.integratedTime : undefined,
     );
+    appendDevLogEntry(logPath, entry);
     sendJson(response, 200, serializeEntry(entry));
     return;
   }
@@ -378,6 +425,24 @@ async function handleDevRequest(input
   sendJson(response, 404, { error: "not found" });
 }
 
+function loadOrCreateDevState(input   
+                    
+                          
+                      
+ )           {
+  const existing = loadDevStateIfPresent();
+  if (
+    existing &&
+    existing.serviceId === input.serviceId &&
+    existing.logUrl === input.logUrl &&
+    existing.logEndpoint === input.logEndpoint
+  ) {
+    return existing;
+  }
+
+  return createDevState(input);
+}
+
 function verifyDevActions(input   
                            
                   
@@ -493,6 +558,54 @@ function devStatePath()         {
   return join(process.cwd(), ".sello", "dev.json");
 }
 
+function devLogPath()         {
+  return join(process.cwd(), ".sello", "dev-log.jsonl");
+}
+
+function loadDevLogEntries(log                     , path        )         {
+  if (!existsSync(path)) {
+    return 0;
+  }
+
+  const lines = textDecoder
+    .decode(readFileBytes(path))
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0);
+
+  let loaded = 0;
+  for (const [index, line] of lines.entries()) {
+    let entry;
+    try {
+      entry = deserializeEntry(JSON.parse(line));
+      if (entry.logUrl !== log.logUrl) {
+        continue;
+      }
+      log.append(entry.envelope, entry.integratedTime);
+      loaded += 1;
+    } catch (error) {
+      throw new TypeError(
+        `invalid local dev log entry ${index + 1} in ${path}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  return loaded;
+}
+
+function appendDevLogEntry(
+  path        ,
+  entry                                           ,
+)       {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(serializeEntry(entry))}\n`, { mode: 0o600 });
+}
+
+function devLogEntryCountLabel(count        )         {
+  return count === 1 ? "1 encrypted receipt" : `${count} encrypted receipts`;
+}
+
 function readFileBytes(path        )             {
   return new Uint8Array(readFileSync(path));
 }
@@ -678,6 +791,7 @@ function printHelp()       {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]
   sello emit-demo [--title title]
+  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 actions [--token agent-token]
@@ -738,6 +852,14 @@ function actionViewerUrl(state          )         {
   return `${endpoint.origin}/actions`;
 }
 
+function formatHttpDemoResponse(responseText        )         {
+  try {
+    return JSON.stringify(JSON.parse(responseText), null, 2);
+  } catch {
+    return responseText;
+  }
+}
+
 function slug(value        )         {
   return value
     .toLowerCase()
@@ -857,9 +979,8 @@ const server = createServer(async (request, response) => {
 server.listen(port, () => {
   console.log("Sello HTTP route demo running at http://localhost:" + port + "/calendar/events");
   console.log("");
-  console.log("Call it with:");
-  console.log("  TOKEN=$(node -e 'console.log(JSON.parse(require(\\\"fs\\\").readFileSync(\\\".sello/dev.json\\\", \\\"utf8\\\")).agentToken)')");
-  console.log("  curl -sS -X POST http://localhost:" + port + "/calendar/events -H \\\"authorization: Bearer $TOKEN\\\" -H \\\"content-type: application/json\\\" -d '{\\\"title\\\":\\\"Ship Sello\\\"}'");
+  console.log("Call it from another terminal with:");
+  console.log("  npx sello call-http-demo");
 });
 
 async function readJson(request) {

package/docs/sdk-quickstart.md

@@ -41,7 +41,18 @@ To write a dependency-free HTTP route example into your project:
 npx --yes sello init-http-demo
 ```
 
-The route example imports `sello`, reads the local dev config, verifies a bearer token, runs one `POST /calendar/events` handler, and emits a receipt.
+The route example imports `sello`, reads the local dev config, verifies a bearer token, runs one `POST /calendar/events` handler, and emits a receipt. With `npx sello dev` and the generated route running, call it with:
+
+```bash
+npx --yes sello call-http-demo
+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.
+
+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.
 
 Inside this repo, start the local log and action viewer:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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,13 @@
 #!/usr/bin/env -S node --experimental-strip-types
 
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 
 import { generateEd25519KeyPair } from "../cose/sign1.ts";
@@ -82,6 +88,9 @@ try {
     case "emit-demo":
       await emitDemoCommand(process.argv.slice(3));
       break;
+    case "call-http-demo":
+      await callHttpDemoCommand(process.argv.slice(3));
+      break;
     case "init-demo":
       initDemoCommand(process.argv.slice(3));
       break;
@@ -161,7 +170,7 @@ async function devCommand(args: string[]): Promise<void> {
     "calendar.example.com/mcp/v1";
   const logEndpoint = `http://localhost:${port}/api`;
   const logUrl = toCanonicalLogUrl(`http://localhost:${port}/api`);
-  const state = createDevState({ serviceId, logUrl, logEndpoint });
+  const state = loadOrCreateDevState({ serviceId, logUrl, logEndpoint });
   saveDevState(state);
 
   if (dryRun) {
@@ -172,10 +181,12 @@ async function devCommand(args: string[]): Promise<void> {
   }
 
   const log = new MockTransparencyLog(logUrl);
+  const logPath = devLogPath();
+  const loadedEntries = loadDevLogEntries(log, logPath);
   const registry = parseRegistry(textEncoder.encode(state.registryJson));
   const server = createServer(async (request, response) => {
     try {
-      await handleDevRequest({ request, response, log, state, registry });
+      await handleDevRequest({ request, response, log, logPath, state, registry });
     } catch (error) {
       sendJson(response, 500, {
         error: error instanceof Error ? error.message : String(error),
@@ -185,6 +196,9 @@ async function devCommand(args: string[]): Promise<void> {
 
   server.listen(port, () => {
     printDevConfig(port, state);
+    console.log("");
+    console.log(`Local dev log: ${logPath}`);
+    console.log(`Loaded ${devLogEntryCountLabel(loadedEntries)}.`);
   });
 }
 
@@ -238,6 +252,38 @@ async function emitDemoCommand(args: string[]): Promise<void> {
   console.log(`  ${actionViewerUrl(state)}`);
 }
 
+async function callHttpDemoCommand(args: string[]): Promise<void> {
+  const state = loadDevStateOrThrow(
+    "missing local Sello dev state. Run `sello dev` first, then run `sello call-http-demo` in another terminal from the same directory.",
+  );
+  const url = readFlag(args, "--url") ?? "http://localhost:8790/calendar/events";
+  const title = readFlag(args, "--title") ?? "Ship Sello";
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${state.agentToken}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ title }),
+  });
+  const responseText = await response.text();
+
+  if (!response.ok) {
+    throw new TypeError(
+      `HTTP route demo failed with HTTP ${response.status}: ${responseText.trim()}`,
+    );
+  }
+
+  console.log("Called Sello HTTP route demo.");
+  console.log(formatHttpDemoResponse(responseText));
+  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");
@@ -279,8 +325,7 @@ function initHttpDemoCommand(args: string[]): void {
   console.log(`  node ${output}`);
   console.log("");
   console.log("Terminal 3: call the route and view the receipt");
-  console.log("  TOKEN=$(node -e 'console.log(JSON.parse(require(\"fs\").readFileSync(\".sello/dev.json\", \"utf8\")).agentToken)')");
-  console.log("  curl -sS -X POST http://localhost:8790/calendar/events -H \"authorization: Bearer $TOKEN\" -H \"content-type: application/json\" -d '{\"title\":\"Ship Sello\"}'");
+  console.log("  npx sello call-http-demo");
   console.log("  npx sello actions");
   console.log("");
   console.log("Then open http://localhost:8787/actions");
@@ -330,10 +375,11 @@ async function handleDevRequest(input: {
   request: IncomingMessage;
   response: ServerResponse;
   log: MockTransparencyLog;
+  logPath: string;
   state: DevState;
   registry: ReturnType<typeof parseRegistry>;
 }): Promise<void> {
-  const { request, response, log, state, registry } = input;
+  const { request, response, log, logPath, state, registry } = input;
   const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
 
   if (request.method === "GET" && (url.pathname === "/" || url.pathname === "/actions")) {
@@ -358,6 +404,7 @@ async function handleDevRequest(input: {
       decodeBase64url(body.envelope, "envelope"),
       typeof body.integratedTime === "string" ? body.integratedTime : undefined,
     );
+    appendDevLogEntry(logPath, entry);
     sendJson(response, 200, serializeEntry(entry));
     return;
   }
@@ -379,6 +426,24 @@ async function handleDevRequest(input: {
   sendJson(response, 404, { error: "not found" });
 }
 
+function loadOrCreateDevState(input: {
+  serviceId: string;
+  logUrl: CanonicalLogUrl;
+  logEndpoint: string;
+}): DevState {
+  const existing = loadDevStateIfPresent();
+  if (
+    existing &&
+    existing.serviceId === input.serviceId &&
+    existing.logUrl === input.logUrl &&
+    existing.logEndpoint === input.logEndpoint
+  ) {
+    return existing;
+  }
+
+  return createDevState(input);
+}
+
 function verifyDevActions(input: {
   log: MockTransparencyLog;
   state: DevState;
@@ -494,6 +559,54 @@ function devStatePath(): string {
   return join(process.cwd(), ".sello", "dev.json");
 }
 
+function devLogPath(): string {
+  return join(process.cwd(), ".sello", "dev-log.jsonl");
+}
+
+function loadDevLogEntries(log: MockTransparencyLog, path: string): number {
+  if (!existsSync(path)) {
+    return 0;
+  }
+
+  const lines = textDecoder
+    .decode(readFileBytes(path))
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0);
+
+  let loaded = 0;
+  for (const [index, line] of lines.entries()) {
+    let entry;
+    try {
+      entry = deserializeEntry(JSON.parse(line));
+      if (entry.logUrl !== log.logUrl) {
+        continue;
+      }
+      log.append(entry.envelope, entry.integratedTime);
+      loaded += 1;
+    } catch (error) {
+      throw new TypeError(
+        `invalid local dev log entry ${index + 1} in ${path}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  return loaded;
+}
+
+function appendDevLogEntry(
+  path: string,
+  entry: ReturnType<MockTransparencyLog["append"]>,
+): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(serializeEntry(entry))}\n`, { mode: 0o600 });
+}
+
+function devLogEntryCountLabel(count: number): string {
+  return count === 1 ? "1 encrypted receipt" : `${count} encrypted receipts`;
+}
+
 function readFileBytes(path: string): Uint8Array {
   return new Uint8Array(readFileSync(path));
 }
@@ -679,6 +792,7 @@ function printHelp(): void {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]
   sello emit-demo [--title title]
+  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 actions [--token agent-token]
@@ -739,6 +853,14 @@ function actionViewerUrl(state: DevState): string {
   return `${endpoint.origin}/actions`;
 }
 
+function formatHttpDemoResponse(responseText: string): string {
+  try {
+    return JSON.stringify(JSON.parse(responseText), null, 2);
+  } catch {
+    return responseText;
+  }
+}
+
 function slug(value: string): string {
   return value
     .toLowerCase()
@@ -858,9 +980,8 @@ const server = createServer(async (request, response) => {
 server.listen(port, () => {
   console.log("Sello HTTP route demo running at http://localhost:" + port + "/calendar/events");
   console.log("");
-  console.log("Call it with:");
-  console.log("  TOKEN=$(node -e 'console.log(JSON.parse(require(\\\"fs\\\").readFileSync(\\\".sello/dev.json\\\", \\\"utf8\\\")).agentToken)')");
-  console.log("  curl -sS -X POST http://localhost:" + port + "/calendar/events -H \\\"authorization: Bearer $TOKEN\\\" -H \\\"content-type: application/json\\\" -d '{\\\"title\\\":\\\"Ship Sello\\\"}'");
+  console.log("Call it from another terminal with:");
+  console.log("  npx sello call-http-demo");
 });
 
 async function readJson(request) {