vitnify 0.2.6__tar.gz → 0.2.8__tar.gz

{vitnify-0.2.6/src/vitnify.egg-info → vitnify-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vitnify
-Version: 0.2.6
+Version: 0.2.8
 Summary: Execution receipts for AI agents: contain, deterministically reconstruct, and cryptographically certify a run.
 Author: vitnify
 License: Apache-2.0

{vitnify-0.2.6 → vitnify-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vitnify"
-version = "0.2.6"
+version = "0.2.8"
 description = "Execution receipts for AI agents: contain, deterministically reconstruct, and cryptographically certify a run."
 readme = "README.md"
 requires-python = ">=3.10"

{vitnify-0.2.6 → vitnify-0.2.8}/src/vitnify/certificate.py

@@ -32,6 +32,19 @@ FORMAT = "vitnify-receipt v2"
 # reconstructs each receipt's signed body per its own `v` (see body()).
 SUPPORTED_FORMATS = frozenset({"vitnify-receipt v1", FORMAT})
 
+# The tool decisions that count as GATED -- the call passed through the capability wall
+# (allow) or was refused by it (deny). Any other label ("observed", ...) is watch-only,
+# not enforcement. This is the SINGLE SOURCE OF TRUTH for the containment predicate:
+# verify_certificate and the human-facing viewer both call it, so the rule cannot drift
+# between the dict a machine checks and the page a person reads.
+GATED_DECISIONS = frozenset({"allow", "deny"})
+
+
+def decision_is_gated(decision) -> bool:
+    """True if a tool decision was gated by the capability wall (allow/deny), not merely
+    observed. Case- and whitespace-insensitive; fails closed on anything unrecognised."""
+    return str(decision).strip().lower() in GATED_DECISIONS
+
 
 def _now_iso() -> str:
     """Issuer-asserted UTC timestamp (second precision). Places the receipt in time
@@ -238,7 +251,7 @@ def verify_certificate(cert: ExecutionCertificate, log: EventLog, key: bytes | N
     # analogue of an empty model_digests. Reported separately, NOT folded into ok, so a
     # valid transcript stays valid while a containment PROOF requires ok AND this True.
     checks["containment_enforced"] = all(
-        str(e.payload.get("decision", "")).strip().lower() in ("allow", "deny")
+        decision_is_gated(e.payload.get("decision"))
         for e in log.events
         if e.kind == Kind.TOOL_CALL.value
     )

{vitnify-0.2.6 → vitnify-0.2.8}/src/vitnify/viewer.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import os, sys, json, html
 
 from ._vendor.pck.cas import MerkleCAS  # noqa: E402
+from .certificate import decision_is_gated  # single source of truth for the containment rule
 
 def _canon(o) -> str:
     return json.dumps(o, sort_keys=True, separators=(",", ":"))
@@ -88,22 +89,56 @@ def render(run: dict) -> str:
     def warn_badge(text):
         return f'<div class="badge warn"><span class="dot"></span>{text}</div>'
 
-    # Whether the receipt PROVES containment, derived from the events the same way the
-    # verifier does: every tool decision must be a gated allow/deny. An observe-only
-    # run (a watching callback that records but does not gate) is a valid transcript but
-    # proves no containment -- it must NOT render as a plain green "verified" receipt,
-    # or a non-engineer is handed a badge that claims more than the receipt shows.
-    containment_enforced = all(
-        str(e["payload"].get("decision", "")).strip().lower() in ("allow", "deny")
-        for e in events if e["kind"] == "tool_call")
-    containment_badge = (badge(True, "Containment enforced", "")
-                         if containment_enforced
-                         else warn_badge("Containment observed — not proven"))
-
-    badges = (badge(v["contained"], "Injection contained", "NOT contained")
-              + badge(v["replay_identical"], "Replay bit-identical", "Replay diverged")
-              + badge(v["cert_ok"], "Certificate verified", "Certificate FAILED")
-              + containment_badge)
+    def neutral_badge(text):
+        return f'<div class="badge neutral"><span class="dot"></span>{text}</div>'
+
+    # Every containment claim on this page is DERIVED from the events with the SAME rule
+    # the verifier uses (decision_is_gated) -- never taken from the caller's verdict dict.
+    # But a claim is only as strong as the evidence under it, so the page asserts
+    # containment POSITIVELY only when both hold:
+    #   * the certificate verifies -- otherwise the log is UNVERIFIED and may be the very
+    #     forgery the certificate exists to catch, so nothing derived from it can be
+    #     trusted, containment included; and
+    #   * a tool was actually gated -- a run that called no tool has nothing to contain,
+    #     so "contained" would be vacuously true.
+    # verify_certificate reports those cases as containment_enforced=True (a machine
+    # predicate over the events alone); the human page is deliberately stricter and never
+    # reads as "contained" on unverified or empty evidence.
+    tool_events = [e for e in events if e["kind"] == "tool_call"]
+    all_gated = all(decision_is_gated(e["payload"].get("decision")) for e in tool_events)
+    blocked = any(str(e["payload"].get("decision", "")).strip().lower() == "deny" for e in tool_events)
+    cert_ok = bool(v.get("cert_ok"))
+    replay_ok = bool(v.get("replay_identical"))
+    containment_proven = cert_ok and bool(tool_events) and all_gated
+
+    if not cert_ok:
+        containment_badge = warn_badge("Containment unverified — certificate failed")
+    elif not tool_events:
+        containment_badge = neutral_badge("No tool calls")            # nothing to contain
+    elif not all_gated:
+        containment_badge = warn_badge("Containment observed — not proven")
+    elif blocked:
+        containment_badge = badge(True, "Injection contained", "")    # an ungranted call was refused
+    else:
+        containment_badge = badge(True, "Containment enforced", "")   # every call gated; none needed blocking
+
+    badges = (containment_badge
+              + badge(replay_ok, "Replay bit-identical", "Replay diverged")
+              + badge(cert_ok, "Certificate verified", "Certificate FAILED"))
+
+    # Headline asserts ONLY what the evidence supports: "contained" needs a verified log
+    # AND a gated tool; "cryptographically certified" needs the signature to check out.
+    claims = (["contained"] if containment_proven else []) \
+        + (["replayed bit-for-bit"] if replay_ok else []) \
+        + (["cryptographically certified"] if cert_ok else [])
+    if not claims:
+        headline = "Recorded agent run."
+    elif len(claims) == 1:
+        headline = f"This agent run was {claims[0]}."
+    elif len(claims) == 2:
+        headline = f"This agent run was {claims[0]} and {claims[1]}."
+    else:
+        headline = "This agent run was " + ", ".join(claims[:-1]) + f", and {claims[-1]}."
 
     cert_rows = "".join(
         f'<div class="crow"><span class="ck">{k}</span><span class="cv mono">{_esc(val)}</span></div>'
@@ -112,8 +147,8 @@ def render(run: dict) -> str:
             ("capabilities granted", ", ".join(cert["capabilities"])),
             ("event-log root", cert["event_root"]),
             ("chain head", cert["head_hash"]),
-            ("certificate id", cert["digest"]),
-            ("signature (HMAC)", cert["sig"]),
+            ("certificate id", cert.get("digest", "—")),
+            ("signature", cert.get("sig", "—")),
         ])
 
     return f"""<title>Agent Replay Certificate</title>
@@ -150,6 +185,7 @@ h1{{font-size:27px;margin:0;letter-spacing:-.01em;text-wrap:balance;}}
 .badge.good{{color:var(--ok);}} .badge.good .dot{{background:var(--ok);}}
 .badge.bad{{color:var(--tamper);}} .badge.bad .dot{{background:var(--tamper);}}
 .badge.warn{{color:var(--warn);}} .badge.warn .dot{{background:var(--warn);}}
+.badge.neutral{{color:var(--ink-dim);}} .badge.neutral .dot{{background:var(--ink-dim);}}
 section{{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:22px 22px;margin:16px 0;box-shadow:var(--shadow);}}
 .sec-h{{display:flex;align-items:baseline;justify-content:space-between;gap:12px;margin:0 0 14px;}}
 .sec-h h2{{font-size:13px;letter-spacing:.09em;text-transform:uppercase;color:var(--ink-dim);margin:0;font-weight:700;}}
@@ -192,7 +228,7 @@ footer{{color:var(--ink-dim);font-size:12px;margin-top:26px;text-align:center;}}
 <div class="wrap">
   <header class="top">
     <div class="eyebrow">Vitnify &middot; Execution Certificate</div>
-    <h1>This agent run was contained, replayed bit-for-bit, and cryptographically certified.</h1>
+    <h1>{_esc(headline)}</h1>
     <p class="task">Task recorded: &ldquo;{_esc(run.get('task','(agent run)'))}&rdquo;</p>
   </header>
 

{vitnify-0.2.6 → vitnify-0.2.8/src/vitnify.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vitnify
-Version: 0.2.6
+Version: 0.2.8
 Summary: Execution receipts for AI agents: contain, deterministically reconstruct, and cryptographically certify a run.
 Author: vitnify
 License: Apache-2.0

{vitnify-0.2.6 → vitnify-0.2.8}/src/vitnify.egg-info/SOURCES.txt

@@ -30,4 +30,5 @@ tests/test_events.py
 tests/test_l2_recompute.py
 tests/test_receipt_v2.py
 tests/test_verification.py
-tests/test_verify_hardening.py
+tests/test_verify_hardening.py
+tests/test_viewer.py

vitnify-0.2.8/tests/test_viewer.py

@@ -0,0 +1,133 @@
+"""The viewer renders receipts for humans, so its claims must be exactly as strong as
+the receipt -- no more. These tests assert the HEADLINE (the largest text on the page)
+and the badges are honest about containment, derived from the events rather than taken
+on faith from the caller's verdict dict. The headline used to be an unconditional
+string that asserted containment even for an observe-only run; nothing imported the
+viewer, so that survived. This is the coverage that closes it.
+"""
+from __future__ import annotations
+import re
+from dataclasses import asdict
+
+from vitnify.events import EventLog, Kind
+from vitnify.certificate import issue_certificate, verify_certificate, gen_ed25519
+from vitnify.viewer import render
+
+PRIV, PUB = gen_ed25519()
+
+
+def _build(decisions, *, cert_ok=True, replay=True):
+    """A run dict shaped exactly like the demos build (examples/demo_react.py)."""
+    log = EventLog()
+    log.append_llm_call("ph", [1, 2, 3], seed=0, model_digest="dd")
+    for i, d in enumerate(decisions):
+        p = {"tool": f"tool{i}", "decision": d}
+        dl = str(d).strip().lower()
+        if dl == "allow":
+            p.update(result="x", result_hash="h")   # gated allow: result + hash
+        elif dl != "deny":
+            p["result"] = "x"                        # observed / other: watched, result recorded
+        # a clean deny carries no result
+        log.append(Kind.TOOL_CALL, p)
+    cert, _ = issue_certificate("prog", ["tool0"], log, priv=PRIV)
+    run = {
+        "task": "demo",
+        "events": [asdict(e) for e in log.events],
+        "certificate": {"program_hash": cert.program_hash, "capabilities": cert.capabilities,
+                        "event_root": cert.event_root, "head_hash": cert.head_hash,
+                        "digest": cert.digest(), "sig": cert.sig},
+        "verdict": {"contained": True, "replay_identical": replay, "cert_ok": cert_ok},
+    }
+    return run, log
+
+
+def _headline(html):
+    return re.search(r"<h1>(.*?)</h1>", html, re.S).group(1)
+
+
+def _badges(html):
+    return re.findall(r'class="badge (\w+)"><span class="dot"></span>([^<]*)', html)
+
+
+def test_observe_only_headline_does_not_claim_containment():
+    # The regression: an observe-only run must not read as "contained" in the headline.
+    run, _ = _build(["observed"])
+    html = render(run)
+    headline = _headline(html)
+    assert "contained" not in headline.lower()
+    assert "Containment observed — not proven" in html
+    # it may still honestly claim the properties that DO hold
+    assert "replayed bit-for-bit" in headline and "cryptographically certified" in headline
+    # and the warn badge, not a green containment badge
+    assert ("warn", "Containment observed — not proven") in _badges(html)
+    assert not any(txt.startswith("Injection contained") or txt.startswith("Containment enforced")
+                   for _, txt in _badges(html))
+
+
+def test_enforced_with_block_claims_containment():
+    run, _ = _build(["allow", "deny"])
+    html = render(run)
+    assert "contained" in _headline(html).lower()
+    assert ("good", "Injection contained") in _badges(html)
+    assert "Containment observed" not in html
+
+
+def test_enforced_all_allow_claims_containment():
+    run, _ = _build(["allow"])
+    html = render(run)
+    assert "contained" in _headline(html).lower()
+    assert ("good", "Containment enforced") in _badges(html)
+    assert "Containment observed" not in html
+
+
+def test_cert_failed_drops_all_derived_claims():
+    # If the certificate does not verify, the event log is UNVERIFIED -- it may be the
+    # very forgery the certificate exists to catch -- so the page must not claim
+    # containment (or certification) from it, even though every event reads as gated.
+    run, _ = _build(["allow"], cert_ok=False)
+    html = render(run)
+    headline = _headline(html)
+    assert "cryptographically certified" not in headline
+    assert "contained" not in headline.lower()
+    assert ("warn", "Containment unverified — certificate failed") in _badges(html)
+    assert ("bad", "Certificate FAILED") in _badges(html)
+    assert not any(t in ("Injection contained", "Containment enforced") for _, t in _badges(html))
+
+
+def test_zero_tool_run_is_not_vacuously_contained():
+    # all([]) is True, so a tool-free run is containment_enforced at the API level -- but
+    # the page must not tell a human the run was "contained" when nothing was ever gated.
+    run, _ = _build([])  # llm_call only, no tool calls
+    html = render(run)
+    assert "contained" not in _headline(html).lower()
+    assert ("neutral", "No tool calls") in _badges(html)
+
+
+def test_viewer_never_claims_containment_without_verified_gating():
+    # Soundness: the headline reads "contained" ONLY when the certificate verifies, a
+    # tool was actually gated, and the verifier's own predicate agrees gating held. The
+    # page never claims containment on unverified, empty, or ungated evidence.
+    cases = [(["allow", "deny"], True), (["observed"], True), (["allow"], True),
+             (["PERMIT"], True), (["allow"], False), ([], True)]
+    for decisions, cert_ok in cases:
+        run, log = _build(decisions, cert_ok=cert_ok)
+        says_contained = "contained" in _headline(render(run)).lower()
+        enforced = verify_certificate(_recert(run), log)["containment_enforced"]
+        if says_contained:
+            assert cert_ok and bool(decisions) and enforced, (decisions, cert_ok)
+
+
+def test_render_tolerates_missing_digest():
+    # render() must not require a `digest` key that cert.to_json() does not emit.
+    run, _ = _build(["allow"])
+    del run["certificate"]["digest"]
+    del run["certificate"]["sig"]
+    html = render(run)  # must not raise
+    assert "—" in html
+
+
+def _recert(run):
+    from vitnify.certificate import ExecutionCertificate
+    c = run["certificate"]
+    return ExecutionCertificate(c["program_hash"], c["capabilities"], c["event_root"],
+                                len(run["events"]), c["head_hash"])