gargoyle-receipts 0.12.0.dev0__tar.gz → 0.14.0.dev0__tar.gz

{gargoyle_receipts-0.12.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.14.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.12.0.dev0
+Version: 0.14.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.12.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.14.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
@@ -240,6 +240,17 @@ its initialize handshake, so a fleet with Claude on some desks and ChatGPT
 on others still has one trail that says who, through what, did what. The
 receipt itself stays model-agnostic.
 
+The evidence is the workstation's own statement, and the workstation
+belongs to its user. So the issuer keeps a witness: a signed, hash-chained
+record of every receipt it issued and every grant it accepted, on the
+operator's server. `gargoyle audit --witness` reconciles the two by
+decision id and names what does not agree: a receipt the issuer never
+issued, a held call honored without a grant the issuer saw, a receipt
+issued with no evidence recorded. `--check-tree` hashes the gated folder
+against the evidence's recorded states and names any file changed around
+the gate. On a machine the user administers the gate constrains the
+assistant, not the user; these two checks make the difference visible.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -368,6 +379,9 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_ENTRA_TENANT`, `_CLIENT_ID`, `_SCOPE`, `_TOKEN_CACHE` | instead of a fixed client token: the user's own Entra ID token, written by `gargoyle login` (device code, MSAL cache, silent refresh); the principal is their UPN. No usable token refuses `REF_TARGET_LOGIN_REQUIRED` |
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
+| 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_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
+| issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |
 | `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |

{gargoyle_receipts-0.12.0.dev0 → gargoyle_receipts-0.14.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.12.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.14.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
@@ -202,6 +202,17 @@ its initialize handshake, so a fleet with Claude on some desks and ChatGPT
 on others still has one trail that says who, through what, did what. The
 receipt itself stays model-agnostic.
 
+The evidence is the workstation's own statement, and the workstation
+belongs to its user. So the issuer keeps a witness: a signed, hash-chained
+record of every receipt it issued and every grant it accepted, on the
+operator's server. `gargoyle audit --witness` reconciles the two by
+decision id and names what does not agree: a receipt the issuer never
+issued, a held call honored without a grant the issuer saw, a receipt
+issued with no evidence recorded. `--check-tree` hashes the gated folder
+against the evidence's recorded states and names any file changed around
+the gate. On a machine the user administers the gate constrains the
+assistant, not the user; these two checks make the difference visible.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -330,6 +341,9 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_ENTRA_TENANT`, `_CLIENT_ID`, `_SCOPE`, `_TOKEN_CACHE` | instead of a fixed client token: the user's own Entra ID token, written by `gargoyle login` (device code, MSAL cache, silent refresh); the principal is their UPN. No usable token refuses `REF_TARGET_LOGIN_REQUIRED` |
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
+| 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_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
+| issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |
 | `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |

{gargoyle_receipts-0.12.0.dev0 → gargoyle_receipts-0.14.0.dev0}/gargoyle/cli.py

@@ -26,6 +26,8 @@ policy engine, a container runtime, or any client changes.
                       approver's machine); with --approvers N also approver-2.env ...
     approver-web.json the same key and token in the form the browser approval
                       console loads (private; same machine as approver.env)
+    gargoyle-issuer.service, apache-gargoyle.conf
+                      a systemd unit and an Apache virtual host for the issuer
     mcp-config.json   the server entry to paste into the MCP client
     public-keys.json  issuer, approver and executor public keys, for audits
 
@@ -147,6 +149,33 @@ def cmd_init(args) -> int:
         "issuer": {"issuer-1": issuer_pub}, "approver": {a[0]: a[3] for a in approvers},
         "executor": {"executor-1": executor_pub}, "identity_provider": {"idp-1": idp_pub},
     }, indent=2) + "\n")
