trooth-verify 0.4.0__tar.gz

trooth_verify-0.4.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: trooth-verify
+Version: 0.4.0
+Summary: Check a Trooth witness statement yourself: Ed25519 signature, key lifecycle, subject, counts, mapping and manifest digests, offline bundles. The rules of docs/VERIFY.md. Also trooth_guard, the guard for Python agent frameworks.
+Author: Trooth, LLC
+License: Apache-2.0
+Project-URL: Homepage, https://trooth.co
+Project-URL: Source, https://github.com/troothllc/trooth-cli/tree/main/sdk/python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Provides-Extra: models
+Requires-Dist: pydantic>=2.5; extra == "models"
+
+# trooth-verify (Python)
+
+Check a Trooth witness statement yourself, with no trust in Trooth's website or API. A port of `trooth verify` that follows [docs/VERIFY.md](../../docs/VERIFY.md) and passes every case in [tests/vectors](../../tests/vectors).
+
+```
+pip install "git+https://github.com/troothllc/trooth-cli#subdirectory=sdk/python"
+```
+
+```python
+import json
+from trooth_verify import verify_bundle
+
+bundle = json.load(open("trooth.co.bundle.json"))  # written by: trooth verify trooth.co --save-bundle trooth.co.bundle.json
+result = verify_bundle(bundle)
+print(result["verdict"])  # checked, checked_v1, partially_checked, signature_not_trusted or mismatch
+```
+
+`verify_statement(statement, keys, mapping_bytes, manifest, domain)` checks inputs you read yourself. The result has the shape of [schemas/verify-result.schema.json](../../schemas/verify-result.schema.json). `trooth_verify.models` holds Pydantic v2 models generated from [schemas/](../../schemas) (install with the `models` extra).
+
+Bundles written by `trooth` 0.9.0 and later carry the witness statement log's answer; the receipt and any correction are checked too, and a valid correction gives the verdict `superseded` ([docs/LOG.md](../../docs/LOG.md)). Pass your own pinned log key to replace the one a bundle carries.
+
+A `checked` verdict means Trooth's key signed these outcome bytes for this domain, bound to the exact check mapping and evidence manifest. It does not establish the company's identity, an independent time, or that the company is safe, compliant or authorized for anything.
+
+Run the tests from this folder: `python3 -m unittest discover -s tests`. Licensed under the Apache License 2.0.

trooth_verify-0.4.0/README.md

@@ -0,0 +1,24 @@
+# trooth-verify (Python)
+
+Check a Trooth witness statement yourself, with no trust in Trooth's website or API. A port of `trooth verify` that follows [docs/VERIFY.md](../../docs/VERIFY.md) and passes every case in [tests/vectors](../../tests/vectors).
+
+```
+pip install "git+https://github.com/troothllc/trooth-cli#subdirectory=sdk/python"
+```
+
+```python
+import json
+from trooth_verify import verify_bundle
+
+bundle = json.load(open("trooth.co.bundle.json"))  # written by: trooth verify trooth.co --save-bundle trooth.co.bundle.json
+result = verify_bundle(bundle)
+print(result["verdict"])  # checked, checked_v1, partially_checked, signature_not_trusted or mismatch
+```
+
+`verify_statement(statement, keys, mapping_bytes, manifest, domain)` checks inputs you read yourself. The result has the shape of [schemas/verify-result.schema.json](../../schemas/verify-result.schema.json). `trooth_verify.models` holds Pydantic v2 models generated from [schemas/](../../schemas) (install with the `models` extra).
+
+Bundles written by `trooth` 0.9.0 and later carry the witness statement log's answer; the receipt and any correction are checked too, and a valid correction gives the verdict `superseded` ([docs/LOG.md](../../docs/LOG.md)). Pass your own pinned log key to replace the one a bundle carries.
+
+A `checked` verdict means Trooth's key signed these outcome bytes for this domain, bound to the exact check mapping and evidence manifest. It does not establish the company's identity, an independent time, or that the company is safe, compliant or authorized for anything.
+
+Run the tests from this folder: `python3 -m unittest discover -s tests`. Licensed under the Apache License 2.0.

