gargoyle-receipts 0.8.1.dev0__tar.gz → 0.9.0.dev0__tar.gz

{gargoyle_receipts-0.8.1.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.9.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.8.1.dev0
+Version: 0.9.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.8.1.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.9.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
@@ -289,6 +289,25 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Remote mode
+
+Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
+custom connectors) and Microsoft 365 servers are reached over HTTPS, not
+through a local process. `gargoyle remote` runs the same gate as a
+Streamable HTTP MCP server in front of a stdio command or a remote MCP
+server (`--upstream-url`), so those paths go through it too:
+
+    gargoyle remote-token --out gargoyle-deploy --principal dana@contoso.com --url https://gargoyle.lan:8444
+    gargoyle remote --out gargoyle-deploy --port 8444 --ssl-certfile ... --ssl-keyfile ... -- python -m gargoyle.fs_server /srv/shared
+
+Each person gets a capability URL (`/mcp/<token>`) that names them on
+every receipt; the operator vouches for that mapping, as with an API key,
+because a hosted connector cannot carry the user's own Entra token.
+Treat the URL as a credential. All sessions share one upstream, one replay
+cache, one evidence log and one snapshot store, so single use and undo
+hold across users. Device-bound identity remains the stdio mode's
+property.
+
 ## The shipped consumer
 
 **MCP middleware** (`python -m gargoyle.mcp_server -- <upstream command>`):
@@ -319,6 +338,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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 |
 | `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_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
 

{gargoyle_receipts-0.8.1.dev0 → gargoyle_receipts-0.9.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.8.1.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.9.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
@@ -251,6 +251,25 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Remote mode
+
+Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
+custom connectors) and Microsoft 365 servers are reached over HTTPS, not
+through a local process. `gargoyle remote` runs the same gate as a
+Streamable HTTP MCP server in front of a stdio command or a remote MCP
+server (`--upstream-url`), so those paths go through it too:
+
+    gargoyle remote-token --out gargoyle-deploy --principal dana@contoso.com --url https://gargoyle.lan:8444
+    gargoyle remote --out gargoyle-deploy --port 8444 --ssl-certfile ... --ssl-keyfile ... -- python -m gargoyle.fs_server /srv/shared
+
+Each person gets a capability URL (`/mcp/<token>`) that names them on
+every receipt; the operator vouches for that mapping, as with an API key,
+because a hosted connector cannot carry the user's own Entra token.
+Treat the URL as a credential. All sessions share one upstream, one replay
+cache, one evidence log and one snapshot store, so single use and undo
+hold across users. Device-bound identity remains the stdio mode's
+property.
+
 ## The shipped consumer
 
 **MCP middleware** (`python -m gargoyle.mcp_server -- <upstream command>`):
@@ -281,6 +300,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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 |
 | `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_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
 

{gargoyle_receipts-0.8.1.dev0 → gargoyle_receipts-0.9.0.dev0}/gargoyle/cli.py

@@ -11,6 +11,9 @@ policy engine, a container runtime, or any client changes.
     gargoyle approve [--out DIR] [--watch SECONDS]       sit and approve held calls
     gargoyle login --tenant T --client-id C --scope S   sign this workstation's user in with
                                                         Entra ID; the middleware then acts as them
+    gargoyle remote --out DIR [--upstream-url URL | -- <command>]   the gate as an HTTPS MCP
+                                                        server, for hosted connectors
+    gargoyle remote-token --out DIR --principal UPN     a capability URL for one person
     gargoyle audit <receipt.json> <execution.json> [grant.json]
     gargoyle audit --log audit.jsonl            verify the middleware's evidence log
 
