vouch-protocol 2.1.0__tar.gz → 2.2.1__tar.gz

{vouch_protocol-2.1.0/vouch_protocol.egg-info → vouch_protocol-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vouch-protocol
-Version: 2.1.0
+Version: 2.2.1
 Summary: The Identity & Reputation Standard for AI Agents
 Author-email: Vouch Protocol Contributors <hello@vouch-protocol.com>
 License: Apache License 2.0
@@ -224,7 +224,7 @@ Requires-Dist: python-dateutil
 Requires-Dist: cryptography
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: httpx>=0.24.0
-Requires-Dist: pqcrypto>=0.4.0
+Requires-Dist: pqcrypto<2.0.0,>=0.4.0
 Provides-Extra: langchain
 Requires-Dist: langchain>=0.1.0; extra == "langchain"
 Provides-Extra: crewai
@@ -387,7 +387,7 @@ Vouch is not one tool, it is a set of them. Here is the whole map.
 - **Continuous trust** heartbeats and session vouchers, so trust is a live signal that has to be renewed, not a badge that is issued once and trusted forever.
 - **Authority freshness** a signed authority state with a counter that only goes up, so a state change (a fraud signal, a suspended mandate) collapses the acceptable freshness window to now for a high-consequence action, even when time-decay trust still passes. See [docs/authority-freshness.md](docs/authority-freshness.md).
 
-### Framework integrations (new in v1.6.2)
+### Framework integrations
 Standalone packages that drop Vouch into the agent framework you already use. Each one issues a verifiable credential for a tool call, with optional delegation back to a human principal.
 - **`vouch-langchain`** a LangChain tool that signs each tool call before it leaves the agent.
 - **`vouch-langgraph`** signs LangGraph tool calls and graph nodes, so a signed trail runs across the whole graph.
@@ -397,7 +397,7 @@ Standalone packages that drop Vouch into the agent framework you already use. Ea
 - **`vouch-mlflow`** signs an MLflow model artifact at registration time, bound to a content digest so any change to the weights breaks the signature.
 - **`vouch-safetensors`** embeds a credential in a `.safetensors` header, complementary to OpenSSF Model Signing, so a model carries who produced it.
 
-The standalone **`vouch-mcp`** package above ships alongside these in v1.6.2.
+The standalone **`vouch-mcp`** package above ships alongside these.
 
 ### SDKs, in the language you use
 Python, TypeScript, and Go are the full reference implementations. A Rust core with idiomatic Swift, JVM (Java and Kotlin), .NET, and C wrappers shares one codebase, so every language produces byte-identical output, verified against shared test vectors. A WebAssembly build is included for the browser and the edge. See the table further down for status per language.

{vouch_protocol-2.1.0 → vouch_protocol-2.2.1}/README.md

@@ -97,7 +97,7 @@ Vouch is not one tool, it is a set of them. Here is the whole map.
 - **Continuous trust** heartbeats and session vouchers, so trust is a live signal that has to be renewed, not a badge that is issued once and trusted forever.
 - **Authority freshness** a signed authority state with a counter that only goes up, so a state change (a fraud signal, a suspended mandate) collapses the acceptable freshness window to now for a high-consequence action, even when time-decay trust still passes. See [docs/authority-freshness.md](docs/authority-freshness.md).
 
-### Framework integrations (new in v1.6.2)
+### Framework integrations
 Standalone packages that drop Vouch into the agent framework you already use. Each one issues a verifiable credential for a tool call, with optional delegation back to a human principal.
 - **`vouch-langchain`** a LangChain tool that signs each tool call before it leaves the agent.
 - **`vouch-langgraph`** signs LangGraph tool calls and graph nodes, so a signed trail runs across the whole graph.
@@ -107,7 +107,7 @@ Standalone packages that drop Vouch into the agent framework you already use. Ea
 - **`vouch-mlflow`** signs an MLflow model artifact at registration time, bound to a content digest so any change to the weights breaks the signature.
 - **`vouch-safetensors`** embeds a credential in a `.safetensors` header, complementary to OpenSSF Model Signing, so a model carries who produced it.
 
-The standalone **`vouch-mcp`** package above ships alongside these in v1.6.2.
+The standalone **`vouch-mcp`** package above ships alongside these.
 
 ### SDKs, in the language you use
 Python, TypeScript, and Go are the full reference implementations. A Rust core with idiomatic Swift, JVM (Java and Kotlin), .NET, and C wrappers shares one codebase, so every language produces byte-identical output, verified against shared test vectors. A WebAssembly build is included for the browser and the edge. See the table further down for status per language.

{vouch_protocol-2.1.0 → vouch_protocol-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vouch-protocol"
-version = "2.1.0"
+version = "2.2.1"
 description = "The Identity & Reputation Standard for AI Agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -37,7 +37,11 @@ dependencies = [
     # credential. Bundled by default: pqcrypto ships
     # prebuilt wheels for all mainstream platforms (~80 KB, no compiler needed)
     # and the PQ story is core to Vouch, so we do not gate it behind an extra.
-    "pqcrypto>=0.4.0",
+    # 0.4.x and 1.0.x are both supported: they differ in the ML-DSA-44 entry
+    # point names and in how verify() reports a verdict, and
+    # vouch/data_integrity_hybrid.py handles both. The major version is capped
+    # so a future release cannot change those contracts underneath a verifier.
+    "pqcrypto>=0.4.0,<2.0.0",
 ]
 
 [project.optional-dependencies]

{vouch_protocol-2.1.0 → vouch_protocol-2.2.1}/tests/test_hybrid.py

@@ -502,7 +502,9 @@ def test_composite_proof_value_is_over_the_legacy_digest():
     digest = data_integrity.legacy_proof_digest(cred, unsigned)
     assert len(digest) == 32
     ed_pub.verify(combined[: data_integrity_hybrid.ED25519_SIGNATURE_SIZE], digest)
-    assert pqcrypto.verify(ml_pub, digest, combined[data_integrity_hybrid.ED25519_SIGNATURE_SIZE :])
+    assert data_integrity_hybrid._mldsa44_verify(
+        pqcrypto, ml_pub, digest, combined[data_integrity_hybrid.ED25519_SIGNATURE_SIZE :]
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -599,3 +601,97 @@ def test_verify_dual_rejects_a_set_missing_the_classical_proof():
         )
         is False
     )
