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

{gargoyle_receipts-0.17.0.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.17.0.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.17.0.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
 
@@ -288,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)
 
@@ -397,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 |
@@ -459,7 +460,7 @@ 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 |

{gargoyle_receipts-0.17.0.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.17.0.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
 
@@ -250,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)
 
@@ -359,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 |
@@ -421,7 +422,7 @@ 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 |

{gargoyle_receipts-0.17.0.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,
@@ -523,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.17.0.dev0 → gargoyle_receipts-0.18.0.dev0}/gargoyle/evidence.py

@@ -129,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
 
 

{gargoyle_receipts-0.17.0.dev0 → gargoyle_receipts-0.18.0.dev0}/gargoyle/issuer_service.py

@@ -63,6 +63,7 @@ from gargoyle.approvers import (DEFAULT_APPROVER_ROLE, ENV_APPROVER_GROUPS, ENV_
                                 ApproverRegistry, RevokedKeyError, may_enroll, valid_public_key_hex)
 from gargoyle.identity import entra_keys, entra_tenant_id, principal_from_token
 from gargoyle.jws import REF_JWS_KEY_UNKNOWN
+from gargoyle.published_record_source import sign_published_record
 from gargoyle.issuer import DEFAULT_TTL_SECONDS, issue
 from gargoyle.policy import Policy
 
