sello 0.1.7 → 0.1.9

package/README.md

@@ -42,6 +42,13 @@ To see the tiny wrapped-tool source:
 npx --yes sello init-demo
 ```
 
+To scaffold a small HTTP route that emits receipts:
+
+```bash
+npx --yes sello init-http-demo
+npx --yes sello call-http-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.
@@ -79,6 +86,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`, 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) |
@@ -135,6 +143,8 @@ 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. With the local log and route running, `npx sello call-http-demo` sends the demo request for you.
+
 ## The First 10 Minutes
 
 If you are implementing Sello, start with one local loop:

package/dist/cli/sello.js

@@ -81,9 +81,15 @@ 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;
+    case "init-http-demo":
+      initHttpDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -234,6 +240,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");
@@ -256,6 +294,31 @@ function initDemoCommand(args          )       {
   console.log("Then open http://localhost:8787/actions");
 }
 
+function initHttpDemoCommand(args          )       {
+  const output = readFlag(args, "--output") ?? "sello-http-route.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, httpRouteDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log("  npx sello dev");
+  console.log("");
+  console.log("Terminal 2: start the route");
+  console.log(`  node ${output}`);
+  console.log("");
+  console.log("Terminal 3: call the route and view the receipt");
+  console.log("  npx sello call-http-demo");
+  console.log("  npx sello actions");
+  console.log("");
+  console.log("Then open http://localhost:8787/actions");
+}
+
 function keysCommand(args          )       {
   const subcommand = args[0] ?? "service";
   if (subcommand !== "service") {
@@ -649,7 +712,9 @@ 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]
   sello keys service
   sello inspect-env
@@ -708,6 +773,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()
@@ -762,3 +835,112 @@ await receipts.flush();
 console.log(result);
 `;
 }
+
+function httpRouteDemoSource()         {
+  return `import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { canonicalJsonBytes, sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+const port = Number(process.env.PORT ?? "8790");
+
+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(
+  "http.POST /calendar/events",
+  async (request) => {
+    const title = readString(request.body.title, "title");
+    return {
+      id: "evt_" + slug(title),
+      title,
+      status: "created",
+      createdAt: new Date().toISOString(),
+    };
+  },
+  {
+    authorizationToken: (request) => request.authorizationToken,
+    canonicalizeInput: (request) =>
+      canonicalJsonBytes({
+        method: "POST",
+        path: "/calendar/events",
+        body: request.body,
+      }),
+    canonicalizeOutput: (response) => canonicalJsonBytes(response),
+  },
+);
+
+const server = createServer(async (request, response) => {
+  try {
+    const path = new URL(request.url ?? "/", "http://localhost").pathname;
+    if (request.method !== "POST" || path !== "/calendar/events") {
+      sendJson(response, 404, { error: "not found" });
+      return;
+    }
+
+    const body = await readJson(request);
+    const result = await createEvent({
+      authorizationToken: bearerToken(request.headers.authorization),
+      body,
+    });
+    await receipts.flush();
+    sendJson(response, 200, result);
+  } catch (error) {
+    sendJson(response, 400, {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+});
+
+server.listen(port, () => {
+  console.log("Sello HTTP route demo running at http://localhost:" + port + "/calendar/events");
+  console.log("");
+  console.log("Call it from another terminal with:");
+  console.log("  npx sello call-http-demo");
+});
+
+async function readJson(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  if (chunks.length === 0) {
+    return {};
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function bearerToken(header) {
+  const value = Array.isArray(header) ? header[0] : header;
+  if (typeof value !== "string" || !value.startsWith("Bearer ")) {
+    throw new TypeError("missing Authorization: Bearer <token> header");
+  }
+  return value.slice("Bearer ".length);
+}
+
+function sendJson(response, statusCode, body) {
+  response.writeHead(statusCode, { "content-type": "application/json" });
+  response.end(JSON.stringify(body, null, 2) + "\\n");
+}
+
+function readString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(name + " must be a non-empty string");
+  }
+  return value;
+}
+
+function slug(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 40);
+}
+`;
+}

