gargoyle-receipts 0.4.0.dev0__tar.gz → 0.5.0.dev0__tar.gz

{gargoyle_receipts-0.4.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.5.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.4.0.dev0
+Version: 0.5.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
@@ -28,6 +28,8 @@ Requires-Dist: uvicorn>=0.30
 Requires-Dist: requests>=2.32
 Provides-Extra: redis
 Requires-Dist: redis; extra == "redis"
+Provides-Extra: entra
+Requires-Dist: msal>=1.28; extra == "entra"
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
@@ -55,7 +57,9 @@ is included); the caller is authenticated by your transport (the
 proxy-verified client certificate, by default); Gargoyle sits in front of
 your MCP server and lets through only what both agreed to.
 
-Status: pre-release (`0.4.0.dev0`). The wire format is `gargoyle/3` and may
+[![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
+
+Status: pre-release (`0.5.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
@@ -242,6 +246,8 @@ chat channel can approve anything.
 
 ## Deploy it
 
+    pip install gargoyle-receipts
+
 Three commands, no policy engine, no containers, no client changes:
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
@@ -290,6 +296,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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 |
+| issuer `GARGOYLE_ISSUER_AUDIENCE` | the `aud` an identity token must carry; a comma-separated list accepts several, so init-minted tokens (`gargoyle-issuer`) and a tenant's tokens (the issuer app's client id) work side by side |
+| `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` |
 | `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_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 |
 
@@ -298,7 +306,9 @@ cannot attach receipts work unchanged. Configuration is by environment:
 exchange for flagged calls (`/issue`, `/pending`, `/grants`, `/decline`,
 `/record`, `/keys`) and the browser approval console at `/approve`. Policy
 from a rules file or OPA; identity from a pinned key or, with
-`GARGOYLE_ENTRA_TENANT`, the tenant's signing keys.
+`GARGOYLE_ENTRA_TENANT`, the tenant's signing keys (both at once when a
+pinned key is also set, so init-minted approver tokens keep working while
+users move to `gargoyle login`).
 
 
 ## Approval holds

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/README.md

@@ -19,7 +19,9 @@ is included); the caller is authenticated by your transport (the
 proxy-verified client certificate, by default); Gargoyle sits in front of
 your MCP server and lets through only what both agreed to.
 
-Status: pre-release (`0.4.0.dev0`). The wire format is `gargoyle/3` and may
+[![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
+
+Status: pre-release (`0.5.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
@@ -206,6 +208,8 @@ chat channel can approve anything.
 
 ## Deploy it
 
+    pip install gargoyle-receipts
+
 Three commands, no policy engine, no containers, no client changes:
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
@@ -254,6 +258,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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 |
+| issuer `GARGOYLE_ISSUER_AUDIENCE` | the `aud` an identity token must carry; a comma-separated list accepts several, so init-minted tokens (`gargoyle-issuer`) and a tenant's tokens (the issuer app's client id) work side by side |
+| `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` |
 | `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_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 |
 
@@ -262,7 +268,9 @@ cannot attach receipts work unchanged. Configuration is by environment:
 exchange for flagged calls (`/issue`, `/pending`, `/grants`, `/decline`,
 `/record`, `/keys`) and the browser approval console at `/approve`. Policy
 from a rules file or OPA; identity from a pinned key or, with
-`GARGOYLE_ENTRA_TENANT`, the tenant's signing keys.
+`GARGOYLE_ENTRA_TENANT`, the tenant's signing keys (both at once when a
+pinned key is also set, so init-minted approver tokens keep working while
+users move to `gargoyle login`).
 
 
 ## Approval holds

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/gargoyle/cli.py

@@ -9,6 +9,8 @@ policy engine, a container runtime, or any client changes.
     gargoyle issuer ... [--ssl-certfile CRT --ssl-keyfile KEY]   serve TLS directly (no reverse proxy)
     gargoyle issuer [--out DIR] [--port 8080]            run the issuing service
     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 audit <receipt.json> <execution.json> [grant.json]
     gargoyle audit --log audit.jsonl            verify the middleware's evidence log
 
@@ -112,6 +114,8 @@ def cmd_init(args) -> int:
         "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",
+        **({"GARGOYLE_ENTRA_TENANT": args.entra_tenant} if args.entra_tenant else {}),
+        **({"GARGOYLE_ISSUER_AUDIENCE": args.entra_audience} if args.entra_audience else {}),
     }), private=True)
     middleware_env = {
         "GARGOYLE_MCP_GATE_KEY_ID": "issuer-1", "GARGOYLE_MCP_GATE_PUBLIC_KEY_HEX": issuer_pub,
@@ -154,6 +158,36 @@ def cmd_init(args) -> int:
     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,
+    and the principal becomes their UPN."""
+    from gargoyle.entra_login import (ENV_ENTRA_CLIENT_ID, ENV_ENTRA_SCOPE, ENV_ENTRA_TENANT, ENV_ENTRA_TOKEN_CACHE,
+                                      device_code_login)
+    out = Path(args.out).resolve()
+    client_dir = Path(args.client_config_dir or out)
+    cache = client_dir / "entra-token-cache.json"
+    result = device_code_login(args.tenant, args.client_id, args.scope, str(cache))
+    principal = result["principal"]
+    env_path = out / "middleware.env"
+    env = _read_env(env_path) if env_path.exists() else {}
+    env.pop("GARGOYLE_MCP_CLIENT_TOKEN", None)
+    env.update({ENV_ENTRA_TENANT: args.tenant, ENV_ENTRA_CLIENT_ID: args.client_id, ENV_ENTRA_SCOPE: args.scope,
+                ENV_ENTRA_TOKEN_CACHE: str(cache), "GARGOYLE_MCP_PRINCIPAL": principal})
+    _write(env_path, _env_lines(env), 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_TARGET_ID" in server.get("env", {}):
+                server["env"].pop("GARGOYLE_MCP_CLIENT_TOKEN", None)
+                server["env"].update({k: env[k] for k in (ENV_ENTRA_TENANT, ENV_ENTRA_CLIENT_ID, ENV_ENTRA_SCOPE,
+                                                            ENV_ENTRA_TOKEN_CACHE, "GARGOYLE_MCP_PRINCIPAL")})
+        _write(mcp, json.dumps(doc, indent=2) + "\n", private=True)
+    print("signed in as %s; the middleware now acts as that user (restart the MCP client)" % principal)
+    return 0
+
+
 def cmd_issuer(args) -> int:
     import uvicorn
     from gargoyle.issuer_service import app_from_env
@@ -236,7 +270,16 @@ def main(argv=None) -> int:
                    help="how many approver keys to create (approver-1..N); a rule with \"approvals\": 2 then needs two of them")
     p.add_argument("--upstream", choices=["npx-filesystem", "python-fs"], default="npx-filesystem",
                    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.set_defaults(fn=cmd_init)
+    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")
+    p.add_argument("--scope", required=True, help="the issuer API scope, e.g. api://<api-client-id>/access")
+    p.add_argument("--out", default="gargoyle-deploy", help="where middleware.env and mcp-config.json live")
+    p.add_argument("--client-config-dir", help="where the token cache goes (default: --out)")
+    p.set_defaults(fn=cmd_login)
     p = sub.add_parser("issuer", help="run the issuing service on the rules file")
     p.add_argument("--out", default="gargoyle-deploy")
     p.add_argument("--host", default="127.0.0.1"); p.add_argument("--port", type=int, default=8080)

gargoyle_receipts-0.5.0.dev0/gargoyle/entra_login.py

@@ -0,0 +1,137 @@
+"""Entra ID login for the client: the middleware's token names a person.
+
+`gargoyle init` mints one shared client token. For a team, each workstation
+should present its own user's identity, so that every receipt's principal
+and every audit row names who asked. `gargoyle login` runs the Entra ID
+device-code flow once (the user signs in from a browser on any device,
+with the tenant's MFA), and stores MSAL's token cache in a private file.
+The middleware then obtains a current access token from that cache before
+each call to the issuer; MSAL refreshes it silently with the refresh token
+until the tenant's policy says to sign in again.
+
+Entra app registration (once per tenant):
+  - an API app for the issuer, exposing one scope (for example
+    api://<api-client-id>/access); the issuer's GARGOYLE_ISSUER_AUDIENCE is
+    that app's client id (v2 tokens) or its app id URI (v1 tokens);
+  - a public client app for `gargoyle login` with "Allow public client
+    flows" on, granted that scope.
+
+The issuer verifies the token against the tenant's published keys
+(GARGOYLE_ENTRA_TENANT) and takes preferred_username, the UPN, as the
+principal; groups and app roles in the token are inputs to the rules.
+
+MSAL is an optional dependency: pip install "gargoyle-receipts[entra]".
+"""
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+ENV_ENTRA_TENANT = "GARGOYLE_MCP_ENTRA_TENANT"
+ENV_ENTRA_CLIENT_ID = "GARGOYLE_MCP_ENTRA_CLIENT_ID"
+ENV_ENTRA_SCOPE = "GARGOYLE_MCP_ENTRA_SCOPE"
+ENV_ENTRA_TOKEN_CACHE = "GARGOYLE_MCP_ENTRA_TOKEN_CACHE"
+
+AUTHORITY = "https://login.microsoftonline.com/{tenant}"
+
+
+class LoginRequired(Exception):
+    """No usable account in the cache: run `gargoyle login`."""
+
+
+def _msal():
+    try:
+        import msal
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError('Entra login needs msal: pip install "gargoyle-receipts[entra]"') from exc
+    return msal
+
+
+class TokenCache:
+    """MSAL's serializable cache, persisted to a private file."""
+
+    def __init__(self, path: str, msal_module: Any = None) -> None:
+        self.path = Path(path)
+        self._msal = msal_module or _msal()
+        self.cache = self._msal.SerializableTokenCache()
+        if self.path.exists():
+            self.cache.deserialize(self.path.read_text(encoding="utf-8"))
+
+    def save(self) -> None:
+        if self.cache.has_state_changed:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(self.cache.serialize(), encoding="utf-8")
+            try:
+                os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
+            except OSError:
+                pass
+
+
+def _app(tenant: str, client_id: str, cache: TokenCache, app_factory: Optional[Callable] = None) -> Any:
+    if app_factory is not None:
+        return app_factory(client_id=client_id, authority=AUTHORITY.format(tenant=tenant), token_cache=cache.cache)
+    return _msal().PublicClientApplication(client_id, authority=AUTHORITY.format(tenant=tenant), token_cache=cache.cache)
+
+
+def device_code_login(tenant: str, client_id: str, scope: str, cache_path: str, *,
+                      app_factory: Optional[Callable] = None, msal_module: Any = None,
+                      prompt: Callable[[str], None] = print) -> Dict[str, Any]:
+    """Sign a user in by device code and store the cache. Returns
+    {"principal": <UPN>, "expires_in": seconds, "cache_path": str}.
+    Raises RuntimeError with Entra's error text when the sign-in fails."""
+    cache = TokenCache(cache_path, msal_module)
+    app = _app(tenant, client_id, cache, app_factory)
+    flow = app.initiate_device_flow(scopes=[scope])
+    if "user_code" not in flow:
+        raise RuntimeError("device flow could not start: %s" % flow.get("error_description", flow))
+    prompt(flow["message"])
+    result = app.acquire_token_by_device_flow(flow)
+    cache.save()
+    if "access_token" not in result:
+        raise RuntimeError("sign-in failed: %s" % result.get("error_description", result.get("error", result)))
+    claims = result.get("id_token_claims") or {}
+    principal = claims.get("preferred_username") or claims.get("upn") or claims.get("oid")
+    if not principal:
+        raise RuntimeError("the token names no user (no preferred_username, upn or oid)")
+    return {"principal": principal, "expires_in": result.get("expires_in"), "cache_path": str(cache.path)}
+
+
+class EntraTokenSource:
+    """What the middleware calls for a bearer token: the cached account's
+    current access token, refreshed silently by MSAL when needed."""
+
+    def __init__(self, tenant: str, client_id: str, scope: str, cache_path: str, *,
+                 app_factory: Optional[Callable] = None, msal_module: Any = None) -> None:
+        self.scope = scope
+        self._cache = TokenCache(cache_path, msal_module)
+        self._app = _app(tenant, client_id, self._cache, app_factory)
+
+    def token(self) -> str:
+        accounts: List[Dict[str, Any]] = self._app.get_accounts()
+        if not accounts:
+            raise LoginRequired("no Entra account in %s; run: gargoyle login" % self._cache.path)
+        result = self._app.acquire_token_silent([self.scope], account=accounts[0]) or {}
+        self._cache.save()
+        if "access_token" not in result:
+            raise LoginRequired("Entra token could not be refreshed (%s); run: gargoyle login"
+                                % result.get("error_description", result.get("error", "no token")))
+        return result["access_token"]
+
+    @property
+    def principal(self) -> Optional[str]:
+        accounts = self._app.get_accounts()
+        return accounts[0].get("username") if accounts else None
+
+
+def token_source_from_env(environ: Dict[str, str]) -> Optional[EntraTokenSource]:
+    """An EntraTokenSource when the four GARGOYLE_MCP_ENTRA_* variables are
+    set, None when none is; a partial set raises."""
+    keys = (ENV_ENTRA_TENANT, ENV_ENTRA_CLIENT_ID, ENV_ENTRA_SCOPE, ENV_ENTRA_TOKEN_CACHE)
+    values = [environ.get(k) for k in keys]
+    if not any(values):
+        return None
+    if not all(values):
+        raise RuntimeError("set all of %s together" % ", ".join(keys))
+    return EntraTokenSource(*values)

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/gargoyle/identity.py

@@ -77,7 +77,7 @@ def _innermost_actor(act: Any) -> Optional[str]:
 
 
 def principal_from_token(token: str, public_keys: Dict[str, Any], *,
-                         audience: Optional[str] = None, now: Optional[datetime] = None) -> Dict[str, Any]:
+                         audience: Any = None, now: Optional[datetime] = None) -> Dict[str, Any]:
     """{"principal", "on_behalf_of" (or None), "claims", "reason": None} for
     a trusted identity token, or {"principal": None, "reason": code}."""
     res = decode(token, public_keys, allowed_algs=IDENTITY_ALGS)
@@ -89,9 +89,13 @@ def principal_from_token(token: str, public_keys: Dict[str, Any], *,
     if not isinstance(exp, int) or isinstance(exp, bool) or current.timestamp() >= exp:
         return {"principal": None, "reason": REF_JWS_EXPIRED}
     if audience is not None:
+        # One audience, or several (a list, or a comma-separated string):
+        # the issuer accepts init-minted tokens and a tenant's tokens side
+        # by side while a site moves from one to the other.
         aud = claims.get("aud")
-        allowed = aud if isinstance(aud, list) else [aud]
-        if audience not in allowed:
+        presented = aud if isinstance(aud, list) else [aud]
+        accepted = audience if isinstance(audience, (list, tuple)) else [a.strip() for a in str(audience).split(",")]
+        if not any(a in presented for a in accepted if a):
             return {"principal": None, "reason": REF_JWS_AUDIENCE_MISMATCH}
 
     # OIDC providers' `sub` is opaque; the UPN is the identity people and

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/gargoyle/issuer_service.py

@@ -258,6 +258,7 @@ def app_from_env() -> FastAPI:
 
     required = {k: os.environ.get(k) for k in (ENV_ISSUER_KEY_ID, ENV_ISSUER_KEY_HEX)}
     tenant = os.environ.get(ENV_ENTRA_TENANT)
+    pinned_idp = os.environ.get(ENV_IDP_KEY_ID) and os.environ.get(ENV_IDP_PUBLIC_KEY_HEX)
     if not tenant:
         required.update({k: os.environ.get(k) for k in (ENV_IDP_KEY_ID, ENV_IDP_PUBLIC_KEY_HEX)})
     missing = [k for k, v in required.items() if not v]
@@ -287,9 +288,12 @@ def app_from_env() -> FastAPI:
         policy=policy,
         signing_key=Ed25519PrivateKey.from_private_bytes(bytes.fromhex(required[ENV_ISSUER_KEY_HEX])),
         key_id=required[ENV_ISSUER_KEY_ID],
-        idp_public_keys=(entra_keys(tenant) if tenant else
-                         {required[ENV_IDP_KEY_ID]:
-                          Ed25519PublicKey.from_public_bytes(bytes.fromhex(required[ENV_IDP_PUBLIC_KEY_HEX]))}),
+        # Both may be trusted at once: the tenant's keys for users who ran
+        # `gargoyle login`, the pinned key for tokens `gargoyle init` minted
+        # (the approver's, until approvers log in with Entra too).
+        idp_public_keys={**(entra_keys(tenant) if tenant else {}),
+                         **({os.environ[ENV_IDP_KEY_ID]: Ed25519PublicKey.from_public_bytes(bytes.fromhex(os.environ[ENV_IDP_PUBLIC_KEY_HEX]))}
+                            if pinned_idp else {})},
         approver_public_keys=approver,
         audience=os.environ.get(ENV_AUDIENCE) or None,
         ttl_seconds=int(os.environ.get(ENV_RECEIPT_TTL, DEFAULT_TTL_SECONDS)),

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/gargoyle/mcp_server.py

@@ -96,7 +96,8 @@ ENV_ISSUER_URL = "GARGOYLE_MCP_ISSUER_URL"
 ENV_CLIENT_TOKEN = "GARGOYLE_MCP_CLIENT_TOKEN"
 ENV_APPROVAL_TIMEOUT = "GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS"
 ENV_POLL_SECONDS = "GARGOYLE_MCP_POLL_SECONDS"
-ENV_AUDIT_LOG = "GARGOYLE_MCP_AUDIT_LOG"   # the evidence log: one hash-chained JSON line per decision, honored or refused
+ENV_AUDIT_LOG = "GARGOYLE_MCP_AUDIT_LOG"
+REF_TARGET_LOGIN_REQUIRED = "REF_TARGET_LOGIN_REQUIRED"   # Entra login mode and no usable token: run `gargoyle login`   # the evidence log: one hash-chained JSON line per decision, honored or refused
 
 # Self-issue refusals.
 REF_TARGET_ISSUER_UNAVAILABLE = "REF_TARGET_ISSUER_UNAVAILABLE"
@@ -110,22 +111,28 @@ class IssuerClient:
     passes a TestClient). Every failure is a refusal reason, never an
     exception out of the gate."""
 
-    def __init__(self, url: str, token: str, *, http: Any = None, approval_timeout: float = 300.0,
+    def __init__(self, url: str, token: Any, *, http: Any = None, approval_timeout: float = 300.0,
                  poll_seconds: float = 2.0, request_timeout: float = 10.0, sleep=time.sleep) -> None:
+        """`token` is the bearer token string, or an object with a token()
+        method that returns the current one (gargoyle.entra_login.EntraTokenSource)."""
         import requests
         self.url = url.rstrip("/")
-        self._headers = {"Authorization": "Bearer " + token}
+        self._token = token
         self._http = http if http is not None else requests.Session()
         self.approval_timeout = approval_timeout
         self.poll_seconds = poll_seconds
         self.request_timeout = request_timeout
         self._sleep = sleep
 
+    def _headers(self) -> Dict[str, str]:
+        token = self._token.token() if hasattr(self._token, "token") else self._token
+        return {"Authorization": "Bearer " + token}
+
     def _post(self, path: str, body: Dict[str, Any]) -> Any:
-        return self._http.post(self.url + path, json=body, headers=self._headers, timeout=self.request_timeout)
+        return self._http.post(self.url + path, json=body, headers=self._headers(), timeout=self.request_timeout)
 
     def _get(self, path: str) -> Any:
-        return self._http.get(self.url + path, headers=self._headers, timeout=self.request_timeout)
+        return self._http.get(self.url + path, headers=self._headers(), timeout=self.request_timeout)
 
     def issue(self, target_url: str, tool: str, args: Any) -> Dict[str, Any]:
         """{"envelope": ...} or {"envelope": None, "reason": ...}. The cause of
@@ -134,6 +141,13 @@ class IssuerClient:
         generic."""
         try:
             r = self._post("/issue", {"target_url": target_url, "tool": tool, "args": args})
+        except Exception as exc:
+            if type(exc).__name__ == "LoginRequired":
+                sys.stderr.write("gargoyle: %s\n" % exc)
+                return {"envelope": None, "reason": REF_TARGET_LOGIN_REQUIRED}
+            sys.stderr.write("gargoyle: issuer unreachable at %s: %s: %s\n" % (self.url, type(exc).__name__, str(exc)[:300]))
+            return {"envelope": None, "reason": REF_TARGET_ISSUER_UNAVAILABLE}
+        try:
             if r.status_code != 200:
                 detail = r.json().get("detail", {}) if r.headers.get("content-type", "").startswith("application/json") else {}
                 sys.stderr.write("gargoyle: issuer answered %s: %s\n" % (r.status_code, r.text[:300]))
@@ -573,17 +587,21 @@ def utf8_stdio(stdin=None, stdout=None):
 
 
 def issuer_client_from_env() -> Optional[IssuerClient]:
-    """Self-issue mode when GARGOYLE_MCP_ISSUER_URL and
-    GARGOYLE_MCP_CLIENT_TOKEN are both set; None otherwise. One without the
-    other is a configuration error and raises."""
+    """Self-issue mode when GARGOYLE_MCP_ISSUER_URL is set together with
+    either GARGOYLE_MCP_CLIENT_TOKEN (a fixed token from `gargoyle init`) or
+    the GARGOYLE_MCP_ENTRA_* set written by `gargoyle login` (a per-user
+    token refreshed from MSAL's cache). None when none is set; a URL without
+    a token source, or the reverse, raises."""
     import os
+    from gargoyle.entra_login import token_source_from_env
 
     url, token = os.environ.get(ENV_ISSUER_URL), os.environ.get(ENV_CLIENT_TOKEN)
-    if not url and not token:
+    source = token_source_from_env(os.environ)
+    if not url and not token and source is None:
         return None
-    if not (url and token):
-        raise RuntimeError("%s and %s go together" % (ENV_ISSUER_URL, ENV_CLIENT_TOKEN))
-    return IssuerClient(url, token,
+    if not url or (not token and source is None):
+        raise RuntimeError("%s goes with %s or the GARGOYLE_MCP_ENTRA_* set" % (ENV_ISSUER_URL, ENV_CLIENT_TOKEN))
+    return IssuerClient(url, source if source is not None else token,
                         approval_timeout=float(os.environ.get(ENV_APPROVAL_TIMEOUT, "300")),
                         poll_seconds=float(os.environ.get(ENV_POLL_SECONDS, "2")))
 

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.4.0.dev0
+Version: 0.5.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
@@ -28,6 +28,8 @@ Requires-Dist: uvicorn>=0.30
 Requires-Dist: requests>=2.32
 Provides-Extra: redis
 Requires-Dist: redis; extra == "redis"
+Provides-Extra: entra
+Requires-Dist: msal>=1.28; extra == "entra"
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
@@ -55,7 +57,9 @@ is included); the caller is authenticated by your transport (the
 proxy-verified client certificate, by default); Gargoyle sits in front of
 your MCP server and lets through only what both agreed to.
 
-Status: pre-release (`0.4.0.dev0`). The wire format is `gargoyle/3` and may
+[![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
+
+Status: pre-release (`0.5.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
@@ -242,6 +246,8 @@ chat channel can approve anything.
 
 ## Deploy it
 
+    pip install gargoyle-receipts
+
 Three commands, no policy engine, no containers, no client changes:
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
@@ -290,6 +296,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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 |
+| issuer `GARGOYLE_ISSUER_AUDIENCE` | the `aud` an identity token must carry; a comma-separated list accepts several, so init-minted tokens (`gargoyle-issuer`) and a tenant's tokens (the issuer app's client id) work side by side |
+| `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` |
 | `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_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 |
 
@@ -298,7 +306,9 @@ cannot attach receipts work unchanged. Configuration is by environment:
 exchange for flagged calls (`/issue`, `/pending`, `/grants`, `/decline`,
 `/record`, `/keys`) and the browser approval console at `/approve`. Policy
 from a rules file or OPA; identity from a pinned key or, with
-`GARGOYLE_ENTRA_TENANT`, the tenant's signing keys.
+`GARGOYLE_ENTRA_TENANT`, the tenant's signing keys (both at once when a
+pinned key is also set, so init-minted approver tokens keep working while
+users move to `gargoyle login`).
 
 
 ## Approval holds

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ gargoyle/approver_cli.py
 gargoyle/approver_trust.py
 gargoyle/cli.py
 gargoyle/consumer.py
+gargoyle/entra_login.py
 gargoyle/envelope.py
 gargoyle/evidence.py
 gargoyle/execution.py
@@ -41,6 +42,7 @@ tests/test_cli.py
 tests/test_console_js.py
 tests/test_consumer.py
 tests/test_entra_identity.py
+tests/test_entra_login.py
 tests/test_evidence.py
 tests/test_execution.py
 tests/test_fs_server.py

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/gargoyle_receipts.egg-info/requires.txt

@@ -8,5 +8,8 @@ httpx>=0.27
 pytest>=8
 redis
 
+[entra]
+msal>=1.28
+
 [redis]
 redis

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 description = "Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -34,6 +34,7 @@ dependencies = [
 
 [project.optional-dependencies]
 redis = ["redis"]
+entra = ["msal>=1.28"]
 dev = ["httpx>=0.27", "pytest>=8", "redis"]
 
 [project.urls]

gargoyle_receipts-0.5.0.dev0/tests/test_entra_login.py

@@ -0,0 +1,126 @@
+"""`gargoyle login`: the middleware's token names a person. MSAL is faked:
+a device flow that signs in alice, a cache that persists, a silent refresh
+that works until the account is gone."""
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from gargoyle.entra_login import EntraTokenSource, LoginRequired, device_code_login, token_source_from_env
+
+
+class FakeCache:
+    def __init__(self): self.state = "{}"; self.has_state_changed = False
+    def deserialize(self, text): self.state = text
+    def serialize(self): return self.state
+
+
+class FakeMsal:
+    SerializableTokenCache = FakeCache
+
+
+class FakeApp:
+    """Enough of msal.PublicClientApplication for the two flows."""
+    sign_in_user = "alice@contoso.com"
+    refresh_ok = True
+
+    def __init__(self, client_id, authority, token_cache):
+        self.client_id, self.authority, self.cache = client_id, authority, token_cache
+        self.calls = []
+
+    def initiate_device_flow(self, scopes):
+        self.calls.append(("device_flow", scopes))
+        return {"user_code": "ABCD-1234", "message": "To sign in, use a web browser to open https://microsoft.com/devicelogin and enter the code ABCD-1234"}
+
+    def acquire_token_by_device_flow(self, flow):
+        self.cache.state = json.dumps({"accounts": [self.sign_in_user]}); self.cache.has_state_changed = True
+        return {"access_token": "at-1", "expires_in": 3600, "id_token_claims": {"preferred_username": self.sign_in_user}}
+
+    def get_accounts(self):
+        return [{"username": u} for u in json.loads(self.cache.state).get("accounts", [])]
+
+    def acquire_token_silent(self, scopes, account):
+        self.calls.append(("silent", scopes, account["username"]))
+        return {"access_token": "at-refreshed"} if self.refresh_ok else {"error": "interaction_required", "error_description": "MFA"}
+
+
+def test_device_code_login_persists_the_cache_and_names_the_user(tmp_path, capsys):
+    cache = tmp_path / "cache.json"
+    shown = []
+    r = device_code_login("contoso.onmicrosoft.com", "client-1", "api://issuer/access", str(cache),
+                          app_factory=FakeApp, msal_module=FakeMsal, prompt=shown.append)
+    assert r["principal"] == "alice@contoso.com" and r["expires_in"] == 3600
+    assert "ABCD-1234" in shown[0]
+    assert json.loads(cache.read_text())["accounts"] == ["alice@contoso.com"]
+    if os.name == "posix":
+        assert oct(cache.stat().st_mode & 0o777) == "0o600"
+
+    # The source refreshes silently from that cache, and knows who it is.
+    src = EntraTokenSource("contoso.onmicrosoft.com", "client-1", "api://issuer/access", str(cache),
+                           app_factory=FakeApp, msal_module=FakeMsal)
+    assert src.principal == "alice@contoso.com" and src.token() == "at-refreshed"
+    assert src._app.calls[-1] == ("silent", ["api://issuer/access"], "alice@contoso.com")
+
+
+def test_no_account_or_failed_refresh_is_login_required(tmp_path):
+    src = EntraTokenSource("t", "c", "s", str(tmp_path / "empty.json"), app_factory=FakeApp, msal_module=FakeMsal)
+    with pytest.raises(LoginRequired):
+        src.token()
+    cache = tmp_path / "cache.json"
+    device_code_login("t", "c", "s", str(cache), app_factory=FakeApp, msal_module=FakeMsal, prompt=lambda m: None)
+
+    class Stale(FakeApp):
+        refresh_ok = False
+    with pytest.raises(LoginRequired, match="MFA"):
+        EntraTokenSource("t", "c", "s", str(cache), app_factory=Stale, msal_module=FakeMsal).token()
+
+
+def test_middleware_refuses_with_login_required_and_uses_a_fresh_token_per_call(tmp_path):
+    from gargoyle.mcp_server import REF_TARGET_LOGIN_REQUIRED, IssuerClient
+    cache = tmp_path / "cache.json"
+    device_code_login("t", "c", "s", str(cache), app_factory=FakeApp, msal_module=FakeMsal, prompt=lambda m: None)
+    seen = []
+
+    class Http:
+        def post(self, url, json=None, headers=None, timeout=None):
+            seen.append(headers["Authorization"])
+            return type("R", (), {"status_code": 200, "headers": {}, "json": lambda self: {"issued": True, "envelope": {"x": 1}}})()
+    src = EntraTokenSource("t", "c", "s", str(cache), app_factory=FakeApp, msal_module=FakeMsal)
+    client = IssuerClient("http://i", src, http=Http())
+    assert client.issue("mcp://x", "read_file", {})["envelope"] == {"x": 1}
+    assert seen == ["Bearer at-refreshed"]
+    empty = EntraTokenSource("t", "c", "s", str(tmp_path / "none.json"), app_factory=FakeApp, msal_module=FakeMsal)
+    assert IssuerClient("http://i", empty, http=Http()).issue("mcp://x", "read_file", {})["reason"] == REF_TARGET_LOGIN_REQUIRED
+
+
+def test_token_source_from_env_requires_the_whole_set():
+    assert token_source_from_env({}) is None
+    with pytest.raises(RuntimeError):
+        token_source_from_env({"GARGOYLE_MCP_ENTRA_TENANT": "t"})
+
+
+def test_login_command_rewrites_the_client_config(tmp_path, monkeypatch, capsys):
+    from gargoyle import cli
+    from gargoyle import entra_login
+    out = tmp_path / "deploy"
+    assert cli.main(["init", str(tmp_path / "p"), "--out", str(out), "--entra-tenant", "contoso.onmicrosoft.com",
+                     "--entra-audience", "api-client-id"]) == 0
+    ienv = cli._read_env(out / "issuer.env")
+    assert ienv["GARGOYLE_ENTRA_TENANT"] == "contoso.onmicrosoft.com" and ienv["GARGOYLE_ISSUER_AUDIENCE"] == "api-client-id"
+    before = cli._read_env(out / "middleware.env"); assert "GARGOYLE_MCP_CLIENT_TOKEN" in before
+    monkeypatch.setattr(entra_login, "_msal", lambda: FakeMsal)
+    monkeypatch.setattr(entra_login, "_app", lambda tenant, client_id, cache, app_factory=None: FakeApp(client_id, tenant, cache.cache))
+    assert cli.main(["login", "--tenant", "contoso.onmicrosoft.com", "--client-id", "pub-client", "--scope", "api://api-client-id/access",
+                     "--out", str(out)]) == 0
+    env = cli._read_env(out / "middleware.env")
+    assert "GARGOYLE_MCP_CLIENT_TOKEN" not in env
+    assert env["GARGOYLE_MCP_PRINCIPAL"] == "alice@contoso.com" and env["GARGOYLE_MCP_ENTRA_CLIENT_ID"] == "pub-client"
+    assert env["GARGOYLE_MCP_ENTRA_TOKEN_CACHE"] == str(out / "entra-token-cache.json")
+    mcp = json.loads((out / "mcp-config.json").read_text())["mcpServers"]["filesystem-gargoyle"]["env"]
+    assert "GARGOYLE_MCP_CLIENT_TOKEN" not in mcp and mcp["GARGOYLE_MCP_PRINCIPAL"] == "alice@contoso.com"
+    assert "signed in as alice@contoso.com" in capsys.readouterr().out
+    # Everything the middleware needs to pick the Entra source is there.
+    for k in ("GARGOYLE_MCP_ENTRA_TENANT", "GARGOYLE_MCP_ENTRA_CLIENT_ID", "GARGOYLE_MCP_ENTRA_SCOPE", "GARGOYLE_MCP_ENTRA_TOKEN_CACHE"):
+        assert env[k] and mcp[k] == env[k]

{gargoyle_receipts-0.4.0.dev0 → gargoyle_receipts-0.5.0.dev0}/tests/test_identity.py

@@ -61,3 +61,9 @@ def test_identity_flows_into_the_receipt():
                                         "on_behalf_of": who["on_behalf_of"]}, signing_key=key, key_id="k1")
     assert r.envelope["request_context"]["principal"] == "agent-7"
     assert r.envelope["request_context"]["on_behalf_of"] == "user-42"
+
+
+def test_several_audiences_are_accepted_as_a_list_or_comma_string():
+    assert principal_from_token(token(sub="agent-7", aud="gargoyle-issuer"), IDP, audience="gargoyle-issuer,88d5", now=NOW)["reason"] is None
+    assert principal_from_token(token(sub="agent-7", aud="88d5"), IDP, audience="gargoyle-issuer, 88d5", now=NOW)["reason"] is None
+    assert principal_from_token(token(sub="agent-7", aud="other"), IDP, audience=["gargoyle-issuer", "88d5"], now=NOW)["reason"] == REF_JWS_AUDIENCE_MISMATCH