sigil-protocol-verifier 1.0.0__py3-none-any.whl

sigil_protocol_verifier-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+sigil_verify/__init__.py,sha256=ySYChUPwU4bE3EJfIR_RsbRaj23uH35PH37aFNJNIPo,518
+sigil_verify/canonical.py,sha256=2Lkwda7RWX8UsyBOtDBlXlPs7OnrcstkMoopvjb-TtE,1091
+sigil_verify/chain.py,sha256=_vLLVsnXAGXzP8iHP_ol7RzMJPTWXpazhnqO4qTdLS8,1605
+sigil_verify/cli.py,sha256=QW_DULfrs2aZXLiltmrDhHWoV9czUvvG6y0tdh24yHU,582
+sigil_verify/pdf.py,sha256=46VZoyXrmiiYtPBcgsrc3Ai7AufGc2m_JkJIJhzgck4,3690
+sigil_protocol_verifier-1.0.0.dist-info/METADATA,sha256=u35ZBj_VTiHPDDhi9n43nNdHwPUi5trMd470nKLgKfo,1275
+sigil_protocol_verifier-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sigil_protocol_verifier-1.0.0.dist-info/entry_points.txt,sha256=xyC-KBC-6w2lVHH9e1UP4g24BzYATyXoBCOTjqNPkeo,55
+sigil_protocol_verifier-1.0.0.dist-info/top_level.txt,sha256=l85jgQPA0XrQs9aByYYlID4YEn5bEILSR2iV5L2wPoQ,13
+sigil_protocol_verifier-1.0.0.dist-info/RECORD,,

sigil_protocol_verifier-1.0.0.dist-info/WHEEL

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

sigil_protocol_verifier-1.0.0.dist-info/entry_points.txt

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

sigil_protocol_verifier-1.0.0.dist-info/top_level.txt

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

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_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_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_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_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,
+    )