gargoyle-receipts 0.20.0.dev0__tar.gz → 0.21.0.dev0__tar.gz

{gargoyle_receipts-0.20.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.21.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.20.0.dev0
+Version: 0.21.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -64,7 +64,7 @@ by whom, and what changed.
 
 ## Status
 
-Pre-release `0.20.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
+Pre-release `0.21.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
 `gargoyle/3`, evidence log `gargoyle-evidence/4`, witness
 `gargoyle-witness/1`; all three are specified in [SPEC.md](SPEC.md) and may
 still change before a first release.
@@ -91,7 +91,7 @@ against a fake Graph server); the OAuth broker for hosted connectors
 (deployed, metadata and redirect checks verified, no human sign-in through a
 connector yet).
 
-**Assurance.** 561 Python tests on Linux and Windows across Python 3.12,
+**Assurance.** 564 Python tests on Linux and Windows across Python 3.12,
 3.13 and 3.14, at dependency floors and at a lock file; a TypeScript suite
 that recomputes the conformance vectors byte for byte; two outside,
 model-driven security reviews on 2026-10-20 (ten findings, all fixed); the
@@ -378,6 +378,13 @@ enrollment, revocation and discovery report, on the operator's server.
     gargoyle audit --log audit.jsonl --witness witness.jsonl           # reconcile by decision id: unwitnessed receipts, releases without a grant, missing evidence
     gargoyle audit --log audit.jsonl --check-tree /srv/shared          # hash the gated folder against the recorded states; name files changed around the gate
     gargoyle audit --log audit.jsonl --summary                         # calls by principal and tool, side-door findings
+    gargoyle audit --log audit.jsonl --issuer https://gargoyle.lan      # take the issuer's keys and every approver key it has seen from the issuer, not from a copied file
+
+The audit needs the public keys (`public-keys.json`, by default beside the
+log or in `--out`). Grants verify against every key an approver has held,
+so an approver who re-enrolled a browser key is still audited; with
+`--issuer` that list comes from the issuer itself and a stale copy of
+`approvers.json` can no longer fail a valid grant.
 
 On a machine the user administers the gate constrains the assistant, not
 the user; these checks make the difference visible. SPEC.md section 15
@@ -661,7 +668,8 @@ receipts work unchanged. Configuration is by environment:
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`, or `gargoyle issuer`): identity token in, receipt out,
 with the hold and grant exchange for flagged calls (`/issue`, `/pending`,
-`/grants`, `/decline`, `/record`, `/keys`, `/sidedoors`) and the browser
+`/grants`, `/decline`, `/record`, `/keys`, `/approvers`, `/approvers/audit`,
+`/sidedoors`) and the browser
 approval console at `/approve`. Policy from a rules file or OPA; identity
 from a pinned key or, with `GARGOYLE_ENTRA_TENANT`, the tenant's signing
 keys (both at once when a pinned key is also set).

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/README.md

@@ -26,7 +26,7 @@ by whom, and what changed.
 
 ## Status
 
-Pre-release `0.20.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
+Pre-release `0.21.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
 `gargoyle/3`, evidence log `gargoyle-evidence/4`, witness
 `gargoyle-witness/1`; all three are specified in [SPEC.md](SPEC.md) and may
 still change before a first release.
@@ -53,7 +53,7 @@ against a fake Graph server); the OAuth broker for hosted connectors
 (deployed, metadata and redirect checks verified, no human sign-in through a
 connector yet).
 
-**Assurance.** 561 Python tests on Linux and Windows across Python 3.12,
+**Assurance.** 564 Python tests on Linux and Windows across Python 3.12,
 3.13 and 3.14, at dependency floors and at a lock file; a TypeScript suite
 that recomputes the conformance vectors byte for byte; two outside,
 model-driven security reviews on 2026-10-20 (ten findings, all fixed); the
@@ -340,6 +340,13 @@ enrollment, revocation and discovery report, on the operator's server.
     gargoyle audit --log audit.jsonl --witness witness.jsonl           # reconcile by decision id: unwitnessed receipts, releases without a grant, missing evidence
     gargoyle audit --log audit.jsonl --check-tree /srv/shared          # hash the gated folder against the recorded states; name files changed around the gate
     gargoyle audit --log audit.jsonl --summary                         # calls by principal and tool, side-door findings
+    gargoyle audit --log audit.jsonl --issuer https://gargoyle.lan      # take the issuer's keys and every approver key it has seen from the issuer, not from a copied file
+
+The audit needs the public keys (`public-keys.json`, by default beside the
+log or in `--out`). Grants verify against every key an approver has held,
+so an approver who re-enrolled a browser key is still audited; with
+`--issuer` that list comes from the issuer itself and a stale copy of
+`approvers.json` can no longer fail a valid grant.
 
 On a machine the user administers the gate constrains the assistant, not
 the user; these checks make the difference visible. SPEC.md section 15
@@ -623,7 +630,8 @@ receipts work unchanged. Configuration is by environment:
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`, or `gargoyle issuer`): identity token in, receipt out,
 with the hold and grant exchange for flagged calls (`/issue`, `/pending`,
-`/grants`, `/decline`, `/record`, `/keys`, `/sidedoors`) and the browser
+`/grants`, `/decline`, `/record`, `/keys`, `/approvers`, `/approvers/audit`,
+`/sidedoors`) and the browser
 approval console at `/approve`. Policy from a rules file or OPA; identity
 from a pinned key or, with `GARGOYLE_ENTRA_TENANT`, the tenant's signing
 keys (both at once when a pinned key is also set).

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/gargoyle/claude_hook.py

