gargoyle-receipts 0.15.0.dev0__tar.gz → 0.16.0.dev0__tar.gz

{gargoyle_receipts-0.15.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.16.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.15.0.dev0
+Version: 0.16.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
@@ -25,7 +25,7 @@ License-File: NOTICE
 Requires-Dist: cryptography>=44.0.0
 Requires-Dist: fastapi>=0.115
 Requires-Dist: uvicorn>=0.30
-Requires-Dist: requests>=2.32
+Requires-Dist: requests>=2.32.3
 Provides-Extra: redis
 Requires-Dist: redis; extra == "redis"
 Provides-Extra: entra
@@ -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.15.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.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
@@ -221,7 +221,9 @@ chain["accepted"], chain["steps"]   # True, [("authorization", ...), ("approval"
 That is the sentence Gargoyle can say that nobody else can: a specific
 policy version authorized a specific call for a specific principal, a
 human's key released it, and exactly that call ran once, verifiable offline
-by anyone, in Python or TypeScript.
+by anyone. The receipt, grant and execution receipt verify in Python or
+TypeScript against the same vectors; the evidence log, the witness, plans
+and the older formats verify in Python.
 
 A held call is approved against the state it was shown in. Before asking
 for the receipt the middleware hashes the target (a file's bytes, or its
@@ -288,7 +290,14 @@ the page shows each held call with its full arguments, checked against
 the receipt, and signs the grant locally with WebCrypto. The key never
 leaves the browser, and with Entra it is generated there, non-exportable,
 and enrolled under the approver's UPN, so grants and audits name the
-person. Then paste the server entry from
+person. An approver retires a lost or replaced key with
+`POST /approvers/revoke` from their own sign-in; the operator revokes
+anyone with `gargoyle approvers revoke <upn>` on the issuer's host, and
+the running service picks the change up without a restart. Revoked keys
+stay on file so earlier grants still audit; new ones are refused at the
+issuer and at every middleware on its next held call. Approvers, and
+only approvers, see the whole queue and the witness; everyone else sees
+their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.
 [docs/guide-hyperv-ubuntu-apache.md](docs/guide-hyperv-ubuntu-apache.md)
 is the full single-instance build: Ubuntu VM on Hyper-V, Apache with TLS,
@@ -378,7 +387,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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` |
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
-| issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
+| issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys, with a `revoked` list; `gargoyle approvers list|revoke`) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
+| issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.16.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.15.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.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
@@ -183,7 +183,9 @@ chain["accepted"], chain["steps"]   # True, [("authorization", ...), ("approval"
 That is the sentence Gargoyle can say that nobody else can: a specific
 policy version authorized a specific call for a specific principal, a
 human's key released it, and exactly that call ran once, verifiable offline
-by anyone, in Python or TypeScript.
+by anyone. The receipt, grant and execution receipt verify in Python or
+TypeScript against the same vectors; the evidence log, the witness, plans
+and the older formats verify in Python.
 
 A held call is approved against the state it was shown in. Before asking
 for the receipt the middleware hashes the target (a file's bytes, or its
@@ -250,7 +252,14 @@ the page shows each held call with its full arguments, checked against
 the receipt, and signs the grant locally with WebCrypto. The key never
 leaves the browser, and with Entra it is generated there, non-exportable,
 and enrolled under the approver's UPN, so grants and audits name the
-person. Then paste the server entry from
+person. An approver retires a lost or replaced key with
+`POST /approvers/revoke` from their own sign-in; the operator revokes
+anyone with `gargoyle approvers revoke <upn>` on the issuer's host, and
+the running service picks the change up without a restart. Revoked keys
+stay on file so earlier grants still audit; new ones are refused at the
+issuer and at every middleware on its next held call. Approvers, and
+only approvers, see the whole queue and the witness; everyone else sees
+their own holds. Then paste the server entry from
 `gargoyle-deploy/mcp-config.json` into your MCP client.
 [docs/guide-hyperv-ubuntu-apache.md](docs/guide-hyperv-ubuntu-apache.md)
 is the full single-instance build: Ubuntu VM on Hyper-V, Apache with TLS,
@@ -340,7 +349,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | 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` |
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
-| issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
+| issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys, with a `revoked` list; `gargoyle approvers list|revoke`) and which Entra app role (default `Approver`) or groups may enroll, see every hold and the witness |
+| issuer `GARGOYLE_ENTRA_TENANT` + `GARGOYLE_ISSUER_AUDIENCE` | trust the tenant's tokens; the audience is required with a tenant (the service will not start without it), and a directory token for any other tenant is `REF_IDENTITY_WRONG_TENANT` |
 | issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.16.0.dev0}/gargoyle/approvers.py

