gargoyle-receipts 0.20.0.dev0__tar.gz → 0.22.0.dev0__tar.gz

{gargoyle_receipts-0.20.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.22.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.20.0.dev0
+Version: 0.22.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -64,7 +64,7 @@ by whom, and what changed.
 
 ## Status
 
-Pre-release `0.20.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
+Pre-release `0.22.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
 `gargoyle/3`, evidence log `gargoyle-evidence/4`, witness
 `gargoyle-witness/1`; all three are specified in [SPEC.md](SPEC.md) and may
 still change before a first release.
@@ -91,7 +91,7 @@ against a fake Graph server); the OAuth broker for hosted connectors
 (deployed, metadata and redirect checks verified, no human sign-in through a
 connector yet).
 
-**Assurance.** 561 Python tests on Linux and Windows across Python 3.12,
+**Assurance.** 565 Python tests on Linux and Windows across Python 3.12,
 3.13 and 3.14, at dependency floors and at a lock file; a TypeScript suite
 that recomputes the conformance vectors byte for byte; two outside,
 model-driven security reviews on 2026-10-20 (ten findings, all fixed); the
@@ -378,6 +378,13 @@ enrollment, revocation and discovery report, on the operator's server.
     gargoyle audit --log audit.jsonl --witness witness.jsonl           # reconcile by decision id: unwitnessed receipts, releases without a grant, missing evidence
     gargoyle audit --log audit.jsonl --check-tree /srv/shared          # hash the gated folder against the recorded states; name files changed around the gate
     gargoyle audit --log audit.jsonl --summary                         # calls by principal and tool, side-door findings
+    gargoyle audit --log audit.jsonl --issuer https://gargoyle.lan      # take the issuer's keys and every approver key it has seen from the issuer, not from a copied file
+
+The audit needs the public keys (`public-keys.json`, by default beside the
+log or in `--out`). Grants verify against every key an approver has held,
+so an approver who re-enrolled a browser key is still audited; with
+`--issuer` that list comes from the issuer itself and a stale copy of
+`approvers.json` can no longer fail a valid grant.
 
 On a machine the user administers the gate constrains the assistant, not
 the user; these checks make the difference visible. SPEC.md section 15
@@ -661,7 +668,8 @@ receipts work unchanged. Configuration is by environment:
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`, or `gargoyle issuer`): identity token in, receipt out,
 with the hold and grant exchange for flagged calls (`/issue`, `/pending`,
-`/grants`, `/decline`, `/record`, `/keys`, `/sidedoors`) and the browser
+`/grants`, `/decline`, `/record`, `/keys`, `/approvers`, `/approvers/audit`,
+`/sidedoors`) and the browser
 approval console at `/approve`. Policy from a rules file or OPA; identity
 from a pinned key or, with `GARGOYLE_ENTRA_TENANT`, the tenant's signing
 keys (both at once when a pinned key is also set).
@@ -674,6 +682,8 @@ keys (both at once when a pinned key is also set).
 | `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys, with a `revoked` list, re-read when its content changes) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
 | `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 `persistent` |
 | `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 |
