vouchwell 0.5.0__py3-none-any.whl

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/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")

vouchwell/checkpoint.py

@@ -0,0 +1,100 @@
+"""Signed checkpoints: a log's size, root and head at a moment, signed by the
+log and countersigned by witnesses. Mirrors packages/core/src/checkpoint.js."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .hashing import CHECKPOINT_PREFIX, hash_object
+from .keys import Identity, sign, verify
+from .receipt import now_iso
+
+CHECKPOINT_VERSION = 1
+
+
+def build_checkpoint(*, log: str, size: int, root: str, head: str, ts: Optional[str] = None) -> dict:
+    return {"v": CHECKPOINT_VERSION, "log": log, "size": size, "root": root, "head": head, "ts": ts or now_iso()}
+
+
+def checkpoint_digest(body: dict) -> bytes:
+    return hash_object(CHECKPOINT_PREFIX, body)
+
+
+def sign_checkpoint(identity: Identity, body: dict, role: str = "log") -> dict:
+    return {"body": body, "sigs": [{"role": role, "kid": identity.kid, "sig": sign(identity, checkpoint_digest(body))}]}
+
+
+def cosign(checkpoint: dict, witness: Identity) -> dict:
+    """Add (or replace) a witness signature."""
+    sig = sign(witness, checkpoint_digest(checkpoint["body"]))
+    others = [s for s in checkpoint["sigs"] if s.get("kid") != witness.kid]
+    return {"body": checkpoint["body"], "sigs": [*others, {"role": "witness", "kid": witness.kid, "sig": sig, "ts": now_iso()}]}
+
+
+def verify_checkpoint(
+    checkpoint: dict,
+    keyring: dict,
+    min_witnesses: int = 0,
+    trusted_witnesses: Optional[dict] = None,
+) -> dict:
+    """Check a checkpoint's signatures.
+
+    With ``trusted_witnesses`` (kid → public key, obtained from outside the
+    evidence), witness signatures are checked against those keys only, and
+    witnesses not on the list are ignored rather than counted. Without it,
+    witness signatures are checked against ``keyring`` and count only as a
+    claim; ``min_witnesses`` then cannot be met from the evidence itself.
+    """
+    issues: list[str] = []
+    signers: list[str] = []
+    witnesses = 0
+    pinned = isinstance(trusted_witnesses, dict)
+    if not isinstance(checkpoint, dict) or not isinstance(checkpoint.get("body"), dict) or not isinstance(checkpoint.get("sigs"), list):
+        return {"ok": False, "issues": ["malformed checkpoint"], "signers": signers, "witnesses": 0, "pinned": pinned}
+    body = checkpoint["body"]
+    if body.get("v") != CHECKPOINT_VERSION:
+        issues.append(f"unsupported checkpoint version {body.get('v')}")
+    digest = checkpoint_digest(body)
+    has_log_sig = False
+    # Each witness counts once, however often its signature is repeated;
+    # keyed by public key, so one key pinned under two names is one witness.
+    counted: set = set()
+    for s in checkpoint["sigs"]:
+        if not isinstance(s, dict):
+            issues.append("malformed signature entry")
+            continue
+        kid, role = s.get("kid"), s.get("role")
+        if pinned and role == "witness":
+            if kid not in trusted_witnesses:
+                continue
+            if trusted_witnesses[kid] in counted:
+                continue
+            if verify(trusted_witnesses[kid], digest, s.get("sig", "")):
+                counted.add(trusted_witnesses[kid])
+                signers.append(kid)
+                witnesses += 1
+            else:
+                issues.append(f"invalid witness signature from {kid}")
+            continue
+        if pinned and role == "log" and kid in trusted_witnesses:
+            issues.append(f"signature from pinned witness {kid} is labelled as the log's")
+            continue
+        if kid not in keyring:
+            issues.append(f"no public key for signer {kid}")
+            continue
+        if not verify(keyring[kid], digest, s.get("sig", "")):
+            issues.append(f"invalid {role} signature from {kid}")
+            continue
+        if role == "witness":
+            if keyring[kid] in counted:
+                continue
+            counted.add(keyring[kid])
+            witnesses += 1  # unpinned: a claim, not evidence
+        signers.append(kid)
+        if role == "log":
+            has_log_sig = True
+    if not has_log_sig:
+        issues.append("checkpoint carries no valid log signature")
+    if witnesses < min_witnesses:
+        issues.append(f"only {witnesses} valid witness signature(s), policy requires {min_witnesses}")
+    return {"ok": not issues, "issues": issues, "signers": signers, "witnesses": witnesses, "pinned": pinned}

vouchwell/hashing.py

@@ -0,0 +1,72 @@
+"""Domain-separated SHA-256, and the byte encodings the wire format uses.
+
+Mirrors packages/core/src/hash.js. Every hash carries a one-byte domain tag,
+so a leaf can never also be read as an interior node (the second-preimage
+attack RFC 6962 closed), nor a receipt digest as a checkpoint digest.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import re
+from typing import Any
+
+from .canonical import canonical_bytes
+
+LEAF_PREFIX = b"\x00"
+NODE_PREFIX = b"\x01"
+RECEIPT_PREFIX = b"\x02"
+CHECKPOINT_PREFIX = b"\x03"
+
+_HEX = re.compile(r"^[0-9a-f]*$")
+_B64URL = re.compile(r"^[A-Za-z0-9_-]*$")
+
+
+def sha256(*parts: bytes) -> bytes:
+    h = hashlib.sha256()
+    for p in parts:
+        h.update(p)
+    return h.digest()
+
+
+def hash_object(prefix: bytes, value: Any) -> bytes:
+    """SHA-256 of a value's canonical form, under a domain tag."""
+    return sha256(prefix, canonical_bytes(value))
+
+
+def to_hex(b: bytes) -> str:
+    return b.hex()
+
+
+def from_hex(s: str) -> bytes:
+    """Lowercase hex only, as the wire format writes it."""
+    if not isinstance(s, str) or not _HEX.match(s) or len(s) % 2:
+        raise ValueError(f"not lowercase hex: {str(s)[:32]!r}")
+    return bytes.fromhex(s)
+
+
+def b64url(b: bytes) -> str:
+    """Unpadded base64url."""
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+def from_b64url(s: str) -> bytes:
+    """Decode unpadded base64url, accepting only the one canonical spelling.
+
+    A final character with unused bits set (``QB`` where ``QA`` is canonical)
+    decodes to the same bytes, so without this check two strings would name the
+    same key or signature. The JavaScript verifier refuses them; so does this.
+    """
+    if not isinstance(s, str) or not _B64URL.match(s) or len(s) % 4 == 1:
+        raise ValueError("not base64url")
+    raw = base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+    if b64url(raw) != s:
+        raise ValueError("not canonical base64url")
+    return raw
+
+
+def equal_bytes(a: bytes, b: bytes) -> bool:
+    """Constant-time comparison."""
+    return hmac.compare_digest(a, b)

