sello 0.1.1 → 0.1.3

package/dist/service/create-receipt.js

@@ -0,0 +1,174 @@
+import { encodeProtectedHeader } from "../cose/protected-header.js";
+import { signReceiptEnvelope } from "../cose/sign1.js";
+import { deriveTokenIdentifiers, sha256 } from "../crypto/identifiers.js";
+import { sealReceiptBody } from "../hpke/receipt.js";
+import {
+                       
+  assertCanonicalLogUrl,
+  logUrlsEqual,
+} from "../log/canonical-url.js";
+import {
+  ZERO_SHA256_DIGEST,
+  encodeReceiptBody,
+                   
+                    
+} from "../receipt/body.js";
+import { verifySelloJwsToken } from "../token/jws-profile.js";
+
+                                  
+                                      
+                                 
+                               
+                         
+                                
+                            
+                            
+                     
+                               
+                                 
+                             
+                    
+  
+
+                                                                   
+                          
+  
+
+                            
+                           
+                                   
+                       
+  
+
+                                             
+                                 
+  
+
+                                             
+                     
+                                                                
+     
+                                          
+                                   
+                                        
+  
+
+export function buildReceipt(input                   )               {
+  assertBytes(input.authorizationTokenBytes, "authorizationTokenBytes");
+  assertByteLength(input.ownerHpkePublicKey, 32, "ownerHpkePublicKey");
+  assertBytes(input.serviceKid, "serviceKid");
+  assertBytes(input.servicePrivateKey, "servicePrivateKey");
+  assertBytes(input.actionInputBytes, "actionInputBytes");
+
+  if (typeof input.serviceIdentifier !== "string" || input.serviceIdentifier.length === 0) {
+    throw new TypeError("serviceIdentifier must be a non-empty string");
+  }
+
+  if (typeof input.actionType !== "string" || input.actionType.length === 0) {
+    throw new TypeError("actionType must be a non-empty string");
+  }
+
+  const selectedLogUrl = selectOwnerTrustedLog(input.selloLogs, input.logUrl);
+  const identifiers = deriveTokenIdentifiers(input.authorizationTokenBytes);
+  const receiptBody              = {
+    "agent-identifier": identifiers.agent_identifier,
+    "action-type": input.actionType,
+    "action-input-hash": sha256(input.actionInputBytes),
+    "action-output-hash":
+      input.resultStatus === "denied"
+        ? ZERO_SHA256_DIGEST
+        : sha256(input.actionOutputBytes ?? new Uint8Array()),
+    "result-status": input.resultStatus,
+    timestamp: input.timestamp,
+  };
+  const protectedHeaderBytes = encodeProtectedHeader({
+    kid: input.serviceKid,
+    sello_token_ref: identifiers.sello_token_ref,
+    sello_log_url: selectedLogUrl,
+  });
+  const payload = sealReceiptBody({
+    plaintext: encodeReceiptBody(receiptBody),
+    ownerPublicKey: input.ownerHpkePublicKey,
+    protectedHeaderBytes,
+    serviceIdentifier: input.serviceIdentifier,
+    selloTokenRef: identifiers.sello_token_ref,
+  });
+  const envelope = signReceiptEnvelope({
+    protectedHeaderBytes,
+    payload,
+    servicePrivateKey: input.servicePrivateKey,
+  });
+
+  return {
+    receiptBody,
+    protectedHeaderBytes,
+    envelope,
+  };
+}
+
+export function createReceipt(input                    )                 {
+  const built = buildReceipt({
+    ...input,
+    logUrl: input.log.logUrl,
+  });
+  const logEntry = input.log.append(built.envelope, input.timestamp);
+
+  return {
+    ...built,
+    logEntry,
+  };
+}
+
+export function createReceiptFromJwsToken(
+  input                           ,
+)                 {
+  const verifiedToken = verifySelloJwsToken({
+    authorizationToken: input.authorizationToken,
+    issuerPublicKey: input.tokenIssuerPublicKey,
+  });
+  const selloLogs = verifiedToken.selloLogs ?? input.fallbackSelloLogs;
+
+  return createReceipt({
+    ...input,
+    authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
+    ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
+    selloLogs: selloLogs ?? [],
+  });
+}
+
+function selectOwnerTrustedLog(
+  selloLogs                   ,
+  candidateLogUrl                 ,
+)                  {
+  if (!Array.isArray(selloLogs) || selloLogs.length === 0) {
+    throw new TypeError("selloLogs must contain at least one owner-trusted log");
+  }
+
+  const canonicalLogs = selloLogs.map((logUrl) => {
+    assertCanonicalLogUrl(logUrl, "selloLogs entry");
+    return logUrl;
+  });
+
+  const match = canonicalLogs.find((logUrl) => logUrlsEqual(logUrl, candidateLogUrl));
+  if (!match) {
+    throw new TypeError("service log must be listed in selloLogs");
+  }
+
+  return match;
+}
+
+function assertByteLength(
+  value         ,
+  length        ,
+  name        ,
+)                              {
+  if (!(value instanceof Uint8Array) || value.byteLength !== length) {
+    throw new TypeError(`${name} must be a ${length}-byte Uint8Array`);
+  }
+}
+
+function assertBytes(value         , name        )                              {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}

