sello 0.1.0 → 0.1.2

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/decisions.md

@@ -2,7 +2,7 @@
 
 ## Initial Scaffold
 
-- Use plain TypeScript modules with Node 24's native type stripping for the first implementation slice.
+- Use plain TypeScript modules with Node 22.7+'s native type stripping for the first implementation slice.
 - Use Node's built-in test runner to avoid dependency installation before the crypto-library spike.
 - Keep `package.json` npm-compatible, but run tests with `node --run test` or the raw `node --test --experimental-strip-types` command while `npm` is unavailable in this workspace.
 - Start with token-derived identifiers because they require no third-party dependencies and exercise the spec's exact-byte handling rule.
@@ -75,5 +75,5 @@
 
 ## Demo Command
 
-- Ship a small `sello-demo` binary that runs through Node 24's native TypeScript type stripping.
+- Ship a small `sello-demo` binary that runs through Node 22.7+'s native TypeScript type stripping.
 - The demo prints success, error, and denied receipts as verified JSON, and `--tamper` appends a deliberately bad entry to show structured rejection output.

package/docs/release-checklist.md

@@ -5,8 +5,8 @@ Use this checklist before publishing a Sello npm release.
 ## Preflight
 
 - Confirm `git status --short` is clean.
-- Confirm `node -v` is `v24.0.0` or newer.
-- If multiple Node versions are installed, confirm `PATH` resolves `node` to Node 24 before running package scripts.
+- Confirm `node -v` is `v22.7.0` or newer.
+- If multiple Node versions are installed, confirm `PATH` resolves `node` to Node 22.7 or newer before running package scripts.
 - Confirm `package.json` has the intended version.
 - Confirm `README.md` and `docs/sdk-quickstart.md` match the current CLI and examples.
 - Confirm the paper link and local PDF are current, if the paper changed.
@@ -24,8 +24,9 @@ Fresh clone smoke test:
 tmpdir=$(mktemp -d)
 git clone https://github.com/juanfiguera/sello.git "$tmpdir/sello"
 cd "$tmpdir/sello"
-node -v # must be v24.0.0 or newer
+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

@@ -2,6 +2,8 @@
 
 Sello's SDK is designed to make the first receipt easy: wrap a tool handler, run it, and inspect verified actions.
 
+Requires Node.js 22.7 or newer.
+
 ```ts
 import { sello } from "sello";
 

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "sello",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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,11 +33,14 @@
     "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": {
-    "node": ">=24.0.0"
+    "node": ">=22.7.0"
   },
   "keywords": [
     "ai-agents",

package/src/cli/sello.ts

@@ -505,10 +505,12 @@ function printDevConfig(port: number, state: DevState): void {
 }
 
 function enforceNodeVersion(): void {
-  const major = Number(process.versions.node.split(".")[0]);
-  if (major < 24) {
+  const [major = 0, minor = 0] = process.versions.node
+    .split(".")
+    .map((part) => Number(part));
+  if (major < 22 || (major === 22 && minor < 7)) {
     throw new TypeError(
-      `Sello requires Node >=24.0.0; current Node is ${process.versions.node}`,
+      `Sello requires Node >=22.7.0; current Node is ${process.versions.node}`,
     );
   }
 }