sebbi 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Monop Content
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# sebbi: a receipt for every AI agent action
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your agent refunds a customer, sends an email, moves money or answers a patient.
+Add one line and every one of those actions gets a **sealed receipt with a public link anyone can check**:
+your customer, your auditor, your insurer, a regulator.
+
+```bash
+npm install sebbi
+```
+
+```js
+import { receipt, last } from "sebbi";
+
+const decideRefund = receipt("refund-decision", async (order) => {
+  return { refund: true, amount: 42 };
+});
+
+await decideRefund({ id: 7 });
+console.log((await last()).url);   // https://sebbi.pro/r/...  anyone can check it
+```
+
+No account needed to start. Zero dependencies. Node 18+, Bun, Deno, edge runtimes and browsers. ESM and CommonJS. Typed.
+
+## Why teams add it
+
+- **Proof, not logs.** Each receipt sits in a Merkle tree sealed into the sebbi.pro chain, witnessed by independent chains, timestamped into Bitcoin and signed post-quantum. Nobody can quietly edit it afterwards.
+- **Your data stays yours.** Inputs and outputs are fingerprinted (SHA-256) where your code runs. Only fingerprints, a short label and a timestamp are sent.
+- **Never slows your agent.** Sealing runs in the background in batches and never throws into your code.
+- **Reversals done properly.** Refund, cancel or withdraw an action and the original receipt is shown as reversed, linked to a sealed reversal receipt. Nothing disappears.
+
+## Your framework, one line
+
+**Vercel AI SDK**
+```js
+import { wrapTools } from "sebbi";
+const result = await generateText({ model, prompt, tools: wrapTools({ getWeather, sendEmail }) });
+```
+
+**LangChain.js / Mastra / anything with tool objects**: `wrapTools([...tools])` wraps each tool's `execute`, `func` or `invoke`.
+
+**MCP servers (TypeScript SDK)**
+```js
+server.tool("lookup_customer", schema, receipt("lookup_customer", async (args) => { ... }));
+```
+
+**Anything else**
+```js
+import { seal } from "sebbi";
+const r = await seal(request, result, "send-invoice");
+await r.wait();   // optional
+console.log(r.url, r.sealed, r.blockIndex);
+```
+
+## Reversing an action
+
+```js
+import { reverse } from "sebbi";
+await reverse(r, "Customer cancelled; refund issued");
+```
+
+The original receipt stays sealed and valid, and its page shows **Reversed**, the reason and a link to the reversal receipt. Only whoever sealed the original (this installation, or the same account key) can reverse it, and a reversal cannot itself be reversed.
+
+## Settings
+
+| Environment | Meaning |
+|---|---|
+| `SEBBI_API_KEY` | Your key from https://sebbi.pro/connect. Optional. |
+| `SEBBI_DISABLED=1` | Turn every receipt into a no-op. |
+| `SEBBI_OWNER_SECRET` | Fix the owner secret (serverless, several machines). |
+
+Or in code: `configure({ apiKey: "..." })`.
+
+## Pricing
+
+- **Free lane:** 1,000 receipts a day, no account, no key.
+- **With a sebbi.pro account:** up to 100,000 a day, tied to your account and your evidence packs. 7 days free, then 50p per device per month.
+- **Checking any receipt is always free:** `check(id)` or https://sebbi.pro/r/<id>.
+
+Docs: https://sebbi.pro/receipts · MCP server: https://sebbi.pro/mcp · Made by Monop Content.

package/index.cjs

