gargoyle-receipts 0.16.4.dev0__tar.gz → 0.17.0.dev0__tar.gz

{gargoyle_receipts-0.16.4.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.17.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.4.dev0
+Version: 0.17.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.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.17.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
@@ -161,7 +161,9 @@ two-method interface.
 **No engine.** `gargoyle.rules.RulesPolicy` decides from a JSON file:
 first matching rule wins, globs on tool name, principal, delegation,
 the caller's groups and roles, and string arguments, actions allow, hold
-or deny. The pin is the file's hash,
+or deny. Argument globs that look like paths are matched on a normalized
+form (separators, `..`, letter case), so a rule for one folder is not
+slipped by traversal or spelling; `*` spans folders. The pin is the file's hash,
 so an edit invalidates outstanding receipts exactly as an engine change
 does. This is what `gargoyle init` sets up.
 
@@ -303,7 +305,11 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Every key an approver held stays in the file
+is never accepted again. The role is what counts at release time: a
+grant under an enrolled key is accepted only from that account, under a
+token that carries the role now, so a role removed in the directory ends
+the power at once. One key per account: a second browser does not enroll
+until the first key consents or the operator revokes it. Every key an approver held stays in the file
 (`history`), so an audit of grants released under an earlier key still
 verifies: copy the issuer's current `approvers.json` beside the evidence
 before auditing. Approvers, and
@@ -402,6 +408,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_MAX_OPEN_HOLDS` | how many held receipts and plans one principal may have waiting at once (default 20); the call over the cap is `REF_ISSUER_TOO_MANY_HOLDS` and nothing is stored |
+| issuer `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
@@ -410,7 +417,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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_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; the replay claims that make a receipt single-use live beside it in `<log stem>.replay.sqlite`, so a restarted gate still refuses a receipt it honored |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`): identity token in, receipt out, with the hold and grant
@@ -458,7 +465,7 @@ on it.
 | `mcp_server` | the stdio MCP middleware (and demo executor), with self-issue mode |
 | `fs_server` | a small Python filesystem MCP server, for clients without Node |
 | `issuer_service` | the HTTP issuing service: identity in, receipts out, holds and grants |
-| `replay_cache`, `pending_store` | single use for receipts and holds; in-memory or Redis |
+| `replay_cache`, `pending_store` | single use for receipts and holds; in memory, SQLite beside the audit log (the middleware's default) or Redis |
 | `approval`, `approver_cli`, `approver_trust` | grants, the human's tool, approver key trust |
 | `published_record_source` | the live policy pin as a publisher-signed record with serial and expiry |
 | `key_record_source` | root-signed issuer and approver keys with windows and revocation |

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.17.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.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.17.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
@@ -123,7 +123,9 @@ two-method interface.
 **No engine.** `gargoyle.rules.RulesPolicy` decides from a JSON file:
 first matching rule wins, globs on tool name, principal, delegation,
 the caller's groups and roles, and string arguments, actions allow, hold
-or deny. The pin is the file's hash,
+or deny. Argument globs that look like paths are matched on a normalized
+form (separators, `..`, letter case), so a rule for one folder is not
+slipped by traversal or spelling; `*` spans folders. The pin is the file's hash,
 so an edit invalidates outstanding receipts exactly as an engine change
 does. This is what `gargoyle init` sets up.
 
@@ -265,7 +267,11 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Every key an approver held stays in the file
+is never accepted again. The role is what counts at release time: a
+grant under an enrolled key is accepted only from that account, under a
+token that carries the role now, so a role removed in the directory ends
+the power at once. One key per account: a second browser does not enroll
+until the first key consents or the operator revokes it. Every key an approver held stays in the file
 (`history`), so an audit of grants released under an earlier key still
 verifies: copy the issuer's current `approvers.json` beside the evidence
 before auditing. Approvers, and
@@ -364,6 +370,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_MAX_OPEN_HOLDS` | how many held receipts and plans one principal may have waiting at once (default 20); the call over the cap is `REF_ISSUER_TOO_MANY_HOLDS` and nothing is stored |
+| issuer `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
@@ -372,7 +379,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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_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; the replay claims that make a receipt single-use live beside it in `<log stem>.replay.sqlite`, so a restarted gate still refuses a receipt it honored |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`): identity token in, receipt out, with the hold and grant
@@ -420,7 +427,7 @@ on it.
 | `mcp_server` | the stdio MCP middleware (and demo executor), with self-issue mode |
 | `fs_server` | a small Python filesystem MCP server, for clients without Node |
 | `issuer_service` | the HTTP issuing service: identity in, receipts out, holds and grants |