+| `GARGOYLE_DECLINE_LIMIT`, `GARGOYLE_DECLINE_WINDOW_HOURS` | the decline cooldown: after this many declines of the same (principal, tool, path) within the window (defaults 2 and 24), the issuer refuses the next ask with `REF_ISSUER_DECLINED_RECENTLY` instead of holding it again, so an approver is not asked the same question a third time in a day; `0` disables |
+| `GARGOYLE_RECEIPT_TTL_SECONDS` | how long an issued receipt stays presentable (default 300); a held receipt's hold lives up to six times that, capped at an hour |
 | `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys) |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | 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.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/README.md

@@ -26,7 +26,7 @@ by whom, and what changed.
 
 ## Status
 
-Pre-release `0.20.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
+Pre-release `0.22.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
 `gargoyle/3`, evidence log `gargoyle-evidence/4`, witness
 `gargoyle-witness/1`; all three are specified in [SPEC.md](SPEC.md) and may
 still change before a first release.
@@ -53,7 +53,7 @@ against a fake Graph server); the OAuth broker for hosted connectors
 (deployed, metadata and redirect checks verified, no human sign-in through a
 connector yet).
 
-**Assurance.** 561 Python tests on Linux and Windows across Python 3.12,
+**Assurance.** 565 Python tests on Linux and Windows across Python 3.12,
 3.13 and 3.14, at dependency floors and at a lock file; a TypeScript suite
 that recomputes the conformance vectors byte for byte; two outside,
 model-driven security reviews on 2026-10-20 (ten findings, all fixed); the
@@ -340,6 +340,13 @@ enrollment, revocation and discovery report, on the operator's server.
     gargoyle audit --log audit.jsonl --witness witness.jsonl           # reconcile by decision id: unwitnessed receipts, releases without a grant, missing evidence
     gargoyle audit --log audit.jsonl --check-tree /srv/shared          # hash the gated folder against the recorded states; name files changed around the gate
     gargoyle audit --log audit.jsonl --summary                         # calls by principal and tool, side-door findings
+    gargoyle audit --log audit.jsonl --issuer https://gargoyle.lan      # take the issuer's keys and every approver key it has seen from the issuer, not from a copied file
+
+The audit needs the public keys (`public-keys.json`, by default beside the
+log or in `--out`). Grants verify against every key an approver has held,
+so an approver who re-enrolled a browser key is still audited; with
+`--issuer` that list comes from the issuer itself and a stale copy of
+`approvers.json` can no longer fail a valid grant.
 
 On a machine the user administers the gate constrains the assistant, not
 the user; these checks make the difference visible. SPEC.md section 15
@@ -623,7 +630,8 @@ receipts work unchanged. Configuration is by environment:
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`, or `gargoyle issuer`): identity token in, receipt out,
 with the hold and grant exchange for flagged calls (`/issue`, `/pending`,
-`/grants`, `/decline`, `/record`, `/keys`, `/sidedoors`) and the browser
+`/grants`, `/decline`, `/record`, `/keys`, `/approvers`, `/approvers/audit`,
+`/sidedoors`) and the browser
 approval console at `/approve`. Policy from a rules file or OPA; identity
 from a pinned key or, with `GARGOYLE_ENTRA_TENANT`, the tenant's signing
 keys (both at once when a pinned key is also set).
@@ -636,6 +644,8 @@ keys (both at once when a pinned key is also set).
 | `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys, with a `revoked` list, re-read when its content changes) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
 | `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 `persistent` |
 | `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 |
+| `GARGOYLE_DECLINE_LIMIT`, `GARGOYLE_DECLINE_WINDOW_HOURS` | the decline cooldown: after this many declines of the same (principal, tool, path) within the window (defaults 2 and 24), the issuer refuses the next ask with `REF_ISSUER_DECLINED_RECENTLY` instead of holding it again, so an approver is not asked the same question a third time in a day; `0` disables |
+| `GARGOYLE_RECEIPT_TTL_SECONDS` | how long an issued receipt stays presentable (default 300); a held receipt's hold lives up to six times that, capped at an hour |
 | `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys) |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | 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.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/claude_hook.py

@@ -116,6 +116,14 @@ class PendingReceipts:
     def __init__(self, path: str) -> None:
         self.path = Path(path)
 
+    def _locked(self):
+        """Pre- and PostToolUse hooks of parallel tool calls run as separate
+        processes at once; each read-modify-write holds the lock, or one
+        loses the other's entry (a call that ran with no evidence row, or an
+        honored one resurrected and reaped as never run)."""
+        from gargoyle.evidence import locked
+        return locked(self.path.with_name(self.path.name + ".lock"))
+
     def _read(self) -> Dict[str, Any]:
         try:
             doc = json.loads(self.path.read_text(encoding="utf-8"))
@@ -129,26 +137,29 @@ class PendingReceipts:
         os.replace(tmp, self.path)
 
     def put(self, tool_use_id: str, gate: Dict[str, Any], params: Dict[str, Any], now: float) -> None:
-        doc = self._read()
-        doc[tool_use_id] = {"envelope": gate["envelope"], "grant": gate["grant"], "self_issued": gate["self_issued"],
-                            "reason": gate["reason"], "ref": gate.get("ref"), "params": params, "at": now}
-        for old in list(doc)[:-PENDING_LIMIT]:
-            doc.pop(old, None)
-        self._write(doc)
+        with self._locked():
+            doc = self._read()
+            doc[tool_use_id] = {"envelope": gate["envelope"], "grant": gate["grant"], "self_issued": gate["self_issued"],
+                                "reason": gate["reason"], "ref": gate.get("ref"), "params": params, "at": now}
+            for old in list(doc)[:-PENDING_LIMIT]:
+                doc.pop(old, None)
+            self._write(doc)
 
     def pop(self, tool_use_id: str) -> Optional[Dict[str, Any]]:
-        doc = self._read()
-        gate = doc.pop(tool_use_id, None)
-        if gate is not None:
-            self._write(doc)
+        with self._locked():
+            doc = self._read()
+            gate = doc.pop(tool_use_id, None)
+            if gate is not None:
+                self._write(doc)
         return gate
 
     def reap(self, now: float, max_age: float) -> List[Dict[str, Any]]:
-        doc = self._read()
-        stale = [k for k, v in doc.items() if not isinstance(v.get("at"), (int, float)) or now - v["at"] > max_age]
-        out = [doc.pop(k) for k in stale]
-        if out:
-            self._write(doc)
+        with self._locked():
+            doc = self._read()
+            stale = [k for k, v in doc.items() if not isinstance(v.get("at"), (int, float)) or now - v["at"] > max_age]
+            out = [doc.pop(k) for k in stale]
+            if out:
+                self._write(doc)
         return out
 
 
@@ -256,6 +267,10 @@ def decide(event: Dict[str, Any], state: Any, *, final: bool = False, now: Optio
         gate = pending.pop(tool_use_id) if (pending is not None and tool_use_id) else None
         if gate is None:
             return {}
+        # The receipt bound the arguments PreToolUse saw; Claude Code may
+        # present some tools' input differently afterwards, so the entry is
+        # written over what was gated, not what PostToolUse carries.
+        params = gate["params"]
         outputs = event.get("tool_response") if kind == POST else {"error": event.get("error")}
         execution = _attest(state, gate["envelope"], outputs, params)
         _record(state, HONORED, gate, params, execution)

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/cli.py

@@ -635,9 +635,11 @@ def _audit_summary(report, raw) -> None:
             releases[who] += 1
         clients[r.get("client") or "(client unnamed)"] += 1
     print("summary: %d call(s)%s" % (len(report), (", %s to %s" % (min(ats)[:19], max(ats)[:19])) if ats else ""))
-    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "failed", "refused"))
+    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "errored", "refused"))
     for (principal, tool), c in sorted(counts.items(), key=lambda kv: (kv[0][0], -sum(kv[1].values()), kv[0][1])):
         print("  %-28s %-24s %7d %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("failed", 0), c.get("refused", 0)))
+    if any(c.get("failed") for c in counts.values()):
+        print("  errored: admitted by the gate, then the upstream reported an error (a missing file, a bad argument); not a verification failure")
     if releases:
         print("  releases: " + ", ".join("%s %d" % (w, n) for w, n in releases.most_common()))
     print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))
@@ -786,11 +788,60 @@ def cmd_restore(args) -> int:
     return 0 if (r.get("restored") or (args.verify_only and not r.get("refused"))) else 1
 
 
