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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.15.0.dev0
+Version: 0.15.1.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.15.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.15.1.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
@@ -272,6 +272,15 @@ field. A hold can also be announced to Slack or any webhook
 (`GARGOYLE_HOLD_WEBHOOK_URL`); the notice carries no key, so nothing in a
 chat channel can approve anything.
 
+## Reviewing it
+
+`gargoyle review-packet --out packet.zip` builds one archive for an outside
+reviewer: the spec, the vectors, the verification source, a reviewer
+prompt, and `verify_stdlib.py`, which recomputes every conformance vector
+(RFC 8785, SHA-256, Ed25519) with nothing but the Python standard library,
+so a reviewer with no pip and no network can still check every hash and
+signature rather than take the README's word.
+
 ## Deploy it
 
     pip install gargoyle-receipts

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.15.1.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.15.1.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
@@ -234,6 +234,15 @@ field. A hold can also be announced to Slack or any webhook
 (`GARGOYLE_HOLD_WEBHOOK_URL`); the notice carries no key, so nothing in a
 chat channel can approve anything.
 
+## Reviewing it
+
+`gargoyle review-packet --out packet.zip` builds one archive for an outside
+reviewer: the spec, the vectors, the verification source, a reviewer
+prompt, and `verify_stdlib.py`, which recomputes every conformance vector
+(RFC 8785, SHA-256, Ed25519) with nothing but the Python standard library,
+so a reviewer with no pip and no network can still check every hash and
+signature rather than take the README's word.
+
 ## Deploy it
 
     pip install gargoyle-receipts

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

@@ -14,6 +14,8 @@ policy engine, a container runtime, or any client changes.
     gargoyle remote --out DIR [--upstream-url URL | -- <command>]   the gate as an HTTPS MCP
                                                         server, for hosted connectors
     gargoyle remote-token --out DIR --principal UPN     a capability URL for one person
+    gargoyle review-packet --out packet.zip [--audit-excerpt FILE]   everything an outside
+                                                        reviewer needs, verifier included
     gargoyle audit <receipt.json> <execution.json> [grant.json]
     gargoyle audit --log audit.jsonl            verify the middleware's evidence log
 
@@ -282,6 +284,18 @@ def cmd_remote(args) -> int:
     return 0
 
 
+def cmd_review_packet(args) -> int:
+    """One archive for an outside reviewer: spec, README, vectors, the
+    verification source, a reviewer prompt, and verify_stdlib.py, which
+    recomputes every vector with the standard library alone."""
+    from gargoyle.review import build_packet
+    root = Path(__file__).resolve().parent.parent
+    excerpt = Path(args.audit_excerpt).read_text(encoding="utf-8") if args.audit_excerpt else None
+    result = build_packet(str(root), args.out, audit_excerpt=excerpt, extra_files=args.extra or [])
+    print("wrote %s (%d files); give the reviewer the archive and REVIEWER_PROMPT.txt" % (result["path"], len(result["files"])))
+    return 0
+
+
 def cmd_issuer(args) -> int:
     import uvicorn
     from gargoyle.issuer_service import app_from_env
@@ -457,6 +471,11 @@ def main(argv=None) -> int:
     p.add_argument("--days", type=int, default=365)
     p.add_argument("--url", help="the gate's public base URL for the printed connector URL")
     p.set_defaults(fn=cmd_remote_token)
+    p = sub.add_parser("review-packet", help="build the archive an outside reviewer needs")
+    p.add_argument("--out", default="gargoyle-review-packet.zip")
+    p.add_argument("--audit-excerpt", help="a text file with real audit output to include")
+    p.add_argument("--extra", action="append", help="additional files to include (repeatable)")
+    p.set_defaults(fn=cmd_review_packet)
     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.1.dev0/gargoyle/review.py