@@ -110,7 +113,7 @@ def cmd_init(args) -> int:
         _write(rules, json.dumps(DEFAULT_RULES, indent=2) + "\n")
     _write(out / "issuer.env", _env_lines({
         "GARGOYLE_ISSUER_KEY_ID": "issuer-1", "GARGOYLE_ISSUER_KEY_HEX": issuer_hex,
-        "GARGOYLE_IDP_KEY_ID": "idp-1", "GARGOYLE_IDP_PUBLIC_KEY_HEX": idp_pub,
+        "GARGOYLE_IDP_KEY_ID": "idp-1", "GARGOYLE_IDP_PUBLIC_KEY_HEX": idp_pub, "GARGOYLE_IDP_KEY_HEX": idp_hex,
         "GARGOYLE_ISSUER_AUDIENCE": "gargoyle-issuer",
         "GARGOYLE_APPROVER_KEY_ID": approver_ids, "GARGOYLE_APPROVER_PUBLIC_KEY_HEX": approver_pubs,
         "GARGOYLE_RULES_PATH": str(rules), "GARGOYLE_RECEIPT_TTL_SECONDS": "600",
@@ -188,6 +191,67 @@ def cmd_login(args) -> int:
     return 0
 
 
+def cmd_remote_token(args) -> int:
+    """Mint one person's capability token for the remote gate: an identity
+    token the issuer trusts for that principal (signed by the pinned IdP key
+    from init), mapped to a random URL segment in remote-tokens.json."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    from gargoyle.remote import TokenMap, mint_identity_token
+    out = Path(args.out).resolve()
+    ienv = _read_env(out / "issuer.env")
+    idp = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(ienv["GARGOYLE_IDP_KEY_HEX"])) if "GARGOYLE_IDP_KEY_HEX" in ienv else None
+    if idp is None:
+        # init keeps the IdP private key only in the approver/client tokens' lineage; derive from the stored seed if present
+        raise SystemExit("issuer.env has no GARGOYLE_IDP_KEY_HEX; run `gargoyle init` from this version first")
+    audience = (ienv.get("GARGOYLE_ISSUER_AUDIENCE") or "gargoyle-issuer").split(",")[0].strip()
+    token = mint_identity_token(args.principal, idp, ienv.get("GARGOYLE_IDP_KEY_ID", "idp-1"), audience, days=args.days)
+    tokens = TokenMap(str(out / "remote-tokens.json"))
+    cap = tokens.mint(args.principal, token)
+    base = args.url or _read_env(out / "middleware.env").get("GARGOYLE_MCP_ISSUER_URL", "https://<gate host>")
+    print("remote-tokens.json updated for %s" % args.principal)
+    print("connector URL (treat as a credential): %s/mcp/%s" % (base.rstrip("/"), cap))
+    return 0
+
+
+def cmd_remote(args) -> int:
+    """Run the gate as a Streamable HTTP MCP server on the deployment's
+    middleware settings, fronting a stdio command or a remote MCP server."""
+    import uvicorn
+    from gargoyle.mcp_server import config_from_env, upstream_from_argv
+    from gargoyle.remote import HttpUpstream, TokenMap, build_remote_app
+    out = Path(args.out).resolve()
+    env = _read_env(out / "middleware.env")
+    env.setdefault("GARGOYLE_MCP_PRINCIPAL", "remote")        # each token supplies the real one
+    env.setdefault("GARGOYLE_MCP_RECORD_PATH", str(out / "record.json"))
+    os.environ.update(env)
+    config = config_from_env()
+    if config is None:
+        raise SystemExit("middleware.env in %s is incomplete" % out)
+    config.pop("principal", None)
+    if args.upstream_url:
+        upstream = HttpUpstream(args.upstream_url, args.upstream_token or os.environ.get("GARGOYLE_MCP_UPSTREAM_TOKEN"))
+    else:
+        upstream = upstream_from_argv(args.rest)
+        if upstream is None:
+            raise SystemExit("give --upstream-url URL or `-- <command>` for the server to front")
+    tokens = TokenMap(str(out / "remote-tokens.json"))
+    app = build_remote_app(config, tokens, upstream=upstream, issuer_url=env.get("GARGOYLE_MCP_ISSUER_URL"),
+                           audit_log=env.get("GARGOYLE_MCP_AUDIT_LOG") or str(out / "remote-audit.jsonl"),
+                           state_probe=args.state_probe, snapshot_dir=env.get("GARGOYLE_MCP_SNAPSHOT_DIR"),
+                           approval_timeout=float(env.get("GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS", "300")))
+    tls = {}
+    if args.ssl_certfile or args.ssl_keyfile:
+        if not (args.ssl_certfile and args.ssl_keyfile):
+            raise SystemExit("--ssl-certfile and --ssl-keyfile go together")
+        tls = {"ssl_certfile": args.ssl_certfile, "ssl_keyfile": args.ssl_keyfile}
+    print("remote gate on %s://%s:%d/mcp/<token>" % ("https" if tls else "http", args.host, args.port), file=sys.stderr)
+    try:
+        uvicorn.run(app, host=args.host, port=args.port, log_level="info" if args.verbose else "warning", **tls)
+    finally:
+        upstream.close()
+    return 0
+
+
 def cmd_issuer(args) -> int:
     import uvicorn
     from gargoyle.issuer_service import app_from_env
@@ -303,6 +367,23 @@ def main(argv=None) -> int:
     p.add_argument("--out", default="gargoyle-deploy")
     p.add_argument("--watch", type=float, metavar="SECONDS"); p.add_argument("--yes", action="store_true")
     p.set_defaults(fn=cmd_approve)
+    p = sub.add_parser("remote", help="run the gate as an HTTPS MCP server for hosted connectors")
+    p.add_argument("--out", default="gargoyle-deploy")
+    p.add_argument("--host", default="127.0.0.1"); p.add_argument("--port", type=int, default=8444)
+    p.add_argument("--ssl-certfile"); p.add_argument("--ssl-keyfile")
+    p.add_argument("--upstream-url", help="front a remote MCP server (Streamable HTTP)")
+    p.add_argument("--upstream-token", help="bearer for that server (or GARGOYLE_MCP_UPSTREAM_TOKEN)")
+    p.add_argument("--state-probe", default="none", choices=["none", "filesystem"],
+                   help="filesystem only when the upstream is a local filesystem server on this host")
+    p.add_argument("--verbose", action="store_true")
+    p.add_argument("rest", nargs=argparse.REMAINDER, help="-- <command> for a stdio server to front")
+    p.set_defaults(fn=cmd_remote)
+    p = sub.add_parser("remote-token", help="mint one person's capability URL for the remote gate")
+    p.add_argument("--out", default="gargoyle-deploy")
+    p.add_argument("--principal", required=True, help="the UPN or principal the receipts will name")
+    p.add_argument("--days", type=int, default=365)
+    p.add_argument("--url", help="the gate's public base URL for the printed connector URL")
+    p.set_defaults(fn=cmd_remote_token)
     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")

gargoyle_receipts-0.9.0.dev0/gargoyle/remote.py

@@ -0,0 +1,252 @@
+"""Remote middleware mode: the gate as a Streamable HTTP MCP server.
+
+The stdio middleware sits on the workstation and fronts a local server.
+Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
+custom connectors) reach an MCP server over HTTPS from Anthropic's side,
+and Microsoft 365 servers are reached the same way. This module runs the
+same gate behind an HTTP endpoint so those paths go through it too:
+
+    POST /mcp/{token}      JSON-RPC in, JSON-RPC out (MCP Streamable HTTP)
+    DELETE /mcp/{token}    end the session named by Mcp-Session-Id
+
+`token` is a capability URL segment that names the workstation user: the
+operator mints one per person (`gargoyle remote-token`), mapping it to the
+principal the receipts will name and to the identity token the gate
+presents to the issuer for that person. The hosted connector cannot carry
+the user's own Entra token (that lives on the workstation), so in this
+mode the gate's operator vouches for the user-to-URL mapping, as an API
+key does. Treat the URL as a credential. Device-bound identity remains the
+stdio mode's property.
+
+The upstream is one shared server: a stdio process started once, or a
+remote MCP server reached over Streamable HTTP (HttpUpstream), with an
+optional static bearer. The gate initializes the upstream once and answers
+each session's `initialize` itself; every session shares one replay cache,
+one evidence log and one snapshot store, so single use holds across
+sessions. Everything else is gargoyle.mcp_server unchanged.
+"""
+
+import json
+import secrets
+import threading
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from gargoyle.mcp_server import (EXECUTED_META_KEY, PROTOCOL_VERSION, REASON_META_KEY, SERVER_INFO, IssuerClient,
+                                 ServerState, StdioUpstream, handle_message)
+from gargoyle.replay_cache import InMemoryReplayCache
+
+ENV_REMOTE_TOKENS = "GARGOYLE_REMOTE_TOKENS"        # remote-tokens.json: {token: {"principal", "issuer_token"}}
+ENV_UPSTREAM_URL = "GARGOYLE_MCP_UPSTREAM_URL"       # front a remote MCP server instead of a stdio command
+ENV_UPSTREAM_TOKEN = "GARGOYLE_MCP_UPSTREAM_TOKEN"   # optional bearer for that server
+
+SESSION_HEADER = "Mcp-Session-Id"
+PROTOCOL_HEADER = "MCP-Protocol-Version"
+
+
+class HttpUpstream:
+    """An MCP server reached over Streamable HTTP. Same contract as
+    StdioUpstream: send(msg) returns the reply for a request, None for a
+    notification. JSON responses and SSE responses are both accepted."""
+
+    def __init__(self, url: str, token: Optional[str] = None, *, http: Any = None, timeout: float = 60.0) -> None:
+        import requests
+        self.url = url
+        self._token = token
+        self._http = http if http is not None else requests.Session()
+        self._timeout = timeout
+        self._session_id: Optional[str] = None
+        self._lock = threading.Lock()
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream",
+             PROTOCOL_HEADER: PROTOCOL_VERSION}
+        if self._token:
+            h["Authorization"] = "Bearer " + self._token
+        if self._session_id:
+            h[SESSION_HEADER] = self._session_id
+        return h
+
+    def send(self, msg: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            r = self._http.post(self.url, data=json.dumps(msg), headers=self._headers(), timeout=self._timeout)
+            sid = r.headers.get(SESSION_HEADER) or r.headers.get(SESSION_HEADER.lower())
+            if sid:
+                self._session_id = sid
+            if "id" not in msg:
+                return None
+            if r.status_code >= 400:
+                raise RuntimeError("upstream answered %s" % r.status_code)
+            ctype = r.headers.get("content-type", "")
+            if ctype.startswith("text/event-stream"):
+                for line in r.text.splitlines():
+                    if line.startswith("data:"):
+                        try:
+                            reply = json.loads(line[5:].strip())
+                        except ValueError:
+                            continue
+                        if isinstance(reply, dict) and reply.get("id") == msg["id"]:
+                            return reply
+                raise RuntimeError("upstream stream ended without a reply")
+            reply = r.json()
+            if isinstance(reply, list):
+                reply = next((m for m in reply if isinstance(m, dict) and m.get("id") == msg["id"]), None)
+            if not isinstance(reply, dict):
+                raise RuntimeError("upstream reply is not a JSON-RPC message")
+            return reply
+
+    def close(self) -> None:
+        try:
+            self._http.delete(self.url, headers=self._headers(), timeout=5)
+        except Exception:
+            pass
+
+
+class TokenMap:
+    """Capability tokens to {principal, issuer_token}, from a JSON file."""
+
+    def __init__(self, path: Optional[str] = None, entries: Optional[Dict[str, Dict[str, str]]] = None) -> None:
+        self.path = Path(path) if path else None
+        self._entries: Dict[str, Dict[str, str]] = dict(entries or {})
+        if self.path is not None and self.path.exists():
+            self._entries.update(json.loads(self.path.read_text(encoding="utf-8")).get("tokens", {}))
+
+    def lookup(self, token: str) -> Optional[Dict[str, str]]:
+        e = self._entries.get(token)
+        return dict(e) if isinstance(e, dict) and e.get("principal") and e.get("issuer_token") else None
+
+    def mint(self, principal: str, issuer_token: str) -> str:
+        token = secrets.token_urlsafe(32)
+        self._entries[token] = {"principal": principal, "issuer_token": issuer_token}
+        if self.path is not None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps({"tokens": self._entries}, indent=2) + "\n", encoding="utf-8")
+            try:
+                import os, stat
+                os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
+            except OSError:
+                pass
+        return token
+
+
+def build_remote_app(
+    config: Dict[str, Any],
+    tokens: TokenMap,
+    *,
+    upstream: Any = None,
+    issuer_url: Optional[str] = None,
+    audit_log: Optional[str] = None,
+    state_probe: Any = "none",
+    snapshot_dir: Optional[str] = None,
+    issuer_http: Any = None,
+    approval_timeout: float = 300.0,
+    poll_seconds: float = 2.0,
+    sleep=None,
+):
+    """The FastAPI app. `config` is config_from_env()'s result minus the
+    principal (each token supplies one). `upstream` is a StdioUpstream or
+    HttpUpstream already running; the gate initializes it once here."""
+    from fastapi import FastAPI, Header, Request, Response
+
+    app = FastAPI(title="Gargoyle remote gate")
+    replay = InMemoryReplayCache()
+    sessions: Dict[str, ServerState] = {}
+    lock = threading.Lock()
+    shared_evidence = None
+    shared_snapshots = None
+
+    upstream_init: Dict[str, Any] = {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {"listChanged": False}},
+                                     "serverInfo": SERVER_INFO}
+    if upstream is not None:
+        reply = upstream.send({"jsonrpc": "2.0", "id": "gargoyle-init", "method": "initialize",
+                               "params": {"protocolVersion": PROTOCOL_VERSION, "capabilities": {},
+                                          "clientInfo": {"name": "gargoyle-remote", "version": SERVER_INFO["version"]}}})
+        if isinstance(reply, dict) and isinstance(reply.get("result"), dict):
+            upstream_init = dict(reply["result"])
+            upstream_init["serverInfo"] = {"name": "gargoyle+" + str(upstream_init.get("serverInfo", {}).get("name", "upstream")),
+                                           "version": SERVER_INFO["version"]}
+        upstream.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    def new_state(principal: str, issuer_token: str) -> ServerState:
+        nonlocal shared_evidence, shared_snapshots
+        ic = None
+        if issuer_url:
+            kw: Dict[str, Any] = {"http": issuer_http, "approval_timeout": approval_timeout, "poll_seconds": poll_seconds}
+            if sleep is not None:
+                kw["sleep"] = sleep
+            ic = IssuerClient(issuer_url, issuer_token, **kw)
+        st = ServerState(dict(config, principal=principal), replay_cache=replay, upstream=upstream, issuer_client=ic,
+                         audit_log=audit_log, state_probe=state_probe, snapshot_dir=snapshot_dir)
+        # One log and one snapshot store for the whole process: the chain and
+        # the sidecars must not interleave from several session objects.
+        if st.evidence is not None:
+            if shared_evidence is None:
+                shared_evidence = st.evidence
+            st.evidence = shared_evidence
+        if st.snapshots is not None:
+            if shared_snapshots is None:
+                shared_snapshots = st.snapshots
+            st.snapshots = shared_snapshots
+        st.upstream_init = upstream_init   # type: ignore[attr-defined]
+        return st
+
+    def handle_one(st: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        method = msg.get("method")
+        if method == "initialize":
+            return {"jsonrpc": "2.0", "id": msg.get("id"), "result": st.upstream_init}   # type: ignore[attr-defined]
+        if method == "notifications/initialized":
+            st.initialized = True
+            return None
+        return handle_message(st, msg)
+
+    @app.post("/mcp/{token}")
+    async def mcp_post(token: str, request: Request,
+                       mcp_session_id: Optional[str] = Header(default=None, alias=SESSION_HEADER)):
+        who = tokens.lookup(token)
+        if who is None:
+            return Response(status_code=401, content="unknown token")
+        try:
+            body = await request.json()
+        except Exception:
+            return Response(status_code=400, content="not JSON")
+        messages: List[Any] = body if isinstance(body, list) else [body]
+        is_init = any(isinstance(m, dict) and m.get("method") == "initialize" for m in messages)
+        with lock:
+            if is_init or not mcp_session_id or mcp_session_id not in sessions:
+                if not is_init:
+                    return Response(status_code=404, content="no such session; initialize first")
+                mcp_session_id = uuid.uuid4().hex
+                sessions[mcp_session_id] = new_state(who["principal"], who["issuer_token"])
+            st = sessions[mcp_session_id]
+        replies = [r for r in (handle_one(st, m) for m in messages if isinstance(m, dict)) if r is not None]
+        headers = {SESSION_HEADER: mcp_session_id, PROTOCOL_HEADER: PROTOCOL_VERSION}
+        if not replies:
+            return Response(status_code=202, headers=headers)
+        payload = replies[0] if not isinstance(body, list) else replies
+        return Response(content=json.dumps(payload), media_type="application/json", headers=headers)
+
+    @app.get("/mcp/{token}")
+    async def mcp_get(token: str):
+        return Response(status_code=405, content="no server-initiated stream")
+
+    @app.delete("/mcp/{token}")
+    async def mcp_delete(token: str, mcp_session_id: Optional[str] = Header(default=None, alias=SESSION_HEADER)):
+        if tokens.lookup(token) is None:
+            return Response(status_code=401)
+        with lock:
+            sessions.pop(mcp_session_id or "", None)
+        return Response(status_code=200)
+
+    app.state.sessions = sessions
+    return app
+
+
+def mint_identity_token(principal: str, idp_signing_key: Any, idp_key_id: str, audience: str, days: int = 365) -> str:
+    """An identity token the issuer trusts for `principal`, signed by the
+    pinned IdP key `gargoyle init` wrote; the gate presents it in this
+    user's sessions."""
+    from datetime import datetime, timedelta, timezone
+    from gargoyle.jws import encode
+    exp = int((datetime.now(timezone.utc) + timedelta(days=days)).timestamp())
+    return encode({"sub": principal, "aud": audience, "exp": exp}, idp_signing_key, idp_key_id)

{gargoyle_receipts-0.8.1.dev0 → gargoyle_receipts-0.9.0.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.8.1.dev0
+Version: 0.9.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.8.1.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.9.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
@@ -289,6 +289,25 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Remote mode
+
+Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
+custom connectors) and Microsoft 365 servers are reached over HTTPS, not
+through a local process. `gargoyle remote` runs the same gate as a
+Streamable HTTP MCP server in front of a stdio command or a remote MCP
+server (`--upstream-url`), so those paths go through it too:
+
+    gargoyle remote-token --out gargoyle-deploy --principal dana@contoso.com --url https://gargoyle.lan:8444
+    gargoyle remote --out gargoyle-deploy --port 8444 --ssl-certfile ... --ssl-keyfile ... -- python -m gargoyle.fs_server /srv/shared
+
+Each person gets a capability URL (`/mcp/<token>`) that names them on
+every receipt; the operator vouches for that mapping, as with an API key,
+because a hosted connector cannot carry the user's own Entra token.
+Treat the URL as a credential. All sessions share one upstream, one replay
+cache, one evidence log and one snapshot store, so single use and undo
+hold across users. Device-bound identity remains the stdio mode's
+property.
+
 ## The shipped consumer
 
 **MCP middleware** (`python -m gargoyle.mcp_server -- <upstream command>`):
@@ -319,6 +338,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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 |
 | `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_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |
 

{gargoyle_receipts-0.8.1.dev0 → gargoyle_receipts-0.9.0.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ gargoyle/opa.py
 gargoyle/pending_store.py
 gargoyle/policy.py
 gargoyle/published_record_source.py
+gargoyle/remote.py
 gargoyle/replay_cache.py
 gargoyle/revert.py
 gargoyle/rules.py
@@ -61,6 +62,7 @@ tests/test_notify.py
 tests/test_opa.py
 tests/test_policy.py
 tests/test_published_record.py
+tests/test_remote.py
 tests/test_revert.py
 tests/test_rules.py
 tests/test_state.py

{gargoyle_receipts-0.8.1.dev0 → gargoyle_receipts-0.9.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.8.1.dev0"
+version = "0.9.0.dev0"
 description = "Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls."
 readme = "README.md"
 requires-python = ">=3.12"

gargoyle_receipts-0.9.0.dev0/tests/test_remote.py

@@ -0,0 +1,182 @@
+"""Remote middleware mode: the same gate behind a Streamable HTTP endpoint,
+one capability URL per person, one shared upstream, shared single use."""
+
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from fastapi import FastAPI, Request, Response
+from fastapi.testclient import TestClient
+
+from gargoyle.approval import build_grant, sign_grant
+from gargoyle.issuer_service import build_issuer_app
+from gargoyle.mcp_server import EXECUTED_META_KEY, REASON_META_KEY, StdioUpstream
+from gargoyle.policy import ELIGIBLE, Decision, refuse
+from gargoyle.remote import SESSION_HEADER, HttpUpstream, TokenMap, build_remote_app, mint_identity_token
+from gargoyle.revert import REVERT_TOOL
+
+issuer, executor, approver, idp = (Ed25519PrivateKey.generate() for _ in range(4))
+PIN = {"policy_id": "p/1", "policy_sha256": "a" * 64}
+TARGET = "mcp://fs"
+
+
+class FsPolicy:
+    def pin(self): return PIN
+    def decide(self, target_url, interaction):
+        t = interaction.get("tool")
+        if t == "write_file": return Decision(ELIGIBLE, None, True)
+        if t == "delete_file": return refuse("DESTRUCTIVE_TOOL")
+        return Decision(ELIGIBLE)
+
+
+def _issuer():
+    app = build_issuer_app(policy=FsPolicy(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()},
+                           approver_public_keys={"approver-1": approver.public_key()}, audience="gargoyle-issuer")
+    c = TestClient(app)
+
+    class Shim:
+        def post(self, url, json=None, headers=None, timeout=None): return c.post(url.replace("http://i", ""), json=json, headers=headers)
+        def get(self, url, headers=None, timeout=None): return c.get(url.replace("http://i", ""), headers=headers)
+
+    def human(seconds):
+        tok = mint_identity_token("approver", idp, "idp-1", "gargoyle-issuer")
+        h = {"Authorization": "Bearer " + tok}
+        for hold in c.get("/pending", headers=h).json()["pending"]:
+            env = hold["envelope"]
+            g = sign_grant(build_grant(decision_sha256=env["decision_sha256"], approval_request_id=env["approval_request_id"],
+                                       grant_id="g-" + env["approval_request_id"], not_after=datetime.now(timezone.utc) + timedelta(minutes=5)),
+                           approver, "approver-1")
+            c.post("/grants", json=g, headers=h)
+    return c, Shim(), human
+
+
+CONFIG = {"pinned_public_keys": {"issuer-1": issuer.public_key()}, "record": PIN, "target_id": TARGET,
+          "approver_public_keys": {"approver-1": approver.public_key()}, "executor_signing_key": executor, "executor_key_id": "executor-1"}
+
+
+def rpc(client, token, msg, sid=None):
+    h = {"Content-Type": "application/json"}
+    if sid: h[SESSION_HEADER] = sid
+    return client.post("/mcp/" + token, content=json.dumps(msg), headers=h)
+
+
+def test_remote_gate_over_stdio_upstream(tmp_path):
+    root = tmp_path / "root"; root.mkdir(); (root / "n.md").write_text("one\n", encoding="utf-8")
+    _, shim, human = _issuer()
+    tokens = TokenMap(str(tmp_path / "remote-tokens.json"))
+    alice = tokens.mint("alice@contoso.com", mint_identity_token("alice@contoso.com", idp, "idp-1", "gargoyle-issuer"))
+    assert TokenMap(str(tmp_path / "remote-tokens.json")).lookup(alice)["principal"] == "alice@contoso.com"
+    up = StdioUpstream([sys.executable, "-I", "-m", "gargoyle.fs_server", str(root)])
+    try:
+        app = build_remote_app(CONFIG, tokens, upstream=up, issuer_url="http://i", issuer_http=shim, audit_log=str(tmp_path / "audit.jsonl"),
+                               state_probe="filesystem", approval_timeout=30, poll_seconds=0.01, sleep=human)
+        c = TestClient(app)
+        # Unknown capability: nothing.
+        assert rpc(c, "nope", {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}).status_code == 401
+        # Initialize: a session id comes back, the upstream's capabilities with it.
+        r = rpc(c, alice, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "t", "version": "0"}}})
+        assert r.status_code == 200 and r.headers[SESSION_HEADER]
+        sid = r.headers[SESSION_HEADER]
+        assert r.json()["result"]["serverInfo"]["name"].startswith("gargoyle+")
+        assert rpc(c, alice, {"jsonrpc": "2.0", "method": "notifications/initialized"}, sid).status_code == 202
+        # Tools: the upstream's plus undo.
+        tools = rpc(c, alice, {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}, sid).json()["result"]["tools"]
+        assert {"read_file", "write_file", REVERT_TOOL} <= {t["name"] for t in tools}
+        # A free read runs; a held write is approved by the human and runs; the receipt names alice.
+        r = rpc(c, alice, {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "read_file", "arguments": {"path": str(root / "n.md")}}}, sid).json()
+        assert r["result"]["_meta"][EXECUTED_META_KEY] is True and r["result"]["content"][0]["text"] == "one\n"
+        r = rpc(c, alice, {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "write_file", "arguments": {"path": str(root / "n.md"), "content": "two\n"}}}, sid).json()
+        assert r["result"]["_meta"][EXECUTED_META_KEY] is True and (root / "n.md").read_text(encoding="utf-8") == "two\n"
+        assert r["result"]["_meta"]["gargoyle/receipt"]["request_context"]["principal"] == "alice@contoso.com"
+        assert "pre_state_sha256" in r["result"]["_meta"]["gargoyle/execution"]
+        # A refusal is a refusal.
+        r = rpc(c, alice, {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "delete_file", "arguments": {"path": str(root / "n.md")}}}, sid).json()
+        assert r["result"]["isError"] and r["result"]["_meta"][REASON_META_KEY] == "DESTRUCTIVE_TOOL"
+        # A second person, a second session, the same upstream and the same evidence log.
+        bob = tokens.mint("bob@contoso.com", mint_identity_token("bob@contoso.com", idp, "idp-1", "gargoyle-issuer"))
+        r = rpc(c, bob, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}); sid2 = r.headers[SESSION_HEADER]
+        rpc(c, bob, {"jsonrpc": "2.0", "method": "notifications/initialized"}, sid2)
+        r = rpc(c, bob, {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "read_file", "arguments": {"path": str(root / "n.md")}}}, sid2).json()
+        assert r["result"]["_meta"]["gargoyle/receipt"]["request_context"]["principal"] == "bob@contoso.com"
+        lines = [json.loads(l) for l in (tmp_path / "audit.jsonl").read_text(encoding="utf-8").splitlines()]
+        assert [e["principal"] for e in lines] == ["alice@contoso.com"] * 3 + ["bob@contoso.com"] and [e["seq"] for e in lines] == [1, 2, 3, 4]
+        # No session: told to initialize; DELETE ends one.
+        assert rpc(c, alice, {"jsonrpc": "2.0", "id": 9, "method": "tools/list", "params": {}}, "stale").status_code == 404
+        assert c.delete("/mcp/" + alice, headers={SESSION_HEADER: sid}).status_code == 200
+        assert rpc(c, alice, {"jsonrpc": "2.0", "id": 9, "method": "tools/list", "params": {}}, sid).status_code == 404
+    finally:
+        up.close()
+
+
+def test_http_upstream_speaks_streamable_http(tmp_path):
+    """The gate fronting a remote MCP server: JSON and SSE answers, session id carried."""
+    fake = FastAPI(); calls = []
+
+    @fake.post("/mcp")
+    async def mcp(request: Request):
+        msg = await request.json(); calls.append((msg, dict(request.headers)))
+        if "id" not in msg:
+            return Response(status_code=202)
+        if msg["method"] == "initialize":
+            return Response(content=json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"protocolVersion": "2025-06-18", "capabilities": {"tools": {}}, "serverInfo": {"name": "graph", "version": "1"}}}),
+                            media_type="application/json", headers={SESSION_HEADER: "up-1"})
+        if msg["method"] == "tools/list":
+            body = "event: message\ndata: " + json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"tools": [{"name": "send_mail"}]}}) + "\n\n"
+            return Response(content=body, media_type="text/event-stream")
+        return Response(content=json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"content": [{"type": "text", "text": "sent"}]}}), media_type="application/json")
+
+    fc = TestClient(fake)
+
+    class Shim:
+        def post(self, url, data=None, headers=None, timeout=None): return fc.post("/mcp", content=data, headers=headers)
+        def delete(self, url, headers=None, timeout=None): return fc.delete("/mcp", headers=headers)
+
+    up = HttpUpstream("https://graph.example/mcp", "secret", http=Shim())
+    init = up.send({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+    assert init["result"]["serverInfo"]["name"] == "graph" and calls[0][1]["authorization"] == "Bearer secret"
+    assert up.send({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
+    assert calls[-1][1][SESSION_HEADER.lower()] == "up-1"                       # session carried after initialize
+    assert up.send({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}})["result"]["tools"][0]["name"] == "send_mail"
+    assert up.send({"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "send_mail", "arguments": {}}})["result"]["content"][0]["text"] == "sent"
+
+    # Behind the gate, with no state probe (the server is remote): free calls relay, policy still decides.
+    class Allow:
+        def pin(self): return PIN
+        def decide(self, target_url, interaction): return Decision(ELIGIBLE)
+    app = build_issuer_app(policy=Allow(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()}, audience="gargoyle-issuer")
+    ic = TestClient(app)
+
+    class IShim:
+        def post(self, url, json=None, headers=None, timeout=None): return ic.post(url.replace("http://i", ""), json=json, headers=headers)
+        def get(self, url, headers=None, timeout=None): return ic.get(url.replace("http://i", ""), headers=headers)
+    tokens = TokenMap(entries={"t1": {"principal": "carol@contoso.com", "issuer_token": mint_identity_token("carol@contoso.com", idp, "idp-1", "gargoyle-issuer")}})
+    gate = TestClient(build_remote_app(dict(CONFIG, target_id="mcp://graph"), tokens, upstream=up, issuer_url="http://i", issuer_http=IShim(), state_probe="none"))
+    r = rpc(gate, "t1", {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}); sid = r.headers[SESSION_HEADER]
+    rpc(gate, "t1", {"jsonrpc": "2.0", "method": "notifications/initialized"}, sid)
+    r = rpc(gate, "t1", {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "send_mail", "arguments": {"to": "x"}}}, sid).json()
+    assert r["result"]["_meta"][EXECUTED_META_KEY] is True and r["result"]["content"][0]["text"] == "sent"
+    assert r["result"]["_meta"]["gargoyle/receipt"]["request_context"]["principal"] == "carol@contoso.com"
+
+
+def test_remote_token_command_mints_a_capability_url(tmp_path, capsys):
+    from gargoyle.cli import main, _read_env
+    out = tmp_path / "deploy"
+    assert main(["init", str(tmp_path / "p"), "--out", str(out), "--issuer-url", "https://gargoyle.lan"]) == 0
+    assert "GARGOYLE_IDP_KEY_HEX" in _read_env(out / "issuer.env")          # kept, so tokens can be minted later
+    assert main(["remote-token", "--out", str(out), "--principal", "dana@contoso.com", "--url", "https://gargoyle.lan:8444"]) == 0
+    text = capsys.readouterr().out
+    assert "https://gargoyle.lan:8444/mcp/" in text
+    tokens = json.loads((out / "remote-tokens.json").read_text())["tokens"]
+    (cap, entry), = tokens.items()
+    assert entry["principal"] == "dana@contoso.com" and text.rstrip().endswith(cap)
+    # The minted identity token is one the deployment's issuer accepts.
+    from gargoyle.issuer_service import app_from_env
+    import os
+    env = _read_env(out / "issuer.env"); os.environ.update(env)
+    try:
+        c = TestClient(app_from_env())
+        r = c.post("/issue", json={"target_url": "mcp://x", "tool": "read_file", "args": {}}, headers={"Authorization": "Bearer " + entry["issuer_token"]})
+        assert r.status_code == 200 and r.json()["envelope"]["request_context"]["principal"] == "dana@contoso.com"
+    finally:
+        for k in env: os.environ.pop(k, None)