+def _issuer_trust(url: str) -> "tuple[Dict[str, str], Dict[str, list]]":
+    """The issuer's current signing keys (GET /keys) and every key each
+    enrolled approver has held (GET /approvers/audit), so an audit on a
+    workstation needs no copy of approvers.json that can go stale. Both are
+    public endpoints. REQUESTS_CA_BUNDLE names the issuer's CA as usual."""
+    import requests
+    base = url.rstrip("/")
+    keys = requests.get(base + "/keys", timeout=10); keys.raise_for_status()
+    appr = requests.get(base + "/approvers/audit", timeout=10); appr.raise_for_status()
+    return dict(keys.json()), dict(appr.json().get("approvers", {}))
+
+
+def _audit_trust_dir(args) -> "Path | None":
+    """Where public-keys.json is: --out, else the evidence log's own folder
+    (on a workstation the keys sit beside audit.jsonl). None when neither."""
+    out = Path(args.out).resolve()
+    if (out / "public-keys.json").exists():
+        return out
+    if getattr(args, "log", None):
+        beside = Path(args.log).resolve().parent
+        if (beside / "public-keys.json").exists():
+            return beside
+    return None
+
+
 def cmd_audit(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
     from gargoyle.execution import verify_chain
 
-    keys, approvers = _trust_hex(Path(args.out).resolve())
+    # A missing log is a usage error with the path named, not a traceback: a
+    # client whose evidence log was rotated or has not been written yet.
+    if getattr(args, "log", None) and not Path(args.log).is_file():
+        print("evidence log not found: %s (nothing recorded there yet, or the log was rotated under another name)"
+              % Path(args.log).resolve(), file=sys.stderr)
+        return 2
+    out = _audit_trust_dir(args)
+    if out is None:
+        print("public-keys.json not found in %s%s: pass --out DIR, the folder that holds public-keys.json (and approvers.json), "
+              "on a workstation the one with middleware.env" % (Path(args.out).resolve(),
+              (" or beside %s" % Path(args.log).resolve().parent) if getattr(args, "log", None) else ""), file=sys.stderr)
+        return 2
+    keys, approvers = _trust_hex(out)
+    if getattr(args, "issuer", None):
+        try:
+            issuer_keys, issuer_approvers = _issuer_trust(args.issuer)
+        except Exception as exc:
+            print("issuer not reachable for keys: %s (%s)" % (args.issuer, exc), file=sys.stderr)
+            return 2
+        keys["issuer"] = dict(keys.get("issuer", {}), **issuer_keys)
+        # The issuer's list is current and complete; a local copy may be older.
+        for upn, hexes in issuer_approvers.items():
+            have = approvers.get(upn)
+            have = have if isinstance(have, list) else ([have] if have else [])
+            approvers[upn] = list(hexes) + [h for h in have if h not in hexes]
     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()}
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
@@ -821,6 +872,17 @@ def cmd_audit(args) -> int:
         failed = sum(1 for r in v["entries"] if not r["accepted"])
         print("%d entries (%d honored, %d refused), %d failed; chain %s; tail %s"
               % (v["count"], v["honored"], v["refused"], failed, v["reason"], v["tail_sha256"][:16]))
+        from gargoyle.approval import REF_APPROVAL_KEY_UNKNOWN, REF_APPROVAL_SIGNATURE_INVALID
+        bad_sigs = [r for r in v["entries"] if not r["accepted"] and r["reason"] in (REF_APPROVAL_SIGNATURE_INVALID, REF_APPROVAL_KEY_UNKNOWN)]
+        if bad_sigs:
+            ids = sorted({k for r in bad_sigs for k in (r.get("released_by") or [])})
+            unknown = [k for k in ids if k not in approvers]
+            stale = [k for k in ids if k in approvers]
+            print("  note: %d release(s) failed the grant check%s%s. The approver keys here come from %s; an approver who "
+                  "re-enrolled a browser key since that copy was made signs with a key it does not list. Copy the issuer's "
+                  "current approvers.json beside public-keys.json, or pass --issuer URL to fetch every key the issuer has seen."
+                  % (len(bad_sigs), (": approver id(s) not known here: %s" % ", ".join(unknown)) if unknown else "",
+                     ("; known approver(s) whose listed key does not verify the grant: %s" % ", ".join(stale)) if stale else "", out))
         rc = 0 if v["accepted"] else 1
         entries = read_log(args.log)
         if args.summary:
@@ -851,14 +913,25 @@ def cmd_audit(args) -> int:
                            if isinstance(e, dict) and isinstance(e.get("receipt"), dict) and e["receipt"].get("target_url")), None)
             r = reconcile(entries, read_witness(args.witness), principal=principal, target_url=target)
             older = [f for f in r["findings"] if f["finding"] == "PREDATES_WITNESS"]
+            before_log = [f for f in r["findings"] if f["finding"] == "PREDATES_EVIDENCE"]
+            in_flight = [f for f in r["findings"] if f["finding"] == "IN_FLIGHT"]
             for f in r["findings"]:
-                if f["finding"] == "PREDATES_WITNESS":
+                if f["finding"] in ("PREDATES_WITNESS", "PREDATES_EVIDENCE", "IN_FLIGHT"):
                     continue
                 print("  FINDING %-22s %s" % (f["finding"], " ".join("%s=%s" % (k, str(v)[:40]) for k, v in f.items() if k != "finding")))
             if older:
                 print("  note: %d honored row(s) predate the witness (started %s) and cannot be vouched for either way: seq %s"
                       % (len(older), (r.get("horizon") or "?")[:19], ", ".join(str(f["seq"]) for f in older[:12]) + (" ..." if len(older) > 12 else "")))