@@ -0,0 +1,293 @@
+"use strict";
+/*
+ * sebbi - a receipt for every AI agent action.  https://sebbi.pro/receipts
+ *
+ *   npm install sebbi
+ *
+ *   const { receipt, last } = require("sebbi");      // or: import { receipt } from "sebbi"
+ *   const decide = receipt("refund-decision", async (order) => ({ refund: true }));
+ *   await decide({ id: 7 });
+ *   console.log((await last()).url);                // https://sebbi.pro/r/...
+ *
+ * Inputs and outputs are fingerprinted (SHA-256 of canonical JSON) where your
+ * code runs. Only fingerprints, a short label and a timestamp are sent.
+ * Sealing runs in the background in batches and never throws into your code.
+ * Zero dependencies. Node 18+, Deno, Bun, edge runtimes and browsers.
+ */
+
+const VERSION = "1.1.0";
+const SITE = "https://sebbi.pro";
+const env = (k) => (typeof process !== "undefined" && process.env ? process.env[k] || "" : "");
+
+const cfg = {
+  apiKey: env("SEBBI_API_KEY"),
+  endpoint: env("SEBBI_ENDPOINT") || SITE + "/v1/receipts",
+  enabled: !["1", "true", "yes", "on"].includes(env("SEBBI_DISABLED").toLowerCase()),
+  client: "sebbi-js/" + VERSION,
+};
+
+function configure(o = {}) {
+  if (o.apiKey !== undefined) cfg.apiKey = o.apiKey;
+  if (o.endpoint !== undefined) cfg.endpoint = o.endpoint;
+  if (o.enabled !== undefined) cfg.enabled = !!o.enabled;
+  if (o.client !== undefined) cfg.client = o.client;
+}
+
+// ------------------------------------------------------------ fingerprints
+const subtle = () => (globalThis.crypto && globalThis.crypto.subtle) || require("node:crypto").webcrypto.subtle;
+const hex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+const enc = (s) => new TextEncoder().encode(s);
+
+function canonical(v, depth = 0) {
+  if (depth > 32) return "__sebbi_deep__";
+  if (v === null || v === undefined) return null;
+  const t = typeof v;
+  if (t === "string" || t === "boolean") return v;
+  if (t === "number") return Number.isFinite(v) ? v : String(v);
+  if (t === "bigint") return v.toString();
+  if (t === "function" || t === "symbol") return { __type__: t };
+  if (v instanceof Date) return v.toISOString();
+  if (Array.isArray(v)) return v.map((x) => canonical(x, depth + 1));
+  if (v instanceof Map) return canonical(Object.fromEntries(v), depth + 1);
+  if (v instanceof Set) return canonical([...v], depth + 1);
+  if (typeof v.toJSON === "function") return canonical(v.toJSON(), depth + 1);
+  const out = {};
+  for (const k of Object.keys(v)) out[k] = canonical(v[k], depth + 1);
+  return out;
+}
+
+function stringify(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(stringify).join(",") + "]";
+  return "{" + Object.keys(v).sort().map((k) => JSON.stringify(k) + ":" + stringify(v[k])).join(",") + "}";
+}
+
+const ascii = (s) => s.replace(/[\u007f-￿]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+
+async function fingerprint(value) {
+  return hex(await subtle().digest("SHA-256", enc(ascii(stringify(canonical(value))))));
+}
+
+// ------------------------------------------------------------- ownership
+// Each receipt commits to a secret only this installation holds, so only you
+// can reverse your own receipts. Per-receipt secrets are derived from one
+// master, so revealing one to reverse a receipt reveals nothing else.
+let masterP = null;
+function master() {
+  if (masterP) return masterP;
+  masterP = (async () => {
+    const e = env("SEBBI_OWNER_SECRET");
+    if (e) return e;
+    const rnd = () => hex(globalThis.crypto ? globalThis.crypto.getRandomValues(new Uint8Array(32)) : require("node:crypto").randomBytes(32));
+    try {
+      const fs = require("node:fs"), path = require("node:path"), os = require("node:os");
+      const p = path.join(os.homedir(), ".sebbi", "owner_secret");
+      try { const v = fs.readFileSync(p, "utf8").trim(); if (v.length >= 32) return v; } catch (_) {}
+      const v = rnd();
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      fs.writeFileSync(p, v, { mode: 0o600, flag: "wx" });
+      return v;
+    } catch (_) {
+      return rnd(); // browsers, edge, read-only disks: this process can still reverse what it sealed
+    }
+  })();
+  return masterP;
+}
+
+async function secretFor(id) {
+  const key = await subtle().importKey("raw", enc(await master()), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return hex(await subtle().sign("HMAC", key, enc("sebbi-owner|" + id)));
+}
+
+const sha = async (s) => hex(await subtle().digest("SHA-256", enc(s)));
+const newId = () => "r" + hex(globalThis.crypto ? globalThis.crypto.getRandomValues(new Uint8Array(12)) : require("node:crypto").randomBytes(12)).slice(0, 23);
+
+// ------------------------------------------------------------------ receipt
+class Receipt {
+  constructor(label, inputHash, outputHash, outcome) {
+    this.id = newId();
+    this.label = String(label || "").slice(0, 80);
+    this.inputHash = inputHash;
+    this.outputHash = outputHash;
+    this.ts = Date.now() / 1000;
+    this.outcome = outcome || "ok";
+    this.sealed = false;
+    this.error = null;
+    this.blockIndex = null;
+    this.merkleRoot = null;
+    this.reverses = null;
+    this.reason = "";
+    this._done = new Promise((r) => (this._resolve = r));
+  }
+  get url() { return SITE + "/r/" + this.id; }
+  /** Resolves once sealed (or failed). */
+  wait(ms = 15000) { kick(); return Promise.race([this._done, new Promise((r) => setTimeout(() => r(this), ms))]); }
+  async wire() {
+    const ih = this.inputHash, oh = this.outputHash;
+    const d = { local_id: this.id, label: this.label, input_hash: ih, output_hash: oh, hash: await sha(ih + ":" + oh),
+      ts: this.ts, outcome: this.outcome, owner: await sha(await secretFor(this.id)) };
+    if (this.reverses) Object.assign(d, { reverses: this.reverses, reason: this.reason, owner_secret: await secretFor(this.reverses) });
+    return d;
+  }
+  toJSON() {
+    return { id: this.id, url: this.url, label: this.label, inputHash: this.inputHash, outputHash: this.outputHash, ts: this.ts,
+      outcome: this.outcome, sealed: this.sealed, error: this.error, blockIndex: this.blockIndex, merkleRoot: this.merkleRoot,
+      reverses: this.reverses };
+  }
+}
+
+// ------------------------------------------------------------------ sender
+const queue = [];
+const counts = { queued: 0, sealed: 0, failed: 0 };
+let notice = null, timer = null, inflight = 0;
+
+function kick(delay = 0) {
+  if (timer) { if (delay) return; clearTimeout(timer); }
+  timer = setTimeout(drain, delay);
+  if (timer && typeof timer.unref === "function" && delay) timer.unref();
+}
+
+async function drain() {
+  timer = null;
+  while (queue.length) {
+    const batch = queue.splice(0, 100);
+    inflight += batch.length;
+    try { await send(batch); } finally { inflight -= batch.length; }
+  }
+}
+
+async function send(batch) {
+  let err = null;
+  const body = JSON.stringify({ records: await Promise.all(batch.map((r) => r.wire())), sdk: cfg.client });
+  const headers = { "Content-Type": "application/json", Accept: "application/json" };
+  if (cfg.apiKey) headers.Authorization = "Bearer " + cfg.apiKey;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const res = await fetch(cfg.endpoint, { method: "POST", headers, body });
+      const doc = await res.json().catch(() => ({}));
+      if (doc.message) notice = doc.message;
+      if (res.ok) return apply(batch, doc);
+      err = "http_" + res.status + (doc.error ? ":" + doc.error : "");
+      if (res.status < 500 && res.status !== 429) break;
+    } catch (e) {
+      err = (e && e.name) || "network";
+    }
+    await new Promise((r) => setTimeout(r, Math.min(8000, 500 * 2 ** attempt)));
+  }
+  for (const r of batch) { r.error = err; counts.failed++; r._resolve(r); }
+}
+
+function apply(batch, doc) {
+  const by = {};
+  for (const x of doc.records || []) if (x && x.local_id) by[x.local_id] = x;
+  for (const r of batch) {
+    const x = by[r.id];
+    if (x) {
+      r.id = x.id || r.id; r.sealed = true; r.blockIndex = x.block_index; r.merkleRoot = x.merkle_root; counts.sealed++;
+    } else { r.error = "not_in_response"; counts.failed++; }
+    r._resolve(r);
+  }
+}
+
+let lastP = Promise.resolve(null);
+
+function enqueue(r) {
+  if (!cfg.enabled) { r.error = "disabled"; r._resolve(r); return r; }
+  queue.push(r); counts.queued++; kick(400);
+  return r;
+}
+
+/** Seal one action. Resolves to its Receipt (url usable at once; .wait() for the seal). */
+function seal(input, output, label = "", outcome = "ok") {
+  const p = (async () => enqueue(new Receipt(label, await fingerprint(input), await fingerprint(output), outcome)))();
+  lastP = p;
+  p.catch(() => {});
+  return p;
+}
+
+/**
+ * Reverse an action you sealed earlier. Nothing is deleted: the original stays
+ * sealed and is shown as REVERSED, linked to the new reversal receipt. The
+ * reason is public on both. Only whoever sealed the original can reverse it.
+ */
+function reverse(original, reason, output = null, label = "") {
+  const oid = typeof original === "string" ? original : original && original.id;
+  if (!oid) return Promise.reject(new Error("reverse(original, reason): original receipt or id required"));
+  if (!reason) return Promise.reject(new Error("a reversal needs a reason; it is shown on both receipts"));
+  const p = (async () => {
+    const r = new Receipt(label || "reversal of " + oid, await fingerprint({ reverses: oid }), await fingerprint(output), "reversal");
+    r.reverses = oid; r.reason = String(reason).slice(0, 300);
+    return enqueue(r);
+  })();
+  lastP = p;
+  return p;
+}
+
+/** Wrap a function (sync or async). receipt(fn) or receipt("label", fn). */
+function receipt(label, fn) {
+  if (typeof label === "function") { fn = label; label = fn.name || "action"; }
+  if (typeof fn !== "function") return (f) => receipt(label, f);
+  const name = label || fn.name || "action";
+  const wrapped = function (...args) {
+    const input = args.length === 1 ? args[0] : args;
+    let out;
+    try { out = fn.apply(this, args); } catch (e) { seal(input, { error_type: (e && e.name) || "Error" }, name, "error"); throw e; }
+    if (out && typeof out.then === "function") {
+      return out.then((v) => { seal(input, v, name); return v; },
+        (e) => { seal(input, { error_type: (e && e.name) || "Error" }, name, "error"); throw e; });
+    }
+    seal(input, out, name);
+    return out;
+  };
+  Object.defineProperty(wrapped, "name", { value: fn.name });
+  return wrapped;
+}
+
+/**
+ * Vercel AI SDK, Mastra, LangChain.js tool objects, MCP handlers: wraps every
+ * tool's `execute` (or `func` / `invoke`) so each tool call gets a receipt.
+ *   tools: wrapTools({ getWeather, sendEmail })
+ */
+function wrapTools(tools, prefix = "") {
+  const wrapOne = (name, t) => {
+    if (typeof t === "function") return receipt(prefix + name, t);
+    if (!t || typeof t !== "object") return t;
+    const c = Object.assign(Object.create(Object.getPrototypeOf(t)), t);
+    for (const m of ["execute", "func", "invoke"]) {
+      if (typeof t[m] === "function") { c[m] = receipt(prefix + (t.name || name), t[m].bind(t)); break; }
+    }
+    return c;
+  };
+  if (Array.isArray(tools)) return tools.map((t, i) => wrapOne((t && t.name) || "tool" + i, t));
+  const out = {};
+  for (const k of Object.keys(tools || {})) out[k] = wrapOne(k, tools[k]);
+  return out;
+}
+
+/** Most recent receipt created in this process (a Promise). */
+const last = () => lastP;
+
+/** Send everything queued now. */
+async function flush(ms = 5000) {
+  const end = Date.now() + ms;
+  kick();
+  while (Date.now() < end) {
+    if (!queue.length && !inflight) return true;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return false;
+}
+
+const stats = () => Object.assign({}, counts, { pending: queue.length, endpoint: cfg.endpoint, keyed: !!cfg.apiKey, notice });
+
+/** Check a receipt by id. Anyone can, no key. */
+async function check(id) {
+  const res = await fetch(SITE + "/v1/receipts/" + encodeURIComponent(id));
+  return res.json();
+}
+
+if (typeof process !== "undefined" && typeof process.on === "function") {
+  process.on("beforeExit", () => { if (queue.length) kick(); });
+}
+
+module.exports = { receipt, seal, reverse, wrapTools, last, flush, configure, stats, fingerprint, check, Receipt, VERSION };

package/index.d.ts

@@ -0,0 +1,25 @@
+export declare const VERSION: string;
+export declare class Receipt {
+  id: string; label: string; inputHash: string; outputHash: string; ts: number; outcome: string;
+  sealed: boolean; error: string | null; blockIndex: number | null; merkleRoot: string | null; reverses: string | null;
+  readonly url: string;
+  wait(ms?: number): Promise<Receipt>;
+  toJSON(): Record<string, unknown>;
+}
+export declare function receipt<F extends (...a: any[]) => any>(fn: F): F;
+export declare function receipt<F extends (...a: any[]) => any>(label: string, fn: F): F;
+export declare function receipt(label: string): <F extends (...a: any[]) => any>(fn: F) => F;
+export declare function seal(input: unknown, output: unknown, label?: string, outcome?: "ok" | "error"): Promise<Receipt>;
+export declare function reverse(original: Receipt | string, reason: string, output?: unknown, label?: string): Promise<Receipt>;
+export declare function wrapTools<T>(tools: T, prefix?: string): T;
+export declare function last(): Promise<Receipt | null>;
+export declare function flush(ms?: number): Promise<boolean>;
+export declare function configure(o: { apiKey?: string; endpoint?: string; enabled?: boolean; client?: string }): void;
+export declare function stats(): { queued: number; sealed: number; failed: number; pending: number; endpoint: string; keyed: boolean; notice: string | null };
+export declare function fingerprint(value: unknown): Promise<string>;
+export declare function check(id: string): Promise<Record<string, any>>;
+declare const _default: {
+  receipt: typeof receipt; seal: typeof seal; reverse: typeof reverse; wrapTools: typeof wrapTools; last: typeof last;
+  flush: typeof flush; configure: typeof configure; stats: typeof stats; fingerprint: typeof fingerprint; check: typeof check;
+};
+export default _default;

package/index.mjs

@@ -0,0 +1,3 @@
+import m from "./index.cjs";
+export const { receipt, seal, reverse, wrapTools, last, flush, configure, stats, fingerprint, check, Receipt, VERSION } = m;
+export default m;

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "sebbi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "A receipt for every AI agent action. One line: every tool call gets a sealed, publicly checkable receipt. Vercel AI SDK, LangChain.js, Mastra, MCP.",
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./index.mjs", "require": "./index.cjs" }
+  },
+  "files": ["index.cjs", "index.mjs", "index.d.ts", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "keywords": ["ai", "agents", "audit", "receipts", "ai-sdk", "vercel-ai", "langchain", "mastra", "mcp", "governance", "eu-ai-act", "compliance", "provenance", "merkle"],
+  "homepage": "https://sebbi.pro/receipts",
+  "author": "Monop Content <justrightdecorators@gmail.com>",
+  "license": "MIT"
+}