pyencode-protector 0.3.0__py3-none-any.whl

pyencode/__init__.py

@@ -0,0 +1,5 @@
+"""Build encrypted Python module bundles."""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"

pyencode/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

pyencode/builder.py

@@ -0,0 +1,628 @@
+"""Build encrypted module trees and their portable Python runtime."""
+
+from __future__ import annotations
+
+import base64
+import ast
+import hashlib
+import json
+import marshal
+import os
+import secrets
+import shutil
+import sys
+import tempfile
+import tokenize
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Sequence
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from . import __version__
+from .container import canonical_json_bytes
+from .code_hardening import harden_code
+from .crypto import derive_bound_master_key
+from .discovery import ProjectLayout, discover_project
+from .errors import PyEncodeError
+from .integrity import (
+    BOUND_FILES_ALGORITHM,
+    BOUND_FILES_FORMAT,
+    bound_files_commitment,
+)
+from .inventory import (
+    discover_inventory_files,
+    hash_inventory_files,
+    validate_inventory_path,
+)
+from .opaque import (
+    OpaqueModuleContext,
+    derive_module_root_key,
+    encrypt_module_index,
+    module_index_commitment,
+    pack_opaque_artifact,
+)
+from .source import prepare_source
+
+
+MANIFEST_NAME = ".pyencode-manifest.json"
+RUNTIME_TEMPLATE_FILES = (
+    "__init__.py",
+    "_mp_main.py",
+    "_runtime.py",
+)
+RESERVED_TOP_LEVEL_MODULES = frozenset(
+    {
+        "cryptography",
+        "__main__",
+        "pyencode_runtime",
+        *(name.partition(".")[0].casefold() for name in sys.builtin_module_names),
+        *(name.partition(".")[0].casefold() for name in sys.stdlib_module_names),
+    }
+)
+
+DEFAULT_LAUNCHER = """import sys
+sys.dont_write_bytecode = True
+
+import os
+
+_runtime_directory = os.path.join(os.path.dirname(os.path.realpath(__file__)), "pyencode_runtime")
+_expected_runtime_files = {"__init__.py", "_mp_main.py", "_runtime.py", "_build.py"}
+try:
+    with os.scandir(_runtime_directory) as _runtime_iterator:
+        _runtime_entries = tuple(_runtime_iterator)
+except OSError as exc:
+    raise ImportError("pyencode runtime directory is missing or unreadable") from exc
+_runtime_names = {entry.name for entry in _runtime_entries}
+_runtime_problems = []
+if _expected_runtime_files - _runtime_names:
+    _runtime_problems.append("missing " + ", ".join(sorted(_expected_runtime_files - _runtime_names)))
+if _runtime_names - _expected_runtime_files:
+    _runtime_problems.append("unexpected " + ", ".join(sorted(_runtime_names - _expected_runtime_files)))
+_non_files = sorted(
+    entry.name
+    for entry in _runtime_entries
+    if entry.is_symlink() or not entry.is_file(follow_symlinks=False)
+)
+if _non_files:
+    _runtime_problems.append("not regular files " + ", ".join(_non_files))
+if _runtime_problems:
+    raise ImportError(
+        "pyencode runtime directory contains unsigned files or directories ("
+        + "; ".join(_runtime_problems)
+        + ")"
+    )
+
+from pyencode_runtime import run
+
+if __name__ == "__main__":
+    run()
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class BuildOptions:
+    source: Path
+    output: Path
+    entry_module: str | None = None
+    excludes: tuple[str, ...] = ()
+    include_resources: bool = True
+    strip_docstrings: bool = True
+    optimize: int = 0
+    expires: date | None = None
+    launcher: Path | None = None
+    rename_locals: bool = False
+    support: tuple[tuple[Path, str], ...] = ()
+    allow_extra_data: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class BuildResult:
+    output: Path
+    entry_module: str
+    build_id: str
+    python_tag: str
+    module_count: int
+    resource_count: int
+    support_count: int
+    launcher_name: str
+
+
+def _python_tag() -> str:
+    return f"cp{sys.version_info.major}{sys.version_info.minor}"
+
+
+def _validate_build_interpreter() -> None:
+    version = (sys.version_info.major, sys.version_info.minor)
+    if getattr(sys.implementation, "name", None) != "cpython" or version < (3, 10):
+        raise PyEncodeError("Builds require standard CPython 3.10 or newer")
+
+
+def _validate_entry(layout: ProjectLayout, requested: str | None) -> str:
+    entry = requested or layout.inferred_entry
+    if entry is None:
+        raise PyEncodeError(
+            "Could not infer an entry module; pass --entry (for example --entry myapp.__main__)"
+        )
+    names = {module.name for module in layout.modules}
+    if entry not in names:
+        raise PyEncodeError(f"Entry module {entry!r} was not found in the protected source tree")
+    return entry
+
+
+def _validate_reserved_modules(layout: ProjectLayout) -> None:
+    conflicts = sorted(
+        module.name
+        for module in layout.modules
+        if module.name.partition(".")[0].casefold() in RESERVED_TOP_LEVEL_MODULES
+    )
+    if conflicts:
+        raise PyEncodeError(
+            "Protected source uses a reserved runtime namespace: "
+            + ", ".join(conflicts)
+        )
+
+
+def _validate_module_hierarchy(layout: ProjectLayout) -> None:
+    package_flags = {module.name: module.is_package for module in layout.modules}
+    for module in layout.modules:
+        parts = module.name.split(".")
+        for end in range(1, len(parts)):
+            ancestor = ".".join(parts[:end])
+            if ancestor in package_flags and not package_flags[ancestor]:
+                raise PyEncodeError(
+                    f"Protected module {ancestor!r} is not a package but has "
+                    f"protected child {module.name!r}"
+                )
+
+
+def _validate_launcher(launcher: Path | None) -> tuple[Path | None, str]:
+    if launcher is None:
+        return None, "run.py"
+    source = launcher.expanduser().resolve()
+    if not source.is_file():
+        raise PyEncodeError(f"Launcher does not exist or is not a file: {source}")
+    name = source.name
+    if source.suffix.lower() != ".py" or not source.stem.isidentifier():
+        raise PyEncodeError("Launcher must be a single valid Python filename")
+    if name.casefold() == "pyencode_runtime.py":
+        raise PyEncodeError("Launcher name would shadow the pyencode_runtime package")
+    _validate_custom_launcher_bootstrap(source)
+    return source, name
+
+
+def _validate_custom_launcher_bootstrap(source: Path) -> None:
+    try:
+        with tokenize.open(source) as stream:
+            tree = ast.parse(stream.read(), filename=str(source))
+    except (OSError, SyntaxError, UnicodeError) as exc:
+        raise PyEncodeError(f"Custom launcher is not valid Python: {source}") from exc
+
+    sys_aliases: set[str] = set()
+    protected = False
+    for statement in tree.body:
+        if (
+            isinstance(statement, ast.Expr)
+            and isinstance(statement.value, ast.Constant)
+            and isinstance(statement.value.value, str)
+        ):
+            continue
+        if isinstance(statement, ast.ImportFrom) and statement.module == "__future__":
+            continue
+        if isinstance(statement, ast.Import):
+            imported = {alias.name for alias in statement.names}
+            if not protected and not imported.issubset({"sys", "os"}):
+                break
+            for alias in statement.names:
+                if alias.name == "sys":
+                    sys_aliases.add(alias.asname or "sys")
+            continue
+        if isinstance(statement, (ast.Assign, ast.AnnAssign)):
+            targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
+            value = statement.value
+            if any(
+                isinstance(target, ast.Attribute)
+                and target.attr == "dont_write_bytecode"
+                and isinstance(target.value, ast.Name)
+                and target.value.id in sys_aliases
+                for target in targets
+            ) and isinstance(value, ast.Constant) and value.value is True:
+                protected = True
+                break
+        if not protected:
+            break
+    if not protected:
+        raise PyEncodeError(
+            "Custom launcher must set sys.dont_write_bytecode = True before "
+            "importing any non-bootstrap module"
+        )
+
+
+def _validate_output(source: Path, output: Path) -> Path:
+    output = output.expanduser().resolve()
+    if output == source or output in source.parents:
+        raise PyEncodeError("Output must not replace the source or one of its parent directories")
+    if output.exists():
+        if not output.is_dir():
+            raise PyEncodeError(f"Output exists and is not a directory: {output}")
+        if any(output.iterdir()):
+            raise PyEncodeError(f"Output directory is not empty: {output}")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    return output
+
+
+def _compile_module(path: Path, module_name: str, options: BuildOptions) -> bytes:
+    with tokenize.open(path) as source_file:
+        text = source_file.read()
+    synthetic_filename = f"<pyencode:{module_name}>"
+    prepared = prepare_source(text, synthetic_filename, strip_docstrings=options.strip_docstrings)
+    code = compile(
+        prepared,
+        synthetic_filename,
+        "exec",
+        dont_inherit=True,
+        optimize=options.optimize,
+    )
+    if options.rename_locals:
+        code = harden_code(code, module_name=module_name)
+    return marshal.dumps(code)
+
+
+def _mask_master_key(master_key: bytes, build_id: str) -> tuple[list[str], list[int]]:
+    mask = hashlib.sha256(b"pyencode-key-mask\0" + bytes.fromhex(build_id)).digest()
+    masked = bytes(value ^ mask[index] for index, value in enumerate(master_key))
+    widths = (5, 7, 4, 8, 8)
+    chunks: list[bytes] = []
+    offset = 0
+    for width in widths:
+        chunks.append(masked[offset : offset + width])
+        offset += width
+
+    shuffled_indexes = list(range(len(chunks)))
+    secrets.SystemRandom().shuffle(shuffled_indexes)
+    stored = [base64.b85encode(chunks[index]).decode("ascii") for index in shuffled_indexes]
+    restore_order = [shuffled_indexes.index(index) for index in range(len(chunks))]
+    return stored, restore_order
+
+
+def _write_runtime_config(
+    runtime_directory: Path,
+    *,
+    build_id: str,
+    python_tag: str,
+    public_key: bytes,
+    master_key: bytes,
+    launcher_name: str,
+    bootstrap_paths: tuple[str, ...],
+) -> None:
+    parts, order = _mask_master_key(master_key, build_id)
+    content = "\n".join(
+        (
+            "# Generated by pyencode. Do not edit.",
+            f"BUILD_ID = {build_id!r}",
+            f"PYTHON_TAG = {python_tag!r}",
+            f"PUBLIC_KEY_B64 = {base64.b64encode(public_key).decode('ascii')!r}",
+            f"KEY_PARTS = {parts!r}",
+            f"KEY_ORDER = {order!r}",
+            f"MANIFEST_NAME = {MANIFEST_NAME!r}",
+            f"LAUNCHER_NAME = {launcher_name!r}",
+            f"BOOTSTRAP_PATHS = {list(bootstrap_paths)!r}",
+            "",
+        )
+    )
+    (runtime_directory / "_build.py").write_text(content, encoding="utf-8", newline="\n")
+
+
+def _copy_runtime(destination: Path) -> None:
+    template = Path(__file__).with_name("runtime_template")
+    if not template.is_dir():
+        raise PyEncodeError(f"Runtime template is missing: {template}")
+    destination.mkdir(parents=True, exist_ok=True)
+    for filename in RUNTIME_TEMPLATE_FILES:
+        source = template / filename
+        if not source.is_file():
+            raise PyEncodeError(f"Runtime template file is missing: {source}")
+        shutil.copy2(source, destination / filename)
+
+
+def _write_launcher(destination: Path, source: Path | None, name: str) -> None:
+    target = destination / name
+    if source is not None:
+        shutil.copyfile(source, target)
+    else:
+        target.write_text(DEFAULT_LAUNCHER, encoding="utf-8", newline="\n")
+
+
+def _write_requirements(destination: Path) -> None:
+    (destination / "requirements.txt").write_text(
+        "cryptography>=42\n", encoding="utf-8", newline="\n"
+    )
+
+
+def _copy_regular_file(source: Path, target: Path, destination: Path) -> None:
+    if source.is_symlink():
+        raise PyEncodeError(f"Refusing to copy symlink into protected output: {source}")
+    if not source.is_file():
+        raise PyEncodeError(f"Support source is not a regular file: {source}")
+    if target.exists():
+        try:
+            relative = target.relative_to(destination).as_posix()
+        except ValueError:
+            relative = str(target)
+        raise PyEncodeError(f"Support output path collides with an existing file: {relative}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+def _copy_support_inputs(
+    destination: Path,
+    support: Sequence[tuple[Path, str]],
+    launcher_name: str,
+) -> int:
+    copied = 0
+    for raw_source, raw_target in support:
+        target_text = validate_inventory_path(raw_target)
+        _validate_generated_path_conflict(target_text, launcher_name)
+        source = Path(raw_source).expanduser()
+        if source.is_symlink():
+            raise PyEncodeError(f"Refusing to copy symlink support input: {source}")
+        try:
+            source = source.resolve(strict=True)
+        except OSError as exc:
+            raise PyEncodeError(f"Support input is missing or unreadable: {source}") from exc
+        target_root = destination / Path(*target_text.split("/"))
+        if source.is_file():
+            _copy_regular_file(source, target_root, destination)
+            copied += 1
+            continue
+        if not source.is_dir():
+            raise PyEncodeError(f"Support input is not a regular file or directory: {source}")
+        for relative_text in discover_inventory_files(source):
+            relative = Path(*relative_text.split("/"))
+            _copy_regular_file(source / relative, target_root / relative, destination)
+            copied += 1
+    return copied
+
+
+def _validate_generated_path_conflict(relative: str, launcher_name: str) -> None:
+    parts = relative.split("/")
+    if parts[0].casefold() == "pyencode_runtime":
+        raise PyEncodeError(
+            "Output path uses the reserved pyencode_runtime subtree: " + relative
+        )
+    if relative.casefold() == MANIFEST_NAME.casefold():
+        raise PyEncodeError(f"Output path is reserved for the signed manifest: {relative}")
+    if relative.casefold() == launcher_name.casefold():
+        raise PyEncodeError(f"Output path collides with the generated launcher: {relative}")
+    if PurePosixPath(relative).suffix.casefold() == ".pye":
+        raise PyEncodeError(f"Output path uses the reserved .pye artifact suffix: {relative}")
+
+
+def _opaque_artifact_path(module_name: str, is_package: bool, token: str) -> Path:
+    parts = module_name.split(".")
+    directory_parts = parts if is_package else parts[:-1]
+    return Path(*directory_parts, f"{token}.pye")
+
+
+def _public_key_bytes(private_key: Ed25519PrivateKey) -> bytes:
+    return private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def _signed_manifest(
+    payload: dict[str, object], private_key: Ed25519PrivateKey
+) -> dict[str, object]:
+    payload_bytes = canonical_json_bytes(payload)
+    signature = private_key.sign(payload_bytes)
+    wrapper: dict[str, object] = {
+        "manifest": payload,
+        "signature": base64.b64encode(signature).decode("ascii"),
+    }
+    return wrapper
+
+
+def _build_into(
+    layout: ProjectLayout,
+    destination: Path,
+    options: BuildOptions,
+    entry_module: str,
+) -> BuildResult:
+    build_id = secrets.token_hex(16)
+    python_tag = _python_tag()
+    master_key = os.urandom(32)
+    signing_key = Ed25519PrivateKey.generate()
+    public_key = _public_key_bytes(signing_key)
+    launcher_source, launcher_name = _validate_launcher(options.launcher)
+    module_index_entries: dict[str, dict[str, object]] = {}
+    module_tokens: dict[str, str] = {}
+
+    runtime_directory = destination / "pyencode_runtime"
+    _copy_runtime(runtime_directory)
+    _write_launcher(destination, launcher_source, launcher_name)
+
+    for resource in layout.resources:
+        _validate_generated_path_conflict(
+            resource.output_path.as_posix(), launcher_name
+        )
+        output_path = destination / resource.output_path
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        if resource.source_path.is_symlink():
+            raise PyEncodeError(
+                f"Refusing to copy symlink resource: {resource.source_path}"
+            )
+        shutil.copy2(resource.source_path, output_path)
+    # Keep the generated runtime dependency authoritative even when a
+    # project-root source tree also contains a requirements.txt resource.
+    _write_requirements(destination)
+    support_count = _copy_support_inputs(destination, options.support, launcher_name)
+
+    _write_runtime_config(
+        runtime_directory,
+        build_id=build_id,
+        python_tag=python_tag,
+        public_key=public_key,
+        master_key=master_key,
+        launcher_name=launcher_name,
+        bootstrap_paths=tuple(
+            sorted(
+                {
+                    "_vendor"
+                    for _source, target in options.support
+                    if validate_inventory_path(target) == "_vendor"
+                }
+            )
+        ),
+    )
+
+    bound_paths = discover_inventory_files(destination)
+    bound_file_digests = hash_inventory_files(destination, bound_paths)
+    commitment = bound_files_commitment(bound_file_digests)
+    support_root_key = derive_bound_master_key(master_key, build_id, commitment)
+
+    used_tokens: set[str] = set()
+    for module in layout.modules:
+        while True:
+            token = secrets.token_hex(16)
+            if token not in used_tokens:
+                break
+        used_tokens.add(token)
+        module_tokens[module.name] = token
+        module_index_entries[module.name] = {
+            "artifact": token,
+            "package": module.is_package,
+        }
+
+    encrypted_index = encrypt_module_index(
+        {
+            "format": 1,
+            "entry_module": entry_module,
+            "modules": module_index_entries,
+        },
+        support_root_key,
+        build_id=build_id,
+        python_tag=python_tag,
+    )
+    index_commitment = module_index_commitment(
+        encrypted_index,
+        build_id=build_id,
+        python_tag=python_tag,
+    )
+    module_root_key = derive_module_root_key(
+        support_root_key,
+        build_id,
+        index_commitment,
+    )
+    artifacts_manifest: dict[str, str] = {}
+
+    for module in layout.modules:
+        marshalled = _compile_module(module.source_path, module.name, options)
+        token = module_tokens[module.name]
+        context = OpaqueModuleContext(
+            build_id=build_id,
+            python_tag=python_tag,
+            module=module.name,
+            package=module.is_package,
+            token=token,
+            marshal_version=marshal.version,
+        )
+        protected = pack_opaque_artifact(marshalled, module_root_key, context)
+        relative_output = _opaque_artifact_path(module.name, module.is_package, token)
+        output_path = destination / relative_output
+        if output_path.exists():
+            raise PyEncodeError(
+                f"Opaque artifact path collides with a resource: {relative_output.as_posix()}"
+            )
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(protected)
+        artifacts_manifest[token] = hashlib.sha256(protected).hexdigest()
+
+    # A final cross-platform scan catches case-fold collisions introduced by
+    # logical package directories and opaque artifact paths before publishing.
+    discover_inventory_files(destination)
+
+    policy: dict[str, object] = {}
+    if options.expires is not None:
+        policy["expires"] = options.expires.isoformat()
+    if options.allow_extra_data:
+        policy["allow_extra_data"] = True
+    manifest_payload: dict[str, object] = {
+        "format": 3,
+        "tool_version": __version__,
+        "build_id": build_id,
+        "python_tag": python_tag,
+        "created_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "module_index": {
+            "format": 1,
+            "cipher": "aes-256-gcm",
+            "compression": "zlib",
+            "nonce_b64": base64.b64encode(encrypted_index.nonce).decode("ascii"),
+            "ciphertext_b64": base64.b64encode(encrypted_index.ciphertext).decode("ascii"),
+            "commitment_sha256": index_commitment.hex(),
+        },
+        "artifacts": dict(sorted(artifacts_manifest.items())),
+        "policy": policy,
+        "integrity": {
+            "format": BOUND_FILES_FORMAT,
+            "algorithm": BOUND_FILES_ALGORITHM,
+            "files": bound_file_digests,
+            "commitment_sha256": commitment.hex(),
+        },
+    }
+    wrapper = _signed_manifest(manifest_payload, signing_key)
+    (destination / MANIFEST_NAME).write_text(
+        json.dumps(wrapper, indent=2, sort_keys=True, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+
+    return BuildResult(
+        output=destination,
+        entry_module=entry_module,
+        build_id=build_id,
+        python_tag=python_tag,
+        module_count=len(layout.modules),
+        resource_count=len(layout.resources),
+        support_count=support_count,
+        launcher_name=launcher_name,
+    )
+
+
+def build(options: BuildOptions) -> BuildResult:
+    _validate_build_interpreter()
+    if options.optimize not in (0, 1, 2):
+        raise PyEncodeError("Optimization level must be 0, 1, or 2")
+    layout = discover_project(
+        options.source,
+        excludes=options.excludes,
+        include_resources=options.include_resources,
+    )
+    _validate_reserved_modules(layout)
+    _validate_module_hierarchy(layout)
+    entry_module = _validate_entry(layout, options.entry_module)
+    output = _validate_output(layout.source, options.output)
+
+    temporary = Path(
+        tempfile.mkdtemp(prefix=f".{output.name}.pyencode-", dir=str(output.parent))
+    )
+    try:
+        temporary_result = _build_into(layout, temporary, options, entry_module)
+        if output.exists():
+            output.rmdir()
+        temporary.replace(output)
+        return BuildResult(
+            output=output,
+            entry_module=temporary_result.entry_module,
+            build_id=temporary_result.build_id,
+            python_tag=temporary_result.python_tag,
+            module_count=temporary_result.module_count,
+            resource_count=temporary_result.resource_count,
+            support_count=temporary_result.support_count,
+            launcher_name=temporary_result.launcher_name,
+        )
+    except Exception:
+        shutil.rmtree(temporary, ignore_errors=True)
+        raise