sello 0.1.6 → 0.1.8

package/README.md

@@ -42,6 +42,12 @@ 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
+```
+
 ## 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 +85,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` |
 | 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 +142,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.
+
 ## The First 10 Minutes
 
 If you are implementing Sello, start with one local loop:

package/dist/cli/sello.js

@@ -84,6 +84,9 @@ try {
     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;
@@ -246,11 +249,40 @@ function initDemoCommand(args          )       {
 
   console.log(`Created ${output}`);
   console.log("");
-  console.log("Run:");
-  console.log("  npm install sello");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log("  npx sello dev");
+  console.log("");
+  console.log("Terminal 2: emit and view a receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  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("  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 actions");
+  console.log("");
+  console.log("Then open http://localhost:8787/actions");
 }
 
 function keysCommand(args          )       {
@@ -647,6 +679,7 @@ function printHelp()       {
   sello dev [--port 8787] [--service service-id] [--dry-run]
   sello emit-demo [--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
@@ -759,3 +792,113 @@ 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 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\\\"}'");
+});
+
+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,14 @@ 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.
+
 Inside this repo, start the local log and action viewer:
 
 ```bash

package/package.json

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

package/src/cli/sello.ts

@@ -85,6 +85,9 @@ try {
     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;
@@ -247,11 +250,40 @@ function initDemoCommand(args: string[]): void {
 
   console.log(`Created ${output}`);
   console.log("");
-  console.log("Run:");
-  console.log("  npm install sello");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log("  npx sello dev");
+  console.log("");
+  console.log("Terminal 2: emit and view a receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  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("  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 actions");
+  console.log("");
+  console.log("Then open http://localhost:8787/actions");
 }
 
 function keysCommand(args: string[]): void {
@@ -648,6 +680,7 @@ function printHelp(): void {
   sello dev [--port 8787] [--service service-id] [--dry-run]
   sello emit-demo [--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
@@ -760,3 +793,113 @@ 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 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\\\"}'");
+});
+
+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);
+}
+`;
+}