+    _write(out / "gargoyle-issuer.service", """[Unit]
+Description=Gargoyle issuing service
+After=network-online.target
+
+[Service]
+User=gargoyle
+WorkingDirectory=%(out)s
+ExecStart=%(python)s -m gargoyle.cli issuer --out %(out)s --host 127.0.0.1 --port %(port)d
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+""" % {"out": str(out), "python": sys.executable, "port": args.port})
+    _write(out / "apache-gargoyle.conf", """# Apache in front of the issuer: TLS from a trusted CA, one virtual host.
+<VirtualHost *:443>
+    ServerName %(host)s
+    SSLEngine on
+    SSLCertificateFile    /etc/ssl/certs/gargoyle.crt
+    SSLCertificateKeyFile /etc/ssl/private/gargoyle.key
+    ProxyPreserveHost On
+    ProxyPass        / http://127.0.0.1:%(port)d/
+    ProxyPassReverse / http://127.0.0.1:%(port)d/
+    ErrorLog  ${APACHE_LOG_DIR}/gargoyle-error.log
+    CustomLog ${APACHE_LOG_DIR}/gargoyle-access.log combined
+</VirtualHost>
+""" % {"host": (args.issuer_url or "gargoyle.example").replace("https://", "").replace("http://", "").split("/")[0].split(":")[0], "port": args.port})
     upstream = (["npx", "-y", "@modelcontextprotocol/server-filesystem", allowed] if args.upstream == "npx-filesystem"
                 else [client_python, "-m", "gargoyle.fs_server", allowed])
     _write(out / "mcp-config.json", json.dumps({"mcpServers": {"filesystem-gargoyle": {
@@ -260,6 +289,9 @@ def cmd_issuer(args) -> int:
     out = Path(args.out).resolve()
     os.environ.update(_read_env(out / "issuer.env"))
     os.environ.setdefault("GARGOYLE_APPROVERS_PATH", str(out / "approvers.json"))   # enrolled approvers live beside the keys
+    os.environ.setdefault("GARGOYLE_HOLDS_PATH", str(out / "holds.sqlite"))          # holds, grants, declines, plans survive restarts
+    os.environ.setdefault("GARGOYLE_WITNESS_PATH", str(out / "witness.jsonl"))       # the issuer's signed record, for reconciliation
+    os.environ.setdefault("GARGOYLE_LOG_JSON", "1")
     app = app_from_env()
     # The middleware reads the policy pin from a file; write it next to the
     # config so the client-side entry finds it at the configured path.
@@ -327,7 +359,29 @@ def cmd_audit(args) -> int:
         failed = sum(1 for r in v["entries"] if not r["accepted"])
         print("%d entries (%d honored, %d refused), %d failed; chain %s; tail %s"
               % (v["count"], v["honored"], v["refused"], failed, v["reason"], v["tail_sha256"][:16]))
-        return 0 if v["accepted"] else 1
+        rc = 0 if v["accepted"] else 1
+        entries = read_log(args.log)
+        if args.witness:
+            # The issuer's signed record: the client's evidence must agree with it.
+            from gargoyle.reconcile import reconcile
+            from gargoyle.witness import read_witness, verify_witness
+            w = verify_witness(read_witness(args.witness), issuer_public_keys=trust["issuer_public_keys"])
+            print("witness: %d entries, %s, tail %s" % (w["count"], w["reason"], w["tail_sha256"][:16]))
+            principal = next((e.get("principal") for e in entries if isinstance(e, dict) and e.get("principal")), None)
+            r = reconcile(entries, read_witness(args.witness), principal=principal)
+            for f in r["findings"]:
+                print("  FINDING %-22s %s" % (f["finding"], " ".join("%s=%s" % (k, str(v)[:40]) for k, v in f.items() if k != "finding")))
+            print("reconciled: %d issued by the issuer, %d in evidence, %d finding(s)" % (r["issued"], r["evidence_with_receipt"], len(r["findings"])))
+            rc = rc or (0 if (w["accepted"] and r["accepted"]) else 1)
+        if args.check_tree:
+            # Every file the gate wrote must still be as the gate left it.
+            from gargoyle.reconcile import check_tree
+            t = check_tree(entries, args.check_tree)
+            for f in t["findings"]:
+                print("  FINDING %-22s %s%s" % (f["finding"], f["path"], " (missing)" if f.get("missing") else ""))
+            print("tree: %d gated file(s) checked, %d untouched by the gate, %d changed outside it" % (t["checked"], t["untouched"], len(t["findings"])))
+            rc = rc or (0 if t["accepted"] else 1)
+        return rc
     receipt, execution = json.load(open(args.receipt)), json.load(open(args.execution))
     grant = json.load(open(args.grant)) if args.grant else None
     result = verify_chain(receipt, execution, grant=grant, **trust)
@@ -393,6 +447,8 @@ def main(argv=None) -> int:
     p = sub.add_parser("audit", help="verify a receipt chain offline, or a whole evidence log")
     p.add_argument("receipt", nargs="?"); p.add_argument("execution", nargs="?"); p.add_argument("grant", nargs="?")
     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("--out", default="gargoyle-deploy")
     p.set_defaults(fn=cmd_audit)
     args = parser.parse_args(argv)

{gargoyle_receipts-0.12.0.dev0 → gargoyle_receipts-0.14.0.dev0}/gargoyle/evidence.py

@@ -48,9 +48,9 @@ from gargoyle.envelope import args_sha256, canonical_json, canonical_json_legacy
 from gargoyle.execution import verify_chain
 from gargoyle.verifier import verify_provenance
 
-EVIDENCE_VERSION = "gargoyle-evidence/3"          # version 3 adds `client`; hashes over RFC 8785 canonical JSON
+EVIDENCE_VERSION = "gargoyle-evidence/4"          # 3 added `client`, 4 adds `ref`; hashes over RFC 8785 canonical JSON
 EVIDENCE_VERSIONS = {"gargoyle-evidence/1": canonical_json_legacy, "gargoyle-evidence/2": canonical_json,
-                     EVIDENCE_VERSION: canonical_json}
+                     "gargoyle-evidence/3": canonical_json, EVIDENCE_VERSION: canonical_json}
 GENESIS = "0" * 64
 
 HONORED = "honored"
@@ -71,6 +71,11 @@ _FIELDS = ("evidence_version", "seq", "prev_sha256", "at", "kind", "tool", "args
 # receipt stays model-agnostic: this is evidence about the session, not a
 # bound field of the decision.
 _FIELDS_V3 = _FIELDS + ("client",)
+# Version 4 adds `ref`: what the adapter examined for a state-bound call (a
+# file path, "mailRule:<id>"), or null. With it a folder can be checked
+# against the evidence without any plaintext (gargoyle.reconcile.check_tree).
+_FIELDS_V4 = _FIELDS_V3 + ("ref",)
+_FIELDS_BY_VERSION = {"gargoyle-evidence/3": _FIELDS_V3, "gargoyle-evidence/4": _FIELDS_V4}
 
 
 def entry_sha256(entry: Dict[str, Any]) -> str:
@@ -84,11 +89,13 @@ def entry_sha256(entry: Dict[str, Any]) -> str:
 
 def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any, principal: str,
                 reason: str, receipt: Any = None, grant: Any = None, execution: Any = None,
-                at: Optional[datetime] = None, client: Optional[str] = None) -> Dict[str, Any]:
+                at: Optional[datetime] = None, client: Optional[str] = None, ref: Optional[str] = None) -> Dict[str, Any]:
     if kind not in (HONORED, REFUSED):
         raise ValueError("kind must be honored or refused")
     if client is not None and not isinstance(client, str):
         raise ValueError("client must be a string or None")
+    if ref is not None and not isinstance(ref, str):
+        raise ValueError("ref must be a string or None")
     entry = {
         "evidence_version": EVIDENCE_VERSION,
         "seq": seq,
@@ -103,6 +110,7 @@ def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any,
         "grant": grant,
         "execution": execution,
         "client": client,
+        "ref": ref,
     }
     entry["entry_sha256"] = entry_sha256(entry)
     return entry
@@ -131,14 +139,14 @@ class EvidenceLog:
 
     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) -> Dict[str, Any]:
+               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)
+                            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"]
@@ -146,10 +154,11 @@ class EvidenceLog:
 
 
 def _well_formed(entry: Any) -> bool:
-    expected = _FIELDS_V3 if isinstance(entry, dict) and entry.get("evidence_version") == EVIDENCE_VERSION else _FIELDS
+    expected = _FIELDS_BY_VERSION.get(entry.get("evidence_version"), _FIELDS) if isinstance(entry, dict) else _FIELDS
     return (isinstance(entry, dict) and set(entry) == set(expected)
             and entry["evidence_version"] in EVIDENCE_VERSIONS
             and (entry.get("client") is None or isinstance(entry.get("client"), str))
+            and (entry.get("ref") is None or isinstance(entry.get("ref"), str))
             and isinstance(entry["seq"], int) and entry["seq"] >= 1
             and isinstance(entry["prev_sha256"], str) and len(entry["prev_sha256"]) == 64
             and isinstance(entry["at"], str) and entry["kind"] in (HONORED, REFUSED)
@@ -192,7 +201,7 @@ def verify_log(
             rc = rc if isinstance(rc, dict) else {}
             report.append({"seq": None, "kind": None, "tool": rc.get("tool"), "principal": rc.get("principal"),
                            "accepted": False, "reason": REF_EVIDENCE_UNCHAINED if legacy else REF_EVIDENCE_MALFORMED,
-                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None})
+                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None, "ref": None})
             all_ok = False
             continue
         e = raw
@@ -230,7 +239,7 @@ def verify_log(
                  if ex.get("pre_state_sha256") or ex.get("post_state_sha256") else None)
         report.append({"seq": e["seq"], "kind": e["kind"], "tool": e["tool"], "principal": e["principal"],
                        "accepted": ok, "reason": reason, "verdict": e["reason"], "released_by": released_by,
-                       "state": state, "client": e.get("client"), "plan": plan_ref})
+                       "state": state, "client": e.get("client"), "plan": plan_ref, "ref": e.get("ref")})
         all_ok = all_ok and ok
         # The chain continues from what the file says, so one bad entry is
         # reported once rather than cascading into every later one.