-            hard = len(r["findings"]) - len(older)
+            if before_log:
+                held_n = sum(1 for f in before_log if f.get("held"))
+                print("  note: %d receipt(s) the issuer issued to this principal predate this evidence log (first entry %s; %d of them held): "
+                      "a log that began later cannot be asked about them. If the log was not meant to start then, that is the finding."
+                      % (len(before_log), (r.get("log_start") or "?")[:19], held_n))
+            if in_flight:
+                print("  note: %d receipt(s) issued after this log's last entry (%s) have no row yet: in flight when the log was read "
+                      "(this audit's own gated command, a call still held). Audit again later; one still missing then is MISSING_EVIDENCE."
+                      % (len(in_flight), (r.get("log_end") or "?")[:19]))
+            hard = len(r["findings"]) - len(older) - len(before_log) - len(in_flight)
             print("reconciled: %d issued by the issuer, %d in evidence, %d finding(s)%s"
                   % (r["issued"], r["evidence_with_receipt"], hard,
                      " (%d issued for other targets, not this gate's)" % r["issued_elsewhere"] if r.get("issued_elsewhere") else ""))
@@ -1021,7 +1094,8 @@ def main(argv=None) -> int:
     p.add_argument("--witness", help="the issuer's witness.jsonl: reconcile the evidence against it")
     p.add_argument("--check-tree", metavar="DIR", help="verify every gated file under DIR is as the gate left it")
     p.add_argument("--summary", action="store_true", help="after the rows: calls by principal and tool with outcomes, releases, clients")
-    p.add_argument("--out", default="gargoyle-deploy")
+    p.add_argument("--out", default="gargoyle-deploy", help="folder with public-keys.json and approvers.json (default: gargoyle-deploy, else the log's own folder)")
+    p.add_argument("--issuer", metavar="URL", help="fetch the issuer's keys and every approver key it has seen (GET /keys, /approvers/audit) instead of relying on a copied approvers.json")
     p.set_defaults(fn=cmd_audit)
     p = sub.add_parser("emilia", help="export an evidence log's approved calls as EMILIA Trust Receipts")
     p.add_argument("--log", required=True, help="the middleware's audit.jsonl")

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/doctor.py

@@ -177,6 +177,17 @@ def check_issuer(env: Dict[str, str], ctx: Context) -> Dict[str, Any]:
     if isinstance(head, dict):
         detail += ", witness seq %s" % head.get("seq")
     date = None
+    try:
+        date = r.headers.get("Date") if hasattr(r, "headers") else None
+    except Exception:
+        date = None
+    if h.get("enrolled_approvers") == 1:
+        # One browser key between every hold and its release: lost, re-enrolled
+        # or on leave, nothing is released until a second approver exists.
+        return {"check": Check("issuer", WARN, detail,
+                               "one approver enrolled: a lost or re-enrolled browser key, or an absence, leaves every hold waiting; enroll a second approver (a deputy role) and test a release by each"),
+                "health": h, "date": date}
+    date = None
     try:
         date = r.headers.get("Date") if hasattr(r, "headers") else None
     except Exception:

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/evidence.py

@@ -127,6 +127,54 @@ def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any,
     return entry
 
 
