gargoyle-receipts 0.7.0.dev0__tar.gz → 0.8.0.dev0__tar.gz

{gargoyle_receipts-0.7.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.8.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.7.0.dev0
+Version: 0.8.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
@@ -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.7.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.8.0.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
@@ -230,7 +230,12 @@ shows the proposed content as a diff against that state; after the human
 signs, the middleware hashes the target again and refuses if it moved; and
 the execution receipt carries the state before and after. An approval
 cannot be redirected by changing the file under it, and an audit shows not
-only that a write ran but what it changed.
+only that a write ran but what it changed. An approved change can be
+undone the same way: the middleware keeps what a held write replaced and
+offers `gargoyle_revert`, which composes the restoring write and sends it
+through the gate, held, shown as a diff, bound to the current state, and
+refused if anything changed since. The audit marks a revert from the
+state hashes alone.
 
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
@@ -314,6 +319,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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 |
 | `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_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.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.7.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.8.0.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
@@ -192,7 +192,12 @@ shows the proposed content as a diff against that state; after the human
 signs, the middleware hashes the target again and refuses if it moved; and
 the execution receipt carries the state before and after. An approval
 cannot be redirected by changing the file under it, and an audit shows not
-only that a write ran but what it changed.
+only that a write ran but what it changed. An approved change can be
+undone the same way: the middleware keeps what a held write replaced and
+offers `gargoyle_revert`, which composes the restoring write and sends it
+through the gate, held, shown as a diff, bound to the current state, and
+refused if anything changed since. The audit marks a revert from the
+state hashes alone.
 
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
@@ -276,6 +281,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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 |
 | `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_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/gargoyle/cli.py

@@ -246,6 +246,12 @@ def cmd_audit(args) -> int:
             why = (" (%s)" % r["verdict"]) if r["kind"] == "refused" and r["verdict"] else ""
             if r.get("released_by"):
                 why += " released by " + ", ".join(r["released_by"])
+            if r.get("state"):
+                # A state-bound call: the target as it was approved, and as the run left it.
+                pre, post = (r["state"].get("pre") or "")[:8], (r["state"].get("post") or "")[:8]
+                why += " state %s -> %s" % (pre or "?", post or "?") if post else " state %s" % pre
+            if r.get("reverts"):
+                why += " reverts #%d" % r["reverts"]
             print("%4s %-5s %-8s %-24s %-28s %s%s" % (r["seq"] if r["seq"] is not None else "?",
                                                       "ok" if r["accepted"] else "FAIL", r["kind"] or "?",
                                                       (r["tool"] or "?")[:24], (r["principal"] or "?")[:28], r["reason"], why))

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/gargoyle/evidence.py

@@ -160,7 +160,8 @@ def verify_log(
     {"accepted", "reason", "tail_sha256", "count", "honored", "refused",
      "entries": [{"seq", "kind", "tool", "principal", "accepted", "reason", "verdict", "released_by"}, ...]},
     `reason` the verification outcome, `verdict` what the executor recorded,
-    `released_by` the approver key ids of the grants an honored held call carried.
+    `released_by` the approver key ids of the grants an honored held call carried,
+    `state` {"pre", "post"} the target's state hashes when the call was state-bound.
     Verification continues past a bad entry so the report names every one."""
     trust = dict(issuer_public_keys=issuer_public_keys, executor_public_keys=executor_public_keys,
                  approver_public_keys=approver_public_keys)
@@ -178,7 +179,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": []})
+                           "verdict": None, "released_by": [], "state": None})
             all_ok = False
             continue
         e = raw
@@ -206,13 +207,28 @@ def verify_log(
         counts[e["kind"]] += 1
         released_by = [g.get("approver_key_id") for g in (e["grant"] if isinstance(e["grant"], list) else [e["grant"]])
                        if isinstance(g, dict)] if e["grant"] is not None else []
+        ex = e["execution"] if isinstance(e["execution"], dict) else {}
+        state = ({"pre": ex.get("pre_state_sha256"), "post": ex.get("post_state_sha256")}
+                 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})
+                       "accepted": ok, "reason": reason, "verdict": e["reason"], "released_by": released_by,
+                       "state": state})
         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.
         expect_seq, prev, tail = e["seq"] + 1, e["entry_sha256"], e["entry_sha256"]
 
+    # A revert is recognisable without any annotation: its pre-state is an
+    # earlier honored entry's post-state and its post-state that entry's pre-state.
+    for i, r in enumerate(report):
+        r["reverts"] = None
+        st = r.get("state")
+        if r["accepted"] and st and st.get("pre") and st.get("post"):
+            for prev in reversed(report[:i]):
+                ps = prev.get("state")
+                if prev["accepted"] and ps and ps.get("post") == st["pre"] and ps.get("pre") == st["post"]:
+                    r["reverts"] = prev["seq"]
+                    break
     return {"accepted": all_ok, "reason": ACCEPT_EVIDENCE_VERIFIED if all_ok else _first_failure(report),
             "tail_sha256": tail, "count": len(report), "honored": counts[HONORED], "refused": counts[REFUSED],
             "entries": report}

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/gargoyle/mcp_server.py

@@ -42,6 +42,7 @@ Run as a stdio MCP server:  python3 -m gargoyle.mcp_server
 import json
 import subprocess
 import sys
+from pathlib import Path
 import threading
 import time
 from typing import Any, Dict, List, Optional
@@ -97,7 +98,8 @@ ENV_CLIENT_TOKEN = "GARGOYLE_MCP_CLIENT_TOKEN"
 ENV_APPROVAL_TIMEOUT = "GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS"
 ENV_POLL_SECONDS = "GARGOYLE_MCP_POLL_SECONDS"
 ENV_AUDIT_LOG = "GARGOYLE_MCP_AUDIT_LOG"
-ENV_STATE_PROBE = "GARGOYLE_MCP_STATE_PROBE"   # "filesystem" (default): bind held calls to the target file's state; "none" to disable
+ENV_STATE_PROBE = "GARGOYLE_MCP_STATE_PROBE"
+ENV_SNAPSHOT_DIR = "GARGOYLE_MCP_SNAPSHOT_DIR"   # where pre-change snapshots live (default: snapshots/ beside the audit log); "none" disables undo   # "filesystem" (default): bind held calls to the target file's state; "none" to disable
 REF_TARGET_LOGIN_REQUIRED = "REF_TARGET_LOGIN_REQUIRED"   # Entra login mode and no usable token: run `gargoyle login`   # the evidence log: one hash-chained JSON line per decision, honored or refused
 
 # Self-issue refusals.
@@ -290,10 +292,16 @@ class ServerState:
         issuer_client: Optional[IssuerClient] = None,
         audit_log: Optional[str] = None,
         state_probe: Any = "filesystem",
+        snapshot_dir: Optional[str] = None,
     ) -> None:
         from gargoyle.state import probe_from_name
+        from gargoyle.revert import SnapshotStore
         self.config = config
         self.probe = state_probe if callable(state_probe) else probe_from_name(state_probe)
+        if snapshot_dir is None and audit_log:
+            snapshot_dir = str(Path(audit_log).parent / "snapshots")
+        self.snapshots: Optional[SnapshotStore] = (SnapshotStore(snapshot_dir)
+                                                   if snapshot_dir and snapshot_dir != "none" and self.probe is not None else None)
         self.upstream = upstream
         self.issuer_client = issuer_client
         self.evidence: Optional[EvidenceLog] = EvidenceLog(audit_log) if audit_log else None
@@ -369,6 +377,18 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     if not verdict.honored:
         return refused(verdict.reason, envelope)
 
+    # Undo material: for a held, state-bound call, keep the target as it is
+    # right now (the state the receipt bound and the check just confirmed).
+    if (state.snapshots is not None and isinstance(envelope, dict) and envelope.get("requires_approval")
+            and live_state is not None and isinstance(envelope.get("decision_id"), str)):
+        try:
+            desc = state.probe(name, args)
+            if desc is not None and state.config and state.config.get("principal"):
+                from gargoyle.state import read_target
+                state.snapshots.put(envelope["decision_id"], desc, read_target(desc), name)
+        except Exception as exc:
+            sys.stderr.write("gargoyle: snapshot failed: %s\n" % exc)
+
     state.executed.append({"tool": name, "args": args})  # THE side effect
     return {"executed": True, "reason": verdict.reason, "envelope": envelope, "grant": grant,
             "self_issued": self_issued}
@@ -419,6 +439,11 @@ def _attest(state: ServerState, envelope: Optional[Dict[str, Any]], outputs: Any
         from gargoyle.state import state_sha256 as _state_hash
         desc = state.probe(str(params.get("name")), params.get("arguments", {}))
         post = _state_hash(desc) if desc is not None else None
+    if post is not None and state.snapshots is not None and isinstance(envelope.get("decision_id"), str):
+        try:
+            state.snapshots.record_post(envelope["decision_id"], post)
+        except Exception:
+            pass
     return state.consumer.attest(envelope, outputs, post_state_sha256=post)
 
 
@@ -439,7 +464,12 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
     params = msg.get("params") or {}
 
     if state.upstream is not None and method in ("initialize", "tools/list"):
-        return _relay(state, msg)
+        reply = _relay(state, msg)
+        if method == "tools/list" and state.snapshots is not None and isinstance(reply, dict) \
+                and isinstance(reply.get("result"), dict) and isinstance(reply["result"].get("tools"), list):
+            from gargoyle.revert import REVERT_TOOL_DEF
+            reply["result"]["tools"] = list(reply["result"]["tools"]) + [REVERT_TOOL_DEF]
+        return reply
 
     if method == "initialize":
         # The handshake completes when the client sends notifications/initialized;
@@ -477,9 +507,23 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
         return _error(msg_id, JSONRPC_NOT_INITIALIZED, "server not initialized")
 
     if method == "tools/list":
-        return _success(msg_id, {"tools": ADVERTISED_TOOLS})
+        from gargoyle.revert import REVERT_TOOL_DEF
+        return _success(msg_id, {"tools": ADVERTISED_TOOLS + ([REVERT_TOOL_DEF] if state.snapshots is not None else [])})
 
     if method == "tools/call":
+        from gargoyle.revert import REVERT_TOOL, plan_revert
+        if params.get("name") == REVERT_TOOL:
+            # An undo is a write the middleware composes from its snapshot; it
+            # then goes through the gate exactly as the assistant's own writes.
+            if state.snapshots is None:
+                return _success(msg_id, {"content": [{"type": "text", "text": "refused: undo is not enabled"}], "isError": True,
+                                         "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: "REF_REVERT_UNKNOWN"}})
+            plan = plan_revert(state.snapshots, str((params.get("arguments") or {}).get("decision_id") or "last"), state.probe)
+            if "reason" in plan:
+                return _success(msg_id, {"content": [{"type": "text", "text": "refused: " + plan["reason"]}], "isError": True,
+                                         "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: plan["reason"]}})
+            params = plan["params"]
+            msg = dict(msg, params=params)
         gate = _gate(state, params)
         executed, reason = gate["executed"], gate["reason"]
         if executed and state.upstream is not None:

gargoyle_receipts-0.8.0.dev0/gargoyle/revert.py

@@ -0,0 +1,124 @@
+"""Undo for an approved change: a revert is another state-bound write.
+
+Before a held, state-bound call runs, the executor keeps the target's
+bytes in a snapshot store beside the audit log, keyed by the state hash
+the receipt bound, with a sidecar naming the decision, the target and,
+after the run, the state the call left. `gargoyle_revert` is a tool the
+middleware adds to the upstream's list: given a decision id (or "last"),
+it builds the write that restores the snapshot and sends it through the
+gate like any other write. So an undo is held, shown to the approver as a
+diff from the current content back to the snapshot, bound to the current
+state, signed, executed once, and recorded. The chain proves the
+relationship without trusting any annotation: the revert's pre-state is
+the original's post-state and its post-state is the original's pre-state;
+`gargoyle audit` prints "reverts #N" when it sees that.
+
+Refused before a card is ever raised:
+  REF_REVERT_UNKNOWN          no snapshot for that decision (or nothing to revert)
+  REF_REVERT_STATE_CHANGED    the target is no longer as the original call left it
+  REF_REVERT_NEEDS_DELETE     the target did not exist before; undoing would delete
+  REF_REVERT_NOT_TEXT         the snapshot is not UTF-8 text the write tool can carry
+
+Text files only, and only files a write can restore. A revert of a create
+would be a delete, which the gate refuses; a revert of a move would be a
+move back, not built here.
+"""
+
+import json
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from gargoyle.state import state_sha256
+
+REVERT_TOOL = "gargoyle_revert"
+REVERT_TOOL_DEF = {
+    "name": REVERT_TOOL,
+    "description": ("Undo an approved file change made through this gate: restores the file to its content "
+                    "before that change. Held for approval like any write; refused if the file changed since. "
+                    "decision_id: the change to undo, or \"last\" for the most recent approved change."),
+    "inputSchema": {"type": "object", "properties": {"decision_id": {"type": "string", "default": "last"}}},
+}
+
+REF_REVERT_UNKNOWN = "REF_REVERT_UNKNOWN"
+REF_REVERT_STATE_CHANGED = "REF_REVERT_STATE_CHANGED"
+REF_REVERT_NEEDS_DELETE = "REF_REVERT_NEEDS_DELETE"
+REF_REVERT_NOT_TEXT = "REF_REVERT_NOT_TEXT"
+
+
+class SnapshotStore:
+    """Content by state hash, plus a sidecar per decision."""
+
+    def __init__(self, directory: str) -> None:
+        self.dir = Path(directory)
+
+    def _ensure(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def put(self, decision_id: str, description: Dict[str, Any], data: Optional[bytes], tool: str) -> Dict[str, Any]:
+        """Keep the pre-state of `decision_id`: the bytes (None when the target
+        did not exist) and a sidecar. Returns the sidecar."""
+        self._ensure()
+        key = state_sha256(description)
+        if data is not None:
+            blob = self.dir / (key + ".bin")
+            if not blob.exists():
+                blob.write_bytes(data)
+                try:
+                    os.chmod(blob, stat.S_IRUSR | stat.S_IWUSR)
+                except OSError:
+                    pass
+        meta = {"decision_id": decision_id, "tool": tool, "ref": description["ref"], "pre_state_sha256": key,
+                "existed": data is not None, "post_state_sha256": None, "at": datetime.now(timezone.utc).isoformat()}
+        (self.dir / (decision_id + ".json")).write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+        return meta
+
+    def record_post(self, decision_id: str, post_state_sha256: Optional[str]) -> None:
+        p = self.dir / (decision_id + ".json")
+        if p.exists():
+            meta = json.loads(p.read_text(encoding="utf-8"))
+            meta["post_state_sha256"] = post_state_sha256
+            p.write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+
+    def sidecars(self) -> List[Dict[str, Any]]:
+        if not self.dir.exists():
+            return []
+        out = [json.loads(p.read_text(encoding="utf-8")) for p in self.dir.glob("*.json")]
+        return sorted(out, key=lambda m: m.get("at", ""))
+
+    def find(self, decision_id: str) -> Optional[Dict[str, Any]]:
+        if decision_id == "last":
+            done = [m for m in self.sidecars() if m.get("post_state_sha256")]
+            return done[-1] if done else None
+        p = self.dir / (decision_id + ".json")
+        return json.loads(p.read_text(encoding="utf-8")) if p.exists() else None
+
+    def content(self, pre_state_sha256: str) -> Optional[bytes]:
+        p = self.dir / (pre_state_sha256 + ".bin")
+        return p.read_bytes() if p.exists() else None
+
+
+def plan_revert(store: SnapshotStore, decision_id: str, probe) -> Dict[str, Any]:
+    """The write that undoes `decision_id`, or a refusal:
+    {"params": {"name": "write_file", "arguments": {...}}, "reverts": id} |
+    {"reason": REF_REVERT_*}. `probe` is the state probe, used to confirm the
+    target is still as that call left it."""
+    meta = store.find(decision_id or "last")
+    if meta is None or not meta.get("post_state_sha256"):
+        return {"reason": REF_REVERT_UNKNOWN}
+    if not meta.get("existed"):
+        return {"reason": REF_REVERT_NEEDS_DELETE}
+    data = store.content(meta["pre_state_sha256"])
+    if data is None:
+        return {"reason": REF_REVERT_UNKNOWN}
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        return {"reason": REF_REVERT_NOT_TEXT}
+    args = {"path": meta["ref"], "content": text}
+    now = probe("write_file", args) if probe is not None else None
+    if now is None or state_sha256(now) != meta["post_state_sha256"]:
+        return {"reason": REF_REVERT_STATE_CHANGED}
+    return {"params": {"name": "write_file", "arguments": args}, "reverts": meta["decision_id"]}

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/gargoyle/state.py

@@ -85,6 +85,17 @@ def filesystem_probe(tool: str, args: Any) -> Optional[Dict[str, Any]]:
     return describe(path, data)
 
 
+def read_target(description: Dict[str, Any]) -> Optional[bytes]:
+    """The bytes behind a filesystem state description, or None when absent."""
+    if description.get("sha256") is None:
+        return None
+    try:
+        with open(description["ref"], "rb") as f:
+            return f.read()
+    except OSError:
+        return None
+
+
 def probe_from_name(name: Optional[str]) -> Optional[Callable[[str, Any], Optional[Dict[str, Any]]]]:
     """GARGOYLE_MCP_STATE_PROBE: "filesystem" (default) or "none"."""
     if name in (None, "", "filesystem"):

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.7.0.dev0
+Version: 0.8.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
@@ -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.7.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.8.0.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
@@ -230,7 +230,12 @@ shows the proposed content as a diff against that state; after the human
 signs, the middleware hashes the target again and refuses if it moved; and
 the execution receipt carries the state before and after. An approval
 cannot be redirected by changing the file under it, and an audit shows not
-only that a write ran but what it changed.
+only that a write ran but what it changed. An approved change can be
+undone the same way: the middleware keeps what a held write replaced and
+offers `gargoyle_revert`, which composes the restoring write and sends it
+through the gate, held, shown as a diff, bound to the current state, and
+refused if anything changed since. The audit marks a revert from the
+state hashes alone.
 
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
@@ -314,6 +319,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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 |
 | `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_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ gargoyle/pending_store.py
 gargoyle/policy.py
 gargoyle/published_record_source.py
 gargoyle/replay_cache.py
+gargoyle/revert.py
 gargoyle/rules.py
 gargoyle/state.py
 gargoyle/verifier.py
@@ -60,6 +61,7 @@ tests/test_notify.py
 tests/test_opa.py
 tests/test_policy.py
 tests/test_published_record.py
+tests/test_revert.py
 tests/test_rules.py
 tests/test_state.py
 tests/test_stdio_encoding.py

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.7.0.dev0"
+version = "0.8.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.8.0.dev0/tests/test_revert.py

@@ -0,0 +1,140 @@
+"""Undo: an approved write leaves a snapshot; gargoyle_revert composes the
+write that restores it and sends it through the gate, held and state-bound.
+Run against the real filesystem server as the upstream."""
+
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+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 read_log, verify_log
+from gargoyle.issuer_service import build_issuer_app
+from gargoyle.jws import encode
+from gargoyle.mcp_server import EXECUTED_META_KEY, REASON_META_KEY, IssuerClient, ServerState, StdioUpstream, handle_message
+from gargoyle.policy import ELIGIBLE, Decision, refuse
+from gargoyle.revert import (REF_REVERT_NEEDS_DELETE, REF_REVERT_STATE_CHANGED, REF_REVERT_UNKNOWN, REVERT_TOOL,
+                             SnapshotStore, plan_revert)
+from gargoyle.state import describe, filesystem_probe, state_sha256
+
+issuer, executor, approver, idp = (Ed25519PrivateKey.generate() for _ in range(4))
+PIN = {"policy_id": "p/1", "policy_sha256": "a" * 64}
+TARGET = "mcp://fs"
+PRINCIPAL = "agent-7"
+
+
+class FsPolicy:
+    def pin(self): return PIN
+    def decide(self, target_url, interaction):
+        t = interaction.get("tool")
+        if t in ("write_file", "move_file", "create_directory"): return Decision(ELIGIBLE, None, True)
+        if t == "delete_file": return refuse("DESTRUCTIVE_TOOL")
+        return Decision(ELIGIBLE)
+
+
+def token():
+    return encode({"sub": PRINCIPAL, "exp": int((datetime.now(timezone.utc) + timedelta(hours=1)).timestamp())}, idp, "idp-1")
+
+
+def test_snapshot_store_and_plan(tmp_path):
+    store = SnapshotStore(str(tmp_path / "snap"))
+    f = tmp_path / "n.md"; f.write_bytes(b"one\n")
+    desc = describe(str(f), b"one\n")
+    meta = store.put("d-1", desc, b"one\n", "write_file")
+    assert meta["pre_state_sha256"] == state_sha256(desc) and meta["existed"] and meta["post_state_sha256"] is None
+    assert plan_revert(store, "d-1", filesystem_probe)["reason"] == REF_REVERT_UNKNOWN        # not finished yet
+    f.write_bytes(b"two\n"); store.record_post("d-1", state_sha256(describe(str(f), b"two\n")))
+    plan = plan_revert(store, "last", filesystem_probe)
+    assert plan["reverts"] == "d-1" and plan["params"] == {"name": "write_file", "arguments": {"path": str(f), "content": "one\n"}}
+    f.write_bytes(b"three\n")
+    assert plan_revert(store, "d-1", filesystem_probe)["reason"] == REF_REVERT_STATE_CHANGED
+    assert plan_revert(store, "nope", filesystem_probe)["reason"] == REF_REVERT_UNKNOWN
+    store.put("d-2", describe(str(tmp_path / "new.md"), None), None, "write_file"); store.record_post("d-2", "b" * 64)
+    assert plan_revert(store, "d-2", filesystem_probe)["reason"] == REF_REVERT_NEEDS_DELETE
+
+
+def _rig(tmp_path, root):
+    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()})
+    c = TestClient(app); h = {"Authorization": "Bearer " + token()}
+    cards = []
+
+    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"]:
+            cards.append(hold)
+            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-1": issuer.public_key()}, "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, cards
+
+
+def call(state, n, name, args):
+    return handle_message(state, {"jsonrpc": "2.0", "id": n, "method": "tools/call", "params": {"name": name, "arguments": args}})
+
+
+def test_revert_restores_an_approved_write_through_the_gate(tmp_path):
+    root = tmp_path / "root"; root.mkdir()
+    target = root / "notes.md"; target.write_text("one\n", encoding="utf-8")
+    state, up, cards = _rig(tmp_path, root)
+    try:
+        tools = handle_message(state, {"jsonrpc": "2.0", "id": 0, "method": "tools/list", "params": {}})["result"]["tools"]
+        assert any(t["name"] == REVERT_TOOL for t in tools) and any(t["name"] == "write_file" for t in tools)
+
+        r = call(state, 2, "write_file", {"path": str(target), "content": "two\n"})
+        assert r["result"]["_meta"][EXECUTED_META_KEY] is True and target.read_text(encoding="utf-8") == "two\n"
+        assert cards[-1]["state"]["text"] == "one\n"
+        snaps = list((tmp_path / "snapshots").glob("*.json")); assert len(snaps) == 1
+        assert json.loads(snaps[0].read_text())["post_state_sha256"] == state_sha256(describe(str(target), b"two\n"))
+
+        # Undo: held, shown as the restore, approved, executed, file back to "one".
+        r = call(state, 3, REVERT_TOOL, {"decision_id": "last"})
+        assert r["result"]["_meta"][EXECUTED_META_KEY] is True, r["result"]
+        assert target.read_text(encoding="utf-8") == "one\n"
+        assert cards[-1]["envelope"]["request_context"]["tool"] == "write_file" and cards[-1]["args"]["content"] == "one\n"
+        assert cards[-1]["state"]["text"] == "two\n"                     # the approver saw the current state
+        ex = r["result"]["_meta"]["gargoyle/execution"]
+        assert ex["pre_state_sha256"] == state_sha256(describe(str(target), b"two\n"))
+        assert ex["post_state_sha256"] == state_sha256(describe(str(target), b"one\n"))
+
+        # The audit recognises the revert from the hashes alone.
+        v = verify_log(read_log(str(tmp_path / "audit.jsonl")), 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"]
+        writes = [e for e in v["entries"] if e["tool"] == "write_file"]
+        assert writes[0]["reverts"] is None and writes[1]["reverts"] == writes[0]["seq"]
+
+        # Nothing newer to revert: the revert itself finished, so "last" now points at it (a redo).
+        r = call(state, 4, REVERT_TOOL, {"decision_id": "last"})
+        assert r["result"]["_meta"][EXECUTED_META_KEY] is True and target.read_text(encoding="utf-8") == "two\n"
+
+        # Changed since: refused before any card.
+        n_cards = len(cards)
+        target.write_text("someone edited this\n", encoding="utf-8")
+        r = call(state, 5, REVERT_TOOL, {"decision_id": "last"})
+        assert r["result"]["isError"] and r["result"]["_meta"][REASON_META_KEY] == REF_REVERT_STATE_CHANGED and len(cards) == n_cards
+
+        # A create cannot be undone by a write.
+        new = root / "fresh.md"
+        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()
+    finally:
+        up.close()

{gargoyle_receipts-0.7.0.dev0 → gargoyle_receipts-0.8.0.dev0}/tests/test_state.py

@@ -168,3 +168,13 @@ def test_middleware_refuses_when_the_file_moved_between_card_and_run(tmp_path):
     chain = verify_chain(gate["envelope"], ex, grant=gate["grant"], issuer_public_keys=ISSUER_KEYS,
                          executor_public_keys={"executor-1": executor.public_key()}, approver_public_keys={"approver-1": approver.public_key()})
     assert chain["reason"] == ACCEPT_CHAIN_VERIFIED
+    # The audit names the state transition.
+    from gargoyle.evidence import verify_log
+    entry = {"evidence_version": "gargoyle-evidence/2", "seq": 1, "prev_sha256": "0" * 64, "at": NOW.isoformat(), "kind": "honored",
+             "tool": "write_file", "args_sha256": gate["envelope"]["request_context"]["args_sha256"], "principal": "agent-7",
+             "reason": gate["reason"], "receipt": gate["envelope"], "grant": gate["grant"], "execution": ex}
+    from gargoyle.evidence import entry_sha256
+    entry["entry_sha256"] = entry_sha256(entry)
+    v = verify_log([entry], issuer_public_keys=ISSUER_KEYS, executor_public_keys={"executor-1": executor.public_key()},
+                   approver_public_keys={"approver-1": approver.public_key()})
+    assert v["accepted"] and v["entries"][0]["state"] == {"pre": ex["pre_state_sha256"], "post": ex["post_state_sha256"]}