@@ -683,9 +684,21 @@ def build_issuer_app(
     async def approve_script():
         return Response((STATIC / "approve.js").read_bytes(), media_type="text/javascript; charset=utf-8")
 
+    app.state.record_pin = None
+    app.state.record_serial = 0
+
     @app.get("/record")
     async def record():
-        return policy.pin()
+        """The live policy pin in the signed published-record form (SPEC 9),
+        so a middleware on another host can follow rule changes without a
+        file copy: it verifies the issuer's signature with the key it
+        already pins. The serial rises whenever the pin changes, so a
+        rolled-back record is refused as stale."""
+        pin = policy.pin()
+        if pin != app.state.record_pin:
+            app.state.record_pin = pin
+            app.state.record_serial = max(int(now().timestamp()), app.state.record_serial + 1)
+        return sign_published_record(pin, signing_key, key_id, serial=app.state.record_serial, now=now(), ttl_seconds=600)
 
     @app.get("/keys")
     async def keys():

{gargoyle_receipts-0.17.0.dev0 → gargoyle_receipts-0.18.0.dev0}/gargoyle/mcp_server.py

@@ -51,6 +51,7 @@ from gargoyle.consumer import REF_TARGET_NOT_CONFIGURED, Consumer
 from gargoyle.evidence import HONORED, REFUSED, EvidenceLog, TOOL_ERROR, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE
 from gargoyle.envelope import valid_principal
 from gargoyle.policy import valid_pin
+from gargoyle.verifier import REF_VERIFY_REASSERT_RE_EVALUATE_REQUIRED
 from gargoyle.replay_cache import InMemoryReplayCache, ReplayCache, SqliteReplayCache
 
 # MCP protocol version this server speaks (a real MCP revision string).
@@ -88,6 +89,7 @@ ENV_GATE_KEY_ID = "GARGOYLE_MCP_GATE_KEY_ID"
 ENV_GATE_PUBLIC_KEY_HEX = "GARGOYLE_MCP_GATE_PUBLIC_KEY_HEX"
 ENV_TARGET_ID = "GARGOYLE_MCP_TARGET_ID"
 ENV_RECORD_PATH = "GARGOYLE_MCP_RECORD_PATH"
+ENV_RECORD_URL = "GARGOYLE_MCP_RECORD_URL"     # follow the issuer's signed record instead of a file (SPEC 9)
 ENV_PRINCIPAL = "GARGOYLE_MCP_PRINCIPAL"
 ENV_APPROVER_KEY_ID = "GARGOYLE_MCP_APPROVER_KEY_ID"
 ENV_APPROVER_PUBLIC_KEY_HEX = "GARGOYLE_MCP_APPROVER_PUBLIC_KEY_HEX"
@@ -108,6 +110,7 @@ REF_TARGET_LOGIN_REQUIRED = "REF_TARGET_LOGIN_REQUIRED"   # Entra login mode and
 REF_TARGET_ISSUER_UNAVAILABLE = "REF_TARGET_ISSUER_UNAVAILABLE"
 REF_TARGET_APPROVAL_TIMEOUT = "REF_TARGET_APPROVAL_TIMEOUT"
 REF_TARGET_APPROVAL_DECLINED = "REF_TARGET_APPROVAL_DECLINED"
+REF_TARGET_GATE_FILES = "REF_TARGET_GATE_FILES"       # the call would touch the gate's own folder (config, keys, evidence, snapshots)
 
 
 class IssuerClient:
@@ -194,6 +197,15 @@ class IssuerClient:
         except Exception:
             return {}
 
+    def decline(self, approval_request_id: str) -> bool:
+        """Withdraw a hold this gate asked for (the hold's own principal may):
+        when the gate stops waiting, the card must not stay approvable."""
+        try:
+            r = self._post("/decline", {"approval_request_id": approval_request_id})
+            return r.status_code == 200 and bool(r.json().get("declined"))
+        except Exception:
+            return False
+
     def wait_for_grant(self, approval_request_id: str) -> Dict[str, Any]:
         """Poll until the hold has its grant (or, for a receipt that needs
         several approvers, the whole set), a human declined it, the hold
@@ -326,6 +338,50 @@ def call_for(tool: str, args: Any, principal: str, state_sha256: Optional[str] =
     return call
 
 
+class RecordFollower:
+    """The live policy pin, fetched as the issuer's signed record (GET
+    /record) and verified against the pinned issuer key, cached for a
+    minute. A rule change on the issuer then reaches every gate within
+    that minute, or at once when a receipt arrives under a pin the cache
+    does not know (the gate forgets the cache and asks again before
+    refusing). No file copy, no restart. The trust is the same as for
+    receipts: the issuer's key, pinned out of band. A deployment that wants
+    an independent copy of the pin keeps GARGOYLE_MCP_RECORD_PATH instead."""
+
+    def __init__(self, url: str, pinned_keys: Dict[str, Any], *, http: Any = None, ttl_seconds: float = 60.0,
+                 request_timeout: float = 10.0) -> None:
+        import requests
+        self.url = url
+        self.pinned_keys = pinned_keys
+        self._http = http if http is not None else requests.Session()
+        self.ttl_seconds = ttl_seconds
+        self.request_timeout = request_timeout
+        self._cache: Optional[tuple] = None
+        self.fetches = 0
+
+    def forget(self) -> None:
+        self._cache = None
+
+    def __call__(self, last_seen_serial: Optional[int]) -> Dict[str, Any]:
+        from gargoyle.published_record_source import load_signed_record_from_bytes
+        from gargoyle.verifier import REF_VERIFY_PUBLISHED_RECORD_INVALID
+        cached = self._cache
+        if cached is not None and time.monotonic() - cached[0] < self.ttl_seconds:
+            return cached[1]
+        self.fetches += 1
+        try:
+            r = self._http.get(self.url, timeout=self.request_timeout)
+            if r.status_code != 200:
+                res = {"record": None, "reason": REF_VERIFY_PUBLISHED_RECORD_INVALID}
+            else:
+                res = load_signed_record_from_bytes(r.content, self.pinned_keys, last_seen_serial=last_seen_serial)
+        except Exception:
+            res = {"record": None, "reason": REF_VERIFY_PUBLISHED_RECORD_INVALID}
+        if res.get("record") is not None:
+            self._cache = (time.monotonic(), res)      # a failure is not cached: the next check asks again
+        return res
+
+
 class ServerState:
     """The executor's out-of-band trust material (issuer keys, the policy record,
     target id, the principal it serves) as a Consumer, and the list of tool