@@ -116,6 +116,14 @@ class PendingReceipts:
     def __init__(self, path: str) -> None:
         self.path = Path(path)
 
+    def _locked(self):
+        """Pre- and PostToolUse hooks of parallel tool calls run as separate
+        processes at once; each read-modify-write holds the lock, or one
+        loses the other's entry (a call that ran with no evidence row, or an
+        honored one resurrected and reaped as never run)."""
+        from gargoyle.evidence import locked
+        return locked(self.path.with_name(self.path.name + ".lock"))
+
     def _read(self) -> Dict[str, Any]:
         try:
             doc = json.loads(self.path.read_text(encoding="utf-8"))
@@ -129,26 +137,29 @@ class PendingReceipts:
         os.replace(tmp, self.path)
 
     def put(self, tool_use_id: str, gate: Dict[str, Any], params: Dict[str, Any], now: float) -> None:
-        doc = self._read()
-        doc[tool_use_id] = {"envelope": gate["envelope"], "grant": gate["grant"], "self_issued": gate["self_issued"],
-                            "reason": gate["reason"], "ref": gate.get("ref"), "params": params, "at": now}
-        for old in list(doc)[:-PENDING_LIMIT]:
-            doc.pop(old, None)
-        self._write(doc)
+        with self._locked():
+            doc = self._read()
+            doc[tool_use_id] = {"envelope": gate["envelope"], "grant": gate["grant"], "self_issued": gate["self_issued"],
+                                "reason": gate["reason"], "ref": gate.get("ref"), "params": params, "at": now}
+            for old in list(doc)[:-PENDING_LIMIT]:
+                doc.pop(old, None)
+            self._write(doc)
 
     def pop(self, tool_use_id: str) -> Optional[Dict[str, Any]]:
-        doc = self._read()
-        gate = doc.pop(tool_use_id, None)
-        if gate is not None:
-            self._write(doc)
+        with self._locked():
+            doc = self._read()
+            gate = doc.pop(tool_use_id, None)
+            if gate is not None:
+                self._write(doc)
         return gate
 
     def reap(self, now: float, max_age: float) -> List[Dict[str, Any]]:
-        doc = self._read()
-        stale = [k for k, v in doc.items() if not isinstance(v.get("at"), (int, float)) or now - v["at"] > max_age]
-        out = [doc.pop(k) for k in stale]
-        if out:
-            self._write(doc)
+        with self._locked():
+            doc = self._read()
+            stale = [k for k, v in doc.items() if not isinstance(v.get("at"), (int, float)) or now - v["at"] > max_age]
+            out = [doc.pop(k) for k in stale]
+            if out:
+                self._write(doc)
         return out
 
 
@@ -256,6 +267,10 @@ def decide(event: Dict[str, Any], state: Any, *, final: bool = False, now: Optio
         gate = pending.pop(tool_use_id) if (pending is not None and tool_use_id) else None
         if gate is None:
             return {}
+        # The receipt bound the arguments PreToolUse saw; Claude Code may
+        # present some tools' input differently afterwards, so the entry is
+        # written over what was gated, not what PostToolUse carries.
+        params = gate["params"]
         outputs = event.get("tool_response") if kind == POST else {"error": event.get("error")}
         execution = _attest(state, gate["envelope"], outputs, params)
         _record(state, HONORED, gate, params, execution)

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/gargoyle/cli.py

@@ -635,9 +635,11 @@ def _audit_summary(report, raw) -> None:
             releases[who] += 1
         clients[r.get("client") or "(client unnamed)"] += 1
     print("summary: %d call(s)%s" % (len(report), (", %s to %s" % (min(ats)[:19], max(ats)[:19])) if ats else ""))
-    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "failed", "refused"))
+    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "errored", "refused"))
     for (principal, tool), c in sorted(counts.items(), key=lambda kv: (kv[0][0], -sum(kv[1].values()), kv[0][1])):
         print("  %-28s %-24s %7d %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("failed", 0), c.get("refused", 0)))
+    if any(c.get("failed") for c in counts.values()):
+        print("  errored: admitted by the gate, then the upstream reported an error (a missing file, a bad argument); not a verification failure")
     if releases:
         print("  releases: " + ", ".join("%s %d" % (w, n) for w, n in releases.most_common()))
     print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))
@@ -786,11 +788,54 @@ def cmd_restore(args) -> int:
     return 0 if (r.get("restored") or (args.verify_only and not r.get("refused"))) else 1
 
 
