pyencode-protector 0.3.0__py3-none-any.whl

pyencode/inventory.py

@@ -0,0 +1,356 @@
+"""Safe, deterministic inventories for files shipped with protected output.
+
+The builder can sign the mappings produced here.  Generated runtimes mirror
+the same deliberately small set of rules rather than importing this module.
+Inventory paths are always canonical POSIX relative paths, independent of the
+host operating system.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Iterable, Iterator
+
+from .errors import PyEncodeError
+
+
+CODE_BEARING_SUFFIXES = frozenset(
+    {".py", ".pyc", ".pyo", ".pyd", ".so", ".dll", ".dylib"}
+)
+_HASH_CHUNK_SIZE = 1024 * 1024
+_WINDOWS_FORBIDDEN_CHARACTERS = frozenset('<>:"|?*')
+_WINDOWS_RESERVED_BASENAMES = frozenset(
+    {
+        "aux",
+        "con",
+        "conin$",
+        "conout$",
+        "nul",
+        "prn",
+        *(f"com{index}" for index in range(1, 10)),
+        *(f"lpt{index}" for index in range(1, 10)),
+    }
+)
+
+
+def _is_portable_component(component: str) -> bool:
+    if component.endswith((".", " ")):
+        return False
+    if any(
+        ord(character) < 32 or character in _WINDOWS_FORBIDDEN_CHARACTERS
+        for character in component
+    ):
+        return False
+    basename = component.partition(".")[0].casefold()
+    return basename not in _WINDOWS_RESERVED_BASENAMES
+
+
+def validate_inventory_path(value: str) -> str:
+    """Return *value* if it is a canonical, portable relative POSIX path.
+
+    Backslashes and Windows drive/alternate-stream syntax are rejected so a
+    manifest has one interpretation on both Windows and POSIX systems.
+    """
+
+    if not isinstance(value, str) or not value or "\x00" in value or "\\" in value:
+        raise PyEncodeError(
+            "inventory paths must be non-empty POSIX relative paths"
+        )
+    path = PurePosixPath(value)
+    windows_path = PureWindowsPath(value)
+    if (
+        path.is_absolute()
+        or windows_path.is_absolute()
+        or bool(windows_path.drive)
+        or any(
+            part in ("", ".", "..") or not _is_portable_component(part)
+            for part in path.parts
+        )
+    ):
+        raise PyEncodeError(f"unsafe inventory path: {value!r}")
+    canonical = path.as_posix()
+    if canonical != value:
+        raise PyEncodeError(f"inventory path is not canonical: {value!r}")
+    return canonical
+
+
+def _path_prefixes(path: str) -> Iterator[str]:
+    parts = PurePosixPath(path).parts
+    for end in range(1, len(parts) + 1):
+        yield "/".join(parts[:end])
+
+
+def normalize_inventory_paths(paths: Iterable[str]) -> tuple[str, ...]:
+    """Validate, de-duplicate and sort inventory paths.
+
+    Case-fold collisions are rejected for every path prefix.  Checking
+    prefixes catches trees such as ``Pkg/a.py`` and ``pkg/b.py`` which cannot
+    be represented consistently after copying to a case-insensitive system.
+    """
+
+    normalized: list[str] = []
+    exact_paths: set[str] = set()
+    folded_prefixes: dict[str, str] = {}
+    for raw_path in paths:
+        path = validate_inventory_path(raw_path)
+        if path in exact_paths:
+            raise PyEncodeError(f"duplicate inventory path: {path!r}")
+        exact_paths.add(path)
+        for prefix in _path_prefixes(path):
+            folded = prefix.casefold()
+            previous = folded_prefixes.get(folded)
+            if previous is not None and previous != prefix:
+                raise PyEncodeError(
+                    "case-folding inventory path collision: "
+                    f"{previous!r} and {prefix!r}"
+                )
+            folded_prefixes[folded] = prefix
+        normalized.append(path)
+    return tuple(sorted(normalized))
+
+
+def is_code_bearing_path(path: str) -> bool:
+    """Return whether *path* names Python or native executable code."""
+
+    canonical = validate_inventory_path(path)
+    name = PurePosixPath(canonical).name.casefold()
+    if any(name.endswith(suffix) for suffix in CODE_BEARING_SUFFIXES):
+        return True
+    # Versioned ELF shared objects conventionally end in e.g. ``.so.1``.
+    return ".so." in name
+
+
+def _is_link_or_reparse(metadata: os.stat_result) -> bool:
+    if stat.S_ISLNK(metadata.st_mode):
+        return True
+    reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    return bool(reparse_flag and attributes & reparse_flag)
+
+
+def _inventory_root(root: Path) -> Path:
+    source = Path(root).expanduser()
+    try:
+        resolved = source.resolve(strict=True)
+    except OSError as exc:
+        raise PyEncodeError(f"inventory root is missing or unreadable: {source}") from exc
+    if not resolved.is_dir():
+        raise PyEncodeError(f"inventory root is not a directory: {resolved}")
+    return resolved
+
+
+def _exact_child(directory: Path, name: str, relative: str) -> os.DirEntry[str]:
+    try:
+        with os.scandir(directory) as entries:
+            exact: os.DirEntry[str] | None = None
+            folded_match: str | None = None
+            for entry in entries:
+                if entry.name == name:
+                    exact = entry
+                    break
+                if entry.name.casefold() == name.casefold():
+                    folded_match = entry.name
+    except OSError as exc:
+        raise PyEncodeError(
+            f"cannot inspect parent directory for inventory file {relative!r}"
+        ) from exc
+    if exact is not None:
+        return exact
+    if folded_match is not None:
+        raise PyEncodeError(
+            "inventory path casing does not match the filesystem: "
+            f"{relative!r} refers to {folded_match!r}"
+        )
+    raise PyEncodeError(f"inventory file is missing: {relative}")
+
+
+def _exact_regular_file(root: Path, relative: str) -> tuple[Path, os.stat_result]:
+    current = root
+    parts = PurePosixPath(relative).parts
+    for index, part in enumerate(parts):
+        entry = _exact_child(current, part, relative)
+        try:
+            metadata = entry.stat(follow_symlinks=False)
+        except OSError as exc:
+            raise PyEncodeError(f"cannot stat inventory file: {relative}") from exc
+        if _is_link_or_reparse(metadata):
+            raise PyEncodeError(
+                f"inventory path contains a symlink or reparse point: {relative!r}"
+            )
+        is_last = index == len(parts) - 1
+        if is_last:
+            if not stat.S_ISREG(metadata.st_mode):
+                raise PyEncodeError(
+                    f"inventory path is not a regular file: {relative!r}"
+                )
+        elif not stat.S_ISDIR(metadata.st_mode):
+            raise PyEncodeError(
+                f"inventory path parent is not a directory: {relative!r}"
+            )
+        current = Path(entry.path)
+
+    try:
+        resolved = current.resolve(strict=True)
+        resolved.relative_to(root)
+    except (OSError, ValueError) as exc:
+        raise PyEncodeError(f"inventory file escapes its root: {relative!r}") from exc
+    try:
+        final_metadata = os.stat(resolved, follow_symlinks=False)
+    except OSError as exc:
+        raise PyEncodeError(f"cannot stat inventory file: {relative}") from exc
+    if _is_link_or_reparse(final_metadata) or not stat.S_ISREG(final_metadata.st_mode):
+        raise PyEncodeError(f"inventory path is not a regular file: {relative!r}")
+    return resolved, final_metadata
+
+
+def _hash_regular_file(path: Path, expected: os.stat_result) -> str:
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as exc:
+        raise PyEncodeError(f"cannot open inventory file: {path}") from exc
+    digest = hashlib.sha256()
+    try:
+        opened = os.fstat(descriptor)
+        if not stat.S_ISREG(opened.st_mode):
+            raise PyEncodeError(f"inventory path is not a regular file: {path}")
+        expected_identity = (expected.st_dev, expected.st_ino)
+        opened_identity = (opened.st_dev, opened.st_ino)
+        if expected_identity != opened_identity:
+            raise PyEncodeError(f"inventory file changed while opening: {path}")
+        while True:
+            chunk = os.read(descriptor, _HASH_CHUNK_SIZE)
+            if not chunk:
+                break
+            digest.update(chunk)
+    finally:
+        os.close(descriptor)
+    return digest.hexdigest()
+
+
+def hash_inventory_files(root: Path, relative_paths: Iterable[str]) -> dict[str, str]:
+    """Hash exact regular non-symlink files below *root* with SHA-256."""
+
+    resolved_root = _inventory_root(root)
+    paths = normalize_inventory_paths(relative_paths)
+    result: dict[str, str] = {}
+    for relative in paths:
+        candidate, metadata = _exact_regular_file(resolved_root, relative)
+        result[relative] = _hash_regular_file(candidate, metadata)
+    return result
+
+
+def _walk_inventory(directory: Path, root: Path, prefixes: tuple[str, ...]) -> Iterator[str]:
+    try:
+        with os.scandir(directory) as iterator:
+            entries = sorted(iterator, key=lambda item: item.name)
+    except OSError as exc:
+        relative = "/".join(prefixes) or "."
+        raise PyEncodeError(f"cannot scan inventory directory: {relative}") from exc
+
+    folded_names: dict[str, str] = {}
+    for entry in entries:
+        folded = entry.name.casefold()
+        previous = folded_names.get(folded)
+        if previous is not None and previous != entry.name:
+            relative = "/".join(prefixes)
+            raise PyEncodeError(
+                "case-folding filesystem collision in inventory directory "
+                f"{relative or '.'!r}: {previous!r} and {entry.name!r}"
+            )
+        folded_names[folded] = entry.name
+
+    for entry in entries:
+        relative = "/".join((*prefixes, entry.name))
+        validate_inventory_path(relative)
+        try:
+            metadata = entry.stat(follow_symlinks=False)
+        except OSError as exc:
+            raise PyEncodeError(f"cannot stat inventory entry: {relative!r}") from exc
+        if _is_link_or_reparse(metadata):
+            raise PyEncodeError(
+                f"inventory contains a symlink or reparse point: {relative!r}"
+            )
+        if stat.S_ISDIR(metadata.st_mode):
+            yield from _walk_inventory(Path(entry.path), root, (*prefixes, entry.name))
+        elif stat.S_ISREG(metadata.st_mode):
+            try:
+                Path(entry.path).resolve(strict=True).relative_to(root)
+            except (OSError, ValueError) as exc:
+                raise PyEncodeError(f"inventory file escapes its root: {relative!r}") from exc
+            yield relative
+        else:
+            raise PyEncodeError(
+                f"inventory contains a non-regular filesystem entry: {relative!r}"
+            )
+
+
+def discover_inventory_files(root: Path) -> tuple[str, ...]:
+    """Return every regular file below *root*, rejecting ambiguous trees."""
+
+    resolved_root = _inventory_root(root)
+    return normalize_inventory_paths(_walk_inventory(resolved_root, resolved_root, ()))
+
+
+def find_unexpected_code_files(
+    root: Path, allowed_paths: Iterable[str]
+) -> tuple[str, ...]:
+    """Return code-bearing files present below *root* but absent from allowlist."""
+
+    allowed = normalize_inventory_paths(allowed_paths)
+    invalid = [path for path in allowed if not is_code_bearing_path(path)]
+    if invalid:
+        raise PyEncodeError(
+            "code-bearing allowlist contains non-code paths: " + ", ".join(invalid)
+        )
+    actual = {
+        path for path in discover_inventory_files(root) if is_code_bearing_path(path)
+    }
+    return tuple(sorted(actual.difference(allowed)))
+
+
+def validate_code_inventory(root: Path, allowed_paths: Iterable[str]) -> tuple[str, ...]:
+    """Validate that code-bearing files below *root* exactly match allowlist.
+
+    The normalized allowlist is returned so callers can reuse it in signed
+    metadata after validation.
+    """
+
+    allowed = normalize_inventory_paths(allowed_paths)
+    invalid = [path for path in allowed if not is_code_bearing_path(path)]
+    if invalid:
+        raise PyEncodeError(
+            "code-bearing allowlist contains non-code paths: " + ", ".join(invalid)
+        )
+    actual = {
+        path for path in discover_inventory_files(root) if is_code_bearing_path(path)
+    }
+    expected = set(allowed)
+    missing = sorted(expected.difference(actual))
+    unexpected = sorted(actual.difference(expected))
+    if missing or unexpected:
+        details: list[str] = []
+        if missing:
+            details.append("missing " + ", ".join(missing))
+        if unexpected:
+            details.append("unexpected " + ", ".join(unexpected))
+        raise PyEncodeError(
+            "code-bearing distribution inventory mismatch (" + "; ".join(details) + ")"
+        )
+    return allowed
+
+
+__all__ = [
+    "CODE_BEARING_SUFFIXES",
+    "discover_inventory_files",
+    "find_unexpected_code_files",
+    "hash_inventory_files",
+    "is_code_bearing_path",
+    "normalize_inventory_paths",
+    "validate_code_inventory",
+    "validate_inventory_path",
+]

pyencode/manifest.py

@@ -0,0 +1,196 @@
+"""Canonical JSON and Ed25519 signatures for build manifests."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from typing import Any, Mapping, TypeAlias
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .crypto import (
+    PrivateKeyLike,
+    PublicKeyLike,
+    load_private_key,
+    public_key_bytes,
+    sign_bytes,
+    verify_bytes,
+)
+from .errors import ManifestError, SignatureError
+
+
+JsonObject: TypeAlias = Mapping[str, Any]
+SIGNATURE_FIELD = "signature"
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    """Serialize a JSON value with pyencode's canonical JSON settings."""
+
+    try:
+        return json.dumps(
+            value,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            allow_nan=False,
+        ).encode("utf-8")
+    except (TypeError, ValueError, UnicodeEncodeError) as exc:
+        raise ManifestError("manifest cannot be encoded as canonical JSON") from exc
+
+
+def canonical_manifest_bytes(manifest: JsonObject) -> bytes:
+    """Validate and canonically serialize a manifest object."""
+
+    if not isinstance(manifest, Mapping):
+        raise ManifestError("manifest must be a JSON object")
+    # Materializing a dict avoids surprising behavior from mutable/custom
+    # Mapping implementations while serialization is in progress.
+    return canonical_json_bytes(dict(manifest))
+
+
+def sign_manifest(manifest: JsonObject, private_key: PrivateKeyLike) -> bytes:
+    """Sign the exact canonical UTF-8 JSON representation of ``manifest``."""
+
+    return sign_bytes(canonical_manifest_bytes(manifest), private_key)
+
+
+def verify_manifest(
+    manifest: JsonObject,
+    signature: bytes | bytearray | memoryview,
+    public_key: PublicKeyLike,
+) -> bool:
+    """Verify a canonical manifest, returning ``True`` or raising on failure."""
+
+    try:
+        return verify_bytes(
+            canonical_manifest_bytes(manifest), signature, public_key
+        )
+    except SignatureError:
+        raise
+    except (TypeError, ValueError) as exc:
+        raise SignatureError("manifest signature is malformed") from exc
+
+
+def encode_signature(signature: bytes | bytearray | memoryview) -> str:
+    """Encode a signature as unambiguous standard Base64 text."""
+
+    if not isinstance(signature, (bytes, bytearray, memoryview)):
+        raise TypeError("signature must be bytes-like")
+    return base64.b64encode(bytes(signature)).decode("ascii")
+
+
+def decode_signature(encoded: str) -> bytes:
+    """Decode a strict standard-Base64 signature."""
+
+    if not isinstance(encoded, str):
+        raise SignatureError("manifest signature must be a Base64 string")
+    try:
+        signature = base64.b64decode(encoded.encode("ascii"), validate=True)
+    except (UnicodeEncodeError, binascii.Error, ValueError) as exc:
+        raise SignatureError("manifest signature is not valid Base64") from exc
+    if len(signature) != 64:
+        raise SignatureError("Ed25519 signature must be exactly 64 bytes")
+    return signature
+
+
+def sign_manifest_base64(manifest: JsonObject, private_key: PrivateKeyLike) -> str:
+    """Sign a manifest and return a JSON-friendly Base64 signature."""
+
+    return encode_signature(sign_manifest(manifest, private_key))
+
+
+def verify_manifest_base64(
+    manifest: JsonObject,
+    signature: str,
+    public_key: PublicKeyLike,
+) -> bool:
+    """Verify a manifest with a strict Base64-encoded signature."""
+
+    return verify_manifest(manifest, decode_signature(signature), public_key)
+
+
+def attach_signature(
+    manifest: JsonObject,
+    private_key: PrivateKeyLike,
+    *,
+    field: str = SIGNATURE_FIELD,
+) -> dict[str, Any]:
+    """Return a copy containing a Base64 signature over all other fields."""
+
+    if not isinstance(manifest, Mapping):
+        raise ManifestError("manifest must be a JSON object")
+    if not isinstance(field, str) or not field:
+        raise ManifestError("signature field name must be a non-empty string")
+    unsigned = dict(manifest)
+    unsigned.pop(field, None)
+    signed = dict(unsigned)
+    signed[field] = sign_manifest_base64(unsigned, private_key)
+    return signed
+
+
+def verify_signed_manifest(
+    signed_manifest: JsonObject,
+    public_key: PublicKeyLike,
+) -> dict[str, Any]:
+    """Verify ``{'manifest': payload, 'signature': base64}`` and return payload."""
+
+    if not isinstance(signed_manifest, Mapping):
+        raise ManifestError("signed manifest wrapper must be a JSON object")
+    if set(signed_manifest) != {"manifest", SIGNATURE_FIELD}:
+        raise ManifestError(
+            "signed manifest wrapper must contain only 'manifest' and 'signature'"
+        )
+    try:
+        payload = signed_manifest["manifest"]
+        encoded = signed_manifest[SIGNATURE_FIELD]
+    except KeyError as exc:
+        raise SignatureError("signed manifest wrapper is incomplete") from exc
+    if not isinstance(payload, Mapping):
+        raise ManifestError("wrapped manifest payload must be a JSON object")
+    if not isinstance(encoded, str):
+        raise SignatureError("embedded manifest signature must be a Base64 string")
+    verify_manifest_base64(payload, encoded, public_key)
+    return dict(payload)
+
+
+def create_signed_manifest(
+    payload: JsonObject,
+    private_key: PrivateKeyLike | None = None,
+) -> tuple[dict[str, Any], bytes, Ed25519PrivateKey]:
+    """Create the portable signed-manifest wrapper used by the builder.
+
+    When ``private_key`` is omitted a fresh key is generated.  The returned
+    tuple contains ``(wrapper, raw_public_key, private_key_object)`` so a caller
+    can persist the public runtime key and reuse or export the private key.
+    """
+
+    if not isinstance(payload, Mapping):
+        raise ManifestError("manifest payload must be a JSON object")
+    signing_key = (
+        Ed25519PrivateKey.generate()
+        if private_key is None
+        else load_private_key(private_key)
+    )
+    normalized = dict(payload)
+    wrapper = {
+        "manifest": normalized,
+        SIGNATURE_FIELD: sign_manifest_base64(normalized, signing_key),
+    }
+    return wrapper, public_key_bytes(signing_key.public_key()), signing_key
+
+
+__all__ = [
+    "SIGNATURE_FIELD",
+    "attach_signature",
+    "canonical_json_bytes",
+    "canonical_manifest_bytes",
+    "create_signed_manifest",
+    "decode_signature",
+    "encode_signature",
+    "sign_manifest",
+    "sign_manifest_base64",
+    "verify_manifest",
+    "verify_manifest_base64",
+    "verify_signed_manifest",
+]