@@ -357,6 +413,13 @@ class ServerState:
         self.upstream = upstream
         self.issuer_client = issuer_client
         self.evidence: Optional[EvidenceLog] = EvidenceLog(audit_log) if audit_log else None
+        # The gate's own folder (config, keys, evidence, snapshots, replay
+        # claims) is never a target: a call whose path arguments reach into
+        # it is refused before any receipt is asked for.
+        self.gate_dir: Optional[str] = None
+        if audit_log:
+            from gargoyle.globs import normalize_path
+            self.gate_dir = normalize_path(str(Path(audit_log).resolve().parent)).rstrip("/")
         if replay_cache is None and audit_log:
             # Single use has to outlive this process: the claims sit in a
             # SQLite file beside the evidence log (audit.replay.sqlite), so a
@@ -364,11 +427,16 @@ class ServerState:
             # receipt that was already honored (second review, finding 4).
             replay_cache = SqliteReplayCache(str(Path(audit_log).with_name(Path(audit_log).stem + ".replay.sqlite")))
         self.consumer: Optional[Consumer] = None
+        self.record_follower: Optional[RecordFollower] = None
         if config is not None and valid_principal(config.get("principal")):
+            if config.get("record_url"):
+                self.record_follower = RecordFollower(config["record_url"], config["pinned_public_keys"],
+                                                      http=getattr(issuer_client, "_http", None))
             self.consumer = Consumer(
                 target_id=config["target_id"],
                 pinned_public_keys=config["pinned_public_keys"],
-                record=config["record"],
+                record=None if self.record_follower is not None else config["record"],
+                record_source=self.record_follower,
                 replay_cache=replay_cache,
                 approver_public_keys=config.get("approver_public_keys"),
                 approver_key_source=(issuer_client.approver_keys if issuer_client is not None else None),
@@ -410,6 +478,8 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     envelope = meta.get(ENVELOPE_META_KEY)
     grant = meta.get(GRANT_META_KEY)
     self_issued = False
+    if state.gate_dir is not None and _touches_gate_files(args, state.gate_dir):
+        return refused(REF_TARGET_GATE_FILES)
 
     if envelope is None and state.issuer_client is not None:
         # Self-issue: ask the issuing service, and wait for the human if it
@@ -432,8 +502,14 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
             # A scoped grant the human already signed may cover this call;
             # otherwise wait for a card of its own.
             if release is None:
-                waited = state.issuer_client.wait_for_grant(str(envelope.get("approval_request_id")))
+                arid = str(envelope.get("approval_request_id"))
+                waited = state.issuer_client.wait_for_grant(arid)
                 if waited["grant"] is None:
+                    if waited["reason"] == REF_TARGET_APPROVAL_TIMEOUT:
+                        # Nobody is waiting for this release any more: take
+                        # the card down, or an approval minutes later would
+                        # read as a change that happened.
+                        state.issuer_client.decline(arid)
                     return refused(waited["reason"], envelope)
                 grant = waited["grant"]
             else:
@@ -454,6 +530,14 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     else:
         verdict = state.consumer.check(envelope, call_for(name, args, state.config["principal"], live_state),
                                        grant=grant)
+    if (not verdict.honored and verdict.reason == REF_VERIFY_REASSERT_RE_EVALUATE_REQUIRED
+            and state.record_follower is not None):
+        # The receipt names a pin the cached record does not: the rules may
+        # have just changed on the issuer. Ask once more before refusing.
+        state.record_follower.forget()
+        call = call_for(name, args, state.config["principal"], live_state)
+        verdict = (state.consumer.check(envelope, call, plan_release=grant) if is_plan_release(grant)
+                   else state.consumer.check(envelope, call, grant=grant))
     if not verdict.honored:
         return refused(verdict.reason, envelope)
     if is_plan_release(grant):
@@ -477,6 +561,38 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
             "self_issued": self_issued, "ref": gate_ref["ref"]}
 
 