vouchwell/integrations/__init__.py

@@ -0,0 +1,26 @@
+"""Adapters for agent frameworks. Each module imports its framework lazily, so
+``vouchwell`` itself still needs nothing but ``cryptography``.
+
+- ``vouchwell.integrations.langchain``: ``record_tools`` for LangChain /
+  LangGraph tools.
+- ``vouchwell.integrations.openai_agents``: ``record_tools`` for the OpenAI
+  Agents SDK's function tools.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..record import PolicyDenied
+
+
+def refusal(err: PolicyDenied) -> str:
+    """What the model is told when a call is refused: the same words the MCP
+    proxy sends, so an agent behaves the same whichever way it is wrapped."""
+    d: Any = err.decision
+    rules = ", ".join(d.get("rules") or []) or "none"
+    return (
+        f"Blocked by Vouchwell policy. {d.get('reason') or ''}\n"
+        f"Rules: {rules}\n"
+        f"This refusal is recorded as receipt {err.receipt['seq']} in log {err.receipt['log']}."
+    )

vouchwell/integrations/langchain.py

@@ -0,0 +1,93 @@
+"""Record, and check, every call a LangChain or LangGraph agent makes to its tools.
+
+    from vouchwell import ProofLog, Recorder
+    from vouchwell.integrations.langchain import record_tools
+
+    rec = Recorder(ProofLog.open(".vouchwell"), agent="support-bot", principal="ops@acme.com", decide=my_rules)
+    tools = record_tools(rec, [search, refund])       # use these in place of the originals
+    agent = create_react_agent(model, tools)
+
+Each wrapped tool records an intent before it runs and an outcome after,
+exactly as ``Recorder.tool`` does. A call the ``decide`` hook refuses never
+runs, and the model is told why, in the tool's reply, rather than the agent
+crashing: the MCP proxy's behaviour.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from ..record import PolicyDenied, Recorder
+from . import refusal
+
+try:
+    from langchain_core.tools import BaseTool, StructuredTool
+except ImportError as err:  # pragma: no cover - exercised only without the package
+    raise ImportError(
+        "vouchwell.integrations.langchain needs langchain-core: pip install langchain-core"
+    ) from err
+
+
+def record_tools(recorder: Recorder, tools: Sequence[BaseTool]) -> list[BaseTool]:
+    """Wrap each tool; returns new tools with the same names, descriptions and
+    argument schemas. The originals are untouched."""
+    return [record_tool(recorder, t) for t in tools]
+
+
+def record_tool(recorder: Recorder, tool: BaseTool) -> BaseTool:
+    """Wrap one tool. See ``record_tools``."""
+    if not isinstance(tool, BaseTool):
+        raise TypeError(f"record_tool expects a LangChain BaseTool, got {type(tool).__name__}")
+    structured = tool.args_schema is not None
+
+    def params_of(args: tuple, kwargs: dict) -> Any:
+        return dict(kwargs) if structured else (args[0] if args else kwargs.get("tool_input", ""))
+
+    def invoke_input(args: tuple, kwargs: dict) -> Any:
+        return dict(kwargs) if structured else params_of(args, kwargs)
+
+    def run(*args: Any, **kwargs: Any) -> Any:
+        try:
+            with recorder.call(tool.name, params_of(args, kwargs)) as c:
+                c.result = _content(tool.invoke(invoke_input(args, kwargs)))
+                return c.result
+        except PolicyDenied as err:
+            return refusal(err)
+
+    async def arun(*args: Any, **kwargs: Any) -> Any:
+        try:
+            with recorder.call(tool.name, params_of(args, kwargs)) as c:
+                c.result = _content(await tool.ainvoke(invoke_input(args, kwargs)))
+                return c.result
+        except PolicyDenied as err:
+            return refusal(err)
+
+    if structured:
+        return StructuredTool.from_function(
+            func=run,
+            coroutine=arun,
+            name=tool.name,
+            description=tool.description,
+            args_schema=tool.args_schema,
+            return_direct=tool.return_direct,
+            infer_schema=False,
+        )
+
+    def run_text(tool_input: str) -> Any:
+        return run(tool_input)
+
+    async def arun_text(tool_input: str) -> Any:
+        return await arun(tool_input)
+
+    return StructuredTool.from_function(
+        func=run_text,
+        coroutine=arun_text,
+        name=tool.name,
+        description=tool.description,
+        return_direct=tool.return_direct,
+    )
+
+
+def _content(output: Any) -> Any:
+    """A ToolMessage is recorded as what it carries."""
+    return getattr(output, "content", output)

