provelog 1.2.0__py3-none-any.whl

provelog/__init__.py

@@ -0,0 +1,11 @@
+"""ProveLog: local, tamper-evident evidence for AI-agent work.
+
+The public product is the CLI (`provelog`). There is no public Python SDK;
+`provelog.sdk.Provelog` is an internal recording engine used by the collector,
+importers.
+"""
+
+                                                                         
+__version__ = "1.2.0"
+
+GENESIS_PREV_HASH = "0" * 64

provelog/__main__.py

@@ -0,0 +1,14 @@
+"""`python -m provelog`: the CLI through the interpreter, immune to PATH order.
+
+Every subcommand works identically to the `provelog` console script:
+    python -m provelog verify bundle.json
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

provelog/active.py

@@ -0,0 +1,26 @@
+"""The process-local active-recorder slot, shared by the SDK and the easy front.
+
+A ContextVar lives here rather than in either module so instrumentation can
+prefer the innermost OPEN session regardless of whether it was opened by
+the internal `easy.record(...)` helper or by a bare `Provelog.session()` - both set it. Without the
+SDK setting it, an explicitly-instrumented client recorded into whatever
+recorder the wrapper was last bound to, silently crossing sessions.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+_active: ContextVar = ContextVar("provelog_active_recorder", default=None)
+
+
+def current():
+    return _active.get()
+
+
+def set_active(recorder):
+    return _active.set(recorder)
+
+
+def reset(token):
+    _active.reset(token)

provelog/anchor.py