+_GATE_FILE_GLOBS = ("*.env", "*.json", "*.jsonl", "*.jsonl.lock", "*.sqlite", "*.sqlite-*", "snapshots")
+
+
+def _touches_gate_files(args: Any, gate_dir: str) -> bool:
+    """Does any path-like string argument (at the top level or in a list)
+    name the gate's own folder, one of its files (env, json, the evidence
+    log and its lock, the replay claims) or anything under its snapshots?
+    Deeper subfolders are left alone: a deployment folder may hold the
+    project it serves."""
+    import fnmatch
+    from gargoyle.globs import is_pathlike, normalize_path
+    values = []
+    if isinstance(args, dict):
+        for v in args.values():
+            if isinstance(v, str):
+                values.append(v)
+            elif isinstance(v, list):
+                values.extend(x for x in v if isinstance(x, str))
+    for v in values:
+        if not is_pathlike(v):
+            continue
+        n = normalize_path(v)
+        if n == gate_dir:
+            return True
+        if n.startswith(gate_dir + "/"):
+            first = n[len(gate_dir) + 1:].split("/")[0]
+            direct = "/" not in n[len(gate_dir) + 1:]
+            if first == "snapshots" or (direct and any(fnmatch.fnmatchcase(first, g) for g in _GATE_FILE_GLOBS)):
+                return True
+    return False
+
+
 def _plan_release_for(state: ServerState, tool: str, args: Any) -> Optional[Dict[str, Any]]:
     """The release record for the first active plan with an unconsumed step
     matching this call, or None."""
@@ -745,8 +861,10 @@ def config_from_env() -> Optional[Dict[str, Any]]:
     GARGOYLE_MCP_TARGET_ID is the identity receipts bind to;
     GARGOYLE_MCP_PRINCIPAL is the client this server serves (see the module
     docstring); the published record (the live policy pin, {policy_id,
-    policy_sha256}) is read from GARGOYLE_MCP_RECORD_PATH. All five are
-    required; there is no default record. GARGOYLE_MCP_APPROVER_KEY_ID and
+    policy_sha256}) is read from GARGOYLE_MCP_RECORD_PATH, or followed live
+    from GARGOYLE_MCP_RECORD_URL (the issuer's signed record; a rule change
+    then needs no file copy). One of the two is required with the other
+    four settings; there is no default record. GARGOYLE_MCP_APPROVER_KEY_ID and
     GARGOYLE_MCP_APPROVER_PUBLIC_KEY_HEX, both or neither, pin the approver
     keys whose grants release flagged receipts (comma-separated lists for
     several)."""
@@ -757,7 +875,8 @@ def config_from_env() -> Optional[Dict[str, Any]]:
     target_id = os.environ.get(ENV_TARGET_ID)
     principal = os.environ.get(ENV_PRINCIPAL)
     record_path = os.environ.get(ENV_RECORD_PATH)
-    if not (key_id and key_hex and target_id and principal and record_path):
+    record_url = os.environ.get(ENV_RECORD_URL)
+    if not (key_id and key_hex and target_id and principal and (record_path or record_url)):
         return None
     ap_key_id = os.environ.get(ENV_APPROVER_KEY_ID)
     ap_key_hex = os.environ.get(ENV_APPROVER_PUBLIC_KEY_HEX)
@@ -780,15 +899,18 @@ def config_from_env() -> Optional[Dict[str, Any]]:
             if len(ids) != len(hexes) or not all(ids):
                 return None
             approver_keys = {i: Ed25519PublicKey.from_public_bytes(bytes.fromhex(h)) for i, h in zip(ids, hexes)}
-        with open(record_path, "rb") as f:
-            record = json.loads(f.read().decode("utf-8"))
-        if not valid_pin(record):
-            return None
+        record = None
+        if not record_url:
+            with open(record_path, "rb") as f:
+                record = json.loads(f.read().decode("utf-8"))
+            if not valid_pin(record):
+                return None
     except Exception:
         return None
     return {
         "pinned_public_keys": {key_id: public_key},
         "record": record,
+        "record_url": record_url or None,
         "target_id": target_id,
         "principal": principal,
         "approver_public_keys": approver_keys,