vouchwell/integrations/openai_agents.py

@@ -0,0 +1,55 @@
+"""Record, and check, every call an OpenAI Agents SDK agent makes to its function tools.
+
+    from agents import Agent, function_tool
+    from vouchwell import ProofLog, Recorder
+    from vouchwell.integrations.openai_agents import record_tools
+
+    rec = Recorder(ProofLog.open(".vouchwell"), agent="support-bot", principal="ops@acme.com", decide=my_rules)
+    agent = Agent(name="Support", tools=record_tools(rec, [lookup_order, refund]))
+
+Each wrapped tool records an intent before it runs and an outcome after. A
+call the ``decide`` hook refuses never runs; the model is told why in the
+tool's reply. Tools that are not function tools (hosted tools such as web
+search run on OpenAI's side) are passed through unchanged, since nothing
+here sees them run.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any, Sequence
+
+from ..record import PolicyDenied, Recorder
+from . import refusal
+
+try:
+    from agents import FunctionTool
+except ImportError as err:  # pragma: no cover - exercised only without the package
+    raise ImportError(
+        "vouchwell.integrations.openai_agents needs the OpenAI Agents SDK: pip install openai-agents"
+    ) from err
+
+
+def record_tools(recorder: Recorder, tools: Sequence[Any]) -> list[Any]:
+    """Wrap each function tool; returns new tools. The originals are untouched."""
+    return [record_tool(recorder, t) if isinstance(t, FunctionTool) else t for t in tools]
+
+
+def record_tool(recorder: Recorder, tool: FunctionTool) -> FunctionTool:
+    """Wrap one function tool. See ``record_tools``."""
+    original = tool.on_invoke_tool
+
+    async def on_invoke_tool(ctx: Any, input_json: str) -> Any:
+        try:
+            params: Any = json.loads(input_json) if input_json else {}
+        except ValueError:
+            params = {"raw": input_json}
+        try:
+            with recorder.call(tool.name, params) as c:
+                c.result = await original(ctx, input_json)
+                return c.result
+        except PolicyDenied as err:
+            return refusal(err)
+
+    return dataclasses.replace(tool, on_invoke_tool=on_invoke_tool)

vouchwell/keys.py

@@ -0,0 +1,84 @@
+"""Ed25519 identities, matching packages/core/src/keys.js.
+
+A key id is ``pw1`` plus the first 16 bytes of SHA-256 over the raw 32-byte
+public key, in hex. Public keys and signatures travel as canonical, unpadded
+base64url. Private keys are stored as PKCS#8 PEM, the same file the
+JavaScript side writes, so either can open a log the other created.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from .hashing import b64url, from_b64url, sha256
+
+
+@dataclass(frozen=True)
+class Identity:
+    kid: str
+    public_key: str
+    private_key: Optional[Ed25519PrivateKey] = None
+
+    @property
+    def can_sign(self) -> bool:
+        return self.private_key is not None
+
+
+def key_id_for(raw_public: bytes) -> str:
+    return "pw1" + sha256(raw_public)[:16].hex()
+
+
+def _raw(pub: Ed25519PublicKey) -> bytes:
+    return pub.public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+
+
+def generate_identity() -> tuple[Identity, str]:
+    """A new identity, and its private key as PKCS#8 PEM for storing."""
+    key = Ed25519PrivateKey.generate()
+    raw = _raw(key.public_key())
+    pem = key.private_bytes(
+        serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption()
+    ).decode("ascii")
+    return Identity(key_id_for(raw), b64url(raw), key), pem
+
+
+def identity_from_pem(pem: str) -> Identity:
+    key = serialization.load_pem_private_key(pem.encode("ascii"), password=None)
+    if not isinstance(key, Ed25519PrivateKey):
+        raise TypeError(f"expected an Ed25519 private key, got {type(key).__name__}")
+    raw = _raw(key.public_key())
+    return Identity(key_id_for(raw), b64url(raw), key)
+
+
+def identity_from_public_key(public_key: str) -> Identity:
+    raw = from_b64url(public_key)
+    if len(raw) != 32:
+        raise ValueError(f"Ed25519 public key must be 32 bytes, got {len(raw)}")
+    return Identity(key_id_for(raw), b64url(raw))
+
+
+def sign(identity: Identity, message: bytes) -> str:
+    if identity.private_key is None:
+        raise ValueError(f"identity {identity.kid} is verify-only; cannot sign")
+    return b64url(identity.private_key.sign(message))
+
+
+def verify(public_key: str, message: bytes, signature: str) -> bool:
+    """Never raises: a malformed key or signature is simply not valid."""
+    try:
+        sig = from_b64url(signature)
+        raw = from_b64url(public_key)
+    except (ValueError, TypeError):
+        return False
+    if len(sig) != 64 or len(raw) != 32:
+        return False
+    try:
+        Ed25519PublicKey.from_public_bytes(raw).verify(sig, message)
+        return True
+    except (InvalidSignature, ValueError):
+        return False