tallylock 0.1.0a1__py3-none-any.whl

tallylock/__init__.py

@@ -0,0 +1,3 @@
+"""Standalone evaluation receipts and offline evidence verification."""
+
+__version__ = "0.1.0a1"

tallylock/__main__.py

@@ -0,0 +1,4 @@
+"""Dispatch ``python -m tallylock`` through the installed command interface."""
+from .cli import main
+
+raise SystemExit(main())

tallylock/_http.py

@@ -0,0 +1,223 @@
+"""Private one-request HTTP boundary, supervised by an absolute deadline."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import base64
+import http.client
+import json
+import math
+import os
+import re
+import select
+import ssl
+import subprocess
+import sys
+import time
+from urllib.parse import urlsplit
+
+from .errors import TallyLockError
+
+
+_MAX_REQUEST_IPC = 2 * 1024 * 1024
+_MAX_REQUEST_BODY = 1024 * 1024
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    body: bytes
+    retry_after: str | None
+
+
+class NetworkError(TallyLockError):
+    def __init__(self):
+        super().__init__("HTTP network request failed or exceeded its deadline", code=5)
+
+
+def _perform(method, url, body, headers, limit, timeout):
+    connection = None
+    try:
+        parsed = urlsplit(url)
+        cls = http.client.HTTPSConnection if parsed.scheme == "https" else http.client.HTTPConnection
+        options = {"timeout": timeout}
+        if parsed.scheme == "https":
+            options["context"] = ssl.create_default_context()
+        connection = cls(parsed.hostname, parsed.port, **options)
+        path = parsed.path or "/"
+        if parsed.query:
+            path += "?" + parsed.query
+        connection.request(method, path, body=body, headers=headers)
+        response = connection.getresponse()
+        lengths = response.headers.get_all("Content-Length", [])
+        encodings = response.headers.get_all("Transfer-Encoding", [])
+        if (len(lengths) > 1 or len(encodings) > 1 or lengths and encodings
+                or encodings and encodings[0].lower() != "chunked"):
+            raise ValueError("response framing")
+        expected = None
+        if lengths:
+            if re.fullmatch(r"[0-9]{1,16}", lengths[0]) is None:
+                raise ValueError("response framing")
+            expected = int(lengths[0])
+            if response.status == 200 and expected > limit:
+                raise ValueError("response limit")
+        retry = response.getheader("Retry-After")
+        if retry is not None and (len(retry) > 256 or not retry.isascii()):
+            retry = None
+        # Error/redirect bodies are neither useful evidence nor safe diagnostics.
+        # Keep them entirely inside the remote connection, outside our IPC.
+        data = response.read(limit + 1) if response.status == 200 else b""
+        if len(data) > limit:
+            raise ValueError("response limit")
+        if response.status == 200 and expected is not None and len(data) != expected:
+            raise ValueError("truncated response")
+        metadata = {"status": response.status, "retry_after": retry}
+    except http.client.RemoteDisconnected:
+        metadata, data = {"error": "network"}, b""
+    except (ssl.SSLError, http.client.HTTPException, ValueError):
+        metadata, data = {"error": "response"}, b""
+    except OSError:
+        metadata, data = {"error": "network"}, b""
+    except Exception:
+        metadata, data = {"error": "response"}, b""
+    finally:
+        if connection is not None:
+            connection.close()
+    return json.dumps(metadata, separators=(",", ":")).encode() + b"\n" + data
+
+
+def _worker():
+    """Static child entry: request data arrives exclusively through bounded stdin."""
+    try:
+        data = sys.stdin.buffer.read(_MAX_REQUEST_IPC + 1)
+        if len(data) > _MAX_REQUEST_IPC:
+            raise ValueError("request IPC limit")
+        value = json.loads(data)
+        body = base64.b64decode(value["body"], validate=True) if value["body"] is not None else None
+        output = _perform(value["method"], value["url"], body, value["headers"],
+                          value["response_limit"], value["timeout"])
+    except Exception:
+        output = b'{"error":"response"}\n'
+    sys.stdout.buffer.write(output)
+    sys.stdout.buffer.flush()
+
+
+def request(method, url, *, body, headers, response_limit, timeout_seconds=10,
+            deadline: float | None = None) -> Response:
+    """Do one request; DNS, TLS, body reads and IPC share one wall-clock bound."""
+    try:
+        parsed = urlsplit(url)
+        valid = (parsed.scheme in {"http", "https"} and parsed.hostname
+                 and parsed.username is None and parsed.password is None
+                 and not parsed.fragment and not any(ord(c) <= 32 or ord(c) == 127 for c in url))
+        parsed.port
+    except (ValueError, TypeError):
+        valid = False
+    if not valid or method not in {"GET", "POST"}:
+        raise TallyLockError("invalid HTTP request", code=5)
+    if (body is not None and (not isinstance(body, bytes) or len(body) > _MAX_REQUEST_BODY)
+            or not isinstance(headers, dict) or len(headers) > 128
+            or any(not isinstance(k, str) or not isinstance(v, str) for k, v in headers.items())):
+        raise TallyLockError("invalid HTTP request payload", code=5)
+    if len(url) > 16384 or sum(len(k)+len(v) for k, v in headers.items()) > 65536:
+        raise TallyLockError("HTTP request metadata exceeds size limit", code=5)
+    if (type(response_limit) is not int or not 0 <= response_limit <= 32 * 1024 * 1024
+            or isinstance(timeout_seconds, bool) or not isinstance(timeout_seconds, (int, float))
+            or not math.isfinite(timeout_seconds) or timeout_seconds <= 0):
+        raise TallyLockError("invalid HTTP request bounds", code=5)
+    end = time.monotonic() + timeout_seconds
+    if deadline is not None:
+        if isinstance(deadline, bool) or not isinstance(deadline, (int, float)) or not math.isfinite(deadline):
+            raise TallyLockError("invalid absolute HTTP deadline", code=5)
+        end = min(end, deadline)
+    if end <= time.monotonic():
+        raise NetworkError()
+    payload = json.dumps({"method": method, "url": url,
+        "body": base64.b64encode(body).decode("ascii") if body is not None else None,
+        "headers": headers, "response_limit": response_limit,
+        "timeout": end-time.monotonic()}, separators=(",", ":")).encode()
+    if len(payload) > _MAX_REQUEST_IPC:
+        raise TallyLockError("HTTP request IPC exceeds size limit", code=5)
+    chunks = bytearray()
+    child = None
+    primary = None
+    closed_streams = set()
+
+    def close_once(name):
+        if name not in closed_streams:
+            closed_streams.add(name)
+            getattr(child, name).close()
+
+    try:
+        child = subprocess.Popen([sys.executable, "-I", "-m", "tallylock._http"], stdin=subprocess.PIPE,
+                                 stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, close_fds=True)
+        os.set_blocking(child.stdin.fileno(), False)
+        os.set_blocking(child.stdout.fileno(), False)
+        position = 0
+        while True:
+            remaining = end - time.monotonic()
+            if remaining <= 0:
+                raise NetworkError()
+            writes = [child.stdin.fileno()] if not child.stdin.closed else []
+            ready, writable, _ = select.select([child.stdout.fileno()], writes, [], remaining)
+            if not ready and not writable:
+                raise NetworkError()
+            if writable:
+                position += os.write(child.stdin.fileno(), payload[position:position+65536])
+                if position == len(payload):
+                    close_once("stdin")
+            if not ready:
+                continue
+            chunk = os.read(child.stdout.fileno(), 65536)
+            if not chunk:
+                break
+            chunks.extend(chunk)
+            if len(chunks) > response_limit + 2048:
+                raise TallyLockError("HTTP response exceeds size limit", code=5)
+        header, separator, data = bytes(chunks).partition(b"\n")
+        if not separator:
+            raise TallyLockError("HTTP request failed", code=5)
+        metadata = json.loads(header)
+        if metadata.get("error") == "network":
+            raise NetworkError()
+        if "error" in metadata:
+            raise TallyLockError("HTTP response failed validation", code=5)
+        if metadata["status"] == 401:
+            raise TallyLockError("HTTP authentication failed", code=5)
+        return Response(metadata["status"], data, metadata["retry_after"])
+    except (OSError, ValueError, KeyError):
+        primary = TallyLockError("HTTP request failed", code=5)
+        raise primary from None
+    except BaseException as error:
+        primary = error
+        raise
+    finally:
+        if child is not None:
+            cleanup_failed = False
+
+            def cleanup(operation):
+                nonlocal cleanup_failed
+                try:
+                    operation()
+                except BaseException:
+                    cleanup_failed = True
+
+            # A close can release its descriptor and still raise. Attempt each
+            # close once, then finish child cleanup even after secondary errors.
+            cleanup(lambda: close_once("stdin"))
+            cleanup(lambda: close_once("stdout"))
+            cleanup(child.terminate)
+            try:
+                child.wait(timeout=.2)
+            except subprocess.TimeoutExpired:
+                cleanup(child.kill)
+                cleanup(child.wait)
+            except BaseException:
+                cleanup_failed = True
+                cleanup(child.kill)
+                cleanup(child.wait)
+            if cleanup_failed and primary is None:
+                raise TallyLockError("HTTP request cleanup failed", code=5) from None
+
+
+if __name__ == "__main__":
+    _worker()

tallylock/anchors.py

@@ -0,0 +1,193 @@
+"""Bounded standard detached OTS inspection and explicit offline verification."""
+
+from __future__ import annotations
+
+import re
+
+from bitcoin.core import CBlockHeader
+from opentimestamps.core.notary import (
+    BitcoinBlockHeaderAttestation, PendingAttestation, TimeAttestation,
+    VerificationError,
+)
+from opentimestamps.core.op import CryptOp, Op, OpSHA256
+from opentimestamps.core.serialize import BytesDeserializationContext, DeserializationError
+from opentimestamps.core.timestamp import DetachedTimestampFile, Timestamp
+
+from .canonical import MAX_SAFE_INTEGER
+from .chain import ChainView
+from .errors import TallyLockError
+
+
+MAX_PROOF_BYTES = 16 * 1024 * 1024
+# Match the pinned upstream timestamp decoder's default recursion policy.
+MAX_TIMESTAMP_DEPTH = 256
+MAX_TIMESTAMP_ITEMS = 100000
+
+
+def _expected_digest(value: str) -> None:
+    if not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{64}", value) is None:
+        raise TallyLockError("expected SHA256 must be exactly 64 lowercase hex characters")
+
+
+def _detached_header(ctx, expected_sha256: str) -> bytes:
+    ctx.assert_magic(DetachedTimestampFile.HEADER_MAGIC)
+    major = ctx.read_uint8()
+    if major != DetachedTimestampFile.MAJOR_VERSION:
+        raise TallyLockError(f"unsupported detached timestamp major version: {major}", code=4)
+    file_hash_op = CryptOp.deserialize(ctx)
+    if not isinstance(file_hash_op, OpSHA256):
+        raise TallyLockError("unsupported detached file hash algorithm", code=4)
+    digest = ctx.read_bytes(file_hash_op.DIGEST_LENGTH)
+    if digest.hex() != expected_sha256:
+        raise TallyLockError("detached timestamp digest differs from the expected core SHA256")
+    return digest
+
+
+def _preflight_timestamp(ctx) -> None:
+    """Walk upstream framing and bounds, without invoking any proof operation."""
+    items = 0
+
+    def count_item():
+        nonlocal items
+        items += 1
+        if items > MAX_TIMESTAMP_ITEMS:
+            raise TallyLockError("timestamp exceeds the aggregate item limit")
+
+    def node(depth):
+        if depth > MAX_TIMESTAMP_DEPTH:
+            raise TallyLockError("timestamp exceeds the depth limit")
+        count_item()
+        operations = set()
+
+        def entry(tag):
+            if tag == b"\x00":
+                count_item()
+                TimeAttestation.deserialize(ctx)
+            else:
+                operation = Op.deserialize_from_tag(ctx, tag)
+                if operation in operations:
+                    raise TallyLockError("timestamp repeats an operation at the same node")
+                operations.add(operation)
+                node(depth + 1)
+
+        tag = ctx.read_bytes(1)
+        while tag == b"\xff":
+            entry(ctx.read_bytes(1))
+            tag = ctx.read_bytes(1)
+        entry(tag)
+
+    node(1)
+
+
+def _load(data: bytes, expected_sha256: str) -> Timestamp:
+    _expected_digest(expected_sha256)
+    if not isinstance(data, bytes):
+        raise TallyLockError("detached timestamp must be bytes")
+    if len(data) > MAX_PROOF_BYTES:
+        raise TallyLockError("detached timestamp exceeds 16 MiB")
+    try:
+        ctx = BytesDeserializationContext(data)
+        _detached_header(ctx, expected_sha256)
+        _preflight_timestamp(ctx)
+        ctx.assert_eof()
+        # Only fully bounded framing reaches upstream operation evaluation.
+        ctx = BytesDeserializationContext(data)
+        digest = _detached_header(ctx, expected_sha256)
+        stamp = Timestamp.deserialize(ctx, digest, _recursion_limit=MAX_TIMESTAMP_DEPTH)
+        ctx.assert_eof()
+        return stamp
+    except (DeserializationError, ValueError) as error:
+        raise TallyLockError(f"invalid detached timestamp: {error}") from error
+
+
+def parse_timestamp(data: bytes, commitment: bytes) -> Timestamp:
+    """Bound raw calendar framing before evaluating standard upstream operations."""
+    if not isinstance(data, bytes) or len(data) > 10000:
+        raise TallyLockError("calendar timestamp exceeds its byte limit")
+    if not isinstance(commitment, bytes) or not 1 <= len(commitment) <= 4096:
+        raise TallyLockError("invalid calendar commitment")
+    try:
+        ctx = BytesDeserializationContext(data)
+        _preflight_timestamp(ctx)
+        ctx.assert_eof()
+        ctx = BytesDeserializationContext(data)
+        stamp = Timestamp.deserialize(ctx, commitment, _recursion_limit=MAX_TIMESTAMP_DEPTH)
+        ctx.assert_eof()
+        return stamp
+    except (DeserializationError, ValueError) as error:
+        raise TallyLockError("invalid raw calendar timestamp") from error
+
+
+def _evidence(stamp: Timestamp):
+    bitcoin = []
+    pending = unsupported = 0
+    for message, attestation in stamp.all_attestations():
+        if isinstance(attestation, BitcoinBlockHeaderAttestation):
+            bitcoin.append((message, attestation))
+        elif isinstance(attestation, PendingAttestation):
+            pending += 1
+        else:
+            unsupported += 1
+    heights = sorted({attestation.height for _, attestation in bitcoin})
+    return bitcoin, heights, pending, unsupported
+
+
+def inspect(data: bytes, expected_sha256: str) -> dict:
+    stamp = _load(data, expected_sha256)
+    _, heights, pending, unsupported = _evidence(stamp)
+    return {
+        "format": "prove.ots-inspection.v1", "sha256": expected_sha256, "bytes": len(data),
+        "bitcoin_heights": heights, "pending_count": pending,
+        "unsupported_attestations": unsupported,
+    }
+
+
+def verify(
+    data: bytes | None, expected_sha256: str, chain_view: ChainView | None,
+    *, minimum_confirmations: int = 6,
+) -> dict:
+    _expected_digest(expected_sha256)
+    if type(minimum_confirmations) is not int or not 1 <= minimum_confirmations <= MAX_SAFE_INTEGER:
+        raise TallyLockError("minimum confirmations must be a positive safe integer")
+    if chain_view is not None and not isinstance(chain_view, ChainView):
+        raise TallyLockError("chain view must be an explicit prepared ChainView")
+    result = {
+        "state": "missing", "height": None, "hash": None, "time": None,
+        "confirmations": None, "required_heights": [],
+        "ignored_invalid_attestations": 0, "unsupported_attestations": 0,
+    }
+    if data is None:
+        return result
+    bitcoin, heights, pending, unsupported = _evidence(_load(data, expected_sha256))
+    result["required_heights"] = heights
+    result["unsupported_attestations"] = unsupported
+    valid = []
+    invalid = 0
+    if chain_view is not None:
+        for message, attestation in bitcoin:
+            block = chain_view.block(attestation.height)
+            if block is None:
+                continue
+            try:
+                attestation.verify_against_blockheader(message, CBlockHeader.deserialize(block.header))
+            except VerificationError:
+                invalid += 1
+            else:
+                valid.append(block)
+    if valid:
+        qualifying = [block for block in valid if block.confirmations >= minimum_confirmations]
+        selected = min(qualifying or valid, key=lambda block: block.height)
+        result.update(
+            state="anchored" if qualifying else "insufficient_confirmations",
+            height=selected.height, hash=selected.hash, time=selected.time,
+            confirmations=selected.confirmations, ignored_invalid_attestations=invalid,
+        )
+    elif invalid:
+        raise TallyLockError("no valid cached Bitcoin witness; a cached header contradicts the proof")
+    elif bitcoin:
+        result["state"] = "insufficient_chain"
+    elif pending:
+        result["state"] = "pending"
+    else:
+        raise TallyLockError("proof contains no supported Bitcoin or pending witness", code=4)
+    return result

tallylock/canonical.py

@@ -0,0 +1,122 @@
+"""Strict parsing and RFC 8785 serialization for protocol metadata."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+import rfc8785
+
+from .errors import TallyLockError
+
+
+MAX_JSON_BYTES = 8 * 1024 * 1024
+MAX_DEPTH = 64
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _fail(message: str) -> None:
+    raise TallyLockError(message)
+
+
+def _integer(value: str) -> int:
+    number = int(value)
+    if not -MAX_SAFE_INTEGER <= number <= MAX_SAFE_INTEGER:
+        _fail("JSON integers must be within the safe integer range")
+    return number
+
+
+def _constant(value: str) -> None:
+    _fail(f"JSON constant {value!r} is not permitted")
+
+
+def _object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            _fail(f"duplicate JSON key: {key!r}")
+        result[key] = value
+    return result
+
+
+def _validate(value: Any, depth: int = 0) -> None:
+    if depth > MAX_DEPTH:
+        _fail("JSON nesting exceeds 64 levels")
+    if isinstance(value, float):
+        _fail("JSON floating-point values are not permitted")
+    if isinstance(value, int) and not isinstance(value, bool):
+        if not -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER:
+            _fail("JSON integers must be within the safe integer range")
+        return
+    if value is None or isinstance(value, (bool, str)):
+        if isinstance(value, str):
+            try:
+                value.encode("utf-8")
+            except UnicodeEncodeError as error:
+                raise TallyLockError("JSON strings must not contain surrogate code points") from error
+        return
+    if isinstance(value, list):
+        for item in value:
+            _validate(item, depth + 1)
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                _fail("JSON object keys must be strings")
+            _validate(key, depth + 1)
+            _validate(item, depth + 1)
+        return
+    _fail(f"value of type {type(value).__name__} is not JSON")
+
+
+def loads(data: bytes | str) -> Any:
+    """Parse bounded strict JSON without executing metadata content."""
+    if isinstance(data, bytes):
+        if len(data) > MAX_JSON_BYTES:
+            _fail("JSON input exceeds 8 MiB")
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise TallyLockError("JSON input must be valid UTF-8") from error
+    elif isinstance(data, str):
+        try:
+            encoded = data.encode("utf-8")
+        except UnicodeEncodeError as error:
+            raise TallyLockError("JSON input must not contain surrogate code points") from error
+        if len(encoded) > MAX_JSON_BYTES:
+            _fail("JSON input exceeds 8 MiB")
+        text = data
+    else:
+        _fail("JSON input must be bytes or str")
+    try:
+        value = json.loads(
+            text,
+            parse_float=lambda _: _fail("JSON floating-point values are not permitted"),
+            parse_int=_integer,
+            parse_constant=_constant,
+            object_pairs_hook=_object,
+        )
+    except TallyLockError:
+        raise
+    except (RecursionError, TypeError, ValueError, json.JSONDecodeError) as error:
+        raise TallyLockError("invalid JSON") from error
+    _validate(value)
+    return value
+
+
+def dumps(value: Any) -> bytes:
+    """Serialize a validated JSON value using RFC 8785 canonical JSON."""
+    _validate(value)
+    try:
+        encoded = rfc8785.dumps(value)
+    except (TypeError, ValueError, OverflowError) as error:
+        raise TallyLockError("value cannot be serialized as canonical JSON") from error
+    if len(encoded) > MAX_JSON_BYTES:
+        _fail("canonical JSON exceeds 8 MiB")
+    return encoded
+
+
+def digest(value: Any) -> str:
+    """Return the SHA-256 digest of the canonical JSON bytes for *value*."""
+    return hashlib.sha256(dumps(value)).hexdigest()

