gargoyle-receipts 0.13.0.dev0__tar.gz → 0.14.1.dev0__tar.gz

{gargoyle_receipts-0.13.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.14.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.13.0.dev0
+Version: 0.14.1.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.13.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.14.1.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
@@ -240,6 +240,17 @@ its initialize handshake, so a fleet with Claude on some desks and ChatGPT
 on others still has one trail that says who, through what, did what. The
 receipt itself stays model-agnostic.
 
+The evidence is the workstation's own statement, and the workstation
+belongs to its user. So the issuer keeps a witness: a signed, hash-chained
+record of every receipt it issued and every grant it accepted, on the
+operator's server. `gargoyle audit --witness` reconciles the two by
+decision id and names what does not agree: a receipt the issuer never
+issued, a held call honored without a grant the issuer saw, a receipt
+issued with no evidence recorded. `--check-tree` hashes the gated folder
+against the evidence's recorded states and names any file changed around
+the gate. On a machine the user administers the gate constrains the
+assistant, not the user; these two checks make the difference visible.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -369,6 +380,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
+| issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.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.13.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.14.1.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
@@ -202,6 +202,17 @@ its initialize handshake, so a fleet with Claude on some desks and ChatGPT
 on others still has one trail that says who, through what, did what. The
 receipt itself stays model-agnostic.
 
+The evidence is the workstation's own statement, and the workstation
+belongs to its user. So the issuer keeps a witness: a signed, hash-chained
+record of every receipt it issued and every grant it accepted, on the
+operator's server. `gargoyle audit --witness` reconciles the two by
+decision id and names what does not agree: a receipt the issuer never
+issued, a held call honored without a grant the issuer saw, a receipt
+issued with no evidence recorded. `--check-tree` hashes the gated folder
+against the evidence's recorded states and names any file changed around
+the gate. On a machine the user administers the gate constrains the
+assistant, not the user; these two checks make the difference visible.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -331,6 +342,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
+| issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0}/gargoyle/cli.py

@@ -290,6 +290,7 @@ def cmd_issuer(args) -> int:
     os.environ.update(_read_env(out / "issuer.env"))
     os.environ.setdefault("GARGOYLE_APPROVERS_PATH", str(out / "approvers.json"))   # enrolled approvers live beside the keys
     os.environ.setdefault("GARGOYLE_HOLDS_PATH", str(out / "holds.sqlite"))          # holds, grants, declines, plans survive restarts
+    os.environ.setdefault("GARGOYLE_WITNESS_PATH", str(out / "witness.jsonl"))       # the issuer's signed record, for reconciliation
     os.environ.setdefault("GARGOYLE_LOG_JSON", "1")
     app = app_from_env()
     # The middleware reads the policy pin from a file; write it next to the
@@ -358,7 +359,35 @@ 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]))
-        return 0 if v["accepted"] else 1
+        rc = 0 if v["accepted"] else 1
+        entries = read_log(args.log)
+        if args.witness and not Path(args.witness).exists():
+            print("witness file not found: %s (copy the issuer's witness.jsonl here first)" % args.witness, file=sys.stderr)
+            return 2
+        if args.check_tree and not Path(args.check_tree).is_dir():
+            print("not a directory: %s" % args.check_tree, file=sys.stderr)
+            return 2
+        if args.witness:
+            # The issuer's signed record: the client's evidence must agree with it.
+            from gargoyle.reconcile import reconcile
+            from gargoyle.witness import read_witness, verify_witness
+            w = verify_witness(read_witness(args.witness), issuer_public_keys=trust["issuer_public_keys"])
+            print("witness: %d entries, %s, tail %s" % (w["count"], w["reason"], w["tail_sha256"][:16]))
+            principal = next((e.get("principal") for e in entries if isinstance(e, dict) and e.get("principal")), None)
+            r = reconcile(entries, read_witness(args.witness), principal=principal)
+            for f in r["findings"]:
+                print("  FINDING %-22s %s" % (f["finding"], " ".join("%s=%s" % (k, str(v)[:40]) for k, v in f.items() if k != "finding")))
+            print("reconciled: %d issued by the issuer, %d in evidence, %d finding(s)" % (r["issued"], r["evidence_with_receipt"], len(r["findings"])))
+            rc = rc or (0 if (w["accepted"] and r["accepted"]) else 1)
+        if args.check_tree:
+            # Every file the gate wrote must still be as the gate left it.
+            from gargoyle.reconcile import check_tree
+            t = check_tree(entries, args.check_tree)
+            for f in t["findings"]:
+                print("  FINDING %-22s %s%s" % (f["finding"], f["path"], " (missing)" if f.get("missing") else ""))
+            print("tree: %d gated file(s) checked, %d untouched by the gate, %d changed outside it" % (t["checked"], t["untouched"], len(t["findings"])))
+            rc = rc or (0 if t["accepted"] else 1)
+        return rc
     receipt, execution = json.load(open(args.receipt)), json.load(open(args.execution))
     grant = json.load(open(args.grant)) if args.grant else None
     result = verify_chain(receipt, execution, grant=grant, **trust)
@@ -424,6 +453,8 @@ def main(argv=None) -> int:
     p = sub.add_parser("audit", help="verify a receipt chain offline, or a whole evidence log")
     p.add_argument("receipt", nargs="?"); p.add_argument("execution", nargs="?"); p.add_argument("grant", nargs="?")
     p.add_argument("--log", help="the middleware's audit.jsonl: verify every entry")
+    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("--out", default="gargoyle-deploy")
     p.set_defaults(fn=cmd_audit)
     args = parser.parse_args(argv)

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0}/gargoyle/evidence.py

