gargoyle-receipts 0.16.0.dev0__tar.gz → 0.16.3.dev0__tar.gz

{gargoyle_receipts-0.16.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.16.3.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.0.dev0
+Version: 0.16.3.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.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.3.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
@@ -295,7 +295,13 @@ person. An approver retires a lost or replaced key with
 anyone with `gargoyle approvers revoke <upn>` on the issuer's host, and
 the running service picks the change up without a restart. Revoked keys
 stay on file so earlier grants still audit; new ones are refused at the
-issuer and at every middleware on its next held call. Approvers, and
+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
+(`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
 only approvers, see the whole queue and the witness; everyone else sees
 their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.
@@ -390,6 +396,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, with a `revoked` list; `gargoyle approvers list|revoke`) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
 | 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_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.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.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.3.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
@@ -257,7 +257,13 @@ person. An approver retires a lost or replaced key with
 anyone with `gargoyle approvers revoke <upn>` on the issuer's host, and
 the running service picks the change up without a restart. Revoked keys
 stay on file so earlier grants still audit; new ones are refused at the
-issuer and at every middleware on its next held call. Approvers, and
+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
+(`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
 only approvers, see the whole queue and the witness; everyone else sees
 their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.
@@ -352,6 +358,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, with a `revoked` list; `gargoyle approvers list|revoke`) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
 | 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_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |

gargoyle_receipts-0.16.3.dev0/gargoyle/__main__.py

@@ -0,0 +1,9 @@
+"""`python -m gargoyle` is the CLI: on a Windows Store Python the Scripts folder
+that holds gargoyle.exe is usually not on PATH."""
+
+import sys
+
+from gargoyle.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/approval.py

@@ -32,6 +32,21 @@ _SIGNATURE_EXCLUDED_KEYS = ("approver_signature",)
 
 # Refusal codes.
 REF_APPROVAL_MALFORMED = "REF_APPROVAL_MALFORMED"
+
+
+class _AnyOf:
+    """A verifying key made of several: the signature is valid if any verifies it."""
+    def __init__(self, keys: list) -> None:
+        self.keys = keys
+
+    def verify(self, signature: bytes, message: bytes) -> None:
+        for key in self.keys[:-1]:
+            try:
+                key.verify(signature, message)
+                return
+            except Exception:
+                continue
+        self.keys[-1].verify(signature, message)
 REF_APPROVAL_MISSING_GRANT_ID = "REF_APPROVAL_MISSING_GRANT_ID"
 REF_APPROVAL_SIGNATURE_INVALID = "REF_APPROVAL_SIGNATURE_INVALID"
 REF_APPROVAL_KEY_UNKNOWN = "REF_APPROVAL_KEY_UNKNOWN"
@@ -178,6 +193,10 @@ def verify_grant(
 
     # 4. known approver key
     public_key = approver_public_keys.get(key_id)
+    if isinstance(public_key, (list, tuple)):
+        # Several keys for one approver id: an audit of grants from before the
+        # approver's browser key was replaced or revoked. Any of them may verify.
+        public_key = _AnyOf(list(public_key)) if public_key else None
     if public_key is None:
         return _reject(REF_APPROVAL_KEY_UNKNOWN)
 

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/approvers.py

@@ -26,7 +26,7 @@ import stat
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import List, Any, Dict, Optional
 
 ENV_APPROVERS_PATH = "GARGOYLE_APPROVERS_PATH"
 ENV_APPROVER_ROLE = "GARGOYLE_APPROVER_ROLE"        # Entra app role an enrolling token must carry (default Approver)
@@ -35,6 +35,11 @@ ENV_APPROVER_GROUPS = "GARGOYLE_APPROVER_GROUPS"    # or: comma-separated group
 DEFAULT_APPROVER_ROLE = "Approver"
 
 
+class RevokedKeyError(ValueError):
+    """The public key offered for enrollment was revoked before: a revoked
+    key stays revoked, the browser must generate a new one."""
+
+
 def valid_public_key_hex(value: Any) -> bool:
     return isinstance(value, str) and len(value) == 64 and all(c in "0123456789abcdef" for c in value)
 
@@ -48,6 +53,7 @@ class ApproverRegistry:
         self._lock = threading.Lock()
         self._approvers: Dict[str, Dict[str, Any]] = {}
         self._revoked: Dict[str, Dict[str, Any]] = {}      # former approvers, kept so old grants still verify in audits
+        self._history: Dict[str, List[Dict[str, Any]]] = {}  # every key each UPN held and how it ended (replaced, revoked)
         self._mtime: Optional[float] = None
         self._load()
 
@@ -62,7 +68,16 @@ class ApproverRegistry:
         for upn, entry in (doc.get("revoked") or {}).items():
             if isinstance(entry, dict) and valid_public_key_hex(entry.get("public_key_hex")):
                 revoked[upn] = dict(entry)
-        self._approvers, self._revoked = approvers, revoked
+        history: Dict[str, List[Dict[str, Any]]] = {}
+        for upn, items in (doc.get("history") or {}).items():
+            if isinstance(items, list):
+                history[upn] = [dict(h) for h in items if isinstance(h, dict) and valid_public_key_hex(h.get("public_key_hex"))]
+        for upn, e in revoked.items():
+            # A file from before history existed: its revoked record is the one former key known.
+            if not any(h.get("public_key_hex") == e["public_key_hex"] for h in history.get(upn, [])):
+                history.setdefault(upn, []).append({**{k: v for k, v in e.items() if k not in ("revoked_at", "revoked_by")},
+                                                    "ended_at": e.get("revoked_at"), "ended_by": e.get("revoked_by"), "reason": "revoked"})
+        self._approvers, self._revoked, self._history = approvers, revoked, history
         self._mtime = self.path.stat().st_mtime
 
     def _refresh(self) -> None:
@@ -84,6 +99,8 @@ class ApproverRegistry:
         doc = {"approvers": self._approvers}
         if self._revoked:
             doc["revoked"] = self._revoked
+        if self._history:
+            doc["history"] = self._history
         self.path.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
         try:
             os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
@@ -97,7 +114,11 @@ class ApproverRegistry:
         UPN (one key per approver; a new browser re-enrolls). The directory's
         immutable object id and tenant id are kept beside the UPN when the
         token carried them: the UPN is the name people read, the oid is what
-        survives a rename."""
+        survives a rename. A key on the revoked list is never enrolled again,
+        for anyone (RevokedKeyError): the live exercise of 2026-10-20 showed a
+        browser re-enrolling the very key the operator had just revoked. The
+        revoked record stays when a fresh key enrolls, so grants signed under
+        the old key still audit."""
         if not isinstance(upn, str) or not upn:
             raise ValueError("upn must be a non-empty string")
         if not valid_public_key_hex(public_key_hex):
@@ -111,12 +132,45 @@ class ApproverRegistry:
             entry["tid"] = tid
         with self._lock:
             self._refresh()
+            if public_key_hex in self._revoked_keys():
+                raise RevokedKeyError("that key was revoked; enroll a new one")
             replaced = upn in self._approvers
+            if replaced and self._approvers[upn].get("public_key_hex") != public_key_hex:
+                # The superseded key is kept: grants signed under it still audit.
+                self._remember(upn, self._approvers[upn], "replaced", enrolled_by or upn, now)
             self._approvers[upn] = entry
-            self._revoked.pop(upn, None)            # enrolling again after a revocation is a fresh key
             self._save()
         return {"upn": upn, "replaced": replaced, **entry}
 
+    def _remember(self, upn: str, entry: Dict[str, Any], reason: str, ended_by: str, now: Optional[datetime]) -> None:
+        hist = self._history.setdefault(upn, [])
+        if not any(h.get("public_key_hex") == entry.get("public_key_hex") for h in hist):
+            hist.append({**{k: v for k, v in entry.items() if k not in ("revoked_at", "revoked_by")},
+                         "ended_at": (now or datetime.now(timezone.utc)).isoformat(), "ended_by": ended_by, "reason": reason})
+
+    def _revoked_keys(self) -> set:
+        """Every public key ever revoked, under any UPN: none may enroll again."""
+        return ({e.get("public_key_hex") for e in self._revoked.values()}
+                | {h.get("public_key_hex") for hist in self._history.values() for h in hist if h.get("reason") == "revoked"})
+
+    def audit_keys_hex(self) -> Dict[str, List[str]]:
+        """{upn: [public_key_hex, ...]}: the current key first, then every key
+        the UPN held before. An audit verifies a grant with any of them; the
+        live service and middleware trust only the current one."""
+        with self._lock:
+            self._refresh()
+            out: Dict[str, List[str]] = {}
+            for upn, e in self._approvers.items():
+                out[upn] = [e["public_key_hex"]]
+            for upn, hist in self._history.items():
+                for h in hist:
+                    if h["public_key_hex"] not in out.setdefault(upn, []):
+                        out[upn].append(h["public_key_hex"])
+            for upn, e in self._revoked.items():
+                if e["public_key_hex"] not in out.setdefault(upn, []):
+                    out[upn].append(e["public_key_hex"])
+            return out
+
     def revoke(self, upn: str, *, revoked_by: Optional[str] = None, now: Optional[datetime] = None) -> bool:
         """Stop trusting `upn`'s key from now on. The entry moves to the
         revoked list with when and by whom, so an audit of earlier evidence
@@ -129,6 +183,7 @@ class ApproverRegistry:
                 return False
             self._revoked[upn] = {**entry, "revoked_at": (now or datetime.now(timezone.utc)).isoformat(),
                                   "revoked_by": revoked_by or upn}
+            self._remember(upn, entry, "revoked", revoked_by or upn, now)
             self._save()
         return True
 
@@ -146,6 +201,13 @@ class ApproverRegistry:
             self._refresh()
             return {upn: e["public_key_hex"] for upn, e in self._approvers.items()}
 
+    def revoked_entries(self) -> Dict[str, Dict[str, Any]]:
+        """The revoked list with when and by whom, re-read from the file: the
+        service notices an operator's `gargoyle approvers revoke` here."""
+        with self._lock:
+            self._refresh()
+            return {upn: dict(e) for upn, e in self._revoked.items()}
+
     def revoked_hex(self) -> Dict[str, str]:
         """{upn: public_key_hex} of revoked approvers: for verifying the
         grants they signed while trusted, never for accepting new ones."""

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/cli.py

@@ -39,6 +39,7 @@ the response metadata; `gargoyle audit` verifies them later, offline.
 
 import argparse
 import json
+from typing import Any, Dict
 import os
 import re
 import stat
@@ -293,7 +294,7 @@ def cmd_remote(args) -> int:
 
 def cmd_issuer(args) -> int:
     import uvicorn
-    from gargoyle.issuer_service import app_from_env
+    from gargoyle.issuer_service import app_from_env, redact_access_log
 
     out = Path(args.out).resolve()
     os.environ.update(_read_env(out / "issuer.env"))
@@ -302,6 +303,7 @@ def cmd_issuer(args) -> int:
     os.environ.setdefault("GARGOYLE_WITNESS_PATH", str(out / "witness.jsonl"))       # the issuer's signed record, for reconciliation
     os.environ.setdefault("GARGOYLE_LOG_JSON", "1")
     app = app_from_env()
+    redact_access_log()                     # no sign-in codes in the access log
     # The middleware reads the policy pin from a file; write it next to the
     # config so the client-side entry finds it at the configured path.
     from gargoyle.rules import RulesPolicy
@@ -345,9 +347,10 @@ def cmd_approvers(args) -> int:
         for upn, e in sorted(entries.items()):
             print("%s  enrolled %s  key %s%s" % (upn, e.get("enrolled_at", "?"), e["public_key_hex"][:16],
                                                   ("  oid " + e["oid"]) if e.get("oid") else ""))
-        revoked = reg.revoked_hex()
+        revoked = reg.revoked_entries()
         if revoked:
-            print("revoked: " + ", ".join(sorted(revoked)))
+            print("revoked: " + ", ".join("%s (key %s, %s by %s)" % (u, e["public_key_hex"][:16], e.get("revoked_at", "?")[:19], e.get("revoked_by", "?"))
+                                          for u, e in sorted(revoked.items())))
         return 0
     import getpass
     if reg.revoke(args.upn, revoked_by="operator:" + getpass.getuser()):
@@ -362,15 +365,17 @@ def cmd_audit(args) -> int:
     from gargoyle.execution import verify_chain
 
     keys = json.loads((Path(args.out).resolve() / "public-keys.json").read_text())
-    load = lambda m: {k: Ed25519PublicKey.from_public_bytes(bytes.fromhex(v)) for k, v in m.items()}
-    approvers = dict(keys["approver"])
+    one = lambda h: Ed25519PublicKey.from_public_bytes(bytes.fromhex(h))
+    load = lambda m: {k: ([one(x) for x in v] if isinstance(v, list) else one(v)) for k, v in m.items()}
+    approvers: Dict[str, Any] = dict(keys["approver"])
     enrolled = Path(args.out).resolve() / "approvers.json"          # approvers who enrolled through Entra, by UPN
     if enrolled.exists():
-        doc = json.loads(enrolled.read_text())
-        # Revoked approvers too: the audit verifies what was signed while they
-        # were trusted. Only the live service and middleware refuse them.
-        approvers.update({u: e["public_key_hex"] for u, e in doc.get("revoked", {}).items()})
-        approvers.update({u: e["public_key_hex"] for u, e in doc.get("approvers", {}).items()})
+        from gargoyle.approvers import ApproverRegistry
+        # Every key each approver ever held, current first: grants signed
+        # under a key since replaced in the browser or revoked still have to
+        # verify. Only the live service and middleware are limited to the
+        # current key. Copy the issuer's file beside the evidence first.
+        approvers.update(ApproverRegistry(str(enrolled)).audit_keys_hex())
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
                  approver_public_keys=load(approvers))
     if args.log:

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/issuer_service.py

@@ -60,7 +60,7 @@ from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF
                             sign_plan, valid_step)
 from gargoyle.notify import notifier_from_env
 from gargoyle.approvers import (DEFAULT_APPROVER_ROLE, ENV_APPROVER_GROUPS, ENV_APPROVER_ROLE, ENV_APPROVERS_PATH,
-                                ApproverRegistry, may_enroll, valid_public_key_hex)
+                                ApproverRegistry, RevokedKeyError, may_enroll, valid_public_key_hex)
 from gargoyle.identity import entra_keys, entra_tenant_id, principal_from_token
 from gargoyle.issuer import DEFAULT_TTL_SECONDS, issue
 from gargoyle.policy import Policy
