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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.10.0.dev0
+Version: 0.12.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.12.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,35 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Scoped grants
+
+One card per held call is right for a mailbox rule and wrong for a long
+task. The assistant can ask for a plan (`gargoyle_plan`): a list of steps,
+each a tool with exact arguments or argument patterns, and a note saying
+why. The issuer judges every step under the policy, signs the plan, and
+holds it as one card; the approver signs once; each later call matching
+an unused step runs without a card of its own until the plan expires.
+Every step is still bound, claimed once, and recorded with the plan and
+step that released it. The rules file decides what may be planned
+(`"plan": false` keeps a tool individual; sends should be), because a
+plan approves scope rather than content.
+
+## 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 +370,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.12.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.12.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,35 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Scoped grants
+
+One card per held call is right for a mailbox rule and wrong for a long
+task. The assistant can ask for a plan (`gargoyle_plan`): a list of steps,
+each a tool with exact arguments or argument patterns, and a note saying
+why. The issuer judges every step under the policy, signs the plan, and
+holds it as one card; the approver signs once; each later call matching
+an unused step runs without a card of its own until the plan expires.
+Every step is still bound, claimed once, and recorded with the plan and
+step that released it. The rules file decides what may be planned
+(`"plan": false` keeps a tool individual; sends should be), because a
+plan approves scope rather than content.
+
+## 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 +332,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.12.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.12.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:
@@ -310,6 +311,8 @@ 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("plan"):
+                why += " (plan %s step %d)" % (str(r["plan"].get("plan_id") or "?")[:8], r["plan"].get("step", -1) + 1)
             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]
@@ -375,8 +378,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.12.0.dev0}/gargoyle/consumer.py

@@ -273,6 +273,7 @@ class Consumer:
         *,
         grant: Any = None,
         now: Optional[datetime] = None,
+        plan_release: Any = None,
     ) -> Verdict:
         """Decide whether to honor `envelope` for `call` ({"tool", "args",
         "principal"}, the principal being the one this consumer
@@ -321,7 +322,26 @@ class Consumer:
         # inside the signed region, so they are the issuer's word, not the
         # caller's. The grant is checked and claimed before the receipt is
         # claimed, so a refused grant leaves the receipt unspent.
-        if envelope["requires_approval"]:
+        if envelope["requires_approval"] and plan_release is not None:
+            # A scoped grant (gargoyle.plans): the plan's step is claimed once
+            # in place of a per-call grant id.
+            from gargoyle.plans import verify_plan_release
+            approver_keys = self._approver_keys(key_record_view, envelope.get("issuer_key_id"), now)
+            if not approver_keys:
+                return Verdict(False, REF_TARGET_NO_APPROVER_TRUST)
+            r = verify_plan_release(plan_release, envelope, call, issuer_public_keys=pinned_public_keys,
+                                    approver_public_keys=approver_keys, now=now, clock_skew=self.clock_skew)
+            if not r["accepted"]:
+                return Verdict(False, r["reason"])
+            plan = plan_release["plan"]
+            try:
+                plan_exp = datetime.fromisoformat(plan["not_after"]) + self.clock_skew
+            except (ValueError, TypeError, KeyError):
+                plan_exp = None
+            if not self.replay_cache.check_and_claim("plan:%s:%d" % (plan["plan_id"], r["step"]), plan_exp, now=now):
+                from gargoyle.plans import REF_PLAN_STEP_CONSUMED
+                return Verdict(False, REF_PLAN_STEP_CONSUMED)
+        elif envelope["requires_approval"]:
             grants = as_grant_list(grant)
             if not grants:
                 return Verdict(False, REF_TARGET_APPROVAL_REQUIRED)

{gargoyle_receipts-0.10.0.dev0 → gargoyle_receipts-0.12.0.dev0}/gargoyle/evidence.py

@@ -192,7 +192,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})
+                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None})
             all_ok = False
             continue
         e = raw
@@ -218,14 +218,19 @@ def verify_log(
                                       now=_parse_at(e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         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 []
+        plan_ref = None
+        grant_set = e["grant"]
+        if isinstance(grant_set, dict) and "plan" in grant_set and "step" in grant_set:
+            plan_ref = {"plan_id": (grant_set["plan"] or {}).get("plan_id"), "step": grant_set["step"]}
+            grant_set = grant_set.get("grants")
+        released_by = [g.get("approver_key_id") for g in (grant_set if isinstance(grant_set, list) else [grant_set])
+                       if isinstance(g, dict)] if grant_set 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,
-                       "state": state, "client": e.get("client")})
+                       "state": state, "client": e.get("client"), "plan": plan_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.10.0.dev0 → gargoyle_receipts-0.12.0.dev0}/gargoyle/execution.py

@@ -218,10 +218,17 @@ def verify_chain(
         return {"accepted": False, "reason": provenance["reason"], "steps": steps}
 
     if envelope["requires_approval"]:
-        if not as_grant_list(grant):
+        from gargoyle.plans import is_plan_release, verify_plan_release
+        if is_plan_release(grant):
+            # Released by a scoped grant: the plan, its grants and the step,
+            # re-matched against the arguments the release recorded.
+            g = verify_plan_release(grant, envelope, {}, issuer_public_keys=issuer_public_keys,
+                                    approver_public_keys=approver_public_keys or {}, now=executed_at)
+        elif not as_grant_list(grant):
             steps.append(("approval", REF_EXEC_GRANT_MISSING))
             return {"accepted": False, "reason": REF_EXEC_GRANT_MISSING, "steps": steps}
-        g = verify_grants(grant, envelope=envelope, approver_public_keys=approver_public_keys or {}, now=executed_at)
+        else:
+            g = verify_grants(grant, envelope=envelope, approver_public_keys=approver_public_keys or {}, now=executed_at)
         steps.append(("approval", g["reason"]))
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"], "steps": steps}