+def _issuer_trust(url: str) -> "tuple[Dict[str, str], Dict[str, list]]":
+    """The issuer's current signing keys (GET /keys) and every key each
+    enrolled approver has held (GET /approvers/audit), so an audit on a
+    workstation needs no copy of approvers.json that can go stale. Both are
+    public endpoints. REQUESTS_CA_BUNDLE names the issuer's CA as usual."""
+    import requests
+    base = url.rstrip("/")
+    keys = requests.get(base + "/keys", timeout=10); keys.raise_for_status()
+    appr = requests.get(base + "/approvers/audit", timeout=10); appr.raise_for_status()
+    return dict(keys.json()), dict(appr.json().get("approvers", {}))
+
+
+def _audit_trust_dir(args) -> "Path | None":
+    """Where public-keys.json is: --out, else the evidence log's own folder
+    (on a workstation the keys sit beside audit.jsonl). None when neither."""
+    out = Path(args.out).resolve()
+    if (out / "public-keys.json").exists():
+        return out
+    if getattr(args, "log", None):
+        beside = Path(args.log).resolve().parent
+        if (beside / "public-keys.json").exists():
+            return beside
+    return None
+
+
 def cmd_audit(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
     from gargoyle.execution import verify_chain
 
-    keys, approvers = _trust_hex(Path(args.out).resolve())
+    out = _audit_trust_dir(args)
+    if out is None:
+        print("public-keys.json not found in %s%s: pass --out DIR, the folder that holds public-keys.json (and approvers.json), "
+              "on a workstation the one with middleware.env" % (Path(args.out).resolve(),
+              (" or beside %s" % Path(args.log).resolve().parent) if getattr(args, "log", None) else ""), file=sys.stderr)
+        return 2
+    keys, approvers = _trust_hex(out)
+    if getattr(args, "issuer", None):
+        try:
+            issuer_keys, issuer_approvers = _issuer_trust(args.issuer)
+        except Exception as exc:
+            print("issuer not reachable for keys: %s (%s)" % (args.issuer, exc), file=sys.stderr)
+            return 2
+        keys["issuer"] = dict(keys.get("issuer", {}), **issuer_keys)
+        # The issuer's list is current and complete; a local copy may be older.
+        for upn, hexes in issuer_approvers.items():
+            have = approvers.get(upn)
+            have = have if isinstance(have, list) else ([have] if have else [])
+            approvers[upn] = list(hexes) + [h for h in have if h not in hexes]
     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()}
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
@@ -821,6 +866,17 @@ def cmd_audit(args) -> int:
         failed = sum(1 for r in v["entries"] if not r["accepted"])
         print("%d entries (%d honored, %d refused), %d failed; chain %s; tail %s"
               % (v["count"], v["honored"], v["refused"], failed, v["reason"], v["tail_sha256"][:16]))
+        from gargoyle.approval import REF_APPROVAL_KEY_UNKNOWN, REF_APPROVAL_SIGNATURE_INVALID
+        bad_sigs = [r for r in v["entries"] if not r["accepted"] and r["reason"] in (REF_APPROVAL_SIGNATURE_INVALID, REF_APPROVAL_KEY_UNKNOWN)]
+        if bad_sigs:
+            ids = sorted({k for r in bad_sigs for k in (r.get("released_by") or [])})
+            unknown = [k for k in ids if k not in approvers]
+            stale = [k for k in ids if k in approvers]
+            print("  note: %d release(s) failed the grant check%s%s. The approver keys here come from %s; an approver who "
+                  "re-enrolled a browser key since that copy was made signs with a key it does not list. Copy the issuer's "
+                  "current approvers.json beside public-keys.json, or pass --issuer URL to fetch every key the issuer has seen."
+                  % (len(bad_sigs), (": approver id(s) not known here: %s" % ", ".join(unknown)) if unknown else "",
+                     ("; known approver(s) whose listed key does not verify the grant: %s" % ", ".join(stale)) if stale else "", out))
         rc = 0 if v["accepted"] else 1
         entries = read_log(args.log)
         if args.summary:
@@ -851,14 +907,20 @@ def cmd_audit(args) -> int:
                            if isinstance(e, dict) and isinstance(e.get("receipt"), dict) and e["receipt"].get("target_url")), None)
             r = reconcile(entries, read_witness(args.witness), principal=principal, target_url=target)
             older = [f for f in r["findings"] if f["finding"] == "PREDATES_WITNESS"]
+            before_log = [f for f in r["findings"] if f["finding"] == "PREDATES_EVIDENCE"]
             for f in r["findings"]:
-                if f["finding"] == "PREDATES_WITNESS":
+                if f["finding"] in ("PREDATES_WITNESS", "PREDATES_EVIDENCE"):
                     continue
                 print("  FINDING %-22s %s" % (f["finding"], " ".join("%s=%s" % (k, str(v)[:40]) for k, v in f.items() if k != "finding")))
             if older:
                 print("  note: %d honored row(s) predate the witness (started %s) and cannot be vouched for either way: seq %s"
                       % (len(older), (r.get("horizon") or "?")[:19], ", ".join(str(f["seq"]) for f in older[:12]) + (" ..." if len(older) > 12 else "")))
-            hard = len(r["findings"]) - len(older)
+            if before_log:
+                held_n = sum(1 for f in before_log if f.get("held"))
+                print("  note: %d receipt(s) the issuer issued to this principal predate this evidence log (first entry %s; %d of them held): "
+                      "a log that began later cannot be asked about them. If the log was not meant to start then, that is the finding."
+                      % (len(before_log), (r.get("log_start") or "?")[:19], held_n))
+            hard = len(r["findings"]) - len(older) - len(before_log)
             print("reconciled: %d issued by the issuer, %d in evidence, %d finding(s)%s"
                   % (r["issued"], r["evidence_with_receipt"], hard,
                      " (%d issued for other targets, not this gate's)" % r["issued_elsewhere"] if r.get("issued_elsewhere") else ""))