-| `replay_cache`, `pending_store` | single use for receipts and holds; in-memory or Redis |
+| `replay_cache`, `pending_store` | single use for receipts and holds; in memory, SQLite beside the audit log (the middleware's default) or Redis |
 | `approval`, `approver_cli`, `approver_trust` | grants, the human's tool, approver key trust |
 | `published_record_source` | the live policy pin as a publisher-signed record with serial and expiry |
 | `key_record_source` | root-signed issuer and approver keys with windows and revocation |

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.17.0.dev0}/gargoyle/adapters.py

@@ -135,9 +135,10 @@ class GraphAdapter:
     @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)
+        # The text is the hashed bytes themselves (canonical JSON), so the
+        # console can verify it against the bound state before showing it;
+        # it pretty-prints JSON for display.
+        desc = describe(ref, data, with_text=True)
         desc["summary"] = summary
         if irreversible:
             desc["irreversible"] = True

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.17.0.dev0}/gargoyle/cli.py

@@ -395,15 +395,19 @@ def _audit_summary(report, raw) -> None:
     releases: Counter = Counter()
     clients: Counter = Counter()
     ats = [e.get("at") for e in raw if isinstance(e, dict) and isinstance(e.get("at"), str)]
+    from gargoyle.evidence import FAILED_VERDICTS
     for r in report:
-        counts.setdefault((r["principal"] or "?", r["tool"] or "?"), Counter())[r["kind"] or "?"] += 1
+        kind = r["kind"] or "?"
+        if kind == "honored" and r.get("verdict") in FAILED_VERDICTS:
+            kind = "failed"            # admitted, but the upstream did not do it
+        counts.setdefault((r["principal"] or "?", r["tool"] or "?"), Counter())[kind] += 1
         for who in r.get("released_by") or []:
             releases[who] += 1
         clients[r.get("client") or "(client unnamed)"] += 1
     print("summary: %d call(s)%s" % (len(report), (", %s to %s" % (min(ats)[:19], max(ats)[:19])) if ats else ""))
-    print("  %-28s %-24s %7s %7s" % ("principal", "tool", "honored", "refused"))
+    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "failed", "refused"))
     for (principal, tool), c in sorted(counts.items(), key=lambda kv: (kv[0][0], -sum(kv[1].values()), kv[0][1])):
