sello 0.1.9 → 0.1.11

package/README.md

@@ -1,6 +1,31 @@
 ![Sello banner](docs/assets/sello-banner.png)
 
-# Sello
+<h1 align="center">Sello</h1>
+
+<p align="center">
+  <a href="https://github.com/juanfiguera/sello/actions/workflows/ci.yml"><img alt="build status" src="https://img.shields.io/github/actions/workflow/status/juanfiguera/sello/ci.yml?branch=main&style=flat-square&label=build&labelColor=0b1011&color=e8f7ef"></a>
+  <a href="https://www.npmjs.com/package/sello"><img alt="npm version" src="https://img.shields.io/npm/v/sello?style=flat-square&label=npm&labelColor=0b1011&color=e8f7ef"></a>
+  <a href="https://pypi.org/project/sello/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/sello?style=flat-square&label=pypi&labelColor=0b1011&color=e8f7ef"></a>
+  <a href="https://www.npmjs.com/package/sello"><img alt="npm downloads" src="https://img.shields.io/npm/dm/sello?style=flat-square&label=downloads&labelColor=0b1011&color=e8f7ef"></a>
+  <a href="LICENSE"><img alt="license Apache-2.0" src="https://img.shields.io/npm/l/sello?style=flat-square&label=license&labelColor=0b1011&color=e8f7ef"></a>
+  <a href="package.json"><img alt="Node.js 22.7 or newer" src="https://img.shields.io/badge/node-%3E%3D22.7-e8f7ef?style=flat-square&labelColor=0b1011"></a>
+  <a href="sdks/python/pyproject.toml"><img alt="Python 3.9 or newer" src="https://img.shields.io/badge/python-%3E%3D3.9-e8f7ef?style=flat-square&labelColor=0b1011"></a>
+  <a href="https://arxiv.org/abs/2606.04193"><img alt="arXiv 2606.04193" src="https://img.shields.io/badge/arXiv-2606.04193-e8f7ef?style=flat-square&labelColor=0b1011"></a>
+</p>
+
+<p align="center">
+  <a href="#try-it">Quickstart</a> &middot;
+  <a href="#add-sello-to-a-tool">Add Sello</a> &middot;
+  <a href="sdks/README.md">SDKs</a> &middot;
+  <a href="#see-logged-actions">Actions</a> &middot;
+  <a href="#how-it-works">How It Works</a> &middot;
+  <a href="#learn-more">Learn More</a> &middot;
+  <a href="SPEC.md">Protocol</a> &middot;
+  <a href="https://arxiv.org/abs/2606.04193">Paper</a> &middot;
+  <a href="SECURITY.md">Security</a> &middot;
+  <a href="CONTRIBUTING.md">Contributing</a> &middot;
+  <a href="#license">License</a>
+</p>
 
 Sello is a protocol for independently-verifiable records of AI agent actions.
 
@@ -36,70 +61,16 @@ Then open:
 http://localhost:8787/actions
 ```
 
-To see the tiny wrapped-tool source:
+`sello dev` creates local keys, a demo token, a service registry, and a local transparency log under `.sello/`. The log stores encrypted receipt entries, not plaintext action details.
 
-```bash
-npx --yes sello init-demo
-```
+## Add Sello to a Tool
 
-To scaffold a small HTTP route that emits receipts:
+TypeScript:
 
 ```bash
