pyencode-protector 0.3.0__py3-none-any.whl

pyencode/crypto.py

@@ -0,0 +1,319 @@
+"""Small, auditable cryptographic primitives used by pyencode.
+
+No custom cipher is implemented here.  Module keys are domain-separated with
+HKDF-SHA256 and payloads are authenticated with AES-256-GCM.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import NamedTuple, TypeAlias
+
+from cryptography.exceptions import InvalidSignature, InvalidTag
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from .errors import CryptoError, IntegrityError, InvalidKeyError, SignatureError
+
+
+NONCE_SIZE = 12
+KEY_SIZE = 32
+TAG_SIZE = 16
+BOUND_COMMITMENT_SIZE = 32
+_BUILD_ID_RE = re.compile(r"[0-9a-fA-F]+\Z")
+
+BytesLike: TypeAlias = bytes | bytearray | memoryview
+PrivateKeyLike: TypeAlias = Ed25519PrivateKey | BytesLike
+PublicKeyLike: TypeAlias = Ed25519PublicKey | BytesLike
+
+
+class EncryptedPayload(NamedTuple):
+    """The nonce and AES-GCM ciphertext (with its tag appended)."""
+
+    nonce: bytes
+    ciphertext: bytes
+
+
+class Ed25519KeyPair(NamedTuple):
+    """Raw 32-byte Ed25519 private and public keys."""
+
+    private_key: bytes
+    public_key: bytes
+
+
+def _as_bytes(value: BytesLike, *, name: str) -> bytes:
+    if not isinstance(value, (bytes, bytearray, memoryview)):
+        raise CryptoError(f"{name} must be bytes-like")
+    return bytes(value)
+
+
+def _build_id_bytes(build_id: str) -> bytes:
+    if not isinstance(build_id, str):
+        raise CryptoError("build_id must be a string")
+    if (
+        not build_id
+        or len(build_id) % 2
+        or _BUILD_ID_RE.fullmatch(build_id) is None
+    ):
+        raise CryptoError("build_id must be a non-empty, even-length hexadecimal string")
+    # Keep this conversion explicit: the container format defines the HKDF salt
+    # as bytes.fromhex(build_id), not as the UTF-8 spelling of the identifier.
+    return bytes.fromhex(build_id)
+
+
+def derive_module_key(master_key: BytesLike, build_id: str, module: str) -> bytes:
+    """Derive a 32-byte key for one module using HKDF-SHA256.
+
+    The derivation is exactly::
+
+        salt = bytes.fromhex(build_id)
+        info = b"pyencode-module\\0" + module.encode("utf-8")
+    """
+
+    key_material = _as_bytes(master_key, name="master_key")
+    if not key_material:
+        raise InvalidKeyError("master_key must not be empty")
+    if not isinstance(module, str):
+        raise CryptoError("module must be a string")
+    if not module:
+        raise CryptoError("module must not be empty")
+    try:
+        module_bytes = module.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise CryptoError("module is not valid UTF-8 text") from exc
+
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=KEY_SIZE,
+        salt=_build_id_bytes(build_id),
+        info=b"pyencode-module\0" + module_bytes,
+    ).derive(key_material)
+
+
+def derive_bound_master_key(
+    master_key: BytesLike,
+    build_id: str,
+    commitment: BytesLike,
+) -> bytes:
+    """Bind a build's root key to the exact staged runtime/support files.
+
+    ``commitment`` is the 32-byte digest produced by
+    :func:`pyencode.integrity.bound_files_commitment`.  The returned key, not
+    the recoverable root key stored by the generated runtime, is used as the
+    master input for per-module key derivation.
+    """
+
+    key_material = _as_bytes(master_key, name="master_key")
+    binding = _as_bytes(commitment, name="commitment")
+    if not key_material:
+        raise InvalidKeyError("master_key must not be empty")
+    if len(binding) != BOUND_COMMITMENT_SIZE:
+        raise CryptoError("bound-files commitment must be exactly 32 bytes")
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=KEY_SIZE,
+        salt=_build_id_bytes(build_id),
+        info=b"pyencode-root-key-v2\0" + binding,
+    ).derive(key_material)
+
+
+def encrypt_payload(
+    payload: BytesLike,
+    key: BytesLike,
+    *,
+    aad: BytesLike = b"",
+    nonce: BytesLike | None = None,
+) -> EncryptedPayload:
+    """Encrypt and authenticate a payload with AES-256-GCM.
+
+    ``ciphertext`` includes the 16-byte GCM authentication tag.  Supplying a
+    nonce is useful for deterministic test vectors; production callers should
+    leave it unset so a fresh random 96-bit nonce is generated.
+    """
+
+    plaintext = _as_bytes(payload, name="payload")
+    aes_key = _as_bytes(key, name="key")
+    associated_data = _as_bytes(aad, name="aad")
+    if len(aes_key) != KEY_SIZE:
+        raise InvalidKeyError("AES-256-GCM key must be exactly 32 bytes")
+
+    if nonce is None:
+        nonce_bytes = os.urandom(NONCE_SIZE)
+    else:
+        nonce_bytes = _as_bytes(nonce, name="nonce")
+        if len(nonce_bytes) != NONCE_SIZE:
+            raise CryptoError("AES-GCM nonce must be exactly 12 bytes")
+
+    try:
+        ciphertext = AESGCM(aes_key).encrypt(
+            nonce_bytes, plaintext, associated_data
+        )
+    except (TypeError, ValueError) as exc:
+        raise CryptoError("could not encrypt payload") from exc
+    return EncryptedPayload(nonce_bytes, ciphertext)
+
+
+def decrypt_payload(
+    ciphertext: BytesLike,
+    key: BytesLike,
+    nonce: BytesLike,
+    *,
+    aad: BytesLike = b"",
+) -> bytes:
+    """Authenticate and decrypt an AES-256-GCM payload.
+
+    ``IntegrityError`` intentionally does not distinguish a wrong key from
+    modified data.
+    """
+
+    encrypted = _as_bytes(ciphertext, name="ciphertext")
+    aes_key = _as_bytes(key, name="key")
+    nonce_bytes = _as_bytes(nonce, name="nonce")
+    associated_data = _as_bytes(aad, name="aad")
+    if len(aes_key) != KEY_SIZE:
+        raise InvalidKeyError("AES-256-GCM key must be exactly 32 bytes")
+    if len(nonce_bytes) != NONCE_SIZE:
+        raise CryptoError("AES-GCM nonce must be exactly 12 bytes")
+    if len(encrypted) < TAG_SIZE:
+        raise IntegrityError("encrypted payload is shorter than the GCM tag")
+
+    try:
+        return AESGCM(aes_key).decrypt(
+            nonce_bytes, encrypted, associated_data
+        )
+    except InvalidTag as exc:
+        raise IntegrityError("payload authentication failed") from exc
+    except (TypeError, ValueError) as exc:
+        raise CryptoError("could not decrypt payload") from exc
+
+
+def load_private_key(key: PrivateKeyLike) -> Ed25519PrivateKey:
+    """Load an Ed25519 private key object from an object or 32 raw bytes."""
+
+    if isinstance(key, Ed25519PrivateKey):
+        return key
+    try:
+        raw = _as_bytes(key, name="private_key")
+        if len(raw) != KEY_SIZE:
+            raise InvalidKeyError("Ed25519 private key must be exactly 32 raw bytes")
+        return Ed25519PrivateKey.from_private_bytes(raw)
+    except InvalidKeyError:
+        raise
+    except (TypeError, ValueError) as exc:
+        raise InvalidKeyError("invalid Ed25519 private key") from exc
+
+
+def load_public_key(key: PublicKeyLike) -> Ed25519PublicKey:
+    """Load an Ed25519 public key object from an object or 32 raw bytes."""
+
+    if isinstance(key, Ed25519PublicKey):
+        return key
+    try:
+        raw = _as_bytes(key, name="public_key")
+        if len(raw) != KEY_SIZE:
+            raise InvalidKeyError("Ed25519 public key must be exactly 32 raw bytes")
+        return Ed25519PublicKey.from_public_bytes(raw)
+    except InvalidKeyError:
+        raise
+    except (TypeError, ValueError) as exc:
+        raise InvalidKeyError("invalid Ed25519 public key") from exc
+
+
+def private_key_bytes(key: PrivateKeyLike) -> bytes:
+    """Return a private key in its portable 32-byte raw encoding."""
+
+    return load_private_key(key).private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def public_key_bytes(key: PublicKeyLike | PrivateKeyLike) -> bytes:
+    """Return a public key in its portable 32-byte raw encoding."""
+
+    if isinstance(key, Ed25519PrivateKey):
+        public_key = key.public_key()
+    else:
+        try:
+            public_key = load_public_key(key)  # type: ignore[arg-type]
+        except InvalidKeyError:
+            # Raw private and public keys are both 32 bytes, so bytes cannot be
+            # disambiguated.  Bytes are intentionally interpreted as public.
+            raise
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def generate_ed25519_keypair() -> Ed25519KeyPair:
+    """Generate a new Ed25519 keypair in raw, cross-platform encodings."""
+
+    private = Ed25519PrivateKey.generate()
+    return Ed25519KeyPair(
+        private_key_bytes(private),
+        private.public_key().public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        ),
+    )
+
+
+def sign_bytes(data: BytesLike, private_key: PrivateKeyLike) -> bytes:
+    """Return an Ed25519 signature for arbitrary bytes."""
+
+    message = _as_bytes(data, name="data")
+    try:
+        return load_private_key(private_key).sign(message)
+    except InvalidKeyError:
+        raise
+    except (TypeError, ValueError) as exc:
+        raise CryptoError("could not sign data") from exc
+
+
+def verify_bytes(
+    data: BytesLike,
+    signature: BytesLike,
+    public_key: PublicKeyLike,
+) -> bool:
+    """Verify an Ed25519 signature, returning ``True`` or raising on failure."""
+
+    message = _as_bytes(data, name="data")
+    signature_bytes = _as_bytes(signature, name="signature")
+    try:
+        load_public_key(public_key).verify(signature_bytes, message)
+    except InvalidSignature as exc:
+        raise SignatureError("signature verification failed") from exc
+    except InvalidKeyError:
+        raise
+    except (TypeError, ValueError) as exc:
+        raise SignatureError("signature is malformed") from exc
+    return True
+
+
+__all__ = [
+    "BOUND_COMMITMENT_SIZE",
+    "Ed25519KeyPair",
+    "EncryptedPayload",
+    "KEY_SIZE",
+    "NONCE_SIZE",
+    "TAG_SIZE",
+    "decrypt_payload",
+    "derive_bound_master_key",
+    "derive_module_key",
+    "encrypt_payload",
+    "generate_ed25519_keypair",
+    "load_private_key",
+    "load_public_key",
+    "private_key_bytes",
+    "public_key_bytes",
+    "sign_bytes",
+    "verify_bytes",
+]

pyencode/discovery.py

@@ -0,0 +1,168 @@
+"""Discover Python modules and resource files in an input tree."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Iterable, Sequence
+
+from .errors import PyEncodeError
+
+
+DEFAULT_EXCLUDED_DIRECTORIES = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "env",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "build",
+        "dist",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SourceModule:
+    name: str
+    source_path: Path
+    output_path: Path
+    is_package: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceFile:
+    source_path: Path
+    output_path: Path
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectLayout:
+    source: Path
+    base_directory: Path
+    modules: tuple[SourceModule, ...]
+    resources: tuple[ResourceFile, ...]
+    inferred_entry: str | None
+
+
+def _relative_module_name(relative_path: Path) -> tuple[str, bool]:
+    is_package = relative_path.name == "__init__.py"
+    module_path = relative_path.parent if is_package else relative_path.with_suffix("")
+    parts = module_path.parts
+    if not parts:
+        raise PyEncodeError("A package __init__.py must have a package directory name")
+    invalid = [part for part in parts if not part.isidentifier()]
+    if invalid:
+        joined = ", ".join(repr(part) for part in invalid)
+        raise PyEncodeError(f"Invalid Python module path component(s): {joined}")
+    return ".".join(parts), is_package
+
+
+def _protected_output_path(relative_path: Path) -> Path:
+    if relative_path.name == "__init__.py":
+        return relative_path.with_name("__init__.pye")
+    return relative_path.with_suffix(".pye")
+
+
+def _matches_user_exclude(relative_path: Path, patterns: Sequence[str]) -> bool:
+    value = relative_path.as_posix()
+    return any(fnmatch(value, pattern) or fnmatch(relative_path.name, pattern) for pattern in patterns)
+
+
+def _is_default_excluded(relative_path: Path) -> bool:
+    if any(part in DEFAULT_EXCLUDED_DIRECTORIES for part in relative_path.parts):
+        return True
+    return relative_path.suffix.lower() in {".pyc", ".pyo", ".pye"}
+
+
+def _iter_files(scope: Path) -> Iterable[Path]:
+    if scope.is_file():
+        yield scope
+        return
+    for path in sorted(scope.rglob("*")):
+        if path.is_file():
+            yield path
+
+
+def discover_project(
+    source: Path,
+    *,
+    excludes: Sequence[str] = (),
+    include_resources: bool = True,
+) -> ProjectLayout:
+    """Return protected modules and copied resources for *source*.
+
+    A directory containing ``__init__.py`` is treated as one package and keeps
+    its top-level package name. Other directories are treated as project roots.
+    """
+
+    source = source.expanduser().resolve()
+    if not source.exists():
+        raise PyEncodeError(f"Source does not exist: {source}")
+    if source.is_file() and source.suffix.lower() != ".py":
+        raise PyEncodeError("A source file must have the .py extension")
+
+    if source.is_file():
+        base_directory = source.parent
+        scope = source
+        package_input = False
+    else:
+        package_input = (source / "__init__.py").is_file()
+        base_directory = source.parent if package_input else source
+        scope = source
+
+    modules: list[SourceModule] = []
+    resources: list[ResourceFile] = []
+    seen_modules: set[str] = set()
+
+    for path in _iter_files(scope):
+        relative = path.relative_to(base_directory)
+        if _is_default_excluded(relative) or _matches_user_exclude(relative, excludes):
+            continue
+
+        if path.suffix.lower() == ".py":
+            module_name, is_package = _relative_module_name(relative)
+            if module_name in seen_modules:
+                raise PyEncodeError(f"Duplicate module discovered: {module_name}")
+            seen_modules.add(module_name)
+            modules.append(
+                SourceModule(
+                    name=module_name,
+                    source_path=path,
+                    output_path=_protected_output_path(relative),
+                    is_package=is_package,
+                )
+            )
+        elif include_resources:
+            resources.append(ResourceFile(source_path=path, output_path=relative))
+
+    if not modules:
+        raise PyEncodeError(f"No Python modules found in {source}")
+
+    inferred_entry: str | None = None
+    names = {module.name for module in modules}
+    if source.is_file():
+        inferred_entry = modules[0].name
+    elif package_input:
+        candidate = f"{source.name}.__main__"
+        if candidate in names:
+            inferred_entry = candidate
+    elif "main" in names:
+        inferred_entry = "main"
+    elif len(modules) == 1 and not modules[0].is_package:
+        inferred_entry = modules[0].name
+
+    return ProjectLayout(
+        source=source,
+        base_directory=base_directory,
+        modules=tuple(modules),
+        resources=tuple(resources),
+        inferred_entry=inferred_entry,
+    )
+

