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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.0.dev0
+Version: 0.16.2.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.2.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,10 @@ 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. 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 +393,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.2.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.2.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,10 @@ 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. 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 +355,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.2.dev0}/gargoyle/approvers.py

@@ -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)
 
@@ -97,7 +102,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,9 +120,10 @@ class ApproverRegistry:
             entry["tid"] = tid
         with self._lock:
             self._refresh()
+            if any(e.get("public_key_hex") == public_key_hex for e in self._revoked.values()):
+                raise RevokedKeyError("that key was revoked; enroll a new one")
             replaced = upn in self._approvers
             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}
 
@@ -146,6 +156,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.2.dev0}/gargoyle/cli.py

@@ -293,7 +293,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 +302,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 +346,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()):

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.2.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.2.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.2.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.2.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.2.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,10 @@ 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. 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 +393,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.2.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.16.0.dev0"
+version = "0.16.2.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.2.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,31 @@ 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")]

{gargoyle_receipts-0.16.0.dev0 → gargoyle_receipts-0.16.2.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"