-npx --yes sello init-http-demo
-npx --yes sello call-http-demo
+npm install sello
 ```
 
-## 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.
-
-Sello moves receipt-writing to the services the agent calls. The service was present for the action, but it is outside the agent's own logging path. The architectural inversion is simple: the signer is not the agent or its operator, but the receiver that observed the action.
-
-## What Sello Gives You
-
-Sello helps an owner verify that:
-
-- A specific service signed a specific receipt.
-- The receipt was encrypted for the owner.
-- The receipt was included in a trusted transparency log.
-- The receipt body was not modified after signing.
-
-Sello does not prove that the agent called every service it should have called, that every service is honest, or that unauthenticated log indexes returned complete results. Those limits are intentional and documented in the spec.
-
-## Repository Status
-
-This repository currently contains:
-
-- [SPEC.md](SPEC.md): the Sello protocol draft.
-- A TypeScript reference implementation in [`src/`](src/).
-- Implementation-backed v0.1 test vectors in [`fixtures/vectors/sello-v0.1.json`](fixtures/vectors/sello-v0.1.json).
-- Security review notes in [`docs/security-review.md`](docs/security-review.md).
-- SDK security audit notes in [`docs/sdk-security-audit.md`](docs/sdk-security-audit.md).
-
-The implementation includes a local end-to-end demo, compact JWS token verification, COSE_Sign1 receipt envelopes, HPKE encryption, a mock transparency log, a Rekor discovery adapter, owner verification, an MCP middleware prototype, security review notes, and a local benchmark. Live Rekor proof verification and production identity operations are still future work.
-
-📄 **Paper:** [Notarized Agents: Receiver-Attested Confidential Receipts for AI Agent Actions](https://arxiv.org/abs/2606.04193) (arXiv:2606.04193, submitted June 2026). Local PDF: [docs/paper/notarized-agents.pdf](docs/paper/notarized-agents.pdf).
-
-## Start Here
-
-| Goal | Read |
-|------|------|
-| 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) |
-| Understand the protocol | [SPEC.md](SPEC.md) Quick Start |
-| Run the local demo | `node --run demo` |
-| Run the test suite | `node --run test` |
-| Measure local size/performance | `node --run bench -- --json` |
-| Emit receipts from a service | [SPEC.md](SPEC.md) §§3.1, 4.1, 5, 6.2 |
-| Verify receipts as an owner | [SPEC.md](SPEC.md) §§4.2, 5, 6.2, 7.1 |
-| Build the reference implementation | Start with "The First 10 Minutes" below |
-
-## Add Sello in a Few Lines
-
 ```ts
 import { sello } from "sello";
 
@@ -110,96 +81,84 @@ export const createEvent = receipts.tool("calendar.create_event", async (request
 });
 ```
 
-Then inspect verified actions:
+Python:
 
 ```bash
-npx sello actions --token <agent-token>
+pip install sello
 ```
 
-In local dev, `sello dev` prints and saves a demo token:
+```py
+import sello
 
-```bash
-SELLO_ACTION_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
-```
+receipts = sello.service()
 
-You usually do not need to copy it. `npx sello actions` reads the latest dev token from `.sello/dev.json`. Use `--token` when you want to inspect receipts for a specific agent authorization token from your own system.
-
-Sello works with your own log server. `sello.build` is optional convenience, not a protocol requirement.
+@receipts.tool("calendar.create_event")
+def create_event(request):
+    return calendar.events.create(request)
+```
 
-To try the repo's local loop:
+In local dev, `npx sello dev` supplies the config this snippet needs. In production, configure your service with a service id, service signing key, token issuer, and log URL:
 
 ```bash
