vouchwell 0.5.0__tar.gz

vouchwell-0.5.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: vouchwell
+Version: 0.5.0
+Summary: Tamper-evident receipts for AI agent actions. Python SDK, wire-compatible with the vouchwell CLI.
+Author: IdeaboticsAI
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/vouchwell/vouchwell
+Project-URL: Source, https://github.com/vouchwell/vouchwell/tree/main/sdk/python
+Project-URL: Issues, https://github.com/vouchwell/vouchwell/issues
+Keywords: ai-agents,audit,transparency-log,merkle,ed25519,eu-ai-act
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.2; extra == "openai-agents"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: langchain-core>=0.3; python_version >= "3.10" and extra == "test"
+Requires-Dist: openai-agents>=0.2; python_version >= "3.10" and extra == "test"
+
+# vouchwell (Python)
+
+Tamper-evident receipts for what your AI agents do, from Python. This is the
+Python SDK for [Vouchwell](https://github.com/vouchwell/vouchwell), and it
+writes exactly the format the `vouchwell` CLI reads:
+
+- a log written here passes `vw verify`;
+- a bundle exported here passes `vw check`;
+- logs and bundles written by the JavaScript side open and verify here.
+
+CI runs both directions against the real CLI on every commit.
+
+```bash
+pip install "vouchwell @ git+https://github.com/vouchwell/vouchwell#subdirectory=sdk/python"
+```
+
+That installs straight from this repository. The package is not on PyPI yet;
+once it is, `pip install vouchwell` will do the same.
+
+Python 3.9+. The one dependency is `cryptography`, for Ed25519.
+
+## Record an agent's tool calls
+
+```python
+from vouchwell import ProofLog, Recorder
+
+log = ProofLog.open_or_create(".vouchwell")
+rec = Recorder(log, agent="support-bot", principal="ops@acme.com", namespace="stripe")
+
+@rec.tool("refund", metrics=lambda order_id, amount_cents: {"amount_usd": amount_cents / 100})
+def refund(order_id: str, amount_cents: int):
+    return stripe.Refund.create(payment_intent=order_id, amount=amount_cents)
+
+refund("pi_123", 4200)
+```
+
+Each call leaves two signed receipts:
+
+1. **An intent receipt, before the call runs.** A crash mid-call still leaves
+   evidence it was attempted.
+2. **An outcome receipt, when it returns or raises**, linked to the intent.
+
+Async functions work the same. So does a context manager:
+
+```python
+with rec.call("crm.update", params={"id": 42}) as call:
+    call.result = crm.update(42)
+```
+
+Arguments and results are **committed to, not stored**. A receipt holds a
+salted hash plus a preview with secrets and personal data masked (API keys,
+card numbers, emails and so on). The salts stay in the log's private
+`salts.jsonl`, so you can later prove what a value was:
+`log.reveal(seq, "params", value)`. Or you can destroy the salts, and the value
+becomes unprovable forever while the receipt still verifies:
+`log.shred(predicate)`.
+
+### Check calls before they run
+
+```python
+def decide(target, params):
+    if target.endswith(".delete"):
+        return {"outcome": "deny", "rules": ["no-deletes"], "reason": "agents may not delete"}
+    return {"outcome": "allow", "policy": "v3"}
+
+rec = Recorder(log, agent="support-bot", principal="ops@acme.com", decide=decide)
+```
+
+A refused call never runs. It gets one receipt, and `PolicyDenied` is raised.
+An `escalate` outcome is a denial here, recorded as `policy:no-approver`,
+because nobody in the process can approve it.
+
+The full policy language (budgets, rate limits, escalation to a person, Slack
+approvals, monitor mode) lives in the `vw proxy` MCP proxy and in the
+JavaScript `Recorder` in `@vouchwell/core`. For an agent that uses MCP, wrap
+its servers with the proxy instead. A Python port of the policy engine is
+planned.
+
+### Use it with LangChain or the OpenAI Agents SDK
+
+Wrap the agent's tools once; use the wrapped ones in their place. Each call is
+checked with `decide`, recorded as intent and outcome, and a refused call
+never runs: the model is told why in the tool's reply, as the MCP proxy does,
+instead of the agent crashing.
+
+```python
+from vouchwell.integrations.langchain import record_tools        # pip install "vouchwell[langchain]"
+agent = create_react_agent(model, record_tools(rec, [search, refund]))
+
+from vouchwell.integrations.openai_agents import record_tools    # pip install "vouchwell[openai-agents]"
+agent = Agent(name="Support", tools=record_tools(rec, [lookup_order, refund]))
+```
+
+Hosted OpenAI tools (web search and the like) run on OpenAI's side, so they
+are passed through unrecorded. Both adapters need Python 3.10+, and are tested
+in CI against the real packages.
+
+### Find calls that never finished
+
+Each call's intent is on disk before the tool runs. If the process is killed
+while a call is out, the intent has no outcome, and that is worth knowing:
+
+```python
+from vouchwell import find_unfinished
+
+found = find_unfinished(log.entries)
+for u in found["unfinished"]:
+    print(u["seq"], u["ts"], u["target"], u["principal"])
+```
+
+`inFlight` holds calls from the last five minutes that may still be running,
+and `abandoned` the ones a recorder gave up on while shutting down. `vw verify`
+reports the same list, and `vw verify --fail-on-unfinished` exits 3 when there
+is one.
+
+## Hand over evidence
+
+```python
+import json
+from vouchwell import verify_bundle
+
+log.checkpoint()                                   # sign the current state
+open("evidence.json", "w").write(json.dumps(log.bundle()))
+
+# Anyone can verify it, here or with `vw check evidence.json`:
+verify_bundle(json.load(open("evidence.json")))
+# -> {"ok": True, "issues": [], "checked": 12}
+```
+
+To require an independent witness, pin its key. Get the key from somewhere the
+bundle can't influence:
+
+```python
+verify_bundle(bundle, min_witnesses=1, trusted_witnesses={"pw1…": "<public key>"})
+```
+
+`vw report` (from the npm CLI) turns a log written here into an evidence pack
+for auditors.
+
+## Ship to a hub
+
+```python
+from vouchwell import push
+
+push(log, "https://hub.acme.com", token=os.environ["VOUCHWELL_TOKEN"], name="support-bot")
+```
+
+It sends whatever the hub doesn't have yet, and is safe to call again. Plain
+`http://` is refused unless the hub is on this machine, so the API key never
+crosses a network unencrypted.
+
+## What's here
+
+| Module | |
+| --- | --- |
+| `canonical` | RFC 8785 canonical JSON: UTF-16 key order, ECMAScript number formatting |
+| `merkle` | RFC 6962 trees, inclusion and consistency proofs |
+| `unfinished` | `find_unfinished`: calls sent and never answered |
+| `integrations` | `langchain.record_tools`, `openai_agents.record_tools` |
+| `keys` | Ed25519 identities, canonical base64url |
+| `receipt` | Build, seal, sign and verify receipts |
+| `checkpoint` | Signed tree heads, witness countersignatures |
+| `log` | `ProofLog`, the on-disk log the CLI shares, and `verify_bundle` |
+| `record` | `Recorder`, for Python agents |
+| `remote` | `push` to a hub |
+
+Tested against the RFC 6962 Certificate Transparency reference tree and the
+RFC 8032 Ed25519 vectors, plus byte-level canonicalization parity with the
+JavaScript implementation over hundreds of awkward values.
+
+License: Apache-2.0.

vouchwell-0.5.0/README.md

@@ -0,0 +1,171 @@
+# vouchwell (Python)
+
+Tamper-evident receipts for what your AI agents do, from Python. This is the
+Python SDK for [Vouchwell](https://github.com/vouchwell/vouchwell), and it
+writes exactly the format the `vouchwell` CLI reads:
+
+- a log written here passes `vw verify`;
+- a bundle exported here passes `vw check`;
+- logs and bundles written by the JavaScript side open and verify here.
+
+CI runs both directions against the real CLI on every commit.
+
+```bash
+pip install "vouchwell @ git+https://github.com/vouchwell/vouchwell#subdirectory=sdk/python"
+```
+
+That installs straight from this repository. The package is not on PyPI yet;
+once it is, `pip install vouchwell` will do the same.
+
+Python 3.9+. The one dependency is `cryptography`, for Ed25519.
+
+## Record an agent's tool calls
+
+```python
+from vouchwell import ProofLog, Recorder
+
+log = ProofLog.open_or_create(".vouchwell")
+rec = Recorder(log, agent="support-bot", principal="ops@acme.com", namespace="stripe")
+
+@rec.tool("refund", metrics=lambda order_id, amount_cents: {"amount_usd": amount_cents / 100})
+def refund(order_id: str, amount_cents: int):
+    return stripe.Refund.create(payment_intent=order_id, amount=amount_cents)
+
+refund("pi_123", 4200)
+```
+
+Each call leaves two signed receipts:
+
+1. **An intent receipt, before the call runs.** A crash mid-call still leaves
+   evidence it was attempted.
+2. **An outcome receipt, when it returns or raises**, linked to the intent.
+
+Async functions work the same. So does a context manager:
+
+```python
+with rec.call("crm.update", params={"id": 42}) as call:
+    call.result = crm.update(42)
+```
+
+Arguments and results are **committed to, not stored**. A receipt holds a
+salted hash plus a preview with secrets and personal data masked (API keys,
+card numbers, emails and so on). The salts stay in the log's private
+`salts.jsonl`, so you can later prove what a value was:
+`log.reveal(seq, "params", value)`. Or you can destroy the salts, and the value
+becomes unprovable forever while the receipt still verifies:
+`log.shred(predicate)`.
+
+### Check calls before they run
+
+```python
+def decide(target, params):
+    if target.endswith(".delete"):
+        return {"outcome": "deny", "rules": ["no-deletes"], "reason": "agents may not delete"}
+    return {"outcome": "allow", "policy": "v3"}
+
+rec = Recorder(log, agent="support-bot", principal="ops@acme.com", decide=decide)
+```
+
+A refused call never runs. It gets one receipt, and `PolicyDenied` is raised.
+An `escalate` outcome is a denial here, recorded as `policy:no-approver`,
+because nobody in the process can approve it.
+
+The full policy language (budgets, rate limits, escalation to a person, Slack
+approvals, monitor mode) lives in the `vw proxy` MCP proxy and in the
+JavaScript `Recorder` in `@vouchwell/core`. For an agent that uses MCP, wrap
+its servers with the proxy instead. A Python port of the policy engine is
+planned.
+
+### Use it with LangChain or the OpenAI Agents SDK
+
+Wrap the agent's tools once; use the wrapped ones in their place. Each call is
+checked with `decide`, recorded as intent and outcome, and a refused call
+never runs: the model is told why in the tool's reply, as the MCP proxy does,
+instead of the agent crashing.
+
+```python
+from vouchwell.integrations.langchain import record_tools        # pip install "vouchwell[langchain]"
+agent = create_react_agent(model, record_tools(rec, [search, refund]))
+
+from vouchwell.integrations.openai_agents import record_tools    # pip install "vouchwell[openai-agents]"
+agent = Agent(name="Support", tools=record_tools(rec, [lookup_order, refund]))
+```
+
+Hosted OpenAI tools (web search and the like) run on OpenAI's side, so they
+are passed through unrecorded. Both adapters need Python 3.10+, and are tested
+in CI against the real packages.
+
+### Find calls that never finished
+
+Each call's intent is on disk before the tool runs. If the process is killed
+while a call is out, the intent has no outcome, and that is worth knowing:
+
+```python
+from vouchwell import find_unfinished
+
+found = find_unfinished(log.entries)
+for u in found["unfinished"]:
+    print(u["seq"], u["ts"], u["target"], u["principal"])
+```
+
+`inFlight` holds calls from the last five minutes that may still be running,
+and `abandoned` the ones a recorder gave up on while shutting down. `vw verify`
+reports the same list, and `vw verify --fail-on-unfinished` exits 3 when there
+is one.
+
+## Hand over evidence
+
+```python
+import json
+from vouchwell import verify_bundle
+
+log.checkpoint()                                   # sign the current state
+open("evidence.json", "w").write(json.dumps(log.bundle()))
+
+# Anyone can verify it, here or with `vw check evidence.json`:
+verify_bundle(json.load(open("evidence.json")))
+# -> {"ok": True, "issues": [], "checked": 12}
+```
+
+To require an independent witness, pin its key. Get the key from somewhere the
+bundle can't influence:
+
+```python
+verify_bundle(bundle, min_witnesses=1, trusted_witnesses={"pw1…": "<public key>"})
+```
+
+`vw report` (from the npm CLI) turns a log written here into an evidence pack
+for auditors.
+
+## Ship to a hub
+
+```python
+from vouchwell import push
+
+push(log, "https://hub.acme.com", token=os.environ["VOUCHWELL_TOKEN"], name="support-bot")
+```
+
+It sends whatever the hub doesn't have yet, and is safe to call again. Plain
+`http://` is refused unless the hub is on this machine, so the API key never
+crosses a network unencrypted.
+
+## What's here
+
+| Module | |
+| --- | --- |
+| `canonical` | RFC 8785 canonical JSON: UTF-16 key order, ECMAScript number formatting |
+| `merkle` | RFC 6962 trees, inclusion and consistency proofs |
+| `unfinished` | `find_unfinished`: calls sent and never answered |
+| `integrations` | `langchain.record_tools`, `openai_agents.record_tools` |
+| `keys` | Ed25519 identities, canonical base64url |
+| `receipt` | Build, seal, sign and verify receipts |
+| `checkpoint` | Signed tree heads, witness countersignatures |
+| `log` | `ProofLog`, the on-disk log the CLI shares, and `verify_bundle` |
+| `record` | `Recorder`, for Python agents |
+| `remote` | `push` to a hub |
+
+Tested against the RFC 6962 Certificate Transparency reference tree and the
+RFC 8032 Ed25519 vectors, plus byte-level canonicalization parity with the
+JavaScript implementation over hundreds of awkward values.
+
+License: Apache-2.0.

vouchwell-0.5.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vouchwell"
+version = "0.5.0"
+description = "Tamper-evident receipts for AI agent actions. Python SDK, wire-compatible with the vouchwell CLI."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "IdeaboticsAI" }]
+keywords = ["ai-agents", "audit", "transparency-log", "merkle", "ed25519", "eu-ai-act"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security :: Cryptography",
+  "Topic :: System :: Logging",
+]
+# One dependency, for Ed25519: the standard library has none, and signature
+# code is the last thing a security product should write itself.
+dependencies = ["cryptography>=41"]
+
+[project.optional-dependencies]
+# The framework adapters import their framework only when used; these extras
+# install it alongside. Both frameworks need Python 3.10+.
+langchain = ["langchain-core>=0.3"]
+openai-agents = ["openai-agents>=0.2"]
+test = [
+  "pytest>=7",
+  # So CI runs the adapters against the real frameworks where they install.
+  "langchain-core>=0.3; python_version >= '3.10'",
+  "openai-agents>=0.2; python_version >= '3.10'",
+]
+
+[project.urls]
+Homepage = "https://github.com/vouchwell/vouchwell"
+Source = "https://github.com/vouchwell/vouchwell/tree/main/sdk/python"
+Issues = "https://github.com/vouchwell/vouchwell/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+vouchwell = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