pyencode/errors.py

@@ -0,0 +1,59 @@
+"""Project-specific exceptions raised by :mod:`pyencode`.
+
+The public exception hierarchy deliberately separates malformed input from
+cryptographic integrity failures.  Applications can catch ``PyEncodeError``
+for a user-facing error while still treating ``IntegrityError`` as a likely
+tamper/wrong-key condition.
+"""
+
+from __future__ import annotations
+
+
+class PyEncodeError(Exception):
+    """Base class for all expected pyencode failures."""
+
+
+class ContainerError(PyEncodeError):
+    """A protected module container is malformed or unsupported."""
+
+
+class UnsupportedFormatError(ContainerError):
+    """The container uses a format version this runtime cannot read."""
+
+
+class CryptoError(PyEncodeError):
+    """A cryptographic operation could not be completed."""
+
+
+class InvalidKeyError(CryptoError):
+    """A key has an invalid type, encoding, or size."""
+
+
+class IntegrityError(CryptoError):
+    """Authenticated data is corrupt, was modified, or used the wrong key."""
+
+
+class ManifestError(PyEncodeError):
+    """A manifest is malformed or cannot be serialized canonically."""
+
+
+class SignatureError(ManifestError, IntegrityError):
+    """A manifest signature is missing, malformed, or invalid."""
+
+
+# A compatibility spelling for callers that do not capitalize the product
+# name as two words.  New code should use ``PyEncodeError``.
+PyencodeError = PyEncodeError
+
+
+__all__ = [
+    "ContainerError",
+    "CryptoError",
+    "IntegrityError",
+    "InvalidKeyError",
+    "ManifestError",
+    "PyEncodeError",
+    "PyencodeError",
+    "SignatureError",
+    "UnsupportedFormatError",
+]