@@ -0,0 +1,213 @@
+"""A review packet: everything an outside reviewer needs in one archive,
+including a verifier that needs nothing but the Python standard library.
+
+`gargoyle review-packet` writes a zip with SPEC.md, README.md, the
+conformance vectors (current and historical), the verification modules
+as source, the live audit excerpt if given, and verify_stdlib.py: RFC
+8785 canonicalization, SHA-256 and Ed25519 verification implemented with
+hashlib and integers only, so a reviewer in a sandbox with no pip and no
+network can recompute every vector and check every signature themselves.
+"""
+
+import io
+import json
+import zipfile
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+VERIFY_STDLIB = r'''#!/usr/bin/env python3
+"""Recompute Gargoyle's conformance vectors with the standard library only.
+
+No third-party packages: RFC 8785 canonical JSON, SHA-256 (hashlib) and
+Ed25519 verification (RFC 8032, implemented here with integers) are enough
+to check that every hash and signature in wire_vectors.json is what the
+specification says. Run:  python3 verify_stdlib.py wire_vectors.json
+Exit code 0 means every check passed; each check prints its own line.
+"""
+import hashlib, json, sys
+
+# ---- RFC 8785 canonical JSON ----
+def _es6_number(x):
+    if x != x or x in (float("inf"), float("-inf")): raise ValueError("non-finite")
+    if x == 0: return "0"
+    sign = "-" if x < 0 else ""
+    r = repr(abs(x)); mantissa, _, exp = r.partition("e"); whole, _, frac = mantissa.partition(".")
+    digits = (whole + frac).lstrip("0"); n = len(whole) + (int(exp) if exp else 0)
+    n -= len(whole + frac) - len((whole + frac).lstrip("0")); digits = digits.rstrip("0") or "0"; k = len(digits)
+    if k <= n <= 21: return sign + digits + "0" * (n - k)
+    if 0 < n <= 21: return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0: return sign + "0." + "0" * (-n) + digits
+    e = n - 1; et = "e" + ("+" if e >= 0 else "-") + str(abs(e))
+    return sign + (digits if k == 1 else digits[0] + "." + digits[1:]) + et
+
+_ESC = {"\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t", '"': '\\"', "\\": "\\\\"}
+def _str(s):
+    return '"' + "".join(_ESC.get(c, c if c >= " " else "\\u%04x" % ord(c)) for c in s) + '"'
+
+def canonical_json(v):
+    if v is None: return "null"
+    if v is True: return "true"
+    if v is False: return "false"
+    if isinstance(v, int): return str(v)
+    if isinstance(v, float): return _es6_number(v)
+    if isinstance(v, str): return _str(v)
+    if isinstance(v, list): return "[" + ",".join(canonical_json(x) for x in v) + "]"
+    if isinstance(v, dict):
+        return "{" + ",".join(_str(k) + ":" + canonical_json(v[k]) for k in sorted(v, key=lambda k: k.encode("utf-16-be"))) + "}"
+    raise TypeError(type(v))
+
+def sha256_hex(text): return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+# ---- Ed25519 (RFC 8032) with integers only; slow, and that is fine for a review ----
+P = 2**255 - 19; L = 2**252 + 27742317777372353535851937790883648493
+D = (-121665 * pow(121666, P - 2, P)) % P
+def _inv(x): return pow(x, P - 2, P)
+def _pt_add(A, B):
+    x1, y1, z1, t1 = A; x2, y2, z2, t2 = B
+    a = (y1 - x1) * (y2 - x2) % P; b = (y1 + x1) * (y2 + x2) % P; c = 2 * t1 * t2 * D % P; d = 2 * z1 * z2 % P
+    e, f, g, h = b - a, d - c, d + c, b + a
+    return (e * f % P, g * h % P, f * g % P, e * h % P)
+def _pt_mul(k, A):
+    R = (0, 1, 1, 0)
+    while k:
+        if k & 1: R = _pt_add(R, A)
+        A = _pt_add(A, A); k >>= 1
+    return R
+def _pt_eq(A, B):
+    x1, y1, z1, _ = A; x2, y2, z2, _ = B
+    return (x1 * z2 - x2 * z1) % P == 0 and (y1 * z2 - y2 * z1) % P == 0
+def _decode(b):
+    y = int.from_bytes(b, "little"); sign = y >> 255; y &= (1 << 255) - 1
+    if y >= P: return None
+    x2 = (y * y - 1) * _inv(D * y * y + 1) % P
+    x = pow(x2, (P + 3) // 8, P)
+    if (x * x - x2) % P != 0: x = x * pow(2, (P - 1) // 4, P) % P
+    if (x * x - x2) % P != 0: return None
+    if x & 1 != sign: x = P - x
+    return (x, y, 1, x * y % P)
+_B = _decode(bytes.fromhex("5866666666666666666666666666666666666666666666666666666666666666"))
+def ed25519_verify(public_key_hex, message_bytes, signature_hex):
+    A = _decode(bytes.fromhex(public_key_hex)); sig = bytes.fromhex(signature_hex)
+    if A is None or len(sig) != 64: return False
+    R = _decode(sig[:32]); S = int.from_bytes(sig[32:], "little")
+    if R is None or S >= L: return False
+    h = hashlib.sha512(sig[:32] + bytes.fromhex(public_key_hex) + message_bytes).digest()
+    k = int.from_bytes(h, "little") % L
+    return _pt_eq(_pt_mul(S, _B), _pt_add(R, _pt_mul(k, A)))
+
+HASH_EXCLUDED = ("decision_sha256", "timestamp_utc", "issuer_key_id", "issuer_signature", "not_after", "decision_id", "approval_request_id")
+
+def check(label, ok):
+    print(("PASS " if ok else "FAIL ") + label); return ok
+
+def verify_receipt(signed, issuer_pub, results):
+    region = {k: v for k, v in signed.items() if k not in HASH_EXCLUDED}
+    results.append(check("decision_sha256 recomputes over the RFC 8785 hash region", sha256_hex(canonical_json(region)) == signed["decision_sha256"]))
+    srg = {k: v for k, v in signed.items() if k not in ("issuer_signature", "timestamp_utc")}
+    results.append(check("issuer_signature verifies (Ed25519, pure Python)", ed25519_verify(issuer_pub, canonical_json(srg).encode(), signed["issuer_signature"])))
+
+def verify_grant(grant, approver_pub, decision_sha256, results):
+    region = {k: v for k, v in grant.items() if k != "approver_signature"}
+    results.append(check("grant binds the decision (%s)" % grant["approver_key_id"], grant["decision_sha256"] == decision_sha256))
+    results.append(check("approver_signature verifies (%s)" % grant["approver_key_id"], ed25519_verify(approver_pub, canonical_json(region).encode(), grant["approver_signature"])))
+
+def verify_execution(ex, executor_pub, signed, results):
+    region = {k: v for k, v in ex.items() if k != "executor_signature"}
+    results.append(check("execution receipt binds the receipt field for field",
+                         all(canonical_json(ex[k]) == canonical_json(signed[k]) for k in ("decision_id", "decision_sha256", "policy", "target_url", "request_context"))))
+    results.append(check("executor_signature verifies", ed25519_verify(executor_pub, canonical_json(region).encode(), ex["executor_signature"])))
+
+def main(path):
+    V = json.load(open(path, encoding="utf-8")); results = []
+    print("== primary vector ==")
+    results.append(check("args_sha256 recomputes", sha256_hex(canonical_json(V["call"]["args"])) == V["args_sha256"]))
+    results.append(check("hash_region bytes match", canonical_json({k: v for k, v in V["signed"].items() if k not in HASH_EXCLUDED}) == V["hash_region"]))
+    verify_receipt(V["signed"], V["issuer_public_key_hex"], results)
+    verify_grant(V["grant"], V["approver_public_key_hex"], V["signed"]["decision_sha256"], results)
+    verify_execution(V["execution"], V["executor_public_key_hex"], V["signed"], results)
+    tampered = dict(V["signed"], target_url="https://elsewhere.example/")
+    srg = {k: v for k, v in tampered.items() if k not in ("issuer_signature", "timestamp_utc")}
+    results.append(check("a tampered receipt does NOT verify", not ed25519_verify(V["issuer_public_key_hex"], canonical_json(srg).encode(), tampered["issuer_signature"])))
+    if "threshold" in V:
+        T = V["threshold"]; print("== threshold vector (two approvers) ==")
+        verify_receipt(T["signed"], V["issuer_public_key_hex"], results)
+        results.append(check("approval terms are inside the hash region", '"approval":{"approvers":["approver-alice","approver-bob"],"required":2}' in T["hash_region"]))
+        for g, pub in zip(T["grants"], (V["approver_public_key_hex"], T["approver_2_public_key_hex"])):
+            verify_grant(g, pub, T["signed"]["decision_sha256"], results)
+        verify_execution(T["execution"], V["executor_public_key_hex"], T["signed"], results)
+    print("%d checks, %d failed" % (len(results), results.count(False)))
+    return 0 if all(results) else 1
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "wire_vectors.json"))
+'''
+
+SOURCE_FILES = ["envelope.py", "verifier.py", "approval.py", "execution.py", "evidence.py", "state.py", "plans.py",
+                "witness.py", "reconcile.py", "revert.py", "adapters.py", "consumer.py", "issuer.py", "jws.py"]
+
+REVIEWER_PROMPT = '''You are an independent, skeptical reviewer of a prerelease open-source project. You
+have this archive and nothing else; it is sufficient. Do not say "I could not access
+the repository": every file you need is here, and verify_stdlib.py needs only Python's
+standard library (no pip, no network).
+
+Read SPEC.md in full, then README.md. Then:
+
+1. Run `python3 verify_stdlib.py wire_vectors.json`. Report every PASS/FAIL line and
+   the count. If you cannot execute, read verify_stdlib.py and state which specific
+   step you would have expected to fail and why; a reviewer who cannot run it must
+   still read it.
+2. Read the source files (envelope.py, verifier.py, approval.py, execution.py,
+   evidence.py, plans.py, witness.py, reconcile.py, state.py, revert.py, adapters.py,
+   consumer.py). For each attack below, point to the exact function and line that
+   stops it, or show the input that gets through:
+   a. a receipt honored for arguments other than the ones it binds;
+   b. a flagged receipt run without a grant from a trusted approver key;
+   c. a receipt, grant or plan step reused;
+   d. an execution receipt or evidence entry forged with the executor's own key, that
+      the audit accepts, with and without an issuer witness present;
+   e. a revert the audit marks exact that was not;
+   f. a file changed under a gated folder that the tree check misses;
+   g. a trust statement in SPEC.md sections 6.1, 8.3, 12, 15.1, 17 the code does not
+      uphold;
+   h. any place the code fails open: a missing key, an unreachable service, a
+      malformed input that is admitted rather than refused.
+3. If audit_excerpt.txt is present, read it as a real deployment's audit output and
+   say what it does and does not establish.
+4. Maturity for a first client beta: what you would require before letting this gate a
+   shared folder or a mailbox, citing the file or spec section that falls short.
+
+Findings first, ordered by severity, each with file and line or the exact input. No
+praise, no summary of the README. Where you did not verify, say exactly that.
+'''
+
+
+def build_packet(repo_root: str, out_path: str, audit_excerpt: Optional[str] = None,
+                 extra_files: Optional[Iterable[str]] = None) -> Dict[str, Any]:
+    root = Path(repo_root)
+    names: List[str] = []
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as z:
+        def add(arc: str, data: bytes) -> None:
+            z.writestr(arc, data); names.append(arc)
+        for rel in ("SPEC.md", "README.md", "docs/beta-checklist.md", "docs/ally-design.md"):
+            p = root / rel
+            if p.exists():
+                add(Path(rel).name if rel.startswith("docs/") else rel, p.read_bytes())
+        for rel in ("tests/fixtures/wire_vectors.json", "tests/fixtures/wire_vectors_v2.json"):
+            p = root / rel
+            if p.exists():
+                add(Path(rel).name, p.read_bytes())
+        for name in SOURCE_FILES:
+            p = root / "gargoyle" / name
+            if p.exists():
+                add("source/" + name, p.read_bytes())
+        add("verify_stdlib.py", VERIFY_STDLIB.encode("utf-8"))
+        add("REVIEWER_PROMPT.txt", REVIEWER_PROMPT.encode("utf-8"))
+        if audit_excerpt:
+            add("audit_excerpt.txt", audit_excerpt.encode("utf-8"))
+        for extra in extra_files or []:
+            p = Path(extra)
+            if p.exists():
+                add("extra/" + p.name, p.read_bytes())
+        manifest = {"files": names, "note": "Built by gargoyle review-packet. verify_stdlib.py needs only the Python standard library."}
+        z.writestr("MANIFEST.json", json.dumps(manifest, indent=2))
+    return {"path": out_path, "files": names + ["MANIFEST.json"]}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.15.0.dev0
+Version: 0.15.1.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.15.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.15.1.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
@@ -272,6 +272,15 @@ field. A hold can also be announced to Slack or any webhook
 (`GARGOYLE_HOLD_WEBHOOK_URL`); the notice carries no key, so nothing in a
 chat channel can approve anything.
 