package/dist/token/jws-profile.js

@@ -0,0 +1,174 @@
+import { signEd25519, verifyEd25519Signature } from "../crypto/ed25519.js";
+import { assertCanonicalLogUrl } from "../log/canonical-url.js";
+
+                                     
+                                      
+                                 
+                                
+                                           
+                                   
+  
+
+                                        
+                                          
+                              
+  
+
+                                      
+                                   
+                               
+                                            
+  
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const BASE64URL_32_BYTE_LENGTH = 43;
+
+export function verifySelloJwsToken(
+  input                          ,
+)                        {
+  const authorizationTokenBytes = normalizeTokenBytes(input.authorizationToken);
+  const authorizationToken = textDecoder.decode(authorizationTokenBytes);
+  const parts = authorizationToken.split(".");
+
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+    throw new TypeError("authorization token must be compact JWS");
+  }
+
+  const [encodedProtected, encodedPayload, encodedSignature] = parts;
+  const protectedHeader = parseJsonObject(
+    base64urlDecode(encodedProtected, "JWS protected header"),
+    "JWS protected header",
+  );
+
+  if (protectedHeader.alg !== "EdDSA") {
+    throw new TypeError("JWS alg must be EdDSA");
+  }
+
+  if ("crit" in protectedHeader) {
+    throw new TypeError("JWS crit is not supported by the v0.1 token profile");
+  }
+
+  const signingInput = textEncoder.encode(`${encodedProtected}.${encodedPayload}`);
+  const signature = base64urlDecode(encodedSignature, "JWS signature");
+  if (!verifyEd25519Signature(signingInput, signature, input.issuerPublicKey)) {
+    throw new TypeError("JWS signature verification failed");
+  }
+
+  const payload = parseJsonObject(
+    base64urlDecode(encodedPayload, "JWS payload"),
+    "JWS payload",
+  );
+  const ownerHpkePublicKey = readOwnerHpkePublicKey(payload);
+  const selloLogs = readSelloLogs(payload);
+
+  return {
+    authorizationTokenBytes,
+    ownerHpkePublicKey,
+    ...(selloLogs === undefined ? {} : { selloLogs }),
+    protectedHeader,
+    payload,
+  };
+}
+
+export function signSelloJwsToken(input                        )         {
+  const protectedHeader = {
+    alg: "EdDSA",
+    typ: "JWT",
+    ...input.protectedHeader,
+  };
+  const encodedProtected = base64urlEncode(
+    textEncoder.encode(JSON.stringify(protectedHeader)),
+  );
+  const encodedPayload = base64urlEncode(
+    textEncoder.encode(JSON.stringify(input.payload)),
+  );
+  const signingInput = textEncoder.encode(`${encodedProtected}.${encodedPayload}`);
+  const signature = signEd25519(signingInput, input.issuerPrivateKey);
+
+  return `${encodedProtected}.${encodedPayload}.${base64urlEncode(signature)}`;
+}
+
+export function base64urlEncode(bytes            )         {
+  return Buffer.from(bytes).toString("base64url");
+}
+
+function readOwnerHpkePublicKey(payload                         )             {
+  const encoded = payload.owner_hpke_pk;
+
+  if (typeof encoded !== "string") {
+    throw new TypeError("owner_hpke_pk must be a string");
+  }
+
+  if (encoded.length !== BASE64URL_32_BYTE_LENGTH) {
+    throw new TypeError("owner_hpke_pk must encode a raw 32-byte X25519 public key");
+  }
+
+  const publicKey = base64urlDecode(encoded, "owner_hpke_pk");
+  if (publicKey.byteLength !== 32) {
+    throw new TypeError("owner_hpke_pk must encode a raw 32-byte X25519 public key");
+  }
+
+  return publicKey;
+}
+
+function readSelloLogs(payload                         )                                {
+  const value = payload.sello_logs;
+
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new TypeError("sello_logs must be an array");
+  }
+
+  return value.map((entry) => {
+    if (typeof entry !== "string") {
+      throw new TypeError("sello_logs entries must be strings");
+    }
+
+    assertCanonicalLogUrl(entry, "sello_logs entry");
+    return entry;
+  });
+}
+
+function normalizeTokenBytes(token                     )             {
+  if (typeof token === "string") {
+    if (!/^[\x21-\x7e]+$/.test(token)) {
+      throw new TypeError("authorization token must be visible ASCII");
+    }
+
+    return textEncoder.encode(token);
+  }
+
+  if (token instanceof Uint8Array) {
+    return new Uint8Array(token);
+  }
+
+  throw new TypeError("authorizationToken must be a string or Uint8Array");
+}
+
+function parseJsonObject(bytes            , name        )                          {
+  let parsed         ;
+
+  try {
+    parsed = JSON.parse(textDecoder.decode(bytes));
+  } catch {
+    throw new TypeError(`${name} must be UTF-8 JSON`);
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new TypeError(`${name} must be a JSON object`);
+  }
+
+  return parsed                           ;
+}
+
+function base64urlDecode(value        , name        )             {
+  if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) {
+    throw new TypeError(`${name} must be unpadded base64url`);
+  }
+
+  return Uint8Array.from(Buffer.from(value, "base64url"));
+}