-# Terminal 1
-node --run dev
-
-# Terminal 2
-node --run example:tool
-node --run actions
+SELLO_SERVICE_ID=calendar.example.com/mcp/v1
+SELLO_SERVICE_KEY=sello_live_local_...
+SELLO_TOKEN_ISSUER_JWKS=https://auth.example.com/.well-known/jwks.json
+SELLO_LOG_URL=https://logs.example.com/api
+SELLO_SUBMIT_MODE=background
 ```
 
-The example wraps a fake calendar tool, emits a service-signed encrypted receipt, and lets the owner verify it from the local action log.
+Sello works with your own log server. Using `sello.build` is an optional convenience, not a protocol requirement.
 
-For an MCP-shaped `tools/call` boundary, run `node --run example:mcp` instead of `node --run example:tool`.
+To scaffold a tiny emitter or HTTP route:
 
-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.
+```bash
+npx --yes sello init-demo
+npx --yes sello init-http-demo
+```
 
-## The First 10 Minutes
+## See Logged Actions
 
-If you are implementing Sello, start with one local loop:
+```bash
+npx sello actions
+```
 
-1. Generate a fixed owner HPKE key pair.
-2. Generate a fixed service Ed25519 signing key.
-3. Create one mock compact JWS token containing `owner_hpke_pk` and `sello_logs`.
-4. Have the service create one receipt for one fake action.
-5. Store the receipt in a mock log under `sello_token_ref`.
-6. Have the owner fetch, verify, and decrypt the receipt.
+In local dev, `sello actions` reads the latest dev token and owner key from `.sello/dev.json`. To inspect actions for a specific agent token, pass it explicitly:
 
-Do not start with Rekor, MCP middleware, distributed identity, or CLI polish. Those become much easier once one local receipt works end to end.
+```bash
+npx sello actions --token <agent-token>
+```
 
-You know the first loop works when the owner can print one verified receipt:
+The token is the same authorization token the agent used when it called services. Sello hashes the exact token bytes into `sello_token_ref`, queries trusted logs, verifies matching receipts, and decrypts them with the owner key.
 
-```json
-{
-  "service": "example.com/tool/v1",
-  "action-type": "tools/call",
-  "result-status": "success",
-  "verified": true
-}
-```
+Public logs store encrypted receipts. Viewing action details requires the owner private key or an explicitly delegated viewer key.
 
-## Service Integration
+## How It Works
 
-A Sello-aware service does this for each agent action:
+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.
 
-1. Verify the agent's authorization token.
-2. Read `owner_hpke_pk` and `sello_logs` from the verified token.
-3. Compute `sello_token_ref = SHA-256(raw compact JWS bytes)`.
-4. Build a CBOR receipt body describing the action.
-5. Encrypt the receipt body to the owner with HPKE.
-6. Sign the COSE_Sign1 envelope with the service key.
-7. Publish the envelope to an owner-trusted transparency log.
+Sello moves receipt-writing to the services the agent calls. The service was present for the action, but it is outside the agent's own logging path.
 
-The service signs what it observed. It does not need the owner's private key, and it does not need to understand the owner's downstream audit workflow.
+1. The agent calls a service with an authorization token.
+2. The service verifies the token, runs the action, and signs an encrypted receipt for what it observed.
+3. A transparency log stores the encrypted receipt.
+4. The owner later fetches, verifies, and decrypts the receipt.
 
-For most services, Sello should fit as middleware around an existing request handler: verify token, run action, emit receipt.
+Sello helps an owner verify that a specific service signed a specific receipt, the receipt was encrypted for the owner, the receipt was included in a trusted transparency log, and the receipt body was not modified after signing.
 
-## Owner Verification
+Sello does not prove that the agent called every service it should have called, that every service is honest, or that unauthenticated log indexes returned complete results. Those limits are intentional and documented in the spec.
 
-An owner verifier does this when reconstructing activity:
+## Learn More
 
-1. Compute `sello_token_ref` from the same raw compact JWS bytes.
-2. Query every trusted log for matching receipts.
-3. Confirm each receipt's `sello_log_url` exactly matches the log that returned the proof.
-4. Verify log inclusion.
-5. Resolve the service signing key from `kid`.
-6. Apply revocation rules using log integrated time.
-7. Verify the COSE signature.
-8. Decrypt the HPKE payload.
-9. Validate and display the receipt body.
+- [SDK Quickstart](docs/sdk-quickstart.md): local dev, HTTP demo, self-hosted config, and hosted config.
+- [SDKs](sdks/README.md): TypeScript and Python package layout.
+- [Python SDK](sdks/python/README.md): Python package install command, scope, and test command.
+- [Protocol Walkthrough](docs/protocol-walkthrough.md): the primitive receipt loop for implementers.
+- [SPEC.md](SPEC.md): the Sello protocol draft.
+- [Notarized Agents paper](https://arxiv.org/abs/2606.04193): design rationale, threat model, and prior art.
+- [sdks/typescript/examples/mcp-minimal-server.ts](sdks/typescript/examples/mcp-minimal-server.ts): a small MCP-shaped integration.
+- [docs/security-review.md](docs/security-review.md) and [docs/sdk-security-audit.md](docs/sdk-security-audit.md): current review notes.
 
-For most owners, Sello should fit as a pull-based audit tool: provide the token and owner key, then retrieve the verified trail from trusted logs.
+The TypeScript SDK is published on [npm](https://www.npmjs.com/package/sello) and lives in [`sdks/typescript/`](sdks/typescript/). The Python SDK is published on [PyPI](https://pypi.org/project/sello/) and lives in [`sdks/python/`](sdks/python/). Live Rekor proof verification and production identity operations are still future work.
 
 ## Core Terms
 
@@ -229,7 +188,7 @@ Much of this prior work surfaced after Sello's design had already converged on s
 
 ## Feedback
 
-Issues and pull requests are welcome. This is an early draft; adversarial review is the point.
+Issues and pull requests are welcome. This is an early draft; adversarial review is the point. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution notes and [SECURITY.md](SECURITY.md) for sensitive reports.
 
 ## License
 

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";
@@ -163,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) {
@@ -174,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),
@@ -187,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)}.`);
   });
 }
 