+LOCK_WAIT_SECONDS = 60.0      # a lock not acquired in this long means a stuck holder; the caller fails closed
+
+
+def locked(lock_path: Any, wait_seconds: float = LOCK_WAIT_SECONDS):
+    """An exclusive lock on `lock_path` (POSIX flock, Windows byte-range
+    lock), released on exit. Processes that share a file on one workstation,
+    the hook's PreToolUse and PostToolUse among them, hold it across their
+    read-modify-write so neither loses the other's update. The wait is
+    bounded: a holder that never lets go (a hung process) raises OSError
+    after `wait_seconds` rather than hanging every later call, and a gate
+    that cannot record does not let the call through."""
+    import contextlib
+    import time as _time
+
+    @contextlib.contextmanager
+    def hold():
+        with open(lock_path, "a+b") as lock:
+            deadline = _time.monotonic() + wait_seconds
+            try:
+                import fcntl
+                while True:
+                    try:
+                        fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                        break
+                    except OSError:
+                        if _time.monotonic() >= deadline:
+                            raise OSError("lock not acquired within %.0f s: %s (a stuck holder?)" % (wait_seconds, lock_path))
+                        _time.sleep(0.02)
+                unlock = lambda: fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+            except ImportError:                       # Windows
+                import msvcrt
+                lock.seek(0)
+                while True:
+                    try:
+                        msvcrt.locking(lock.fileno(), msvcrt.LK_NBLCK, 1)
+                        break
+                    except OSError:
+                        if _time.monotonic() >= deadline:
+                            raise OSError("lock not acquired within %.0f s: %s (a stuck holder?)" % (wait_seconds, lock_path))
+                        _time.sleep(0.02)
+                unlock = lambda: (lock.seek(0), msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1))
+            try:
+                yield
+            finally:
+                unlock()
+    return hold()
+
+
 class EvidenceLog:
     """Appends entries to a JSON Lines file, continuing the chain found at
     its tail. Several gate processes may share one log (a Claude Code and
@@ -156,33 +204,8 @@ class EvidenceLog:
                     self._seq, self._tail = int(last["seq"]), str(last["entry_sha256"])
 
     def _locked(self):
-        """An exclusive, blocking lock on the log's lock file (POSIX flock,
-        Windows byte-range lock), released on exit."""
-        import contextlib
-
-        @contextlib.contextmanager
-        def hold():
-            lock_path = self.path.with_name(self.path.name + ".lock")
-            with open(lock_path, "a+b") as lock:
-                try:
-                    import fcntl
-                    fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
-                    unlock = lambda: fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
-                except ImportError:                       # Windows
-                    import msvcrt
-                    lock.seek(0)
-                    while True:
-                        try:
-                            msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)   # retries about ten seconds, then raises
-                            break
-                        except OSError:
-                            continue
-                    unlock = lambda: (lock.seek(0), msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1))
-                try:
-                    yield
-                finally:
-                    unlock()
-        return hold()
+        """An exclusive, blocking lock on the log's lock file, released on exit."""
+        return locked(self.path.with_name(self.path.name + ".lock"))
 
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
                receipt: Any = None, grant: Any = None, execution: Any = None,
