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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.4.dev0
+Version: 0.18.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.18.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
@@ -103,7 +103,7 @@ Python 3.12 or later. A TypeScript verifier and consumer for Node 20+
 lives in [ts/](ts/) (`cd ts && npm install && npm test`); its suite
 recomputes the same conformance vectors byte for byte, so the two
 implementations cannot drift apart silently. Redis is optional (`.[redis]`) and only needed to
-share the replay cache and pending-approval set across executor replicas.
+share the replay cache and pending-approval set across replicas of the remote gate; a single gate keeps its replay claims in SQLite beside its evidence log.
 
 ## Issuing a receipt
 
@@ -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.
 
@@ -286,6 +288,7 @@ 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 tokens --out gargoyle-deploy       # later: new client and approver tokens, same keys
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
@@ -303,7 +306,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
@@ -391,7 +398,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_GATE_KEY_ID`, `GARGOYLE_MCP_GATE_PUBLIC_KEY_HEX` | the pinned issuer key |
 | `GARGOYLE_MCP_TARGET_ID` | the target identity receipts bind to |
 | `GARGOYLE_MCP_PRINCIPAL` | the client this server serves |
-| `GARGOYLE_MCP_RECORD_PATH` | the published policy record |
+| `GARGOYLE_MCP_RECORD_PATH`, `GARGOYLE_MCP_RECORD_URL` | the live policy pin: a file copied out of band, or (what `init` sets) the issuer's signed record at `<issuer>/record`, followed live and cached a minute, so a rule change reaches every gate without a copy or a restart |
 | `GARGOYLE_MCP_APPROVER_KEY_ID`, `GARGOYLE_MCP_APPROVER_PUBLIC_KEY_HEX` | the approver keys whose grants release flagged calls (optional, both or neither; comma-separated lists for several) |
 | `GARGOYLE_MCP_EXECUTOR_KEY_ID`, `GARGOYLE_MCP_EXECUTOR_KEY_HEX` | this server's own signing key, so honored calls carry an execution receipt in `_meta["gargoyle/execution"]` (optional, both or neither) |
 | `GARGOYLE_MCP_ISSUER_URL`, `GARGOYLE_MCP_CLIENT_TOKEN` | self-issue mode: the issuing service and the identity token (whose subject is this server's principal) to obtain receipts with; `GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS` and `GARGOYLE_MCP_POLL_SECONDS` tune the wait for a grant |
@@ -402,6 +409,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_MAX_OPEN_HOLDS` | how many held receipts and plans one principal may have waiting at once (default 20); the call over the cap is `REF_ISSUER_TOO_MANY_HOLDS` and nothing is stored |
+| issuer `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
@@ -410,7 +418,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
@@ -452,13 +460,13 @@ on it.
 | `jws` | the receipt as a JWS any JWT library verifies |
 | `envelope` | receipt construction, hash region, signature region, currency check |
 | `verifier` | the pure target-side check and every refusal code |
-| `consumer` | `Consumer` (pin, keys, verify, claim, attest) and the reference HTTP target |
+| `consumer` | `Consumer` (pin, keys, verify, claim, attest) |
 | `execution` | execution receipts and the offline chain check |
 | `evidence` | the executor's hash-chained log of every decision, and its offline verifier |
 | `mcp_server` | the stdio MCP middleware (and demo executor), with self-issue mode |
 | `fs_server` | a small Python filesystem MCP server, for clients without Node |
 | `issuer_service` | the HTTP issuing service: identity in, receipts out, holds and grants |
-| `replay_cache`, `pending_store` | single use for receipts and holds; in-memory or Redis |
+| `replay_cache`, `pending_store` | single use for receipts and holds; in memory, SQLite beside the audit log (the middleware's default) or Redis |
 | `approval`, `approver_cli`, `approver_trust` | grants, the human's tool, approver key trust |
 | `published_record_source` | the live policy pin as a publisher-signed record with serial and expiry |
 | `key_record_source` | root-signed issuer and approver keys with windows and revocation |

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.18.0.dev0}/README.md

@@ -21,7 +21,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.18.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
@@ -65,7 +65,7 @@ Python 3.12 or later. A TypeScript verifier and consumer for Node 20+
 lives in [ts/](ts/) (`cd ts && npm install && npm test`); its suite
 recomputes the same conformance vectors byte for byte, so the two
 implementations cannot drift apart silently. Redis is optional (`.[redis]`) and only needed to
-share the replay cache and pending-approval set across executor replicas.
+share the replay cache and pending-approval set across replicas of the remote gate; a single gate keeps its replay claims in SQLite beside its evidence log.
 
 ## Issuing a receipt
 
@@ -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.
 
@@ -248,6 +250,7 @@ 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 tokens --out gargoyle-deploy       # later: new client and approver tokens, same keys
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
@@ -265,7 +268,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
@@ -353,7 +360,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_GATE_KEY_ID`, `GARGOYLE_MCP_GATE_PUBLIC_KEY_HEX` | the pinned issuer key |
 | `GARGOYLE_MCP_TARGET_ID` | the target identity receipts bind to |
 | `GARGOYLE_MCP_PRINCIPAL` | the client this server serves |