tallylock/chain.py

@@ -0,0 +1,71 @@
+"""Explicit verifier-supplied cache, with internal bindings checked offline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Mapping
+
+from bitcoin.core import CBlockHeader, b2lx
+
+from . import canonical
+from .canonical import MAX_SAFE_INTEGER
+from .errors import TallyLockError
+from .schema import validate_chain
+
+
+@dataclass(frozen=True)
+class CachedBlock:
+    height: int
+    hash: str
+    header: bytes
+    confirmations: int
+    time: int
+    merkle_root: bytes
+
+
+@dataclass(frozen=True)
+class ChainView:
+    _blocks: Mapping[int, CachedBlock]
+    _exported_at: str
+    _source: str
+    _tip_height: int
+    _tip_hash: str
+
+    def block(self, height: int) -> CachedBlock | None:
+        """Look up a checked cached header without consulting any external source."""
+        if type(height) is not int or not 0 <= height <= MAX_SAFE_INTEGER:
+            raise TallyLockError("block height must be a nonnegative safe integer")
+        return self._blocks.get(height)
+
+    def summary(self) -> dict:
+        return {
+            "exported_at": self._exported_at,
+            "source": self._source,
+            "tip": {"height": self._tip_height, "hash": self._tip_hash},
+            "trust": "external_explicit",
+            "freshness": "cached_only",
+        }
+
+
+def prepare(value: dict) -> ChainView:
+    """Snapshot a cache; consistency checks do not authenticate its provenance."""
+    # Apply the existing bounded JSON profile before copying untrusted nesting.
+    snapshot = canonical.loads(canonical.dumps(value))
+    validate_chain(snapshot)
+    blocks = {}
+    for height_text, block in snapshot["blocks"].items():
+        height = int(height_text)
+        raw = bytes.fromhex(block["header"])
+        # Schema checks exact length/encoding; upstream supplies parsing and hash.
+        parsed = CBlockHeader.deserialize(raw)
+        if b2lx(parsed.GetHash()) != block["hash"]:
+            raise TallyLockError(f"cached block {height} hash differs from its header")
+        blocks[height] = CachedBlock(
+            height, block["hash"], raw, block["confirmations"],
+            parsed.nTime, parsed.hashMerkleRoot,
+        )
+    return ChainView(
+        MappingProxyType(blocks), snapshot["exported_at"], snapshot["source"],
+        snapshot["tip"]["height"], snapshot["tip"]["hash"],
+    )