gargoyle_receipts-0.14.0.dev0/gargoyle/holdstore.py

@@ -0,0 +1,116 @@
+"""Persistent issuer state: holds, grants, declines and plans survive a restart.
+
+The issuing service keeps little state, but what it keeps is what a human
+is in the middle of acting on. In a lab the service was restarted a dozen
+times in two days and each restart dropped the holds in flight; the
+middleware then reported a timeout and the assistant retried. A client's
+approver would see a card that did nothing. This module backs each of the
+service's maps with a SQLite table (standard library, one file, one
+process), so a restart changes nothing a person can see. With no path the
+store is in memory, which is what the tests use.
+
+Dict semantics are kept on purpose: the service code reads as before,
+and a value is written back on assignment, never by mutating what a read
+returned.
+"""
+
+import json
+import sqlite3
+import threading
+from collections.abc import MutableMapping, MutableSet
+from typing import Any, Iterator, Optional
+
+ENV_HOLDS_PATH = "GARGOYLE_HOLDS_PATH"
+
+
+class HoldStore:
+    def __init__(self, path: Optional[str] = None) -> None:
+        self.path = path or ":memory:"
+        self._db = sqlite3.connect(self.path, check_same_thread=False, isolation_level=None)
+        self._lock = threading.RLock()
+        with self._lock:
+            self._db.execute("PRAGMA journal_mode=WAL") if self.path != ":memory:" else None
+            self._db.execute("CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, k TEXT NOT NULL, v TEXT NOT NULL, PRIMARY KEY (ns, k))")
+
+    def dict(self, ns: str) -> "PersistentDict":
+        return PersistentDict(self, ns)
+
+    def set(self, ns: str) -> "PersistentSet":
+        return PersistentSet(self, ns)
+
+    # ---- primitives ----
+    def _get(self, ns: str, k: str) -> Any:
+        with self._lock:
+            row = self._db.execute("SELECT v FROM kv WHERE ns=? AND k=?", (ns, k)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def _has(self, ns: str, k: str) -> bool:
+        with self._lock:
+            return self._db.execute("SELECT 1 FROM kv WHERE ns=? AND k=?", (ns, k)).fetchone() is not None
+
+    def _put(self, ns: str, k: str, v: Any) -> None:
+        with self._lock:
+            self._db.execute("INSERT OR REPLACE INTO kv (ns, k, v) VALUES (?, ?, ?)", (ns, k, json.dumps(v, sort_keys=True)))
+
+    def _delete(self, ns: str, k: str) -> bool:
+        with self._lock:
+            cur = self._db.execute("DELETE FROM kv WHERE ns=? AND k=?", (ns, k))
+            return cur.rowcount > 0
+
+    def _keys(self, ns: str) -> list:
+        with self._lock:
+            return [r[0] for r in self._db.execute("SELECT k FROM kv WHERE ns=? ORDER BY rowid", (ns,)).fetchall()]
+
+    def _count(self, ns: str) -> int:
+        with self._lock:
+            return self._db.execute("SELECT COUNT(*) FROM kv WHERE ns=?", (ns,)).fetchone()[0]
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+
+class PersistentDict(MutableMapping):
+    def __init__(self, store: HoldStore, ns: str) -> None:
+        self._s, self._ns = store, ns
+
+    def __getitem__(self, k: str) -> Any:
+        if not self._s._has(self._ns, k):
+            raise KeyError(k)
+        return self._s._get(self._ns, k)
+
+    def __setitem__(self, k: str, v: Any) -> None:
+        self._s._put(self._ns, k, v)
+
+    def __delitem__(self, k: str) -> None:
+        if not self._s._delete(self._ns, k):
+            raise KeyError(k)
+
+    def __contains__(self, k: object) -> bool:
+        return isinstance(k, str) and self._s._has(self._ns, k)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._s._keys(self._ns))
+
+    def __len__(self) -> int:
+        return self._s._count(self._ns)
+
+
+class PersistentSet(MutableSet):
+    def __init__(self, store: HoldStore, ns: str) -> None:
+        self._s, self._ns = store, ns
+
+    def __contains__(self, k: object) -> bool:
+        return isinstance(k, str) and self._s._has(self._ns, k)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._s._keys(self._ns))
+
+    def __len__(self) -> int:
+        return self._s._count(self._ns)
+
+    def add(self, k: str) -> None:
+        self._s._put(self._ns, k, True)
+
+    def discard(self, k: str) -> None:
+        self._s._delete(self._ns, k)

