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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.3.dev0
+Version: 0.17.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.17.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -161,7 +161,9 @@ two-method interface.
 **No engine.** `gargoyle.rules.RulesPolicy` decides from a JSON file:
 first matching rule wins, globs on tool name, principal, delegation,
 the caller's groups and roles, and string arguments, actions allow, hold
-or deny. The pin is the file's hash,
+or deny. Argument globs that look like paths are matched on a normalized
+form (separators, `..`, letter case), so a rule for one folder is not
+slipped by traversal or spelling; `*` spans folders. The pin is the file's hash,
 so an edit invalidates outstanding receipts exactly as an engine change
 does. This is what `gargoyle init` sets up.
 
@@ -278,9 +280,14 @@ chat channel can approve anything.
 
     pip install gargoyle-receipts
 
-Three commands, no policy engine, no containers, no client changes:
+Three commands, no policy engine, no containers, no client changes
+(`--observe` starts a deployment in record-only mode, every call allowed
+including destructive ones and every call recorded; `gargoyle audit
+--summary` then shows calls by principal and tool, the input for the
+hold and deny rules):
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
+    gargoyle init --observe /path/...           # or: allow and record everything, hold nothing, tighten later
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
@@ -298,7 +305,11 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Every key an approver held stays in the file
+is never accepted again. The role is what counts at release time: a
+grant under an enrolled key is accepted only from that account, under a
+token that carries the role now, so a role removed in the directory ends
+the power at once. One key per account: a second browser does not enroll
+until the first key consents or the operator revokes it. Every key an approver held stays in the file
 (`history`), so an audit of grants released under an earlier key still
 verifies: copy the issuer's current `approvers.json` beside the evidence
 before auditing. Approvers, and
@@ -397,6 +408,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_MAX_OPEN_HOLDS` | how many held receipts and plans one principal may have waiting at once (default 20); the call over the cap is `REF_ISSUER_TOO_MANY_HOLDS` and nothing is stored |
+| issuer `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
@@ -405,7 +417,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |
 | `GARGOYLE_MCP_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
-| `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
+| `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file; the replay claims that make a receipt single-use live beside it in `<log stem>.replay.sqlite`, so a restarted gate still refuses a receipt it honored |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`): identity token in, receipt out, with the hold and grant
@@ -453,7 +465,7 @@ on it.
 | `mcp_server` | the stdio MCP middleware (and demo executor), with self-issue mode |
 | `fs_server` | a small Python filesystem MCP server, for clients without Node |
 | `issuer_service` | the HTTP issuing service: identity in, receipts out, holds and grants |
-| `replay_cache`, `pending_store` | single use for receipts and holds; in-memory or Redis |
+| `replay_cache`, `pending_store` | single use for receipts and holds; in memory, SQLite beside the audit log (the middleware's default) or Redis |
 | `approval`, `approver_cli`, `approver_trust` | grants, the human's tool, approver key trust |
 | `published_record_source` | the live policy pin as a publisher-signed record with serial and expiry |
 | `key_record_source` | root-signed issuer and approver keys with windows and revocation |

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.17.0.dev0}/README.md

@@ -21,7 +21,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.17.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -123,7 +123,9 @@ two-method interface.
 **No engine.** `gargoyle.rules.RulesPolicy` decides from a JSON file:
 first matching rule wins, globs on tool name, principal, delegation,
 the caller's groups and roles, and string arguments, actions allow, hold
-or deny. The pin is the file's hash,
+or deny. Argument globs that look like paths are matched on a normalized
+form (separators, `..`, letter case), so a rule for one folder is not
+slipped by traversal or spelling; `*` spans folders. The pin is the file's hash,
 so an edit invalidates outstanding receipts exactly as an engine change
 does. This is what `gargoyle init` sets up.
 
@@ -240,9 +242,14 @@ chat channel can approve anything.
 
     pip install gargoyle-receipts
 
