gargoyle-receipts 0.5.2.dev0__tar.gz → 0.5.3.dev0__tar.gz

{gargoyle_receipts-0.5.2.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.5.3.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.5.2.dev0
+Version: 0.5.3.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.5.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.5.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/README.md

@@ -21,7 +21,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.5.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.5.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/gargoyle/approval.py

@@ -19,7 +19,7 @@ grant_id is present, so that claim cannot be skipped.
 from datetime import datetime, timedelta
 from typing import Any, Dict, List, Optional
 
-from gargoyle.envelope import approval_terms, canonical_json
+from gargoyle.envelope import approval_terms, canonical_json, serializer_for
 from gargoyle.verifier import not_after_valid
 
 
@@ -129,8 +129,11 @@ def verify_grant(
     gate_key_id: str,
     now: Optional[datetime] = None,
     clock_skew: timedelta = timedelta(0),
+    serializer: Any = None,
 ) -> Dict[str, Any]:
-    """Is `grant` a valid human release of the held decision?
+    """Is `grant` a valid human release of the held decision? `serializer`
+    is the canonical form the grant was signed under (default: the current
+    one; an audit of a historical receipt passes its format's).
 
     Returns {"accepted", "reason"}. First failure wins:
       1. structure                          -> REF_APPROVAL_MALFORMED
@@ -180,7 +183,7 @@ def verify_grant(
 
     # 5. signature verifies (duck-typed; covers everything but the signature)
     region = {k: v for k, v in grant.items() if k not in _SIGNATURE_EXCLUDED_KEYS}
-    message = canonical_json(region).encode("utf-8")
+    message = (serializer or canonical_json)(region).encode("utf-8")
     try:
         public_key.verify(bytes.fromhex(signature_hex), message)
     except Exception:
@@ -236,6 +239,7 @@ def verify_grants(
     with the grants that were counted, so the caller can claim each one."""
     terms = approval_terms(envelope)
     items = as_grant_list(grants)
+    serializer = serializer_for(envelope.get("envelope_version")) or canonical_json
     seen: List[str] = []
     for grant in items:
         g = verify_grant(
@@ -246,6 +250,7 @@ def verify_grants(
             gate_key_id=envelope.get("issuer_key_id"),
             now=now,
             clock_skew=clock_skew,
+            serializer=serializer,
         )
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"], "grants": []}

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/gargoyle/envelope.py

@@ -88,6 +88,28 @@ def canonical_json(data: Any) -> str:
     return "".join(out)
 
 
+def canonical_json_legacy(data: Any) -> str:
+    """The gargoyle/2 canonical form (Python json.dumps with sort_keys,
+    compact separators and ensure_ascii). Kept so that receipts, grants,
+    execution receipts and evidence entries written under gargoyle/2 can
+    still be verified in an audit. Nothing new is ever signed with it."""
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+# Formats an auditor may still verify, each with the serializer its bytes
+# were signed under. Admission (Consumer.check) accepts only ENVELOPE_VERSION.
+HISTORICAL_VERSIONS = {"gargoyle/2": canonical_json_legacy}
+
+
+def serializer_for(version: Any):
+    """The canonical serializer for a receipt format version: the current
+    one for ENVELOPE_VERSION, the legacy one for a historical version, None
+    for anything else."""
+    if version == ENVELOPE_VERSION:
+        return canonical_json
+    return HISTORICAL_VERSIONS.get(version)
+
+
 def _jcs(value: Any, out: list) -> None:
     if value is None:
         out.append("null")
@@ -200,8 +222,11 @@ def valid_approval(approval: Any) -> bool:
 
 
 def decision_sha256_of(envelope: Dict[str, Any]) -> str:
+    """The hash-region digest, under the serializer of the receipt's own
+    format version (a historical receipt hashes as it was issued)."""
     hashable = {k: v for k, v in envelope.items() if k not in _HASH_EXCLUDED_KEYS}
-    return _sha256_text(canonical_json(hashable))
+    serializer = serializer_for(envelope.get("envelope_version")) or canonical_json
+    return _sha256_text(serializer(hashable))
 
 
 def live_pin(

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/gargoyle/evidence.py

@@ -7,7 +7,7 @@ executor's record of every decision it made, honored or refused, each entry
 hashed over the one before it:
 
     entry = {
-        "evidence_version": "gargoyle-evidence/1",
+        "evidence_version": "gargoyle-evidence/2",
         "seq":           1, 2, 3 ...            (dense, from 1)
         "prev_sha256":   <entry_sha256 of seq-1; 64 zeros for seq 1>,
         "at":            <when the executor decided, ISO 8601, UTC>,
@@ -44,11 +44,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional
 
-from gargoyle.envelope import args_sha256, canonical_json
+from gargoyle.envelope import args_sha256, canonical_json, canonical_json_legacy
 from gargoyle.execution import verify_chain
 from gargoyle.verifier import verify_provenance
 
-EVIDENCE_VERSION = "gargoyle-evidence/1"
+EVIDENCE_VERSION = "gargoyle-evidence/2"          # entry hashes over RFC 8785 canonical JSON
+EVIDENCE_VERSIONS = {"gargoyle-evidence/1": canonical_json_legacy, EVIDENCE_VERSION: canonical_json}
 GENESIS = "0" * 64
 
 HONORED = "honored"
@@ -67,9 +68,12 @@ _FIELDS = ("evidence_version", "seq", "prev_sha256", "at", "kind", "tool", "args
 
 
 def entry_sha256(entry: Dict[str, Any]) -> str:
-    """The hash an entry carries: over its canonical JSON without the hash itself."""
+    """The hash an entry carries: over its canonical JSON without the hash
+    itself, under the serializer of the entry's own evidence_version, so a
+    log that spans a format change still verifies end to end."""
     body = {k: v for k, v in entry.items() if k != "entry_sha256"}
-    return hashlib.sha256(canonical_json(body).encode("utf-8")).hexdigest()
+    serialize = EVIDENCE_VERSIONS.get(entry.get("evidence_version"), canonical_json)
+    return hashlib.sha256(serialize(body).encode("utf-8")).hexdigest()
 
 
 def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any, principal: str,
@@ -113,7 +117,7 @@ class EvidenceLog:
         for line in self.path.read_text(encoding="utf-8").splitlines():
             if line.strip():
                 last = json.loads(line)
-                if last.get("evidence_version") == EVIDENCE_VERSION:
+                if last.get("evidence_version") in EVIDENCE_VERSIONS:
                     self._seq, self._tail = int(last["seq"]), str(last["entry_sha256"])
 
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
@@ -132,7 +136,7 @@ class EvidenceLog:
 
 def _well_formed(entry: Any) -> bool:
     return (isinstance(entry, dict) and set(entry) == set(_FIELDS)
-            and entry["evidence_version"] == EVIDENCE_VERSION
+            and entry["evidence_version"] in EVIDENCE_VERSIONS
             and isinstance(entry["seq"], int) and entry["seq"] >= 1
             and isinstance(entry["prev_sha256"], str) and len(entry["prev_sha256"]) == 64
             and isinstance(entry["at"], str) and entry["kind"] in (HONORED, REFUSED)
@@ -196,7 +200,7 @@ def verify_log(
             reason = ACCEPT_ENTRY_VERIFIED
             if e["receipt"] is not None:
                 p = verify_provenance(e["receipt"], pinned_public_keys=issuer_public_keys,
-                                      now=_parse_at(e["at"]))
+                                      now=_parse_at(e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         counts[e["kind"]] += 1
         report.append({"seq": e["seq"], "kind": e["kind"], "tool": e["tool"], "principal": e["principal"],

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/gargoyle/execution.py

@@ -40,7 +40,7 @@ from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from gargoyle.approval import as_grant_list, verify_grants
-from gargoyle.envelope import args_sha256, canonical_json
+from gargoyle.envelope import args_sha256, canonical_json, serializer_for
 from gargoyle.verifier import verify_provenance
 
 EXECUTION_VERSION = "gargoyle-execution/1"
@@ -145,13 +145,16 @@ def verify_execution_receipt(
     public_key = executor_public_keys.get(key_id)
     if public_key is None:
         return _reject(REF_EXEC_KEY_UNKNOWN)
+    # The execution receipt was signed under the canonical form of the
+    # receipt's format version; an audit of a historical chain uses that.
+    serialize = serializer_for(envelope.get("envelope_version")) or canonical_json
     region = {k: v for k, v in execution.items() if k not in _SIGNATURE_EXCLUDED_KEYS}
     try:
-        public_key.verify(bytes.fromhex(signature_hex), canonical_json(region).encode("utf-8"))
+        public_key.verify(bytes.fromhex(signature_hex), serialize(region).encode("utf-8"))
     except Exception:
         return _reject(REF_EXEC_SIGNATURE_INVALID)
     for key in _BOUND_FROM_RECEIPT:
-        if key not in envelope or canonical_json(execution[key]) != canonical_json(envelope[key]):
+        if key not in envelope or serialize(execution[key]) != serialize(envelope[key]):
             return _reject(REF_EXEC_BINDING_MISMATCH)
     if check_outputs:
         try:
@@ -190,7 +193,8 @@ def verify_chain(
     except (ValueError, TypeError):
         return {"accepted": False, "reason": REF_EXEC_MALFORMED, "steps": steps}
 
-    provenance = verify_provenance(envelope, pinned_public_keys=issuer_public_keys, now=executed_at)
+    # An audit verifies historical formats; admission (the consumer) does not.
+    provenance = verify_provenance(envelope, pinned_public_keys=issuer_public_keys, now=executed_at, historical=True)
     steps.append(("authorization", provenance["reason"]))
     if not provenance["accepted"]:
         return {"accepted": False, "reason": provenance["reason"], "steps": steps}

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/gargoyle/verifier.py

@@ -46,6 +46,7 @@ from datetime import datetime, timedelta, timezone
 
 from gargoyle.envelope import (
     ENVELOPE_VERSION,
+    serializer_for,
     valid_approval,
     INVALIDATED,
     REASSERTED,
@@ -174,6 +175,7 @@ def verify_provenance(
     key_record_view: Dict[str, Any] = None,
     now: datetime = None,
     clock_skew: timedelta = timedelta(0),
+    historical: bool = False,
 ) -> Dict[str, Any]:
     """Steps 1 and 2 of verify_envelope on their own: the receipt is
     structurally usable, a trusted issuer key signed it, and it had not
@@ -181,7 +183,12 @@ def verify_provenance(
     offline on a stored receipt (with `now` set to when it was presented).
     Returns {"accepted": bool, "reason": str}; the accept reason is
     ACCEPT_PROVENANCE. Currency and binding are verify_envelope's steps 3
-    and 4 and are not checked here."""
+    and 4 and are not checked here.
+
+    `historical` lets an audit verify a receipt of an earlier format
+    version (envelope.HISTORICAL_VERSIONS) under the serializer it was
+    signed with. Admission never sets it: a target honors only the
+    current format."""
     if clock_skew < timedelta(0):
         raise ValueError("clock_skew must be non-negative")
     if pinned_public_keys is None and key_record_view is None:
@@ -192,8 +199,10 @@ def verify_provenance(
     for key in _REQUIRED_ENVELOPE_KEYS:
         if key not in envelope:
             return _reject(REF_VERIFY_ENVELOPE_ABSENT)
-    if envelope.get("envelope_version") != ENVELOPE_VERSION:
+    version = envelope.get("envelope_version")
+    if version != ENVELOPE_VERSION and not (historical and serializer_for(version) is not None):
         return _reject(REF_VERIFY_VERSION_UNSUPPORTED)
+    serialize = serializer_for(version)
     rc = envelope["request_context"]
     if not isinstance(rc, dict):
         return _reject(REF_VERIFY_ENVELOPE_ABSENT)
@@ -252,7 +261,7 @@ def verify_provenance(
         for k, v in envelope.items()
         if k not in ("issuer_signature", "timestamp_utc")
     }
-    message = canonical_json(signed_region).encode("utf-8")
+    message = serialize(signed_region).encode("utf-8")
     try:
         public_key.verify(bytes.fromhex(signature_hex), message)
     except Exception:

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.5.2.dev0
+Version: 0.5.3.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.5.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.5.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -46,6 +46,7 @@ tests/test_entra_login.py
 tests/test_evidence.py
 tests/test_execution.py
 tests/test_fs_server.py
+tests/test_historical.py
 tests/test_identity.py
 tests/test_issuer_service.py
 tests/test_jws.py

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.5.3.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.5.2.dev0"
+version = "0.5.3.dev0"
 description = "Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls."
 readme = "README.md"
 requires-python = ">=3.12"

gargoyle_receipts-0.5.3.dev0/tests/test_historical.py

@@ -0,0 +1,82 @@
+"""Evidence outlives format changes. A gargoyle/2 receipt (the fixture
+frozen before the move to RFC 8785) is refused at admission but verifies in
+an audit under the serializer it was signed with, grants and execution
+receipt included; an evidence log that spans the change verifies end to end."""
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from gargoyle.consumer import Consumer
+from gargoyle.envelope import ENVELOPE_VERSION, canonical_json_legacy, decision_sha256_of, serializer_for
+from gargoyle.evidence import EVIDENCE_VERSION, HONORED, REFUSED, EvidenceLog, entry_sha256, verify_log
+from gargoyle.execution import ACCEPT_CHAIN_VERIFIED, verify_chain
+from gargoyle.verifier import ACCEPT_PROVENANCE, REF_VERIFY_SIGNATURE_INVALID, REF_VERIFY_VERSION_UNSUPPORTED, verify_provenance
+
+V2 = json.loads((Path(__file__).parent / "fixtures" / "wire_vectors_v2.json").read_text(encoding="utf-8"))
+NOW = datetime(2026, 10, 16, 12, 1, tzinfo=timezone.utc)
+
+
+def _key(label):
+    return Ed25519PrivateKey.from_private_bytes(hashlib.sha256(label.encode()).digest())
+
+
+def _keys():
+    issuer, approver, bob, executor = (_key(V2[k] if k in V2 else V2["threshold"][k])
+                                       for k in ("issuer_seed_label", "approver_seed_label", "approver_2_seed_label", "executor_seed_label"))
+    return (issuer, {V2["signed"]["issuer_key_id"]: issuer.public_key()},
+            {"approver-alice": approver.public_key(), "approver-bob": bob.public_key()},
+            {V2["execution"]["executor_key_id"]: executor.public_key()})
+
+
+def test_the_fixture_is_the_old_format_and_hashes_under_the_old_serializer():
+    assert V2["signed"]["envelope_version"] == "gargoyle/2" != ENVELOPE_VERSION
+    assert serializer_for("gargoyle/2") is canonical_json_legacy and serializer_for("gargoyle/9") is None
+    assert decision_sha256_of(V2["signed"]) == V2["signed"]["decision_sha256"]
+
+
+def test_admission_refuses_but_an_audit_verifies_the_whole_old_chain():
+    _, issuer_keys, approvers, exec_keys = _keys()
+    # Admission: the format is not current.
+    assert verify_provenance(V2["signed"], pinned_public_keys=issuer_keys, now=NOW)["reason"] == REF_VERIFY_VERSION_UNSUPPORTED
+    c = Consumer(target_id=V2["signed"]["target_url"], record=V2["signed"]["policy"], pinned_public_keys=issuer_keys, approver_public_keys=approvers)
+    assert c.check(V2["signed"], V2["call"], grant=V2["grant"], now=NOW).reason == REF_VERIFY_VERSION_UNSUPPORTED
+    # Audit: historical verification under the gargoyle/2 serializer.
+    assert verify_provenance(V2["signed"], pinned_public_keys=issuer_keys, now=NOW, historical=True)["reason"] == ACCEPT_PROVENANCE
+    chain = verify_chain(V2["signed"], V2["execution"], grant=V2["grant"], issuer_public_keys=issuer_keys,
+                         executor_public_keys=exec_keys, approver_public_keys=approvers, outputs=V2["outputs"], check_outputs=True)
+    assert chain["reason"] == ACCEPT_CHAIN_VERIFIED
+    T = V2["threshold"]
+    chain2 = verify_chain(T["signed"], T["execution"], grant=T["grants"], issuer_public_keys=issuer_keys,
+                          executor_public_keys=exec_keys, approver_public_keys=approvers)
+    assert chain2["reason"] == ACCEPT_CHAIN_VERIFIED
+    # Historical does not mean lenient: a tampered old receipt still fails.
+    tampered = dict(V2["signed"], target_url="https://elsewhere.example/")
+    assert verify_provenance(tampered, pinned_public_keys=issuer_keys, now=NOW, historical=True)["reason"] == REF_VERIFY_SIGNATURE_INVALID
+
+
+def test_an_evidence_log_spanning_the_format_change_verifies(tmp_path):
+    _, issuer_keys, approvers, exec_keys = _keys()
+    path = tmp_path / "audit.jsonl"
+    # Two entries as a gargoyle-evidence/1 writer produced them: hashed with the legacy serializer.
+    def v1_entry(seq, prev, kind, tool, reason, receipt=None, grant=None, execution=None, principal="agent-7"):
+        e = {"evidence_version": "gargoyle-evidence/1", "seq": seq, "prev_sha256": prev, "at": "2026-10-16T12:01:00+00:00",
+             "kind": kind, "tool": tool, "args_sha256": V2["args_sha256"], "principal": principal, "reason": reason,
+             "receipt": receipt, "grant": grant, "execution": execution}
+        body = dict(e)
+        e["entry_sha256"] = hashlib.sha256(canonical_json_legacy(body).encode("utf-8")).hexdigest()
+        return e
+    e1 = v1_entry(1, "0" * 64, HONORED, "transfer_funds", "CHAIN_VERIFIED", V2["signed"], V2["grant"], V2["execution"])
+    e2 = v1_entry(2, e1["entry_sha256"], REFUSED, "delete_file", "DESTRUCTIVE_TOOL")
+    assert entry_sha256(e1) == e1["entry_sha256"]            # recomputed under the entry's own version
+    path.write_text(json.dumps(e1) + "\n" + json.dumps(e2) + "\n", encoding="utf-8")
+    # A current writer continues the chain with a version-2 entry.
+    e3 = EvidenceLog(str(path)).append(REFUSED, "delete_file", {"path": "x"}, "agent-7", "DESTRUCTIVE_TOOL")
+    assert e3["evidence_version"] == EVIDENCE_VERSION and e3["seq"] == 3 and e3["prev_sha256"] == e2["entry_sha256"]
+    entries = [json.loads(l) for l in path.read_text(encoding="utf-8").splitlines()]
+    v = verify_log(entries, issuer_public_keys=issuer_keys, executor_public_keys=exec_keys, approver_public_keys=approvers)
+    assert v["accepted"], [r["reason"] for r in v["entries"]]
+    assert [r["reason"] for r in v["entries"]][0] == ACCEPT_CHAIN_VERIFIED