package/docs/release-checklist.md

@@ -26,6 +26,7 @@ git clone https://github.com/juanfiguera/sello.git "$tmpdir/sello"
 cd "$tmpdir/sello"
 node -v # must be v22.7.0 or newer
 node --run test
+node --run package:test
 npm pack --dry-run
 node --experimental-strip-types src/cli/sello.ts --help
 node --experimental-strip-types src/cli/sello.ts dev --dry-run

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,22 +1,23 @@
 {
   "name": "sello",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
   "exports": {
-    ".": "./src/index.ts",
+    ".": "./dist/index.js",
     "./fixtures/vectors/sello-v0.1.json": "./fixtures/vectors/sello-v0.1.json",
     "./spec": "./SPEC.md",
     "./package.json": "./package.json"
   },
   "bin": {
-    "sello": "src/cli/sello.ts",
-    "sello-bench": "src/cli/bench.ts",
-    "sello-demo": "src/cli/demo.ts"
+    "sello": "dist/cli/sello.js",
+    "sello-bench": "dist/cli/bench.js",
+    "sello-demo": "dist/cli/demo.js"
   },
   "files": [
+    "dist",
     "examples",
     "src",
     "fixtures/vectors",
@@ -32,7 +33,10 @@
     "dev": "node --experimental-strip-types src/cli/sello.ts dev",
     "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:test": "node scripts/package-smoke.mjs",
     "pack:check": "npm pack --dry-run",
+    "prepack": "node --disable-warning=ExperimentalWarning scripts/build-dist.mjs",
     "test": "node --test --experimental-strip-types"
   },
   "engines": {

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