sello 0.1.0

package/docs/paper/refs.bib

@@ -0,0 +1,245 @@
+@techreport{RFC6962,
+  author = {Laurie, B. and Langley, A. and Kasper, E.},
+  title = {Certificate Transparency},
+  institution = {IETF},
+  type = {RFC},
+  number = {6962},
+  year = {2013},
+  month = jun
+}
+
+@techreport{RFC9162,
+  author = {Laurie, B. and Messeri, E. and Stradling, R.},
+  title = {Certificate Transparency Version 2.0},
+  institution = {IETF},
+  type = {RFC},
+  number = {9162},
+  year = {2021},
+  month = dec
+}
+
+@techreport{RFC7515,
+  author = {Jones, M. and Bradley, J. and Sakimura, N.},
+  title = {JSON Web Signature (JWS)},
+  institution = {IETF},
+  type = {RFC},
+  number = {7515},
+  year = {2015},
+  month = may
+}
+
+@techreport{RFC8610,
+  author = {Birkholz, H. and Vigano, C. and Bormann, C.},
+  title = {Concise {Data} {Definition} {Language} ({CDDL}): {A} {Notational} {Convention} to {Express} {Concise} {Binary} {Object} {Representation} ({CBOR}) and {JSON} {Data} {Structures}},
+  institution = {IETF},
+  type = {RFC},
+  number = {8610},
+  year = {2019},
+  month = jun
+}
+
+@techreport{RFC9052,
+  author = {Schaad, J.},
+  title = {{CBOR} {Object} {Signing} and {Encryption} ({COSE}): {Structures} and {Process}},
+  institution = {IETF},
+  type = {RFC},
+  number = {9052},
+  year = {2022},
+  month = aug
+}
+
+@techreport{RFC9180,
+  author = {Barnes, R. and Bhargavan, K. and Lipp, B. and Wood, C.},
+  title = {Hybrid {Public} {Key} {Encryption}},
+  institution = {IETF},
+  type = {RFC},
+  number = {9180},
+  year = {2022},
+  month = feb
+}
+
+@techreport{RFC9449,
+  author = {Fett, D. and Campbell, B. and Bradley, J. and Lodderstedt, T. and Jones, M. and Waite, D.},
+  title = {{OAuth} 2.0 {Demonstrating} {Proof} of {Possession} ({DPoP})},
+  institution = {IETF},
+  type = {RFC},
+  number = {9449},
+  year = {2023},
+  month = sep
+}
+
+@article{Heinrich2021,
+  author = {Heinrich, A. and Stute, M. and Kornhuber, T. and Hollick, M.},
+  title = {Who {Can} {Find} {My} {Devices}? {Security} and {Privacy} of {Apple}'s {Crowd}-{Sourced} {Bluetooth} {Location} {Tracking} {System}},
+  journal = {Proceedings on Privacy Enhancing Technologies},
+  volume = {2021},
+  number = {3},
+  pages = {227--245},
+  year = {2021}
+}
+
+@inproceedings{Syta2016,
+  author = {Syta, E. and Tamas, I. and Visher, D. and Wolinsky, D. I. and Jovanovic, P. and Gasser, L. and Gailly, N. and Khoffi, I. and Ford, B.},
+  title = {Keeping {Authorities} `{Honest} or {Bust}' with {Decentralized} {Witness} {Cosigning}},
+  booktitle = {IEEE Symposium on Security and Privacy},
+  pages = {526--545},
+  year = {2016}
+}
+
+@article{bernstein2012ed25519,
+  author = {Bernstein, D. J. and Duif, N. and Lange, T. and Schwabe, P. and Yang, B.},
+  title = {High-speed high-security signatures},
+  journal = {Journal of Cryptographic Engineering},
+  volume = {2},
+  number = {2},
+  year = {2012}
+}
+
+@misc{sigstore-rekor,
+  author = {{The Sigstore Authors}},
+  title = {Rekor: {Software} {Supply} {Chain} {Transparency} {Log}},
+  howpublished = {\url{https://github.com/sigstore/rekor}},
+  year = {2024}
+}
+
+@misc{sello-repo,
+  author = {Figuera, J.},
+  title = {Sello: {A} protocol for receiver-attested confidential receipts for {AI} agent actions},
+  howpublished = {Reference implementation, \url{https://github.com/juanfiguera/sello}},
+  year = {2026}
+}
+
+@techreport{scitt-architecture,
+  author = {Birkholz, H. and Delignat-Lavaud, A. and Fournet, C. and Deshpande, Y. and Lasker, S.},
+  title = {An {Architecture} for {Trustworthy} and {Transparent} {Digital} {Supply} {Chains}},
+  institution = {IETF},
+  type = {Internet-Draft},
+  number = {draft-ietf-scitt-architecture},
+  year = {2026}
+}
+
+@techreport{scitt-scrapi,
+  author = {Steele, O. and Birkholz, H.},
+  title = {{SCITT} {Reference} {APIs}},
+  institution = {IETF},
+  type = {Internet-Draft},
+  number = {draft-ietf-scitt-scrapi},
+  year = {2026}
+}
+
+@techreport{scitt-ccf,
+  author = {Delignat-Lavaud, A. and others},
+  title = {{SCITT} {Receipts}: {CCF} {Profile}},
+  institution = {IETF},
+  type = {Internet-Draft},
+  number = {draft-ietf-scitt-receipts-ccf-profile},
+  year = {2026}
+}
+
+@misc{agentreceipts,
+  author = {Jongerius, O.},
+  title = {Agent {Receipts}},
+  howpublished = {\url{https://agentreceipts.ai}},
+  year = {2025--2026}
+}
+
+@misc{signet,
+  author = {Hou, W.},
+  title = {Signet: {Cryptographic} {Action} {Receipts} for {AI} {Agents}},
+  howpublished = {\url{https://github.com/Prismer-AI/signet}},
+  year = {2025--2026}
+}
+
+@misc{pipelock,
+  author = {{PipeLab}},
+  title = {Pipelock: {AI} {Agent} {Security} {Gateway}},
+  howpublished = {\url{https://pipelab.org}},
+  year = {2026}
+}
+
+@misc{aps,
+  author = {Pidlisnyi, T.},
+  title = {Agent {Passport} {System}},
+  howpublished = {\url{https://github.com/aeoess/agent-passport-system}},
+  year = {2025--2026}
+}
+
+@techreport{farley-acta,
+  author = {Farley, T.},
+  title = {Signed {Decision} {Receipts} for {Machine}-to-{Machine} {Access} {Control}},
+  institution = {IETF},
+  type = {Internet-Draft},
+  number = {draft-farley-acta-signed-receipts},
+  year = {2026}
+}
+
+@techreport{nivalto-agentroa,
+  author = {Michalak, J.},
+  title = {Agent {Route} {Origin} {Authorization} ({AgentROA}): {A} {Cryptographic} {Policy} {Enforcement} {Framework} for {AI} {Agent} {Actions}},
+  institution = {IETF},
+  type = {Internet-Draft},
+  number = {draft-nivalto-agentroa-route-authorization},
+  year = {2026}
+}
+
+@misc{attestedintelligence,
+  author = {{Attested Intelligence Holdings LLC}},
+  title = {Attested {Governance} {Artifacts}: {Public} {Comment} on {Docket} {NIST}-2025-0035},
+  year = {2026},
+  month = mar
+}
+
+@techreport{kamimura-scitt,
+  author = {Kamimura, S.},
+  title = {{SCITT} {Profile} for {Financial} {Trading} {Audit} {Trails}},
+  institution = {IETF},
+  type = {Internet-Draft},
+  number = {draft-kamimura-scitt-vcp},
+  year = {2026}
+}
+
+@article{zhang-righttohistory,
+  author = {Zhang, J.},
+  title = {Right to {History}: {A} {Sovereignty} {Kernel} for {Verifiable} {AI} {Agent} {Execution}},
+  journal = {arXiv preprint arXiv:2602.20214},
+  year = {2026},
+  month = feb
+}
+
+@article{gupta-verifiabilityfirst,
+  author = {Gupta, A.},
+  title = {Verifiability-{First} {Agents}: {Provable} {Observability} and {Lightweight} {Audit} {Agents} for {Controlling} {Autonomous} {LLM} {Systems}},
+  journal = {arXiv preprint arXiv:2512.17259},
+  year = {2025},
+  month = dec
+}
+
+@article{basu-toolreceipts,
+  author = {Basu, A.},
+  title = {Tool {Receipts}, {Not} {Zero}-{Knowledge} {Proofs}: {Practical} {Hallucination} {Detection} for {AI} {Agents}},
+  journal = {arXiv preprint arXiv:2603.10060},
+  year = {2026},
+  month = mar
+}
+
+@inproceedings{casper-blackbox,
+  author = {Casper, Stephen and Ezell, Carson and Siegmann, Charlotte and Kolt, Noam and Curtis, Taylor Lynn and Bucknall, Benjamin and Haupt, Andreas and Wei, Kevin and Scheurer, J{\'e}r{\'e}my and Hobbhahn, Marius and Sharkey, Lee and Krishna, Satyapriya and Von Hagen, Marvin and Alberti, Silas and Chan, Alan and Sun, Qinyi and Gerovitch, Michael and Bau, David and Tegmark, Max and Krueger, David and Hadfield-Menell, Dylan},
+  title = {Black-Box {Access} is {Insufficient} for {Rigorous} {AI} {Audits}},
+  booktitle = {Proceedings of the 2024 ACM Conference on Fairness, Accountability, and Transparency (FAccT)},
+  pages = {2254--2272},
+  year = {2024}
+}
+
+@inproceedings{kales-pir-ct,
+  author = {Kales, D. and Omolola, O. and Ramacher, S.},
+  title = {Revisiting {User} {Privacy} for {Certificate} {Transparency}},
+  booktitle = {IEEE European Symposium on Security and Privacy},
+  year = {2019}
+}
+
+@misc{euaiact,
+  key = {EU AI Act},
+  title = {Regulation ({EU}) 2024/1689 of the {European} {Parliament} and of the {Council} laying down harmonised rules on artificial intelligence ({Artificial} {Intelligence} {Act})},
+  year = {2024},
+  month = jul
+}

package/docs/performance.md

@@ -0,0 +1,24 @@
+# Performance And Receipt Size
+
+Sello includes a small local benchmark for tracking rough receipt size and implementation performance:
+
+```sh
+node --run bench
+node --run bench -- --iterations 500 --warmup 500 --json
+```
+
+The benchmark uses the reference implementation with fixed local keys and the mock transparency log. By default it runs 500 warmup iterations before measuring. It reports:
+
+- CBOR receipt body size.
+- COSE protected-header size.
+- HPKE payload size.
+- Full COSE_Sign1 envelope size.
+- Mock proof JSON size.
+- Average receipt creation time.
+- Average one-receipt verification time.
+- Batch verification time and per-receipt average.
+- Mean, median, p95, p99, and standard deviation for per-receipt creation and one-receipt verification samples.
+
+These numbers are useful for local regression tracking and integration planning. They are not formal cryptographic benchmarks: results vary by CPU, Node version, OS, and thermal state, and the mock log is not a live Rekor deployment.
+
+For production capacity planning, measure against the real service middleware, real action payload canonicalization, the chosen log adapter, and the deployment's key storage path.

package/docs/release-checklist.md

@@ -0,0 +1,56 @@
+# Release Checklist
+
+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 `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.
+
+## Local Verification
+
+```bash
+node --run test
+npm pack --dry-run
+```
+
+Fresh clone smoke test:
+
+```bash
+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 --run 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
+```
+
+## npm Verification
+
+```bash
+npm whoami
+npm view sello version
+npm publish --dry-run
+```
+
+If the package name is already published, confirm the local version is greater than the registry version before publishing.
+
+## Publish
+
+```bash
+npm publish
+git tag v$(node -p "require('./package.json').version")
+git push origin main --tags
+```
+
+After publishing:
+
+- Confirm `npm view sello version` shows the new version.
+- Confirm `npx sello --help` works from a clean temp directory.
+- Confirm GitHub Actions passes on `main`.

package/docs/sdk-build-plan.md

@@ -0,0 +1,214 @@
+# 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.

package/docs/sdk-quickstart.md

@@ -0,0 +1,115 @@
+# Sello SDK Quickstart
+
+Sello's SDK is designed to make the first receipt easy: wrap a tool handler, run it, and inspect verified actions.
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const createEvent = receipts.tool("calendar.create_event", async (request) => {
+  return calendar.events.create(request);
+});
+```
+
+The service process emits receipts. It does not need the owner private key.
+
+## Local Development
+
+Inside this repo, start the local log and action viewer:
+
+```bash
+node --run dev
+```
+
+In another terminal, run the repo's wrapped tool example:
+
+```bash
+node --run example:tool
+node --run actions
+```
+
+For an MCP-shaped `tools/call` boundary, run:
+
+```bash
+node --run example:mcp
+node --run actions
+```
+
+or open:
+
+```text
+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.
+
+For your own tool server, copy the printed service env:
+
+```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
+```
+
+Call your wrapped tool with the printed dev token. Then view actions:
+
+```bash
+npx sello actions
+```
+
+## Self-Hosted Production
+
+Use your own Sello-compatible log server:
+
+```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
+```
+
+View actions from an owner-controlled environment:
+
+```bash
+SELLO_OWNER_KEY=sello_owner_live_...
+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
+npx sello actions --token <agent-token>
+```
+
+## Hosted Sello
+
+Hosted mode keeps the application code the same:
+
+```bash
+SELLO_SECRET_KEY=sello_test_...
+```
+
+The secret is server-side only. Hosted mode is optional; Sello does not require `sello.build`.
+
+## Advanced Explicit Config
+
+You can bypass env config entirely:
+
+```ts
+const receipts = sello.service({
+  service: "calendar.example.com/mcp/v1",
+  serviceKey: { kid, privateKey },
+  tokenIssuer: tokenIssuerPublicKey,
+  log: sello.logs.memory("https://localhost:8787/api"),
+  submit: { mode: "await" },
+});
+```
+
+Use explicit config for tests, embedded runtimes, or custom self-hosted deployments.
+
+## Privacy
+
+Public logs store encrypted receipts. Viewing action details requires the owner private key or an explicitly delegated viewer key. The CLI decrypts locally; hosted dashboards must use client-side decryption or delegated viewer keys.