@@ -1021,7 +1083,8 @@ def main(argv=None) -> int:
     p.add_argument("--witness", help="the issuer's witness.jsonl: reconcile the evidence against it")
     p.add_argument("--check-tree", metavar="DIR", help="verify every gated file under DIR is as the gate left it")
     p.add_argument("--summary", action="store_true", help="after the rows: calls by principal and tool with outcomes, releases, clients")
-    p.add_argument("--out", default="gargoyle-deploy")
+    p.add_argument("--out", default="gargoyle-deploy", help="folder with public-keys.json and approvers.json (default: gargoyle-deploy, else the log's own folder)")
+    p.add_argument("--issuer", metavar="URL", help="fetch the issuer's keys and every approver key it has seen (GET /keys, /approvers/audit) instead of relying on a copied approvers.json")
     p.set_defaults(fn=cmd_audit)
     p = sub.add_parser("emilia", help="export an evidence log's approved calls as EMILIA Trust Receipts")
     p.add_argument("--log", required=True, help="the middleware's audit.jsonl")

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/gargoyle/evidence.py

@@ -127,6 +127,37 @@ def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any,
     return entry
 
 
+def locked(lock_path: Any):
+    """An exclusive, blocking lock on `lock_path` (POSIX flock, Windows
+    byte-range lock), released on exit. Processes that share a file on one
+    workstation, the hook's PreToolUse and PostToolUse among them, hold it
+    across their read-modify-write so neither loses the other's update."""
+    import contextlib
+
+    @contextlib.contextmanager
+    def hold():
+        with open(lock_path, "a+b") as lock:
+            try:
+                import fcntl
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+                unlock = lambda: fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+            except ImportError:                       # Windows
+                import msvcrt
+                lock.seek(0)
+                while True:
+                    try:
+                        msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)   # retries about ten seconds, then raises
+                        break
+                    except OSError:
+                        continue
+                unlock = lambda: (lock.seek(0), msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1))
+            try:
+                yield
+            finally:
+                unlock()
+    return hold()
+
+
 class EvidenceLog:
     """Appends entries to a JSON Lines file, continuing the chain found at
     its tail. Several gate processes may share one log (a Claude Code and
@@ -156,33 +187,8 @@ class EvidenceLog:
                     self._seq, self._tail = int(last["seq"]), str(last["entry_sha256"])
 
     def _locked(self):
-        """An exclusive, blocking lock on the log's lock file (POSIX flock,
-        Windows byte-range lock), released on exit."""
-        import contextlib
-
-        @contextlib.contextmanager
-        def hold():
-            lock_path = self.path.with_name(self.path.name + ".lock")
-            with open(lock_path, "a+b") as lock:
-                try:
-                    import fcntl
-                    fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
-                    unlock = lambda: fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
-                except ImportError:                       # Windows
-                    import msvcrt
-                    lock.seek(0)
-                    while True:
-                        try:
-                            msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)   # retries about ten seconds, then raises
-                            break
-                        except OSError:
-                            continue
-                    unlock = lambda: (lock.seek(0), msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1))
-                try:
-                    yield
-                finally:
-                    unlock()
-        return hold()
+        """An exclusive, blocking lock on the log's lock file, released on exit."""
+        return locked(self.path.with_name(self.path.name + ".lock"))
 
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
                receipt: Any = None, grant: Any = None, execution: Any = None,