@@ -79,6 +79,8 @@ ENV_APPROVER_PUBLIC_KEY_HEX = "GARGOYLE_APPROVER_PUBLIC_KEY_HEX"
 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
+DEFAULT_MAX_OPEN_HOLDS = 20
 
 REF_ISSUER_UNAUTHENTICATED = "REF_ISSUER_UNAUTHENTICATED"
 REF_ISSUER_BAD_REQUEST = "REF_ISSUER_BAD_REQUEST"
@@ -87,6 +89,8 @@ REF_ISSUER_UNKNOWN_HOLD = "REF_ISSUER_UNKNOWN_HOLD"
 REF_ISSUER_NO_APPROVER_TRUST = "REF_ISSUER_NO_APPROVER_TRUST"
 REF_ISSUER_NOT_AN_APPROVER = "REF_ISSUER_NOT_AN_APPROVER"   # enrollment without the approver role or group
 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
 
 
 def build_issuer_app(
@@ -109,6 +113,7 @@ def build_issuer_app(
     witness: Optional[WitnessLog] = None,
     tenant: Optional[str] = None,
     tenant_key_ids: Optional[set] = None,
+    max_open_holds: int = DEFAULT_MAX_OPEN_HOLDS,
 ) -> 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
@@ -146,7 +151,20 @@ def build_issuer_app(
     registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
     static_approvers = dict(approver_public_keys or {})
 
+    app.state.revoked_seen = set(registry.revoked_entries())
+
+    def _notice_revocations() -> None:
+        """An operator's `gargoyle approvers revoke` edits the file on the
+        host; the first read after it puts a `revoked` entry in the witness,
+        so the record shows who was trusted when. Revocations the service
+        made itself were witnessed as they happened."""
+        current = registry.revoked_entries()
+        for upn in sorted(set(current) - app.state.revoked_seen):
+            event("revoked", approver=upn, by=current[upn].get("revoked_by"), revoked_at=current[upn].get("revoked_at"))
+        app.state.revoked_seen = set(current)
+
     def approver_keys() -> Dict[str, Any]:
+        _notice_revocations()
         """Static keys from configuration plus every enrolled approver, by UPN."""
         return {**static_approvers, **registry.keys()}
 
@@ -164,6 +182,21 @@ def build_issuer_app(
         plan = app.state.pending_plans.get(arid)
         return plan.get("principal") if plan is not None else None
 
+    def _open_holds(principal: str) -> int:
+        """Held receipts and plans of `principal` still waiting on a release:
+        not expired, not complete. A declined hold is already gone. One runaway
+        client must not fill every approver's queue and the hold store."""
+        current = now()
+        n = 0
+        for arid, env in app.state.pending.items():
+            if (env.get("request_context", {}).get("principal") == principal
+                    and datetime.fromisoformat(env["not_after"]) > current and not _complete(arid)):
+                n += 1
+        for arid, plan in app.state.pending_plans.items():
+            if plan.get("principal") == principal and datetime.fromisoformat(plan["not_after"]) > current and not _complete(arid):
+                n += 1
+        return n
+
     def _refuse(status: int, reason: str) -> HTTPException:
         return HTTPException(status_code=status, detail={"reason": reason})
 
@@ -228,6 +261,11 @@ def build_issuer_app(
                 if plan["plan_id"] == plan_id and _complete(arid_p) and match_step(plan, body["tool"], body["args"]) is not None:
                     covered = True
                     break
+        if result.envelope["requires_approval"] and not covered and _open_holds(who["principal"]) >= max_open_holds:
+            # A service limit, not a policy decision: nothing is stored, the
+            # signed envelope is dropped, the client reports the reason.
+            event("refused", principal=who["principal"], tool=body["tool"], reason=REF_ISSUER_TOO_MANY_HOLDS)
+            return {"issued": False, "reason": REF_ISSUER_TOO_MANY_HOLDS}
         event("issued", principal=who["principal"], tool=body["tool"], held=bool(result.envelope["requires_approval"]),
               **({"oid": who["oid"]} if who.get("oid") else {}),
               covered=covered, decision_id=result.envelope.get("decision_id"), decision_sha256=result.envelope["decision_sha256"],
@@ -287,6 +325,9 @@ def build_issuer_app(
                 if d.approvers:
                     approvers.update(d.approvers)
             norm.append(step)
+        if held and _open_holds(who["principal"]) >= max_open_holds:
+            event("refused", principal=who["principal"], tool="plan", reason=REF_ISSUER_TOO_MANY_HOLDS)
+            return {"issued": False, "reason": REF_ISSUER_TOO_MANY_HOLDS}
         import uuid
         approval = None
         if required > 1 or approvers:
@@ -357,21 +398,27 @@ def build_issuer_app(
         plan = app.state.pending_plans.get(arid) if isinstance(arid, str) else None
         if env is None and plan is None:
             return {"accepted": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
+        def refused(reason: str) -> Dict[str, Any]:
+            # A release that did not happen is a decision too: a revoked or
+            # unknown key trying to release a hold belongs in the witness.
+            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}
         trusted = approver_keys()
         if not trusted:
-            return {"accepted": False, "reason": REF_ISSUER_NO_APPROVER_TRUST}
+            return refused(REF_ISSUER_NO_APPROVER_TRUST)
         g = verify_grant(grant, expected_decision_sha256=env["decision_sha256"] if env else plan["plan_sha256"],
                          expected_approval_request_id=arid, approver_public_keys=trusted,
                          gate_key_id=key_id, now=now())
         if not g["accepted"]:
-            return {"accepted": False, "reason": g["reason"]}
+            return refused(g["reason"])
         # 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, []))
         if any(h["approver_key_id"] == grant["approver_key_id"] for h in have):
-            return {"accepted": False, "reason": REF_APPROVAL_DUPLICATE_APPROVER}
+            return refused(REF_APPROVAL_DUPLICATE_APPROVER)
         if terms["approvers"] is not None and grant["approver_key_id"] not in terms["approvers"]:
-            return {"accepted": False, "reason": REF_APPROVAL_APPROVER_NOT_ELIGIBLE}
+            return refused(REF_APPROVAL_APPROVER_NOT_ELIGIBLE)
         have.append(grant)
         app.state.grants[arid] = have                      # written back: the store persists on assignment
         event("granted", approval_request_id=arid, approver=grant["approver_key_id"], collected=len(have), required=terms["required"],
@@ -419,6 +466,7 @@ def build_issuer_app(
         """Public, like /record: the enrolled approvers' public keys by UPN,
         for the middleware and for audits. Static configured keys are not
         listed; they travel in config."""
+        _notice_revocations()
         return {"approvers": registry.public_hex()}
 
     @app.post("/approvers/enroll")
@@ -435,7 +483,13 @@ 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)
-        result = registry.enroll(who["principal"], body["public_key_hex"], now=now(), oid=who.get("oid"), tid=who.get("tid"))
+        try:
+            result = registry.enroll(who["principal"], body["public_key_hex"], now=now(), oid=who.get("oid"), tid=who.get("tid"))
+        except RevokedKeyError:
+            # A revoked key stays revoked, whoever offers it; the console
+            # generates a fresh one on this answer.
+            event("enroll_refused", approver=who["principal"], reason=REF_ISSUER_KEY_REVOKED, oid=who.get("oid"))
+            raise _refuse(409, REF_ISSUER_KEY_REVOKED)
         event("enrolled", approver=who["principal"], replaced=result["replaced"], oid=who.get("oid"))
         return {"enrolled": True, "key_id": who["principal"], "replaced": result["replaced"]}
 
@@ -459,6 +513,7 @@ def build_issuer_app(
         gone = registry.revoke(upn, revoked_by=who["principal"], now=now())
         if gone:
             event("revoked", approver=upn, by=who["principal"])
+            app.state.revoked_seen.add(upn)
         return {"revoked": gone}
 
     @app.get("/me")
@@ -468,6 +523,7 @@ def build_issuer_app(
         its own key is the one on record)."""
         who = authenticate(authorization)
         upn = who["principal"]
+        _notice_revocations()
         return {"principal": upn, "may_approve": may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers,
                 "enrolled_public_key_hex": registry.public_hex().get(upn)}
 
@@ -485,6 +541,7 @@ def build_issuer_app(
         how much is waiting, and since when. No secrets."""
         return {"ok": True, "policy": policy.pin(), "issuer_key_id": key_id,
                 "pending_receipts": len(app.state.pending), "pending_plans": len(app.state.pending_plans),
+                "max_open_holds": max_open_holds,
                 "enrolled_approvers": len(registry.public_hex()), "static_approvers": len(static_approvers),
                 "entra": bool(console_entra), "persistent": store.path != ":memory:", "started_at": app.state.started_at}
 
@@ -514,6 +571,22 @@ def build_issuer_app(
     return app
 
 
+def redact_access_log(logger_name: str = "uvicorn.access") -> None:
+    """The console returns from Microsoft as GET /approve?code=...; the code
+    is single-use and bound to the browser's PKCE verifier, and it still has
+    no place in an access log. Replace query strings on logged paths."""
+    import logging
+    import re
+
+    class _Redact(logging.Filter):
+        def filter(self, record: logging.LogRecord) -> bool:
+            if isinstance(record.args, tuple):
+                record.args = tuple(re.sub(r"\?.*", "?<redacted>", a) if isinstance(a, str) and a.startswith("/") and "?" in a else a
+                                    for a in record.args)
+            return True
+    logging.getLogger(logger_name).addFilter(_Redact())
+
+
 def app_from_env() -> FastAPI:
     """The deployable app: OPA policy, issuer key, trusted identity-provider
     key and optional approver key from the environment. Missing required
@@ -570,6 +643,7 @@ def app_from_env() -> FastAPI:
         ttl_seconds=int(os.environ.get(ENV_RECEIPT_TTL, DEFAULT_TTL_SECONDS)),
         on_hold=notifier_from_env(os.environ),
         hold_store=HoldStore(os.environ.get(ENV_HOLDS_PATH) or None),
+        max_open_holds=int(os.environ.get(ENV_MAX_OPEN_HOLDS, DEFAULT_MAX_OPEN_HOLDS)),
         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,

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle/static/approve.html

@@ -94,8 +94,18 @@ async function entraReady() {
   const mine = await publicKeyHex(keyPair);
   if (me.enrolled_public_key_hex !== mine) {
     // First time in this browser (or a new browser): enroll this key under the UPN.
-    const res = await api("approvers/enroll", { method: "POST", body: JSON.stringify({ public_key_hex: mine }) });
-    log(res.replaced ? "this browser's key replaced your previous one" : "this browser's key enrolled");
+    let res;
+    try {
+      res = await api("approvers/enroll", { method: "POST", body: JSON.stringify({ public_key_hex: mine }) });
+    } catch (err) {
+      if (err.status !== 409) throw err;
+      // This browser's key was revoked. A revoked key stays revoked: make a new one and enroll that.
+      keyPair = await generateApproverKey(); await storeKey(me.principal, keyPair);
+      res = await api("approvers/enroll", { method: "POST", body: JSON.stringify({ public_key_hex: await publicKeyHex(keyPair) }) });
+      log("this browser's previous key was revoked; a new key enrolled");
+      res = null;
+    }
+    if (res) log(res.replaced ? "this browser's key replaced your previous one" : "this browser's key enrolled");
   }
   state.key = keyPair.privateKey; state.keyId = me.principal;
   $("entra").style.display = "none"; $("setup").style.display = "none";
@@ -117,7 +127,7 @@ $("file").addEventListener("change", async (e) => {
 
 async function api(path, opts = {}) {
   const r = await fetch(path, { ...opts, headers: { "Authorization": "Bearer " + state.token, "content-type": "application/json", ...(opts.headers || {}) } });
-  if (!r.ok) throw new Error(path + " -> " + r.status);
+  if (!r.ok) { const e = new Error(path + " -> " + r.status); e.status = r.status; throw e; }
   return r.json();
 }
 

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.0.dev0
+Version: 0.16.3.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.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.3.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
@@ -295,7 +295,13 @@ person. An approver retires a lost or replaced key with
 anyone with `gargoyle approvers revoke <upn>` on the issuer's host, and
 the running service picks the change up without a restart. Revoked keys
 stay on file so earlier grants still audit; new ones are refused at the
-issuer and at every middleware on its next held call. Approvers, and
+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
+(`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
 only approvers, see the whole queue and the witness; everyone else sees
 their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.
@@ -390,6 +396,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, with a `revoked` list; `gargoyle approvers list|revoke`) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
 | 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_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ NOTICE
 README.md
 pyproject.toml
 gargoyle/__init__.py
+gargoyle/__main__.py
 gargoyle/adapters.py
 gargoyle/approval.py
 gargoyle/approver_cli.py

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.16.0.dev0"
+version = "0.16.3.dev0"
 description = "Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls."
 readme = "README.md"
 requires-python = ">=3.12"

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/tests/test_approvers.py

@@ -151,10 +151,17 @@ def test_a_revoked_approver_is_refused_at_once_and_still_verifies_in_the_past(tm
     doc = json.loads((tmp_path / "approvers.json").read_text())
     assert "dana@contoso.com" not in doc["approvers"] and doc["revoked"]["dana@contoso.com"]["public_key_hex"] == pub_hex(dana)
     assert doc["revoked"]["dana@contoso.com"]["revoked_by"] == "dana@contoso.com"
-    # Enrolling again is a fresh key, and the revoked record goes.
+    # The revoked key is never enrolled again, by Dana or anyone (a browser
+    # that kept its key pair would otherwise re-enroll it on the next sign-in).
+    from gargoyle.issuer_service import REF_ISSUER_KEY_REVOKED
+    r = c.post("/approvers/enroll", json={"public_key_hex": pub_hex(dana)}, headers=h(token("dana@contoso.com", roles=["Approver"])))
+    assert r.status_code == 409 and r.json()["detail"]["reason"] == REF_ISSUER_KEY_REVOKED
+    r = c.post("/approvers/enroll", json={"public_key_hex": pub_hex(dana)}, headers=h(token("lee@contoso.com", roles=["Approver"])))
+    assert r.status_code == 409
+    # A fresh key enrolls, and the revoked record stays so Dana's earlier grants still audit.
     dana2 = Ed25519PrivateKey.generate()
     assert c.post("/approvers/enroll", json={"public_key_hex": pub_hex(dana2)}, headers=h(token("dana@contoso.com", roles=["Approver"]))).json()["enrolled"]
-    assert reg.revoked_hex() == {} and reg.public_hex() == {"dana@contoso.com": pub_hex(dana2)}
+    assert reg.revoked_hex() == {"dana@contoso.com": pub_hex(dana)} and reg.public_hex() == {"dana@contoso.com": pub_hex(dana2)}
 
 
 def test_the_registry_picks_up_a_file_another_process_wrote(tmp_path):
@@ -169,3 +176,67 @@ def test_the_registry_picks_up_a_file_another_process_wrote(tmp_path):
     assert operator.revoke("dana@contoso.com", revoked_by="operator:root")
     os.utime(path, (time.time() + 2, time.time() + 2))     # make the change visible even on a coarse filesystem clock
     assert "dana@contoso.com" not in live and live.public_hex() == {} and live.revoked_hex() == {"dana@contoso.com": pub_hex(key)}
+
+
+def test_an_operators_revocation_on_the_host_reaches_the_witness(tmp_path):
+    """`gargoyle approvers revoke` edits the file; the service witnesses the
+    revocation (who, when) the first time it reads the file afterwards, and
+    only once. Its own revocations are witnessed as they happen, not again."""
+    import os
+    events = []
+    reg = ApproverRegistry(str(tmp_path / "approvers.json"))
+    app = build_issuer_app(policy=Hold(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()},
+                           approver_registry=reg, log_events=events.append)
+    c = TestClient(app)
+    h = lambda t: {"Authorization": "Bearer " + t}
+    for who in ("dana@contoso.com", "lee@contoso.com"):
+        assert c.post("/approvers/enroll", json={"public_key_hex": pub_hex(Ed25519PrivateKey.generate())}, headers=h(token(who, roles=["Approver"]))).json()["enrolled"]
+    # The operator, in another process.
+    other = ApproverRegistry(str(tmp_path / "approvers.json"))
+    assert other.revoke("dana@contoso.com", revoked_by="operator:root")
+    st = os.stat(tmp_path / "approvers.json"); os.utime(tmp_path / "approvers.json", (st.st_atime, st.st_mtime + 2))
+    assert c.get("/approvers").json()["approvers"].keys() == {"lee@contoso.com"}
+    c.get("/approvers")
+    revoked = [e for e in events if e["event"] == "revoked"]
+    assert len(revoked) == 1 and revoked[0]["approver"] == "dana@contoso.com" and revoked[0]["by"] == "operator:root" and revoked[0]["revoked_at"]
+    # Lee revokes their own key through the service: one entry, by Lee.
+    assert c.post("/approvers/revoke", json={"upn": "lee@contoso.com"}, headers=h(token("lee@contoso.com", roles=["Approver"]))).json() == {"revoked": True}
+    c.get("/approvers")
+    revoked = [e for e in events if e["event"] == "revoked"]
+    assert [(e["approver"], e["by"]) for e in revoked] == [("dana@contoso.com", "operator:root"), ("lee@contoso.com", "lee@contoso.com")]
+
+
+def test_every_key_an_approver_held_stays_for_audits(tmp_path):
+    """The client audit of 2026-10-20 failed a row released under a key that a
+    later browser enrollment had replaced: the registry had dropped it. Now
+    every key a UPN held is kept (history: replaced or revoked, when, by whom),
+    the audit map carries them all, and a grant verifies with any of them."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    from gargoyle.approval import ACCEPT_GRANT_VALID, build_grant, sign_grant, verify_grant
+    from gargoyle.approvers import RevokedKeyError
+    path = tmp_path / "a.json"
+    reg = ApproverRegistry(str(path))
+    k1, k2, k3 = (Ed25519PrivateKey.generate() for _ in range(3))
+    reg.enroll("dana@contoso.com", pub_hex(k1))
+    assert reg.enroll("dana@contoso.com", pub_hex(k2))["replaced"] is True            # a new browser
+    assert reg.revoke("dana@contoso.com", revoked_by="operator:root")
+    reg.enroll("dana@contoso.com", pub_hex(k3))
+    assert reg.audit_keys_hex() == {"dana@contoso.com": [pub_hex(k3), pub_hex(k1), pub_hex(k2)]}
+    doc = json.loads(path.read_text())
+    assert [(h["reason"], h["ended_by"]) for h in doc["history"]["dana@contoso.com"]] == [("replaced", "dana@contoso.com"), ("revoked", "operator:root")]
+    now = datetime.now(timezone.utc)
+    keys = {u: [Ed25519PublicKey.from_public_bytes(bytes.fromhex(x)) for x in hs] for u, hs in reg.audit_keys_hex().items()}
+    for k in (k1, k2, k3):
+        g = sign_grant(build_grant(decision_sha256="a" * 64, approval_request_id="r", grant_id="g", not_after=now + timedelta(minutes=5)), k, "dana@contoso.com")
+        v = verify_grant(g, expected_decision_sha256="a" * 64, expected_approval_request_id="r", approver_public_keys=keys, gate_key_id="issuer-1", now=now)
+        assert v["accepted"] is True and v["reason"] == ACCEPT_GRANT_VALID
+    stranger = sign_grant(build_grant(decision_sha256="a" * 64, approval_request_id="r", grant_id="g", not_after=now + timedelta(minutes=5)),
+                          Ed25519PrivateKey.generate(), "dana@contoso.com")
+    assert verify_grant(stranger, expected_decision_sha256="a" * 64, expected_approval_request_id="r", approver_public_keys=keys, gate_key_id="issuer-1", now=now)["accepted"] is False
+    # The revoked key k2 is refused for anyone, from history, even after Dana's revoked record is gone.
+    with pytest.raises(RevokedKeyError):
+        reg.enroll("lee@contoso.com", pub_hex(k2))
+    # A file from before history existed: its revoked record seeds the history.
+    old = tmp_path / "old.json"
+    old.write_text(json.dumps({"approvers": {}, "revoked": {"x@contoso.com": {"public_key_hex": pub_hex(k1), "revoked_at": "t", "revoked_by": "b"}}}))
+    assert ApproverRegistry(str(old)).audit_keys_hex() == {"x@contoso.com": [pub_hex(k1)]}

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/tests/test_cli.py

@@ -136,3 +136,10 @@ def test_approvers_list_and_revoke_on_the_issuer_host(tmp_path, capsys):
     assert doc["approvers"] == {} and doc["revoked"]["dana@contoso.com"]["revoked_by"].startswith("operator:")
     assert main(["approvers", "list", "--out", str(out)]) == 0
     assert "revoked: dana@contoso.com" in capsys.readouterr().out
+
+
+def test_the_package_runs_as_a_module():
+    """`python -m gargoyle --help` works where gargoyle.exe is not on PATH."""
+    import subprocess, sys
+    r = subprocess.run([sys.executable, "-m", "gargoyle", "--help"], capture_output=True, text=True, timeout=60)
+    assert r.returncode == 0 and "audit" in r.stdout

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.3.dev0}/tests/test_issuer_service.py

@@ -9,7 +9,8 @@ from fastapi.testclient import TestClient
 from gargoyle.approval import REF_APPROVAL_SOD, build_grant, sign_grant
 from gargoyle.consumer import Consumer
 from gargoyle.issuer_service import (
-    REF_ISSUER_BAD_REQUEST, REF_ISSUER_NO_APPROVER_TRUST, REF_ISSUER_UNAUTHENTICATED, REF_ISSUER_UNKNOWN_HOLD,
+    REF_ISSUER_BAD_REQUEST, REF_ISSUER_NO_APPROVER_TRUST, REF_ISSUER_TOO_MANY_HOLDS, REF_ISSUER_UNAUTHENTICATED,
+    REF_ISSUER_UNKNOWN_HOLD,
     build_issuer_app,
 )
 from gargoyle.jws import REF_JWS_EXPIRED, encode
@@ -227,3 +228,68 @@ def test_the_approver_role_in_an_identity_token_also_sees_every_hold():
     c.post("/issue", json={"target_url": TARGET, "tool": "write_file", "args": {"path": "x"}}, headers=auth(token(sub="carol@contoso.com", aud="gargoyle-issuer")))
     assert c.get("/pending", headers=auth(token(sub="dana@contoso.com", aud="gargoyle-issuer", roles=["Approver"]))).json()["pending"][0]["args"] == {"path": "x"}
     assert c.get("/pending", headers=auth(token(sub="erin@contoso.com", aud="gargoyle-issuer", roles=["Reader"]))).json()["pending"] == []
+
+
+def test_open_holds_per_principal_are_capped():
+    """One runaway client cannot fill the approvers' queue: the cap counts a
+    principal's held receipts and plans that are neither expired nor released;
+    reads, other principals, declines and expiry are unaffected or free a slot."""
+    clock = {"now": NOW}
+    app = build_issuer_app(policy=ToolPolicy(), signing_key=issuer, key_id="issuer-1",
+                           idp_public_keys={"idp-1": idp.public_key()},
+                           approver_public_keys={"approver-alice": approver.public_key()},
+                           audience="gargoyle-issuer", now=lambda: clock["now"], max_open_holds=2)
+    c = TestClient(app)
+
+    def write(i, tok=None):
+        return c.post("/issue", json={"target_url": TARGET, "tool": "write_file", "args": {"path": "%d.txt" % i, "content": "x"}},
+                      headers=auth(tok)).json()
+
+    assert write(1)["issued"] is True and write(2)["issued"] is True
+    assert write(3) == {"issued": False, "reason": REF_ISSUER_TOO_MANY_HOLDS}
+    assert c.get("/health").json()["pending_receipts"] == 2                     # the refused call stored nothing
+    assert c.post("/issue", json={"target_url": TARGET, "tool": "read_file", "args": {"path": "a"}}, headers=auth()).json()["issued"] is True
+    assert write(4, token(sub="spiffe://example.org/agents/other", aud="gargoyle-issuer"))["issued"] is True
+    plan = c.post("/plans", json={"target_url": TARGET, "steps": [{"tool": "write_file", "args": {"path": "p.txt", "content": "y"}}], "note": "n"},
+                  headers=auth()).json()
+    assert plan == {"issued": False, "reason": REF_ISSUER_TOO_MANY_HOLDS}
+    mine = [h for h in c.get("/pending", headers=auth()).json()["pending"]]
+    assert len(mine) == 2                                                        # the requester sees only their own
+    arid = mine[0]["envelope"]["approval_request_id"]
+    assert c.post("/decline", json={"approval_request_id": arid}, headers=auth()).json()["declined"] is True
+    assert write(5)["issued"] is True                                            # the decline freed a slot
+    assert write(6)["issued"] is False
+    clock["now"] = NOW + timedelta(minutes=10)                                   # expiry frees the rest
+    assert write(7, token(exp=NOW + timedelta(minutes=20), aud="gargoyle-issuer"))["issued"] is True
+    assert c.get("/health").json()["max_open_holds"] == 2
+
+
+def test_a_refused_release_is_an_event_and_sign_in_codes_leave_the_access_log():
+    """A grant under an unknown or revoked key is refused and the refusal is
+    recorded (log and witness) with the key id and the reason; the live
+    revocation exercise of 2026-10-20 found it left no trace. And the Entra
+    redirect's one-time code is cut from uvicorn's access log."""
+    import logging
+    from gargoyle.approval import REF_APPROVAL_KEY_UNKNOWN
+    from gargoyle.issuer_service import redact_access_log
+    events = []
+    app = build_issuer_app(policy=ToolPolicy(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()},
+                           approver_public_keys={"approver-alice": approver.public_key()}, audience="gargoyle-issuer",
+                           log_events=events.append, now=lambda: NOW)
+    c = TestClient(app)
+    env = c.post("/issue", json={"target_url": TARGET, "tool": "write_file", "args": {"path": "a.txt", "content": "x"}}, headers=auth()).json()["envelope"]
+    arid = env["approval_request_id"]
+    g = sign_grant(build_grant(decision_sha256=env["decision_sha256"], approval_request_id=arid, grant_id="g-9", not_after=NOW + timedelta(minutes=5)),
+                   Ed25519PrivateKey.generate(), "mallory@example.org")
+    assert c.post("/grants", json=g, headers=auth()).json() == {"accepted": False, "reason": REF_APPROVAL_KEY_UNKNOWN}
+    refused = [e for e in events if e["event"] == "grant_refused"]
+    assert refused == [{"event": "grant_refused", "at": NOW.isoformat(), "approval_request_id": arid,
+                        "approver": "mallory@example.org", "reason": REF_APPROVAL_KEY_UNKNOWN}]
+    assert c.get("/pending", headers=auth()).json()["pending"][0]["envelope"]["approval_request_id"] == arid   # the hold stands
+
+    redact_access_log("test.access")
+    rec = logging.LogRecord("test.access", logging.INFO, "", 0, '%s - "%s %s HTTP/%s" %d',
+                            ("1.2.3.4:1", "GET", "/approve?code=SECRET&state=s", "1.1", 200), None)
+    for f in logging.getLogger("test.access").filters:
+        f.filter(rec)
+    assert rec.args[2] == "/approve?<redacted>" and rec.args[1] == "GET"