+## Reviewing it
+
+`gargoyle review-packet --out packet.zip` builds one archive for an outside
+reviewer: the spec, the vectors, the verification source, a reviewer
+prompt, and `verify_stdlib.py`, which recomputes every conformance vector
+(RFC 8785, SHA-256, Ed25519) with nothing but the Python standard library,
+so a reviewer with no pip and no network can still check every hash and
+signature rather than take the README's word.
+
 ## Deploy it
 
     pip install gargoyle-receipts

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.15.1.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ gargoyle/reconcile.py
 gargoyle/remote.py
 gargoyle/replay_cache.py
 gargoyle/revert.py
+gargoyle/review.py
 gargoyle/rules.py
 gargoyle/state.py
 gargoyle/verifier.py

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.15.1.dev0}/pyproject.toml

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

{gargoyle_receipts-0.15.0.dev0 → gargoyle_receipts-0.15.1.dev0}/tests/test_cli.py

@@ -119,3 +119,22 @@ def test_init_for_a_windows_client_and_audit_log_verification(tmp_path, monkeypa
     assert main(["audit", "--log", str(log), "--out", str(out)]) == 1
     out_text = capsys.readouterr().out
     assert "1 failed" in out_text and "REF_EVIDENCE_HASH_MISMATCH" in out_text
+
+
+def test_review_packet_builds_and_its_verifier_runs_on_plain_python(tmp_path):
+    """The packet verifies the real vectors with the standard library only,
+    run through an isolated interpreter that has no site-packages."""
+    import subprocess, sys, zipfile
+    from gargoyle.cli import main
+    out = tmp_path / "packet.zip"
+    (tmp_path / "audit.txt").write_text("45 entries (42 honored, 3 refused), 0 failed")
+    assert main(["review-packet", "--out", str(out), "--audit-excerpt", str(tmp_path / "audit.txt")]) == 0
+    with zipfile.ZipFile(out) as z:
+        names = set(z.namelist())
+        assert {"SPEC.md", "README.md", "wire_vectors.json", "wire_vectors_v2.json", "verify_stdlib.py", "REVIEWER_PROMPT.txt",
+                "audit_excerpt.txt", "source/verifier.py", "source/plans.py", "MANIFEST.json"} <= names
+        z.extractall(tmp_path / "x")
+    r = subprocess.run([sys.executable, "-I", "-S", str(tmp_path / "x" / "verify_stdlib.py"), str(tmp_path / "x" / "wire_vectors.json")],
+                       capture_output=True, text=True)
+    assert r.returncode == 0, r.stdout + r.stderr
+    assert "18 checks, 0 failed" in r.stdout and "a tampered receipt does NOT verify" in r.stdout