{gargoyle_receipts-0.12.0.dev0 → gargoyle_receipts-0.14.0.dev0}/gargoyle/issuer_service.py

@@ -40,6 +40,7 @@ it again when the call runs. The pending set is in memory: one instance.
 
 import json
 import os
+import sys
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional
@@ -53,6 +54,8 @@ from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_
                                verify_grant)
 from gargoyle.envelope import approval_terms
 from gargoyle.state import state_sha256, valid_description
+from gargoyle.holdstore import ENV_HOLDS_PATH, HoldStore
+from gargoyle.witness import WitnessLog
 from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF_PLAN_STEP_REFUSED, build_plan,
                             sign_plan, valid_step)
 from gargoyle.notify import notifier_from_env
@@ -100,17 +103,43 @@ def build_issuer_app(
     approver_role: str = DEFAULT_APPROVER_ROLE,
     approver_groups: Optional[list] = None,
     console_entra: Optional[Dict[str, str]] = None,
+    hold_store: Optional[HoldStore] = None,
+    log_events: Optional[Callable[[Dict[str, Any]], None]] = None,
+    witness: Optional[WitnessLog] = None,
 ) -> FastAPI:
     """`on_hold(envelope, args)` is called once for every new hold (gargoyle.notify
     posts it to a webhook); it is notice, not admission, and its failure
     never affects the hold."""
     app = FastAPI(title="Gargoyle issuing service")
