sci-protocol 0.2.0__py3-none-any.whl

pysci/draft.py

@@ -0,0 +1,374 @@
+"""Unsigned drafts: checks before signing (§2-§4, §2.1) and signing (§3, §5.1).
+
+A draft is a set of files at their bundle paths (``sci.json``, ``README.md``,
+optional ``LICENSE``, ``files/...``) without ``manifest.json`` and
+``manifest.json.sig``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from . import ed25519
+from .baseline import BaselineReport, evaluate_baseline
+from .bundle import VerificationResult, verify_loose
+from .errors import Incomplete, Issue, IssueCollector, Outcome, SciError
+from .keys import PublicKey, looks_like_private_key, public_key_of
+from .manifest import (
+    LICENSE_PATH,
+    MANIFEST_PATH,
+    METADATA_PATH,
+    README_PATH,
+    SIGNATURE_PATH,
+    TIMESTAMP_SIDECAR_PATH,
+    FileEntry,
+    build_manifest,
+    serialize_manifest,
+)
+from .metadata import Metadata, parse_metadata
+from .paths import check_paths
+from .png import PngStructure, display_problem, is_display_candidate, png_decode_problem
+from .source import ByteSource, PathSource, as_source, iter_chunks
+from .text import TextFileValidator
+from .zipformat import canonical_zip_size
+
+__all__ = [
+    "GENERATED_PATHS",
+    "BaselineRefused",
+    "DraftReport",
+    "SignedPublication",
+    "check_draft",
+    "load_draft",
+    "sign_draft",
+]
+
+GENERATED_PATHS: Final = frozenset({MANIFEST_PATH, SIGNATURE_PATH, TIMESTAMP_SIDECAR_PATH})
+"""Files produced by signing/timestamping; never part of the draft content."""
+
+_PLACEHOLDER_KEY: Final = PublicKey(bytes(32))
+_PLACEHOLDER_HASH: Final = "0" * 64
+_METADATA_READ_LIMIT: Final = 16 * 1024**2
+_KEY_SCAN_OVERLAP: Final = 64
+
+
+@dataclass(frozen=True, slots=True)
+class DraftReport:
+    """Result of :func:`check_draft`.
+
+    ``valid`` means a signature over these files would yield a protocol-valid
+    publication. Baseline eligibility is reported separately in ``baseline``.
+    ``signed`` is True if generated files (manifest, signature) were present
+    and ignored.
+    """
+
+    issues: tuple[Issue, ...]
+    files: Mapping[str, int]
+    metadata: Metadata | None
+    manifest_bytes: int | None
+    zip_bytes: int | None
+    baseline: BaselineReport | None
+    signed: bool = False
+    display_warnings: tuple[Issue, ...] = ()
+    """Display images that pass the baseline checks but do not decode (§6.2)."""
+
+    @property
+    def valid(self) -> bool:
+        return not self.issues
+
+    @property
+    def outcome(self) -> Outcome:
+        return IssueCollector(list(self.issues)).outcome
+
+
+@dataclass(frozen=True, slots=True)
+class SignedPublication:
+    """A signed bundle: exact manifest bytes, raw signature, and its verification."""
+
+    manifest_bytes: bytes
+    signature: bytes
+    publication_id: str
+    verification: VerificationResult
+
+
+class BaselineRefused(Exception):
+    """Signing stopped because the draft does not meet the baseline (§2.1)."""
+
+    def __init__(self, report: BaselineReport) -> None:
+        self.report = report
+        super().__init__("; ".join(str(reason) for reason in report.reasons))
+
+
+def load_draft(
+    directory: str | os.PathLike[str], ignore: Collection[str] = ()
+) -> tuple[dict[str, ByteSource], list[Issue], bool]:
+    """Collect draft files from ``directory``.
+
+    Returns ``(sources, issues, signed)``: sources keyed by relative POSIX
+    path; issues for symbolic links and special files; whether generated
+    files (manifest, signature, sidecar) were present (they are excluded).
+    Paths in ``ignore`` (relative POSIX paths) are skipped.
+    """
+    root = Path(directory)
+    sources: dict[str, ByteSource] = {}
+    issues: list[Issue] = []
+    signed = False
+    stack = [root]
+    while stack:
+        current = stack.pop()
+        with os.scandir(current) as iterator:
+            for item in sorted(iterator, key=lambda e: e.name):
+                relative = Path(item.path).relative_to(root).as_posix()
+                if relative in ignore:
+                    continue
+                info = item.stat(follow_symlinks=False)
+                if stat.S_ISLNK(info.st_mode) or not (
+                    stat.S_ISDIR(info.st_mode) or stat.S_ISREG(info.st_mode)
+                ):
+                    issues.append(
+                        Issue(
+                            "not_regular_file",
+                            "drafts may contain only regular "
+                            "files and directories (no symbolic links or special "
+                            "files)",
+                            section="2",
+                            file=relative,
+                        )
+                    )
+                elif stat.S_ISDIR(info.st_mode):
+                    stack.append(Path(item.path))
+                elif relative in GENERATED_PATHS:
+                    signed = True
+                else:
+                    sources[relative] = PathSource(item.path, info.st_size)
+    return sources, issues, signed
+
+
+def _contains_private_key(source: ByteSource) -> bool:
+    tail = b""
+    for chunk in iter_chunks(source):
+        if looks_like_private_key(tail + chunk):
+            return True
+        tail = chunk[-_KEY_SCAN_OVERLAP:]
+    return False
+
+
+def check_draft(
+    draft: str | os.PathLike[str] | Mapping[str, ByteSource | bytes],
+    *,
+    ignore: Collection[str] = (),
+) -> DraftReport:
+    """Check an unsigned draft without signing it (CLI ``sci check``).
+
+    Reports all independent problems together: paths and conflicts (§3.1),
+    required files (§3), ``sci.json`` (§4), README/LICENSE text (§2, §4.2),
+    private-key material (§2), and the planned manifest and ZIP sizes with
+    baseline eligibility (§2.1). Reads no private key and writes nothing.
+    """
+    if isinstance(draft, Mapping):
+        sources = {path: as_source(value) for path, value in draft.items()}
+        signed = any(path in GENERATED_PATHS for path in sources)
+        sources = {p: s for p, s in sources.items() if p not in GENERATED_PATHS}
+        load_issues: list[Issue] = []
+    else:
+        sources, load_issues, signed = load_draft(draft, ignore)
+    collector = IssueCollector(list(load_issues))
+    try:
+        return _check(sources, collector, signed)
+    except OSError as exc:
+        collector.add(
+            "input_unavailable",
+            "draft files could not be read",
+            section="6",
+            observed=str(exc),
+            outcome=Outcome.INCOMPLETE,
+        )
+        return DraftReport(tuple(collector.issues), {}, None, None, None, None, signed)
+
+
+def _check(sources: dict[str, ByteSource], collector: IssueCollector, signed: bool) -> DraftReport:
+    paths = list(sources)
+    for required in (METADATA_PATH, README_PATH):
+        if required not in sources:
+            collector.add(
+                "draft_required_file",
+                f"a draft must contain {required}",
+                section="2",
+                file=required,
+            )
+    for path in paths:
+        if path not in (METADATA_PATH, README_PATH, LICENSE_PATH) and not path.startswith("files/"):
+            collector.add(
+                "manifest_path_location",
+                "files other than sci.json, README.md, and LICENSE must be under files/",
+                section="3",
+                file=path,
+            )
+    check_paths(paths, collector=collector)
+    for path, source in sources.items():
+        if _contains_private_key(source):
+            collector.add(
+                "private_key_material",
+                "publishing tools must not include private key material in a bundle",
+                section="2",
+                file=path,
+            )
+    metadata = None
+    if METADATA_PATH in sources:
+        source = sources[METADATA_PATH]
+        if source.size > _METADATA_READ_LIMIT:
+            collector.add(
+                "local_size_limit",
+                "sci.json exceeds the local size limit",
+                section="6",
+                file=METADATA_PATH,
+                observed=source.size,
+                outcome=Outcome.INCOMPLETE,
+            )
+        else:
+            try:
+                metadata = parse_metadata(source.read_at(0, source.size), paths)
+            except SciError as exc:
+                collector.extend(exc.issues)
+    for path, nonblank in ((README_PATH, True), (LICENSE_PATH, False)):
+        if path in sources:
+            validator = TextFileValidator(file=path, nonblank=nonblank)
+            for chunk in iter_chunks(sources[path]):
+                if not validator.feed(chunk):
+                    break
+            collector.extend(validator.finish())
+    sizes = {path: source.size for path, source in sources.items()}
+    display_problems, display_warnings = _check_display(metadata, sources)
+    manifest_size = zip_size = None
+    baseline = None
+    planned = serialize_manifest(
+        _PLACEHOLDER_KEY, {p: FileEntry(_PLACEHOLDER_HASH, n) for p, n in sizes.items()}
+    )
+    if planned:
+        manifest_size = len(planned)
+        zip_size = canonical_zip_size(
+            [(MANIFEST_PATH, manifest_size), (SIGNATURE_PATH, 64), *sizes.items()]
+        )
+        license_hash = None
+        if LICENSE_PATH in sources:
+            digest = hashlib.sha256()
+            for chunk in iter_chunks(sources[LICENSE_PATH]):
+                digest.update(chunk)
+            license_hash = digest.hexdigest()
+        baseline = evaluate_baseline(
+            zip_bytes=zip_size,
+            file_count=len(sizes),
+            display_items=len(metadata.display) if metadata else 0,
+            manifest_bytes=manifest_size,
+            metadata_bytes=sizes.get(METADATA_PATH, 0),
+            readme_bytes=sizes.get(README_PATH, 0),
+            license_sha256=license_hash,
+            display_problems=display_problems,
+        )
+    return DraftReport(
+        tuple(collector.issues),
+        sizes,
+        metadata,
+        manifest_size,
+        zip_size,
+        baseline,
+        signed,
+        display_warnings,
+    )
+
+
+def _check_display(
+    metadata: Metadata | None, sources: Mapping[str, ByteSource]
+) -> tuple[dict[str, str], tuple[Issue, ...]]:
+    """Baseline problems (§2.1) and decode warnings (§6.2) for the display files."""
+    problems: dict[str, str] = {}
+    warnings: list[Issue] = []
+    for item in metadata.display if metadata else ():
+        source = sources[item.path]
+        structure = None
+        if is_display_candidate(item.path, source.size):
+            structure = PngStructure()
+            for chunk in iter_chunks(source):
+                structure.feed(chunk)
+        problem = display_problem(item.path, source.size, structure)
+        if problem is not None:
+            problems[item.path] = problem
+            continue
+        reason = png_decode_problem(source.read_at(0, source.size))
+        if reason is not None:
+            warnings.append(
+                Issue(
+                    "display_undecodable",
+                    "publishing tools should check that display images decode",
+                    section="6.2",
+                    file=item.path,
+                    observed=reason,
+                )
+            )
+    return problems, tuple(warnings)
+
+
+def sign_draft(
+    draft: str | os.PathLike[str] | Mapping[str, ByteSource | bytes],
+    private_key: Ed25519PrivateKey,
+    *,
+    allow_nonbaseline: bool = False,
+    ignore: Collection[str] = (),
+) -> SignedPublication:
+    """Check, build the manifest, sign (§5.1), and verify the result (§6.4).
+
+    Nothing is written; the caller stores ``manifest_bytes`` and
+    ``signature`` (and optionally a ZIP via :func:`pysci.bundle.write_bundle_zip`).
+
+    Raises:
+        Invalid: the draft is not protocol-valid (all issues attached).
+        BaselineRefused: baseline unmet and ``allow_nonbaseline`` is False.
+        Incomplete: files could not be read or changed during signing.
+    """
+    if isinstance(draft, Mapping):
+        sources = {p: as_source(v) for p, v in draft.items() if p not in GENERATED_PATHS}
+    else:
+        sources, _, _ = load_draft(draft, ignore)
+    report = (
+        check_draft(sources) if isinstance(draft, Mapping) else check_draft(draft, ignore=ignore)
+    )
+    if report.issues:
+        IssueCollector(list(report.issues)).raise_if_any()
+    assert report.baseline is not None
+    if not report.baseline.eligible and not allow_nonbaseline:
+        raise BaselineRefused(report.baseline)
+    entries: dict[str, FileEntry] = {}
+    for path, source in sources.items():
+        digest = hashlib.sha256()
+        for chunk in iter_chunks(source):
+            digest.update(chunk)
+        entries[path] = FileEntry(digest.hexdigest(), source.size)
+    manifest_bytes = build_manifest(public_key_of(private_key), entries)
+    signature = ed25519.sign(private_key, manifest_bytes)
+    files: dict[str, ByteSource | bytes] = {
+        MANIFEST_PATH: manifest_bytes,
+        SIGNATURE_PATH: signature,
+        **sources,
+    }
+    result = verify_loose(files)
+    if not result.ok:
+        if any(i.code in ("file_hash_mismatch", "file_size_mismatch") for i in result.issues):
+            raise Incomplete(
+                Issue(
+                    "draft_changed",
+                    "draft files changed during signing",
+                    section="6",
+                    outcome=Outcome.INCOMPLETE,
+                )
+            )
+        IssueCollector(list(result.issues)).raise_if_any()
+    return SignedPublication(
+        manifest_bytes, signature, "sha256:" + hashlib.sha256(manifest_bytes).hexdigest(), result
+    )

pysci/ed25519.py

@@ -0,0 +1,153 @@
+"""Ed25519 signatures with the protocol's additional point checks (§5.1).
+
+Verification follows RFC 8032 §5.1.7 and additionally requires that the public
+key ``A`` and the signature point ``R`` are canonical encodings of nonidentity
+points in the prime-order subgroup. With both points in that subgroup the
+cofactored and cofactorless equations agree, so the final equation is checked
+by ``cryptography`` (OpenSSL), which also rejects ``S >= L``; the scalar range
+is checked here as well so that the failure is reported precisely.
+
+Signing uses ``cryptography``, which implements the deterministic procedure
+of RFC 8032 §5.1.6.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Final
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from .errors import Invalid, Issue
+
+__all__ = [
+    "GROUP_ORDER",
+    "SIGNATURE_LENGTH",
+    "check_public_key_point",
+    "sign",
+    "verify",
+]
+
+_P: Final = 2**255 - 19
+GROUP_ORDER: Final = 2**252 + 27742317777372353535851937790883648493
+"""The prime order L of the Ed25519 base-point subgroup."""
+_D: Final = (-121665 * pow(121666, _P - 2, _P)) % _P
+_SQRT_M1: Final = pow(2, (_P - 1) // 4, _P)
+SIGNATURE_LENGTH: Final = 64
+
+_Point = tuple[int, int, int, int]  # extended twisted Edwards coordinates
+_IDENTITY: Final[_Point] = (0, 1, 1, 0)
+
+
+def _decode_point(encoded: bytes) -> _Point | None:
+    """RFC 8032 §5.1.3 decoding; None for a noncanonical or off-curve encoding."""
+    if len(encoded) != 32:
+        return None
+    value = int.from_bytes(encoded, "little")
+    sign = value >> 255
+    y = value & ((1 << 255) - 1)
+    if y >= _P:
+        return None
+    u = (y * y - 1) % _P
+    v = (_D * y * y + 1) % _P
+    x2 = u * pow(v, _P - 2, _P) % _P
+    x = pow(x2, (_P + 3) // 8, _P)
+    if (x * x - x2) % _P != 0:
+        x = x * _SQRT_M1 % _P
+    if (x * x - x2) % _P != 0:
+        return None
+    if x == 0 and sign == 1:
+        return None
+    if (x & 1) != sign:
+        x = _P - x
+    return (x, y, 1, x * y % _P)
+
+
+def _add(a: _Point, b: _Point) -> _Point:
+    x1, y1, z1, t1 = a
+    x2, y2, z2, t2 = b
+    k_a = (y1 - x1) * (y2 - x2) % _P
+    k_b = (y1 + x1) * (y2 + x2) % _P
+    k_c = 2 * t1 * t2 * _D % _P
+    k_d = 2 * z1 * z2 % _P
+    e, f, g, h = k_b - k_a, k_d - k_c, k_d + k_c, k_b + k_a
+    return (e * f % _P, g * h % _P, f * g % _P, e * h % _P)
+
+
+def _multiply(scalar: int, point: _Point) -> _Point:
+    result = _IDENTITY
+    addend = point
+    while scalar:
+        if scalar & 1:
+            result = _add(result, addend)
+        addend = _add(addend, addend)
+        scalar >>= 1
+    return result
+
+
+def _is_identity(point: _Point) -> bool:
+    x, y, z, _ = point
+    return x % _P == 0 and (y - z) % _P == 0
+
+
+@lru_cache(maxsize=4096)
+def _point_problem(encoded: bytes) -> str | None:
+    """Return why ``encoded`` is not an admissible point, or None."""
+    point = _decode_point(encoded)
+    if point is None:
+        return "noncanonical or invalid point encoding"
+    if _is_identity(point):
+        return "identity point"
+    if not _is_identity(_multiply(GROUP_ORDER, point)):
+        return "point outside the prime-order subgroup"
+    return None
+
+
+def check_public_key_point(public_key: bytes, *, file: str | None = None) -> None:
+    """Require ``A`` to be a canonical nonidentity prime-order point (§5.1)."""
+    problem = _point_problem(bytes(public_key))
+    if problem is not None:
+        raise Invalid(
+            Issue(
+                "public_key_point",
+                "public key A must be a nonidentity member of the prime-order subgroup",
+                section="5.1",
+                file=file,
+                field="/public_key/x",
+                observed=problem,
+            )
+        )
+
+
+def verify(public_key: bytes, signature: bytes, message: bytes, *, file: str | None = None) -> None:
+    """Verify a pure Ed25519 signature under §5.1. Raises :class:`Invalid`."""
+
+    def fail(code: str, requirement: str, observed: str | None = None) -> Invalid:
+        return Invalid(Issue(code, requirement, section="5.1", file=file, observed=observed))
+
+    if len(signature) != SIGNATURE_LENGTH:
+        raise fail(
+            "signature_length",
+            "signature must be exactly the raw 64 Ed25519 signature bytes",
+            f"{len(signature)} bytes",
+        )
+    check_public_key_point(public_key, file=file)
+    problem = _point_problem(bytes(signature[:32]))
+    if problem is not None:
+        raise fail(
+            "signature_r_point",
+            "signature point R must be a nonidentity member of the prime-order subgroup",
+            problem,
+        )
+    if int.from_bytes(signature[32:], "little") >= GROUP_ORDER:
+        raise fail("signature_scalar", "signature scalar S must be less than L (RFC 8032 §5.1.7)")
+    try:
+        Ed25519PublicKey.from_public_bytes(bytes(public_key)).verify(bytes(signature), message)
+    except (InvalidSignature, ValueError):
+        raise fail("signature_mismatch", "Ed25519 signature does not verify") from None
+
+
+def sign(private_key: Ed25519PrivateKey, message: bytes) -> bytes:
+    """Deterministic RFC 8032 §5.1.6 signature (64 raw bytes)."""
+    return private_key.sign(message)