@@ -47,26 +47,57 @@ class ApproverRegistry:
         self.path = Path(path) if path else None
         self._lock = threading.Lock()
         self._approvers: Dict[str, Dict[str, Any]] = {}
-        if self.path is not None and self.path.exists():
-            doc = json.loads(self.path.read_text(encoding="utf-8"))
-            for upn, entry in (doc.get("approvers") or {}).items():
-                if isinstance(entry, dict) and valid_public_key_hex(entry.get("public_key_hex")):
-                    self._approvers[upn] = dict(entry)
+        self._revoked: Dict[str, Dict[str, Any]] = {}      # former approvers, kept so old grants still verify in audits
+        self._mtime: Optional[float] = None
+        self._load()
+
+    def _load(self) -> None:
+        if self.path is None or not self.path.exists():
+            return
+        doc = json.loads(self.path.read_text(encoding="utf-8"))
+        approvers, revoked = {}, {}
+        for upn, entry in (doc.get("approvers") or {}).items():
+            if isinstance(entry, dict) and valid_public_key_hex(entry.get("public_key_hex")):
+                approvers[upn] = dict(entry)
+        for upn, entry in (doc.get("revoked") or {}).items():
+            if isinstance(entry, dict) and valid_public_key_hex(entry.get("public_key_hex")):
+                revoked[upn] = dict(entry)
+        self._approvers, self._revoked = approvers, revoked
+        self._mtime = self.path.stat().st_mtime
+
+    def _refresh(self) -> None:
+        """Re-read the file when something else wrote it: `gargoyle approvers
+        revoke` on the issuer's host takes effect without a restart."""
+        if self.path is None:
+            return
+        try:
+            mtime = self.path.stat().st_mtime
+        except OSError:
+            return
+        if mtime != self._mtime:
+            self._load()
 
     def _save(self) -> None:
         if self.path is None:
             return
         self.path.parent.mkdir(parents=True, exist_ok=True)
