gargoyle-receipts 0.10.0.dev0__tar.gz → 0.11.0.dev0__tar.gz

{gargoyle_receipts-0.10.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.11.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.10.0.dev0
+Version: 0.11.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.10.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.11.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
@@ -292,6 +292,22 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Microsoft 365 and other targets: adapters
+
+What a held call changes is the adapter's business (`gargoyle.adapters`):
+it describes the target's state before and after, tells the approver what
+the call means in plain words, and composes the call that undoes it. Files
+on the executor's host are the default. `GARGOYLE_MCP_STATE_PROBE=graph`
+selects the Graph adapter for a Microsoft Graph MCP server: inbox rules,
+calendar events, contacts and Teams membership are bound to their state,
+explained on the card ("creates inbox rule 'Fwd invoices' (to an outside
+address: x@evil.example)"), undone by the inverse Graph call, and a send
+is marked as something that cannot be undone. The adapter reads state
+through the upstream server itself, so the gate needs no Graph credential
+of its own. Which tool is which is a JSON spec; the reference naming is in
+`gargoyle/specs/graph-reference.json`, and a different server's names are
+mapped there, not in code.
+
 ## Remote mode
 
 Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
@@ -341,6 +357,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_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |
 | `GARGOYLE_MCP_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `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 |

{gargoyle_receipts-0.10.0.dev0 → gargoyle_receipts-0.11.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.10.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.11.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
@@ -254,6 +254,22 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Microsoft 365 and other targets: adapters
+
+What a held call changes is the adapter's business (`gargoyle.adapters`):
+it describes the target's state before and after, tells the approver what
+the call means in plain words, and composes the call that undoes it. Files
+on the executor's host are the default. `GARGOYLE_MCP_STATE_PROBE=graph`
+selects the Graph adapter for a Microsoft Graph MCP server: inbox rules,
+calendar events, contacts and Teams membership are bound to their state,
+explained on the card ("creates inbox rule 'Fwd invoices' (to an outside
+address: x@evil.example)"), undone by the inverse Graph call, and a send
+is marked as something that cannot be undone. The adapter reads state
+through the upstream server itself, so the gate needs no Graph credential
+of its own. Which tool is which is a JSON spec; the reference naming is in
+`gargoyle/specs/graph-reference.json`, and a different server's names are
+mapped there, not in code.
+
 ## Remote mode
 
 Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
@@ -303,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_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |
 | `GARGOYLE_MCP_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `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 |

gargoyle_receipts-0.11.0.dev0/gargoyle/adapters.py

@@ -0,0 +1,279 @@
+"""Adapters: what a held call changes, in a form the gate can bind, show,
+and undo. The gate itself knows only tool names and arguments. An adapter
+knows the target: it describes the target's state before and after a call
+(gargoyle.state), tells the approver what the call means, and composes the
+call that restores the earlier state (gargoyle.revert).
+
+    probe(tool, args)   -> (description, bytes) | None
+        description: {"ref", "sha256", "size", "text"?, "summary"?, "irreversible"?}
+        bytes: the state's canonical bytes (the hash's preimage), kept as the
+        snapshot; None when the target does not exist
+    restore(meta, pre_bytes, post_bytes) -> {"params": {"name", "arguments"}} | {"reason": REF_REVERT_*}
+        the inverse call, given the sidecar and the two snapshots
+
+FilesystemAdapter: a tool with a path changes that file. GraphAdapter: a
+Microsoft Graph MCP server's tools change mail rules, events, contacts,
+Teams objects; which tool is which is a JSON spec (gargoyle/specs/
+graph-reference.json is the reference naming; map your server's names).
+The Graph adapter reads state through the upstream server itself, with
+the same credential the write will use, so the gate needs no Graph access
+of its own.
+"""
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from gargoyle.envelope import canonical_json
+from gargoyle.state import describe, filesystem_probe, read_target
+
+REF_REVERT_UNKNOWN = "REF_REVERT_UNKNOWN"
+REF_REVERT_NEEDS_DELETE = "REF_REVERT_NEEDS_DELETE"
+REF_REVERT_NOT_TEXT = "REF_REVERT_NOT_TEXT"
+REF_REVERT_IRREVERSIBLE = "REF_REVERT_IRREVERSIBLE"
+REF_REVERT_UNSUPPORTED = "REF_REVERT_UNSUPPORTED"
+
+Probe = Optional[Tuple[Dict[str, Any], Optional[bytes]]]
+
+
+class FilesystemAdapter:
+    """Files on the executor's host (the stdio middleware's own case)."""
+
+    name = "filesystem"
+
+    def probe(self, tool: str, args: Any) -> Probe:
+        desc = filesystem_probe(tool, args)
+        if desc is None:
+            return None
+        return desc, read_target(desc)
+
+    def restore(self, meta: Dict[str, Any], pre: Optional[bytes], post: Optional[bytes]) -> Dict[str, Any]:
+        if pre is None:
+            return {"reason": REF_REVERT_NEEDS_DELETE}      # undoing a create is a delete, which the gate refuses
+        try:
+            text = pre.decode("utf-8")
+        except UnicodeDecodeError:
+            return {"reason": REF_REVERT_NOT_TEXT}
+        return {"params": {"name": "write_file", "arguments": {"path": meta["ref"], "content": text}}}
+
+
+def _tool_json(reply: Any) -> Any:
+    """The JSON a Graph MCP tool returned, from its text content."""
+    if not isinstance(reply, dict) or "result" not in reply:
+        return None
+    result = reply["result"]
+    if isinstance(result, dict) and result.get("isError"):
+        return None
+    if isinstance(result, dict) and isinstance(result.get("structuredContent"), (dict, list)):
+        return result["structuredContent"]
+    for item in (result.get("content") or []) if isinstance(result, dict) else []:
+        if isinstance(item, dict) and item.get("type") == "text":
+            try:
+                return json.loads(item["text"])
+            except (ValueError, TypeError):
+                return None
+    return None
+
+
+class GraphAdapter:
+    """A Microsoft Graph MCP server, by spec.
+
+    spec = {
+      "internal_domains": ["contoso.com"],
+      "kinds": {
+        "<kind>": {"label": "inbox rule", "name_field": "displayName", "id_field": "id",
+                   "list_tool": "...", "list_args": {}, "items_path": "value",
+                   "get_tool": "...", "id_arg": "id",
+                   "create_tool": "...", "create_arg": "rule",
+                   "update_tool": "...", "update_arg": "rule",
+                   "delete_tool": "...",
+                   "writable_fields": ["displayName", "sequence", "conditions", "actions", "isEnabled"]}
+      },
+      "tools": {
+        "<tool name>": {"kind": "<kind>", "op": "create" | "update" | "delete"},
+        "<tool name>": {"op": "irreversible", "label": "send mail", "summary": "sends mail to {toRecipients}: {subject}"}
+      }
+    }"""
+
+    name = "graph"
+
+    def __init__(self, upstream: Any, spec: Dict[str, Any]) -> None:
+        self.upstream = upstream
+        self.spec = spec
+        self._next_id = 0
+
+    @classmethod
+    def from_file(cls, upstream: Any, path: str) -> "GraphAdapter":
+        return cls(upstream, json.loads(Path(path).read_text(encoding="utf-8")))
+
+    # ---- talking to the upstream ----
+    def _call(self, tool: str, args: Dict[str, Any]) -> Any:
+        self._next_id += 1
+        reply = self.upstream.send({"jsonrpc": "2.0", "id": "gargoyle-probe-%d" % self._next_id, "method": "tools/call",
+                                    "params": {"name": tool, "arguments": args}})
+        return _tool_json(reply)
+
+    def _items(self, kind: Dict[str, Any]) -> Optional[List[Dict[str, Any]]]:
+        doc = self._call(kind["list_tool"], dict(kind.get("list_args") or {}))
+        if doc is None:
+            return None
+        items = doc
+        for key in (kind.get("items_path") or "").split("."):
+            if key:
+                items = items.get(key) if isinstance(items, dict) else None
+        if not isinstance(items, list):
+            return None
+        idf = kind.get("id_field", "id")
+        return sorted((i for i in items if isinstance(i, dict) and idf in i), key=lambda i: str(i[idf]))
+
+    def _item(self, kind: Dict[str, Any], item_id: str) -> Optional[Dict[str, Any]]:
+        doc = self._call(kind["get_tool"], {kind.get("id_arg", "id"): item_id})
+        return doc if isinstance(doc, dict) else None
+
+    # ---- descriptions ----
+    @staticmethod
+    def _desc(ref: str, obj: Any, summary: str, irreversible: bool = False) -> Tuple[Dict[str, Any], Optional[bytes]]:
+        data = canonical_json(obj).encode("utf-8") if obj is not None else None
+        desc = describe(ref, data, with_text=False)
+        if data is not None:
+            desc["text"] = json.dumps(obj, indent=2, sort_keys=True)
+        desc["summary"] = summary
+        if irreversible:
+            desc["irreversible"] = True
+        return desc, data
+
+    def _external(self, value: Any) -> List[str]:
+        """Addresses in `value` outside the internal domains."""
+        internal = [d.lower() for d in self.spec.get("internal_domains", [])]
+        found: List[str] = []
+
+        def walk(v):
+            if isinstance(v, str) and "@" in v:
+                dom = v.rsplit("@", 1)[1].strip(">").lower()
+                if internal and dom not in internal:
+                    found.append(v)
+            elif isinstance(v, dict):
+                for x in v.values():
+                    walk(x)
+            elif isinstance(v, list):
+                for x in v:
+                    walk(x)
+        walk(value)
+        return found
+
+    def probe(self, tool: str, args: Any) -> Probe:
+        rule = (self.spec.get("tools") or {}).get(tool)
+        if rule is None or not isinstance(args, dict):
+            return None
+        op = rule.get("op")
+        if op == "irreversible":
+            text = rule.get("summary", "{tool}").replace("{tool}", tool)
+            for k, v in args.items():
+                text = text.replace("{" + k + "}", v if isinstance(v, str) else json.dumps(v))
+            ext = self._external(args)
+            if ext:
+                text += " (to an outside address: %s)" % ", ".join(ext[:3])
+            return self._desc("%s:%s" % (tool, rule.get("label", tool)), None, text + ". Cannot be undone.", irreversible=True)
+        kind = (self.spec.get("kinds") or {}).get(rule.get("kind"))
+        if kind is None:
+            return None
+        label = kind.get("label", rule.get("kind"))
+        name_field = kind.get("name_field")
+        if op == "create":
+            items = self._items(kind)
+            if items is None:
+                return None
+            payload = args.get(kind.get("create_arg", "item"), args)
+            name = payload.get(name_field) if isinstance(payload, dict) and name_field else None
+            summary = "creates %s%s" % (label, (" '%s'" % name) if name else "")
+            ext = self._external(payload)
+            if ext:
+                summary += " (to an outside address: %s)" % ", ".join(ext[:3])
+            return self._desc("%s:all" % rule["kind"], items, summary + "; %d %s(s) exist now" % (len(items), label))
+        item_id = args.get(kind.get("id_arg", "id"))
+        if not isinstance(item_id, str) or not item_id:
+            return None
+        item = self._item(kind, item_id)
+        name = item.get(name_field) if isinstance(item, dict) and name_field else None
+        verb = "updates" if op == "update" else "deletes" if op == "delete" else op
+        summary = "%s %s%s" % (verb, label, (" '%s'" % name) if name else " " + item_id)
+        if op == "update":
+            ext = self._external(args.get(kind.get("update_arg", "item"), args))
+            if ext:
+                summary += " (to an outside address: %s)" % ", ".join(ext[:3])
+        if item is None:
+            summary += " (does not exist now)"
+        return self._desc("%s:%s" % (rule["kind"], item_id), item, summary)
+
+    # ---- undo ----
+    def restore(self, meta: Dict[str, Any], pre: Optional[bytes], post: Optional[bytes]) -> Dict[str, Any]:
+        rule = (self.spec.get("tools") or {}).get(meta.get("tool"))
+        if rule is None:
+            return {"reason": REF_REVERT_UNSUPPORTED}
+        if rule.get("op") == "irreversible":
+            return {"reason": REF_REVERT_IRREVERSIBLE}
+        kind = (self.spec.get("kinds") or {}).get(rule.get("kind")) or {}
+        idf = kind.get("id_field", "id")
+        load = lambda b: json.loads(b.decode("utf-8")) if b is not None else None
+        before, after = load(pre), load(post)
+        if rule["op"] == "create":
+            # The created object is the one in the post set that was not in the pre set.
+            if not isinstance(before, list) or not isinstance(after, list) or not kind.get("delete_tool"):
+                return {"reason": REF_REVERT_UNSUPPORTED}
+            old = {str(i.get(idf)) for i in before}
+            new = [i for i in after if str(i.get(idf)) not in old]
+            if len(new) != 1:
+                return {"reason": REF_REVERT_UNKNOWN}
+            return {"params": {"name": kind["delete_tool"], "arguments": {kind.get("id_arg", "id"): str(new[0][idf])}}}
+        if rule["op"] == "update":
+            if not isinstance(before, dict) or not kind.get("update_tool"):
+                return {"reason": REF_REVERT_UNSUPPORTED}
+            fields = kind.get("writable_fields")
+            body = {k: v for k, v in before.items() if (fields is None or k in fields) and k != idf}
+            return {"params": {"name": kind["update_tool"], "arguments": {kind.get("id_arg", "id"): str(before[idf]),
+                                                                           kind.get("update_arg", "item"): body}}}
+        if rule["op"] == "delete":
+            if not isinstance(before, dict) or not kind.get("create_tool"):
+                return {"reason": REF_REVERT_UNSUPPORTED}
+            fields = kind.get("writable_fields")
+            body = {k: v for k, v in before.items() if (fields is None or k in fields) and k != idf}
+            return {"params": {"name": kind["create_tool"], "arguments": {kind.get("create_arg", "item"): body}}}
+        return {"reason": REF_REVERT_UNSUPPORTED}
+
+
+def adapter_from_name(name: Any, upstream: Any = None, spec_path: Optional[str] = None) -> Any:
+    """GARGOYLE_MCP_STATE_PROBE: "filesystem" (default), "none", or "graph"
+    with GARGOYLE_MCP_ADAPTER_SPEC naming the tool mapping (default: the
+    reference naming shipped in gargoyle/specs/graph-reference.json)."""
+    if name is None or name == "" or name == "filesystem":
+        return FilesystemAdapter()
+    if name == "none":
+        return None
+    if name == "graph":
+        if upstream is None:
+            raise ValueError("the graph adapter needs the upstream server")
+        path = spec_path or str(Path(__file__).parent / "specs" / "graph-reference.json")
+        return GraphAdapter.from_file(upstream, path)
+    if hasattr(name, "probe"):
+        return name
+    if callable(name):
+        return _LegacyProbeAdapter(name)
+    raise ValueError("unknown state probe: %s" % name)
+
+
+class _LegacyProbeAdapter:
+    """A bare probe function (tool, args) -> description, for tests and
+    integrators who wrote one before adapters existed."""
+
+    name = "custom"
+
+    def __init__(self, fn) -> None:
+        self.fn = fn
+
+    def probe(self, tool: str, args: Any) -> Probe:
+        desc = self.fn(tool, args)
+        return None if desc is None else (desc, read_target(desc))
+
+    def restore(self, meta, pre, post):
+        return FilesystemAdapter().restore(meta, pre, post)

{gargoyle_receipts-0.10.0.dev0 → gargoyle_receipts-0.11.0.dev0}/gargoyle/cli.py

@@ -238,6 +238,7 @@ def cmd_remote(args) -> int:
     app = build_remote_app(config, tokens, upstream=upstream, issuer_url=env.get("GARGOYLE_MCP_ISSUER_URL"),
                            audit_log=env.get("GARGOYLE_MCP_AUDIT_LOG") or str(out / "remote-audit.jsonl"),
                            state_probe=args.state_probe, snapshot_dir=env.get("GARGOYLE_MCP_SNAPSHOT_DIR"),
+                           adapter_spec=args.adapter_spec or env.get("GARGOYLE_MCP_ADAPTER_SPEC"),
                            approval_timeout=float(env.get("GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS", "300")))
     tls = {}
     if args.ssl_certfile or args.ssl_keyfile:
@@ -375,8 +376,9 @@ def main(argv=None) -> int:
     p.add_argument("--ssl-certfile"); p.add_argument("--ssl-keyfile")
     p.add_argument("--upstream-url", help="front a remote MCP server (Streamable HTTP)")
     p.add_argument("--upstream-token", help="bearer for that server (or GARGOYLE_MCP_UPSTREAM_TOKEN)")
-    p.add_argument("--state-probe", default="none", choices=["none", "filesystem"],
-                   help="filesystem only when the upstream is a local filesystem server on this host")
+    p.add_argument("--state-probe", default="none", choices=["none", "filesystem", "graph"],
+                   help="filesystem when the upstream is a local filesystem server on this host; graph for a Microsoft Graph MCP server")
+    p.add_argument("--adapter-spec", help="with --state-probe graph: the tool mapping JSON (default: the reference naming)")
     p.add_argument("--verbose", action="store_true")
     p.add_argument("rest", nargs=argparse.REMAINDER, help="-- <command> for a stdio server to front")
     p.set_defaults(fn=cmd_remote)

{gargoyle_receipts-0.10.0.dev0 → gargoyle_receipts-0.11.0.dev0}/gargoyle/mcp_server.py

@@ -99,6 +99,7 @@ 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"
+ENV_ADAPTER_SPEC = "GARGOYLE_MCP_ADAPTER_SPEC"    # with GARGOYLE_MCP_STATE_PROBE=graph: the tool mapping JSON
 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
 
@@ -302,15 +303,18 @@ class ServerState:
         audit_log: Optional[str] = None,
         state_probe: Any = "filesystem",
         snapshot_dir: Optional[str] = None,
+        adapter_spec: Optional[str] = None,
     ) -> None:
-        from gargoyle.state import probe_from_name
+        from gargoyle.adapters import adapter_from_name
         from gargoyle.revert import SnapshotStore
         self.config = config
-        self.probe = state_probe if callable(state_probe) else probe_from_name(state_probe)
+        # The adapter describes, explains and undoes what a tool changes
+        # (gargoyle.adapters): files on this host by default, a Graph server by spec.
+        self.adapter = adapter_from_name(state_probe, upstream, adapter_spec)
         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)