trooth_verify-0.4.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trooth-verify"
+version = "0.4.0"
+description = "Check a Trooth witness statement yourself: Ed25519 signature, key lifecycle, subject, counts, mapping and manifest digests, offline bundles. The rules of docs/VERIFY.md. Also trooth_guard, the guard for Python agent frameworks."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Trooth, LLC" }]
+requires-python = ">=3.9"
+dependencies = ["cryptography>=42"]
+
+[project.optional-dependencies]
+models = ["pydantic>=2.5"]
+
+[project.urls]
+Homepage = "https://trooth.co"
+Source = "https://github.com/troothllc/trooth-cli/tree/main/sdk/python"
+
+[tool.setuptools]
+packages = ["trooth_verify", "trooth_guard"]

trooth_verify-0.4.0/setup.cfg

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

trooth_verify-0.4.0/tests/test_guard.py

@@ -0,0 +1,341 @@
+"""trooth_guard against a fake `trooth guard decide` (fake_trooth.py): no network, no npm,
+no framework package. Framework pieces (interrupt, ToolMessage, Command, contexts) are
+small fakes in the shapes the frameworks document."""
+
+import asyncio
+import json
+import os
+import pathlib
+import sys
+import tempfile
+import unittest
+from types import SimpleNamespace
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+
+from trooth_guard import (  # noqa: E402
+    TROOTH_VERSION,
+    GuardDeny,
+    GuardError,
+    GuardHold,
+    covered,
+    decide,
+    decide_tool_call,
+    describe,
+    error_for,
+    fail_closed,
+    is_approval,
+    trooth_command,
+)
+from trooth_guard import crewai as tg_crewai  # noqa: E402
+from trooth_guard import langchain as tg_langchain  # noqa: E402
+from trooth_guard import langgraph as tg_langgraph  # noqa: E402
+from trooth_guard import openai_agents as tg_openai  # noqa: E402
+
+FAKE = [sys.executable, str(HERE / "fake_trooth.py")]
+KW = {"trooth_cmd": FAKE}
+POLICY = "policy.yaml"  # the fake never opens it
+
+
+class FakeToolMessage:
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+
+class FakeCommand:
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+
+class Core(unittest.TestCase):
+    def test_exit_codes_map_to_decisions(self):
+        self.assertEqual(decide(POLICY, "pay.out", "good.example", **KW)["decision"], "allow")
+        self.assertEqual(decide(POLICY, "pay.out", "unknown.example", **KW)["decision"], "hold")
+        d = decide(POLICY, "pay.out", "bad.example", **KW)
+        self.assertEqual(d["decision"], "deny")
+        self.assertEqual(d["reasons"][0]["code"], "SIGNATURE_INVALID")
+
+    def test_uncovered_tool_decides_nothing(self):
+        self.assertIsNone(decide(POLICY, "uncovered.tool", "bad.example", **KW))
+        ok, out = tg_crewai.task_guardrail(POLICY, "uncovered.tool", extract=lambda o: {"host": "bad.example"}, **KW)("x")
+        self.assertTrue(ok)
+        self.assertEqual(out, "x")
+
+    def test_failures_hold_never_allow(self):
+        for host, why in [("crash.example", "exited 3"), ("garbage.example", "not JSON"), ("mismatch.example", "exit code says hold")]:
+            with self.subTest(host):
+                d = decide(POLICY, "pay.out", host, **KW)
+                self.assertEqual(d["decision"], "hold")
+                self.assertEqual(d["reasons"][0]["code"], "SOURCE_UNREACHABLE")
+                self.assertIn(why, d["reasons"][0]["detail"])
+        d = decide(POLICY, "pay.out", "slow.example", timeout=0.5, **KW)
+        self.assertEqual((d["decision"], d["reasons"][0]["code"]), ("hold", "SOURCE_UNREACHABLE"))
+        d = decide(POLICY, "pay.out", "good.example", trooth_cmd=["/nonexistent/trooth-cli-for-test"])
+        self.assertEqual((d["decision"], d["reasons"][0]["code"]), ("hold", "SOURCE_UNREACHABLE"))
+        self.assertIn("not found", d["reasons"][0]["detail"])
+        d = decide(POLICY, "pay.out", "good.example", trooth_cmd=[sys.executable, "-c", "import sys; print('{\"decision\": \"allow\"}'); sys.exit(0)"])
+        self.assertEqual(d["decision"], "hold", "an allow without reasons is not a Decision")
+
+    def test_command_line(self):
+        with tempfile.TemporaryDirectory() as t:
+            log = os.path.join(t, "argv.jsonl")
+            os.environ["FAKE_TROOTH_LOG"] = log
+            try:
+                decide(POLICY, "pay.out", "good.example", {"amount": 5}, cache=t, offline=True, **KW)
+                decide_tool_call(POLICY, "send_email", {"to": "ap@good.example"}, **KW)
+            finally:
+                del os.environ["FAKE_TROOTH_LOG"]
+            a, b = [json.loads(x) for x in pathlib.Path(log).read_text().splitlines()]
+        self.assertEqual(a, ["guard", "decide", "--policy", POLICY, "--tool", "pay.out", "--host", "good.example", "--args", '{"amount":5}', "--offline", "--cache", t, "--json"])
+        self.assertEqual(b, ["guard", "decide", "--policy", POLICY, "--tool", "send_email", "--args", '{"to":"ap@good.example"}', "--json"])
+
+    def test_trooth_command(self):
+        old = os.environ.pop("TROOTH_CMD", None)
+        try:
+            self.assertEqual(trooth_command(), ["npx", "--yes", f"trooth@{TROOTH_VERSION}"])
+            os.environ["TROOTH_CMD"] = "node /opt/trooth/bin/trooth.mjs"
+            self.assertEqual(trooth_command(), ["node", "/opt/trooth/bin/trooth.mjs"])
+            self.assertEqual(trooth_command(["x", "y"]), ["x", "y"], "the argument wins over the environment")
+            self.assertEqual(decide(POLICY, "pay.out", "good.example", trooth_cmd=" ".join(FAKE))["decision"], "allow")
+            with self.assertRaises(ValueError):
+                trooth_command("")
+        finally:
+            os.environ.pop("TROOTH_CMD", None)
+            if old is not None:
+                os.environ["TROOTH_CMD"] = old
+
+    def test_errors_and_helpers(self):
+        h = error_for(decide(POLICY, "pay.out", "unknown.example", **KW))
+        self.assertIsInstance(h, GuardHold)
+        self.assertIsInstance(h, GuardError)
+        self.assertEqual(h.reasons, ["EVIDENCE_MISSING"])
+        self.assertIsInstance(error_for(decide(POLICY, "pay.out", "bad.example", **KW)), GuardDeny)
+        self.assertIsNone(error_for(decide(POLICY, "pay.out", "good.example", **KW)))
+        self.assertIsInstance(error_for({}), GuardHold)
+        m = describe(decide(POLICY, "pay.out", "unknown.example", **KW))
+        self.assertTrue(m.startswith("Trooth guard: hold the call to pay.out for unknown.example under policy vendor-payments version 3."), m)
+        for v in ("allow", "hold", "deny"):
+            s = describe({"decision": v, "reasons": [], "action": {"tool": "t", "host": "h.example"}})
+            for bad in ("safe", "verified", "trusted", "score", "!", "n't"):
+                self.assertNotIn(bad, s.lower())
+        f = fail_closed("t", None, "x")
+        self.assertEqual((f["decision"], f["subject"]), ("hold", ""))
+        for yes in (True, "approve", {"type": "approve"}, {"approved": True}, {"decisions": [{"type": "approve"}]}):
+            self.assertTrue(is_approval(yes), yes)
+        for no in (None, False, "yes", {"type": "reject"}, {"decisions": []}, {"decisions": [{"type": "approve"}, {"type": "edit"}]}):
+            self.assertFalse(is_approval(no), no)
+        self.assertTrue(covered("pay.out", None))
+        self.assertTrue(covered("mcp__bank__send", ["pay.*", "mcp__bank__*"]))
+        self.assertFalse(covered("search", ["pay.*"]))
+        self.assertFalse(covered(None, ["*"]))
+
+    def test_covered_matches_the_cli_rule(self):
+        # The CLI covers these (bin/lib/guard-policy.mjs toolCovered); with tools= given,
+        # an adapter that said "not covered" would run the call without asking.
+        tools = ["stripe.create_payout", "mcp__bank__*"]
+        for name in ("Stripe.create_payout", "STRIPE.CREATE_PAYOUT", "ｓtripe.create_payout", "stripe.create_payout ", "mcp__BANK__pay", "mcp__bank__x\n"):
+            self.assertTrue(covered(name, tools), repr(name))
+        self.assertFalse(covered("stripe.list_payouts", tools))
+        self.assertFalse(covered("mcp__bank", tools))
+        self.assertTrue(covered("a[b]", ["a[b]"]), "only * is a wildcard; [ ] are literal")
+        self.assertFalse(covered("a.b", ["a?b"]), "? is literal, as in the CLI")
+        hook = tg_crewai.before_tool_call_hook(POLICY, tools=["pay.*"], **KW)
+        self.assertIs(hook(SimpleNamespace(tool_name="PAY.out", tool_input={"url": "bad.example"})), False)
+
+
+class CrewAI(unittest.TestCase):
+    def test_task_guardrail(self):
+        g = tg_crewai.task_guardrail(POLICY, "pay.out", **KW)
+        # CrewAI's Task validator reads the return annotation with typing.get_origin; it must be the real type, not a string.
+        import inspect
+        import typing
+        ann = inspect.signature(g).return_annotation
+        self.assertIs(typing.get_origin(ann), tuple)
+        self.assertEqual(typing.get_args(ann), (bool, typing.Any))
+        out = SimpleNamespace(raw=json.dumps({"url": "https://good.example/pay"}), json_dict=None, pydantic=None)
+        self.assertEqual(g(out), (True, out))
+        ok, msg = g(SimpleNamespace(raw='{"url": "https://bad.example/x"}', json_dict=None, pydantic=None))
+        self.assertFalse(ok)
+        self.assertIn("deny", msg)
+        ok, msg = g(SimpleNamespace(raw="", json_dict={"url": "unknown.example"}, pydantic=None))
+        self.assertFalse(ok)
+        self.assertIn("A person must approve it", msg)
+        asked = []
+        approve = tg_crewai.task_guardrail(POLICY, "pay.out", ask=lambda d: asked.append(d) or True, **KW)
+        self.assertTrue(approve(SimpleNamespace(raw='{"url": "unknown.example"}', json_dict=None, pydantic=None))[0])
+        self.assertTrue(approve(SimpleNamespace(raw='{"url": "bad.example"}', json_dict=None, pydantic=None))[0] is False, "a person cannot approve a deny")
+        self.assertEqual(len(asked), 1)
+        skip = tg_crewai.task_guardrail(POLICY, "pay.out", extract=lambda o: None, **KW)
+        self.assertEqual(skip("x"), (True, "x"))
+        broken = tg_crewai.task_guardrail(POLICY, "pay.out", extract=lambda o: 1 / 0, **KW)
+        self.assertFalse(broken("x")[0])
+
+    def test_before_tool_call_hook(self):
+        seen = []
+        hook = tg_crewai.before_tool_call_hook(POLICY, tools=["pay.*"], on_decision=lambda d: seen.append(d["decision"]), **KW)
+        ctx = lambda name, inp: SimpleNamespace(tool_name=name, tool_input=inp)  # noqa: E731
+        self.assertIsNone(hook(ctx("pay.out", {"url": "good.example"})))
+        self.assertIs(hook(ctx("pay.out", {"url": "bad.example"})), False)
+        self.assertIs(hook(ctx("pay.out", {"url": "unknown.example"})), False)
+        self.assertIs(hook(ctx("pay.out", {"url": "crash.example"})), False)
+        self.assertIsNone(hook(ctx("search", {"q": "x"})), "an uncovered tool runs without asking")
+        self.assertEqual(seen, ["allow", "deny", "hold", "hold"])
+        ask = tg_crewai.before_tool_call_hook(POLICY, ask=lambda d: True, **KW)
+        self.assertIsNone(ask(ctx("pay.out", {"url": "unknown.example"})))
+        self.assertIs(ask(ctx("pay.out", {"url": "bad.example"})), False)
+
+
+class LangGraph(unittest.TestCase):
+    def state(self, *calls):
+        return {"messages": [{"type": "human"}, SimpleNamespace(tool_calls=list(calls))]}
+
+    def test_allow_and_skip(self):
+        node = tg_langgraph.guard_node(POLICY, interrupt=lambda p: self.fail("no interrupt"), tools=["pay.*"], **KW)
+        self.assertEqual(node(self.state({"name": "pay.out", "args": {"url": "good.example"}, "id": "a"}, {"name": "search", "args": {}, "id": "b"})), {})
+        self.assertEqual(node({"messages": []}), {})
+        keyed = tg_langgraph.guard_node(POLICY, interrupt=lambda p: None, decisions_key="trooth", **KW)
+        u = keyed(self.state({"name": "pay.out", "args": {"url": "good.example"}, "id": "a"}))
+        self.assertEqual(u["trooth"][0]["decision"]["decision"], "allow")
+        with self.assertRaises(TypeError):
+            tg_langgraph.guard_node(POLICY, interrupt=lambda p: None, deny_goto="x")
+        # Routing without tools_goto is refused: a static edge would also run the tools after a routed deny.
+        with self.assertRaises(TypeError):
+            tg_langgraph.guard_node(POLICY, interrupt=lambda p: None, command=FakeCommand, deny_goto="x")
+        routed = tg_langgraph.guard_node(POLICY, interrupt=lambda p: self.fail("no interrupt"), command=FakeCommand, deny_goto="x", tools_goto="tools", **KW)
+        self.assertEqual(routed(self.state({"name": "pay.out", "args": {"url": "good.example"}, "id": "a"})).goto, "tools")
+
+    def test_hold_interrupts_once(self):
+        payloads = []
+        s = self.state({"name": "pay.out", "args": {"url": "unknown.example"}, "id": "a"}, {"name": "send_email", "args": {"to": "x@unknown.example"}, "id": "b"}, {"name": "pay.out", "args": {"url": "good.example"}, "id": "c"})
+        node = lambda resume, **kw: tg_langgraph.guard_node(POLICY, interrupt=lambda p: payloads.append(p) or resume, **kw, **KW)  # noqa: E731
+        self.assertEqual(node({"type": "approve"})(s), {})
+        self.assertEqual(len(payloads), 1)
+        self.assertEqual(payloads[0]["type"], "trooth_guard_hold")
+        self.assertEqual([x["tool_call"]["id"] for x in payloads[0]["held"]], ["a", "b"])
+        with self.assertRaises(GuardHold):
+            node({"type": "reject"})(s)
+        c = node(False, command=FakeCommand, hold_goto="review", tools_goto="tools")(s)
+        self.assertEqual(c.goto, "review")
+
+    def test_deny_before_interrupt(self):
+        s = self.state({"name": "pay.out", "args": {"url": "unknown.example"}, "id": "a"}, {"name": "pay.out", "args": {"url": "bad.example"}, "id": "b"})
+        asked = []
+        with self.assertRaises(GuardDeny):
+            tg_langgraph.guard_node(POLICY, interrupt=lambda p: asked.append(p), **KW)(s)
+        c = tg_langgraph.guard_node(POLICY, interrupt=lambda p: asked.append(p), command=FakeCommand, deny_goto="blocked", tools_goto="tools", decisions_key="d", **KW)(s)
+        self.assertEqual((c.goto, len(c.update["d"])), ("blocked", 2))
+        self.assertEqual(asked, [])
+
+
+class LangChain(unittest.TestCase):
+    def req(self, name, args, id_="tc1"):
+        return SimpleNamespace(tool_call={"name": name, "args": args, "id": id_}, tool=None, state={}, runtime=None)
+
+    def test_allow_deny_hold(self):
+        ran = []
+        handler = lambda r: ran.append(r.tool_call["name"]) or "ran"  # noqa: E731
+        w = tg_langchain.tool_call_wrapper(POLICY, tools=["pay.*"], **KW)
+        self.assertEqual(w(self.req("pay.out", {"url": "good.example"}), handler), "ran")
+        self.assertEqual(w(self.req("search", {}), handler), "ran")
+        with self.assertRaises(GuardDeny):
+            w(self.req("pay.out", {"url": "bad.example"}), handler)
+        with self.assertRaises(GuardHold):
+            w(self.req("pay.out", {"url": "unknown.example"}), handler)
+        m = tg_langchain.tool_call_wrapper(POLICY, tool_message=FakeToolMessage, on_deny="message", **KW)
+        msg = m(self.req("pay.out", {"url": "bad.example"}, "id9"), handler)
+        self.assertEqual((msg.status, msg.tool_call_id, msg.name), ("error", "id9", "pay.out"))
+        self.assertIn("SIGNATURE_INVALID", msg.content)
+        msg = m(self.req("pay.out", {"url": "unknown.example"}), handler)
+        self.assertIn("A person must approve it", msg.content)
+        self.assertEqual(ran, ["pay.out", "search"])
+
+    def test_interrupt(self):
+        ran = []
+        handler = lambda r: ran.append(1) or "ran"  # noqa: E731
+        payloads = []
+        mk = lambda resume, **kw: tg_langchain.tool_call_wrapper(POLICY, interrupt=lambda p: payloads.append(p) or resume, **kw, **KW)  # noqa: E731
+        self.assertEqual(mk({"type": "approve"})(self.req("pay.out", {"url": "unknown.example"}), handler), "ran")
+        self.assertEqual(payloads[0]["tool_call"], {"name": "pay.out", "id": "tc1"})
+        with self.assertRaises(GuardHold):
+            mk({"type": "reject"})(self.req("pay.out", {"url": "unknown.example"}), handler)
+        msg = mk(None, tool_message=FakeToolMessage)(self.req("pay.out", {"url": "unknown.example"}), handler)
+        self.assertIn("did not approve", msg.content)
+        self.assertEqual(ran, [1])
+
+        class Pause(Exception):
+            pass
+
+        def pause(_p):
+            raise Pause()
+
+        with self.assertRaises(Pause):
+            tg_langchain.tool_call_wrapper(POLICY, interrupt=pause, **KW)(self.req("pay.out", {"url": "unknown.example"}), handler)
+        for bad in ({"on_hold": "interrupt"}, {"on_deny": "message"}, {"on_hold": "allow"}):
+            with self.assertRaises(ValueError):
+                tg_langchain.tool_call_wrapper(POLICY, **bad)
+
+    def test_async(self):
+        async def handler(r):
+            return "ran"
+
+        w = tg_langchain.atool_call_wrapper(POLICY, **KW)
+        self.assertEqual(asyncio.run(w(self.req("pay.out", {"url": "good.example"}), handler)), "ran")
+        with self.assertRaises(GuardHold):
+            asyncio.run(w(self.req("pay.out", {"url": "crash.example"}), handler))
+
+
+class OpenAIAgents(unittest.TestCase):
+    def data(self, name, args, call_id="c1", approved=None):
+        ctx = SimpleNamespace(tool_name=name, tool_call_id=call_id, tool_arguments=json.dumps(args), is_tool_approved=lambda t, c: (approved or {}).get((t, c)))
+        return SimpleNamespace(context=ctx, agent=None)
+
+    def run_g(self, g, d):
+        return asyncio.run(g(d))
+
+    def test_guardrail(self):
+        g = tg_openai.tool_input_guardrail_function(POLICY, tools=["pay.*"], output_factory=tg_openai._Output, **KW)
+        self.assertEqual(self.run_g(g, self.data("pay.out", {"url": "good.example"})).behavior, {"type": "allow"})
+        self.assertEqual(self.run_g(g, self.data("pay.out", {"url": "bad.example"})).behavior, {"type": "raise_exception"})
+        r = self.run_g(g, self.data("pay.out", {"url": "unknown.example"}))
+        self.assertEqual(r.behavior["type"], "reject_content")
+        self.assertIn("A person must approve it", r.behavior["message"])
+        self.assertEqual(r.output_info["decision"]["decision"], "hold")
+        u = self.run_g(g, self.data("search", {"q": 1}))
+        self.assertEqual((u.behavior, u.output_info), ({"type": "allow"}, {"covered": False}))
+        f = self.run_g(g, self.data("pay.out", {"url": "crash.example"}))
+        self.assertEqual(f.behavior["type"], "reject_content")
+        raise_on_hold = tg_openai.tool_input_guardrail_function(POLICY, on_hold="raise", output_factory=tg_openai._Output, **KW)
+        self.assertEqual(self.run_g(raise_on_hold, self.data("pay.out", {"url": "unknown.example"})).behavior, {"type": "raise_exception"})
+        with self.assertRaises(ValueError):
+            tg_openai.tool_input_guardrail_function(POLICY, on_hold="allow")
+
+    def test_approved_hold_runs_but_approved_deny_does_not(self):
+        g = tg_openai.tool_input_guardrail_function(POLICY, output_factory=tg_openai._Output, **KW)
+        ok = {("pay.out", "c9"): True}
+        r = self.run_g(g, self.data("pay.out", {"url": "unknown.example"}, "c9", ok))
+        self.assertEqual(r.behavior, {"type": "allow"})
+        self.assertTrue(r.output_info["approved_by_person"])
+        self.assertEqual(self.run_g(g, self.data("pay.out", {"url": "unknown.example"}, "c8", ok)).behavior["type"], "reject_content")
+        self.assertEqual(self.run_g(g, self.data("pay.out", {"url": "bad.example"}, "c9", ok)).behavior, {"type": "raise_exception"})
+
+    def test_needs_approval(self):
+        na = tg_openai.needs_approval(POLICY, "pay.out", **KW)
+        self.assertTrue(asyncio.run(na(None, {"url": "unknown.example"}, "c1")))
+        self.assertFalse(asyncio.run(na(None, {"url": "good.example"}, "c2")))
+        self.assertFalse(asyncio.run(na(None, {"url": "bad.example"}, "c3")))
+        self.assertTrue(asyncio.run(na(None, {"url": "crash.example"}, "c4")))
+        # A tool the policy does not cover: decide() returns None, so no approval is needed and nothing is decided.
+        seen = []
+        uncovered = tg_openai.needs_approval(POLICY, "uncovered.tool", on_decision=seen.append, **KW)
+        self.assertFalse(asyncio.run(uncovered(None, {"url": "bad.example"}, "c5")))
+        self.assertEqual(seen, [])
+
+    def test_duck_output_matches_sdk_names(self):
+        self.assertEqual(tg_openai._Output.allow().behavior, {"type": "allow"})
+        self.assertEqual(tg_openai._Output.reject_content("m").behavior, {"type": "reject_content", "message": "m"})
+        self.assertEqual(tg_openai._Output.raise_exception({"x": 1}).output_info, {"x": 1})
+
+
+if __name__ == "__main__":
+    unittest.main()