@@ -287,8 +310,13 @@ def verify_log(
         else:
             reason = ACCEPT_ENTRY_VERIFIED
             if e["receipt"] is not None:
+                # Provenance only: a refused entry says the receipt was issued and
+                # the call did not run. It may be written long after the receipt
+                # expired (an honored call nobody came back for is reaped an hour
+                # on), so it is checked as of its own issuance, not the entry's.
+                issued_at = e["receipt"].get("timestamp_utc") if isinstance(e["receipt"], dict) else None
                 p = verify_provenance(e["receipt"], pinned_public_keys=issuer_public_keys,
-                                      now=_parse_at(e["at"]), historical=True)
+                                      now=_parse_at(issued_at if isinstance(issued_at, str) else e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         counts[e["kind"]] += 1
         plan_ref = None

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/issuer_service.py

@@ -777,6 +777,14 @@ def build_issuer_app(
         _notice_revocations()
         return {"approvers": registry.public_hex()}
 
+    @app.get("/approvers/audit")
+    async def approvers_audit():
+        """Public, for `gargoyle audit --issuer`: every key each approver has
+        held, current first, then replaced and revoked ones. A grant signed
+        while a key was trusted still verifies; nothing here admits a key."""
+        _notice_revocations()
+        return {"approvers": registry.audit_keys_hex()}
+
     @app.post("/approvers/enroll")
     async def enroll(request: Request, authorization: Optional[str] = Header(default=None)):
         """Bind the caller's UPN to the public key their browser generated.

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/mcp_server.py

@@ -888,16 +888,21 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
             # then goes through the gate exactly as the assistant's own writes.
             from gargoyle.revert import REF_REVERT_DISABLED, revert_text
             from gargoyle.state import REF_TARGET_STATE_UNREADABLE, StateUnreadable
-            if state.snapshots is None:
-                return _success(msg_id, {"content": [{"type": "text", "text": revert_text(REF_REVERT_DISABLED)}], "isError": True,
-                                         "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: REF_REVERT_DISABLED}})
             rargs = params.get("arguments") or {}
-            try:
-                plan = plan_revert(state.snapshots, str(rargs.get("decision_id") or "last"), state.adapter,
-                                   ref=rargs.get("path") if isinstance(rargs.get("path"), str) else None)
-            except StateUnreadable:
-                plan = {"reason": REF_TARGET_STATE_UNREADABLE}
+            if state.snapshots is None:
+                plan = {"reason": REF_REVERT_DISABLED}
+            else:
+                try:
+                    plan = plan_revert(state.snapshots, str(rargs.get("decision_id") or "last"), state.adapter,
+                                       ref=rargs.get("path") if isinstance(rargs.get("path"), str) else None)
+                except StateUnreadable:
+                    plan = {"reason": REF_TARGET_STATE_UNREADABLE}
             if "reason" in plan:
+                # Refused before any receipt: the trail still says the assistant
+                # asked to undo something and why it could not (the Windows
+                # acceptance run of 2026-11-02 found this refusal unrecorded).
+                _record(state, "refused", {"reason": plan["reason"], "envelope": None, "grant": None,
+                                           "ref": rargs.get("path") if isinstance(rargs.get("path"), str) else None}, params)
                 return _success(msg_id, {"content": [{"type": "text", "text": revert_text(plan["reason"])}], "isError": True,
                                          "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: plan["reason"]}})
             params = plan["params"]

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/gargoyle/reconcile.py

@@ -6,6 +6,7 @@ Findings, never silently fixed:
   UNWITNESSED_RECEIPT   evidence honors a decision the issuer never issued (forged or foreign)
   UNWITNESSED_RELEASE   a held call was honored but the issuer saw no grant for its hold (or plan)
   MISSING_EVIDENCE      the issuer issued a receipt to this principal and the client recorded nothing
+  PREDATES_EVIDENCE     issued more than the window before this log's genesis entry; the log cannot be asked about it (information)
   EVIDENCE_BEFORE_ISSUE the client's entry predates the issuer's issuance
   CHANGED_OUTSIDE_GATE  a file under the gated folder is not in the state the last gated write left it
 """
@@ -52,6 +53,23 @@ def reconcile(evidence: Iterable[Any], witness: Iterable[Any], *, principal: Opt
     findings: List[Dict[str, Any]] = []
     seen_decisions = set()
     honored_at: Dict[Any, Any] = {}          # decision_id -> seq of the entry that first honored it
+    # The evidence log's own beginning: an issuance older than its first entry
+    # is one this log was never in a position to record (a fresh install, a
+    # rotated log). Reported, counted, and kept apart from MISSING_EVIDENCE.
+    evidence = list(evidence)
+    log_start: Optional[datetime] = None
+    first = next((e for e in evidence if isinstance(e, dict)), None)
+    if first is not None and first.get("seq") == 1 and first.get("prev_sha256") == "0" * 64:
+        # Only a log that begins at its genesis entry can say when it began;
+        # a log missing its head is a chain failure, and what the head would
+        # have held stays MISSING_EVIDENCE.
+        log_start = _parse(first.get("at"))
+    # The log's last entry: an issuance newer than it is a call whose evidence
+    # row the executor had not written when this log was read (the audit's own
+    # gated command, a call still waiting for its approver). Reported as
+    # IN_FLIGHT, information, not failure; the next audit settles it.
+    last = next((e for e in reversed(evidence) if isinstance(e, dict)), None)
+    log_end: Optional[datetime] = _parse(last.get("at")) if last is not None else None
     for e in evidence:
         if not isinstance(e, dict):
             continue
@@ -100,10 +118,21 @@ def reconcile(evidence: Iterable[Any], witness: Iterable[Any], *, principal: Opt
         if target_url is not None and isinstance(w.get("target_url"), str) and w["target_url"] != target_url:
             elsewhere += 1
             continue
-        findings.append({"finding": "MISSING_EVIDENCE", "decision_id": did, "tool": w.get("tool"), "principal": w.get("principal"),
+        at_w = _parse(w.get("at"))
+        # Every issuance precedes its own evidence entry by a little; only one
+        # older than the log's first entry by more than the window predates it.
+        if log_start is not None and at_w is not None and (log_start - at_w).total_seconds() > window_seconds:
+            kind = "PREDATES_EVIDENCE"
+        elif log_end is not None and at_w is not None and at_w > log_end:
+            kind = "IN_FLIGHT"
+        else:
+            kind = "MISSING_EVIDENCE"
+        findings.append({"finding": kind, "decision_id": did, "tool": w.get("tool"), "principal": w.get("principal"),
                          "held": bool(w.get("held")), "at": w.get("at")})
-    hard = [f for f in findings if f["finding"] != "PREDATES_WITNESS"]
+    hard = [f for f in findings if f["finding"] not in ("PREDATES_WITNESS", "PREDATES_EVIDENCE", "IN_FLIGHT")]
     return {"accepted": not hard, "findings": findings, "horizon": horizon.isoformat() if horizon else None,
+            "log_start": log_start.isoformat() if log_start else None,
+            "log_end": log_end.isoformat() if log_end else None,
             "issued": len(issued), "evidence_with_receipt": len(seen_decisions), "issued_elsewhere": elsewhere}
 
 

{gargoyle_receipts-0.20.0.dev0 → gargoyle_receipts-0.22.0.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.20.0.dev0
+Version: 0.22.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -64,7 +64,7 @@ by whom, and what changed.
 
 ## Status
 
-Pre-release `0.20.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
+Pre-release `0.22.0.dev0` on PyPI as `gargoyle-receipts`. Wire format
 `gargoyle/3`, evidence log `gargoyle-evidence/4`, witness
 `gargoyle-witness/1`; all three are specified in [SPEC.md](SPEC.md) and may
 still change before a first release.
@@ -91,7 +91,7 @@ against a fake Graph server); the OAuth broker for hosted connectors
 (deployed, metadata and redirect checks verified, no human sign-in through a
 connector yet).
 
-**Assurance.** 561 Python tests on Linux and Windows across Python 3.12,
+**Assurance.** 565 Python tests on Linux and Windows across Python 3.12,
 3.13 and 3.14, at dependency floors and at a lock file; a TypeScript suite
 that recomputes the conformance vectors byte for byte; two outside,
 model-driven security reviews on 2026-10-20 (ten findings, all fixed); the
@@ -378,6 +378,13 @@ enrollment, revocation and discovery report, on the operator's server.
     gargoyle audit --log audit.jsonl --witness witness.jsonl           # reconcile by decision id: unwitnessed receipts, releases without a grant, missing evidence
     gargoyle audit --log audit.jsonl --check-tree /srv/shared          # hash the gated folder against the recorded states; name files changed around the gate
     gargoyle audit --log audit.jsonl --summary                         # calls by principal and tool, side-door findings
+    gargoyle audit --log audit.jsonl --issuer https://gargoyle.lan      # take the issuer's keys and every approver key it has seen from the issuer, not from a copied file
+
+The audit needs the public keys (`public-keys.json`, by default beside the
+log or in `--out`). Grants verify against every key an approver has held,
+so an approver who re-enrolled a browser key is still audited; with
+`--issuer` that list comes from the issuer itself and a stale copy of
+`approvers.json` can no longer fail a valid grant.
 
 On a machine the user administers the gate constrains the assistant, not
 the user; these checks make the difference visible. SPEC.md section 15
@@ -661,7 +668,8 @@ receipts work unchanged. Configuration is by environment:
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`, or `gargoyle issuer`): identity token in, receipt out,
 with the hold and grant exchange for flagged calls (`/issue`, `/pending`,
-`/grants`, `/decline`, `/record`, `/keys`, `/sidedoors`) and the browser
+`/grants`, `/decline`, `/record`, `/keys`, `/approvers`, `/approvers/audit`,
+`/sidedoors`) and the browser
 approval console at `/approve`. Policy from a rules file or OPA; identity
 from a pinned key or, with `GARGOYLE_ENTRA_TENANT`, the tenant's signing
 keys (both at once when a pinned key is also set).
@@ -674,6 +682,8 @@ keys (both at once when a pinned key is also set).
 | `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys, with a `revoked` list, re-read when its content changes) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
 | `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 `persistent` |
 | `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 |
+| `GARGOYLE_DECLINE_LIMIT`, `GARGOYLE_DECLINE_WINDOW_HOURS` | the decline cooldown: after this many declines of the same (principal, tool, path) within the window (defaults 2 and 24), the issuer refuses the next ask with `REF_ISSUER_DECLINED_RECENTLY` instead of holding it again, so an approver is not asked the same question a third time in a day; `0` disables |
+| `GARGOYLE_RECEIPT_TTL_SECONDS` | how long an issued receipt stays presentable (default 300); a held receipt's hold lives up to six times that, capped at an hour |
 | `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys) |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | 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.20.0.dev0 → gargoyle_receipts-0.22.0.dev0}/pyproject.toml

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