primarypath-verify 1.0.0rc1__py3-none-any.whl

primarypath_verify-1.0.0rc1.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: primarypath-verify
+Version: 1.0.0rc1
+Summary: Offline verifier for Primary Path audit bundles: the record stands on its own math
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Dynamic: license-file

primarypath_verify-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,7 @@
+primarypath_verify.py,sha256=jp4EZprfrby27TdeboJhXXC06O0tNghZfqYLlqwXzo0,23849
+primarypath_verify-1.0.0rc1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+primarypath_verify-1.0.0rc1.dist-info/METADATA,sha256=wFy-pyKLI7C6oLV2QwvhBA8ibN0NM_vLAKs1m92nTHM,288
+primarypath_verify-1.0.0rc1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+primarypath_verify-1.0.0rc1.dist-info/entry_points.txt,sha256=1_rQQ8YiTGEnR_DY1frBx6QSk13Y0G6buwiHMpghz_M,63
+primarypath_verify-1.0.0rc1.dist-info/top_level.txt,sha256=_BwW5Qpg6pvsUbFLlwzYXtMVNu064rWQay-kld7rD0E,19
+primarypath_verify-1.0.0rc1.dist-info/RECORD,,

primarypath_verify-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

primarypath_verify-1.0.0rc1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+primarypath-verify = primarypath_verify:main

primarypath_verify-1.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

primarypath_verify-1.0.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+primarypath_verify

primarypath_verify.py

