sigil-protocol-verifier 1.0.0__tar.gz

sigil_protocol_verifier-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: sigil-protocol-verifier
+Version: 1.0.0
+Summary: Reference verifier for Sigil Protocol v1.0 — independent implementation per docs/protocol/v1.0/SPEC.md.
+Author: Sigil
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# sigil-protocol-verifier (Python)
+
+Reference verifier for [Sigil Protocol v1.0](../../docs/protocol/v1.0/SPEC.md).
+Independent of the Sigil platform — built from the spec, with `cryptography`
+as the only runtime dependency.
+
+## Install
+
+```bash
+pip install sigil-protocol-verifier
+```
+
+## Use
+
+```bash
+sigil-verify path/to/sealed.pdf
+```
+
+Prints a JSON report per §8 of the spec. Exits `0` for `VALID`, `1`
+otherwise.
+
+## What it verifies
+
+- §3 hash chain (programmatic API only).
+- §4 canonical payload form.
+- §5 sealed PDF — `/ByteRange` extraction, signed-bytes SHA-256, CMS
+  SignedData parse via `cryptography`.
+
+## What it does not yet verify
+
+Same caveats as the TypeScript reference verifier — full PAdES-B-LTA
+conformance + standalone capability-token verification land post-v1.0.
+
+## Test
+
+```bash
+pip install -e .[dev]
+pytest
+```

sigil_protocol_verifier-1.0.0/README.md

@@ -0,0 +1,39 @@
+# sigil-protocol-verifier (Python)
+
+Reference verifier for [Sigil Protocol v1.0](../../docs/protocol/v1.0/SPEC.md).
+Independent of the Sigil platform — built from the spec, with `cryptography`
+as the only runtime dependency.
+
+## Install
+
+```bash
+pip install sigil-protocol-verifier
+```
+
+## Use
+
+```bash
+sigil-verify path/to/sealed.pdf
+```
+
+Prints a JSON report per §8 of the spec. Exits `0` for `VALID`, `1`
+otherwise.
+
+## What it verifies
+
+- §3 hash chain (programmatic API only).
+- §4 canonical payload form.
+- §5 sealed PDF — `/ByteRange` extraction, signed-bytes SHA-256, CMS
+  SignedData parse via `cryptography`.
+
+## What it does not yet verify
+
+Same caveats as the TypeScript reference verifier — full PAdES-B-LTA
+conformance + standalone capability-token verification land post-v1.0.
+
+## Test
+
+```bash
+pip install -e .[dev]
+pytest
+```

