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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.17.0.dev0
+Version: 0.19.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.19.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,8 @@ 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 emilia --log audit.jsonl           # export approved calls as EMILIA Trust Receipts (docs/interop-emilia.md)
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
@@ -397,7 +399,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 +461,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.19.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.19.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,8 @@ 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 emilia --log audit.jsonl           # export approved calls as EMILIA Trust Receipts (docs/interop-emilia.md)
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
@@ -359,7 +361,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 +423,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.19.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,
@@ -413,22 +490,58 @@ def _audit_summary(report, raw) -> None:
     print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))
 
 
+def _trust_hex(out: Path) -> "tuple[Dict[str, Any], Dict[str, Any]]":
+    """public-keys.json plus, when present, every key each enrolled approver
+    ever held (approvers.json, current first): grants signed under a key
+    since replaced in the browser or revoked still have to verify. Only the
+    live service and middleware are limited to the current key. Copy the
+    issuer's file beside the evidence first. Returns (keys, approvers_hex)."""
+    keys = json.loads((out / "public-keys.json").read_text())
+    approvers: Dict[str, Any] = dict(keys["approver"])
+    enrolled = out / "approvers.json"          # approvers who enrolled through Entra, by UPN
+    if enrolled.exists():
+        from gargoyle.approvers import ApproverRegistry
+        approvers.update(ApproverRegistry(str(enrolled)).audit_keys_hex())
+    return keys, approvers
+
+
+def cmd_emilia(args) -> int:
+    """Export an evidence log's honored, approved calls as EMILIA Trust
+    Receipts (docs/interop-emilia.md): one file in the format EMILIA's
+    conformance runners read, every receipt carrying the signoff the
+    approver's console made, the whole set under one Merkle checkpoint
+    signed by this gate's executor key."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    from gargoyle.emilia import trust_receipts_from_entries, verification_for
+    from gargoyle.evidence import read_log
+    out = Path(args.out).resolve()
+    keys, approvers = _trust_hex(out)
+    env = _read_env(Path(args.env or (out / "middleware.env")))
+    if "GARGOYLE_MCP_EXECUTOR_KEY_HEX" not in env:
+        print("%s has no GARGOYLE_MCP_EXECUTOR_KEY_HEX; point --env at this gate's middleware.env" % (args.env or out / "middleware.env"), file=sys.stderr)
+        return 2
+    executor = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(env["GARGOYLE_MCP_EXECUTOR_KEY_HEX"]))
+    log_key_id = env.get("GARGOYLE_MCP_EXECUTOR_KEY_ID", "executor-1")
+    result = trust_receipts_from_entries(read_log(args.log), log_signing_key=executor, log_key_id=log_key_id)
+    vectors = [{"id": r["receipt_id"], "expect": {"valid": True}, "trust_receipt": r,
+                "verification": verification_for(r, approvers, executor.public_key())} for r in result["receipts"]]
+    missing = [v["id"] for v in vectors if len(v["verification"]["approver_keys"]) < len(v["trust_receipt"]["signoffs"])]
+    doc = {"suite": "GARGOYLE EP-TRUST-RECEIPT-v1 export", "source": "gargoyle-receipts", "log": str(Path(args.log).resolve()),
+           "exported_at": datetime.now(timezone.utc).isoformat(), "count": len(vectors), "vectors": vectors}
+    _write(Path(args.write), json.dumps(doc, indent=1) + "\n")
+    print("%d trust receipts under one checkpoint (tree size %d) -> %s; %d approved calls skipped (no console signoff on every grant)%s"
+          % (len(vectors), len(vectors), args.write, result["skipped"],
+             ("; %d receipts name an approver key not in %s/public-keys.json or approvers.json" % (len(missing), out)) if missing else ""))
+    return 0
+
+
 def cmd_audit(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
     from gargoyle.execution import verify_chain
 
-    keys = json.loads((Path(args.out).resolve() / "public-keys.json").read_text())
+    keys, approvers = _trust_hex(Path(args.out).resolve())
     one = lambda h: Ed25519PublicKey.from_public_bytes(bytes.fromhex(h))
     load = lambda m: {k: ([one(x) for x in v] if isinstance(v, list) else one(v)) for k, v in m.items()}
-    approvers: Dict[str, Any] = dict(keys["approver"])
-    enrolled = Path(args.out).resolve() / "approvers.json"          # approvers who enrolled through Entra, by UPN
-    if enrolled.exists():
-        from gargoyle.approvers import ApproverRegistry
-        # Every key each approver ever held, current first: grants signed
-        # under a key since replaced in the browser or revoked still have to
-        # verify. Only the live service and middleware are limited to the
-        # current key. Copy the issuer's file beside the evidence first.
-        approvers.update(ApproverRegistry(str(enrolled)).audit_keys_hex())
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
                  approver_public_keys=load(approvers))
     if args.log:
@@ -523,7 +636,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")
@@ -572,6 +691,12 @@ def main(argv=None) -> int:
     p.add_argument("--summary", action="store_true", help="after the rows: calls by principal and tool with outcomes, releases, clients")
     p.add_argument("--out", default="gargoyle-deploy")
     p.set_defaults(fn=cmd_audit)
+    p = sub.add_parser("emilia", help="export an evidence log's approved calls as EMILIA Trust Receipts")
+    p.add_argument("--log", required=True, help="the middleware's audit.jsonl")
+    p.add_argument("--write", default="emilia-trust-receipts.json", help="output file, in the format EMILIA's conformance runners read")
+    p.add_argument("--env", help="this gate's middleware.env (executor key signs the checkpoint); default <out>/middleware.env")
+    p.add_argument("--out", default="gargoyle-deploy")
+    p.set_defaults(fn=cmd_emilia)
     args = parser.parse_args(argv)
     return args.fn(args)