-    app.state.pending: Dict[str, Dict[str, Any]] = {}     # approval_request_id -> envelope
-    app.state.pending_args: Dict[str, Any] = {}           # approval_request_id -> the call's arguments
-    app.state.pending_state: Dict[str, Any] = {}          # approval_request_id -> the target's state when held
-    app.state.grants: Dict[str, Dict[str, Any]] = {}      # approval_request_id -> grant
-    app.state.declined: set = set()                       # approval_request_ids a human refused
-    app.state.pending_plans: Dict[str, Dict[str, Any]] = {}   # approval_request_id -> signed plan (gargoyle.plans)
+    # Everything a human may be in the middle of acting on lives in the hold
+    # store (gargoyle.holdstore): SQLite on disk in a deployment, memory in tests.
+    store = hold_store if hold_store is not None else HoldStore(None)
+    app.state.store = store
+    app.state.pending = store.dict("pending")             # approval_request_id -> envelope
+    app.state.pending_args = store.dict("pending_args")   # approval_request_id -> the call's arguments
+    app.state.pending_state = store.dict("pending_state") # approval_request_id -> the target's state when held
+    app.state.grants = store.dict("grants")               # approval_request_id -> [grant, ...]
+    app.state.declined = store.set("declined")            # approval_request_ids a human refused
+    app.state.pending_plans = store.dict("pending_plans") # approval_request_id -> signed plan (gargoyle.plans)
+    app.state.started_at = now().isoformat()
+
+    def event(kind: str, **fields: Any) -> None:
+        """One structured line per decision the service makes, for the
+        operator's log, and one signed entry in the witness log (gargoyle.witness),
+        the independent record the client's evidence is reconciled against.
+        Neither is the admission path."""
+        if log_events is not None:
+            try:
+                log_events({"event": kind, "at": now().isoformat(), **fields})
+            except Exception:
+                pass
+        if witness is not None:
+            try:
+                witness.record(kind, **fields)
+            except Exception as exc:
+                import sys as _sys
+                _sys.stderr.write("gargoyle: witness log unwritable: %s\n" % exc)
+    app.state.witness = witness
     registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
     static_approvers = dict(approver_public_keys or {})
 
