gargoyle-receipts 0.5.2.dev0__tar.gz → 0.6.0.dev0__tar.gz

{gargoyle_receipts-0.5.2.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.6.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.5.2.dev0
+Version: 0.6.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.5.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.6.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
@@ -255,9 +255,12 @@ Three commands, no policy engine, no containers, no client changes:
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
 or approve in a browser: open the issuer's `/approve` page and load
-`approver-web.json`; 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. Then paste the server entry from
+`approver-web.json`, or, with Entra configured, sign in with Microsoft;
+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
 `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,
@@ -298,6 +301,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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` |
+| 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 |
 | `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 |
 

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.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.5.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.6.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
@@ -217,9 +217,12 @@ Three commands, no policy engine, no containers, no client changes:
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 
 or approve in a browser: open the issuer's `/approve` page and load
-`approver-web.json`; 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. Then paste the server entry from
+`approver-web.json`, or, with Entra configured, sign in with Microsoft;
+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
 `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,
@@ -260,6 +263,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `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` |
+| 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 |
 | `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 |
 

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/approval.py

@@ -19,7 +19,7 @@ grant_id is present, so that claim cannot be skipped.
 from datetime import datetime, timedelta
 from typing import Any, Dict, List, Optional
 
-from gargoyle.envelope import approval_terms, canonical_json
+from gargoyle.envelope import approval_terms, canonical_json, serializer_for
 from gargoyle.verifier import not_after_valid
 
 
@@ -129,8 +129,11 @@ def verify_grant(
     gate_key_id: str,
     now: Optional[datetime] = None,
     clock_skew: timedelta = timedelta(0),
+    serializer: Any = None,
 ) -> Dict[str, Any]:
-    """Is `grant` a valid human release of the held decision?
+    """Is `grant` a valid human release of the held decision? `serializer`
+    is the canonical form the grant was signed under (default: the current
+    one; an audit of a historical receipt passes its format's).
 
     Returns {"accepted", "reason"}. First failure wins:
       1. structure                          -> REF_APPROVAL_MALFORMED
@@ -180,7 +183,7 @@ def verify_grant(
 
     # 5. signature verifies (duck-typed; covers everything but the signature)
     region = {k: v for k, v in grant.items() if k not in _SIGNATURE_EXCLUDED_KEYS}
-    message = canonical_json(region).encode("utf-8")
+    message = (serializer or canonical_json)(region).encode("utf-8")
     try:
         public_key.verify(bytes.fromhex(signature_hex), message)
     except Exception:
@@ -236,6 +239,7 @@ def verify_grants(
     with the grants that were counted, so the caller can claim each one."""
     terms = approval_terms(envelope)
     items = as_grant_list(grants)
+    serializer = serializer_for(envelope.get("envelope_version")) or canonical_json
     seen: List[str] = []
     for grant in items:
         g = verify_grant(
@@ -246,6 +250,7 @@ def verify_grants(
             gate_key_id=envelope.get("issuer_key_id"),
             now=now,
             clock_skew=clock_skew,
+            serializer=serializer,
         )
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"], "grants": []}

gargoyle_receipts-0.6.0.dev0/gargoyle/approvers.py

@@ -0,0 +1,116 @@
+"""Enrolled approvers: a person's Entra identity bound to a key they hold.
+
+`gargoyle init` writes approver key files. For a team, an approver should
+instead sign in with Entra ID in the console, generate a key that never
+leaves their browser, and enroll its public half once. The issuer accepts
+the enrollment from a token that carries the approver app role (or a
+configured group), binds the key to the token's UPN, and persists it here.
+From then on the UPN is the approver key id on every grant, a threshold
+rule may name UPNs, and removing a line from this file (or the role in
+Entra) ends that person's ability to approve.
+
+    approvers.json = {"approvers": {"<upn>": {"public_key_hex": ..., "enrolled_at": ..., "enrolled_by": ...}}}
+
+Trust note. The issuer publishes this map (GET /approvers) and the
+middleware fetches it over the issuer's TLS. That makes the issuer's
+operator the authority for who may approve, which is weaker than a
+root-signed key record (SPEC.md section 10) and the right fit for a site
+where the same administrator runs the issuer and the tenant. Separation of
+duties still holds at the key level: an approver's key is never the
+issuer's, and the issuer never sees a private key.
+"""
+
+import json
+import os
+import stat
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+ENV_APPROVERS_PATH = "GARGOYLE_APPROVERS_PATH"
+ENV_APPROVER_ROLE = "GARGOYLE_APPROVER_ROLE"        # Entra app role an enrolling token must carry (default Approver)
+ENV_APPROVER_GROUPS = "GARGOYLE_APPROVER_GROUPS"    # or: comma-separated group ids, any of which qualifies
+
+DEFAULT_APPROVER_ROLE = "Approver"
+
+
+def valid_public_key_hex(value: Any) -> bool:
+    return isinstance(value, str) and len(value) == 64 and all(c in "0123456789abcdef" for c in value)
+
+
+class ApproverRegistry:
+    """The enrolled approvers, persisted to a JSON file. Thread-safe for the
+    single process that owns the file."""
+
+    def __init__(self, path: Optional[str]) -> None:
+        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)
+
+    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")
+        try:
+            os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+
+    def enroll(self, upn: str, public_key_hex: str, *, enrolled_by: Optional[str] = None,
+               now: Optional[datetime] = 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)."""
+        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):
+            raise ValueError("public_key_hex must be 64 lowercase hex characters")
+        entry = {"public_key_hex": public_key_hex,
+                 "enrolled_at": (now or datetime.now(timezone.utc)).isoformat(),
+                 "enrolled_by": enrolled_by or upn}
+        with self._lock:
+            replaced = upn in self._approvers
+            self._approvers[upn] = entry
+            self._save()
+        return {"upn": upn, "replaced": replaced, **entry}
+
+    def remove(self, upn: str) -> bool:
+        with self._lock:
+            gone = self._approvers.pop(upn, None) is not None
+            if gone:
+                self._save()
+        return gone
+
+    def public_hex(self) -> Dict[str, str]:
+        """{upn: public_key_hex}, what GET /approvers publishes."""
+        with self._lock:
+            return {upn: e["public_key_hex"] 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
+
+
+def may_enroll(who: Dict[str, Any], *, role: str = DEFAULT_APPROVER_ROLE, groups: Optional[list] = None) -> bool:
+    """Does an authenticated identity (identity.principal_from_token's
+    result) qualify as an approver: the app role, or any configured group."""
+    if role and role in (who.get("roles") or []):
+        return True
+    if groups and any(g in (who.get("groups") or []) for g in groups):
+        return True
+    return False
+
+
+def keys_from_hex(mapping: Dict[str, str]) -> Dict[str, Any]:
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    return {k: Ed25519PublicKey.from_public_bytes(bytes.fromhex(v)) for k, v in mapping.items() if valid_public_key_hex(v)}

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/cli.py

@@ -194,6 +194,7 @@ def cmd_issuer(args) -> int:
 
     out = Path(args.out).resolve()
     os.environ.update(_read_env(out / "issuer.env"))
+    os.environ.setdefault("GARGOYLE_APPROVERS_PATH", str(out / "approvers.json"))   # enrolled approvers live beside the keys
     app = app_from_env()
     # The middleware reads the policy pin from a file; write it next to the
     # config so the client-side entry finds it at the configured path.
@@ -229,8 +230,12 @@ def cmd_audit(args) -> int:
 
     keys = json.loads((Path(args.out).resolve() / "public-keys.json").read_text())
     load = lambda m: {k: Ed25519PublicKey.from_public_bytes(bytes.fromhex(v)) for k, v in m.items()}
+    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()})
     trust = dict(issuer_public_keys=load(keys["issuer"]), executor_public_keys=load(keys["executor"]),
-                 approver_public_keys=load(keys["approver"]))
+                 approver_public_keys=load(approvers))
     if args.log:
         # The middleware's evidence log: every decision, honored or refused,
         # hash-chained. Each honored entry is a full receipt chain.

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/consumer.py

@@ -152,6 +152,7 @@ class Consumer:
         clock_skew: timedelta = timedelta(0),
         high_water: Optional[HighWater] = None,
         approver_public_keys: Optional[Dict[str, Any]] = None,
+        approver_key_source: Optional[Callable[[], Dict[str, Any]]] = None,
         executor_signing_key: Any = None,
         executor_key_id: Optional[str] = None,
     ) -> None:
@@ -195,6 +196,9 @@ class Consumer:
         self.clock_skew = clock_skew
         self.high_water = high_water if high_water is not None else HighWater()
         self.approver_public_keys = approver_public_keys
+        # Enrolled approvers (gargoyle.approvers), fetched live by the caller's
+        # function and merged over the static map at each flagged check.
+        self.approver_key_source = approver_key_source
 
     # ----- the live policy pin -----
 
@@ -253,7 +257,13 @@ class Consumer:
         if key_record_view is not None:
             return resolve_approver_keys(key_record_view, gate_key_id=gate_key_id,
                                          now=now, clock_skew=self.clock_skew)
-        return dict(self.approver_public_keys or {})
+        keys = dict(self.approver_public_keys or {})
+        if self.approver_key_source is not None:
+            try:
+                keys.update({k: v for k, v in (self.approver_key_source() or {}).items() if k != gate_key_id})
+            except Exception:
+                pass          # an unreachable source adds nothing; the static map stands
+        return keys
 
     def check(
         self,

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/envelope.py

@@ -88,6 +88,28 @@ def canonical_json(data: Any) -> str:
     return "".join(out)
 
 
+def canonical_json_legacy(data: Any) -> str:
+    """The gargoyle/2 canonical form (Python json.dumps with sort_keys,
+    compact separators and ensure_ascii). Kept so that receipts, grants,
+    execution receipts and evidence entries written under gargoyle/2 can
+    still be verified in an audit. Nothing new is ever signed with it."""
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+# Formats an auditor may still verify, each with the serializer its bytes
+# were signed under. Admission (Consumer.check) accepts only ENVELOPE_VERSION.
+HISTORICAL_VERSIONS = {"gargoyle/2": canonical_json_legacy}
+
+
+def serializer_for(version: Any):
+    """The canonical serializer for a receipt format version: the current
+    one for ENVELOPE_VERSION, the legacy one for a historical version, None
+    for anything else."""
+    if version == ENVELOPE_VERSION:
+        return canonical_json
+    return HISTORICAL_VERSIONS.get(version)
+
+
 def _jcs(value: Any, out: list) -> None:
     if value is None:
         out.append("null")
@@ -200,8 +222,11 @@ def valid_approval(approval: Any) -> bool:
 
 
 def decision_sha256_of(envelope: Dict[str, Any]) -> str:
+    """The hash-region digest, under the serializer of the receipt's own
+    format version (a historical receipt hashes as it was issued)."""
     hashable = {k: v for k, v in envelope.items() if k not in _HASH_EXCLUDED_KEYS}
-    return _sha256_text(canonical_json(hashable))
+    serializer = serializer_for(envelope.get("envelope_version")) or canonical_json
+    return _sha256_text(serializer(hashable))
 
 
 def live_pin(

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/evidence.py

@@ -7,7 +7,7 @@ executor's record of every decision it made, honored or refused, each entry
 hashed over the one before it:
 
     entry = {
-        "evidence_version": "gargoyle-evidence/1",
+        "evidence_version": "gargoyle-evidence/2",
         "seq":           1, 2, 3 ...            (dense, from 1)
         "prev_sha256":   <entry_sha256 of seq-1; 64 zeros for seq 1>,
         "at":            <when the executor decided, ISO 8601, UTC>,
@@ -44,11 +44,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional
 
-from gargoyle.envelope import args_sha256, canonical_json
+from gargoyle.envelope import args_sha256, canonical_json, canonical_json_legacy
 from gargoyle.execution import verify_chain
 from gargoyle.verifier import verify_provenance
 
-EVIDENCE_VERSION = "gargoyle-evidence/1"
+EVIDENCE_VERSION = "gargoyle-evidence/2"          # entry hashes over RFC 8785 canonical JSON
+EVIDENCE_VERSIONS = {"gargoyle-evidence/1": canonical_json_legacy, EVIDENCE_VERSION: canonical_json}
 GENESIS = "0" * 64
 
 HONORED = "honored"
@@ -67,9 +68,12 @@ _FIELDS = ("evidence_version", "seq", "prev_sha256", "at", "kind", "tool", "args
 
 
 def entry_sha256(entry: Dict[str, Any]) -> str:
-    """The hash an entry carries: over its canonical JSON without the hash itself."""
+    """The hash an entry carries: over its canonical JSON without the hash
+    itself, under the serializer of the entry's own evidence_version, so a
+    log that spans a format change still verifies end to end."""
     body = {k: v for k, v in entry.items() if k != "entry_sha256"}
-    return hashlib.sha256(canonical_json(body).encode("utf-8")).hexdigest()
+    serialize = EVIDENCE_VERSIONS.get(entry.get("evidence_version"), canonical_json)
+    return hashlib.sha256(serialize(body).encode("utf-8")).hexdigest()
 
 
 def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any, principal: str,
@@ -113,7 +117,7 @@ class EvidenceLog:
         for line in self.path.read_text(encoding="utf-8").splitlines():
             if line.strip():
                 last = json.loads(line)
-                if last.get("evidence_version") == EVIDENCE_VERSION:
+                if last.get("evidence_version") in EVIDENCE_VERSIONS:
                     self._seq, self._tail = int(last["seq"]), str(last["entry_sha256"])
 
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
@@ -132,7 +136,7 @@ class EvidenceLog:
 
 def _well_formed(entry: Any) -> bool:
     return (isinstance(entry, dict) and set(entry) == set(_FIELDS)
-            and entry["evidence_version"] == EVIDENCE_VERSION
+            and entry["evidence_version"] in EVIDENCE_VERSIONS
             and isinstance(entry["seq"], int) and entry["seq"] >= 1
             and isinstance(entry["prev_sha256"], str) and len(entry["prev_sha256"]) == 64
             and isinstance(entry["at"], str) and entry["kind"] in (HONORED, REFUSED)
@@ -196,7 +200,7 @@ def verify_log(
             reason = ACCEPT_ENTRY_VERIFIED
             if e["receipt"] is not None:
                 p = verify_provenance(e["receipt"], pinned_public_keys=issuer_public_keys,
-                                      now=_parse_at(e["at"]))
+                                      now=_parse_at(e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         counts[e["kind"]] += 1
         report.append({"seq": e["seq"], "kind": e["kind"], "tool": e["tool"], "principal": e["principal"],

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/execution.py

@@ -40,7 +40,7 @@ from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from gargoyle.approval import as_grant_list, verify_grants
-from gargoyle.envelope import args_sha256, canonical_json
+from gargoyle.envelope import args_sha256, canonical_json, serializer_for
 from gargoyle.verifier import verify_provenance
 
 EXECUTION_VERSION = "gargoyle-execution/1"
@@ -145,13 +145,16 @@ def verify_execution_receipt(
     public_key = executor_public_keys.get(key_id)
     if public_key is None:
         return _reject(REF_EXEC_KEY_UNKNOWN)
+    # The execution receipt was signed under the canonical form of the
+    # receipt's format version; an audit of a historical chain uses that.
+    serialize = serializer_for(envelope.get("envelope_version")) or canonical_json
     region = {k: v for k, v in execution.items() if k not in _SIGNATURE_EXCLUDED_KEYS}
     try:
-        public_key.verify(bytes.fromhex(signature_hex), canonical_json(region).encode("utf-8"))
+        public_key.verify(bytes.fromhex(signature_hex), serialize(region).encode("utf-8"))
     except Exception:
         return _reject(REF_EXEC_SIGNATURE_INVALID)
     for key in _BOUND_FROM_RECEIPT:
-        if key not in envelope or canonical_json(execution[key]) != canonical_json(envelope[key]):
+        if key not in envelope or serialize(execution[key]) != serialize(envelope[key]):
             return _reject(REF_EXEC_BINDING_MISMATCH)
     if check_outputs:
         try:
@@ -190,7 +193,8 @@ def verify_chain(
     except (ValueError, TypeError):
         return {"accepted": False, "reason": REF_EXEC_MALFORMED, "steps": steps}
 
-    provenance = verify_provenance(envelope, pinned_public_keys=issuer_public_keys, now=executed_at)
+    # An audit verifies historical formats; admission (the consumer) does not.
+    provenance = verify_provenance(envelope, pinned_public_keys=issuer_public_keys, now=executed_at, historical=True)
     steps.append(("authorization", provenance["reason"]))
     if not provenance["accepted"]:
         return {"accepted": False, "reason": provenance["reason"], "steps": steps}

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/issuer_service.py

@@ -53,6 +53,8 @@ from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_
                                verify_grant)
 from gargoyle.envelope import approval_terms
 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.issuer import DEFAULT_TTL_SECONDS, issue
 from gargoyle.policy import Policy
@@ -69,12 +71,15 @@ ENV_AUDIENCE = "GARGOYLE_ISSUER_AUDIENCE"
 ENV_APPROVER_KEY_ID = "GARGOYLE_APPROVER_KEY_ID"
 ENV_APPROVER_PUBLIC_KEY_HEX = "GARGOYLE_APPROVER_PUBLIC_KEY_HEX"
 ENV_RECEIPT_TTL = "GARGOYLE_RECEIPT_TTL_SECONDS"
+ENV_CONSOLE_CLIENT_ID = "GARGOYLE_ENTRA_CLIENT_ID"   # the public client app the console signs in with (User-Client-Flow)
+ENV_CONSOLE_SCOPE = "GARGOYLE_ENTRA_SCOPE"           # default api://<last audience>/access
 
 REF_ISSUER_UNAUTHENTICATED = "REF_ISSUER_UNAUTHENTICATED"
 REF_ISSUER_BAD_REQUEST = "REF_ISSUER_BAD_REQUEST"
 REF_ISSUER_ARGS_NOT_TEXT = "REF_ISSUER_ARGS_NOT_TEXT"   # arguments carry characters no UTF-8 text has
 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
 
 
 def build_issuer_app(
@@ -88,6 +93,10 @@ def build_issuer_app(
     ttl_seconds: int = DEFAULT_TTL_SECONDS,
     now: Callable[[], datetime] = lambda: datetime.now(timezone.utc),
     on_hold: Optional[Callable[[Dict[str, Any], Any], None]] = None,
+    approver_registry: Optional[ApproverRegistry] = None,
+    approver_role: str = DEFAULT_APPROVER_ROLE,
+    approver_groups: Optional[list] = None,
+    console_entra: Optional[Dict[str, str]] = 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
@@ -97,6 +106,12 @@ def build_issuer_app(
     app.state.pending_args: Dict[str, Any] = {}           # approval_request_id -> the call's arguments
     app.state.grants: Dict[str, Dict[str, Any]] = {}      # approval_request_id -> grant
     app.state.declined: set = set()                       # approval_request_ids a human refused
+    registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
+    static_approvers = dict(approver_public_keys or {})
+
+    def approver_keys() -> Dict[str, Any]:
+        """Static keys from configuration plus every enrolled approver, by UPN."""
+        return {**static_approvers, **registry.keys()}
 
     def _refuse(status: int, reason: str) -> HTTPException:
         return HTTPException(status_code=status, detail={"reason": reason})
@@ -182,10 +197,11 @@ def build_issuer_app(
         env = app.state.pending.get(arid) if isinstance(arid, str) else None
         if env is None:
             return {"accepted": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
-        if not approver_public_keys:
+        trusted = approver_keys()
+        if not trusted:
             return {"accepted": False, "reason": REF_ISSUER_NO_APPROVER_TRUST}
         g = verify_grant(grant, expected_decision_sha256=env["decision_sha256"],
-                         expected_approval_request_id=arid, approver_public_keys=approver_public_keys,
+                         expected_approval_request_id=arid, approver_public_keys=trusted,
                          gate_key_id=key_id, now=now())
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"]}
@@ -230,6 +246,46 @@ def build_issuer_app(
                 "collected": len(have), "required": approval_terms(env)["required"] if env else None,
                 "declined": approval_request_id in app.state.declined}
 
+    @app.get("/approvers")
+    async def approvers():
+        """Public, like /record: the enrolled approvers' public keys by UPN,
+        for the middleware and for audits. Static configured keys are not
+        listed; they travel in config."""
+        return {"approvers": registry.public_hex()}
+
+    @app.post("/approvers/enroll")
+    async def enroll(request: Request, authorization: Optional[str] = Header(default=None)):
+        """Bind the caller's UPN to the public key their browser generated.
+        Only a token carrying the approver role (or a configured group) may;
+        the UPN comes from the token, never from the body."""
+        who = authenticate(authorization)
+        if not may_enroll(who, role=approver_role, groups=approver_groups):
+            raise _refuse(403, REF_ISSUER_NOT_AN_APPROVER)
+        try:
+            body = await request.json()
+        except Exception:
+            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())
+        return {"enrolled": True, "key_id": who["principal"], "replaced": result["replaced"]}
+
+    @app.get("/me")
+    async def me(authorization: Optional[str] = Header(default=None)):
+        """Who the console is signed in as, whether they may approve, and
+        the public key enrolled for them (so the browser can tell whether
+        its own key is the one on record)."""
+        who = authenticate(authorization)
+        upn = who["principal"]
+        return {"principal": upn, "may_approve": may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers,
+                "enrolled_public_key_hex": registry.public_hex().get(upn)}
+
+    @app.get("/approve-config")
+    async def approve_config():
+        """Public: how the console signs in. `entra` is null when the site
+        uses approver files instead."""
+        return {"entra": console_entra}
+
     @app.get("/approve")
     async def approve_page():
         return Response((STATIC / "approve.html").read_bytes(), media_type="text/html; charset=utf-8")
@@ -298,4 +354,10 @@ def app_from_env() -> FastAPI:
         audience=os.environ.get(ENV_AUDIENCE) or None,
         ttl_seconds=int(os.environ.get(ENV_RECEIPT_TTL, DEFAULT_TTL_SECONDS)),
         on_hold=notifier_from_env(os.environ),
+        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,
+        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),
     )

{gargoyle_receipts-0.5.2.dev0 → gargoyle_receipts-0.6.0.dev0}/gargoyle/mcp_server.py

@@ -160,6 +160,16 @@ class IssuerClient:
             return {"envelope": None, "reason": body.get("reason") or REF_TARGET_ISSUER_UNAVAILABLE}
         return {"envelope": body.get("envelope"), "reason": None}
 
+    def approver_keys(self) -> Dict[str, Any]:
+        """The issuer's enrolled approvers as {upn: public key}; {} when the
+        issuer cannot be reached (the static map then stands alone)."""
+        from gargoyle.approvers import keys_from_hex
+        try:
+            r = self._get("/approvers")
+            return keys_from_hex(r.json().get("approvers", {})) if r.status_code == 200 else {}
+        except Exception:
+            return {}
+
     def wait_for_grant(self, approval_request_id: str) -> Dict[str, Any]:
         """Poll until the hold has its grant (or, for a receipt that needs
         several approvers, the whole set), a human declined it, the hold
@@ -284,6 +294,7 @@ class ServerState:
                 record=config["record"],
                 replay_cache=replay_cache,
                 approver_public_keys=config.get("approver_public_keys"),
+                approver_key_source=(issuer_client.approver_keys if issuer_client is not None else None),
                 executor_signing_key=config.get("executor_signing_key"),
                 executor_key_id=config.get("executor_key_id"),
             )