-        self.path.write_text(json.dumps({"approvers": self._approvers}, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        doc = {"approvers": self._approvers}
+        if self._revoked:
+            doc["revoked"] = self._revoked
+        self.path.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
         try:
             os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
         except OSError:
             pass
+        self._mtime = self.path.stat().st_mtime
 
     def enroll(self, upn: str, public_key_hex: str, *, enrolled_by: Optional[str] = None,
-               now: Optional[datetime] = None) -> Dict[str, Any]:
+               now: Optional[datetime] = None, oid: Optional[str] = None, tid: Optional[str] = None) -> Dict[str, Any]:
         """Bind `upn` to `public_key_hex`, replacing any earlier key for that
-        UPN (one key per approver; a new browser re-enrolls)."""
+        UPN (one key per approver; a new browser re-enrolls). The directory's
+        immutable object id and tenant id are kept beside the UPN when the
+        token carried them: the UPN is the name people read, the oid is what
+        survives a rename."""
         if not isinstance(upn, str) or not upn:
             raise ValueError("upn must be a non-empty string")
         if not valid_public_key_hex(public_key_hex):
@@ -74,14 +105,36 @@ class ApproverRegistry:
         entry = {"public_key_hex": public_key_hex,
                  "enrolled_at": (now or datetime.now(timezone.utc)).isoformat(),
                  "enrolled_by": enrolled_by or upn}
+        if oid:
+            entry["oid"] = oid
+        if tid:
+            entry["tid"] = tid
         with self._lock:
+            self._refresh()
             replaced = upn in self._approvers
             self._approvers[upn] = entry
+            self._revoked.pop(upn, None)            # enrolling again after a revocation is a fresh key
             self._save()
         return {"upn": upn, "replaced": replaced, **entry}
 
+    def revoke(self, upn: str, *, revoked_by: Optional[str] = None, now: Optional[datetime] = None) -> bool:
+        """Stop trusting `upn`'s key from now on. The entry moves to the
+        revoked list with when and by whom, so an audit of earlier evidence
+        can still verify the grants it signed; the issuer and the
+        middleware stop accepting new ones at once."""
+        with self._lock:
+            self._refresh()
+            entry = self._approvers.pop(upn, None)
+            if entry is None:
+                return False
+            self._revoked[upn] = {**entry, "revoked_at": (now or datetime.now(timezone.utc)).isoformat(),
+                                  "revoked_by": revoked_by or upn}
+            self._save()
+        return True
+
     def remove(self, upn: str) -> bool:
         with self._lock:
+            self._refresh()
             gone = self._approvers.pop(upn, None) is not None
             if gone:
                 self._save()
@@ -90,15 +143,31 @@ class ApproverRegistry:
     def public_hex(self) -> Dict[str, str]:
         """{upn: public_key_hex}, what GET /approvers publishes."""
         with self._lock:
+            self._refresh()
             return {upn: e["public_key_hex"] for upn, e in self._approvers.items()}
 
+    def revoked_hex(self) -> Dict[str, str]:
+        """{upn: public_key_hex} of revoked approvers: for verifying the
+        grants they signed while trusted, never for accepting new ones."""
+        with self._lock:
+            self._refresh()
+            return {upn: e["public_key_hex"] for upn, e in self._revoked.items()}
+
+    def entries(self) -> Dict[str, Dict[str, Any]]:
+        """Every current approver's record, for `gargoyle approvers list`."""
+        with self._lock:
+            self._refresh()
+            return {upn: dict(e) for upn, e in self._approvers.items()}
+
     def keys(self) -> Dict[str, Any]:
         """{upn: Ed25519PublicKey}, the map a verifier uses."""
         from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
         return {upn: Ed25519PublicKey.from_public_bytes(bytes.fromhex(h)) for upn, h in self.public_hex().items()}
 
     def __contains__(self, upn: str) -> bool:
-        return upn in self._approvers
+        with self._lock:
+            self._refresh()
+            return upn in self._approvers
 
 
 def may_enroll(who: Dict[str, Any], *, role: str = DEFAULT_APPROVER_ROLE, groups: Optional[list] = None) -> bool:

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.16.0.dev0}/gargoyle/cli.py

@@ -43,6 +43,8 @@ import os
 import re
 import stat
 import sys
+
+from gargoyle.approvers import DEFAULT_APPROVER_ROLE
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
@@ -107,7 +109,11 @@ def cmd_init(args) -> int:
     executor, executor_hex, executor_pub = new_key()
     exp = int((datetime.now(timezone.utc) + timedelta(days=args.token_days)).timestamp())
     client_token = encode({"sub": PRINCIPAL, "aud": "gargoyle-issuer", "exp": exp}, idp, "idp-1")
-    approver_token = encode({"sub": "approver", "aud": "gargoyle-issuer", "exp": exp}, idp, "idp-1")
+    # One identity token per approver, named by the key id it travels with and
+    # carrying the approver role: the issuer shows the whole queue to approvers
+    # and only a person's own holds to anyone else.
+    def approver_token_for(kid: str) -> str:
+        return encode({"sub": kid, "roles": [DEFAULT_APPROVER_ROLE], "aud": "gargoyle-issuer", "exp": exp}, idp, "idp-1")
     issuer_url = args.issuer_url or "http://%s:%d" % (args.host, args.port)
 
     rules = out / "rules.json"