@@ -48,9 +48,9 @@ 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/3"          # version 3 adds `client`; hashes over RFC 8785 canonical JSON
+EVIDENCE_VERSION = "gargoyle-evidence/4"          # 3 added `client`, 4 adds `ref`; hashes over RFC 8785 canonical JSON
 EVIDENCE_VERSIONS = {"gargoyle-evidence/1": canonical_json_legacy, "gargoyle-evidence/2": canonical_json,
-                     EVIDENCE_VERSION: canonical_json}
+                     "gargoyle-evidence/3": canonical_json, EVIDENCE_VERSION: canonical_json}
 GENESIS = "0" * 64
 
 HONORED = "honored"
@@ -71,6 +71,11 @@ _FIELDS = ("evidence_version", "seq", "prev_sha256", "at", "kind", "tool", "args
 # receipt stays model-agnostic: this is evidence about the session, not a
 # bound field of the decision.
 _FIELDS_V3 = _FIELDS + ("client",)
+# Version 4 adds `ref`: what the adapter examined for a state-bound call (a
+# file path, "mailRule:<id>"), or null. With it a folder can be checked
+# against the evidence without any plaintext (gargoyle.reconcile.check_tree).
+_FIELDS_V4 = _FIELDS_V3 + ("ref",)
+_FIELDS_BY_VERSION = {"gargoyle-evidence/3": _FIELDS_V3, "gargoyle-evidence/4": _FIELDS_V4}
 
 
 def entry_sha256(entry: Dict[str, Any]) -> str:
@@ -84,11 +89,13 @@ def entry_sha256(entry: Dict[str, Any]) -> str:
 
 def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any, principal: str,
                 reason: str, receipt: Any = None, grant: Any = None, execution: Any = None,
-                at: Optional[datetime] = None, client: Optional[str] = None) -> Dict[str, Any]:
+                at: Optional[datetime] = None, client: Optional[str] = None, ref: Optional[str] = None) -> Dict[str, Any]:
     if kind not in (HONORED, REFUSED):
         raise ValueError("kind must be honored or refused")
     if client is not None and not isinstance(client, str):
         raise ValueError("client must be a string or None")
+    if ref is not None and not isinstance(ref, str):
+        raise ValueError("ref must be a string or None")
     entry = {
         "evidence_version": EVIDENCE_VERSION,
         "seq": seq,
@@ -103,6 +110,7 @@ def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any,
         "grant": grant,
         "execution": execution,
         "client": client,
+        "ref": ref,
     }
     entry["entry_sha256"] = entry_sha256(entry)
     return entry
@@ -131,14 +139,14 @@ class EvidenceLog:
 
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
                receipt: Any = None, grant: Any = None, execution: Any = None,
-               client: Optional[str] = None) -> Dict[str, Any]:
+               client: Optional[str] = None, ref: Optional[str] = None) -> Dict[str, Any]:
         """Write one entry and return it. Raises OSError if the file cannot
         be written; the caller decides whether that stops the call."""
         if self._seq is None:
             self._load_tail()
         entry = build_entry(seq=self._seq + 1, prev_sha256=self._tail, kind=kind, tool=tool, args=args,
                             principal=principal, reason=reason, receipt=receipt, grant=grant, execution=execution,
-                            client=client)
+                            client=client, ref=ref)
         with open(self.path, "a", encoding="utf-8") as f:
             f.write(json.dumps(entry, sort_keys=True) + "\n")
         self._seq, self._tail = entry["seq"], entry["entry_sha256"]
@@ -146,10 +154,11 @@ class EvidenceLog:
 
 
 def _well_formed(entry: Any) -> bool:
-    expected = _FIELDS_V3 if isinstance(entry, dict) and entry.get("evidence_version") == EVIDENCE_VERSION else _FIELDS
+    expected = _FIELDS_BY_VERSION.get(entry.get("evidence_version"), _FIELDS) if isinstance(entry, dict) else _FIELDS
     return (isinstance(entry, dict) and set(entry) == set(expected)
             and entry["evidence_version"] in EVIDENCE_VERSIONS
             and (entry.get("client") is None or isinstance(entry.get("client"), str))
+            and (entry.get("ref") is None or isinstance(entry.get("ref"), str))
             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)
@@ -192,7 +201,7 @@ def verify_log(
             rc = rc if isinstance(rc, dict) else {}
             report.append({"seq": None, "kind": None, "tool": rc.get("tool"), "principal": rc.get("principal"),
                            "accepted": False, "reason": REF_EVIDENCE_UNCHAINED if legacy else REF_EVIDENCE_MALFORMED,
-                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None})
+                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None, "ref": None})
             all_ok = False
             continue
         e = raw
@@ -230,7 +239,7 @@ def verify_log(
                  if ex.get("pre_state_sha256") or ex.get("post_state_sha256") else None)
         report.append({"seq": e["seq"], "kind": e["kind"], "tool": e["tool"], "principal": e["principal"],
                        "accepted": ok, "reason": reason, "verdict": e["reason"], "released_by": released_by,
-                       "state": state, "client": e.get("client"), "plan": plan_ref})
+                       "state": state, "client": e.get("client"), "plan": plan_ref, "ref": e.get("ref")})
         all_ok = all_ok and ok
         # The chain continues from what the file says, so one bad entry is
         # reported once rather than cascading into every later one.

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0}/gargoyle/issuer_service.py

@@ -55,6 +55,7 @@ from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_
 from gargoyle.envelope import approval_terms
 from gargoyle.state import state_sha256, valid_description
 from gargoyle.holdstore import ENV_HOLDS_PATH, HoldStore