+
+
+# ---------------------------------------------------------------------------
+# pqcrypto API contracts: 0.4.x and 1.0.0 differ in how they report a verdict
+# ---------------------------------------------------------------------------
+
+
+class _BoolVerify:
+    """The pqcrypto 0.4.x contract: verify() returns a bool."""
+
+    def __init__(self, verdict):
+        self.verdict = verdict
+
+    def verify(self, public_key, message, signature):
+        return self.verdict
+
+
+class _RaisingVerify:
+    """The pqcrypto 1.0.0 contract: verify() returns None on success and
+    raises on failure."""
+
+    def __init__(self, error=None):
+        self.error = error
+
+    def verify(self, public_key, message, signature):
+        if self.error is not None:
+            raise self.error
+        return None
+
+
+def test_verify_reads_the_bool_returning_contract():
+    assert data_integrity_hybrid._mldsa44_verify(_BoolVerify(True), b"pub", b"msg", b"sig") is True
+    assert (
+        data_integrity_hybrid._mldsa44_verify(_BoolVerify(False), b"pub", b"msg", b"sig") is False
+    )
+
+
+def test_verify_reads_the_raising_contract():
+    """A None return means success under pqcrypto 1.0.0. Reading it as a bool
+    would reject every valid post-quantum proof."""
+    assert data_integrity_hybrid._mldsa44_verify(_RaisingVerify(), b"pub", b"msg", b"sig") is True
+
+
+def test_verify_rejects_when_the_library_raises():
+    for error in (
+        ValueError("signature verification failed"),
+        RuntimeError("truncated input"),
+        TypeError("wrong key type"),
+    ):
+        assert (
+            data_integrity_hybrid._mldsa44_verify(_RaisingVerify(error), b"pub", b"msg", b"sig")
+            is False
+        )
+
+
+def test_keygen_accepts_either_entry_point_name():
+    """pqcrypto 1.0.0 renamed generate_keypair() to keygen()."""
+
+    class _Keygen:
+        def keygen(self):
+            return b"pub-new", b"sec-new"
+
+    class _GenerateKeypair:
+        def generate_keypair(self):
+            return b"pub-old", b"sec-old"
+
+    class _Neither:
+        pass
+
+    assert data_integrity_hybrid._mldsa44_keygen(_Keygen()) == (b"pub-new", b"sec-new")
+    assert data_integrity_hybrid._mldsa44_keygen(_GenerateKeypair()) == (b"pub-old", b"sec-old")
+    with pytest.raises(RuntimeError):
+        data_integrity_hybrid._mldsa44_keygen(_Neither())
+
+
+def test_a_tampered_signature_is_rejected_under_the_installed_library():
+    """End-to-end against whichever pqcrypto is actually installed: a real
+    signature verifies and a flipped byte does not."""
+    ml_pub, ml_sec = data_integrity_hybrid.generate_mldsa44_keypair()
+    message = b"vouch protocol ml-dsa-44 contract check"
+    signature = pqcrypto.sign(ml_sec, message)
+
+    assert data_integrity_hybrid._mldsa44_verify(pqcrypto, ml_pub, message, signature) is True
+
+    tampered = bytearray(signature)
+    tampered[0] ^= 0x01
+    assert (
+        data_integrity_hybrid._mldsa44_verify(pqcrypto, ml_pub, message, bytes(tampered)) is False
+    )
+    assert (
+        data_integrity_hybrid._mldsa44_verify(pqcrypto, ml_pub, b"other message", signature)
+        is False
+    )
+    assert data_integrity_hybrid._mldsa44_verify(pqcrypto, ml_pub, message, b"short") is False