+                                                   if snapshot_dir and snapshot_dir != "none" and self.adapter 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
@@ -363,8 +367,8 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         # verified against the pinned issuer key like any other. The
         # target's current state goes with the request (gargoyle.state), so
         # a hold is approved against it and bound to it.
-        pre_state = state.probe(name, args) if state.probe is not None else None
-        res = state.issuer_client.issue(state.config["target_id"], name, args, state=pre_state)
+        probed = state.adapter.probe(name, args) if state.adapter is not None else None
+        res = state.issuer_client.issue(state.config["target_id"], name, args, state=probed[0] if probed else None)
         if res["envelope"] is None:
             return refused(res["reason"])
         envelope, self_issued = res["envelope"], True
@@ -376,12 +380,12 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
 
     # A state-bound receipt is checked against the state as it is now, after
     # any wait for approval: if the target moved, the call does not run.
-    live_state = None
+    live_state, now_probe = None, None
     if isinstance(envelope, dict) and isinstance(envelope.get("request_context"), dict) \
-            and "state_sha256" in envelope["request_context"] and state.probe is not None:
+            and "state_sha256" in envelope["request_context"] and state.adapter is not None:
         from gargoyle.state import state_sha256 as _state_hash
-        now_desc = state.probe(name, args)
-        live_state = _state_hash(now_desc) if now_desc is not None else None
+        now_probe = state.adapter.probe(name, args)
+        live_state = _state_hash(now_probe[0]) if now_probe is not None else None
     verdict = state.consumer.check(envelope, call_for(name, args, state.config["principal"], live_state),
                                    grant=grant)
     if not verdict.honored:
@@ -390,12 +394,9 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     # 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)):
+            and now_probe 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)
+            state.snapshots.put(envelope["decision_id"], now_probe[0], now_probe[1], name, args)
         except Exception as exc:
             sys.stderr.write("gargoyle: snapshot failed: %s\n" % exc)
 
@@ -445,14 +446,15 @@ def _attest(state: ServerState, envelope: Optional[Dict[str, Any]], outputs: Any
     probed again after the run, so the receipt says what it changed."""
     if state.consumer is None or not state.consumer.attests or envelope is None:
         return None
-    post = None
-    if params is not None and state.probe is not None and "state_sha256" in (envelope.get("request_context") or {}):
+    post, post_data = None, None
+    if params is not None and state.adapter is not None and "state_sha256" in (envelope.get("request_context") or {}):
         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
+        probed = state.adapter.probe(str(params.get("name")), params.get("arguments", {}))
+        if probed is not None:
+            post, post_data = _state_hash(probed[0]), probed[1]
     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)
+            state.snapshots.record_post(envelope["decision_id"], post, post_data)
         except Exception:
             pass
     return state.consumer.attest(envelope, outputs, post_state_sha256=post)
@@ -532,7 +534,7 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
             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)
+            plan = plan_revert(state.snapshots, str((params.get("arguments") or {}).get("decision_id") or "last"), state.adapter)
             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"]}})
@@ -719,7 +721,8 @@ if __name__ == "__main__":
     try:
         serve_stdio(ServerState(config_from_env(), upstream=_upstream, issuer_client=issuer_client_from_env(),
                                 audit_log=_os.environ.get(ENV_AUDIT_LOG) or None,
-                                state_probe=_os.environ.get(ENV_STATE_PROBE) or "filesystem"))
+                                state_probe=_os.environ.get(ENV_STATE_PROBE) or "filesystem",
+                                adapter_spec=_os.environ.get(ENV_ADAPTER_SPEC) or None))
     finally:
         if _upstream is not None:
             _upstream.close()

{gargoyle_receipts-0.10.0.dev0 → gargoyle_receipts-0.11.0.dev0}/gargoyle/remote.py

@@ -138,6 +138,7 @@ def build_remote_app(
     issuer_url: Optional[str] = None,
     audit_log: Optional[str] = None,
     state_probe: Any = "none",
+    adapter_spec: Optional[str] = None,
     snapshot_dir: Optional[str] = None,
     issuer_http: Any = None,
     approval_timeout: float = 300.0,
@@ -177,7 +178,7 @@ def build_remote_app(
                 kw["sleep"] = sleep
             ic = IssuerClient(issuer_url, issuer_token, **kw)
         st = ServerState(dict(config, principal=principal), replay_cache=replay, upstream=upstream, issuer_client=ic,
-                         audit_log=audit_log, state_probe=state_probe, snapshot_dir=snapshot_dir)
+                         audit_log=audit_log, state_probe=state_probe, snapshot_dir=snapshot_dir, adapter_spec=adapter_spec)
         # One log and one snapshot store for the whole process: the chain and
         # the sidecars must not interleave from several session objects.
         if st.evidence is not None:

{gargoyle_receipts-0.10.0.dev0 → gargoyle_receipts-0.11.0.dev0}/gargoyle/revert.py

@@ -32,6 +32,8 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from gargoyle.state import state_sha256
+from gargoyle.adapters import (REF_REVERT_IRREVERSIBLE, REF_REVERT_NEEDS_DELETE, REF_REVERT_NOT_TEXT, REF_REVERT_UNKNOWN,
+                               REF_REVERT_UNSUPPORTED)
 
 REVERT_TOOL = "gargoyle_revert"
 REVERT_TOOL_DEF = {
@@ -42,10 +44,7 @@ REVERT_TOOL_DEF = {
     "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:
@@ -57,9 +56,12 @@ class SnapshotStore:
     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]:
+    def put(self, decision_id: str, description: Dict[str, Any], data: Optional[bytes], tool: str,
+            args: Any = None) -> 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."""
+        did not exist) and a sidecar naming the call, so the same probe can be
+        repeated later to ask whether the target is still as the call left it.
+        Returns the sidecar."""
         self._ensure()
         key = state_sha256(description)
         if data is not None:
@@ -70,17 +72,23 @@ class SnapshotStore:
                     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,
+        meta = {"decision_id": decision_id, "tool": tool, "args": args, "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:
+    def record_post(self, decision_id: str, post_state_sha256: Optional[str], data: Optional[bytes] = None) -> None:
+        """The state the call left: its hash in the sidecar, its bytes under
+        that hash (an adapter may need both snapshots to compose the undo)."""
         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")
+        if data is not None and post_state_sha256:
+            blob = self.dir / (post_state_sha256 + ".bin")
+            if not blob.exists():
+                blob.write_bytes(data)
 
     def sidecars(self) -> List[Dict[str, Any]]:
         if not self.dir.exists():
@@ -100,25 +108,26 @@ class SnapshotStore:
         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
+def plan_revert(store: SnapshotStore, decision_id: str, adapter) -> Dict[str, Any]:
+    """The call that undoes `decision_id`, or a refusal:
+    {"params": {"name", "arguments"}, "reverts": id} | {"reason": REF_REVERT_*}.
+    The adapter composes the inverse from the two snapshots and confirms 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:
+    if adapter is None:
+        return {"reason": REF_REVERT_UNSUPPORTED}
+    pre = store.content(meta["pre_state_sha256"]) if meta.get("existed") else None
+    if meta.get("existed") and pre 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"]:
+    post = store.content(meta["post_state_sha256"])
+    plan = adapter.restore(meta, pre, post)
+    if "reason" in plan:
+        return plan
+    # Still as the original call left it? Repeat the original call's probe
+    # now and compare with the state recorded after it ran.
+    probe = adapter.probe(meta["tool"], meta.get("args") if meta.get("args") is not None else {"path": meta["ref"]})
+    if probe is None or state_sha256(probe[0]) != meta["post_state_sha256"]:
         return {"reason": REF_REVERT_STATE_CHANGED}
-    return {"params": {"name": "write_file", "arguments": args}, "reverts": meta["decision_id"]}
+    return {"params": plan["params"], "reverts": meta["decision_id"]}