+from gargoyle.witness import WitnessLog
 from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF_PLAN_STEP_REFUSED, build_plan,
                             sign_plan, valid_step)
 from gargoyle.notify import notifier_from_env
@@ -104,6 +105,7 @@ def build_issuer_app(
     console_entra: Optional[Dict[str, str]] = None,
     hold_store: Optional[HoldStore] = None,
     log_events: Optional[Callable[[Dict[str, Any]], None]] = None,
+    witness: Optional[WitnessLog] = None,
 ) -> FastAPI:
     """`on_hold(envelope, args)` is called once for every new hold (gargoyle.notify
     posts it to a webhook); it is notice, not admission, and its failure
@@ -123,12 +125,21 @@ def build_issuer_app(
 
     def event(kind: str, **fields: Any) -> None:
         """One structured line per decision the service makes, for the
-        operator's log; never the admission path."""
+        operator's log, and one signed entry in the witness log (gargoyle.witness),
+        the independent record the client's evidence is reconciled against.
+        Neither is the admission path."""
         if log_events is not None:
             try:
                 log_events({"event": kind, "at": now().isoformat(), **fields})
             except Exception:
                 pass
+        if witness is not None:
+            try:
+                witness.record(kind, **fields)
+            except Exception as exc:
+                import sys as _sys
+                _sys.stderr.write("gargoyle: witness log unwritable: %s\n" % exc)
+    app.state.witness = witness
     registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
     static_approvers = dict(approver_public_keys or {})
 
@@ -200,7 +211,8 @@ def build_issuer_app(
                     covered = True
                     break
         event("issued", principal=who["principal"], tool=body["tool"], held=bool(result.envelope["requires_approval"]),
-              covered=covered, decision_id=result.envelope.get("decision_id"))
+              covered=covered, decision_id=result.envelope.get("decision_id"), decision_sha256=result.envelope["decision_sha256"],
+              approval_request_id=result.envelope.get("approval_request_id"), args_sha256=result.envelope["request_context"]["args_sha256"])
         if result.envelope["requires_approval"] and not covered:
             arid = result.envelope["approval_request_id"]
             app.state.pending[arid] = result.envelope
@@ -408,6 +420,12 @@ def build_issuer_app(
         return {"principal": upn, "may_approve": may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers,
                 "enrolled_public_key_hex": registry.public_hex().get(upn)}
 
+    @app.get("/witness")
+    async def witness_entries(authorization: Optional[str] = Header(default=None)):
+        """The issuer's signed witness log, for reconciliation with a client's evidence."""
+        authenticate(authorization)
+        return {"entries": list(witness.entries) if witness is not None else []}
+
     @app.get("/health")
     async def health():
         """Public, for a monitor: the service is up, which policy it runs,
@@ -492,6 +510,8 @@ def app_from_env() -> FastAPI:
         ttl_seconds=int(os.environ.get(ENV_RECEIPT_TTL, DEFAULT_TTL_SECONDS)),
         on_hold=notifier_from_env(os.environ),
         hold_store=HoldStore(os.environ.get(ENV_HOLDS_PATH) or None),
+        witness=(WitnessLog(os.environ["GARGOYLE_WITNESS_PATH"], Ed25519PrivateKey.from_private_bytes(bytes.fromhex(required[ENV_ISSUER_KEY_HEX])),
+                            required[ENV_ISSUER_KEY_ID]) if os.environ.get("GARGOYLE_WITNESS_PATH") else None),
         log_events=(lambda e: sys.stderr.write(json.dumps(e, sort_keys=True) + "\n")) if os.environ.get("GARGOYLE_LOG_JSON") else None,
         approver_registry=ApproverRegistry(os.environ.get(ENV_APPROVERS_PATH)),
         approver_role=os.environ.get(ENV_APPROVER_ROLE, DEFAULT_APPROVER_ROLE),

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0}/gargoyle/mcp_server.py

@@ -364,10 +364,12 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     """{"executed", "reason", "envelope", "grant", "self_issued"}: the
     receipt and grant that were honored, whether the client brought them or
     this server obtained them."""
+    gate_ref: Dict[str, Any] = {"ref": None}
+
     def refused(reason, envelope=None):
         # A refusal keeps the receipt when there was one (a hold the human
         # declined or let lapse), so the evidence log can show what was asked.
-        return {"executed": False, "reason": reason, "envelope": envelope, "grant": None, "self_issued": False}
+        return {"executed": False, "reason": reason, "envelope": envelope, "grant": None, "self_issued": False, "ref": gate_ref["ref"]}
     if state.consumer is None:
         return refused(REF_TARGET_NOT_CONFIGURED)
 
@@ -385,6 +387,8 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         # target's current state goes with the request (gargoyle.state), so
         # a hold is approved against it and bound to it.
         probed = state.adapter.probe(name, args) if state.adapter is not None else None
+        if probed is not None:
+            gate_ref["ref"] = probed[0].get("ref")
         # An approved plan may already cover this call; say so, and the
         # issuer opens no hold for it.
         release = _plan_release_for(state, name, args)
@@ -435,9 +439,11 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         except Exception as exc:
             sys.stderr.write("gargoyle: snapshot failed: %s\n" % exc)
 
+    if now_probe is not None:
+        gate_ref["ref"] = now_probe[0].get("ref")
     state.executed.append({"tool": name, "args": args})  # THE side effect
     return {"executed": True, "reason": verdict.reason, "envelope": envelope, "grant": grant,
-            "self_issued": self_issued}
+            "self_issued": self_issued, "ref": gate_ref["ref"]}
 
 
 def _plan_release_for(state: ServerState, tool: str, args: Any) -> Optional[Dict[str, Any]]:
@@ -524,7 +530,7 @@ def _record(state: ServerState, kind: str, gate: Dict[str, Any], params: Dict[st
     try:
         state.evidence.append(kind, str(params.get("name")), params.get("arguments", {}), principal,
                               gate["reason"], receipt=gate["envelope"], grant=gate["grant"], execution=execution,
-                              client=state.client)
+                              client=state.client, ref=gate.get("ref"))
     except (OSError, ValueError) as exc:
         sys.stderr.write("gargoyle: evidence log unwritable: %s\n" % exc)
 

gargoyle_receipts-0.14.1.dev0/gargoyle/reconcile.py

@@ -0,0 +1,130 @@
+"""Reconciliation: the client's evidence against the issuer's witness, and
+the gated folder against the evidence.
+
+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
+  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
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+from gargoyle.state import describe, state_sha256
+
+
+def _parse(ts: Any) -> Optional[datetime]:
+    try:
+        return datetime.fromisoformat(ts)
+    except (TypeError, ValueError):
+        return None
+
+
+def reconcile(evidence: Iterable[Any], witness: Iterable[Any], *, principal: Optional[str] = None,
+              window_seconds: float = 5.0) -> Dict[str, Any]:
+    """Compare verified evidence entries with verified witness entries.
+    `principal` limits MISSING_EVIDENCE to receipts issued to that
+    principal (the evidence log is one executor's); None means every
+    principal in the witness."""
+    issued: Dict[str, Dict[str, Any]] = {}
+    granted: Dict[str, List[Dict[str, Any]]] = {}
+    plan_granted: Dict[str, List[Dict[str, Any]]] = {}
+    for w in witness:
+        if not isinstance(w, dict):
+            continue
+        if w.get("event") == "issued" and isinstance(w.get("decision_id"), str):
+            issued[w["decision_id"]] = w
+        elif w.get("event") == "granted" and isinstance(w.get("approval_request_id"), str):
+            (plan_granted if w.get("hold_kind") == "plan" else granted).setdefault(w["approval_request_id"], []).append(w)
+
+    findings: List[Dict[str, Any]] = []
+    seen_decisions = set()
+    for e in evidence:
+        if not isinstance(e, dict):
+            continue
+        receipt = e.get("receipt") if isinstance(e.get("receipt"), dict) else None
+        if receipt is None:
+            continue
+        did = receipt.get("decision_id")
+        seen_decisions.add(did)
+        w = issued.get(did)
+        if e.get("kind") == "honored":
+            if w is None:
+                findings.append({"finding": "UNWITNESSED_RECEIPT", "seq": e.get("seq"), "decision_id": did, "tool": e.get("tool")})
+                continue
+            if w.get("decision_sha256") != receipt.get("decision_sha256") or w.get("principal") != receipt.get("request_context", {}).get("principal"):
+                findings.append({"finding": "UNWITNESSED_RECEIPT", "seq": e.get("seq"), "decision_id": did, "tool": e.get("tool")})
+                continue
+            if receipt.get("requires_approval"):
+                g = e.get("grant")
+                arid = receipt.get("approval_request_id")
+                if isinstance(g, dict) and "plan" in g:
+                    pid = (g.get("plan") or {}).get("approval_request_id")
+                    if pid not in plan_granted:
+                        findings.append({"finding": "UNWITNESSED_RELEASE", "seq": e.get("seq"), "decision_id": did, "tool": e.get("tool"), "plan": True})
+                elif arid not in granted:
+                    findings.append({"finding": "UNWITNESSED_RELEASE", "seq": e.get("seq"), "decision_id": did, "tool": e.get("tool")})
+            at_e, at_w = _parse(e.get("at")), _parse(w.get("at"))
+            if at_e and at_w and (at_w - at_e).total_seconds() > window_seconds:
+                findings.append({"finding": "EVIDENCE_BEFORE_ISSUE", "seq": e.get("seq"), "decision_id": did})
+    for did, w in issued.items():
+        if did in seen_decisions:
+            continue
+        if principal is not None and w.get("principal") != principal:
+            continue
+        findings.append({"finding": "MISSING_EVIDENCE", "decision_id": did, "tool": w.get("tool"), "principal": w.get("principal"),
+                         "held": bool(w.get("held")), "at": w.get("at")})
+    return {"accepted": not findings, "findings": findings,
+            "issued": len(issued), "evidence_with_receipt": len(seen_decisions)}
+
+
+def check_tree(evidence: Iterable[Any], root: str) -> Dict[str, Any]:
+    """Every file under `root` that the evidence has a post-state for must
+    be in that state now; files the gate never touched are counted, not
+    judged. A file whose last recorded state says it existed but which is
+    gone is reported too."""
+    last: Dict[str, Dict[str, Any]] = {}
+    for e in evidence:
+        if not isinstance(e, dict) or e.get("kind") != "honored":
+            continue
+        ex = e.get("execution") if isinstance(e.get("execution"), dict) else None
+        rc = (e.get("receipt") or {}).get("request_context") if isinstance(e.get("receipt"), dict) else None
+        if ex is None or not ex.get("post_state_sha256") or not rc:
+            continue
+        ref = None
+        meta = e.get("grant") if isinstance(e.get("grant"), dict) else None
+        # The ref is the path the call changed: from the plan release's args, or
+        # the snapshot sidecar is not in evidence, so recover it from the
+        # arguments the executor recorded when it could, else skip.
+        args = (meta or {}).get("args") if meta and "plan" in meta else None
+        if isinstance(args, dict):
+            ref = args.get("path") or args.get("source")
+        if ref is None:
+            ref = e.get("ref")
+        if ref is None:
+            continue
+        last[ref] = {"post": ex["post_state_sha256"], "seq": e.get("seq")}
+    findings, checked, untouched = [], 0, 0
+    for dirpath, _, files in os.walk(root):
+        for name in files:
+            p = os.path.join(dirpath, name)
+            rec = last.get(p)
+            if rec is None:
+                untouched += 1
+                continue
+            checked += 1
+            try:
+                data = open(p, "rb").read()
+            except OSError:
+                data = None
+            now = state_sha256(describe(p, data, with_text=False))
+            if now != rec["post"]:
+                findings.append({"finding": "CHANGED_OUTSIDE_GATE", "path": p, "last_gated_seq": rec["seq"]})
+    for p, rec in last.items():
+        if str(Path(p)).startswith(str(Path(root))) and not os.path.exists(p):
+            findings.append({"finding": "CHANGED_OUTSIDE_GATE", "path": p, "last_gated_seq": rec["seq"], "missing": True})
+    return {"accepted": not findings, "findings": findings, "checked": checked, "untouched": untouched}

gargoyle_receipts-0.14.1.dev0/gargoyle/witness.py

@@ -0,0 +1,128 @@
+"""The issuer's witness log: an independent record to check the client's evidence against.
+
+The evidence log (gargoyle.evidence) is the executor's own statement, and
+the executor is the workstation, where the user administers the machine
+and holds the executor key. The issuer is a different party on a server
+the operator controls. It records, signed with the issuer key and
+hash-chained, every receipt it issued, every grant it accepted, every
+decline and every plan. Reconciling the two (gargoyle.reconcile) turns the
+client's evidence from a self-report into a report checked against a
+witness: evidence for a decision the issuer never issued is a forgery, a
+held call honored without a grant the issuer saw is a bypass, a receipt
+issued with no evidence at all is a gap.
+
+    entry = {
+      "witness_version": "gargoyle-witness/1",
+      "seq": n, "prev_sha256": ..., "at": ...,
+      "event": "issued" | "refused" | "granted" | "declined" | "plan" | "plan_granted",
+      <fields per event>,
+      "entry_sha256": sha256(canonical_json(entry minus entry_sha256, issuer_key_id, issuer_signature)),
+      "issuer_key_id": ..., "issuer_signature": ed25519 over canonical_json(entry minus issuer_signature)
+    }
+"""
+
+import hashlib
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+from gargoyle.envelope import canonical_json
+
+WITNESS_VERSION = "gargoyle-witness/1"
+GENESIS = "0" * 64
+_HASH_EXCLUDED = ("entry_sha256", "issuer_key_id", "issuer_signature")
+
+REF_WITNESS_MALFORMED = "REF_WITNESS_MALFORMED"
+REF_WITNESS_HASH_MISMATCH = "REF_WITNESS_HASH_MISMATCH"
+REF_WITNESS_CHAIN_BROKEN = "REF_WITNESS_CHAIN_BROKEN"
+REF_WITNESS_KEY_UNKNOWN = "REF_WITNESS_KEY_UNKNOWN"
+REF_WITNESS_SIGNATURE_INVALID = "REF_WITNESS_SIGNATURE_INVALID"
+ACCEPT_WITNESS_VERIFIED = "WITNESS_VERIFIED"
+
+
+def entry_sha256(entry: Dict[str, Any]) -> str:
+    body = {k: v for k, v in entry.items() if k not in _HASH_EXCLUDED}
+    return hashlib.sha256(canonical_json(body).encode("utf-8")).hexdigest()
+
+
+class WitnessLog:
+    """Append-only, one JSON line per event, each signed by the issuer."""
+
+    def __init__(self, path: Optional[str], signing_key: Any, key_id: str) -> None:
+        self.path = Path(path) if path else None
+        self._key, self._kid = signing_key, key_id
+        self._lock = threading.Lock()
+        self._seq = 0
+        self._tail = GENESIS
+        self.entries: List[Dict[str, Any]] = []          # kept in memory too, for tests and GET /witness
+        if self.path is not None and self.path.exists():
+            for line in self.path.read_text(encoding="utf-8").splitlines():
+                if line.strip():
+                    e = json.loads(line)
+                    self.entries.append(e)
+                    self._seq, self._tail = int(e["seq"]), e["entry_sha256"]
+        elif self.path is not None:
+            # Exists from the first start, so an operator can copy it before
+            # the first decision and a monitor can see it is in place.
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.touch()
+
+    def record(self, event: str, **fields: Any) -> Dict[str, Any]:
+        with self._lock:
+            entry: Dict[str, Any] = {"witness_version": WITNESS_VERSION, "seq": self._seq + 1, "prev_sha256": self._tail,
+                                     "at": datetime.now(timezone.utc).isoformat(), "event": event, **fields}
+            entry["entry_sha256"] = entry_sha256(entry)
+            entry["issuer_key_id"] = self._kid
+            region = {k: v for k, v in entry.items() if k != "issuer_signature"}
+            entry["issuer_signature"] = self._key.sign(canonical_json(region).encode("utf-8")).hex()
+            if self.path is not None:
+                self.path.parent.mkdir(parents=True, exist_ok=True)
+                with open(self.path, "a", encoding="utf-8") as f:
+                    f.write(json.dumps(entry, sort_keys=True) + "\n")
+            self.entries.append(entry)
+            self._seq, self._tail = entry["seq"], entry["entry_sha256"]
+            return entry
+
+
+def verify_witness(entries: Iterable[Any], *, issuer_public_keys: Dict[str, Any]) -> Dict[str, Any]:
+    """Every entry hashes, links and carries a valid issuer signature.
+    Returns {"accepted", "reason", "count", "tail_sha256", "entries": [...]}."""
+    report, prev, expect, tail, ok_all = [], GENESIS, 1, GENESIS, True
+    for raw in entries:
+        if not isinstance(raw, dict) or raw.get("witness_version") != WITNESS_VERSION or "entry_sha256" not in raw \
+                or not isinstance(raw.get("seq"), int) or "event" not in raw:
+            report.append({"seq": None, "accepted": False, "reason": REF_WITNESS_MALFORMED}); ok_all = False
+            continue
+        ok, reason = True, ACCEPT_WITNESS_VERIFIED
+        if entry_sha256(raw) != raw["entry_sha256"]:
+            ok, reason = False, REF_WITNESS_HASH_MISMATCH
+        elif raw["seq"] != expect or raw.get("prev_sha256") != prev:
+            ok, reason = False, REF_WITNESS_CHAIN_BROKEN
+        else:
+            key = issuer_public_keys.get(raw.get("issuer_key_id"))
+            if key is None:
+                ok, reason = False, REF_WITNESS_KEY_UNKNOWN
+            else:
+                region = {k: v for k, v in raw.items() if k != "issuer_signature"}
+                try:
+                    key.verify(bytes.fromhex(raw.get("issuer_signature", "")), canonical_json(region).encode("utf-8"))
+                except Exception:
+                    ok, reason = False, REF_WITNESS_SIGNATURE_INVALID
+        report.append({"seq": raw["seq"], "event": raw["event"], "accepted": ok, "reason": reason})
+        ok_all = ok_all and ok
+        expect, prev, tail = raw["seq"] + 1, raw["entry_sha256"], raw["entry_sha256"]
+    return {"accepted": ok_all, "reason": ACCEPT_WITNESS_VERIFIED if ok_all else next(r["reason"] for r in report if not r["accepted"]),
+            "count": len(report), "tail_sha256": tail, "entries": report}
+
+
+def read_witness(path: str) -> List[Any]:
+    out: List[Any] = []
+    for line in Path(path).read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            try:
+                out.append(json.loads(line))
+            except ValueError:
+                out.append(None)
+    return out

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.13.0.dev0
+Version: 0.14.1.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.13.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.14.1.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
@@ -240,6 +240,17 @@ its initialize handshake, so a fleet with Claude on some desks and ChatGPT
 on others still has one trail that says who, through what, did what. The
 receipt itself stays model-agnostic.
 
+The evidence is the workstation's own statement, and the workstation
+belongs to its user. So the issuer keeps a witness: a signed, hash-chained
+record of every receipt it issued and every grant it accepted, on the
+operator's server. `gargoyle audit --witness` reconciles the two by
+decision id and names what does not agree: a receipt the issuer never
+issued, a held call honored without a grant the issuer saw, a receipt
+issued with no evidence recorded. `--check-tree` hashes the gated folder
+against the evidence's recorded states and names any file changed around
+the gate. On a machine the user administers the gate constrains the
+assistant, not the user; these two checks make the difference visible.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -369,6 +380,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
+| issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -28,12 +28,14 @@ gargoyle/pending_store.py
 gargoyle/plans.py
 gargoyle/policy.py
 gargoyle/published_record_source.py
+gargoyle/reconcile.py
 gargoyle/remote.py
 gargoyle/replay_cache.py
 gargoyle/revert.py
 gargoyle/rules.py
 gargoyle/state.py
 gargoyle/verifier.py
+gargoyle/witness.py
 gargoyle/specs/graph-reference.json
 gargoyle/static/approve.html
 gargoyle/static/approve.js
@@ -75,4 +77,5 @@ tests/test_state.py
 tests/test_stdio_encoding.py
 tests/test_threshold.py
 tests/test_typescript_conformance.py
-tests/test_wire_spec.py
+tests/test_wire_spec.py
+tests/test_witness.py

{gargoyle_receipts-0.13.0.dev0 → gargoyle_receipts-0.14.1.dev0}/pyproject.toml

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

@@ -197,11 +197,15 @@ def test_entries_name_the_client_and_older_versions_still_verify(tmp_path):
     assert anon["client"] is None
     v = verify_log(read_log(str(log.path)), **TRUST)
     assert v["accepted"] and [r["client"] for r in v["entries"]] == ["Claude Desktop 1.4", None]
-    # A version-2 entry (no client member) is still well-formed; a version-3 entry without it is not.
-    v2 = {k: val for k, val in anon.items() if k != "client"}; v2["evidence_version"] = "gargoyle-evidence/2"
+    # A version-2 entry (no client, no ref) is still well-formed; a version-3 entry has client but no ref;
+    # a version-4 entry without its ref member is not well-formed.
+    v2 = {k: val for k, val in anon.items() if k not in ("client", "ref")}; v2["evidence_version"] = "gargoyle-evidence/2"
     v2["entry_sha256"] = entry_sha256(v2)
     assert _well_formed(v2)
-    v3_missing = {k: val for k, val in anon.items() if k != "client"}
-    assert not _well_formed(v3_missing)
+    v3 = {k: val for k, val in anon.items() if k != "ref"}; v3["evidence_version"] = "gargoyle-evidence/3"
+    v3["entry_sha256"] = entry_sha256(v3)
+    assert _well_formed(v3)
+    v4_missing = {k: val for k, val in anon.items() if k != "ref"}
+    assert not _well_formed(v4_missing)
     with pytest.raises(ValueError):
         build_entry(seq=1, prev_sha256=GENESIS, kind=REFUSED, tool="t", args={}, principal=PRINCIPAL, reason="x", client=7)

gargoyle_receipts-0.14.1.dev0/tests/test_witness.py

@@ -0,0 +1,165 @@
+"""The issuer's witness log and reconciliation: client evidence checked
+against an independent, issuer-signed record; a gated folder checked
+against the evidence."""
+
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from fastapi.testclient import TestClient
+
+from gargoyle.approval import build_grant, sign_grant
+from gargoyle.evidence import HONORED, EvidenceLog, read_log, verify_log
+from gargoyle.execution import build_execution_receipt, sign_execution_receipt
+from gargoyle.issuer import issue
+from gargoyle.issuer_service import build_issuer_app
+from gargoyle.jws import encode
+from gargoyle.mcp_server import EXECUTED_META_KEY, IssuerClient, ServerState, StdioUpstream, handle_message
+from gargoyle.policy import ELIGIBLE, Decision
+from gargoyle.reconcile import check_tree, reconcile
+from gargoyle.witness import (ACCEPT_WITNESS_VERIFIED, REF_WITNESS_HASH_MISMATCH, REF_WITNESS_SIGNATURE_INVALID, WitnessLog,
+                              read_witness, verify_witness)
+
+issuer, executor, approver, idp = (Ed25519PrivateKey.generate() for _ in range(4))
+PIN = {"policy_id": "p/1", "policy_sha256": "a" * 64}
+TARGET = "mcp://fs"
+PRINCIPAL = "agent@contoso.com"
+ISSUER_KEYS = {"issuer-1": issuer.public_key()}
+
+
+class FsPolicy:
+    def pin(self): return PIN
+    def decide(self, target_url, interaction):
+        return Decision(ELIGIBLE, None, True) if interaction.get("tool") == "write_file" else Decision(ELIGIBLE)
+
+
+def token():
+    return encode({"sub": PRINCIPAL, "exp": int((datetime.now(timezone.utc) + timedelta(hours=1)).timestamp())}, idp, "idp-1")
+
+
+def test_witness_entries_are_signed_and_chained(tmp_path):
+    w = WitnessLog(str(tmp_path / "w.jsonl"), issuer, "issuer-1")
+    w.record("issued", decision_id="d-1", principal=PRINCIPAL, tool="read_file")
+    w.record("granted", approval_request_id="r-1", approver="dana")
+    again = WitnessLog(str(tmp_path / "w.jsonl"), issuer, "issuer-1")      # continues the chain after a restart
+    again.record("declined", approval_request_id="r-2")
+    entries = read_witness(str(tmp_path / "w.jsonl"))
+    v = verify_witness(entries, issuer_public_keys=ISSUER_KEYS)
+    assert v["accepted"] and v["count"] == 3 and [e["seq"] for e in entries] == [1, 2, 3]
+    forged = dict(entries[1], approver="mallory")
+    assert verify_witness([entries[0], forged, entries[2]], issuer_public_keys=ISSUER_KEYS)["entries"][1]["reason"] == REF_WITNESS_HASH_MISMATCH
+    from gargoyle.witness import entry_sha256
+    forged["entry_sha256"] = entry_sha256(forged)              # rehashed, but the issuer did not sign it
+    assert verify_witness([entries[0], forged], issuer_public_keys=ISSUER_KEYS)["entries"][1]["reason"] == REF_WITNESS_SIGNATURE_INVALID
+    assert not verify_witness(entries, issuer_public_keys={"other": executor.public_key()})["accepted"]
+
+
+def _rig(tmp_path, root):
+    w = WitnessLog(str(tmp_path / "witness.jsonl"), issuer, "issuer-1")
+    app = build_issuer_app(policy=FsPolicy(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()},
+                           approver_public_keys={"approver-1": approver.public_key()}, witness=w)
+    c = TestClient(app); h = {"Authorization": "Bearer " + token()}
+
+    class Shim:
+        def post(self, url, json=None, headers=None, timeout=None): return c.post(url.replace("http://i", ""), json=json, headers=headers)
+        def get(self, url, headers=None, timeout=None): return c.get(url.replace("http://i", ""), headers=headers)
+
+    def human(seconds):
+        for hold in c.get("/pending", headers=h).json()["pending"]:
+            env = hold["envelope"]
+            g = sign_grant(build_grant(decision_sha256=env["decision_sha256"], approval_request_id=env["approval_request_id"],
+                                       grant_id="g-" + env["approval_request_id"], not_after=datetime.now(timezone.utc) + timedelta(minutes=5)), approver, "approver-1")
+            c.post("/grants", json=g, headers=h)
+
+    up = StdioUpstream([sys.executable, "-I", "-m", "gargoyle.fs_server", str(root)])
+    state = ServerState({"pinned_public_keys": ISSUER_KEYS, "record": PIN, "target_id": TARGET, "principal": PRINCIPAL,
+                         "approver_public_keys": {"approver-1": approver.public_key()}, "executor_signing_key": executor, "executor_key_id": "executor-1"},
+                        upstream=up, issuer_client=IssuerClient("http://i", token(), http=Shim(), approval_timeout=30, poll_seconds=0.01, sleep=human),
+                        audit_log=str(tmp_path / "audit.jsonl"))
+    handle_message(state, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+    handle_message(state, {"jsonrpc": "2.0", "method": "notifications/initialized"})
+    return state, up, c, h, w
+
+
+def call(state, n, name, args):
+    return handle_message(state, {"jsonrpc": "2.0", "id": n, "method": "tools/call", "params": {"name": name, "arguments": args}})["result"]
+
+
+def test_honest_evidence_reconciles_and_tampering_is_found(tmp_path):
+    root = tmp_path / "root"; root.mkdir(); (root / "n.md").write_text("one\n", encoding="utf-8"); (root / "other.md").write_text("x", encoding="utf-8")
+    state, up, c, h, w = _rig(tmp_path, root)
+    try:
+        assert call(state, 2, "read_file", {"path": str(root / "n.md")})["_meta"][EXECUTED_META_KEY]
+        assert call(state, 3, "write_file", {"path": str(root / "n.md"), "content": "two\n"})["_meta"][EXECUTED_META_KEY]
+    finally:
+        up.close()
+    evidence = read_log(str(tmp_path / "audit.jsonl")); witness = read_witness(str(tmp_path / "witness.jsonl"))
+    assert [e["event"] for e in witness] == ["issued", "issued", "granted"]
+    assert evidence[1]["ref"] == str(root / "n.md") and evidence[1]["evidence_version"] == "gargoyle-evidence/4"
+    assert verify_log(evidence, issuer_public_keys=ISSUER_KEYS, executor_public_keys={"executor-1": executor.public_key()},
+                      approver_public_keys={"approver-1": approver.public_key()})["accepted"]
+    r = reconcile(evidence, witness, principal=PRINCIPAL)
+    assert r["accepted"] and r["issued"] == 2 and r["evidence_with_receipt"] == 2
+    # The witness is served to an authenticated caller too.
+    assert len(c.get("/witness", headers=h).json()["entries"]) == 3
+
+    # 1. A forged honored entry for a decision the issuer never issued: the user holds the executor key, so it verifies alone.
+    now = datetime.now(timezone.utc)
+    fake_call = {"tool": "write_file", "args": {"path": str(root / "other.md"), "content": "pwned"}, "principal": PRINCIPAL}
+    rogue_issuer = Ed25519PrivateKey.generate()
+    fake_env = issue(FsPolicy(), TARGET, fake_call, signing_key=rogue_issuer, key_id="issuer-1", now=now).envelope
+    forged = {"kind": HONORED, "receipt": fake_env, "grant": None, "execution": None, "seq": 99, "at": now.isoformat(), "tool": "write_file"}
+    r = reconcile(evidence + [forged], witness, principal=PRINCIPAL)
+    assert [f["finding"] for f in r["findings"]] == ["UNWITNESSED_RECEIPT"]
+    # 2. A held call honored with no grant the issuer saw: drop the witness's grant line.
+    r = reconcile(evidence, [x for x in witness if x["event"] != "granted"], principal=PRINCIPAL)
+    assert [f["finding"] for f in r["findings"]] == ["UNWITNESSED_RELEASE"]
+    # 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"
+
+    # The tree: as the gate left it, then edited behind its back, then deleted.
+    t = check_tree(evidence, str(root))
+    assert t["accepted"] and t["checked"] == 1 and t["untouched"] == 1
+    (root / "n.md").write_text("edited in notepad\n", encoding="utf-8")
+    t = check_tree(evidence, str(root))
+    assert [f["finding"] for f in t["findings"]] == ["CHANGED_OUTSIDE_GATE"] and t["findings"][0]["path"] == str(root / "n.md")
+    (root / "n.md").unlink()
+    assert check_tree(evidence, str(root))["findings"][0].get("missing") is True
+
+
+def test_audit_command_reports_reconciliation_and_tree(tmp_path, capsys):
+    root = tmp_path / "root"; root.mkdir(); (root / "n.md").write_text("one\n", encoding="utf-8")
+    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()
+    out = tmp_path / "deploy"; out.mkdir()
+    (out / "public-keys.json").write_text(json.dumps({"issuer": {"issuer-1": hexpub(issuer)}, "executor": {"executor-1": hexpub(executor)},
+                                                      "approver": {"approver-1": hexpub(approver)}}))
+    from gargoyle.cli import main
+    assert main(["audit", "--log", str(tmp_path / "audit.jsonl"), "--out", str(out), "--witness", str(tmp_path / "witness.jsonl"),
+                 "--check-tree", str(root)]) == 0
+    text = capsys.readouterr().out
+    assert "witness: 2 entries, WITNESS_VERIFIED" in text and "0 finding(s)" in text and "1 gated file(s) checked" in text
+    (root / "n.md").write_text("tampered", encoding="utf-8")
+    assert main(["audit", "--log", str(tmp_path / "audit.jsonl"), "--out", str(out), "--check-tree", str(root)]) == 1
+    assert "CHANGED_OUTSIDE_GATE" in capsys.readouterr().out
+
+
+def test_audit_names_a_missing_witness_or_folder_plainly(tmp_path, capsys):
+    from gargoyle.cli import main
+    log = tmp_path / "audit.jsonl"; log.write_text("")
+    out = tmp_path / "deploy"; out.mkdir()
+    (out / "public-keys.json").write_text(json.dumps({"issuer": {}, "executor": {}, "approver": {}}))
+    assert main(["audit", "--log", str(log), "--out", str(out), "--witness", str(tmp_path / "nope.jsonl")]) == 2
+    assert "witness file not found" in capsys.readouterr().err
+    assert main(["audit", "--log", str(log), "--out", str(out), "--check-tree", str(tmp_path / "nodir")]) == 2
+    assert "not a directory" in capsys.readouterr().err
+    # The issuer creates the witness file at start, before any decision.
+    w = WitnessLog(str(tmp_path / "fresh" / "witness.jsonl"), issuer, "issuer-1")
+    assert (tmp_path / "fresh" / "witness.jsonl").exists() and w.entries == []