@@ -364,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")) {
@@ -391,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;
   }
@@ -412,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   
                            
                   
@@ -527,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));
 }

package/docs/paper/notarized-agents.md

@@ -323,7 +323,7 @@ We present first-party microbenchmarks of the cryptographic operations Sello per
 
 ### 7.1 Methodology
 
-The reference implementation [@sello-repo] ships with a benchmark tool (`src/cli/bench.ts`) that exercises the full receipt lifecycle. For each iteration the bench: (1) constructs a verified compact JWS authorization token, (2) creates a Sello receipt at the service side (HPKE seal of the CBOR-encoded receipt body to the owner's X25519 public key, followed by COSE_Sign1 signing with the service's Ed25519 private key), (3) submits the signed envelope to an in-process mock transparency log that returns an inclusion proof, and (4) performs full owner-side verification (proof verification, registry resolution, COSE_Sign1 signature verification, HPKE open, and receipt body validation). The mock log replaces network submission with deterministic in-process bookkeeping; this isolates the cryptographic costs from log-operator-specific network latency. Log submission latency to a hosted public log is discussed separately in §7.3.
+The reference implementation [@sello-repo] ships with a benchmark tool (`sdks/typescript/src/cli/bench.ts`) that exercises the full receipt lifecycle. For each iteration the bench: (1) constructs a verified compact JWS authorization token, (2) creates a Sello receipt at the service side (HPKE seal of the CBOR-encoded receipt body to the owner's X25519 public key, followed by COSE_Sign1 signing with the service's Ed25519 private key), (3) submits the signed envelope to an in-process mock transparency log that returns an inclusion proof, and (4) performs full owner-side verification (proof verification, registry resolution, COSE_Sign1 signature verification, HPKE open, and receipt body validation). The mock log replaces network submission with deterministic in-process bookkeeping; this isolates the cryptographic costs from log-operator-specific network latency. Log submission latency to a hosted public log is discussed separately in §7.3.
 
 The cryptographic primitives are Node.js bindings to the system OpenSSL: X25519 key agreement and Ed25519 signing via `node:crypto`, ChaCha20-Poly1305 AEAD via `createCipheriv`, HKDF-SHA256 via `createHmac`, and SHA-256 via `createHash`. HPKE is implemented per RFC 9180 base mode with the suite specified in §2.1; the implementation is pinned to RFC 9180 Appendix A.2.1 test vectors and validated in the test suite.
 

package/docs/paper/notarized-agents.tex

@@ -994,7 +994,7 @@ on the Sello protocol itself.
 \subsubsection{7.1 Methodology}\label{methodology}}
 
 The reference implementation \citep{sello-repo} ships with a benchmark