package/docs/sdk-quickstart.md

@@ -35,6 +35,19 @@ To write the tiny emitter file into your project:
 npx --yes sello init-demo
 ```
 
+To write a dependency-free HTTP route example into your project:
+
+```bash
+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. With `npx sello dev` and the generated route running, call it with:
+
+```bash
+npx --yes sello call-http-demo
+npx --yes sello actions
+```
+
 Inside this repo, start the local log and action viewer:
 
 ```bash

package/package.json

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

package/src/cli/sello.ts

@@ -82,9 +82,15 @@ 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;
+    case "init-http-demo":
+      initHttpDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -235,6 +241,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");
@@ -257,6 +295,31 @@ function initDemoCommand(args: string[]): void {
   console.log("Then open http://localhost:8787/actions");
 }
 
+function initHttpDemoCommand(args: string[]): void {
+  const output = readFlag(args, "--output") ?? "sello-http-route.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, httpRouteDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log("  npx sello dev");
+  console.log("");
+  console.log("Terminal 2: start the route");
+  console.log(`  node ${output}`);
+  console.log("");
+  console.log("Terminal 3: call the route and view the receipt");
+  console.log("  npx sello call-http-demo");
+  console.log("  npx sello actions");
+  console.log("");
+  console.log("Then open http://localhost:8787/actions");
+}
+
 function keysCommand(args: string[]): void {
   const subcommand = args[0] ?? "service";
   if (subcommand !== "service") {
@@ -650,7 +713,9 @@ 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]
   sello keys service
   sello inspect-env
@@ -709,6 +774,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()
@@ -763,3 +836,112 @@ await receipts.flush();
 console.log(result);
 `;
 }
+
+function httpRouteDemoSource(): string {
+  return `import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { canonicalJsonBytes, sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+const port = Number(process.env.PORT ?? "8790");
+
+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(
+  "http.POST /calendar/events",
+  async (request) => {
+    const title = readString(request.body.title, "title");
+    return {
+      id: "evt_" + slug(title),
+      title,
+      status: "created",
+      createdAt: new Date().toISOString(),
+    };
+  },
+  {
+    authorizationToken: (request) => request.authorizationToken,
+    canonicalizeInput: (request) =>
+      canonicalJsonBytes({
+        method: "POST",
+        path: "/calendar/events",
+        body: request.body,
+      }),
+    canonicalizeOutput: (response) => canonicalJsonBytes(response),
+  },
+);
+
+const server = createServer(async (request, response) => {
+  try {
+    const path = new URL(request.url ?? "/", "http://localhost").pathname;
+    if (request.method !== "POST" || path !== "/calendar/events") {
+      sendJson(response, 404, { error: "not found" });
+      return;
+    }
+
+    const body = await readJson(request);
+    const result = await createEvent({
+      authorizationToken: bearerToken(request.headers.authorization),
+      body,
+    });
+    await receipts.flush();
+    sendJson(response, 200, result);
+  } catch (error) {
+    sendJson(response, 400, {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+});
+
+server.listen(port, () => {
+  console.log("Sello HTTP route demo running at http://localhost:" + port + "/calendar/events");
+  console.log("");
+  console.log("Call it from another terminal with:");
+  console.log("  npx sello call-http-demo");
+});
+
+async function readJson(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  if (chunks.length === 0) {
+    return {};
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function bearerToken(header) {
+  const value = Array.isArray(header) ? header[0] : header;
+  if (typeof value !== "string" || !value.startsWith("Bearer ")) {
+    throw new TypeError("missing Authorization: Bearer <token> header");
+  }
+  return value.slice("Bearer ".length);
+}
+
+function sendJson(response, statusCode, body) {
+  response.writeHead(statusCode, { "content-type": "application/json" });
+  response.end(JSON.stringify(body, null, 2) + "\\n");
+}
+
+function readString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(name + " must be a non-empty string");
+  }
+  return value;
+}
+
+function slug(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 40);
+}
+`;
+}