vouchwell-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vouchwell-0.5.0/src/vouchwell/__init__.py

@@ -0,0 +1,82 @@
+"""Vouchwell for Python: tamper-evident receipts for what AI agents do.
+
+Wire-compatible with the ``vouchwell`` npm packages: a log written here
+passes ``vw verify``, a bundle exported here passes ``vw check``, and logs
+and bundles written by the JavaScript side open and verify here.
+"""
+
+__version__ = "0.5.0"
+
+from .canonical import canonical_bytes, canonicalize
+from .checkpoint import build_checkpoint, checkpoint_digest, cosign, sign_checkpoint, verify_checkpoint
+from .keys import Identity, generate_identity, identity_from_pem, identity_from_public_key, key_id_for, sign, verify
+from .log import ProofLog, verify_bundle
+from .merkle import (
+    MerkleTree,
+    consistency_proof,
+    inclusion_proof,
+    leaf_hash,
+    merkle_root,
+    node_hash,
+    verify_consistency,
+    verify_inclusion,
+)
+from .record import PolicyDenied, Recorder
+from .redact import redact
+from .receipt import (
+    GENESIS_PREV,
+    build_receipt,
+    entry_hash,
+    open_seal,
+    receipt_digest,
+    seal,
+    sign_receipt,
+    verify_chain,
+    verify_receipt,
+)
+from .remote import HubError, push
+from .unfinished import DEFAULT_GRACE_MS, find_unfinished
+
+__all__ = [
+    "__version__",
+    "DEFAULT_GRACE_MS",
+    "GENESIS_PREV",
+    "HubError",
+    "Identity",
+    "MerkleTree",
+    "PolicyDenied",
+    "ProofLog",
+    "Recorder",
+    "build_checkpoint",
+    "build_receipt",
+    "canonical_bytes",
+    "canonicalize",
+    "checkpoint_digest",
+    "consistency_proof",
+    "cosign",
+    "entry_hash",
+    "find_unfinished",
+    "generate_identity",
+    "identity_from_pem",
+    "identity_from_public_key",
+    "inclusion_proof",
+    "key_id_for",
+    "leaf_hash",
+    "merkle_root",
+    "node_hash",
+    "open_seal",
+    "push",
+    "receipt_digest",
+    "redact",
+    "seal",
+    "sign",
+    "sign_checkpoint",
+    "sign_receipt",
+    "verify",
+    "verify_bundle",
+    "verify_chain",
+    "verify_checkpoint",
+    "verify_consistency",
+    "verify_inclusion",
+    "verify_receipt",
+]