-tool (\texttt{src/cli/bench.ts}) that exercises the full receipt
+tool (\texttt{sdks/typescript/src/cli/bench.ts}) that exercises the full receipt
 lifecycle. For each iteration the bench: (1) constructs a verified
 compact JWS authorization token, (2) creates a Sello receipt at the
 service side (HPKE seal of the CBOR-encoded receipt body to the owner's

package/docs/protocol-walkthrough.md

@@ -0,0 +1,74 @@
+# Protocol Walkthrough
+
+This guide is for people implementing Sello itself or studying the receipt flow below the SDK. If you only want to try Sello or add it to a service, start with the README or [`docs/sdk-quickstart.md`](sdk-quickstart.md).
+
+## Goal
+
+Build the smallest complete Sello loop:
+
+1. One mock action happens.
+2. The service creates one encrypted signed receipt.
+3. A mock transparency log stores it under `sello_token_ref`.
+4. The owner fetches, verifies, and decrypts it.
+
+Run the complete loop first:
+
+```bash
+node --run demo
+```
+
+The runnable source is [`sdks/typescript/src/cli/demo.ts`](../sdks/typescript/src/cli/demo.ts).
+
+## Local Pieces
+
+The primitive loop needs these pieces:
+
+| Piece | Local helper | Why it exists |
+|-------|--------------|---------------|
+| Owner key | `generateHpkeKeyPair()` | The public key goes in the token. The private key decrypts receipts later. |
+| Service key | `generateEd25519KeyPair()` | The service signs receipts for actions it observed. |
+| Token issuer key | `generateEd25519KeyPair()` | The issuer signs the mock agent token. |
+| Transparency log | `new MockTransparencyLog(...)` | The log stores encrypted signed receipts by `sello_token_ref`. |
+| Service registry | `loadSignedRegistry(...)` | The owner uses it to resolve service public keys and revocation status. |
+
+Start with the owner key:
+
+```ts
+import { base64urlEncode, generateHpkeKeyPair } from "sello";
+
+const owner = generateHpkeKeyPair();
+const ownerHpkePk = base64urlEncode(owner.publicKey);
+```
+
+Put `ownerHpkePk` in the token's `owner_hpke_pk` claim. Keep `owner.privateKey` for the owner verifier.
+
+Then create the other local pieces:
+
+```ts
+import { generateEd25519KeyPair, MockTransparencyLog } from "sello";
+
+const service = generateEd25519KeyPair();
+const tokenIssuer = generateEd25519KeyPair();
+const trustRoot = generateEd25519KeyPair();
+const log = new MockTransparencyLog("https://rekor.example.com/api");
+```
+
+## Flow
+
+1. Sign a compact JWS token with `signSelloJwsToken(...)`.
+2. Include `owner_hpke_pk` and `sello_logs` in the signed token.
+3. Create a receipt with `createReceiptFromJwsToken(...)`.
+4. Verify with `verifyReceipts(...)` using the same raw token, owner private key, mock log, and service registry.
+
+You know the loop works when the owner can print one verified receipt:
+
+```json
+{
+  "service": "example.com/tool/v1",
+  "action-type": "tools/call",
+  "result-status": "success",
+  "verified": true
+}
+```
+
+Do not start with Rekor, MCP middleware, distributed identity, or CLI polish. Those become much easier once one local receipt works end to end.

package/docs/release-checklist.md

@@ -1,6 +1,6 @@
 # Release Checklist
 
-Use this checklist before publishing a Sello npm release.
+Use this checklist before publishing a Sello release.
 
 ## Preflight
 
@@ -8,6 +8,7 @@ Use this checklist before publishing a Sello npm release.
 - 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 `sdks/python/pyproject.toml` has the intended version when publishing Python.
 - 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.
 
@@ -28,8 +29,8 @@ 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
+node --experimental-strip-types sdks/typescript/src/cli/sello.ts --help
+node --experimental-strip-types sdks/typescript/src/cli/sello.ts dev --dry-run
 ```
 
 ## npm Verification
@@ -42,6 +43,18 @@ npm publish --dry-run
 
 If the package name is already published, confirm the local version is greater than the registry version before publishing.
 
+## PyPI Verification
+
+```bash
+python -m pip install --upgrade build twine
+cd sdks/python
+rm -rf dist
+python -m build
+python -m twine check dist/*
+```
+
+The PyPI project uses trusted publishing from `.github/workflows/release.yml`.
+
 ## Publish
 
 ```bash
@@ -53,5 +66,6 @@ git push origin main --tags
 After publishing:
 
 - Confirm `npm view sello version` shows the new version.
+- Confirm `python -m pip index versions sello` shows the new version after PyPI publishing.
 - Confirm `npx sello --help` works from a clean temp directory.
 - Confirm GitHub Actions passes on `main`.

package/docs/sdk-quickstart.md

@@ -2,7 +2,15 @@
 
 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.
+The local demo CLI and action viewer require Node.js 22.7 or newer. The Python SDK requires Python 3.9 or newer.
+
+## Install
+
+TypeScript:
+
+```bash
+npm install sello
+```
 
 ```ts
 import { sello } from "sello";
@@ -14,6 +22,22 @@ export const createEvent = receipts.tool("calendar.create_event", async (request
 });
 ```
 
+Python:
+
+```bash
+pip install sello
+```
+
+```py
+import sello
+
+receipts = sello.service()
+
+@receipts.tool("calendar.create_event")
+def create_event(request):
+    return calendar.events.create(request)
+```
+
 The service process emits receipts. It does not need the owner private key.
 
 ## Local Development
@@ -48,6 +72,18 @@ 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.
+
+## Troubleshooting
+
+- **Port already in use:** run `npx sello dev --port 8791`.
+- **No actions found:** make sure `sello dev` is running from the same project folder where you emitted the receipt.
+- **Missing token:** run `npx sello dev` first so `.sello/dev.json` exists.
+
 Inside this repo, start the local log and action viewer:
 
 ```bash
@@ -74,9 +110,9 @@ or open:
 http://localhost:8787/actions
 ```
 
-Both examples read `.sello/dev.json`, wrap a fake calendar handler, submit one encrypted receipt, and let the owner verify it locally.
+Both examples read `.sello/dev.json`, wrap a mock calendar handler, submit one encrypted receipt, and let the owner verify it locally.
 
-For the smallest production-shaped MCP boundary, 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 the smallest production-shaped MCP boundary, see [`sdks/typescript/examples/mcp-minimal-server.ts`](../sdks/typescript/examples/mcp-minimal-server.ts). It wraps one `tools/call` handler with `sello.service()` and leaves unknown tools unreceipted.
 
 For your own tool server, copy the printed service env:
 

package/docs/sdk-security-audit.md

@@ -7,7 +7,7 @@ These notes cover the first Stripe-style SDK implementation pass. They are writt
 - Service emission and owner viewing are documented as separate environments.
 - The service process is not required to hold `SELLO_OWNER_KEY`.
 - Hosted `sello.build` is described as optional convenience, not as a protocol dependency.
-- Deferred production features are named in `docs/sdk-build-plan.md`.
+- Deferred production features are named in the README, quickstart, and this audit note.
 
 ## Phase 1: Env-First Facade
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "sello",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.js",
-    "./fixtures/vectors/sello-v0.1.json": "./fixtures/vectors/sello-v0.1.json",
+    "./fixtures/vectors/sello-v0.1.json": "./sdks/typescript/fixtures/vectors/sello-v0.1.json",
     "./spec": "./SPEC.md",
     "./package.json": "./package.json"
   },
@@ -18,27 +18,27 @@
   },
   "files": [
     "dist",
-    "examples",
-    "src",
-    "fixtures/vectors",
+    "sdks/typescript/examples",
+    "sdks/typescript/src",
+    "sdks/typescript/fixtures/vectors",
     "docs",
     "SPEC.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "actions": "node --experimental-strip-types src/cli/sello.ts actions",
-    "bench": "node --experimental-strip-types src/cli/bench.ts",
-    "demo": "node --experimental-strip-types src/cli/demo.ts",
-    "dev": "node --experimental-strip-types src/cli/sello.ts dev",
-    "example:mcp:minimal": "node --test --experimental-strip-types test/examples/mcp-minimal-server.test.ts",
-    "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"
+    "actions": "node --experimental-strip-types sdks/typescript/src/cli/sello.ts actions",
+    "bench": "node --experimental-strip-types sdks/typescript/src/cli/bench.ts",
+    "demo": "node --experimental-strip-types sdks/typescript/src/cli/demo.ts",
+    "dev": "node --experimental-strip-types sdks/typescript/src/cli/sello.ts dev",
+    "example:mcp:minimal": "node --test --experimental-strip-types sdks/typescript/test/examples/mcp-minimal-server.test.ts",
+    "example:mcp": "node --experimental-strip-types sdks/typescript/examples/mcp-tool-server.ts",
+    "example:tool": "node --experimental-strip-types sdks/typescript/examples/quickstart-tool.ts",
+    "build": "node --disable-warning=ExperimentalWarning sdks/typescript/scripts/build-dist.mjs",
+    "package:test": "node sdks/typescript/scripts/package-smoke.mjs",
+    "pack:check": "node sdks/typescript/scripts/pack-check.mjs",
+    "prepack": "node --disable-warning=ExperimentalWarning sdks/typescript/scripts/build-dist.mjs",
+    "test": "cd sdks/typescript && node --test --experimental-strip-types"
   },
   "engines": {
     "node": ">=22.7.0"

package/sdks/README.md

@@ -0,0 +1,17 @@
+# Sello SDKs
+
+The protocol, paper, and project docs live at the repository root. Language SDKs live here:
+
+- [`typescript/`](typescript/): npm package source, CLI, examples, fixtures, and Node tests.
+- [`python/`](python/): Python package source and tests.
+
+Root commands still work from the repository top level:
+
+```bash
+node --run test
+node --run package:test
+python -m pip install ./sdks/python
+python -m unittest discover -s sdks/python/tests
+```
+
+This keeps the first screen of the repo focused on the protocol while giving each language a predictable home.

package/{src → sdks/typescript/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";
@@ -164,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) {
@@ -175,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),
@@ -188,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)}.`);
   });
 }
 
@@ -364,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")) {
@@ -392,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;
   }
@@ -413,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;
@@ -528,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));
 }

package/docs/sdk-build-plan.md

@@ -1,214 +0,0 @@
-# Stripe-Style Sello SDK Integration Plan
-
-## Summary
-
-Build the first Sello SDK around a complete, Stripe-like loop:
-
-1. Add one import.
-2. Call `sello.service()`.
-3. Wrap an existing tool handler.
-4. Run the tool.
-5. See verified logged actions.
-
-Quickstart service code:
-
-```ts
-import { sello } from "sello";
-
-const receipts = sello.service();
-
-export const createEvent = receipts.tool("calendar.create_event", async (request) => {
-  return calendar.events.create(request);
-});
-```
-
-Quickstart viewing:
-
-```bash
-npx sello actions --token <agent-token>
-```
-
-Local dev can also show:
-
-```text
-http://localhost:8787/actions
-```
-
-Sello must work without `sello.build`. Self-hosting is first-class. Hosted `sello.build` is optional convenience.
-
-## Configuration Model
-
-Keep service emission and owner viewing separate.
-
-### Service Runtime Env
-
-Used by the app/tool server that emits receipts.
-
-Self-hosted development:
-
-```bash
-SELLO_SERVICE_ID=calendar.example.com/mcp/v1
-SELLO_SERVICE_KEY=sello_dev_...
-SELLO_TOKEN_ISSUER_PUBLIC_KEY=...
-SELLO_LOG_URL=https://localhost:8787/api
-SELLO_LOG_ENDPOINT=http://localhost:8787/api
-SELLO_SUBMIT_MODE=background
-```
-
-Self-hosted production:
-
-```bash
-SELLO_SERVICE_ID=calendar.example.com/mcp/v1
-SELLO_SERVICE_KEY=sello_live_local_...
-SELLO_TOKEN_ISSUER_JWKS=https://auth.example.com/.well-known/jwks.json
-SELLO_LOG_URL=https://logs.example.com/api
-SELLO_SUBMIT_MODE=background
-```
-
-Hosted `sello.build`:
-
-```bash
-SELLO_SECRET_KEY=sello_test_...
-SELLO_SECRET_KEY=sello_live_...
-```
-
-Hosted mode uses one server-side secret to fetch service config and enable local receipt signing by default. Managed remote signing must be a later explicit opt-in because it changes the trust model.
-
-### Viewer Runtime Env
-
-Used by the owner CLI, local UI, or hosted dashboard to verify/decrypt actions.
-
-```bash
-SELLO_OWNER_KEY=sello_owner_...
-SELLO_REGISTRY_URL=https://registry.example.com/sello.json
-SELLO_REGISTRY_SIGNATURE=...
-SELLO_REGISTRY_TRUST_ROOT_PUBLIC_KEY=...
-SELLO_LOG_URL=https://logs.example.com/api
-```
-
-The owner key must not be required in the service process.
-
-## Public API
-
-```ts
-const receipts = sello.service();
-const receipts = sello.service("calendar.example.com/mcp/v1");
-const receipts = sello.service({ service, serviceKey, tokenIssuer, log, submit });
-```
-
-```ts
-const wrapped = receipts.tool(actionType, handler, options);
-await receipts.flush();
-```
-
-Tool behavior:
-
-- Verify token before handler execution.
-- Emit `success`, `error`, or `denied` receipts.
-- Return handler response unchanged.
-- Rethrow handler errors.
-- Use canonical JSON hashing by default.
-- Submit in background by default.
-- Support `submit.mode: "await"` for strict durability.
-- Support explicit custom log adapters for self-hosting.
-
-## Logged Actions UX
-
-```bash
-npx sello actions --token <agent-token>
-```
-
-Behavior:
-
-- Loads viewer config, not service config.
-- Computes `sello_token_ref`.
-- Queries trusted logs.
-- Verifies inclusion, service signature, revocation, HPKE decryption, and receipt body shape.
-- Prints verified actions and rejected receipts.
-
-Local dev:
-
-```bash
-npx sello dev
-npx sello actions
-```
-
-In dev mode, `sello dev` remembers the latest dev token and owner key in ignored local state so `npx sello actions` works without extra flags.
-
-Privacy rule:
-
-- Public logs store encrypted receipts.
-- Viewing action details requires the owner private key or delegated viewer key.
-- Self-hosted CLI decrypts locally.
-- Hosted dashboard must use client-side decryption or explicit delegated viewer keys.
-
-## Phase Plan
-
-### Phase 0: Baseline And SDK Contract
-
-- Write SDK examples into docs first.
-- Define env names, config precedence, and friendly errors.
-- Document service env versus viewer env.
-- Record deferred items: production Rekor proof verification, hosted dashboard, managed signing, durable queue.
-- Run `node --run test` and `node --run pack:check`.
-- Security audit: check the SDK contract does not weaken receiver-side signing or owner-side decryption.
-
-### Phase 1: Env-First SDK Facade
-
-- Add `sello.service()`.
-- Add env config loader.
-- Add key normalization for `Uint8Array` and encoded string inputs.
-- Add explicit config override path.
-- Add friendly missing-config errors.
-- Tests: env loading, service id override, explicit config override, hosted config selection, no owner key required for service emission.
-- Security audit: check secret handling, env precedence, errors, logging, and hosted/self-hosted boundaries.
-
-### Phase 2: Receipt Build/Submit Split And Background Publisher
-
-- Refactor receipt creation into build/encrypt/sign first, append second.
-- Keep existing `createReceipt()` behavior by composing build + append.
-- Add bounded background publisher with concurrency, `flush()`, `onSubmitError`, and `onDrop`.
-- Default to background submission.
-- Support `submit.mode: "await"`.
-- Tests: existing receipt tests, built envelope verification, background latency, `flush()`, overflow, failures, await mode, concurrency.
-- Security audit: check durability wording, queue bounds, memory pressure, failure handling, and unchanged cryptography.
-
-### Phase 3: Tool Wrapper MVP
-
-- Implement `receipts.tool(actionType, handler, options)`.
-- Default token extraction, input hashing, output hashing, and error hashing.
-- Support custom token extraction and canonicalizers.
-- Preserve handler semantics exactly.
-- Tests: success, error, denied, invalid token, custom extraction, custom canonicalizers, unchanged response, MCP compatibility.
-- Security audit: check token verification ordering, plaintext leakage, and service identity binding.
-
-### Phase 4: Logs And Action Viewing
-
-- Add `sello.logs.memory(url)` for local tests/dev.
-- Add `sello.logs.http(url, options?)` for self-hosted Sello-compatible log servers.
-- Add `npx sello actions --token <token>`.
-- Add local dev `/actions` page.
-- Action viewing uses owner-side verification and decryption.
-- Tests: memory log, HTTP append/query, CLI output, dev-mode token fallback, rejected reason codes, `/actions` states, no action details without owner/delegated key.
-- Security audit: check owner-side decryption, no plaintext in public logs, and safe rejected-receipt display.
-
-### Phase 5: Docs Polish And First-Run Flow
-
-- Add README section: **Add Sello in a Few Lines**.
-- Add `docs/sdk-quickstart.md`.
-- Document self-hosted development, self-hosted production, `sello.build` development, and `sello.build` production.
-- Document action viewing, token requirement, and privacy model.
-- Keep advanced explicit config separate from quickstart.
-- Tests: `node --run test`, `node --run pack:check`, manual quickstart run, docs do not require `sello.build`.
-- Security audit: review README, quickstart, CLI help, and examples with the full plan in hand.
-
-## Assumptions
-
-- MVP ships inside the current `sello` package.
-- One excellent generic tool wrapper beats many shallow adapters.
-- Testing is required for every phase before the next phase starts.
-- A security audit is required after every phase before the next phase starts.
-- Each auditor receives the full plan, current phase scope, deferred-item list, and threat model.
-- The service process emits receipts but does not need the owner private key.
-- Local/self-hosted usage is first-class.
-- `sello.build` is optional convenience, not a protocol requirement.