pyencode/integrity.py

@@ -0,0 +1,88 @@
+"""Deterministic commitments for plaintext runtime and launcher files."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path, PurePosixPath
+from typing import Mapping, Sequence
+
+from .container import canonical_json_bytes
+from .errors import PyEncodeError
+
+
+BOUND_FILES_FORMAT = 1
+BOUND_FILES_ALGORITHM = "sha256"
+BOUND_FILES_DOMAIN = b"pyencode-bound-files-v1\0"
+
+
+def validate_bound_path(value: str) -> str:
+    """Validate a platform-neutral relative path and return its canonical form."""
+
+    if not isinstance(value, str) or not value or "\\" in value:
+        raise PyEncodeError("bound file paths must be non-empty POSIX relative paths")
+    path = PurePosixPath(value)
+    if path.is_absolute() or any(part in ("", ".", "..") for part in path.parts):
+        raise PyEncodeError(f"unsafe bound file path: {value!r}")
+    canonical = path.as_posix()
+    if canonical != value:
+        raise PyEncodeError(f"bound file path is not canonical: {value!r}")
+    return canonical
+
+
+def normalize_file_digests(file_digests: Mapping[str, str]) -> dict[str, str]:
+    """Validate a path-to-SHA256 mapping and return it sorted by path."""
+
+    if not isinstance(file_digests, Mapping) or not file_digests:
+        raise PyEncodeError("bound file digest mapping must not be empty")
+    normalized: dict[str, str] = {}
+    for raw_path, raw_digest in file_digests.items():
+        path = validate_bound_path(raw_path)
+        if not isinstance(raw_digest, str) or len(raw_digest) != 64:
+            raise PyEncodeError(f"invalid SHA-256 digest for bound file {path!r}")
+        try:
+            decoded = bytes.fromhex(raw_digest)
+        except ValueError as exc:
+            raise PyEncodeError(f"invalid SHA-256 digest for bound file {path!r}") from exc
+        if len(decoded) != 32 or raw_digest != raw_digest.lower():
+            raise PyEncodeError(f"invalid SHA-256 digest for bound file {path!r}")
+        normalized[path] = raw_digest
+    return dict(sorted(normalized.items()))
+
+
+def bound_files_commitment(file_digests: Mapping[str, str]) -> bytes:
+    """Commit to exact file paths and raw-byte SHA-256 digests."""
+
+    descriptor = {
+        "format": BOUND_FILES_FORMAT,
+        "files": normalize_file_digests(file_digests),
+    }
+    return hashlib.sha256(BOUND_FILES_DOMAIN + canonical_json_bytes(descriptor)).digest()
+
+
+def hash_bound_files(root: Path, relative_paths: Sequence[str]) -> dict[str, str]:
+    """Hash exact bytes below *root*, rejecting missing or escaping paths."""
+
+    root = root.resolve()
+    result: dict[str, str] = {}
+    for raw_path in relative_paths:
+        relative = validate_bound_path(raw_path)
+        candidate = (root / Path(*PurePosixPath(relative).parts)).resolve()
+        try:
+            candidate.relative_to(root)
+        except ValueError as exc:
+            raise PyEncodeError(f"bound file escapes output root: {relative!r}") from exc
+        if not candidate.is_file():
+            raise PyEncodeError(f"bound file is missing: {relative}")
+        result[relative] = hashlib.sha256(candidate.read_bytes()).hexdigest()
+    return normalize_file_digests(result)
+
+
+__all__ = [
+    "BOUND_FILES_ALGORITHM",
+    "BOUND_FILES_DOMAIN",
+    "BOUND_FILES_FORMAT",
+    "bound_files_commitment",
+    "hash_bound_files",
+    "normalize_file_digests",
+    "validate_bound_path",
+]