vouchwell-0.5.0/src/vouchwell/canonical.py

@@ -0,0 +1,139 @@
+"""RFC 8785 (JCS) canonical JSON, byte-identical to packages/core/src/canonical.js.
+
+Two implementations must produce the same bytes for the same receipt, or a
+receipt signed in Python would not verify in JavaScript. Three details decide
+that, and each is matched here exactly:
+
+* object keys sort by UTF-16 code unit, not by code point;
+* control characters escape as lowercase ``\\u00xx``, with the short forms for
+  ``\\b \\t \\n \\f \\r`` and ``"`` and ``\\``, and everything else is literal;
+* numbers are written the way ECMAScript's ``Number::toString`` writes them,
+  with ``-0`` as ``0``, and NaN and infinities refused.
+"""
+
+from __future__ import annotations
+
+import math
+from decimal import Decimal
+from typing import Any
+
+__all__ = ["canonicalize", "canonical_bytes"]
+
+_ESCAPES = {
+    0x08: "\\b",
+    0x09: "\\t",
+    0x0A: "\\n",
+    0x0C: "\\f",
+    0x0D: "\\r",
+    0x22: '\\"',
+    0x5C: "\\\\",
+}
+
+#: The largest integer every JSON implementation represents exactly.
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _encode_string(s: str) -> str:
+    out = ['"']
+    for ch in s:
+        cp = ord(ch)
+        esc = _ESCAPES.get(cp)
+        if esc is not None:
+            out.append(esc)
+        elif cp < 0x20:
+            out.append("\\u%04x" % cp)
+        elif 0xD800 <= cp <= 0xDFFF:
+            # A lone surrogate has no UTF-8 form. JavaScript's encoder writes
+            # U+FFFD in its place, so the bytes hashed there are these.
+            out.append("�")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _es_number(x: float) -> str:
+    """ECMAScript Number::toString for a finite, non-zero float.
+
+    Python's ``repr`` already finds the shortest digit string that round-trips,
+    which is what ECMAScript uses too; only the layout differs.
+    """
+    sign = "-" if x < 0 else ""
+    d = Decimal(repr(abs(x)))
+    _, digits, exponent = d.as_tuple()
+    s = "".join(map(str, digits)).rstrip("0")
+    exponent += len(digits) - len(s)  # account for the zeros just stripped
+    k = len(s)
+    n = exponent + k  # the value is 0.s × 10^n
+
+    if k <= n <= 21:
+        body = s + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = s[:n] + "." + s[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + s
+    else:
+        e = n - 1
+        exp = ("+" if e > 0 else "-") + str(abs(e))
+        body = (s if k == 1 else s[0] + "." + s[1:]) + "e" + exp
+    return sign + body
+
+
+def _encode_number(n: Any) -> str:
+    if isinstance(n, bool):  # bool is an int subclass; never a number here
+        raise TypeError("booleans are not numbers")
+    if isinstance(n, int):
+        if abs(n) <= _MAX_SAFE_INTEGER:
+            return str(n)
+        # Beyond 2**53 a JSON number is a double everywhere else, so it is
+        # treated as one here: the same value JavaScript would parse and print.
+        try:
+            n = float(n)
+        except OverflowError:
+            raise TypeError(f"cannot canonicalize {n}: too large for a JSON number") from None
+    if not math.isfinite(n):
+        raise TypeError(f"cannot canonicalize non-finite number: {n}")
+    if n == 0:
+        return "0"
+    if n.is_integer() and abs(n) <= _MAX_SAFE_INTEGER:
+        return str(int(n))
+    # Everything else, including whole numbers above 2**53, which ECMAScript
+    # prints as shortest round-trip digits padded with zeros, not exactly.
+    return _es_number(n)
+
+
+def _sort_key(key: str) -> bytes:
+    # Big-endian UTF-16 bytes compare in the same order as UTF-16 code units,
+    # which is how JavaScript's default sort orders strings.
+    return key.encode("utf-16-be", "surrogatepass")
+
+
+def canonicalize(value: Any) -> str:
+    """The RFC 8785 canonical form of a JSON-compatible value."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, (int, float)):
+        return _encode_number(value)
+    if isinstance(value, str):
+        return _encode_string(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonicalize(v) for v in value) + "]"
+    if isinstance(value, dict):
+        for k in value:
+            if not isinstance(k, str):
+                raise TypeError(f"object keys must be strings, got {type(k).__name__}")
+        parts = [
+            _encode_string(k) + ":" + canonicalize(value[k])
+            for k in sorted(value, key=_sort_key)
+        ]
+        return "{" + ",".join(parts) + "}"
+    raise TypeError(f"cannot canonicalize {type(value).__name__}")
+
+
+def canonical_bytes(value: Any) -> bytes:
+    """Canonical form as UTF-8: what actually gets hashed and signed."""
+    return canonicalize(value).encode("utf-8")