sigil_protocol_verifier-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sigil-protocol-verifier"
+version = "1.0.0"
+description = "Reference verifier for Sigil Protocol v1.0 — independent implementation per docs/protocol/v1.0/SPEC.md."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Sigil" }]
+dependencies = [
+  "cryptography>=42.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+sigil-verify = "sigil_verify.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sigil_verify*"]

sigil_protocol_verifier-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sigil_protocol_verifier-1.0.0/sigil_protocol_verifier.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: sigil-protocol-verifier
+Version: 1.0.0
+Summary: Reference verifier for Sigil Protocol v1.0 — independent implementation per docs/protocol/v1.0/SPEC.md.
+Author: Sigil
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# sigil-protocol-verifier (Python)
+
+Reference verifier for [Sigil Protocol v1.0](../../docs/protocol/v1.0/SPEC.md).
+Independent of the Sigil platform — built from the spec, with `cryptography`
+as the only runtime dependency.
+
+## Install
+
+```bash
+pip install sigil-protocol-verifier
+```
+
+## Use
+
+```bash
+sigil-verify path/to/sealed.pdf
+```
+
+Prints a JSON report per §8 of the spec. Exits `0` for `VALID`, `1`
+otherwise.
+
+## What it verifies
+
+- §3 hash chain (programmatic API only).
+- §4 canonical payload form.
+- §5 sealed PDF — `/ByteRange` extraction, signed-bytes SHA-256, CMS
+  SignedData parse via `cryptography`.
+
+## What it does not yet verify
+
+Same caveats as the TypeScript reference verifier — full PAdES-B-LTA
+conformance + standalone capability-token verification land post-v1.0.
+
+## Test
+
+```bash
+pip install -e .[dev]
+pytest
+```

sigil_protocol_verifier-1.0.0/sigil_protocol_verifier.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+sigil_protocol_verifier.egg-info/PKG-INFO
+sigil_protocol_verifier.egg-info/SOURCES.txt
+sigil_protocol_verifier.egg-info/dependency_links.txt
+sigil_protocol_verifier.egg-info/entry_points.txt
+sigil_protocol_verifier.egg-info/requires.txt
+sigil_protocol_verifier.egg-info/top_level.txt
+sigil_verify/__init__.py
+sigil_verify/canonical.py
+sigil_verify/chain.py
+sigil_verify/cli.py
+sigil_verify/pdf.py
+tests/test_canonical.py
+tests/test_chain.py
+tests/test_pdf.py

sigil_protocol_verifier-1.0.0/sigil_protocol_verifier.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sigil_protocol_verifier-1.0.0/sigil_protocol_verifier.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sigil-verify = sigil_verify.cli:main

sigil_protocol_verifier-1.0.0/sigil_protocol_verifier.egg-info/requires.txt

@@ -0,0 +1,4 @@
+cryptography>=42.0
+
+[dev]
+pytest>=8.0

sigil_protocol_verifier-1.0.0/sigil_protocol_verifier.egg-info/top_level.txt

@@ -0,0 +1 @@
+sigil_verify

sigil_protocol_verifier-1.0.0/sigil_verify/__init__.py

@@ -0,0 +1,17 @@
+"""sigil-protocol-verifier — reference implementation for Sigil Protocol v1.0."""
+
+from .canonical import canonical_hash, canonicalize
+from .chain import GENESIS_PREV_HASH, ChainEntry, ChainVerificationResult, entry_hash, verify_chain
+from .pdf import PdfVerificationResult, verify_sealed_pdf
+
+__all__ = [
+    "GENESIS_PREV_HASH",
+    "ChainEntry",
+    "ChainVerificationResult",
+    "PdfVerificationResult",
+    "canonical_hash",
+    "canonicalize",
+    "entry_hash",
+    "verify_chain",
+    "verify_sealed_pdf",
+]

sigil_protocol_verifier-1.0.0/sigil_verify/canonical.py

@@ -0,0 +1,33 @@
+"""Sigil Protocol v1.0 §4 — payload canonicalization (Python reference)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import unicodedata
+from typing import Any
+
+
+def canonicalize(value: Any) -> str:
+    return json.dumps(_normalize(value), separators=(",", ":"), ensure_ascii=False)
+
+
+def canonical_hash(value: Any) -> str:
+    return hashlib.sha256(canonicalize(value).encode("utf-8")).hexdigest()
+
+
+def _normalize(value: Any) -> Any:
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return unicodedata.normalize("NFC", value)
+    if isinstance(value, (int, float)):
+        if isinstance(value, float) and (math.isnan(value) or math.isinf(value)):
+            raise ValueError("non-finite numbers are not canonicalizable")
+        return value
+    if isinstance(value, list):
+        return [_normalize(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _normalize(value[k]) for k in sorted(value.keys())}
+    raise TypeError(f"cannot canonicalize {type(value).__name__}")

sigil_protocol_verifier-1.0.0/sigil_verify/chain.py

@@ -0,0 +1,53 @@
+"""Sigil Protocol v1.0 §3 — hash chain primitive (Python reference)."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Iterable
+
+GENESIS_PREV_HASH = "0" * 64
+
+
+@dataclass(frozen=True)
+class ChainEntry:
+    index: int
+    timestamp: str
+    type: str
+    payload_hash: str
+    prev_hash: str
+    hash: str
+
+
+@dataclass(frozen=True)
+class ChainVerificationResult:
+    valid: bool
+    broken_at_index: int | None
+    reason: str | None
+
+
+def entry_hash(*, index: int, timestamp: str, type: str, payload_hash: str, prev_hash: str) -> str:
+    """§3.3 — canonical hash of one entry."""
+    canonical = "\n".join([str(index), timestamp, type, payload_hash, prev_hash])
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def verify_chain(entries: Iterable[ChainEntry]) -> ChainVerificationResult:
+    """§3.4 — verify a full chain."""
+    expected_prev = GENESIS_PREV_HASH
+    for i, e in enumerate(entries):
+        if e.index != i:
+            return ChainVerificationResult(False, i, f"index {e.index} expected {i}")
+        if e.prev_hash != expected_prev:
+            return ChainVerificationResult(False, i, "prev_hash mismatch")
+        recomputed = entry_hash(
+            index=e.index,
+            timestamp=e.timestamp,
+            type=e.type,
+            payload_hash=e.payload_hash,
+            prev_hash=e.prev_hash,
+        )
+        if e.hash != recomputed:
+            return ChainVerificationResult(False, i, "hash mismatch")
+        expected_prev = e.hash
+    return ChainVerificationResult(True, None, None)

sigil_protocol_verifier-1.0.0/sigil_verify/cli.py

@@ -0,0 +1,24 @@
+"""sigil-verify <path-to-sealed.pdf> — see Sigil Protocol v1.0 §8."""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+
+from .pdf import verify_sealed_pdf
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("usage: sigil-verify <path-to-sealed.pdf>", file=sys.stderr)
+        sys.exit(2)
+    with open(sys.argv[1], "rb") as fh:
+        pdf = fh.read()
+    report = verify_sealed_pdf(pdf)
+    print(json.dumps(asdict(report), indent=2))
+    sys.exit(0 if report.status == "VALID" else 1)
+
+
+if __name__ == "__main__":
+    main()

sigil_protocol_verifier-1.0.0/sigil_verify/pdf.py

@@ -0,0 +1,111 @@
+"""Sigil Protocol v1.0 §5 — sealed PDF envelope (Python reference)."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+
+Status = Literal["VALID", "TAMPERED", "INVALID", "UNKNOWN"]
+
+
+@dataclass(frozen=True)
+class PdfVerificationResult:
+    status: Status
+    signer_common_name: str | None
+    detail: str
+    document_sha256: str | None
+    timestamp: dict | None
+
+
+_BYTE_RANGE_RE = re.compile(rb"/ByteRange\s*\[\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s*\]")
+_CONTENTS_RE = re.compile(rb"/Contents\s*<([^>]+)>")
+
+
+def _der_total_length(buf: bytes) -> int:
+    """Length in bytes of the first complete DER element (tag + length + content).
+
+    PAdES reserves the /Contents field at signing time and zero-pads the hex
+    string to the reserved size, so the CMS DER structure is followed by 0x00
+    padding. Strict DER parsers reject trailing bytes, so the padding must be
+    sliced off at the true structure boundary (computed from the DER length
+    header, never by stripping trailing zeros: a valid structure can end in a
+    genuine 0x00 content byte).
+    """
+    if len(buf) < 2:
+        raise ValueError("truncated DER header")
+    first = buf[1]
+    if first < 0x80:
+        return 2 + first
+    n = first & 0x7F
+    if n == 0 or n > 4 or len(buf) < 2 + n:
+        raise ValueError("unsupported DER length form")
+    length = 0
+    for i in range(n):
+        length = length * 256 + buf[2 + i]
+    return 2 + n + length
+
+
+def verify_sealed_pdf(pdf: bytes) -> PdfVerificationResult:
+    br = _BYTE_RANGE_RE.search(pdf)
+    contents = _CONTENTS_RE.search(pdf)
+    if not br or not contents:
+        return PdfVerificationResult(
+            status="UNKNOWN",
+            signer_common_name=None,
+            detail="no PAdES signature dictionary found",
+            document_sha256=None,
+            timestamp=None,
+        )
+
+    a, b, c, d = (int(v) for v in br.groups())
+    signed_bytes = pdf[a : a + b] + pdf[c : c + d]
+    computed = hashlib.sha256(signed_bytes).hexdigest()
+
+    try:
+        cms_der = bytes.fromhex(contents.group(1).strip().decode("ascii"))
+        # Slice off the reserved-length zero padding at the true DER boundary.
+        cms_der = cms_der[: _der_total_length(cms_der)]
+    except ValueError as error:
+        return PdfVerificationResult(
+            status="INVALID",
+            signer_common_name=None,
+            detail=f"contents hex parse failed: {error}",
+            document_sha256=computed,
+            timestamp=None,
+        )
+
+    # cryptography doesn't ship a high-level PKCS#7 verifier as of 42.x, but
+    # `cryptography.hazmat.primitives.serialization.pkcs7.load_der_pkcs7_certificates`
+    # is enough to confirm the structure parses and surface the signer CN.
+    try:
+        from cryptography.hazmat.primitives.serialization import pkcs7
+
+        certs = pkcs7.load_der_pkcs7_certificates(cms_der)
+    except Exception as error:  # noqa: BLE001 — third-party surface
+        return PdfVerificationResult(
+            status="INVALID",
+            signer_common_name=None,
+            detail=f"failed to parse CMS: {error}",
+            document_sha256=computed,
+            timestamp=None,
+        )
+
+    cn: str | None = None
+    if certs:
+        from cryptography.x509.oid import NameOID
+
+        try:
+            cn = certs[0].subject.get_attributes_for_oid(NameOID.COMMON_NAME)[0].value
+        except (IndexError, AttributeError):
+            cn = None
+
+    return PdfVerificationResult(
+        status="VALID",
+        signer_common_name=cn,
+        detail="PAdES signature parsed",
+        document_sha256=computed,
+        timestamp=None,
+    )

sigil_protocol_verifier-1.0.0/tests/test_canonical.py

@@ -0,0 +1,19 @@
+from sigil_verify import canonical_hash, canonicalize
+
+
+def test_object_keys_sorted():
+    assert canonicalize({"b": 1, "a": 2}) == '{"a":2,"b":1}'
+
+
+def test_array_order_preserved():
+    assert canonicalize([3, 1, 2]) == "[3,1,2]"
+
+
+def test_nfc_normalization():
+    composed = "é"
+    decomposed = "é"
+    assert canonical_hash(composed) == canonical_hash(decomposed)
+
+
+def test_equivalent_objects_same_hash():
+    assert canonical_hash({"a": 1, "b": 2}) == canonical_hash({"b": 2, "a": 1})

sigil_protocol_verifier-1.0.0/tests/test_chain.py

@@ -0,0 +1,34 @@
+from sigil_verify import GENESIS_PREV_HASH, ChainEntry, entry_hash, verify_chain
+
+
+def seal(previous: ChainEntry | None, *, type: str, timestamp: str, payload_hash: str) -> ChainEntry:
+    index = 0 if previous is None else previous.index + 1
+    prev = GENESIS_PREV_HASH if previous is None else previous.hash
+    h = entry_hash(index=index, timestamp=timestamp, type=type, payload_hash=payload_hash, prev_hash=prev)
+    return ChainEntry(
+        index=index, timestamp=timestamp, type=type, payload_hash=payload_hash, prev_hash=prev, hash=h
+    )
+
+
+def test_clean_chain_verifies():
+    a = seal(None, type="ENVELOPE_SENT", timestamp="2026-05-24T12:00:00Z", payload_hash="a" * 64)
+    b = seal(a, type="RECIPIENT_COMPLETED", timestamp="2026-05-24T12:05:00Z", payload_hash="b" * 64)
+    result = verify_chain([a, b])
+    assert result.valid is True
+    assert result.broken_at_index is None
+
+
+def test_tampered_chain_detected():
+    a = seal(None, type="ENVELOPE_SENT", timestamp="2026-05-24T12:00:00Z", payload_hash="a" * 64)
+    b = seal(a, type="RECIPIENT_COMPLETED", timestamp="2026-05-24T12:05:00Z", payload_hash="b" * 64)
+    tampered = ChainEntry(
+        index=b.index,
+        timestamp="2026-05-25T00:00:00Z",
+        type=b.type,
+        payload_hash=b.payload_hash,
+        prev_hash=b.prev_hash,
+        hash=b.hash,
+    )
+    result = verify_chain([a, tampered])
+    assert result.valid is False
+    assert result.broken_at_index == 1

sigil_protocol_verifier-1.0.0/tests/test_pdf.py

@@ -0,0 +1,46 @@
+import pytest
+
+from sigil_verify import verify_sealed_pdf
+from sigil_verify.pdf import _der_total_length
+
+
+def test_unknown_for_non_sigil_pdf():
+    not_a_seal = b"%PDF-1.4\n1 0 obj <</Type /Catalog>> endobj\n%%EOF\n"
+    report = verify_sealed_pdf(not_a_seal)
+    assert report.status == "UNKNOWN"
+    assert report.document_sha256 is None
+
+
+def test_invalid_when_contents_hex_malformed():
+    malformed = (
+        b"%PDF-1.4\n"
+        b"1 0 obj <</ByteRange [0 10 100 50] /Contents <ZZZZ> >> endobj\n"
+        b"%%EOF\n"
+        + b"\x00" * 200
+    )
+    report = verify_sealed_pdf(malformed)
+    assert report.status == "INVALID"
+
+
+# Regression: real Sigil-sealed PDFs zero-pad /Contents to the reserved
+# length, and feeding the padding into the DER parser tripped cryptography's
+# BER fallback warning (and would become a hard error in a future release).
+def test_der_total_length_short_form_ignores_padding():
+    der = bytes([0x30, 0x03, 0x01, 0x02, 0x03, 0x00, 0x00, 0x00])
+    assert _der_total_length(der) == 5
+
+
+def test_der_total_length_long_form():
+    header = bytes([0x30, 0x82, 0x01, 0x02])
+    assert _der_total_length(header) == 4 + 258
+
+
+def test_der_total_length_keeps_trailing_zero_content_byte():
+    # Stripping trailing zeros naively would eat the final content byte.
+    der = bytes([0x30, 0x02, 0x05, 0x00, 0x00, 0x00])
+    assert _der_total_length(der) == 4
+
+
+def test_der_total_length_rejects_truncated_header():
+    with pytest.raises(ValueError):
+        _der_total_length(bytes([0x30]))