@@ -287,8 +293,13 @@ def verify_log(
         else:
             reason = ACCEPT_ENTRY_VERIFIED
             if e["receipt"] is not None:
+                # Provenance only: a refused entry says the receipt was issued and
+                # the call did not run. It may be written long after the receipt
+                # expired (an honored call nobody came back for is reaped an hour
+                # on), so it is checked as of its own issuance, not the entry's.
+                issued_at = e["receipt"].get("timestamp_utc") if isinstance(e["receipt"], dict) else None
                 p = verify_provenance(e["receipt"], pinned_public_keys=issuer_public_keys,
-                                      now=_parse_at(e["at"]), historical=True)
+                                      now=_parse_at(issued_at if isinstance(issued_at, str) else e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         counts[e["kind"]] += 1
         plan_ref = None

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/gargoyle/issuer_service.py

@@ -777,6 +777,14 @@ def build_issuer_app(
         _notice_revocations()
         return {"approvers": registry.public_hex()}
 
+    @app.get("/approvers/audit")
+    async def approvers_audit():
+        """Public, for `gargoyle audit --issuer`: every key each approver has
+        held, current first, then replaced and revoked ones. A grant signed
+        while a key was trusted still verifies; nothing here admits a key."""
+        _notice_revocations()
+        return {"approvers": registry.audit_keys_hex()}
+
     @app.post("/approvers/enroll")
     async def enroll(request: Request, authorization: Optional[str] = Header(default=None)):
         """Bind the caller's UPN to the public key their browser generated.

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/gargoyle/mcp_server.py

@@ -888,16 +888,21 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
             # then goes through the gate exactly as the assistant's own writes.
             from gargoyle.revert import REF_REVERT_DISABLED, revert_text
             from gargoyle.state import REF_TARGET_STATE_UNREADABLE, StateUnreadable
-            if state.snapshots is None:
-                return _success(msg_id, {"content": [{"type": "text", "text": revert_text(REF_REVERT_DISABLED)}], "isError": True,
-                                         "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: REF_REVERT_DISABLED}})
             rargs = params.get("arguments") or {}
-            try:
-                plan = plan_revert(state.snapshots, str(rargs.get("decision_id") or "last"), state.adapter,
-                                   ref=rargs.get("path") if isinstance(rargs.get("path"), str) else None)
-            except StateUnreadable:
-                plan = {"reason": REF_TARGET_STATE_UNREADABLE}
+            if state.snapshots is None:
+                plan = {"reason": REF_REVERT_DISABLED}
+            else:
+                try:
+                    plan = plan_revert(state.snapshots, str(rargs.get("decision_id") or "last"), state.adapter,
+                                       ref=rargs.get("path") if isinstance(rargs.get("path"), str) else None)
+                except StateUnreadable:
+                    plan = {"reason": REF_TARGET_STATE_UNREADABLE}
             if "reason" in plan:
+                # Refused before any receipt: the trail still says the assistant
+                # asked to undo something and why it could not (the Windows
+                # acceptance run of 2026-11-02 found this refusal unrecorded).
+                _record(state, "refused", {"reason": plan["reason"], "envelope": None, "grant": None,
+                                           "ref": rargs.get("path") if isinstance(rargs.get("path"), str) else None}, params)
                 return _success(msg_id, {"content": [{"type": "text", "text": revert_text(plan["reason"])}], "isError": True,
                                          "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: plan["reason"]}})
             params = plan["params"]

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/gargoyle/reconcile.py

@@ -6,6 +6,7 @@ Findings, never silently fixed:
   UNWITNESSED_RECEIPT   evidence honors a decision the issuer never issued (forged or foreign)
   UNWITNESSED_RELEASE   a held call was honored but the issuer saw no grant for its hold (or plan)
   MISSING_EVIDENCE      the issuer issued a receipt to this principal and the client recorded nothing
+  PREDATES_EVIDENCE     issued more than the window before this log's genesis entry; the log cannot be asked about it (information)
   EVIDENCE_BEFORE_ISSUE the client's entry predates the issuer's issuance
   CHANGED_OUTSIDE_GATE  a file under the gated folder is not in the state the last gated write left it
 """
@@ -52,6 +53,17 @@ def reconcile(evidence: Iterable[Any], witness: Iterable[Any], *, principal: Opt
     findings: List[Dict[str, Any]] = []
     seen_decisions = set()
     honored_at: Dict[Any, Any] = {}          # decision_id -> seq of the entry that first honored it
+    # The evidence log's own beginning: an issuance older than its first entry
+    # is one this log was never in a position to record (a fresh install, a
+    # rotated log). Reported, counted, and kept apart from MISSING_EVIDENCE.
+    evidence = list(evidence)
+    log_start: Optional[datetime] = None
+    first = next((e for e in evidence if isinstance(e, dict)), None)
+    if first is not None and first.get("seq") == 1 and first.get("prev_sha256") == "0" * 64:
+        # Only a log that begins at its genesis entry can say when it began;
+        # a log missing its head is a chain failure, and what the head would
+        # have held stays MISSING_EVIDENCE.
+        log_start = _parse(first.get("at"))
     for e in evidence:
         if not isinstance(e, dict):
             continue
@@ -100,10 +112,16 @@ def reconcile(evidence: Iterable[Any], witness: Iterable[Any], *, principal: Opt
         if target_url is not None and isinstance(w.get("target_url"), str) and w["target_url"] != target_url:
             elsewhere += 1
             continue
-        findings.append({"finding": "MISSING_EVIDENCE", "decision_id": did, "tool": w.get("tool"), "principal": w.get("principal"),
+        at_w = _parse(w.get("at"))
+        # Every issuance precedes its own evidence entry by a little; only one
+        # older than the log's first entry by more than the window predates it.
+        kind = ("PREDATES_EVIDENCE" if (log_start is not None and at_w is not None
+                                        and (log_start - at_w).total_seconds() > window_seconds) else "MISSING_EVIDENCE")
+        findings.append({"finding": kind, "decision_id": did, "tool": w.get("tool"), "principal": w.get("principal"),
                          "held": bool(w.get("held")), "at": w.get("at")})
-    hard = [f for f in findings if f["finding"] != "PREDATES_WITNESS"]
+    hard = [f for f in findings if f["finding"] not in ("PREDATES_WITNESS", "PREDATES_EVIDENCE")]
     return {"accepted": not hard, "findings": findings, "horizon": horizon.isoformat() if horizon else None,
+            "log_start": log_start.isoformat() if log_start else None,
             "issued": len(issued), "evidence_with_receipt": len(seen_decisions), "issued_elsewhere": elsewhere}
 
 

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.20.0.dev0
+Version: 0.21.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -64,7 +64,7 @@ by whom, and what changed.
 
 ## Status
 
-Pre-release `0.20.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
+Pre-release `0.21.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
 `gargoyle/3`, evidence log `gargoyle-evidence/4`, witness
 `gargoyle-witness/1`; all three are specified in [SPEC.md](SPEC.md) and may
 still change before a first release.
@@ -91,7 +91,7 @@ against a fake Graph server); the OAuth broker for hosted connectors
 (deployed, metadata and redirect checks verified, no human sign-in through a
 connector yet).
 
-**Assurance.** 561 Python tests on Linux and Windows across Python 3.12,
+**Assurance.** 564 Python tests on Linux and Windows across Python 3.12,
 3.13 and 3.14, at dependency floors and at a lock file; a TypeScript suite
 that recomputes the conformance vectors byte for byte; two outside,
 model-driven security reviews on 2026-10-20 (ten findings, all fixed); the
@@ -378,6 +378,13 @@ enrollment, revocation and discovery report, on the operator's server.
     gargoyle audit --log audit.jsonl --witness witness.jsonl           # reconcile by decision id: unwitnessed receipts, releases without a grant, missing evidence
     gargoyle audit --log audit.jsonl --check-tree /srv/shared          # hash the gated folder against the recorded states; name files changed around the gate
     gargoyle audit --log audit.jsonl --summary                         # calls by principal and tool, side-door findings
+    gargoyle audit --log audit.jsonl --issuer https://gargoyle.lan      # take the issuer's keys and every approver key it has seen from the issuer, not from a copied file
+
+The audit needs the public keys (`public-keys.json`, by default beside the
+log or in `--out`). Grants verify against every key an approver has held,
+so an approver who re-enrolled a browser key is still audited; with
+`--issuer` that list comes from the issuer itself and a stale copy of
+`approvers.json` can no longer fail a valid grant.
 
 On a machine the user administers the gate constrains the assistant, not
 the user; these checks make the difference visible. SPEC.md section 15
@@ -661,7 +668,8 @@ receipts work unchanged. Configuration is by environment:
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`, or `gargoyle issuer`): identity token in, receipt out,
 with the hold and grant exchange for flagged calls (`/issue`, `/pending`,
-`/grants`, `/decline`, `/record`, `/keys`, `/sidedoors`) and the browser
+`/grants`, `/decline`, `/record`, `/keys`, `/approvers`, `/approvers/audit`,
+`/sidedoors`) and the browser
 approval console at `/approve`. Policy from a rules file or OPA; identity
 from a pinned key or, with `GARGOYLE_ENTRA_TENANT`, the tenant's signing
 keys (both at once when a pinned key is also set).

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/pyproject.toml

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

@@ -330,3 +330,21 @@ def test_a_revoke_inside_the_same_timestamp_tick_is_still_noticed(tmp_path):
     os.utime(path, ns=(before.st_atime_ns, before.st_mtime_ns))     # the write is invisible by mtime
     assert path.stat().st_mtime_ns == before.st_mtime_ns
     assert "dana@contoso.com" not in reg and reg.revoked_entries()["dana@contoso.com"]["revoked_by"] == "operator:root"
+
+
+def test_approvers_audit_endpoint_lists_every_key_an_approver_held(tmp_path):
+    """GET /approvers/audit is what `gargoyle audit --issuer` reads: the current
+    key first, then replaced and revoked ones, so grants signed under any of
+    them verify; GET /approvers keeps listing only the current, trusted key."""
+    reg = ApproverRegistry(str(tmp_path / "approvers.json"))
+    app = build_issuer_app(policy=Hold(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()},
+                           approver_registry=reg)
+    c = TestClient(app)
+    h = {"Authorization": "Bearer " + token("dana@contoso.com", roles=["Approver"])}
+    k1, k2 = Ed25519PrivateKey.generate(), Ed25519PrivateKey.generate()
+    assert c.post("/approvers/enroll", json={"public_key_hex": pub_hex(k1)}, headers=h).json()["enrolled"]
+    assert c.post("/approvers/revoke", json={"upn": "dana@contoso.com"}, headers=h).json() == {"revoked": True}
+    assert c.post("/approvers/enroll", json={"public_key_hex": pub_hex(k2)}, headers=h).json()["enrolled"]
+    assert c.get("/approvers").json() == {"approvers": {"dana@contoso.com": pub_hex(k2)}}
+    audit = c.get("/approvers/audit").json()["approvers"]
+    assert audit["dana@contoso.com"][0] == pub_hex(k2) and set(audit["dana@contoso.com"]) == {pub_hex(k1), pub_hex(k2)}

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/tests/test_claude_hook.py

@@ -177,3 +177,61 @@ def test_pending_store_is_bounded_and_survives_garbage(tmp_path):
     assert len(p._read()) == 200 and "t4" not in p._read() and "t204" in p._read()
     assert len(p.reap(now=1000.0, max_age=800.0)) == 195
     assert p.pop("t204")["params"]["name"] == "Read" and p.pop("t204") is None
+
+
+def test_post_event_input_differs_from_pre_and_the_entry_still_matches_the_receipt(tmp_path, monkeypatch):
+    # Claude Code presents some tools' input differently in PostToolUse than
+    # in PreToolUse (seen live with Artifact). The receipt bound what the gate
+    # saw; the honored entry must hash those arguments or the audit reports
+    # REF_EVIDENCE_RECEIPT_MISSING for a call that was gated correctly.
+    out, project, env, state, client = deployment(tmp_path, monkeypatch)
+    decide(event(PRE, "Bash", {"command": "true"}, "toolu_1"), state())
+    decide(event(POST, "Bash", {"command": "true", "description": "added afterwards"}, "toolu_1", tool_response={"stdout": ""}), state())
+    entries = read_log(env["GARGOYLE_MCP_AUDIT_LOG"])
+    assert [(e["kind"], e["tool"]) for e in entries] == [("honored", "Bash")]
+    assert entries[0]["args_sha256"] == entries[0]["receipt"]["request_context"]["args_sha256"]
+    assert main(["audit", "--log", env["GARGOYLE_MCP_AUDIT_LOG"], "--out", str(out)]) == 0
+
+
+def test_reaped_entry_written_after_the_receipt_expired_still_verifies(tmp_path, monkeypatch):
+    # An honored receipt nobody came back for is reaped REAP_SECONDS later,
+    # long after its TTL. The refused entry carries it as provenance of what
+    # was gated; it is checked as of issuance, not as of the entry.
+    import datetime as dt
+    from gargoyle import evidence as ev
+    out, project, env, state, client = deployment(tmp_path, monkeypatch)
+    decide(event(PRE, "Bash", {"command": "true"}, "toolu_1"), state(), now=1000.0)
+    later = dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=REAP_SECONDS + 1)
+
+    class Clock(dt.datetime):
+        @classmethod
+        def now(cls, tz=None):
+            return later if tz is not None else later.replace(tzinfo=None)
+    monkeypatch.setattr(ev, "datetime", Clock)
+    decide(event(PRE, "Read", {"file_path": str(project / "a.txt")}, "toolu_2"), state(), now=1000.0 + REAP_SECONDS + 1)
+    monkeypatch.undo()
+    entries = read_log(env["GARGOYLE_MCP_AUDIT_LOG"])
+    reaped = [e for e in entries if e["reason"] == REF_HOOK_NOT_RUN]
+    assert len(reaped) == 1 and reaped[0]["at"] > reaped[0]["receipt"]["not_after"]
+    # The audit exits 1 when any entry fails verification.
+    assert main(["audit", "--log", env["GARGOYLE_MCP_AUDIT_LOG"], "--out", str(out)]) == 0
+
+
+def test_pending_store_survives_concurrent_hooks(tmp_path):
+    # Parallel tool calls run their Pre and Post hooks as separate processes
+    # at once. Without the lock a put can overwrite a concurrent pop (the
+    # honored receipt comes back and is reaped as never run) or a concurrent
+    # put (a call that ran leaves no evidence row).
+    import threading
+    p = PendingReceipts(str(tmp_path / "audit.hook-pending.json"))
+    gate = {"envelope": {"decision_id": "d"}, "grant": None, "self_issued": True, "reason": "ok", "ref": None}
+    ids = ["t%d" % i for i in range(120)]
+    threads = [threading.Thread(target=p.put, args=(i, gate, {"name": "Bash", "arguments": {}}, 1.0)) for i in ids]
+    for t in threads: t.start()
+    for t in threads: t.join()
+    assert sorted(p._read()) == sorted(ids)
+    popped = []
+    threads = [threading.Thread(target=lambda i=i: popped.append(p.pop(i))) for i in ids]
+    for t in threads: t.start()
+    for t in threads: t.join()
+    assert len(popped) == 120 and all(g is not None for g in popped) and p._read() == {}

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/tests/test_revert.py

@@ -137,5 +137,14 @@ def test_revert_restores_an_approved_write_through_the_gate(tmp_path):
         assert call(state, 6, "write_file", {"path": str(new), "content": "x"})["result"]["_meta"][EXECUTED_META_KEY]
         r = call(state, 7, REVERT_TOOL, {"decision_id": "last"})
         assert r["result"]["_meta"][REASON_META_KEY] == REF_REVERT_NEEDS_DELETE and new.exists()
+
+        # Both refusals are in the trail: the assistant asked to undo, and why it could not.
+        log = read_log(str(tmp_path / "audit.jsonl"))
+        refused = [(e["tool"], e["reason"]) for e in log if e["kind"] == "refused"]
+        assert refused == [(REVERT_TOOL, REF_REVERT_STATE_CHANGED), (REVERT_TOOL, REF_REVERT_NEEDS_DELETE)]
+        assert log[-1]["receipt"] is None and log[-1]["principal"]
+        v = verify_log(log, issuer_public_keys={"issuer-1": issuer.public_key()},
+                       executor_public_keys={"executor-1": executor.public_key()}, approver_public_keys={"approver-1": approver.public_key()})
+        assert v["accepted"] and v["refused"] == 2
     finally:
         up.close()

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/tests/test_review_fixes.py

@@ -134,7 +134,7 @@ def test_every_path_after_the_claim_leaves_evidence(tmp_path, capsys):
     assert report["accepted"] and [e["verdict"] for e in report["entries"]][:3] == [TOOL_ERROR, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE]
     _audit_summary(report["entries"], log)
     out = capsys.readouterr().out
-    assert "failed" in out and "%-24s %7d %7d %7d" % ("write_file", 1, 3, 0) in out
+    assert "errored" in out and "upstream reported an error" in out and "%-24s %7d %7d %7d" % ("write_file", 1, 3, 0) in out
     # The spent receipts are spent: a retry of the failed one is a replay.
     again = handle_message(state, _call(envs[0], {"path": "/gargoyle-test-root/f0"}, 5))
     assert again["result"]["_meta"][REASON_META_KEY] == REF_VERIFY_REPLAY

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.21.0.dev0}/tests/test_witness.py

@@ -133,6 +133,15 @@ def test_honest_evidence_reconciles_and_tampering_is_found(tmp_path):
     # 3. A receipt the issuer issued but the client never recorded: drop the client's read entry.
     r = reconcile([e for e in evidence if e["tool"] != "read_file"], witness, principal=PRINCIPAL)
     assert [f["finding"] for f in r["findings"]] == ["MISSING_EVIDENCE"] and r["findings"][0]["tool"] == "read_file"
+    # An issuance older than the log's first entry is one this log could never have recorded:
+    # information with a count, not a failure (a fresh install, a rotated log).
+    ancient = dict([w for w in witness if w["event"] == "issued"][0], decision_id="d-ancient",
+                   at=(datetime.fromisoformat(evidence[0]["at"]) - timedelta(days=2)).isoformat())
+    r = reconcile(evidence, witness + [ancient], principal=PRINCIPAL)
+    assert r["accepted"] and [f["finding"] for f in r["findings"]] == ["PREDATES_EVIDENCE"] and r["log_start"] == evidence[0]["at"]
+    later = dict(ancient, decision_id="d-later", at=(datetime.fromisoformat(evidence[0]["at"]) + timedelta(seconds=1)).isoformat())
+    r = reconcile(evidence, witness + [later], principal=PRINCIPAL)
+    assert not r["accepted"] and [f["finding"] for f in r["findings"]] == ["MISSING_EVIDENCE"]
 
     # The tree: as the gate left it, then edited behind its back, then deleted.
     t = check_tree(evidence, str(root))
@@ -231,3 +240,44 @@ def test_reconciliation_is_scoped_to_the_evidence_logs_target(tmp_path):
     assert [f["finding"] for f in r["findings"]] == ["MISSING_EVIDENCE"]
     r = reconcile(evidence, witness + [legacy], principal=PRINCIPAL, target_url=TARGET)   # no target on record: reported
     assert [f["finding"] for f in r["findings"]] == ["MISSING_EVIDENCE"] and r["issued_elsewhere"] == 0
+
+
+def test_audit_finds_its_keys_beside_the_log_and_can_take_approver_keys_from_the_issuer(tmp_path, capsys, monkeypatch):
+    """A workstation's keys sit beside audit.jsonl; a wrong --out is not a
+    traceback. A grant signed by a key the local approvers copy does not list
+    fails with a note that says so; --issuer fetches the issuer's full list."""
+    root = tmp_path / "root"; root.mkdir(); (root / "n.md").write_text("one\n", encoding="utf-8", newline="\n")
+    state, up, c, h, w = _rig(tmp_path, root)
+    try:
+        assert call(state, 2, "write_file", {"path": str(root / "n.md"), "content": "two\n"})["_meta"][EXECUTED_META_KEY]
+    finally:
+        up.close()
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+    hexpub = lambda k: k.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw).hex()
+    from gargoyle.cli import main
+    log = str(tmp_path / "audit.jsonl")
+    # No keys anywhere: a usage error, not a traceback.
+    monkeypatch.chdir(tmp_path)
+    assert main(["audit", "--log", log]) == 2
+    assert "public-keys.json not found" in capsys.readouterr().err
+    # Keys beside the log, --out left at its default: found.
+    (tmp_path / "public-keys.json").write_text(json.dumps({"issuer": {"issuer-1": hexpub(issuer)}, "executor": {"executor-1": hexpub(executor)},
+                                                            "approver": {"approver-1": hexpub(approver)}}))
+    assert main(["audit", "--log", log]) == 0
+    # The local copy does not know the approver's key: the release fails, and the note says what to do.
+    (tmp_path / "public-keys.json").write_text(json.dumps({"issuer": {"issuer-1": hexpub(issuer)}, "executor": {"executor-1": hexpub(executor)},
+                                                            "approver": {}}))
+    assert main(["audit", "--log", log]) == 1
+    text = capsys.readouterr().out
+    assert "REF_APPROVAL_KEY_UNKNOWN" in text and "not known here: approver-1" in text and "--issuer URL" in text
+    # The copy knows the approver under an older key (the Windows run of 2026-11-02): named as stale, same remedy.
+    (tmp_path / "public-keys.json").write_text(json.dumps({"issuer": {"issuer-1": hexpub(issuer)}, "executor": {"executor-1": hexpub(executor)},
+                                                            "approver": {"approver-1": hexpub(Ed25519PrivateKey.generate())}}))
+    assert main(["audit", "--log", log]) == 1
+    text = capsys.readouterr().out
+    assert "REF_APPROVAL_SIGNATURE_INVALID" in text and "listed key does not verify the grant: approver-1" in text
+    # --issuer: the issuer's list (current key plus history) stands in for the copy.
+    import gargoyle.cli as cli
+    monkeypatch.setattr(cli, "_issuer_trust", lambda url: ({"issuer-1": hexpub(issuer)}, {"approver-1": [hexpub(Ed25519PrivateKey.generate()), hexpub(approver)]}))
+    assert main(["audit", "--log", log, "--issuer", "https://issuer.test"]) == 0
+    assert "0 failed" in capsys.readouterr().out