@@ -135,6 +141,7 @@ def cmd_init(args) -> int:
     _write(out / "middleware.env", _env_lines(middleware_env), private=True)
     b64url = lambda b: __import__("base64").urlsafe_b64encode(b).rstrip(b"=").decode()
     for n, (kid, _k, khex, kpub) in enumerate(approvers, 1):
+        approver_token = approver_token_for(kid)
         # approver.env / approver-web.json for the first; -2, -3 ... for the others.
         suffix = "" if n == 1 else "-%d" % n
         _write(out / ("approver%s.env" % suffix), _env_lines({
@@ -173,7 +180,9 @@ WantedBy=multi-user.target
     ProxyPass        / http://127.0.0.1:%(port)d/
     ProxyPassReverse / http://127.0.0.1:%(port)d/
     ErrorLog  ${APACHE_LOG_DIR}/gargoyle-error.log
-    CustomLog ${APACHE_LOG_DIR}/gargoyle-access.log combined
+    # Remote-mode capability URLs carry a bearer token in the path; keep them out of the access log.
+    SetEnvIf Request_URI "^/mcp/" gargoyle_capability_url
+    CustomLog ${APACHE_LOG_DIR}/gargoyle-access.log combined env=!gargoyle_capability_url
 </VirtualHost>
 """ % {"host": (args.issuer_url or "gargoyle.example").replace("https://", "").replace("http://", "").split("/")[0].split(":")[0], "port": args.port})
     upstream = (["npx", "-y", "@modelcontextprotocol/server-filesystem", allowed] if args.upstream == "npx-filesystem"
@@ -321,6 +330,33 @@ def cmd_approve(args) -> int:
     return approver_main(argv)
 
 
+def cmd_approvers(args) -> int:
+    """List the enrolled approvers, or revoke one. Works on the issuer's
+    approvers.json; the running service re-reads the file, so a revocation
+    takes effect without a restart and reaches the middleware at its next
+    held call."""
+    from gargoyle.approvers import ApproverRegistry
+
+    reg = ApproverRegistry(str(Path(args.out).resolve() / "approvers.json"))
+    if args.action == "list":
+        entries = reg.entries()
+        if not entries:
+            print("no enrolled approvers (configured approver keys are in issuer.env)")
+        for upn, e in sorted(entries.items()):
+            print("%s  enrolled %s  key %s%s" % (upn, e.get("enrolled_at", "?"), e["public_key_hex"][:16],
+                                                  ("  oid " + e["oid"]) if e.get("oid") else ""))
+        revoked = reg.revoked_hex()
+        if revoked:
+            print("revoked: " + ", ".join(sorted(revoked)))
+        return 0
+    import getpass
+    if reg.revoke(args.upn, revoked_by="operator:" + getpass.getuser()):
+        print("revoked %s; grants under that key are refused from now on, earlier ones still audit" % args.upn)
+        return 0
+    print("%s is not an enrolled approver" % args.upn, file=sys.stderr)
+    return 1
+
+
 def cmd_audit(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
     from gargoyle.execution import verify_chain
@@ -330,7 +366,11 @@ def cmd_audit(args) -> int:
     approvers = dict(keys["approver"])
     enrolled = Path(args.out).resolve() / "approvers.json"          # approvers who enrolled through Entra, by UPN
     if enrolled.exists():
-        approvers.update({u: e["public_key_hex"] for u, e in json.loads(enrolled.read_text()).get("approvers", {}).items()})
+        doc = json.loads(enrolled.read_text())
+        # Revoked approvers too: the audit verifies what was signed while they
+        # were trusted. Only the live service and middleware refuse them.
+        approvers.update({u: e["public_key_hex"] for u, e in doc.get("revoked", {}).items()})
+        approvers.update({u: e["public_key_hex"] for u, e in doc.get("approvers", {}).items()})
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
                  approver_public_keys=load(approvers))
     if args.log:
@@ -454,9 +494,14 @@ def main(argv=None) -> int:
     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("--days", type=int, default=30, help="lifetime of the identity token inside the capability URL (default 30)")
     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("approvers", help="list enrolled approvers, or revoke one on the issuer's host")
+    p.add_argument("action", choices=["list", "revoke"])
+    p.add_argument("upn", nargs="?", help="the approver to revoke")
+    p.add_argument("--out", default="gargoyle-deploy")
+    p.set_defaults(fn=cmd_approvers)
     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.15.0.dev0 → gargoyle_receipts-0.16.0.dev0}/gargoyle/identity.py

@@ -32,15 +32,38 @@ entra_keys (fetched from the tenant's discovery endpoint; cache and
 refresh on an unknown kid, as every OIDC client does).
 """
 
+import re
 from datetime import datetime, timezone
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Set
 
 from gargoyle.jws import (
     IDENTITY_ALGS, REF_JWS_AUDIENCE_MISMATCH, REF_JWS_EXPIRED, REF_JWS_MALFORMED, decode, keys_from_jwks,
 )
 
 REF_IDENTITY_NO_SUBJECT = "REF_IDENTITY_NO_SUBJECT"
+REF_IDENTITY_WRONG_TENANT = "REF_IDENTITY_WRONG_TENANT"     # a directory token for some other tenant, or one that names none
 ENTRA_JWKS_URL = "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys"
+ENTRA_OPENID_URL = "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"
+_GUID = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+
+
+def entra_tenant_id(tenant: str, *, http: Any = None, timeout: float = 10.0) -> str:
+    """The tenant id (a GUID) for a tenant given by id or by domain. Tokens
+    name their tenant by id in `tid`, so the check in principal_from_token
+    needs the id; a domain is resolved once, from the tenant's OpenID
+    configuration, at startup. Raises on transport failure."""
+    if _GUID.match(tenant):
+        return tenant.lower()
+    import requests
+    http = http if http is not None else requests
+    r = http.get(ENTRA_OPENID_URL.format(tenant=tenant), timeout=timeout)
+    if r.status_code != 200:
+        raise RuntimeError("OpenID configuration fetch returned %s" % r.status_code)
+    issuer = r.json().get("issuer") or ""
+    m = re.search(r"/([0-9a-fA-F-]{36})/", issuer)
+    if not m or not _GUID.match(m.group(1)):
+        raise RuntimeError("OpenID configuration for %s names no tenant id: %r" % (tenant, issuer))
+    return m.group(1).lower()
 
 
 def entra_keys(tenant: str, *, http: Any = None, timeout: float = 10.0) -> Dict[str, Any]:
@@ -77,9 +100,18 @@ def _innermost_actor(act: Any) -> Optional[str]:
 
 
 def principal_from_token(token: str, public_keys: Dict[str, Any], *,
-                         audience: Any = None, now: Optional[datetime] = None) -> Dict[str, Any]:
+                         audience: Any = None, now: Optional[datetime] = None,
+                         tenant: Optional[str] = None, tenant_key_ids: Optional[Set[str]] = None) -> Dict[str, Any]:
     """{"principal", "on_behalf_of" (or None), "claims", "reason": None} for
-    a trusted identity token, or {"principal": None, "reason": code}."""
+    a trusted identity token, or {"principal": None, "reason": code}.
+
+    `tenant` (a tenant id) makes the token's `tid` part of trust: a token
+    signed by one of `tenant_key_ids` (the keys fetched from the directory;
+    every key when None) must carry that tid, and its `iss`, when present,
+    must name it. Directory signing keys are shared across tenants, so a
+    valid signature alone says only that some tenant issued the token.
+    Tokens under other trusted keys (a pinned key `gargoyle init` wrote)
+    name no tenant and are not held to one."""
     res = decode(token, public_keys, allowed_algs=IDENTITY_ALGS)
     if res["reason"] is not None:
         return {"principal": None, "reason": res["reason"]}
@@ -97,6 +129,10 @@ def principal_from_token(token: str, public_keys: Dict[str, Any], *,
         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}
+    if tenant is not None and (tenant_key_ids is None or res["header"].get("kid") in tenant_key_ids):
+        tid = _nonempty(claims.get("tid")); iss = _nonempty(claims.get("iss"))
+        if tid is None or tid.lower() != tenant.lower() or (iss is not None and tenant.lower() not in iss.lower()):
+            return {"principal": None, "reason": REF_IDENTITY_WRONG_TENANT}
 
     # OIDC providers' `sub` is opaque; the UPN is the identity people and
     # rules recognise.
@@ -115,4 +151,4 @@ def principal_from_token(token: str, public_keys: Dict[str, Any], *,
         return {"principal": None, "reason": REF_IDENTITY_NO_SUBJECT}
     return {"principal": principal, "on_behalf_of": on_behalf_of, "claims": claims, "reason": None,
             "groups": _string_list(claims.get("groups")), "roles": _string_list(claims.get("roles")),
-            "oid": _nonempty(claims.get("oid"))}
+            "oid": _nonempty(claims.get("oid")), "tid": _nonempty(claims.get("tid"))}

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.16.0.dev0}/gargoyle/issuer_service.py

@@ -61,7 +61,7 @@ from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF
 from gargoyle.notify import notifier_from_env
 from gargoyle.approvers import (DEFAULT_APPROVER_ROLE, ENV_APPROVER_GROUPS, ENV_APPROVER_ROLE, ENV_APPROVERS_PATH,
                                 ApproverRegistry, may_enroll, valid_public_key_hex)
-from gargoyle.identity import entra_keys, principal_from_token
+from gargoyle.identity import entra_keys, entra_tenant_id, principal_from_token
 from gargoyle.issuer import DEFAULT_TTL_SECONDS, issue
 from gargoyle.policy import Policy
 
@@ -86,6 +86,7 @@ REF_ISSUER_ARGS_NOT_TEXT = "REF_ISSUER_ARGS_NOT_TEXT"   # arguments carry charac
 REF_ISSUER_UNKNOWN_HOLD = "REF_ISSUER_UNKNOWN_HOLD"
 REF_ISSUER_NO_APPROVER_TRUST = "REF_ISSUER_NO_APPROVER_TRUST"
 REF_ISSUER_NOT_AN_APPROVER = "REF_ISSUER_NOT_AN_APPROVER"   # enrollment without the approver role or group
+REF_ISSUER_FORBIDDEN = "REF_ISSUER_FORBIDDEN"               # authenticated, but not an approver and not the hold's own principal
 
 
 def build_issuer_app(
@@ -106,6 +107,8 @@ def build_issuer_app(
     hold_store: Optional[HoldStore] = None,
     log_events: Optional[Callable[[Dict[str, Any]], None]] = None,
     witness: Optional[WitnessLog] = None,
+    tenant: Optional[str] = None,
+    tenant_key_ids: Optional[set] = None,
 ) -> FastAPI:
     """`on_hold(envelope, args)` is called once for every new hold (gargoyle.notify
     posts it to a webhook); it is notice, not admission, and its failure
@@ -147,13 +150,28 @@ def build_issuer_app(
         """Static keys from configuration plus every enrolled approver, by UPN."""
         return {**static_approvers, **registry.keys()}
 
+    def is_approver(who: Dict[str, Any]) -> bool:
+        """May this identity see every hold and the witness: the approver role
+        or group, a configured approver key id, or an enrolled approver."""
+        upn = who["principal"]
+        return may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers or upn in registry
+
+    def hold_owner(arid: str) -> Optional[str]:
+        """The principal whose call is held under `arid` (a hold or a plan), or None."""
+        env = app.state.pending.get(arid)
+        if env is not None:
+            return env.get("request_context", {}).get("principal")
+        plan = app.state.pending_plans.get(arid)
+        return plan.get("principal") if plan is not None else None
+
     def _refuse(status: int, reason: str) -> HTTPException:
         return HTTPException(status_code=status, detail={"reason": reason})
 
     def authenticate(authorization: Optional[str]) -> Dict[str, Any]:
         if not authorization or not authorization.startswith("Bearer "):
             raise _refuse(401, REF_ISSUER_UNAUTHENTICATED)
-        who = principal_from_token(authorization[7:].strip(), idp_public_keys, audience=audience, now=now())
+        who = principal_from_token(authorization[7:].strip(), idp_public_keys, audience=audience, now=now(),
+                                   tenant=tenant, tenant_key_ids=tenant_key_ids)
         if who["reason"] is not None:
             raise _refuse(401, who["reason"])
         return who
@@ -211,6 +229,7 @@ def build_issuer_app(
                     covered = True
                     break
         event("issued", principal=who["principal"], tool=body["tool"], held=bool(result.envelope["requires_approval"]),
+              **({"oid": who["oid"]} if who.get("oid") else {}),
               covered=covered, decision_id=result.envelope.get("decision_id"), decision_sha256=result.envelope["decision_sha256"],
               approval_request_id=result.envelope.get("approval_request_id"), args_sha256=result.envelope["request_context"]["args_sha256"])
         if result.envelope["requires_approval"] and not covered:
@@ -286,7 +305,11 @@ def build_issuer_app(
 
     @app.get("/pending")
     async def pending(authorization: Optional[str] = Header(default=None)):
-        authenticate(authorization)
+        """Approvers see every hold with its arguments; anyone else sees only
+        the holds on their own calls. Held arguments are often file contents,
+        and one user's are not another's to read."""
+        who = authenticate(authorization)
+        sees_all = is_approver(who)
         current = now()
         live = {}
         for arid, plan in list(app.state.pending_plans.items()):
@@ -294,6 +317,8 @@ def build_issuer_app(
                 del app.state.pending_plans[arid]
                 app.state.grants.pop(arid, None)
             elif len(app.state.grants.get(arid, [])) < _plan_terms(plan)["required"]:
+                if not sees_all and plan.get("principal") != who["principal"]:
+                    continue
                 have = app.state.grants.get(arid, [])
                 live[arid] = {"plan": plan, "collected": len(have), "required": _plan_terms(plan)["required"],
                               "approvers": [g["approver_key_id"] for g in have]}
@@ -304,6 +329,8 @@ def build_issuer_app(
                 app.state.pending_state.pop(arid, None)
                 app.state.grants.pop(arid, None)
             elif not _complete(arid):
+                if not sees_all and env.get("request_context", {}).get("principal") != who["principal"]:
+                    continue
                 have = app.state.grants.get(arid, [])
                 live[arid] = {"envelope": env, "args": app.state.pending_args.get(arid),
                               "state": app.state.pending_state.get(arid),
@@ -364,6 +391,8 @@ def build_issuer_app(
         arid = body.get("approval_request_id") if isinstance(body, dict) else None
         if not isinstance(arid, str) or (arid not in app.state.pending and arid not in app.state.pending_plans):
             return {"declined": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
+        if not is_approver(who) and hold_owner(arid) != who["principal"]:
+            raise _refuse(403, REF_ISSUER_FORBIDDEN)      # only an approver, or the person whose call it is, may cancel it
         app.state.pending_plans.pop(arid, None)
         app.state.pending.pop(arid, None)
         app.state.pending_args.pop(arid, None)
@@ -406,10 +435,32 @@ def build_issuer_app(
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         if not isinstance(body, dict) or not valid_public_key_hex(body.get("public_key_hex")):
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
-        result = registry.enroll(who["principal"], body["public_key_hex"], now=now())
-        event("enrolled", approver=who["principal"], replaced=result["replaced"])
+        result = registry.enroll(who["principal"], body["public_key_hex"], now=now(), oid=who.get("oid"), tid=who.get("tid"))
+        event("enrolled", approver=who["principal"], replaced=result["replaced"], oid=who.get("oid"))
         return {"enrolled": True, "key_id": who["principal"], "replaced": result["replaced"]}
 
+    @app.post("/approvers/revoke")
+    async def revoke(request: Request, authorization: Optional[str] = Header(default=None)):
+        """An approver retires their own key (a lost or replaced device): from
+        now on grants under it are refused here and at every middleware that
+        asks this service for approver keys. Revoking someone else is the
+        operator's act, done on the host with `gargoyle approvers revoke`,
+        so that one compromised approver cannot remove the others."""
+        who = authenticate(authorization)
+        try:
+            body = await request.json()
+        except Exception:
+            raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        upn = body.get("upn") if isinstance(body, dict) else None
+        if not isinstance(upn, str) or not upn:
+            raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        if upn != who["principal"]:
+            raise _refuse(403, REF_ISSUER_FORBIDDEN)
+        gone = registry.revoke(upn, revoked_by=who["principal"], now=now())
+        if gone:
+            event("revoked", approver=upn, by=who["principal"])
+        return {"revoked": gone}
+
     @app.get("/me")
     async def me(authorization: Optional[str] = Header(default=None)):
         """Who the console is signed in as, whether they may approve, and
@@ -422,8 +473,10 @@ def build_issuer_app(
 
     @app.get("/witness")
     async def witness_entries(authorization: Optional[str] = Header(default=None)):
-        """The issuer's signed witness log, for reconciliation with a client's evidence."""
-        authenticate(authorization)
+        """The issuer's signed witness log, for reconciliation with a client's
+        evidence. It names every user's decisions, so it is for approvers."""
+        if not is_approver(authenticate(authorization)):
+            raise _refuse(403, REF_ISSUER_FORBIDDEN)
         return {"entries": list(witness.entries) if witness is not None else []}
 
     @app.get("/health")
@@ -475,6 +528,13 @@ def app_from_env() -> FastAPI:
     missing = [k for k, v in required.items() if not v]
     if missing:
         raise RuntimeError("issuer service needs " + ", ".join(missing))
+    if tenant and not os.environ.get(ENV_AUDIENCE):
+        # Fail closed: without an audience, any token the tenant ever issued
+        # for any application would be accepted here.
+        raise RuntimeError("issuer service with %s set needs %s (the issuer API's client id or app id URI)"
+                           % (ENV_ENTRA_TENANT, ENV_AUDIENCE))
+    tenant_id = entra_tenant_id(tenant) if tenant else None
+    tenant_keys = entra_keys(tenant_id) if tenant else {}
     rules_path = os.environ.get(ENV_RULES_PATH)
     if rules_path:
         from gargoyle.rules import RulesPolicy
@@ -502,7 +562,7 @@ def app_from_env() -> FastAPI:
         # 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 {}),
+        idp_public_keys={**tenant_keys,
                          **({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,
@@ -516,6 +576,8 @@ def app_from_env() -> FastAPI:
         approver_registry=ApproverRegistry(os.environ.get(ENV_APPROVERS_PATH)),
         approver_role=os.environ.get(ENV_APPROVER_ROLE, DEFAULT_APPROVER_ROLE),
         approver_groups=[g.strip() for g in os.environ.get(ENV_APPROVER_GROUPS, "").split(",") if g.strip()] or None,
+        tenant=tenant_id,
+        tenant_key_ids=set(tenant_keys) if tenant else None,
         console_entra=({"tenant": tenant, "client_id": os.environ[ENV_CONSOLE_CLIENT_ID],
                         "scope": os.environ.get(ENV_CONSOLE_SCOPE) or "api://%s/access" % (os.environ.get(ENV_AUDIENCE) or "").split(",")[-1].strip()}
                        if tenant and os.environ.get(ENV_CONSOLE_CLIENT_ID) else None),