@@ -0,0 +1,517 @@
+"""Offline audit verifier: prove the record without trusting the server.
+
+    primarypath-verify bundle.json                  # verify a saved bundle
+    primarypath-verify bundle.json --pubring ring.json   # also pin the signing key
+    primarypath-verify https://primarypath.example.com --token <admin-token>   # fetch first
+    primarypath-verify https://primarypath.example.com --agent payments-bot --token ...
+
+Bundle shapes (all verified offline, air-gapped for a file bundle):
+- a chain bundle (`scope` "full" single-chain, "agent:<name>", or
+  "governance"): one hash chain from its own genesis to its head — F24
+  gives every agent its own chain, so an auditor verifies ONE agent
+  without processing the other 99
+- a whole-log bundle (`chains`: [...]): every chain, each verified alone;
+  one signature over all the heads
+- a run-scoped bundle (`scope` "run:..."): per-record integrity only
+
+Checks, in order:
+1. every event's hash recomputes from (seq|ts_ms|type|payload|prev_hash)
+2. the chain links from its own genesis and reaches `head`
+3. the Ed25519 signature verifies with the bundle's public key — for a
+   per-agent bundle that is the key its EVIDENCE PROFILE demands
+4. (--pubring) the bundle's key_id is in your pinned public-key ring
+
+The hashing is byte-identical to the server's (and to the original
+walking skeleton).
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import sys
+import time
+
+GENESIS = "genesis"
+
+
+def canonical(payload: dict) -> str:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False)
+
+
+def chain_hash(seq: int, ts_ms: int, type: str, payload_json: str,
+               prev_hash: str) -> str:
+    line = f"{seq}|{ts_ms}|{type}|{payload_json}|{prev_hash}"
+    return hashlib.sha256(line.encode("utf-8")).hexdigest()
+
+
+def _is_contiguous(bundle: dict) -> bool:
+    """Whether this bundle claims to be a complete chain (genesis -> head).
+    Run-scoped bundles are excerpts: per-record integrity only."""
+    scope = bundle.get("scope", "full")
+    return (scope in ("full", "governance")
+            or scope.startswith("agent:"))
+
+
+def _verify_events(events: list[dict], head: str, full: bool,
+                   label: str = "") -> tuple[bool, str]:
+    where = f"{label} " if label else ""
+    prev = GENESIS
+    for e in events:
+        payload = e["payload"]
+        payload_json = payload if isinstance(payload, str) else canonical(payload)
+        if full and e["prev_hash"] != prev:
+            return False, f"broken at {where}seq {e['seq']}: prev_hash mismatch"
+        recomputed = chain_hash(e["seq"], e["ts_ms"], e["type"], payload_json,
+                                e["prev_hash"] if not full else prev)
+        if recomputed != e["hash"]:
+            return False, (f"broken at {where}seq {e['seq']}: recomputed hash "
+                           f"differs, record was modified after writing")
+        prev = recomputed
+    last = events[-1]["hash"] if events else GENESIS
+    if head != last:
+        return False, (f"{where}head {head[:16]}… does not match last "
+                       f"event hash")
+    return True, ""
+
+
+def verify_chain(bundle: dict) -> tuple[bool, str]:
+    if "chains" in bundle:
+        total = 0
+        for c in bundle["chains"]:
+            ok, msg = _verify_events(c["events"], c.get("head", GENESIS),
+                                     full=True, label=f"chain {c['chain_id']}")
+            if not ok:
+                return False, msg
+            total += len(c["events"])
+        return True, (f"chain OK: {len(bundle['chains'])} chains, "
+                      f"{total} events, each verified independently")
+    events = bundle["events"]
+    full = _is_contiguous(bundle)
+    head = bundle.get("head", GENESIS)
+    ok, msg = _verify_events(events, head, full)
+    if not ok:
+        return False, msg
+    if not full:
+        # a scoped bundle proves each record is what was written, but cannot
+        # prove no record was omitted — only the full chain proves completeness
+        return True, (f"records OK: {len(events)} events, head {head[:16]}… "
+                      f"(run-scoped: per-record integrity, not completeness)")
+    what = bundle.get("scope", "full")
+    label = "" if what == "full" else f" [{what}]"
+    return True, f"chain OK: {len(events)} events, head {head[:16]}…{label}"
+
+
+def _signed_record(bundle: dict) -> dict:
+    if "chains" in bundle:
+        return {"chains": [{
+            "chain_id": c["chain_id"],
+            "head": c["head"],
+            "count": len(c["events"]),
+            "first_seq": c["events"][0]["seq"] if c["events"] else None,
+            "last_seq": c["events"][-1]["seq"] if c["events"] else None,
+        } for c in sorted(bundle["chains"], key=lambda c: c["chain_id"])]}
+    events = bundle["events"]
+    record = {
+        "head": bundle["head"],
+        "count": len(events),
+        "first_seq": events[0]["seq"] if events else None,
+        "last_seq": events[-1]["seq"] if events else None,
+    }
+    if "events_hash" in bundle:
+        # non-contiguous (run) bundles: the signature commits to every event
+        # hash. RECOMPUTE the commitment from the events themselves; a lying
+        # events_hash field then fails signature verification, and stripping
+        # the field changes the record shape, which also fails.
+        record["events_hash"] = hashlib.sha256(canonical(
+            {"hashes": [e["hash"] for e in events]}).encode("utf-8")
+        ).hexdigest()
+    return record
+
+
+SIGNATURE_FIELDS = ("signature", "public_key", "key_id")
+
+
+def verify_signature(bundle: dict, pubring: dict | None = None,
+                     allow_unsigned: bool = False) -> tuple[bool, str]:
+    present = [f for f in SIGNATURE_FIELDS if f in bundle]
+    if not present:
+        if pubring is not None and not allow_unsigned:
+            # a pinned ring asks "did MY org sign this": an attacker who
+            # cannot forge the signature can always delete it, so absence
+            # must fail exactly like a bad signature
+            return False, ("UNSIGNED: a pinned ring was given but the bundle "
+                           "carries no signature, so nothing ties it to your "
+                           "org's key. If this chain is unsigned on purpose "
+                           "(evidence profile signing_backend: none), pass "
+                           "--allow-unsigned for an integrity-only check")
+        return True, ("unsigned bundle (no signature present): integrity "
+                      "only, NOT authenticity")
+    if len(present) != len(SIGNATURE_FIELDS):
+        missing = [f for f in SIGNATURE_FIELDS if f not in bundle]
+        return False, (f"SIGNATURE INVALID: bundle is missing "
+                       f"{', '.join(missing)}")
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric import ed25519
+    except ImportError:
+        return False, "signature present but `cryptography` is not installed"
+
+    record = _signed_record(bundle)
+    raw_pub = base64.b64decode(bundle["public_key"])
+    kid = hashlib.sha256(raw_pub).hexdigest()[:16]
+    if kid != bundle.get("key_id"):
+        return False, "key_id does not match the embedded public key"
+    if pubring is not None and kid not in pubring:
+        return False, f"key {kid} is not in the pinned public-key ring"
+    key = ed25519.Ed25519PublicKey.from_public_bytes(raw_pub)
+    try:
+        key.verify(base64.b64decode(bundle["signature"]),
+                   canonical(record).encode("utf-8"))
+    except InvalidSignature:
+        return False, "SIGNATURE INVALID: bundle does not match its signature"
+    caveat = ""
+    if not _is_contiguous(bundle) and "events_hash" not in bundle:
+        # a pre-events_hash run export: its signature does not commit to the
+        # event contents, only to head/count/seqs
+        caveat = (" WARNING: legacy run bundle without events_hash; the "
+                  "signature does not bind the event contents. Re-export "
+                  "from a current server for a content-bound signature.")
+    if pubring is None:
+        # self-consistency only: a malicious operator can rewrite history and
+        # re-sign with a fresh embedded key. Authenticity needs pinning.
+        return True, (f"signature OK: key {kid} — UNPINNED: this only proves "
+                      f"the bundle matches its own embedded key, NOT that the "
+                      f"key is your org's. Pin the ring once, out of band, "
+                      f"and pass --pubring to establish authenticity"
+                      f"{caveat}")
+    return True, f"signature OK: key {kid} (pinned in ring){caveat}"
+
+
+GRANT_SIGNED_FIELDS = ("v", "approval_id", "tenant", "agent_id", "tool",
+                       "action_digest", "issued_ms", "expires_ms", "nonce")
+
+
+def verify_grants(bundle: dict, pubring: dict | None = None) -> tuple[bool, str]:
+    """Execution grants: every approval_granted that carries a grant must
+    carry a valid signature (against the pinned ring, else the bundle's
+    embedded key), and every grant_redeemed must name a grant that
+    exists — so the bundle proves the executor ran exactly the approved
+    action, and could run it only once."""
+    grants: dict[str, dict] = {}
+    redeemed: list[dict] = []
+    for e in _all_events(bundle):
+        p = e["payload"]
+        try:
+            p = json.loads(p) if isinstance(p, str) else p
+        except ValueError:
+            continue
+        if not isinstance(p, dict):
+            continue
+        if e["type"] == "approval_granted" and isinstance(p.get("grant"), dict):
+            grants[p["approval_id"]] = p["grant"]
+        elif e["type"] == "grant_redeemed":
+            redeemed.append(p)
+    if not grants and not redeemed:
+        return True, "no execution grants in this bundle"
+    keys = dict(pubring or {})
+    # the embedded key is a fallback for UNPINNED runs only: an empty ring
+    # is still a ring, and pins nothing
+    if pubring is None and bundle.get("public_key"):
+        keys[bundle.get("key_id", "")] = bundle["public_key"]
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric import ed25519
+    except ImportError:
+        return False, "grants present but `cryptography` is not installed"
+    for approval_id, g in grants.items():
+        pub = keys.get(g.get("key_id", ""))
+        if pub is None:
+            return False, (f"GRANT INVALID: {approval_id} signed by key "
+                           f"{g.get('key_id')} which is not in the ring")
+        try:
+            record = canonical({k: g[k] for k in GRANT_SIGNED_FIELDS})
+            ed25519.Ed25519PublicKey.from_public_bytes(
+                base64.b64decode(pub)).verify(
+                base64.b64decode(g["signature"]), record.encode("utf-8"))
+        except (InvalidSignature, KeyError, ValueError):
+            return False, f"GRANT INVALID: {approval_id} does not match its signature"
+    seen: set[tuple[str, str]] = set()
+    for r in redeemed:
+        g = grants.get(r.get("approval_id"))
+        if g is None or g.get("nonce") != r.get("nonce"):
+            return False, (f"GRANT INVALID: {r.get('approval_id')} redeemed "
+                           f"with a nonce no grant in this bundle issued")
+        if g.get("action_digest") != r.get("action_digest"):
+            return False, (f"GRANT INVALID: {r.get('approval_id')} redeemed "
+                           f"for a different action digest than granted")
+        key = (r["approval_id"], r["nonce"])
+        if key in seen:
+            return False, f"GRANT INVALID: {r['approval_id']} redeemed twice"
+        seen.add(key)
+    return True, (f"{len(grants)} execution grant(s) verified, "
+                  f"{len(redeemed)} redeemed")
+
+
+def verify_bundle(bundle: dict, pubring: dict | None = None,
+                  allow_unsigned: bool = False) -> tuple[bool, str]:
+    ok, msg = verify_chain(bundle)
+    if not ok:
+        return False, msg
+    ok2, msg2 = verify_signature(bundle, pubring, allow_unsigned)
+    if not ok2:
+        return False, f"{msg}; {msg2}"
+    ok3, msg3 = verify_grants(bundle, pubring)
+    return ok3, f"{msg}; {msg2}; {msg3}"
+
+
+def _load(src: str, token: str | None, agent: str | None = None,
+          governance: bool = False) -> dict:
+    if src.startswith("http://") or src.startswith("https://"):
+        import urllib.parse
+        import urllib.request
+        url = f"{src.rstrip('/')}/api/audit/export"
+        if agent:
+            url += "?" + urllib.parse.urlencode({"agent": agent})
+        elif governance:
+            url += "?scope=governance"
+        req = urllib.request.Request(url)
+        if token:
+            req.add_header("Authorization", f"Bearer {token}")
+        with urllib.request.urlopen(req, timeout=10) as r:
+            return json.loads(r.read().decode("utf-8"))
+    with open(src, encoding="utf-8") as f:
+        return json.load(f)
+
+
+# -- the evidence pack: the same proof, readable by a human -------------------
+
+_REPORT_CSS = """
+body { font: 14px/1.5 -apple-system, "Segoe UI", sans-serif; color: #1a1f2e;
+       max-width: 960px; margin: 32px auto; padding: 0 16px; }
+h1 { font-size: 22px; margin-bottom: 2px; }
+h2 { font-size: 15px; margin: 26px 0 8px; text-transform: uppercase;
+     letter-spacing: 0.04em; color: #5a6072; }
+.sub { color: #5a6072; margin-top: 0; }
+.verdict { padding: 10px 14px; border-radius: 6px; font-weight: 600;
+           margin: 14px 0; }
+.ok { background: #e7f5ec; color: #116632; border: 1px solid #b5dfc4; }
+.bad { background: #fdebea; color: #a11a25; border: 1px solid #f3c1be; }
+table { border-collapse: collapse; width: 100%; font-size: 13px; }
+th { text-align: left; color: #5a6072; font-weight: 600; }
+th, td { padding: 6px 10px 6px 0; border-bottom: 1px solid #e4e6ec;
+         vertical-align: top; }
+code, .mono { font-family: ui-monospace, Consolas, monospace; font-size: 12px;
+              overflow-wrap: anywhere; }
+.badge { font-size: 11px; padding: 1px 8px; border-radius: 999px;
+         white-space: nowrap; }
+.granted { background: #e7f5ec; color: #116632; }
+.denied { background: #fdebea; color: #a11a25; }
+.pending { background: #fff4dd; color: #8a5a00; }
+footer { margin-top: 30px; color: #5a6072; font-size: 12px;
+         border-top: 1px solid #e4e6ec; padding-top: 10px; }
+"""
+
+
+def _all_events(bundle: dict) -> list[dict]:
+    if "chains" in bundle:
+        out = []
+        for c in bundle["chains"]:
+            out.extend(c["events"])
+        return out
+    return bundle["events"]
+
+
+def _fold_for_report(events: list[dict]) -> tuple[list[dict], list[dict]]:
+    """Approvals (with endorsement + decision) and control-plane changes,
+    folded from the bundle alone — the report never trusts anything the
+    verified events do not carry."""
+    approvals: dict[str, dict] = {}
+    controls: list[dict] = []
+    for e in sorted(events, key=lambda x: (x["ts_ms"], x["seq"])):
+        p = e["payload"]
+        try:
+            p = json.loads(p) if isinstance(p, str) else p
+        except ValueError:
+            continue  # a tampered payload still gets its FAILED verdict
+        if not isinstance(p, dict):
+            continue
+        t = e["type"]
+        if t == "approval_requested" and p.get("approval_id"):
+            approvals[p["approval_id"]] = {
+                "approval_id": p["approval_id"], "tool": p.get("tool"),
+                "arguments": p.get("arguments") or {},
+                "reasoning": p.get("reasoning"),
+                "requested_ts_ms": e["ts_ms"], "status": "pending",
+                "endorsed_by": None, "reviewer": None, "reason": None,
+                "reviewer_role": None, "decided_ts_ms": None,
+                "executed_by": None, "executed_instance": None,
+                "executed_ts_ms": None,
+            }
+        elif t == "approval_endorsed" and p.get("approval_id") in approvals:
+            approvals[p["approval_id"]]["endorsed_by"] = p.get("reviewer")
+        elif t in ("approval_granted", "approval_denied") \
+                and p.get("approval_id") in approvals:
+            a = approvals[p["approval_id"]]
+            if a["status"] == "pending":
+                a["status"] = ("granted" if t == "approval_granted"
+                               else "denied")
+                a["reviewer"] = p.get("reviewer")
+                a["reason"] = p.get("reason")
+                a["reviewer_role"] = p.get("reviewer_role")
+                a["decided_ts_ms"] = e["ts_ms"]
+        elif t == "grant_redeemed" and p.get("approval_id") in approvals:
+            a = approvals[p["approval_id"]]
+            if a["executed_ts_ms"] is None:
+                a["executed_by"] = p.get("executor")
+                a["executed_instance"] = p.get("executor_instance")
+                a["executed_ts_ms"] = e["ts_ms"]
+        elif t in ("policy_set", "budget_set", "gate_decision",
+                   "admin_action", "agent_registered", "evidence_set",
+                   "eval_recorded", "audit_exported"):
+            controls.append({"ts_ms": e["ts_ms"], "type": t,
+                             "by": p.get("by"),
+                             "reason": p.get("reason"),
+                             "detail": {k: v for k, v in p.items()
+                                        if k not in ("by", "reason")}})
+    return list(approvals.values()), controls
+
+
+def _ts(ms) -> str:
+    import datetime
+    if not ms:
+        return ""
+    return datetime.datetime.fromtimestamp(
+        ms / 1000, tz=datetime.UTC).strftime("%Y-%m-%d %H:%M:%SZ")
+
+
+def write_report(bundle: dict, path: str, ok: bool, msg: str,
+                 pinned: bool, source: str) -> None:
+    """A self-contained HTML evidence pack: the verification verdict plus
+    every decision (who, as what role, when, why) folded from the verified
+    events. For the auditor who will not read JSON; the machine-checkable
+    bundle stays the proof."""
+    from html import escape as h
+
+    approvals, controls = _fold_for_report(_all_events(bundle))
+    scope = bundle.get("scope", "full")
+    head = bundle.get("head") or "(multi-chain)"
+    key_id = bundle.get("key_id")
+
+    rows = []
+    for a in sorted(approvals, key=lambda x: x["requested_ts_ms"]):
+        args_txt = ", ".join(f"{k}={v}" for k, v in a["arguments"].items())
+        who = a["reviewer"] or ""
+        if a["endorsed_by"]:
+            who = f"{a['endorsed_by']} (endorsed) + {who}" if who else \
+                f"{a['endorsed_by']} (endorsed, awaiting second)"
+        executed = ""
+        if a["executed_ts_ms"]:
+            inst = (f" as <i>{h(a['executed_instance'])}</i>"
+                    if a.get("executed_instance") else "")
+            executed = (f"<br><small>executed by {h(a['executed_by'] or '?')}"
+                        f"{inst} {_ts(a['executed_ts_ms'])}</small>")
+        rows.append(
+            f"<tr><td class=mono>{h(a['approval_id'])}</td>"
+            f"<td><code>{h(a['tool'] or '')}</code><br>"
+            f"<span class=mono>{h(args_txt[:200])}</span></td>"
+            f"<td><span class='badge {a['status']}'>{a['status']}</span>"
+            f"{executed}</td>"
+            f"<td>{h(who)}"
+            f"{(' <i>(' + h(a['reviewer_role']) + ')</i>') if a['reviewer_role'] else ''}"
+            f"</td>"
+            f"<td>{h(a['reason'] or '')}</td>"
+            f"<td class=mono>{_ts(a['requested_ts_ms'])}<br>"
+            f"{_ts(a['decided_ts_ms'])}</td></tr>")
+
+    ctl_rows = [
+        f"<tr><td class=mono>{_ts(c['ts_ms'])}</td>"
+        f"<td><code>{h(c['type'])}</code></td>"
+        f"<td>{h(str(c['by'] or ''))}</td>"
+        f"<td>{h(str(c['reason'] or ''))}</td>"
+        f"<td class=mono>{h(json.dumps(c['detail'])[:220])}</td></tr>"
+        for c in controls]
+
+    verdict_cls = "ok" if ok else "bad"
+    verdict_word = "VERIFIED" if ok else "VERIFICATION FAILED"
+    if not bundle.get("signature"):
+        key_line = ("Unsigned bundle: the hash chain is the integrity "
+                    "proof; signature authenticity does not apply.")
+    elif pinned:
+        key_line = (f"Signed with key <code>{key_id}</code>, verified "
+                    f"against the pinned key ring.")
+    else:
+        key_line = (f"Signed with key <code>{key_id}</code>. UNPINNED: "
+                    f"this proves self-consistency only; pass --pubring "
+                    f"for authenticity.")
+
+    html_doc = f"""<!doctype html><html lang=en><head><meta charset=utf-8>
+<title>Primary Path evidence pack · {h(scope)}</title>
+<style>{_REPORT_CSS}</style></head><body>
+<h1>Evidence pack</h1>
+<p class=sub>Scope <code>{h(scope)}</code> · {len(_all_events(bundle))}
+chained events · generated {_ts(time.time() * 1000)} from
+<code>{h(source)}</code></p>
+<div class="verdict {verdict_cls}">{verdict_word} — {h(msg)}</div>
+<p class=sub>{key_line}
+Chain head <code>{h(str(head))}</code>. Every statement below is folded
+from the verified events themselves; re-verify this pack's source bundle
+anytime with <code>primarypath-verify bundle.json --pubring
+pubring.json</code>.</p>
+<h2>Decisions ({len(approvals)})</h2>
+<table><tr><th>approval</th><th>action</th><th>outcome</th>
+<th>decided by</th><th>reason</th><th>requested / decided (UTC)</th></tr>
+{''.join(rows) or '<tr><td colspan=6>none in this bundle</td></tr>'}</table>
+<h2>Control-plane changes ({len(controls)})</h2>
+<table><tr><th>at (UTC)</th><th>change</th><th>by</th><th>reason</th>
+<th>detail</th></tr>
+{''.join(ctl_rows) or '<tr><td colspan=5>none in this bundle</td></tr>'}</table>
+<footer>Primary Path evidence pack. The proof is the hash chain and the
+Ed25519 signature, not this rendering: any edit to any event names itself
+under re-verification. Tamper-evidence, not tamper-prevention.</footer>
+</body></html>"""
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(html_doc)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("source", help="bundle.json path or service base URL")
+    ap.add_argument("--pubring", help="pinned public-key ring JSON (key_id -> b64)")
+    ap.add_argument("--allow-unsigned", action="store_true",
+                    help="with --pubring: accept a bundle that carries no "
+                         "signature as an integrity-only check (for chains "
+                         "profiled signing_backend: none). Without this, an "
+                         "unsigned bundle FAILS pinned verification")
+    ap.add_argument("--token", help="admin token when fetching from a URL")
+    ap.add_argument("--agent", help="fetch ONE agent's chain (its own head, "
+                                    "its own key)")
+    ap.add_argument("--governance", action="store_true",
+                    help="fetch the control-plane chain")
+    ap.add_argument("--report", metavar="PACK.html",
+                    help="also write a self-contained HTML evidence pack "
+                         "(verdict + every decision, human-readable)")
+    args = ap.parse_args()
+
+    bundle = _load(args.source, args.token, agent=args.agent,
+                   governance=args.governance)
+    pubring = None
+    if args.pubring:
+        with open(args.pubring, encoding="utf-8") as f:
+            pubring = json.load(f)
+
+    ok, msg = verify_bundle(bundle, pubring,
+                            allow_unsigned=args.allow_unsigned)
+    print(("OK  " if ok else "FAIL") + " " + msg)
+    if args.report:
+        # a failed verdict is documented too: that IS the evidence
+        write_report(bundle, args.report, ok, msg,
+                     pinned=pubring is not None, source=args.source)
+        print(f"evidence pack written to {args.report}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())