-        print("  %-28s %-24s %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("refused", 0)))
+        print("  %-28s %-24s %7d %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("failed", 0), c.get("refused", 0)))
     if releases:
         print("  releases: " + ", ".join("%s %d" % (w, n) for w, n in releases.most_common()))
     print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.17.0.dev0}/gargoyle/envelope.py

@@ -208,7 +208,9 @@ def valid_principal(principal: Any) -> bool:
 def valid_approval(approval: Any) -> bool:
     """True iff `approval` is a well-formed receipt `approval` member:
     {"required": int >= 1, "approvers": [non-empty unique strings] optional}."""
-    if not isinstance(approval, dict) or not set(approval) <= {"required", "approvers"} or "required" not in approval:
+    if not isinstance(approval, dict) or not set(approval) <= {"required", "approvers", "plannable"} or "required" not in approval:
+        return False
+    if "plannable" in approval and not isinstance(approval["plannable"], bool):
         return False
     required = approval["required"]
     if isinstance(required, bool) or not isinstance(required, int) or required < 1:
@@ -320,6 +322,8 @@ def build_envelope(
         envelope["approval"] = {"required": approval["required"]}
         if "approvers" in approval:
             envelope["approval"]["approvers"] = sorted(approval["approvers"])
+        if approval.get("plannable") is False:
+            envelope["approval"]["plannable"] = False
     envelope["decision_sha256"] = decision_sha256_of(envelope)
     return envelope
 
@@ -329,8 +333,8 @@ def approval_terms(envelope: Dict[str, Any]) -> Dict[str, Any]:
     the receipt's `approval` member, or the default of one from anyone."""
     a = envelope.get("approval")
     if isinstance(a, dict):
-        return {"required": a["required"], "approvers": a.get("approvers")}
-    return {"required": 1, "approvers": None}
+        return {"required": a["required"], "approvers": a.get("approvers"), "plannable": a.get("plannable", True)}
+    return {"required": 1, "approvers": None, "plannable": True}
 
 
 def reassert(

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.17.0.dev0}/gargoyle/evidence.py

@@ -63,6 +63,17 @@ REF_EVIDENCE_HASH_MISMATCH = "REF_EVIDENCE_HASH_MISMATCH"  # entry_sha256 does n
 REF_EVIDENCE_CHAIN_BROKEN = "REF_EVIDENCE_CHAIN_BROKEN"    # seq or prev_sha256 does not follow
 REF_EVIDENCE_RECEIPT_MISSING = "REF_EVIDENCE_RECEIPT_MISSING"  # honored without receipt or execution
 REF_EVIDENCE_UNCHAINED = "REF_EVIDENCE_UNCHAINED"       # a pre-chain {receipt, grant, execution} line
+REF_EVIDENCE_REPLAY = "REF_EVIDENCE_REPLAY"             # a decision id (or plan step) honored twice in one log
+
+# Verdicts an honored entry carries when the admitted call did not succeed
+# downstream: the receipt was claimed, so the entry must exist, and the
+# verdict says the change most likely did not happen (the execution receipt's
+# outputs carry the error). Any other verdict on an honored entry is the
+# verifier's accept reason.
+TOOL_ERROR = "TOOL_ERROR"                       # the upstream answered with isError: true
+UPSTREAM_ERROR = "UPSTREAM_ERROR"               # the upstream answered with a JSON-RPC error
+UPSTREAM_UNAVAILABLE = "UPSTREAM_UNAVAILABLE"   # the upstream could not be reached after the claim
+FAILED_VERDICTS = frozenset((TOOL_ERROR, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE))
 
 _FIELDS = ("evidence_version", "seq", "prev_sha256", "at", "kind", "tool", "args_sha256",
            "principal", "reason", "receipt", "grant", "execution", "entry_sha256")
@@ -191,6 +202,7 @@ def verify_log(
     expect_seq, prev, tail = 1, GENESIS, GENESIS
     counts = {HONORED: 0, REFUSED: 0}
     all_ok = True
+    claimed: Dict[str, int] = {}      # decision_id / plan step -> seq of the honored entry that spent it
 
     for raw in entries:
         if not _well_formed(raw):
@@ -220,6 +232,19 @@ def verify_log(
                 if ok and (rc.get("tool") != e["tool"] or rc.get("args_sha256") != e["args_sha256"]
                            or rc.get("principal") != e["principal"]):
                     ok, reason = False, REF_EVIDENCE_RECEIPT_MISSING
+                if ok:
+                    # Single use, checked after the fact: a decision id, or a
+                    # plan step, honored twice in one log is a replay the
+                    # executor's cache missed (a second process, a lost cache).
+                    keys = [str(e["receipt"].get("decision_id"))]
+                    gs = e["grant"]
+                    if isinstance(gs, dict) and "plan" in gs and "step" in gs:
+                        keys.append("plan:%s:%s" % ((gs["plan"] or {}).get("plan_id"), gs["step"]))
+                    if any(k in claimed for k in keys):
+                        ok, reason = False, REF_EVIDENCE_REPLAY
+                    else:
+                        for k in keys:
+                            claimed[k] = e["seq"]
         else:
             reason = ACCEPT_ENTRY_VERIFIED
             if e["receipt"] is not None:

gargoyle_receipts-0.17.0.dev0/gargoyle/globs.py

@@ -0,0 +1,58 @@
+"""Argument globs, as rules (gargoyle.rules) and plan steps (gargoyle.plans)
+use them: `fnmatch` patterns over one argument value, with paths made safe
+to match.
+
+A raw `fnmatch` on a path is a hole: `C:\\proj\\*` is slipped by
+`C:\\proj\\..\\secrets\\x`, by `c:\\PROJ\\x` on a case-insensitive disk and
+by `C:/proj/x`. So when either side looks like a path (a separator, or a
+drive letter), both are normalized first: separators become `/`, `.` and
+`..` segments are resolved lexically, repeated separators collapse, and
+the whole string is lower-cased, since the gate cannot know the target
+filesystem's case rules and a rule meant for one folder must not be
+slipped by a letter. Values that look like nothing of the kind (a mail
+address, an account id) are matched exactly as written, case included.
+
+`*` spans folders: a rule for `C:\\proj\\*` covers the whole tree under it.
+There is no segment-bounded wildcard; a rule that wants one folder level
+names it.
+"""
+
+import fnmatch
+import posixpath
+import re
+
+_PATHLIKE = re.compile(r"[\\/]|^[A-Za-z]:")
+_DRIVE = re.compile(r"^([A-Za-z]:)(.*)$", re.S)
+
+
+def is_pathlike(value: str) -> bool:
+    return bool(_PATHLIKE.search(value))
+
+
+def normalize_path(value: str) -> str:
+    """The comparable form of a path or path glob (see the module note)."""
+    text = value.replace("\\", "/")
+    drive = ""
+    m = _DRIVE.match(text)
+    if m:
+        drive, text = m.group(1), m.group(2) or "/"
+        if text.startswith("/"):
+            text = "/" + text.lstrip("/")       # after a drive, repeated separators are just separators
+    unc = not drive and text.startswith("//") and not text.startswith("///")
+    text = posixpath.normpath(text) if text else ""
+    if unc and not text.startswith("//"):
+        text = "/" + text
+    return (drive + text).lower()
+
+
+def comparable(glob: str, value: str):
+    """Both sides as they are compared: normalized when either is a path."""
+    if is_pathlike(value) or is_pathlike(glob):
+        return normalize_path(glob), normalize_path(value)
+    return glob, value
+
+
+def glob_match(glob: str, value: str) -> bool:
+    """Does the argument value match the glob? Paths normalized first."""
+    g, v = comparable(glob, value)
+    return fnmatch.fnmatchcase(v, g)

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.17.0.dev0}/gargoyle/issuer_service.py

@@ -53,7 +53,7 @@ STATIC = Path(__file__).resolve().parent / "static"
 from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_DUPLICATE_APPROVER,
                                verify_grant)
 from gargoyle.envelope import approval_terms
-from gargoyle.state import state_sha256, valid_description
+from gargoyle.state import state_sha256, text_consistent, valid_description
 from gargoyle.holdstore import ENV_HOLDS_PATH, HoldStore
 from gargoyle.witness import WitnessLog
 from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF_PLAN_STEP_REFUSED, build_plan,
@@ -62,6 +62,7 @@ from gargoyle.notify import notifier_from_env
 from gargoyle.approvers import (DEFAULT_APPROVER_ROLE, ENV_APPROVER_GROUPS, ENV_APPROVER_ROLE, ENV_APPROVERS_PATH,
                                 ApproverRegistry, RevokedKeyError, may_enroll, valid_public_key_hex)
 from gargoyle.identity import entra_keys, entra_tenant_id, principal_from_token
+from gargoyle.jws import REF_JWS_KEY_UNKNOWN
 from gargoyle.issuer import DEFAULT_TTL_SECONDS, issue
 from gargoyle.policy import Policy
 
@@ -80,6 +81,7 @@ ENV_RECEIPT_TTL = "GARGOYLE_RECEIPT_TTL_SECONDS"
 ENV_CONSOLE_CLIENT_ID = "GARGOYLE_ENTRA_CLIENT_ID"   # the public client app the console signs in with (User-Client-Flow)
 ENV_CONSOLE_SCOPE = "GARGOYLE_ENTRA_SCOPE"           # default api://<last audience>/access
 ENV_MAX_OPEN_HOLDS = "GARGOYLE_MAX_OPEN_HOLDS"       # holds one principal may have waiting at once
+ENV_ALLOW_SELF_APPROVAL = "GARGOYLE_ALLOW_SELF_APPROVAL"   # "1": a person may release their own call (default: refused)
 DEFAULT_MAX_OPEN_HOLDS = 20
 
 REF_ISSUER_UNAUTHENTICATED = "REF_ISSUER_UNAUTHENTICATED"
@@ -91,6 +93,31 @@ REF_ISSUER_NOT_AN_APPROVER = "REF_ISSUER_NOT_AN_APPROVER"   # enrollment without
 REF_ISSUER_FORBIDDEN = "REF_ISSUER_FORBIDDEN"               # authenticated, but not an approver and not the hold's own principal
 REF_ISSUER_TOO_MANY_HOLDS = "REF_ISSUER_TOO_MANY_HOLDS"     # the principal already has the cap's worth of holds waiting
 REF_ISSUER_KEY_REVOKED = "REF_ISSUER_KEY_REVOKED"           # enrollment offered a key that was revoked; a new key is needed
+REF_ISSUER_KEY_ENROLLED = "REF_ISSUER_KEY_ENROLLED"          # another key is enrolled for this account; it must consent, or the operator revoke it
+REF_ISSUER_HOLD_EXPIRED = "REF_ISSUER_HOLD_EXPIRED"          # the hold's receipt or plan expired; nothing can release it now
+REF_ISSUER_SELF_APPROVAL = "REF_ISSUER_SELF_APPROVAL"        # the approver is the hold's requester (or the party acted for)
+REF_ISSUER_STATE_TEXT_MISMATCH = "REF_ISSUER_STATE_TEXT_MISMATCH"  # the state text is not the bytes the state hash names
+
+
+SUPERSEDE_PREFIX = b"gargoyle-enroll/1\n"
+
+
+def supersede_message(new_public_key_hex: str) -> bytes:
+    """What an enrolled key signs to hand its account to a new key."""
+    return SUPERSEDE_PREFIX + new_public_key_hex.encode("ascii")
+
+
+def _supersedes(current_hex: str, signature_hex: Any, new_hex: str) -> bool:
+    """Does `signature_hex` (Ed25519, by the key `current_hex`) consent to `new_hex`?"""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    if not isinstance(signature_hex, str) or len(signature_hex) != 128:
+        return False
+    try:
+        Ed25519PublicKey.from_public_bytes(bytes.fromhex(current_hex)).verify(bytes.fromhex(signature_hex), supersede_message(new_hex))
+        return True
+    except (InvalidSignature, ValueError):
+        return False
 
 
 def build_issuer_app(
@@ -114,10 +141,19 @@ def build_issuer_app(
     tenant: Optional[str] = None,
     tenant_key_ids: Optional[set] = None,
     max_open_holds: int = DEFAULT_MAX_OPEN_HOLDS,
+    idp_key_refresh: Optional[Callable[[], Dict[str, Any]]] = None,
+    allow_self_approval: bool = False,
 ) -> FastAPI:
     """`on_hold(envelope, args)` is called once for every new hold (gargoyle.notify
     posts it to a webhook); it is notice, not admission, and its failure
-    never affects the hold."""
+    never affects the hold. `idp_key_refresh()` returns the identity
+    provider's current signing keys {kid: key}; it is called, at most once a
+    minute, when a token names a kid the service does not know, so a key the
+    directory rolled after startup is picked up without a restart."""
+    # The trusted identity keys are held in a dict this app owns: a refresh adds to them.
+    idp_public_keys = dict(idp_public_keys)
+    tenant_key_ids = set(tenant_key_ids) if tenant_key_ids is not None else None
+    key_refreshed_at: list = [None]
     app = FastAPI(title="Gargoyle issuing service")
     # Everything a human may be in the middle of acting on lives in the hold
     # store (gargoyle.holdstore): SQLite on disk in a deployment, memory in tests.
@@ -170,9 +206,21 @@ def build_issuer_app(
 
     def is_approver(who: Dict[str, Any]) -> bool:
         """May this identity see every hold and the witness: the approver role
-        or group, a configured approver key id, or an enrolled approver."""
+        or group in today's token, or a configured approver key id. An
+        enrolled key alone does not count: the directory decides who is an
+        approver now, the registry only remembers which key is theirs."""
         upn = who["principal"]
-        return may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers or upn in registry
+        return may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers
+
+    def _enrolled_speaks_for(who: Dict[str, Any], approver_key_id: str) -> bool:
+        """May a grant under this key id be posted by `who`? A configured
+        (static) key is trusted by configuration. An enrolled key releases a
+        hold only when posted by its own account, under a token that still
+        carries the approver role or group: losing the role ends the power
+        at once, whatever key record remains (second review, finding 2)."""
+        if approver_key_id in static_approvers or approver_key_id not in registry:
+            return True
+        return who["principal"] == approver_key_id and may_enroll(who, role=approver_role, groups=approver_groups)
 
     def hold_owner(arid: str) -> Optional[str]:
         """The principal whose call is held under `arid` (a hold or a plan), or None."""
@@ -200,11 +248,35 @@ def build_issuer_app(
     def _refuse(status: int, reason: str) -> HTTPException:
         return HTTPException(status_code=status, detail={"reason": reason})
 
+    def _refresh_idp_keys() -> bool:
+        """Fetch the identity provider's keys again (an unknown kid is how a
+        key roll shows up), at most once a minute. True when new keys came."""
+        if idp_key_refresh is None:
+            return False
+        current = now()
+        last = key_refreshed_at[0]
+        if last is not None and (current - last).total_seconds() < 60:
+            return False
+        key_refreshed_at[0] = current
+        try:
+            fresh = idp_key_refresh()
+        except Exception as exc:
+            import sys
+            sys.stderr.write("gargoyle: identity key refresh failed: %s\n" % exc)
+            return False
+        new = {k: v for k, v in fresh.items() if k not in idp_public_keys}
+        idp_public_keys.update(fresh)
+        if tenant_key_ids is not None:
+            tenant_key_ids.update(fresh)
+        return bool(new)
+
     def authenticate(authorization: Optional[str]) -> Dict[str, Any]:
         if not authorization or not authorization.startswith("Bearer "):
             raise _refuse(401, REF_ISSUER_UNAUTHENTICATED)
-        who = principal_from_token(authorization[7:].strip(), idp_public_keys, audience=audience, now=now(),
-                                   tenant=tenant, tenant_key_ids=tenant_key_ids)
+        token = authorization[7:].strip()
+        who = principal_from_token(token, idp_public_keys, audience=audience, now=now(), tenant=tenant, tenant_key_ids=tenant_key_ids)
+        if who["reason"] == REF_JWS_KEY_UNKNOWN and _refresh_idp_keys():
+            who = principal_from_token(token, idp_public_keys, audience=audience, now=now(), tenant=tenant, tenant_key_ids=tenant_key_ids)
         if who["reason"] is not None:
             raise _refuse(401, who["reason"])
         return who
@@ -227,11 +299,17 @@ def build_issuer_app(
             json.dumps(body["args"], ensure_ascii=False).encode("utf-8")
         except UnicodeEncodeError:
             raise _refuse(400, REF_ISSUER_ARGS_NOT_TEXT)
-        # The policy sees the identity provider's groups and roles as claims;
-        # the receipt binds only the call and the principal.
-        interaction = {**body.get("claims", {}), "tool": body["tool"], "args": body["args"],
+        # The policy sees the identity provider's groups and roles; the receipt
+        # binds only the call and the principal (and the token's delegation).
+        # Anything the caller asserts in `claims` is kept apart under
+        # interaction["claims"]: it never sets principal, on_behalf_of,
+        # groups, roles or the state hash, which come from the token and the
+        # described state alone (second review, finding 3).
+        interaction = {"tool": body["tool"], "args": body["args"],
                        "principal": who["principal"], "groups": who.get("groups", []),
                        "roles": who.get("roles", [])}
+        if body.get("claims"):
+            interaction["claims"] = dict(body["claims"])
         state = body.get("state")
         if state is not None:
             # The executor's description of the target before the call: its
@@ -239,6 +317,9 @@ def build_issuer_app(
             # the approver and seen by the policy.
             if not valid_description(state):
                 raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+            if not text_consistent(state):
+                # The text shown to the approver must hash to the bound state.
+                raise _refuse(400, REF_ISSUER_STATE_TEXT_MISMATCH)
             interaction["state_sha256"] = state_sha256(state)
             interaction["state"] = {k: v for k, v in state.items() if k != "text"}
         if who["on_behalf_of"]:
@@ -250,15 +331,18 @@ def build_issuer_app(
             return {"issued": False, "reason": result.decision.reason}
         covered = False
         plan_id = body.get("plan_id")
-        if result.envelope["requires_approval"] and isinstance(plan_id, str):
-            # The executor says an approved plan covers this call. No card then:
-            # the executor enforces the plan (step single use, grants, expiry)
-            # and the console should not show a hold nobody needs to act on.
-            # A false claim costs nothing here: without a valid release the
-            # executor refuses the call.
-            from gargoyle.plans import match_step
+        if result.envelope["requires_approval"] and isinstance(plan_id, str) and result.decision.plannable:
+            # The executor says an approved plan covers this call. No card then,
+            # provided the plan's grants meet this receipt's own terms (as many
+            # signatures, from its named approvers): the executor enforces the
+            # same, so a hold here would be one nobody needs to act on. A call
+            # the policy keeps individual is never covered. A false claim costs
+            # nothing: without a valid release the executor refuses the call.
+            from gargoyle.plans import grants_satisfy, match_step
+            env_terms = approval_terms(result.envelope)
             for arid_p, plan in app.state.pending_plans.items():
-                if plan["plan_id"] == plan_id and _complete(arid_p) and match_step(plan, body["tool"], body["args"]) is not None:
+                if (plan["plan_id"] == plan_id and _complete(arid_p) and match_step(plan, body["tool"], body["args"]) is not None
+                        and grants_satisfy(env_terms, [g["approver_key_id"] for g in app.state.grants.get(arid_p, [])])):
                     covered = True
                     break
         if result.envelope["requires_approval"] and not covered and _open_holds(who["principal"]) >= max_open_holds:
@@ -312,7 +396,16 @@ def build_issuer_app(
             interaction = {"tool": s["tool"], "args": judged_args, "principal": who["principal"],
                            "groups": who.get("groups", []), "roles": who.get("roles", [])}
             try:
-                d = policy.decide(body["target_url"], interaction)
+                if "match" in step:
+                    # A pattern step is judged by the strictest rule any call
+                    # matching it could reach (gargoyle.rules.decide_rules_pattern).
+                    # A policy that cannot judge patterns keeps them out of plans.
+                    decide_pattern = getattr(policy, "decide_pattern", None)
+                    if decide_pattern is None:
+                        return {"issued": False, "reason": REF_PLAN_STEP_NOT_PLANNABLE, "step": len(norm)}
+                    d = decide_pattern(body["target_url"], interaction)
+                else:
+                    d = policy.decide(body["target_url"], interaction)
             except Exception:
                 return {"issued": False, "reason": REF_PLAN_STEP_REFUSED}
             if not d.eligible:
@@ -355,8 +448,7 @@ def build_issuer_app(
         live = {}
         for arid, plan in list(app.state.pending_plans.items()):
             if datetime.fromisoformat(plan["not_after"]) <= current:
-                del app.state.pending_plans[arid]
-                app.state.grants.pop(arid, None)
+                _forget(arid)
             elif len(app.state.grants.get(arid, [])) < _plan_terms(plan)["required"]:
                 if not sees_all and plan.get("principal") != who["principal"]:
                     continue
@@ -365,10 +457,7 @@ def build_issuer_app(
                               "approvers": [g["approver_key_id"] for g in have]}
         for arid, env in list(app.state.pending.items()):
             if datetime.fromisoformat(env["not_after"]) <= current:
-                del app.state.pending[arid]           # an expired hold can never be released
-                app.state.pending_args.pop(arid, None)
-                app.state.pending_state.pop(arid, None)
-                app.state.grants.pop(arid, None)
+                _forget(arid)                         # an expired hold can never be released
             elif not _complete(arid):
                 if not sees_all and env.get("request_context", {}).get("principal") != who["principal"]:
                     continue
@@ -379,6 +468,14 @@ def build_issuer_app(
                               "approvers": [g["approver_key_id"] for g in have]}
         return {"pending": list(live.values())}
 
+    def _forget(arid: str) -> None:
+        """Drop a hold or plan and everything kept for it."""
+        app.state.pending.pop(arid, None)
+        app.state.pending_args.pop(arid, None)
+        app.state.pending_state.pop(arid, None)
+        app.state.pending_plans.pop(arid, None)
+        app.state.grants.pop(arid, None)
+
     def _complete(arid: str) -> bool:
         env = app.state.pending.get(arid)
         if env is None:
@@ -388,7 +485,7 @@ def build_issuer_app(
 
     @app.post("/grants")
     async def post_grant(request: Request, authorization: Optional[str] = Header(default=None)):
-        authenticate(authorization)
+        who = authenticate(authorization)
         try:
             grant = await request.json()
         except Exception:
@@ -404,6 +501,13 @@ def build_issuer_app(
             kid = grant.get("approver_key_id")
             event("grant_refused", approval_request_id=arid, reason=reason, **({"approver": kid} if isinstance(kid, str) else {}))
             return {"accepted": False, "reason": reason}
+        if datetime.fromisoformat((env or plan)["not_after"]) <= now():
+            # An expired hold can never be released: the executor refuses the
+            # receipt whatever the grant says, so accepting one here would
+            # only tell the approver that something ran. Drop it now, not on
+            # the next listing (second review, finding 10).
+            _forget(arid)
+            return refused(REF_ISSUER_HOLD_EXPIRED)
         trusted = approver_keys()
         if not trusted:
             return refused(REF_ISSUER_NO_APPROVER_TRUST)
@@ -412,6 +516,17 @@ def build_issuer_app(
                          gate_key_id=key_id, now=now())
         if not g["accepted"]:
             return refused(g["reason"])
+        if not _enrolled_speaks_for(who, grant["approver_key_id"]):
+            return refused(REF_ISSUER_NOT_AN_APPROVER)
+        if not allow_self_approval:
+            # Two people: the one asking and the one releasing. The approver
+            # key id (a UPN for an enrolled key) may be neither the hold's
+            # principal nor the party it acts for (second review, finding 8).
+            parties = {hold_owner(arid)}
+            if env is not None:
+                parties.add((env.get("request_context") or {}).get("on_behalf_of"))
+            if grant["approver_key_id"] in parties:
+                return refused(REF_ISSUER_SELF_APPROVAL)
         # The receipt's (or plan's) own terms: distinct approvers, from the named set if any.
         terms = approval_terms(env) if env else _plan_terms(plan)
         have = list(app.state.grants.get(arid, []))
@@ -483,6 +598,15 @@ def build_issuer_app(
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         if not isinstance(body, dict) or not valid_public_key_hex(body.get("public_key_hex")):
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        current = registry.public_hex().get(who["principal"])
+        if current is not None and current != body["public_key_hex"]:
+            # A bearer token alone must not swap the key holds are released
+            # with: a second browser's key enrolls only with the first key's
+            # signature over it (`supersede_signature`), or after the operator
+            # revoked the first (`gargoyle approvers revoke <upn>`).
+            if not _supersedes(current, body.get("supersede_signature"), body["public_key_hex"]):
+                event("enroll_refused", approver=who["principal"], reason=REF_ISSUER_KEY_ENROLLED, oid=who.get("oid"))
+                raise _refuse(409, REF_ISSUER_KEY_ENROLLED)
         try:
             result = registry.enroll(who["principal"], body["public_key_hex"], now=now(), oid=who.get("oid"), tid=who.get("tid"))
         except RevokedKeyError:
@@ -644,6 +768,7 @@ def app_from_env() -> FastAPI:
         on_hold=notifier_from_env(os.environ),
         hold_store=HoldStore(os.environ.get(ENV_HOLDS_PATH) or None),
         max_open_holds=int(os.environ.get(ENV_MAX_OPEN_HOLDS, DEFAULT_MAX_OPEN_HOLDS)),
+        allow_self_approval=os.environ.get(ENV_ALLOW_SELF_APPROVAL, "").strip().lower() in ("1", "true", "yes"),
         witness=(WitnessLog(os.environ["GARGOYLE_WITNESS_PATH"], Ed25519PrivateKey.from_private_bytes(bytes.fromhex(required[ENV_ISSUER_KEY_HEX])),
                             required[ENV_ISSUER_KEY_ID]) if os.environ.get("GARGOYLE_WITNESS_PATH") else None),
         log_events=(lambda e: sys.stderr.write(json.dumps(e, sort_keys=True) + "\n")) if os.environ.get("GARGOYLE_LOG_JSON") else None,
@@ -652,6 +777,7 @@ def app_from_env() -> FastAPI:
         approver_groups=[g.strip() for g in os.environ.get(ENV_APPROVER_GROUPS, "").split(",") if g.strip()] or None,
         tenant=tenant_id,
         tenant_key_ids=set(tenant_keys) if tenant else None,
+        idp_key_refresh=(lambda: entra_keys(tenant_id)) if tenant else None,
         console_entra=({"tenant": tenant, "client_id": os.environ[ENV_CONSOLE_CLIENT_ID],
                         "scope": os.environ.get(ENV_CONSOLE_SCOPE) or "api://%s/access" % (os.environ.get(ENV_AUDIENCE) or "").split(",")[-1].strip()}
                        if tenant and os.environ.get(ENV_CONSOLE_CLIENT_ID) else None),