vouch_protocol-2.2.1/tests/test_mcp_server_shield.py

@@ -0,0 +1,139 @@
+"""vouch-mcp consults Shield before it signs.
+
+A credential is a statement that this agent authorised an action. If policy says
+it may not, there is nothing to attest, so no credential is issued. That makes
+the signer the first of two refusal points, the second being the tool server
+that receives the credential.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+
+import pytest
+
+pytest.importorskip("mcp", reason="MCP SDK not installed")
+
+from vouch import multikey  # noqa: E402
+from vouch.integrations.mcp import server as notary  # noqa: E402
+from vouch.autosign import reset_default_signer  # noqa: E402
+from vouch.keys import generate_identity  # noqa: E402
+
+TARGET = "files"
+
+
+@pytest.fixture
+def notary_env(tmp_path, monkeypatch):
+    keypair = generate_identity()
+    raw = base64.urlsafe_b64decode(json.loads(keypair.public_key_jwk)["x"] + "==")
+    did = "did:key:" + multikey.encode_ed25519_public(raw)
+
+    rules = tmp_path / "rules.json"
+    rules.write_text(
+        json.dumps(
+            {
+                "version": 2,
+                "rules": [
+                    {
+                        "did": did,
+                        "allow": [
+                            {
+                                "id": "read-reports",
+                                "action": "read_file",
+                                "target": TARGET,
+                                "resource": "reports/**",
+                            }
+                        ],
+                    }
+                ],
+                "deny_default": True,
+            }
+        )
+    )
+
+    monkeypatch.setenv("VOUCH_DID", did)
+    monkeypatch.setenv("VOUCH_PRIVATE_KEY", keypair.private_key_jwk)
+    monkeypatch.setattr(notary, "_RULES_PATH", str(rules))
+    notary._shield_cache.clear()
+    # resolve_signer() memoises the process-wide default signer, so a stale one
+    # from an earlier test would sign under the wrong DID.
+    reset_default_signer()
+    yield {"did": did}
+    notary._shield_cache.clear()
+    reset_default_signer()
+
+
+def test_sign_issues_a_credential_for_a_permitted_intent(notary_env):
+    out = json.loads(notary.sign(action="read_file", target=TARGET, resource="reports/q3.txt"))
+
+    assert out.get("error") is None
+    assert out["credentialSubject"]["intent"]["resource"] == "reports/q3.txt"
+    assert out["proof"]["cryptosuite"] == "eddsa-jcs-2022"
+
+
+def test_sign_refuses_a_denied_action_with_a_structured_refusal(notary_env):
+    """Nothing to present: the notary will not stamp it."""
+    out = json.loads(notary.sign(action="delete_file", target=TARGET, resource="reports/q3.txt"))
+
+    assert out["error"] == "refused"
+    assert out["reason"] == "no matching rule"
+    assert out["action"] == "delete_file"
+    assert "proof" not in out
+
+
+def test_sign_refuses_a_resource_outside_scope(notary_env):
+    out = json.loads(notary.sign(action="read_file", target=TARGET, resource="secrets/keys.txt"))
+
+    assert out["error"] == "refused"
+    assert out["reason"] == "resource outside scope"
+
+
+def test_sign_refuses_traversal(notary_env):
+    out = json.loads(
+        notary.sign(action="read_file", target=TARGET, resource="reports/../secrets/keys.txt")
+    )
+    assert out["error"] == "refused"
+    assert out["reason"] == "resource outside scope"
+
+
+def test_sign_refuses_everything_without_a_rules_file(monkeypatch, tmp_path):
+    keypair = generate_identity()
+    raw = base64.urlsafe_b64decode(json.loads(keypair.public_key_jwk)["x"] + "==")
+    did = "did:key:" + multikey.encode_ed25519_public(raw)
+    monkeypatch.setenv("VOUCH_DID", did)
+    monkeypatch.setenv("VOUCH_PRIVATE_KEY", keypair.private_key_jwk)
+    monkeypatch.setattr(notary, "_RULES_PATH", None)
+    notary._shield_cache.clear()
+    reset_default_signer()
+
+    out = json.loads(notary.sign(action="read_file", target=TARGET, resource="reports/q3.txt"))
+    assert out["error"] == "refused"
+    assert out["reason"] == "unknown did"
+    notary._shield_cache.clear()
+    reset_default_signer()
+
+
+def test_check_action_reports_the_decision_and_its_reason(notary_env):
+    did = notary_env["did"]
+
+    allowed = notary.check_action(
+        action="read_file", target=TARGET, resource="reports/q3.txt", did=did
+    )
+    assert allowed.startswith("ALLOW")
+    assert "read-reports" in allowed
+
+    outside = notary.check_action(
+        action="read_file", target=TARGET, resource="secrets/keys.txt", did=did
+    )
+    assert outside == "DENY: resource outside scope"
+
+    wrong_action = notary.check_action(
+        action="delete_file", target=TARGET, resource="reports/q3.txt", did=did
+    )
+    assert wrong_action == "DENY: no matching rule"
+
+    stranger = notary.check_action(
+        action="read_file", target=TARGET, resource="reports/q3.txt", did="did:key:z6MkStranger"
+    )
+    assert stranger == "DENY: unknown did"

vouch_protocol-2.2.1/tests/test_shield_rules.py

@@ -0,0 +1,356 @@
+"""Shield v2: action / target / resource rules with globs on resource.
+
+The property under test throughout is that nothing is permitted unless a rule
+says so, and that a rule says only what it appears to say.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from vouch.shield import Shield, ShieldConfig
+from vouch.shield.rules import (
+    Decision,
+    load_rules,
+    load_rules_file,
+    normalize_pattern,
+    normalize_resource,
+    resource_matches,
+)
+
+DID = "did:web:agent.example.com"
+OTHER = "did:web:someone-else.example.com"
+
+
+def doc(*allow, did=DID):
+    return {"version": 2, "rules": [{"did": did, "allow": list(allow)}], "deny_default": True}
+
+
+def rule(action="read_file", target="filesystem", resource="reports/**", **kw):
+    return {"action": action, "target": target, "resource": resource, **kw}
+
+
+@pytest.fixture
+def rules():
+    return load_rules(doc(rule(id="reports-read")))
+
+
+# ---------------------------------------------------------------------------
+# The three fields
+# ---------------------------------------------------------------------------
+
+
+def test_allows_when_all_three_fields_match(rules):
+    decision = rules.check(DID, "read_file", "filesystem", "reports/q3.txt")
+    assert decision.allow
+    assert decision.reason == "allowed"
+    assert decision.rule_id == "reports-read"
+
+
+def test_denies_on_action_mismatch(rules):
+    decision = rules.check(DID, "write_file", "filesystem", "reports/q3.txt")
+    assert not decision.allow
+    assert decision.reason == "no matching rule"
+
+
+def test_denies_on_target_mismatch(rules):
+    decision = rules.check(DID, "read_file", "network", "reports/q3.txt")
+    assert not decision.allow
+    assert decision.reason == "no matching rule"
+
+
+def test_denies_on_resource_mismatch_with_a_distinct_reason(rules):
+    """'you may not do this' and 'not there' are different things to say."""
+    decision = rules.check(DID, "read_file", "filesystem", "secrets/keys.txt")
+    assert not decision.allow
+    assert decision.reason == "resource outside scope"
+
+
+def test_unknown_did_is_denied(rules):
+    decision = rules.check(OTHER, "read_file", "filesystem", "reports/q3.txt")
+    assert not decision.allow
+    assert decision.reason == "unknown did"
+
+
+def test_action_and_target_are_case_sensitive(rules):
+    assert not rules.check(DID, "READ_FILE", "filesystem", "reports/q3.txt").allow
+    assert not rules.check(DID, "read_file", "Filesystem", "reports/q3.txt").allow
+
+
+def test_decision_is_falsy_when_denied(rules):
+    assert not rules.check(DID, "read_file", "filesystem", "secrets/x")
+    assert rules.check(DID, "read_file", "filesystem", "reports/x")
+
+
+# ---------------------------------------------------------------------------
+# Glob depth semantics
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "pattern,resource,expected",
+    [
+        # '**' is any depth, including the bare prefix.
+        ("reports/**", "reports", True),
+        ("reports/**", "reports/q3.txt", True),
+        ("reports/**", "reports/2026/q3.txt", True),
+        ("reports/**", "reports/a/b/c/d", True),
+        ("reports/**", "secrets/keys.txt", False),
+        # A prefix must match a whole segment, not a substring.
+        ("reports/**", "reportsX/a", False),
+        # '*' is exactly one segment.
+        ("reports/*", "reports/q3.txt", True),
+        ("reports/*", "reports/2026/q3.txt", False),
+        ("reports/*", "reports", False),
+        # '**' in the middle.
+        ("a/**/b", "a/b", True),
+        ("a/**/b", "a/x/b", True),
+        ("a/**/b", "a/x/y/b", True),
+        ("a/**/b", "a/x/c", False),
+        # Everything.
+        ("**", "anything/at/all", True),
+        ("**", "single", True),
+        # A resource with no '/' is one segment, which is what makes a
+        # non-path resource such as a table name work.
+        ("public.*", "public.customers", True),
+        ("public.*", "internal.salaries", False),
+        # '.' is literal, not a regex wildcard.
+        ("a.b", "axb", False),
+        ("a.b", "a.b", True),
+    ],
+)
+def test_glob_depth_semantics(pattern, resource, expected):
+    assert resource_matches(normalize_pattern(pattern), normalize_resource(resource)) is expected
+
+
+# ---------------------------------------------------------------------------
+# Normalisation and traversal
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("reports/q3.txt", "reports/q3.txt"),
+        ("/reports/q3.txt", "reports/q3.txt"),
+        ("reports//q3.txt", "reports/q3.txt"),
+        ("reports/./q3.txt", "reports/q3.txt"),
+        ("reports/", "reports"),
+        ("a/b/../c", "a/c"),
+        # Escapes the root: refused rather than clamped.
+        ("../x", None),
+        ("..", None),
+        ("reports/../..", None),
+        ("", None),
+        ("a\x00b", None),
+        ("a\x1fb", None),
+    ],
+)
+def test_normalisation(raw, expected):
+    assert normalize_resource(raw) == expected
+
+
+def test_traversal_cannot_reach_outside_the_glob():
+    """The case the whole normalisation step exists for."""
+    rules = load_rules(doc(rule(resource="reports/**")))
+    decision = rules.check(DID, "read_file", "filesystem", "reports/../etc/passwd")
+    assert not decision.allow
+    assert decision.reason == "resource outside scope"
+
+
+def test_leading_slash_and_double_slash_do_not_change_the_verdict():
+    rules = load_rules(doc(rule(resource="reports/**")))
+    for variant in ("reports/q3.txt", "/reports/q3.txt", "reports//q3.txt", "reports/./q3.txt"):
+        assert rules.check(DID, "read_file", "filesystem", variant).allow, variant
+
+
+def test_control_characters_are_refused_with_their_own_reason():
+    rules = load_rules(doc(rule()))
+    decision = rules.check(DID, "read_file", "filesystem", "reports/\x00etc")
+    assert not decision.allow
+    assert decision.reason == "invalid resource"
+
+
+def test_a_rule_pattern_is_normalised_too():
+    """'/reports/**' and 'reports/**' mean the same thing."""
+    rules = load_rules(doc(rule(resource="/reports/**")))
+    assert rules.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+
+
+# ---------------------------------------------------------------------------
+# Fail closed
+# ---------------------------------------------------------------------------
+
+
+def test_empty_rules_denies_everything():
+    rules = load_rules({"version": 2, "rules": [], "deny_default": True})
+    assert rules.ok
+    assert not rules.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+
+
+def test_no_rules_key_denies_everything():
+    rules = load_rules({"version": 2, "deny_default": True})
+    assert not rules.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+
+
+@pytest.mark.parametrize(
+    "document",
+    [
+        {"rules": []},  # no version
+        {"version": 1, "rules": []},  # v1
+        {"version": 2, "rules": {}},  # rules not a list
+        {"version": 2, "rules": [{"did": DID}]},  # no allow
+        {"version": 2, "rules": [{"did": "", "allow": []}]},
+        {"version": 2, "rules": [{"allow": []}]},  # no did
+        {"version": 2, "rules": [{"did": DID, "allow": [{"action": "a", "target": "b"}]}]},
+        {"version": 2, "rules": [{"did": DID, "allow": [{}]}]},
+        {"version": 2, "rules": [], "deny_default": False},
+        "not a mapping",
+        None,
+    ],
+)
+def test_malformed_rules_deny_everything(document, caplog):
+    rules = load_rules(document)
+    assert not rules.ok
+    decision = rules.check(DID, "read_file", "filesystem", "reports/q3.txt")
+    assert not decision.allow
+    assert decision.reason == "malformed rules"
+
+
+def test_malformed_rules_are_logged(caplog):
+    with caplog.at_level("ERROR"):
+        load_rules({"version": 1, "rules": []})
+    assert any("denying all calls" in r.getMessage() for r in caplog.records)
+
+
+def test_a_typo_in_a_rule_key_is_rejected_not_ignored():
+    """'resourse' must not become an allow-anything rule."""
+    document = {
+        "version": 2,
+        "rules": [{"did": DID, "allow": [{"action": "a", "target": "b", "resourse": "x"}]}],
+        "deny_default": True,
+    }
+    rules = load_rules(document)
+    assert not rules.ok
+    assert not rules.check(DID, "a", "b", "anything").allow
+
+
+def test_unknown_block_key_is_rejected():
+    document = {
+        "version": 2,
+        "rules": [{"did": DID, "allow": [], "deny": [rule()]}],
+        "deny_default": True,
+    }
+    assert not load_rules(document).ok
+
+
+@pytest.mark.parametrize("bad", ["a/**b", "a/../b", "a/./b", "", "**b"])
+def test_malformed_resource_patterns_are_rejected(bad):
+    assert not load_rules(doc(rule(resource=bad))).ok
+
+
+def test_missing_rules_file_denies_everything(tmp_path):
+    rules = load_rules_file(tmp_path / "nope.yaml")
+    assert not rules.ok
+    assert rules.check(DID, "read_file", "filesystem", "x").reason == "malformed rules"
+
+
+# ---------------------------------------------------------------------------
+# File loading
+# ---------------------------------------------------------------------------
+
+
+def test_loads_json_rules(tmp_path):
+    path = tmp_path / "rules.json"
+    path.write_text(json.dumps(doc(rule())))
+    assert load_rules_file(path).check(DID, "read_file", "filesystem", "reports/x").allow
+
+
+def test_loads_yaml_rules(tmp_path):
+    pytest.importorskip("yaml")
+    path = tmp_path / "rules.yaml"
+    path.write_text(
+        "version: 2\n"
+        "rules:\n"
+        f"  - did: {DID}\n"
+        "    allow:\n"
+        '      - {action: read_file, target: filesystem, resource: "reports/**"}\n'
+        "deny_default: true\n"
+    )
+    rules = load_rules_file(path)
+    assert rules.ok
+    assert rules.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+    assert not rules.check(DID, "read_file", "filesystem", "secrets/x").allow
+
+
+def test_invalid_json_file_denies_everything(tmp_path):
+    path = tmp_path / "rules.json"
+    path.write_text("{not json")
+    assert not load_rules_file(path).ok
+
+
+def test_rule_ids_are_assigned_when_absent():
+    rules = load_rules(doc(rule(), rule(action="list_dir")))
+    decision = rules.check(DID, "list_dir", "filesystem", "reports/x")
+    assert decision.allow
+    assert decision.rule_id == f"{DID}#1"
+
+
+def test_several_rules_for_one_did_are_all_considered():
+    rules = load_rules(doc(rule(), rule(action="list_dir", resource="logs/**")))
+    assert rules.check(DID, "read_file", "filesystem", "reports/x").allow
+    assert rules.check(DID, "list_dir", "filesystem", "logs/a/b").allow
+    assert not rules.check(DID, "list_dir", "filesystem", "reports/x").allow
+
+
+# ---------------------------------------------------------------------------
+# The Shield facade
+# ---------------------------------------------------------------------------
+
+
+def test_shield_with_no_rules_path_denies_everything():
+    shield = Shield(ShieldConfig(require_signature=False))
+    assert not shield.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+
+
+def test_shield_check_from_a_file(tmp_path):
+    path = tmp_path / "rules.json"
+    path.write_text(json.dumps(doc(rule())))
+    shield = Shield(ShieldConfig(rules_path=str(path), require_signature=False))
+
+    assert shield.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+    assert not shield.check(DID, "read_file", "filesystem", "secrets/k").allow
+
+
+def test_shield_allow_adds_an_in_memory_rule():
+    shield = Shield(ShieldConfig(require_signature=False))
+    shield.allow(DID, action="read_file", target="filesystem", resource="reports/**")
+
+    assert shield.check(DID, "read_file", "filesystem", "reports/q3.txt").allow
+    assert not shield.check(DID, "read_file", "filesystem", "etc/passwd").allow
+    assert len(shield.rules_for(DID)) == 1
+
+
+def test_shield_intercept_defaults_resource_to_the_arguments():
+    """Without an explicit resource, a decision binds to these exact arguments."""
+    from vouch import jcs
+
+    shield = Shield(ShieldConfig(require_signature=False, default_target="tool"))
+    shield.trust_did(DID)
+    args = {"path": "reports/q3.txt"}
+    shield.allow(DID, action="read_file", target="tool", resource=jcs.canonicalize_str(args))
+
+    assert shield.intercept(tool="read_file", args=args, did=DID).allowed
+    # Different arguments, so a different resource, so no match.
+    assert not shield.intercept(tool="read_file", args={"path": "reports/q4.txt"}, did=DID).allowed
+
+
+def test_decision_is_immutable():
+    """A decision is a verdict, not a mutable flag someone can flip later."""
+    import dataclasses
+
+    decision = Decision(True, "allowed", "r1")
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        decision.allow = False  # type: ignore[misc]