trooth_verify-0.4.0/tests/test_vectors.py

@@ -0,0 +1,96 @@
+"""Every vector and bundle in tests/vectors/ of trooth-cli, through this package."""
+
+import json
+import pathlib
+import unittest
+
+from trooth_verify import BundleError, canonicalize, is_canonical, statement_id, verify_bundle, verify_statement
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+VEC = ROOT / "tests" / "vectors"
+
+
+class Vectors(unittest.TestCase):
+    def test_vectors(self):
+        doc = json.loads((VEC / "vectors.json").read_text("utf-8"))
+        mapping = (VEC / doc["mapping_file"]).read_bytes()
+        other = (VEC / doc["other_mapping_file"]).read_bytes()
+        self.assertGreaterEqual(len(doc["vectors"]), 27)
+        for v in doc["vectors"]:
+            with self.subTest(v["name"]):
+                mb = mapping if v["mapping"] is True else other if v["mapping"] == "other" else None
+                r = verify_statement(v["statement"], v["keys"], mb, v["manifest"], v["domain"])
+                self.assertEqual(r["verdict"], v["expect"]["verdict"], v["note"])
+                self.assertEqual(r["signature"], v["expect"]["signature"], v["note"])
+
+    def test_bundles(self):
+        for b in json.loads((VEC / "bundles.json").read_text("utf-8"))["bundles"]:
+            with self.subTest(b["name"]):
+                if "error" in b["expect"]:
+                    with self.assertRaises(BundleError):
+                        verify_bundle(b["bundle"], b.get("domain"))
+                    continue
+                r = verify_bundle(b["bundle"], b.get("domain"))
+                self.assertEqual(r["verdict"], b["expect"]["verdict"], b["note"])
+                self.assertEqual(r["signature"], b["expect"]["signature"], b["note"])
+
+    def test_real_trooth_bundle(self):
+        b = json.loads((ROOT / "tests" / "fixtures" / "bundles" / "trooth.co-2026-10-06.bundle.json").read_text("utf-8"))
+        r = verify_bundle(b)
+        self.assertEqual(r["verdict"], "checked")
+        self.assertEqual(r["statement_id"], statement_id(b["statement"]["payload"]))
+
+    def test_canonical_v3_payload_is_reproduced(self):
+        doc = json.loads((VEC / "vectors.json").read_text("utf-8"))
+        p = next(v for v in doc["vectors"] if v["name"] == "valid-v3")["statement"]["payload"]
+        self.assertTrue(is_canonical(p))
+        self.assertEqual(canonicalize(json.loads(p)), p)
+        self.assertEqual(canonicalize({"\U0001F600": 1, "דּ": 2, "b": 0}), '{"b":0,"\U0001F600":1,"דּ":2}')
+
+
+class Log(unittest.TestCase):
+    def test_log_cases(self):
+        from trooth_verify import verify_statement
+        doc = json.loads((VEC / "log.json").read_text("utf-8"))
+        v = json.loads((VEC / "vectors.json").read_text("utf-8"))
+        mapping = (VEC / v["mapping_file"]).read_bytes()
+        for c in doc["cases"]:
+            with self.subTest(c["name"]):
+                r = verify_statement(c["statement"], c["keys"], mapping, c["manifest"], c["domain"], c["log"])
+                self.assertEqual(r["verdict"], c["expect"]["verdict"], c["note"])
+                self.assertEqual(r["log"]["status"] if r.get("log") else None, c["expect"]["log"], c["note"])
+
+    def test_consistency(self):
+        import base64
+        from trooth_verify import verify_consistency
+        doc = json.loads((VEC / "log.json").read_text("utf-8"))
+        for c in doc["consistency"]:
+            with self.subTest(c["name"]):
+                d = lambda s: base64.b64decode(s)
+                self.assertEqual(verify_consistency(c["first"], c["second"], d(c["first_root"]), d(c["second_root"]), [d(p) for p in c["proof"]]), c["expect"])
+
+    def test_checkpoints(self):
+        from trooth_verify import open_checkpoint
+        doc = json.loads((VEC / "log.json").read_text("utf-8"))
+        self.assertEqual(open_checkpoint(doc["checkpoints"]["5"], doc["vkey"])["size"], 5)
+        with self.assertRaises(ValueError):
+            open_checkpoint(doc["checkpoints"]["5"], doc["impostor_vkey"])
+
+
+class Models(unittest.TestCase):
+    def test_models_load_vectors(self):
+        try:
+            from trooth_verify import models
+        except ImportError:
+            self.skipTest("pydantic is not installed (pip install trooth-verify[models])")
+        doc = json.loads((VEC / "vectors.json").read_text("utf-8"))
+        for name, cls in (("valid-v2", models.WitnessPayloadV2), ("valid-v3", models.WitnessPayloadV3), ("valid-v1", models.WitnessPayloadV1)):
+            v = next(x for x in doc["vectors"] if x["name"] == name)
+            cls.model_validate_json(v["statement"]["payload"])
+            models.WitnessStatement.model_validate(v["statement"])
+        b = json.loads((VEC / "bundles.json").read_text("utf-8"))["bundles"][0]["bundle"]
+        models.VerificationBundle.model_validate(b)
+
+
+if __name__ == "__main__":
+    unittest.main()

