gargoyle-receipts 0.16.2.dev0__tar.gz → 0.16.3.dev0__tar.gz

{gargoyle_receipts-0.16.2.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.16.3.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.2.dev0
+Version: 0.16.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.16.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.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
@@ -298,7 +298,10 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Approvers, and
+is never accepted again. Every key an approver held stays in the file
+(`history`), so an audit of grants released under an earlier key still
+verifies: copy the issuer's current `approvers.json` beside the evidence
+before auditing. Approvers, and
 only approvers, see the whole queue and the witness; everyone else sees
 their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.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.16.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.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
@@ -260,7 +260,10 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Approvers, and
+is never accepted again. Every key an approver held stays in the file
+(`history`), so an audit of grants released under an earlier key still
+verifies: copy the issuer's current `approvers.json` beside the evidence
+before auditing. Approvers, and
 only approvers, see the whole queue and the witness; everyone else sees
 their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.

gargoyle_receipts-0.16.3.dev0/gargoyle/__main__.py

@@ -0,0 +1,9 @@
+"""`python -m gargoyle` is the CLI: on a Windows Store Python the Scripts folder
+that holds gargoyle.exe is usually not on PATH."""
+
+import sys
+
+from gargoyle.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/approval.py

@@ -32,6 +32,21 @@ _SIGNATURE_EXCLUDED_KEYS = ("approver_signature",)
 
 # Refusal codes.
 REF_APPROVAL_MALFORMED = "REF_APPROVAL_MALFORMED"
+
+
+class _AnyOf:
+    """A verifying key made of several: the signature is valid if any verifies it."""
+    def __init__(self, keys: list) -> None:
+        self.keys = keys
+
+    def verify(self, signature: bytes, message: bytes) -> None:
+        for key in self.keys[:-1]:
+            try:
+                key.verify(signature, message)
+                return
+            except Exception:
+                continue
+        self.keys[-1].verify(signature, message)
 REF_APPROVAL_MISSING_GRANT_ID = "REF_APPROVAL_MISSING_GRANT_ID"
 REF_APPROVAL_SIGNATURE_INVALID = "REF_APPROVAL_SIGNATURE_INVALID"
 REF_APPROVAL_KEY_UNKNOWN = "REF_APPROVAL_KEY_UNKNOWN"
@@ -178,6 +193,10 @@ def verify_grant(
 
     # 4. known approver key
     public_key = approver_public_keys.get(key_id)
+    if isinstance(public_key, (list, tuple)):
+        # Several keys for one approver id: an audit of grants from before the
+        # approver's browser key was replaced or revoked. Any of them may verify.
+        public_key = _AnyOf(list(public_key)) if public_key else None
     if public_key is None:
         return _reject(REF_APPROVAL_KEY_UNKNOWN)
 

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/approvers.py

@@ -26,7 +26,7 @@ import stat
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import List, Any, Dict, Optional
 
 ENV_APPROVERS_PATH = "GARGOYLE_APPROVERS_PATH"
 ENV_APPROVER_ROLE = "GARGOYLE_APPROVER_ROLE"        # Entra app role an enrolling token must carry (default Approver)
@@ -53,6 +53,7 @@ class ApproverRegistry:
         self._lock = threading.Lock()
         self._approvers: Dict[str, Dict[str, Any]] = {}
         self._revoked: Dict[str, Dict[str, Any]] = {}      # former approvers, kept so old grants still verify in audits
+        self._history: Dict[str, List[Dict[str, Any]]] = {}  # every key each UPN held and how it ended (replaced, revoked)
         self._mtime: Optional[float] = None
         self._load()
 
@@ -67,7 +68,16 @@ class ApproverRegistry:
         for upn, entry in (doc.get("revoked") or {}).items():
             if isinstance(entry, dict) and valid_public_key_hex(entry.get("public_key_hex")):
                 revoked[upn] = dict(entry)
-        self._approvers, self._revoked = approvers, revoked
+        history: Dict[str, List[Dict[str, Any]]] = {}
+        for upn, items in (doc.get("history") or {}).items():
+            if isinstance(items, list):
+                history[upn] = [dict(h) for h in items if isinstance(h, dict) and valid_public_key_hex(h.get("public_key_hex"))]
+        for upn, e in revoked.items():
+            # A file from before history existed: its revoked record is the one former key known.
+            if not any(h.get("public_key_hex") == e["public_key_hex"] for h in history.get(upn, [])):
+                history.setdefault(upn, []).append({**{k: v for k, v in e.items() if k not in ("revoked_at", "revoked_by")},
+                                                    "ended_at": e.get("revoked_at"), "ended_by": e.get("revoked_by"), "reason": "revoked"})
+        self._approvers, self._revoked, self._history = approvers, revoked, history
         self._mtime = self.path.stat().st_mtime
 
     def _refresh(self) -> None:
@@ -89,6 +99,8 @@ class ApproverRegistry:
         doc = {"approvers": self._approvers}
         if self._revoked:
             doc["revoked"] = self._revoked
+        if self._history:
+            doc["history"] = self._history
         self.path.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
         try:
             os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
@@ -120,13 +132,45 @@ class ApproverRegistry:
             entry["tid"] = tid
         with self._lock:
             self._refresh()
-            if any(e.get("public_key_hex") == public_key_hex for e in self._revoked.values()):
+            if public_key_hex in self._revoked_keys():
                 raise RevokedKeyError("that key was revoked; enroll a new one")
             replaced = upn in self._approvers
+            if replaced and self._approvers[upn].get("public_key_hex") != public_key_hex:
+                # The superseded key is kept: grants signed under it still audit.
+                self._remember(upn, self._approvers[upn], "replaced", enrolled_by or upn, now)
             self._approvers[upn] = entry
             self._save()
         return {"upn": upn, "replaced": replaced, **entry}
 
+    def _remember(self, upn: str, entry: Dict[str, Any], reason: str, ended_by: str, now: Optional[datetime]) -> None:
+        hist = self._history.setdefault(upn, [])
+        if not any(h.get("public_key_hex") == entry.get("public_key_hex") for h in hist):
+            hist.append({**{k: v for k, v in entry.items() if k not in ("revoked_at", "revoked_by")},
+                         "ended_at": (now or datetime.now(timezone.utc)).isoformat(), "ended_by": ended_by, "reason": reason})
+
+    def _revoked_keys(self) -> set:
+        """Every public key ever revoked, under any UPN: none may enroll again."""
+        return ({e.get("public_key_hex") for e in self._revoked.values()}
+                | {h.get("public_key_hex") for hist in self._history.values() for h in hist if h.get("reason") == "revoked"})
+
+    def audit_keys_hex(self) -> Dict[str, List[str]]:
+        """{upn: [public_key_hex, ...]}: the current key first, then every key
+        the UPN held before. An audit verifies a grant with any of them; the
+        live service and middleware trust only the current one."""
+        with self._lock:
+            self._refresh()
+            out: Dict[str, List[str]] = {}
+            for upn, e in self._approvers.items():
+                out[upn] = [e["public_key_hex"]]
+            for upn, hist in self._history.items():
+                for h in hist:
+                    if h["public_key_hex"] not in out.setdefault(upn, []):
+                        out[upn].append(h["public_key_hex"])
+            for upn, e in self._revoked.items():
+                if e["public_key_hex"] not in out.setdefault(upn, []):
+                    out[upn].append(e["public_key_hex"])
+            return out
+
     def revoke(self, upn: str, *, revoked_by: Optional[str] = None, now: Optional[datetime] = None) -> bool:
         """Stop trusting `upn`'s key from now on. The entry moves to the
         revoked list with when and by whom, so an audit of earlier evidence
@@ -139,6 +183,7 @@ class ApproverRegistry:
                 return False
             self._revoked[upn] = {**entry, "revoked_at": (now or datetime.now(timezone.utc)).isoformat(),
                                   "revoked_by": revoked_by or upn}
+            self._remember(upn, entry, "revoked", revoked_by or upn, now)
             self._save()
         return True
 

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/cli.py

@@ -39,6 +39,7 @@ the response metadata; `gargoyle audit` verifies them later, offline.
 
 import argparse
 import json
+from typing import Any, Dict
 import os
 import re
 import stat
@@ -364,15 +365,17 @@ def cmd_audit(args) -> int:
     from gargoyle.execution import verify_chain
 
     keys = json.loads((Path(args.out).resolve() / "public-keys.json").read_text())
-    load = lambda m: {k: Ed25519PublicKey.from_public_bytes(bytes.fromhex(v)) for k, v in m.items()}
-    approvers = dict(keys["approver"])
+    one = lambda h: Ed25519PublicKey.from_public_bytes(bytes.fromhex(h))
+    load = lambda m: {k: ([one(x) for x in v] if isinstance(v, list) else one(v)) for k, v in m.items()}
+    approvers: Dict[str, Any] = dict(keys["approver"])
     enrolled = Path(args.out).resolve() / "approvers.json"          # approvers who enrolled through Entra, by UPN
     if enrolled.exists():
-        doc = json.loads(enrolled.read_text())
-        # Revoked approvers too: the audit verifies what was signed while they
-        # were trusted. Only the live service and middleware refuse them.
-        approvers.update({u: e["public_key_hex"] for u, e in doc.get("revoked", {}).items()})
-        approvers.update({u: e["public_key_hex"] for u, e in doc.get("approvers", {}).items()})
+        from gargoyle.approvers import ApproverRegistry
+        # Every key each approver ever held, current first: grants signed
+        # under a key since replaced in the browser or revoked still have to
+        # verify. Only the live service and middleware are limited to the
+        # current key. Copy the issuer's file beside the evidence first.
+        approvers.update(ApproverRegistry(str(enrolled)).audit_keys_hex())
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
                  approver_public_keys=load(approvers))
     if args.log:

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.2.dev0
+Version: 0.16.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.16.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.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
@@ -298,7 +298,10 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Approvers, and
+is never accepted again. Every key an approver held stays in the file
+(`history`), so an audit of grants released under an earlier key still
+verifies: copy the issuer's current `approvers.json` beside the evidence
+before auditing. Approvers, and
 only approvers, see the whole queue and the witness; everyone else sees
 their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ NOTICE
 README.md
 pyproject.toml
 gargoyle/__init__.py
+gargoyle/__main__.py
 gargoyle/adapters.py
 gargoyle/approval.py
 gargoyle/approver_cli.py

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.16.2.dev0"
+version = "0.16.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.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/tests/test_approvers.py

@@ -204,3 +204,39 @@ def test_an_operators_revocation_on_the_host_reaches_the_witness(tmp_path):
     c.get("/approvers")
     revoked = [e for e in events if e["event"] == "revoked"]
     assert [(e["approver"], e["by"]) for e in revoked] == [("dana@contoso.com", "operator:root"), ("lee@contoso.com", "lee@contoso.com")]
+
+
+def test_every_key_an_approver_held_stays_for_audits(tmp_path):
+    """The client audit of 2026-10-20 failed a row released under a key that a
+    later browser enrollment had replaced: the registry had dropped it. Now
+    every key a UPN held is kept (history: replaced or revoked, when, by whom),
+    the audit map carries them all, and a grant verifies with any of them."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    from gargoyle.approval import ACCEPT_GRANT_VALID, build_grant, sign_grant, verify_grant
+    from gargoyle.approvers import RevokedKeyError
+    path = tmp_path / "a.json"
+    reg = ApproverRegistry(str(path))
+    k1, k2, k3 = (Ed25519PrivateKey.generate() for _ in range(3))
+    reg.enroll("dana@contoso.com", pub_hex(k1))
+    assert reg.enroll("dana@contoso.com", pub_hex(k2))["replaced"] is True            # a new browser
+    assert reg.revoke("dana@contoso.com", revoked_by="operator:root")
+    reg.enroll("dana@contoso.com", pub_hex(k3))
+    assert reg.audit_keys_hex() == {"dana@contoso.com": [pub_hex(k3), pub_hex(k1), pub_hex(k2)]}
+    doc = json.loads(path.read_text())
+    assert [(h["reason"], h["ended_by"]) for h in doc["history"]["dana@contoso.com"]] == [("replaced", "dana@contoso.com"), ("revoked", "operator:root")]
+    now = datetime.now(timezone.utc)
+    keys = {u: [Ed25519PublicKey.from_public_bytes(bytes.fromhex(x)) for x in hs] for u, hs in reg.audit_keys_hex().items()}
+    for k in (k1, k2, k3):
+        g = sign_grant(build_grant(decision_sha256="a" * 64, approval_request_id="r", grant_id="g", not_after=now + timedelta(minutes=5)), k, "dana@contoso.com")
+        v = verify_grant(g, expected_decision_sha256="a" * 64, expected_approval_request_id="r", approver_public_keys=keys, gate_key_id="issuer-1", now=now)
+        assert v["accepted"] is True and v["reason"] == ACCEPT_GRANT_VALID
+    stranger = sign_grant(build_grant(decision_sha256="a" * 64, approval_request_id="r", grant_id="g", not_after=now + timedelta(minutes=5)),
+                          Ed25519PrivateKey.generate(), "dana@contoso.com")
+    assert verify_grant(stranger, expected_decision_sha256="a" * 64, expected_approval_request_id="r", approver_public_keys=keys, gate_key_id="issuer-1", now=now)["accepted"] is False
+    # The revoked key k2 is refused for anyone, from history, even after Dana's revoked record is gone.
+    with pytest.raises(RevokedKeyError):
+        reg.enroll("lee@contoso.com", pub_hex(k2))
+    # A file from before history existed: its revoked record seeds the history.
+    old = tmp_path / "old.json"
+    old.write_text(json.dumps({"approvers": {}, "revoked": {"x@contoso.com": {"public_key_hex": pub_hex(k1), "revoked_at": "t", "revoked_by": "b"}}}))
+    assert ApproverRegistry(str(old)).audit_keys_hex() == {"x@contoso.com": [pub_hex(k1)]}

{gargoyle_receipts-0.16.2.dev0 → gargoyle_receipts-0.16.3.dev0}/tests/test_cli.py

@@ -136,3 +136,10 @@ def test_approvers_list_and_revoke_on_the_issuer_host(tmp_path, capsys):
     assert doc["approvers"] == {} and doc["revoked"]["dana@contoso.com"]["revoked_by"].startswith("operator:")
     assert main(["approvers", "list", "--out", str(out)]) == 0
     assert "revoked: dana@contoso.com" in capsys.readouterr().out
+
+
+def test_the_package_runs_as_a_module():
+    """`python -m gargoyle --help` works where gargoyle.exe is not on PATH."""
+    import subprocess, sys
+    r = subprocess.run([sys.executable, "-m", "gargoyle", "--help"], capture_output=True, text=True, timeout=60)
+    assert r.returncode == 0 and "audit" in r.stdout