@@ -0,0 +1,223 @@
+"""External anchoring of the server receipt-chain head.
+
+Anchoring bounds the tamper window: anything anchored cannot be rewritten without
+the anchor failing to verify. We anchor a Merkle root over a batch of receipt hashes.
+
+Two backends:
+  - RFC3161Anchor: real trusted timestamp from a TSA. The server default is
+    Sectigo primary with FreeTSA as the failure fallback. The TSA genTime is
+    authoritative wall-clock; the verifier flags client ts_utc that trails it.
+  - LocalAnchor: offline/dev anchor signed by a separate "anchor key". Carries NO
+    third-party trust; used for tests and air-gapped runs. Clearly labelled in output.
+
+Merkle construction follows RFC 6962 domain separation (0x00 leaf / 0x01 node) so the
+inclusion proofs are interoperable with standard transparency tooling.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Protocol
+
+_log = logging.getLogger("provelog.anchor")
+
+
+def _leaf(h: bytes) -> bytes:
+    return hashlib.sha256(b"\x00" + h).digest()
+
+
+def _node(l: bytes, r: bytes) -> bytes:
+    return hashlib.sha256(b"\x01" + l + r).digest()
+
+
+def merkle_root(leaves_hex: list[str]) -> str:
+    if not leaves_hex:
+        return "0" * 64
+    level = [_leaf(bytes.fromhex(h)) for h in leaves_hex]
+    while len(level) > 1:
+        nxt = []
+        for i in range(0, len(level), 2):
+            if i + 1 < len(level):
+                nxt.append(_node(level[i], level[i + 1]))
+            else:
+                nxt.append(level[i])                               
+        level = nxt
+    return level[0].hex()
+
+
+def _checked_root(root_hex: str) -> str:
+    """A root arrives over the wire in the anchor-only service, so it is untrusted input. It must
+    be exactly 32 hex-encoded bytes: anything else is a client bug, and timestamping it would mint
+    a receipt that can never match any bundle."""
+    root = (root_hex or "").strip().lower()
+    if len(root) != 64:
+        raise ValueError(f"a Merkle root is 32 bytes, so 64 hex characters, got {len(root)}")
+    try:
+        bytes.fromhex(root)
+    except ValueError:
+        raise ValueError("a Merkle root must be hex") from None
+    return root
+
+
+@dataclass
+class AnchorReceipt:
+    kind: str                                 
+    merkle_root: str
+    gen_time: str                                                       
+    token_b64: str | None = None                                                
+    signature: str | None = None                                              
+    anchor_pubkey: str | None = None
+    tsa_url: str | None = None
+
+
+class Anchor(Protocol):
+    def anchor(self, leaves_hex: list[str]) -> AnchorReceipt: ...
+    def anchor_root(self, root_hex: str) -> AnchorReceipt: ...
+
+
+class LocalAnchor:
+    """Offline anchor signed by a dedicated key held outside the agent process."""
+
+    def __init__(self, signing_key=None):
+        from .keys import SigningKey                                                 
+        self._key = signing_key or SigningKey.generate()
+
+    def anchor(self, leaves_hex: list[str]) -> AnchorReceipt:
+        return self.anchor_root(merkle_root(leaves_hex))
+
+    def anchor_root(self, root_hex: str) -> AnchorReceipt:
+        """Timestamp a root someone else computed. The anchor-only service never sees the
+        leaves, so it cannot derive the root; it can only vouch for the one it was handed."""
+        root = _checked_root(root_hex)
+        gen_time = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        sig = self._key.sign((root + "|" + gen_time).encode("utf-8"))
+        return AnchorReceipt(
+            kind="local",
+            merkle_root=root,
+            gen_time=gen_time,
+            signature=sig,
+            anchor_pubkey=self._key.public_key_hex(),
+        )
+
+
+class RFC3161Anchor:
+    """Trusted timestamp anchor. Defaults to Sectigo's public TSA over HTTPS
+    (probed working 2026-09-22; the HTTP endpoint remains valid); any RFC 3161
+    TSA URL works. FreeTSA remains supported and in the failover list for
+    operators who prefer it. Every round-trip is timed and its HTTP status
+    counted in `stats` - the operator's health check shows which TSA is
+    slow or rate-limiting."""
+
+    def __init__(self, tsa_url: str = "https://timestamp.sectigo.com/rfc3161",
+                 timeout: float = 10.0):
+        self.tsa_url = tsa_url
+        self.timeout = timeout
+        self.stats = {"calls": 0, "ok": 0, "http_429": 0, "http_5xx": 0,
+                      "http_other_error": 0, "total_latency_s": 0.0,
+                      "last_latency_s": 0.0, "last_error": ""}
+
+    def anchor(self, leaves_hex: list[str]) -> AnchorReceipt:
+        return self.anchor_root(merkle_root(leaves_hex))
+
+    def anchor_root(self, root_hex: str) -> AnchorReceipt:
+        import base64
+        import time as _time
+
+        import httpx
+        from rfc3161_client import TimestampRequestBuilder
+
+        from .tsa_der import decode_timestamp_response
+
+        root = _checked_root(root_hex)
+        req = TimestampRequestBuilder().data(bytes.fromhex(root)).build()
+        self.stats["calls"] += 1
+        t0 = _time.monotonic()
+        try:
+            resp = httpx.post(
+                self.tsa_url,
+                content=req.as_bytes(),
+                headers={"Content-Type": "application/timestamp-query"},
+                timeout=self.timeout,
+            )
+            latency = _time.monotonic() - t0
+            self.stats["total_latency_s"] += latency
+            self.stats["last_latency_s"] = latency
+            if resp.status_code == 429:
+                self.stats["http_429"] += 1
+            elif resp.status_code >= 500:
+                self.stats["http_5xx"] += 1
+            elif resp.status_code >= 400:
+                self.stats["http_other_error"] += 1
+            resp.raise_for_status()
+            tst = decode_timestamp_response(resp.content)
+            gen_time = tst.tst_info.gen_time.astimezone(UTC).strftime(
+                "%Y-%m-%dT%H:%M:%S.%fZ"
+            )
+            self.stats["ok"] += 1
+            self.stats["last_error"] = ""
+            return AnchorReceipt(
+                kind="rfc3161",
+                merkle_root=root,
+                gen_time=gen_time,
+                token_b64=base64.b64encode(resp.content).decode("ascii"),
+                tsa_url=self.tsa_url,
+            )
+        except Exception as e:
+            if not self.stats["last_error"]:
+                self.stats["last_error"] = f"{type(e).__name__}: {e}"[:300]
+            raise
+
+
+                                                                             
+                                                                 
+                           
+SECTIGO_TSA_URL = "https://timestamp.sectigo.com/rfc3161"
+FREETSA_TSA_URL = "https://freetsa.org/tsr"
+
+
+class FailoverTSAAnchor:
+    """Primary/fallback TSA chain, in a fixed order.
+
+    It always tries the first TSA first; only a failure hands THIS anchoring
+    call to the next. The default chain is Sectigo -> FreeTSA. Both are
+    independent RFC 3161 TSAs and produce equally valid receipts; the order
+    is preference/availability, not a trust level. FreeTSA permits low volume
+    at 1 request/second/IP, so it is the fallback.
+    If every member fails, the last error is raised and the caller keeps the
+    batch pending; no local stamp is produced.
+    """
+
+    def __init__(self, tsa_urls: list[str] | None = None, timeout: float = 10.0,
+                 _factory=None):
+        urls = ([SECTIGO_TSA_URL, FREETSA_TSA_URL] if tsa_urls is None
+                else list(tsa_urls))
+        if not urls:
+            raise ValueError("FailoverTSAAnchor needs at least one TSA URL")
+        self._factory = _factory or (lambda u: RFC3161Anchor(u, timeout))
+        self.members = [self._factory(u) for u in urls]
+
+    @property
+    def primary_url(self) -> str:
+        return getattr(self.members[0], "tsa_url", "")
+
+    def anchor(self, leaves_hex: list[str]) -> AnchorReceipt:
+        return self.anchor_root(merkle_root(leaves_hex))
+
+    def anchor_root(self, root_hex: str) -> AnchorReceipt:
+        errors: list[str] = []
+        for member in self.members:
+            try:
+                return member.anchor_root(root_hex)
+            except Exception as e:                                              
+                errors.append(f"{getattr(member, 'tsa_url', '?')}: {e}")
+        raise RuntimeError(
+            f"all {len(self.members)} TSAs failed to timestamp; "
+            f"last errors: {'; '.join(errors[-2:])}")
+
+    def stats(self) -> dict:
+        return {"tsa": {m.tsa_url: dict(m.stats) for m in self.members}}
+
+

provelog/anchoring.py

@@ -0,0 +1,327 @@
+"""Client-side anchor submission for the log collector process.
+
+A claim is tiny: one Merkle root over a stream's receipt hashes, a count, and a
+device signature. The service folds every claim it receives into a single
+RFC 3161 stamp per 60 s epoch, so the number of TSA calls grows with time, not
+with the number of conversations or users - which is what makes stamping
+free to offer.
+
+Rules, all of them deliberate:
+
+* **One claim per stream per minute.** A newer claim supersedes an older one
+  (``covers_up_to`` only grows), so more often than that buys nothing and
+  spends the service's per-IP budget, of which a busy machine with subagents
+  already has several streams.
+* **Only when the stream grew.** A quiet conversation is not re-pushed.
+* **Never break collection.** Every failure here is silent: the records are
+  already on disk and signed, and the next pass retries. Stamping is the only
+  network dependency in the product, so it must never be able to stop it.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .netutil import client_for
+
+                                                                              
+                                                        
+ANCHOR_EVERY_S = 60.0
+ANCHOR_TIMEOUT_S = 4.0
+                                                                                
+                                                                                 
+ANCHOR_BACKOFF_S = 300.0
+                                                                           
+                                                                            
+                                                                             
+                                                                         
+PENDING_TTL_S = 600.0
+
+                                                                               
+                                                           
+_last_attempt: dict[str, float] = {}
+_down_until: float = 0.0
+_last_429: float = 0.0
+_upgrade_required: dict[str, Any] | None = None
+_upgrade_noticed = False
+                                                                              
+                                                                           
+                                                                           
+                                                                        
+_pickup_at: dict[str, float] = {}
+
+
+def upgrade_info() -> dict[str, Any] | None:
+    """The relay's last 426 response, if this process received one."""
+    return _upgrade_required
+
+
+def _journal_path(store: Any) -> Path | None:
+    root = getattr(store, "root", None)
+    return None if root is None else Path(root) / ".internal" / "pending_anchors.json"
+
+
+def _journal(store: Any) -> dict[str, str]:
+    """{stream_id: anchor_id} for claims whose receipt is still queued.
+
+    A file, not a scan: with thousands of conversations, "ask every stream whether
+    it has a pending receipt" is O(n^2) per pass (98 ms per call at 3,000 folders,
+    measured), while this is one small read.
+    """
+    path = _journal_path(store)
+    if path is None or not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _journal_set(store: Any, stream_id: str, anchor_id: str | None) -> None:
+    path = _journal_path(store)
+    if path is None:
+        return
+    rows = _journal(store)
+    if anchor_id:
+        rows[stream_id] = anchor_id
+    else:
+        rows.pop(stream_id, None)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(rows, indent=2), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def pickup_pending(store: Any, *, url: str | None = None,
+                   limit: int = 50, timeout: float = ANCHOR_TIMEOUT_S,
+                   now: float | None = None) -> int:
+    """Fetch receipts for claims this machine knows are queued. Bounded per pass.
+
+    A 404 means the epoch has not minted the receipt yet (normal right after a
+    claim): the journal pointer is KEPT and re-polled at most once per epoch, so
+    a quiet session still receives its receipt promptly. The pointer is dropped
+    only when the receipt is delivered, the relay says it is gone (410), or the
+    claim outlives the TTL - the TTL path in ``maybe_anchor`` then fails and
+    re-claims it.
+    """
+    rows = _journal(store)
+    if not rows:
+        return 0
+    base = (url or endpoint()).rstrip("/")
+    resolved = 0
+    fetched = 0
+    stamp = now if now is not None else time.time()
+    for stream_id, anchor_id in list(rows.items()):
+        if fetched >= limit:
+            break
+        if _pickup_at.get(stream_id, 0.0) > stamp:
+            continue                                                         
+        try:
+            with client_for(base, timeout=timeout) as client:
+                resp = client.get(f"{base}/v1/anchors/{anchor_id}")
+        except Exception:
+            return resolved
+        fetched += 1
+        if resp.status_code == 200:
+            try:
+                store.resolve_pending_anchor(stream_id, resp.json())
+            except Exception:
+                continue
+            _journal_set(store, stream_id, None)
+            _pickup_at.pop(stream_id, None)
+            resolved += 1
+        elif resp.status_code == 410:
+                                                                            
+                                                                             
+                                                                   
+            _journal_set(store, stream_id, None)
+            _pickup_at.pop(stream_id, None)
+        else:
+                                                                          
+                                                                              
+                                                                         
+            pending = (store.pending_anchor(stream_id)
+                       if hasattr(store, "pending_anchor") else None)
+            if pending and _age_seconds(pending.get("created_at")) >= PENDING_TTL_S:
+                _journal_set(store, stream_id, None)
+                _pickup_at.pop(stream_id, None)
+            else:
+                _pickup_at[stream_id] = stamp + ANCHOR_EVERY_S
+    return resolved
+
+
+def endpoint(config: dict[str, Any] | None = None) -> str:
+    """Where claims go: the configured endpoint, else the hosted default."""
+    if config and config.get("anchor_endpoint"):
+        return str(config["anchor_endpoint"]).rstrip("/")
+    from .easy import _resolve
+    return str(_resolve().get("anchor_endpoint") or "https://provelog.ai").rstrip("/")
+
+
+def rate_limited_recently(now: float | None = None, window: float = 180.0) -> bool:
+    """Did the service push back in the last few minutes?"""
+    stamp = now if now is not None else time.time()
+    return bool(_last_429) and (stamp - _last_429) < window
+
+
+def _age_seconds(stamp: Any) -> float:
+    try:
+        parsed = datetime.fromisoformat(str(stamp).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return float("inf")
+    return (datetime.now(UTC) - parsed.astimezone(UTC)).total_seconds()
+
+
+def pickup(store: Any, stream_id: str, *, url: str | None = None,
+           timeout: float = ANCHOR_TIMEOUT_S) -> bool:
+    """Fetch a receipt the service has finished minting. Silent on failure."""
+    if not hasattr(store, "pending_anchor"):
+        return False
+    pending = store.pending_anchor(stream_id)
+    if not pending or not pending.get("anchor_id"):
+        return False
+    import httpx
+
+    target = url or endpoint()
+    try:
+        with client_for(target, timeout=timeout) as client:
+            resp = client.get(f"{target}/v1/anchors/{pending['anchor_id']}")
+    except httpx.HTTPError:
+        return False
+    if resp.status_code != 200:
+                                                                             
+                                                                               
+                                                                          
+        return False
+    try:
+        body = resp.json()
+    except ValueError:
+        return False
+    store.resolve_pending_anchor(stream_id, body)
+    return True
+
+
+def maybe_anchor(store: Any, stream_id: str, *, url: str | None = None,
+                 key: Any | None = None, now: float | None = None,
+                 timeout: float = ANCHOR_TIMEOUT_S,
+                 force: bool = False, lane: str = "live") -> dict[str, Any] | None:
+    """Push one claim for this stream if it grew; pick up a finished receipt first."""
+    if not hasattr(store, "anchor_leaves"):
+        return None
+    global _down_until, _upgrade_required, _upgrade_noticed
+
+    stamp_now = now if now is not None else time.time()
+    if _upgrade_required is not None:
+        return None
+    if stamp_now < _down_until:
+        return None
+    url = (url or endpoint()).rstrip("/")
+
+    pickup(store, stream_id, url=url, timeout=timeout)
+
+    leaves = store.anchor_leaves(stream_id)
+    if not leaves:
+        return None
+    anchors = store.anchors_for_stream(stream_id) if hasattr(store, "anchors_for_stream") else []
+                                                                               
+                                                                         
+    delivered = [a for a in anchors if not a.get("pending") and not a.get("failed")]
+    covered = max((int(a.get("covers_up_to") or 0) for a in delivered), default=0)
+    if len(leaves) <= covered:
+        return None
+                                                                               
+                                                                              
+                                                                               
+                                                                       
+    pending = store.pending_anchor(stream_id) if hasattr(store, "pending_anchor") else None
+    if pending:
+        stale = _age_seconds(pending.get("created_at")) >= PENDING_TTL_S
+        if stale:
+            if hasattr(store, "fail_pending_anchor"):
+                store.fail_pending_anchor(stream_id, pending["anchor_id"],
+                                          "no receipt within TTL; re-claiming")
+        elif len(leaves) <= int(pending.get("covers_up_to") or 0):
+            return None
+    if not force:
+        last = _last_attempt.get(stream_id, 0.0)
+        if stamp_now - last < ANCHOR_EVERY_S:
+            return None
+        if delivered and _age_seconds(delivered[-1].get("created_at")) < ANCHOR_EVERY_S:
+            return None
+    _last_attempt[stream_id] = stamp_now
+
+    import httpx
+
+    from .anchor import merkle_root
+    from .easy import _device_key
+
+    root = merkle_root(leaves)
+    signing_key = key or _device_key()
+    covers = len(leaves)
+    payload = {
+        "stream_id": stream_id,
+        "merkle_root": root,
+        "covers_up_to": covers,
+        "device_pubkey": signing_key.public_key_hex(),
+        "device_sig": signing_key.sign(
+            f"{stream_id}||{root}||{covers}||{lane}".encode()),
+        "lane": lane,
+    }
+    from . import __version__
+
+    try:
+        with client_for(url, timeout=timeout) as client:
+            resp = client.post(f"{url}/v1/anchors", json=payload,
+                               headers={"X-ProveLog-Version": __version__})
+    except httpx.HTTPError:
+        _down_until = stamp_now + ANCHOR_BACKOFF_S
+        return None
+    if resp.status_code == 426:
+                                                                             
+                                                                                
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+        _upgrade_required = body if isinstance(body, dict) else {}
+        if not _upgrade_noticed:
+            from .version import DOWNLOAD_URL
+            url_hint = str(_upgrade_required.get("url") or DOWNLOAD_URL)
+            print("ProveLog: this version is no longer supported by the stamping "
+                  f"service. Update: {url_hint}", file=__import__("sys").stderr)
+            _upgrade_noticed = True
+        return None
+    if resp.status_code == 429:
+                                                                              
+                                                                          
+        global _last_429
+        _last_429 = stamp_now
+        return None
+    if resp.status_code >= 500:
+        _down_until = stamp_now + ANCHOR_BACKOFF_S
+        return None
+    if resp.status_code != 200:
+        return None
+    try:
+        out = resp.json()
+    except ValueError:
+        return None
+    if not isinstance(out, dict):
+        return None
+    if out.get("status") == "queued":
+                                                                              
+                                                         
+        store.add_anchor(stream_id, out, covers_up_to=covers,
+                         anchor_id=out.get("anchor_id"), pending=True)
+        _journal_set(store, stream_id, out.get("anchor_id"))
+        _pickup_at.pop(stream_id, None)                                           
+        return out
+    store.add_anchor(stream_id, out, covers_up_to=covers,
+                     anchor_id=out.get("anchor_id"))
+    return out

provelog/assets/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#0E8F7E"/>
+  <path d="M23.7 19.2 L41 32 L23.7 44.8" fill="none" stroke="#FFFFFF"
+        stroke-width="6.7" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>