trooth_verify-0.4.0/trooth_guard/__init__.py

@@ -0,0 +1,53 @@
+"""trooth_guard: the Trooth guard for Python agent frameworks.
+
+    from trooth_guard import decide
+    d = decide("policy.yaml", "stripe.create_payout", host="api.example.com")
+    d["decision"]  # "allow", "hold" or "deny"
+
+One decision implementation: this package runs `trooth guard decide --json`
+(the npm package `trooth`) in a subprocess and parses its Decision. It needs
+no Python package. Adapters, each importing nothing from its framework:
+trooth_guard.crewai, trooth_guard.langgraph, trooth_guard.langchain and
+trooth_guard.openai_agents. Licensed under the Apache License 2.0.
+
+The guard answers allow, hold or deny about an action under the caller's
+policy. It never labels a company.
+"""
+
+from .core import (
+    EXIT_ALLOW,
+    EXIT_DENY,
+    EXIT_HOLD,
+    TROOTH_VERSION,
+    GuardDeny,
+    GuardError,
+    GuardHold,
+    decide,
+    decide_tool_call,
+    describe,
+    covered,
+    error_for,
+    fail_closed,
+    is_approval,
+    reason_codes,
+    trooth_command,
+)
+
+__all__ = [
+    "EXIT_ALLOW",
+    "EXIT_DENY",
+    "EXIT_HOLD",
+    "TROOTH_VERSION",
+    "GuardDeny",
+    "GuardError",
+    "GuardHold",
+    "decide",
+    "decide_tool_call",
+    "describe",
+    "covered",
+    "error_for",
+    "fail_closed",
+    "is_approval",
+    "reason_codes",
+    "trooth_command",
+]