-| `GARGOYLE_MCP_RECORD_PATH` | the published policy record |
+| `GARGOYLE_MCP_RECORD_PATH`, `GARGOYLE_MCP_RECORD_URL` | the live policy pin: a file copied out of band, or (what `init` sets) the issuer's signed record at `<issuer>/record`, followed live and cached a minute, so a rule change reaches every gate without a copy or a restart |
 | `GARGOYLE_MCP_APPROVER_KEY_ID`, `GARGOYLE_MCP_APPROVER_PUBLIC_KEY_HEX` | the approver keys whose grants release flagged calls (optional, both or neither; comma-separated lists for several) |
 | `GARGOYLE_MCP_EXECUTOR_KEY_ID`, `GARGOYLE_MCP_EXECUTOR_KEY_HEX` | this server's own signing key, so honored calls carry an execution receipt in `_meta["gargoyle/execution"]` (optional, both or neither) |
 | `GARGOYLE_MCP_ISSUER_URL`, `GARGOYLE_MCP_CLIENT_TOKEN` | self-issue mode: the issuing service and the identity token (whose subject is this server's principal) to obtain receipts with; `GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS` and `GARGOYLE_MCP_POLL_SECONDS` tune the wait for a grant |
@@ -364,6 +371,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_MAX_OPEN_HOLDS` | how many held receipts and plans one principal may have waiting at once (default 20); the call over the cap is `REF_ISSUER_TOO_MANY_HOLDS` and nothing is stored |
+| issuer `GARGOYLE_ALLOW_SELF_APPROVAL` | `1` lets a person release their own call; by default the approver may be neither the hold's principal nor the party acted for (`REF_ISSUER_SELF_APPROVAL`). A grant for an expired hold is `REF_ISSUER_HOLD_EXPIRED` and the hold is dropped |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
@@ -372,7 +380,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
@@ -414,13 +422,13 @@ on it.
 | `jws` | the receipt as a JWS any JWT library verifies |
 | `envelope` | receipt construction, hash region, signature region, currency check |
 | `verifier` | the pure target-side check and every refusal code |
-| `consumer` | `Consumer` (pin, keys, verify, claim, attest) and the reference HTTP target |
+| `consumer` | `Consumer` (pin, keys, verify, claim, attest) |
 | `execution` | execution receipts and the offline chain check |
 | `evidence` | the executor's hash-chained log of every decision, and its offline verifier |
 | `mcp_server` | the stdio MCP middleware (and demo executor), with self-issue mode |
 | `fs_server` | a small Python filesystem MCP server, for clients without Node |
 | `issuer_service` | the HTTP issuing service: identity in, receipts out, holds and grants |
-| `replay_cache`, `pending_store` | single use for receipts and holds; in-memory or Redis |
+| `replay_cache`, `pending_store` | single use for receipts and holds; in memory, SQLite beside the audit log (the middleware's default) or Redis |
 | `approval`, `approver_cli`, `approver_trust` | grants, the human's tool, approver key trust |
 | `published_record_source` | the live policy pin as a publisher-signed record with serial and expiry |
 | `key_record_source` | root-signed issuer and approver keys with windows and revocation |

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

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

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

@@ -55,8 +55,8 @@ 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.
+    # rules do; the issuer applies the edit at once and clients that follow
+    # its signed record pick the new pin up within a minute.
     "version": "1",
     "default": "allow",
     "rules": [],
@@ -93,6 +93,27 @@ def _write(path: Path, text: str, private: bool = False) -> None:
     print("wrote", path)
 
 
+def _observe_rules(rules: Path) -> int:
+    """Switch a deployment's rules file to observe mode (allow and record
+    everything), leaving a hand-edited file alone."""
+    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`; the issuer applies the "
+          "change at once and clients that follow its record (GARGOYLE_MCP_RECORD_URL) pick the new pin up "
+          "within a minute. A client on a static record.json needs the new file.")
+    return 0
+
+
 def cmd_init(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
     from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption, PrivateFormat, PublicFormat
@@ -100,12 +121,26 @@ def cmd_init(args) -> int:
 
     out = Path(args.out).resolve()
     out.mkdir(parents=True, exist_ok=True)
+    if (out / "issuer.env").exists() and not args.force:
+        # A deployment lives here. Its keys and tokens are what every client
+        # and approver holds; regenerating them by accident strands them all.
+        if args.observe:
+            return _observe_rules(out / "rules.json")
+        print("%s already holds a deployment; its keys and tokens are kept. New tokens: `gargoyle tokens --out %s`. "
+              "Fresh keys: `gargoyle init --force` (every client and approver must then be re-provisioned), or a new --out."
+              % (out, out), file=sys.stderr)
+        return 2
     # A Windows path given on a Linux issuer host is the client's and is kept as typed.
     windows = re.match(r"^[A-Za-z]:[\\/]", args.directory) is not None
     allowed = args.directory if windows else str(Path(args.directory).resolve())
     sep = "\\" if windows else "/"
     client_dir = args.client_config_dir or str(out)
     client_python = args.client_python or sys.executable
+    from gargoyle.globs import normalize_path
+    if normalize_path(client_dir) == normalize_path(allowed) or normalize_path(client_dir).startswith(normalize_path(allowed).rstrip("/") + "/"):
+        print("note: the client config folder %s is inside the folder the gate serves (%s). The gate refuses calls into its "
+              "own files (REF_TARGET_GATE_FILES), but secrets are better kept out of the served tree: --client-config-dir."
+              % (client_dir, allowed), file=sys.stderr)
 
     def new_key():
         k = Ed25519PrivateKey.generate()
@@ -130,20 +165,9 @@ def cmd_init(args) -> int:
 
     rules = out / "rules.json"
     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.")
+        rc = _observe_rules(rules)
+        if rc:
+            return rc
     elif not rules.exists():
         _write(rules, json.dumps(DEFAULT_RULES, indent=2) + "\n")
     _write(out / "issuer.env", _env_lines({
@@ -159,6 +183,7 @@ def cmd_init(args) -> int:
         "GARGOYLE_MCP_GATE_KEY_ID": "issuer-1", "GARGOYLE_MCP_GATE_PUBLIC_KEY_HEX": issuer_pub,
         "GARGOYLE_MCP_TARGET_ID": "mcp://filesystem/" + allowed, "GARGOYLE_MCP_PRINCIPAL": PRINCIPAL,
         "GARGOYLE_MCP_RECORD_PATH": client_dir + sep + "record.json",
+        "GARGOYLE_MCP_RECORD_URL": issuer_url + "/record",       # follow the issuer's signed pin; the file is the offline fallback
         "GARGOYLE_MCP_APPROVER_KEY_ID": approver_ids, "GARGOYLE_MCP_APPROVER_PUBLIC_KEY_HEX": approver_pubs,
         "GARGOYLE_MCP_EXECUTOR_KEY_ID": "executor-1", "GARGOYLE_MCP_EXECUTOR_KEY_HEX": executor_hex,
         "GARGOYLE_MCP_ISSUER_URL": issuer_url, "GARGOYLE_MCP_CLIENT_TOKEN": client_token,
@@ -226,6 +251,58 @@ WantedBy=multi-user.target
     return 0
 
 
+def cmd_tokens(args) -> int:
+    """New identity tokens from the deployment's existing identity key: the
+    client's shared token (unless the client signs in with Entra, whose
+    token renews itself) and every file-key approver's. Nothing else
+    changes, so clients keep their keys and the audit its trust."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    from gargoyle.jws import encode
+    out = Path(args.out).resolve()
+    issuer_env = out / "issuer.env"
+    if not issuer_env.exists():
+        print("%s holds no deployment (no issuer.env)" % out, file=sys.stderr)
+        return 2
+    env = _read_env(issuer_env)
+    idp_hex = env.get("GARGOYLE_IDP_KEY_HEX")
+    if not idp_hex:
+        print("issuer.env keeps no identity key (a deployment older than 0.9); make a fresh one with `gargoyle init` to a new --out", file=sys.stderr)
+        return 2
+    idp = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(idp_hex))
+    kid = env.get("GARGOYLE_IDP_KEY_ID", "idp-1")
+    exp = int((datetime.now(timezone.utc) + timedelta(days=args.token_days)).timestamp())
+    mw = out / "middleware.env"
+    if mw.exists():
+        menv = _read_env(mw)
+        if "GARGOYLE_MCP_CLIENT_TOKEN" in menv:
+            menv["GARGOYLE_MCP_CLIENT_TOKEN"] = encode({"sub": menv.get("GARGOYLE_MCP_PRINCIPAL", PRINCIPAL), "aud": "gargoyle-issuer", "exp": exp}, idp, kid)
+            _write(mw, _env_lines(menv), private=True)
+            mcp = out / "mcp-config.json"
+            if mcp.exists():
+                doc = json.loads(mcp.read_text())
+                for server in doc.get("mcpServers", {}).values():
+                    if "GARGOYLE_MCP_CLIENT_TOKEN" in server.get("env", {}):
+                        server["env"]["GARGOYLE_MCP_CLIENT_TOKEN"] = menv["GARGOYLE_MCP_CLIENT_TOKEN"]
+                _write(mcp, json.dumps(doc, indent=2) + "\n", private=True)
+        else:
+            print("middleware.env signs in with Entra; that token renews itself and was left alone")
+    for env_path in sorted(out.glob("approver*.env")):
+        aenv = _read_env(env_path)
+        akid = aenv.get("GARGOYLE_APPROVER_KEY_ID")
+        if not akid:
+            continue
+        tok = encode({"sub": akid, "roles": [DEFAULT_APPROVER_ROLE], "aud": "gargoyle-issuer", "exp": exp}, idp, kid)
+        aenv["GARGOYLE_APPROVER_TOKEN"] = tok
+        _write(env_path, _env_lines(aenv), private=True)
+        web = out / env_path.name.replace("approver", "approver-web", 1).replace(".env", ".json")
+        if web.exists():
+            doc = json.loads(web.read_text())
+            doc["token"] = tok
+            _write(web, json.dumps(doc, indent=2) + "\n", private=True)
+    print("new tokens, valid %d days; copy middleware.env (and approver-web*.json) to the machines that use them and restart their MCP clients" % args.token_days)
+    return 0
+
+
 def cmd_login(args) -> int:
     """Device-code sign-in; then middleware.env (and mcp-config.json when
     present) switch from the shared init token to this user's Entra token,
@@ -395,15 +472,19 @@ def _audit_summary(report, raw) -> None:
     releases: Counter = Counter()
     clients: Counter = Counter()
     ats = [e.get("at") for e in raw if isinstance(e, dict) and isinstance(e.get("at"), str)]
+    from gargoyle.evidence import FAILED_VERDICTS
     for r in report:
-        counts.setdefault((r["principal"] or "?", r["tool"] or "?"), Counter())[r["kind"] or "?"] += 1
+        kind = r["kind"] or "?"
+        if kind == "honored" and r.get("verdict") in FAILED_VERDICTS:
+            kind = "failed"            # admitted, but the upstream did not do it
+        counts.setdefault((r["principal"] or "?", r["tool"] or "?"), Counter())[kind] += 1
         for who in r.get("released_by") or []:
             releases[who] += 1
         clients[r.get("client") or "(client unnamed)"] += 1
     print("summary: %d call(s)%s" % (len(report), (", %s to %s" % (min(ats)[:19], max(ats)[:19])) if ats else ""))
-    print("  %-28s %-24s %7s %7s" % ("principal", "tool", "honored", "refused"))
+    print("  %-28s %-24s %7s %7s %7s" % ("principal", "tool", "honored", "failed", "refused"))
     for (principal, tool), c in sorted(counts.items(), key=lambda kv: (kv[0][0], -sum(kv[1].values()), kv[0][1])):
-        print("  %-28s %-24s %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("refused", 0)))
+        print("  %-28s %-24s %7d %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("failed", 0), c.get("refused", 0)))
     if releases:
         print("  releases: " + ", ".join("%s %d" % (w, n) for w, n in releases.most_common()))
     print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))
@@ -519,7 +600,13 @@ def main(argv=None) -> int:
                    help="the filesystem MCP server behind the gate: the official one via npx, or gargoyle.fs_server")
     p.add_argument("--entra-tenant", help="trust this Entra ID tenant's tokens at the issuer (users then run `gargoyle login`)")
     p.add_argument("--entra-audience", help="the issuer API app's client id or app id URI, required in Entra tokens")
+    p.add_argument("--force", action="store_true",
+                   help="regenerate keys and tokens in an existing --out (every client and approver must be re-provisioned)")
     p.set_defaults(fn=cmd_init)
+    p = sub.add_parser("tokens", help="mint new client and approver tokens from a deployment's existing keys")
+    p.add_argument("--out", default="gargoyle-deploy")
+    p.add_argument("--token-days", type=int, default=30)
+    p.set_defaults(fn=cmd_tokens)
     p = sub.add_parser("login", help="sign this workstation's user in with Entra ID (device code)")
     p.add_argument("--tenant", required=True, help="tenant id or domain")
     p.add_argument("--client-id", required=True, help="the public client app registration")

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

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

{gargoyle_receipts-0.16.4.dev0 → gargoyle_receipts-0.18.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")
@@ -118,38 +129,77 @@ def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any,
 
 class EvidenceLog:
     """Appends entries to a JSON Lines file, continuing the chain found at
-    its tail. The file is read once, when the first entry is appended; a
-    file nobody else writes to is the operating assumption (one middleware
-    process, one log), as for any append-only log."""
+    its tail. Several gate processes may share one log (a Claude Code and
+    a Claude Desktop session on the same folder): each append takes an
+    exclusive lock on `<log>.lock`, re-reads the tail when the file grew
+    since this process last wrote, then writes, so the chain never forks.
+    The lock is advisory and per host, as for any append-only log on a
+    local disk."""
 
     def __init__(self, path: str) -> None:
         self.path = Path(path)
         self._seq: Optional[int] = None
         self._tail: str = GENESIS
+        self._size: int = -1          # the file size after our last write; another writer changes it
 
     def _load_tail(self) -> None:
         self._seq, self._tail = 0, GENESIS
         if not self.path.exists():
+            self._size = 0
             return
-        for line in self.path.read_text(encoding="utf-8").splitlines():
+        text = self.path.read_text(encoding="utf-8")
+        self._size = self.path.stat().st_size
+        for line in text.splitlines():
             if line.strip():
                 last = json.loads(line)
                 if last.get("evidence_version") in EVIDENCE_VERSIONS:
                     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()
+
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
                receipt: Any = None, grant: Any = None, execution: Any = None,
                client: Optional[str] = None, ref: Optional[str] = None) -> Dict[str, Any]:
         """Write one entry and return it. Raises OSError if the file cannot
         be written; the caller decides whether that stops the call."""
-        if self._seq is None:
-            self._load_tail()
-        entry = build_entry(seq=self._seq + 1, prev_sha256=self._tail, kind=kind, tool=tool, args=args,
-                            principal=principal, reason=reason, receipt=receipt, grant=grant, execution=execution,
-                            client=client, ref=ref)
-        with open(self.path, "a", encoding="utf-8") as f:
-            f.write(json.dumps(entry, sort_keys=True) + "\n")
-        self._seq, self._tail = entry["seq"], entry["entry_sha256"]
+        with self._locked():
+            current = self.path.stat().st_size if self.path.exists() else 0
+            if self._seq is None or current != self._size:
+                self._load_tail()                 # first write, or another process wrote since: continue its chain
+            entry = build_entry(seq=self._seq + 1, prev_sha256=self._tail, kind=kind, tool=tool, args=args,
+                                principal=principal, reason=reason, receipt=receipt, grant=grant, execution=execution,
+                                client=client, ref=ref)
+            with open(self.path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, sort_keys=True) + "\n")
+            self._seq, self._tail = entry["seq"], entry["entry_sha256"]
+            self._size = self.path.stat().st_size
         return entry
 
 
@@ -191,6 +241,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 +271,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.18.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)