-Three commands, no policy engine, no containers, no client changes:
+Three commands, no policy engine, no containers, no client changes
+(`--observe` starts a deployment in record-only mode, every call allowed
+including destructive ones and every call recorded; `gargoyle audit
+--summary` then shows calls by principal and tool, the input for the
+hold and deny rules):
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
+    gargoyle init --observe /path/...           # or: allow and record everything, hold nothing, tighten later
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
@@ -260,7 +267,11 @@ stay on file so earlier grants still audit; new ones are refused at the
 issuer and at every middleware on its next held call. Revocation retires
 a key, not a person: while the Approver role stands, the person can sign
 in and enroll a fresh key, so remove the role too; the revoked key itself
-is never accepted again. Every key an approver held stays in the file
+is never accepted again. The role is what counts at release time: a
+grant under an enrolled key is accepted only from that account, under a
+token that carries the role now, so a role removed in the directory ends
+the power at once. One key per account: a second browser does not enroll
+until the first key consents or the operator revokes it. Every key an approver held stays in the file
 (`history`), so an audit of grants released under an earlier key still
 verifies: copy the issuer's current `approvers.json` beside the evidence
 before auditing. Approvers, and
@@ -359,6 +370,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_MAX_OPEN_HOLDS` | how many held receipts and plans one principal may have waiting at once (default 20); the call over the cap is `REF_ISSUER_TOO_MANY_HOLDS` and nothing is stored |
+| issuer `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
@@ -367,7 +379,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |
 | `GARGOYLE_MCP_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
-| `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
+| `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file; the replay claims that make a receipt single-use live beside it in `<log stem>.replay.sqlite`, so a restarted gate still refuses a receipt it honored |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from
 `app_from_env()`): identity token in, receipt out, with the hold and grant
@@ -415,7 +427,7 @@ on it.
 | `mcp_server` | the stdio MCP middleware (and demo executor), with self-issue mode |
 | `fs_server` | a small Python filesystem MCP server, for clients without Node |
 | `issuer_service` | the HTTP issuing service: identity in, receipts out, holds and grants |
-| `replay_cache`, `pending_store` | single use for receipts and holds; in-memory or Redis |
+| `replay_cache`, `pending_store` | single use for receipts and holds; in memory, SQLite beside the audit log (the middleware's default) or Redis |
 | `approval`, `approver_cli`, `approver_trust` | grants, the human's tool, approver key trust |
 | `published_record_source` | the live policy pin as a publisher-signed record with serial and expiry |
 | `key_record_source` | root-signed issuer and approver keys with windows and revocation |

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

@@ -135,9 +135,10 @@ class GraphAdapter:
     @staticmethod
     def _desc(ref: str, obj: Any, summary: str, irreversible: bool = False) -> Tuple[Dict[str, Any], Optional[bytes]]:
         data = canonical_json(obj).encode("utf-8") if obj is not None else None
-        desc = describe(ref, data, with_text=False)
-        if data is not None:
-            desc["text"] = json.dumps(obj, indent=2, sort_keys=True)
+        # The text is the hashed bytes themselves (canonical JSON), so the
+        # console can verify it against the bound state before showing it;
+        # it pretty-prints JSON for display.
+        desc = describe(ref, data, with_text=True)
         desc["summary"] = summary
         if irreversible:
             desc["irreversible"] = True

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

@@ -51,6 +51,17 @@ from pathlib import Path
 
 PRINCIPAL = "spiffe://gargoyle.local/agents/assistant"
 
+OBSERVE_RULES = {
+    # Observe mode: every call allowed (deletes too), every call recorded, none held. The
+    # first week of a deployment, so the hold and deny rules are written
+    # from the audit rather than guessed. The policy pin changes when the
+    # rules do, so switching modes means restarting the issuer and copying
+    # the new record.json to each client.
+    "version": "1",
+    "default": "allow",
+    "rules": [],
+}
+
 DEFAULT_RULES = {
     "version": "1",
     "default": "deny",
@@ -118,7 +129,22 @@ def cmd_init(args) -> int:
     issuer_url = args.issuer_url or "http://%s:%d" % (args.host, args.port)
 
     rules = out / "rules.json"
-    if not rules.exists():
+    if args.observe:
+        current = None
+        if rules.exists():
+            try:
+                current = json.loads(rules.read_text())
+            except ValueError as exc:
+                print("%s is not valid JSON (%s); fix or remove it before --observe" % (rules, exc), file=sys.stderr)
+                return 2
+        if current is None or current == DEFAULT_RULES:
+            _write(rules, json.dumps(OBSERVE_RULES, indent=2) + "\n")
+        elif current != OBSERVE_RULES:
+            print("rules.json was edited by hand and is left as it is; --observe changed nothing", file=sys.stderr)
+        print("observe mode: rules.json allows every call, destructive ones included; the gate records all of "
+              "them and holds none. Tighten rules.json from `gargoyle audit --summary`, then restart the issuer "
+              "and copy the new record.json to the clients.")
+    elif not rules.exists():
         _write(rules, json.dumps(DEFAULT_RULES, indent=2) + "\n")
     _write(out / "issuer.env", _env_lines({
         "GARGOYLE_ISSUER_KEY_ID": "issuer-1", "GARGOYLE_ISSUER_KEY_HEX": issuer_hex,
@@ -360,6 +386,33 @@ def cmd_approvers(args) -> int:
     return 1
 
 
+def _audit_summary(report, raw) -> None:
+    """Calls by principal and tool with their outcomes, then who released
+    and which clients: a week of observe mode as a table, the input for
+    writing the hold and deny rules."""
+    from collections import Counter
+    counts: Dict[tuple, Counter] = {}
+    releases: Counter = Counter()
+    clients: Counter = Counter()
+    ats = [e.get("at") for e in raw if isinstance(e, dict) and isinstance(e.get("at"), str)]
+    from gargoyle.evidence import FAILED_VERDICTS
+    for r in report:
+        kind = r["kind"] or "?"
+        if kind == "honored" and r.get("verdict") in FAILED_VERDICTS:
+            kind = "failed"            # admitted, but the upstream did not do it
+        counts.setdefault((r["principal"] or "?", r["tool"] or "?"), Counter())[kind] += 1
+        for who in r.get("released_by") or []:
+            releases[who] += 1
+        clients[r.get("client") or "(client unnamed)"] += 1
+    print("summary: %d call(s)%s" % (len(report), (", %s to %s" % (min(ats)[:19], max(ats)[:19])) if ats else ""))
+    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "failed", "refused"))
+    for (principal, tool), c in sorted(counts.items(), key=lambda kv: (kv[0][0], -sum(kv[1].values()), kv[0][1])):
+        print("  %-28s %-24s %7d %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("failed", 0), c.get("refused", 0)))
+    if releases:
+        print("  releases: " + ", ".join("%s %d" % (w, n) for w, n in releases.most_common()))
+    print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))
+
+
 def cmd_audit(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
     from gargoyle.execution import verify_chain
@@ -406,6 +459,8 @@ def cmd_audit(args) -> int:
               % (v["count"], v["honored"], v["refused"], failed, v["reason"], v["tail_sha256"][:16]))
         rc = 0 if v["accepted"] else 1
         entries = read_log(args.log)
+        if args.summary:
+            _audit_summary(v["entries"], entries)
         if args.witness and not Path(args.witness).exists():
             print("witness file not found: %s (copy the issuer's witness.jsonl here first)" % args.witness, file=sys.stderr)
             return 2
@@ -460,6 +515,8 @@ def main(argv=None) -> int:
     p.add_argument("--issuer-url", help="URL the client reaches the issuer at (default http://HOST:PORT)")
     p.add_argument("--client-python", help="the client's Python executable for the MCP entry (default: this one)")
     p.add_argument("--client-config-dir", help="where the client keeps middleware.env, record.json, audit.jsonl (default: --out)")
+    p.add_argument("--observe", action="store_true",
+                   help="observe mode: allow and record every call, hold none; tighten rules.json later from the audit")
     p.add_argument("--approvers", type=int, default=1, metavar="N",
                    help="how many approver keys to create (approver-1..N); a rule with \"approvals\": 2 then needs two of them")
     p.add_argument("--upstream", choices=["npx-filesystem", "python-fs"], default="npx-filesystem",
@@ -512,6 +569,7 @@ def main(argv=None) -> int:
     p.add_argument("--log", help="the middleware's audit.jsonl: verify every entry")
     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.set_defaults(fn=cmd_audit)
     args = parser.parse_args(argv)

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

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

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

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

gargoyle_receipts-0.17.0.dev0/gargoyle/globs.py

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