@@ -166,6 +195,7 @@ def build_issuer_app(
         result = issue(policy, body["target_url"], interaction, signing_key=signing_key, key_id=key_id,
                        ttl_seconds=ttl_seconds, now=now())
         if result.envelope is None:
+            event("refused", principal=who["principal"], tool=body["tool"], reason=result.decision.reason)
             return {"issued": False, "reason": result.decision.reason}
         covered = False
         plan_id = body.get("plan_id")
@@ -180,6 +210,9 @@ def build_issuer_app(
                 if plan["plan_id"] == plan_id and _complete(arid_p) and match_step(plan, body["tool"], body["args"]) is not None:
                     covered = True
                     break
+        event("issued", principal=who["principal"], tool=body["tool"], held=bool(result.envelope["requires_approval"]),
+              covered=covered, decision_id=result.envelope.get("decision_id"), decision_sha256=result.envelope["decision_sha256"],
+              approval_request_id=result.envelope.get("approval_request_id"), args_sha256=result.envelope["request_context"]["args_sha256"])
         if result.envelope["requires_approval"] and not covered:
             arid = result.envelope["approval_request_id"]
             app.state.pending[arid] = result.envelope
@@ -245,6 +278,7 @@ def build_issuer_app(
                                     approval=approval), signing_key, key_id)
         if held:
             app.state.pending_plans[plan["approval_request_id"]] = plan
+        event("plan", principal=who["principal"], steps=len(norm), held=held, plan_id=plan["plan_id"])
         return {"issued": True, "plan": plan, "held": held}
 
     def _plan_terms(plan):
@@ -306,12 +340,15 @@ def build_issuer_app(
             return {"accepted": False, "reason": g["reason"]}
         # The receipt's (or plan's) own terms: distinct approvers, from the named set if any.
         terms = approval_terms(env) if env else _plan_terms(plan)
-        have = app.state.grants.setdefault(arid, [])
+        have = list(app.state.grants.get(arid, []))
         if any(h["approver_key_id"] == grant["approver_key_id"] for h in have):
             return {"accepted": False, "reason": REF_APPROVAL_DUPLICATE_APPROVER}
         if terms["approvers"] is not None and grant["approver_key_id"] not in terms["approvers"]:
             return {"accepted": False, "reason": REF_APPROVAL_APPROVER_NOT_ELIGIBLE}
         have.append(grant)
+        app.state.grants[arid] = have                      # written back: the store persists on assignment
+        event("granted", approval_request_id=arid, approver=grant["approver_key_id"], collected=len(have), required=terms["required"],
+              hold_kind="plan" if plan else "receipt")
         return {"accepted": True, "reason": g["reason"], "collected": len(have), "required": terms["required"],
                 "complete": len(have) >= terms["required"]}
 
@@ -319,7 +356,7 @@ def build_issuer_app(
     async def decline(request: Request, authorization: Optional[str] = Header(default=None)):
         """A human's refusal: the hold is dropped, a waiting middleware learns
         at once. No signature is needed to say no; nothing can run on it."""
-        authenticate(authorization)
+        who = authenticate(authorization)
         try:
             body = await request.json()
         except Exception:
@@ -333,6 +370,7 @@ def build_issuer_app(
         app.state.pending_state.pop(arid, None)
         app.state.grants.pop(arid, None)
         app.state.declined.add(arid)
+        event("declined", approval_request_id=arid, by=who["principal"])
         return {"declined": True, "reason": None}
 
     @app.get("/grants/{approval_request_id}")
@@ -369,6 +407,7 @@ def build_issuer_app(
         if not isinstance(body, dict) or not valid_public_key_hex(body.get("public_key_hex")):
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         result = registry.enroll(who["principal"], body["public_key_hex"], now=now())
+        event("enrolled", approver=who["principal"], replaced=result["replaced"])
         return {"enrolled": True, "key_id": who["principal"], "replaced": result["replaced"]}
 
     @app.get("/me")
@@ -381,6 +420,21 @@ def build_issuer_app(
         return {"principal": upn, "may_approve": may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers,
                 "enrolled_public_key_hex": registry.public_hex().get(upn)}
 
+    @app.get("/witness")
+    async def witness_entries(authorization: Optional[str] = Header(default=None)):
+        """The issuer's signed witness log, for reconciliation with a client's evidence."""
+        authenticate(authorization)
+        return {"entries": list(witness.entries) if witness is not None else []}
+
+    @app.get("/health")
+    async def health():
+        """Public, for a monitor: the service is up, which policy it runs,
+        how much is waiting, and since when. No secrets."""
+        return {"ok": True, "policy": policy.pin(), "issuer_key_id": key_id,
+                "pending_receipts": len(app.state.pending), "pending_plans": len(app.state.pending_plans),
+                "enrolled_approvers": len(registry.public_hex()), "static_approvers": len(static_approvers),
+                "entra": bool(console_entra), "persistent": store.path != ":memory:", "started_at": app.state.started_at}
+
     @app.get("/approve-config")
     async def approve_config():
         """Public: how the console signs in. `entra` is null when the site
@@ -455,6 +509,10 @@ def app_from_env() -> FastAPI:
         audience=os.environ.get(ENV_AUDIENCE) or None,
         ttl_seconds=int(os.environ.get(ENV_RECEIPT_TTL, DEFAULT_TTL_SECONDS)),
         on_hold=notifier_from_env(os.environ),
+        hold_store=HoldStore(os.environ.get(ENV_HOLDS_PATH) or None),
+        witness=(WitnessLog(os.environ["GARGOYLE_WITNESS_PATH"], Ed25519PrivateKey.from_private_bytes(bytes.fromhex(required[ENV_ISSUER_KEY_HEX])),
+                            required[ENV_ISSUER_KEY_ID]) if os.environ.get("GARGOYLE_WITNESS_PATH") else None),
+        log_events=(lambda e: sys.stderr.write(json.dumps(e, sort_keys=True) + "\n")) if os.environ.get("GARGOYLE_LOG_JSON") else None,
         approver_registry=ApproverRegistry(os.environ.get(ENV_APPROVERS_PATH)),
         approver_role=os.environ.get(ENV_APPROVER_ROLE, DEFAULT_APPROVER_ROLE),
         approver_groups=[g.strip() for g in os.environ.get(ENV_APPROVER_GROUPS, "").split(",") if g.strip()] or None,

{gargoyle_receipts-0.12.0.dev0 → gargoyle_receipts-0.14.0.dev0}/gargoyle/mcp_server.py

@@ -364,10 +364,12 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     """{"executed", "reason", "envelope", "grant", "self_issued"}: the
     receipt and grant that were honored, whether the client brought them or
     this server obtained them."""
+    gate_ref: Dict[str, Any] = {"ref": None}
+
     def refused(reason, envelope=None):
         # A refusal keeps the receipt when there was one (a hold the human
         # declined or let lapse), so the evidence log can show what was asked.
-        return {"executed": False, "reason": reason, "envelope": envelope, "grant": None, "self_issued": False}
+        return {"executed": False, "reason": reason, "envelope": envelope, "grant": None, "self_issued": False, "ref": gate_ref["ref"]}
     if state.consumer is None:
         return refused(REF_TARGET_NOT_CONFIGURED)
 
@@ -385,6 +387,8 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         # target's current state goes with the request (gargoyle.state), so
         # a hold is approved against it and bound to it.
         probed = state.adapter.probe(name, args) if state.adapter is not None else None
+        if probed is not None:
+            gate_ref["ref"] = probed[0].get("ref")
         # An approved plan may already cover this call; say so, and the
         # issuer opens no hold for it.
         release = _plan_release_for(state, name, args)
@@ -435,9 +439,11 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         except Exception as exc:
             sys.stderr.write("gargoyle: snapshot failed: %s\n" % exc)
 
+    if now_probe is not None:
+        gate_ref["ref"] = now_probe[0].get("ref")
     state.executed.append({"tool": name, "args": args})  # THE side effect
     return {"executed": True, "reason": verdict.reason, "envelope": envelope, "grant": grant,
-            "self_issued": self_issued}
+            "self_issued": self_issued, "ref": gate_ref["ref"]}
 
 
 def _plan_release_for(state: ServerState, tool: str, args: Any) -> Optional[Dict[str, Any]]:
@@ -524,7 +530,7 @@ def _record(state: ServerState, kind: str, gate: Dict[str, Any], params: Dict[st
     try:
         state.evidence.append(kind, str(params.get("name")), params.get("arguments", {}), principal,
                               gate["reason"], receipt=gate["envelope"], grant=gate["grant"], execution=execution,
-                              client=state.client)
+                              client=state.client, ref=gate.get("ref"))
     except (OSError, ValueError) as exc:
         sys.stderr.write("gargoyle: evidence log unwritable: %s\n" % exc)