pyencode-protector 0.3.0__py3-none-any.whl

pyencode/cli.py

@@ -0,0 +1,136 @@
+"""Command line interface for PyEncode."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Sequence
+
+from . import __version__
+from .builder import BuildOptions, build
+from .errors import PyEncodeError
+
+
+def _expiry(value: str) -> date:
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("expected YYYY-MM-DD") from exc
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pyencode",
+        description="Protect Python modules in authenticated encrypted .pye files.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    build_parser = subparsers.add_parser("build", help="build a protected application")
+    build_parser.add_argument("source", type=Path, help="Python file, project directory, or package")
+    build_parser.add_argument("-o", "--output", type=Path, default=Path("dist"))
+    build_parser.add_argument("-e", "--entry", dest="entry_module", help="entry module name")
+    build_parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="exclude a relative path glob; may be repeated",
+    )
+    build_parser.add_argument(
+        "--no-resources",
+        action="store_true",
+        help="do not copy non-Python files",
+    )
+    build_parser.add_argument(
+        "--keep-docstrings",
+        action="store_true",
+        help="keep module, class, and function docstrings",
+    )
+    build_parser.add_argument(
+        "--optimize",
+        type=int,
+        choices=(0, 1, 2),
+        default=0,
+        help="CPython optimization level (default: 0)",
+    )
+    build_parser.add_argument(
+        "--expires",
+        type=_expiry,
+        metavar="YYYY-MM-DD",
+        help="refuse to run after this UTC date",
+    )
+    build_parser.add_argument(
+        "--launcher",
+        type=Path,
+        help="copy, sign, and key-bind this custom plaintext launcher instead of run.py",
+    )
+    build_parser.add_argument(
+        "--rename-locals",
+        action="store_true",
+        help=(
+            "rename non-argument local metadata conservatively; opt in because "
+            "dynamic locals/frame introspection can depend on original names"
+        ),
+    )
+    build_parser.add_argument(
+        "--support",
+        action="append",
+        nargs=2,
+        default=[],
+        metavar=("SOURCE", "DEST"),
+        help=(
+            "copy, sign, and key-bind an additional file or directory at the "
+            "POSIX-relative output path DEST; may be repeated"
+        ),
+    )
+    build_parser.add_argument(
+        "--allow-extra-data",
+        action="store_true",
+        help=(
+            "allow the host to add unsigned non-code files and directories; "
+            "signed files and recognized Python/native modules remain protected"
+        ),
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "build":
+            result = build(
+                BuildOptions(
+                    source=args.source,
+                    output=args.output,
+                    entry_module=args.entry_module,
+                    excludes=tuple(args.exclude),
+                    include_resources=not args.no_resources,
+                    strip_docstrings=not args.keep_docstrings,
+                    optimize=args.optimize,
+                    expires=args.expires,
+                    launcher=args.launcher,
+                    rename_locals=args.rename_locals,
+                    support=tuple((Path(source), destination) for source, destination in args.support),
+                    allow_extra_data=args.allow_extra_data,
+                )
+            )
+            print(f"Built {result.module_count} protected module(s) in {result.output}")
+            if result.resource_count:
+                print(f"Copied {result.resource_count} resource file(s)")
+            if result.support_count:
+                print(f"Bound {result.support_count} additional support file(s)")
+            print(f"Entry: {result.entry_module} ({result.python_tag})")
+            print(f"Launcher: {result.launcher_name}")
+            print(f"Run: {sys.executable} {result.output / result.launcher_name}")
+            return 0
+    except PyEncodeError as exc:
+        print(f"pyencode: error: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"pyencode: filesystem error: {exc}", file=sys.stderr)
+        return 2
+    return 1

pyencode/code_hardening.py

@@ -0,0 +1,185 @@
+"""Conservative, version-portable hardening for compiled code metadata.
+
+The transformer deliberately changes only metadata fields accepted by
+``CodeType.replace`` on CPython 3.10 and newer. New CPython feature releases
+are admitted on a forward-compatible basis and exercised by the CI matrix.
+It does not rewrite bytecode or line tables.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import types
+
+
+# These names are a conservative signal that a scope may depend on the names
+# exposed through its fast-locals mapping.  Dynamic aliases cannot be detected,
+# so callers that rely on unusual frame introspection should disable local
+# renaming explicitly.
+_REFLECTIVE_LOCAL_NAMES = frozenset(
+    {
+        "__code__",
+        "_getframe",
+        "co_varnames",
+        "currentframe",
+        "dir",
+        "eval",
+        "exec",
+        "f_code",
+        "f_locals",
+        "getargvalues",
+        "getasyncgenlocals",
+        "getcoroutinelocals",
+        "getgeneratorlocals",
+        "locals",
+        "vars",
+    }
+)
+
+_CO_VARARGS = 0x04
+_CO_VARKEYWORDS = 0x08
+_LOCAL_ALIAS_DOMAIN = b"pyencode-local-name-v1\0"
+
+
+def _validate_module_name(module_name: str) -> None:
+    if not isinstance(module_name, str):
+        raise TypeError("module_name must be a string")
+    if not module_name or any(
+        not component.isidentifier() for component in module_name.split(".")
+    ):
+        raise ValueError("module_name must be a dotted Python module name")
+
+
+def _argument_slot_count(code: types.CodeType) -> int:
+    """Return the prefix of ``co_varnames`` occupied by call arguments."""
+
+    count = code.co_argcount + code.co_kwonlyargcount
+    if code.co_flags & _CO_VARARGS:
+        count += 1
+    if code.co_flags & _CO_VARKEYWORDS:
+        count += 1
+    return count
+
+
+def _local_alias(
+    module_name: str,
+    scope_path: tuple[int, ...],
+    slot: int,
+    attempt: int,
+) -> str:
+    scope = ".".join(str(index) for index in scope_path)
+    material = f"{module_name}\0{scope}\0{slot}\0{attempt}".encode("utf-8")
+    digest = hashlib.sha256(_LOCAL_ALIAS_DOMAIN + material).hexdigest()[:12]
+    return f"_pye_{digest}"
+
+
+def _renamed_varnames(
+    code: types.CodeType,
+    *,
+    module_name: str,
+    scope_path: tuple[int, ...],
+) -> tuple[str, ...]:
+    if _REFLECTIVE_LOCAL_NAMES.intersection(code.co_names):
+        return code.co_varnames
+
+    argument_slots = _argument_slot_count(code)
+    if argument_slots >= len(code.co_varnames):
+        return code.co_varnames
+
+    protected_closure_names = set(code.co_cellvars) | set(code.co_freevars)
+    used_names = (
+        set(code.co_varnames)
+        | protected_closure_names
+        | set(code.co_names)
+    )
+    renamed = list(code.co_varnames)
+
+    for slot in range(argument_slots, len(renamed)):
+        if renamed[slot] in protected_closure_names:
+            # On CPython 3.10 a captured local can occur in both co_varnames
+            # and co_cellvars.  Keeping both names aligned avoids changing the
+            # cell-to-local mapping when CodeType.replace reconstructs it.
+            continue
+
+        attempt = 0
+        while True:
+            alias = _local_alias(module_name, scope_path, slot, attempt)
+            if alias not in used_names:
+                break
+            attempt += 1
+        renamed[slot] = alias
+        used_names.add(alias)
+
+    return tuple(renamed)
+
+
+def _harden_code(
+    code: types.CodeType,
+    *,
+    module_name: str,
+    filename: str,
+    rename_locals: bool,
+    normalize_filenames: bool,
+    scope_path: tuple[int, ...],
+) -> types.CodeType:
+    constants = tuple(
+        _harden_code(
+            value,
+            module_name=module_name,
+            filename=filename,
+            rename_locals=rename_locals,
+            normalize_filenames=normalize_filenames,
+            scope_path=(*scope_path, index),
+        )
+        if isinstance(value, types.CodeType)
+        else value
+        for index, value in enumerate(code.co_consts)
+    )
+
+    changes: dict[str, object] = {"co_consts": constants}
+    if rename_locals:
+        changes["co_varnames"] = _renamed_varnames(
+            code,
+            module_name=module_name,
+            scope_path=scope_path,
+        )
+    if normalize_filenames:
+        changes["co_filename"] = filename
+
+    # In particular, do not pass co_linetable=b"".  On CPython 3.11+ an
+    # incomplete positions iterator can make traceback formatting fail.
+    return code.replace(**changes)
+
+
+def harden_code(
+    code: types.CodeType,
+    *,
+    module_name: str,
+    rename_locals: bool = True,
+    normalize_filenames: bool = True,
+) -> types.CodeType:
+    """Return a recursively metadata-hardened copy of *code*.
+
+    Argument names, global/name lookups, closure names, function names,
+    qualified names, constants, bytecode, exception tables, and line tables are
+    preserved.  A scope that directly references a known locals/frame
+    introspection API keeps all of its local names as a compatibility guard.
+
+    Local-name reflection through dynamically aliased APIs cannot be detected;
+    pass ``rename_locals=False`` for code that relies on such behavior.
+    """
+
+    if not isinstance(code, types.CodeType):
+        raise TypeError("code must be a Python code object")
+    _validate_module_name(module_name)
+    return _harden_code(
+        code,
+        module_name=module_name,
+        filename=f"<pyencode:{module_name}>",
+        rename_locals=rename_locals,
+        normalize_filenames=normalize_filenames,
+        scope_path=(),
+    )
+
+
+__all__ = ["harden_code"]

pyencode/container.py

@@ -0,0 +1,319 @@
+"""Binary container for encrypted Python module payloads."""
+
+from __future__ import annotations
+
+import json
+import struct
+import zlib
+from dataclasses import dataclass
+from typing import Any, Mapping, TypedDict, cast
+
+from .crypto import (
+    NONCE_SIZE,
+    TAG_SIZE,
+    BytesLike,
+    decrypt_payload,
+    derive_module_key,
+    encrypt_payload,
+)
+from .errors import ContainerError, UnsupportedFormatError
+
+
+MAGIC = b"PYE1"
+FORMAT_VERSION = 1
+COMPRESSION = "zlib"
+_LENGTH = struct.Struct(">I")
+_PREFIX_SIZE = len(MAGIC) + _LENGTH.size
+_MAX_HEADER_SIZE = 64 * 1024
+
+
+class ModuleHeader(TypedDict):
+    """Authenticated metadata stored before an encrypted module payload."""
+
+    format: int
+    module: str
+    package: bool
+    python_tag: str
+    build_id: str
+    compression: str
+    marshal_version: int
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedContainer:
+    """A parsed but still-encrypted module container."""
+
+    header: ModuleHeader
+    nonce: bytes
+    ciphertext: bytes
+    associated_data: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class UnpackedModule:
+    """The authenticated module header and decompressed plaintext payload."""
+
+    header: ModuleHeader
+    payload: bytes
+
+    def __iter__(self):
+        """Allow convenient ``header, payload = unpack(...)`` usage."""
+
+        yield self.header
+        yield self.payload
+
+
+def _as_bytes(value: BytesLike, *, name: str) -> bytes:
+    if not isinstance(value, (bytes, bytearray, memoryview)):
+        raise ContainerError(f"{name} must be bytes-like")
+    return bytes(value)
+
+
+def canonical_header_bytes(header: Mapping[str, Any]) -> bytes:
+    """Validate and serialize a header as canonical UTF-8 JSON."""
+
+    normalized = validate_header(header)
+    return canonical_json_bytes(normalized)
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    """Serialize a JSON value using the canonical container/manifest encoding."""
+
+    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 ContainerError("header cannot be encoded as canonical JSON") from exc
+
+
+def validate_header(header: Mapping[str, Any]) -> ModuleHeader:
+    """Return a validated copy of a version-1 module header."""
+
+    if not isinstance(header, Mapping):
+        raise ContainerError("container header must be a JSON object")
+
+    required = {
+        "format",
+        "module",
+        "package",
+        "python_tag",
+        "build_id",
+        "compression",
+        "marshal_version",
+    }
+    missing = required.difference(header)
+    if missing:
+        raise ContainerError(
+            "container header is missing: " + ", ".join(sorted(missing))
+        )
+
+    version = header["format"]
+    if type(version) is not int:
+        raise ContainerError("header format must be an integer")
+    if version != FORMAT_VERSION:
+        raise UnsupportedFormatError(f"unsupported container format: {version}")
+
+    module = header["module"]
+    if not isinstance(module, str) or not module:
+        raise ContainerError("header module must be a non-empty string")
+    if "\x00" in module:
+        raise ContainerError("header module must not contain NUL")
+
+    package = header["package"]
+    if type(package) is not bool:
+        raise ContainerError("header package must be a boolean")
+
+    python_tag = header["python_tag"]
+    if not isinstance(python_tag, str) or not python_tag:
+        raise ContainerError("header python_tag must be a non-empty string")
+
+    build_id = header["build_id"]
+    if not isinstance(build_id, str) or not build_id:
+        raise ContainerError("header build_id must be a non-empty hexadecimal string")
+    try:
+        decoded_build_id = bytes.fromhex(build_id)
+    except ValueError as exc:
+        raise ContainerError("header build_id must be hexadecimal") from exc
+    if not decoded_build_id or len(build_id) != len(decoded_build_id) * 2:
+        # The length check rejects spaces accepted by bytes.fromhex().
+        raise ContainerError("header build_id must be canonical even-length hexadecimal")
+
+    compression = header["compression"]
+    if compression != COMPRESSION:
+        raise ContainerError(f"unsupported payload compression: {compression!r}")
+
+    marshal_version = header["marshal_version"]
+    if type(marshal_version) is not int or marshal_version < 0:
+        raise ContainerError("header marshal_version must be a non-negative integer")
+
+    # Version 1 has a deliberately fixed header schema.  Rejecting additions
+    # prevents a producer and consumer from authenticating fields with different
+    # semantics.
+    extra = set(header).difference(required)
+    if extra:
+        raise ContainerError(
+            "container header has unknown fields: " + ", ".join(sorted(extra))
+        )
+
+    return cast(
+        ModuleHeader,
+        {
+            "format": version,
+            "module": module,
+            "package": package,
+            "python_tag": python_tag,
+            "build_id": build_id,
+            "compression": compression,
+            "marshal_version": marshal_version,
+        },
+    )
+
+
+def _prefix(header_json: bytes) -> bytes:
+    if not header_json:
+        raise ContainerError("container header must not be empty")
+    if len(header_json) > _MAX_HEADER_SIZE:
+        raise ContainerError("container header is too large")
+    return MAGIC + _LENGTH.pack(len(header_json)) + header_json
+
+
+def assemble_container(
+    header: Mapping[str, Any],
+    nonce: BytesLike,
+    ciphertext: BytesLike,
+) -> bytes:
+    """Assemble an already-encrypted payload into the version-1 wire format."""
+
+    header_json = canonical_header_bytes(header)
+    nonce_bytes = _as_bytes(nonce, name="nonce")
+    encrypted = _as_bytes(ciphertext, name="ciphertext")
+    if len(nonce_bytes) != NONCE_SIZE:
+        raise ContainerError("container nonce must be exactly 12 bytes")
+    if len(encrypted) < TAG_SIZE:
+        raise ContainerError("container ciphertext is shorter than the GCM tag")
+    return _prefix(header_json) + nonce_bytes + encrypted
+
+
+def parse_container(data: BytesLike) -> ParsedContainer:
+    """Parse and validate the unencrypted structure of a container."""
+
+    blob = _as_bytes(data, name="data")
+    minimum = _PREFIX_SIZE + 2 + NONCE_SIZE + TAG_SIZE
+    if len(blob) < minimum:
+        raise ContainerError("container is truncated")
+    if blob[: len(MAGIC)] != MAGIC:
+        raise ContainerError("invalid container magic")
+
+    header_length = _LENGTH.unpack_from(blob, len(MAGIC))[0]
+    if header_length == 0:
+        raise ContainerError("container header must not be empty")
+    if header_length > _MAX_HEADER_SIZE:
+        raise ContainerError("container header is too large")
+
+    header_start = _PREFIX_SIZE
+    header_end = header_start + header_length
+    payload_start = header_end + NONCE_SIZE
+    if payload_start + TAG_SIZE > len(blob):
+        raise ContainerError("container is truncated")
+
+    header_json = blob[header_start:header_end]
+    try:
+        decoded = json.loads(header_json.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ContainerError("container header is not valid UTF-8 JSON") from exc
+    if not isinstance(decoded, dict):
+        raise ContainerError("container header must be a JSON object")
+    header = validate_header(decoded)
+    if canonical_header_bytes(header) != header_json:
+        raise ContainerError("container header JSON is not canonical")
+
+    return ParsedContainer(
+        header=header,
+        nonce=blob[header_end:payload_start],
+        ciphertext=blob[payload_start:],
+        associated_data=header_json,
+    )
+
+
+def pack(
+    payload: BytesLike,
+    header: Mapping[str, Any],
+    master_key: BytesLike,
+    *,
+    nonce: BytesLike | None = None,
+    compression_level: int = 9,
+) -> bytes:
+    """Compress, encrypt, and pack one marshalled module payload."""
+
+    plaintext = _as_bytes(payload, name="payload")
+    normalized = validate_header(header)
+    if not isinstance(compression_level, int) or not -1 <= compression_level <= 9:
+        raise ContainerError("zlib compression_level must be between -1 and 9")
+
+    header_json = canonical_header_bytes(normalized)
+    prefix = _prefix(header_json)
+    key = derive_module_key(
+        master_key,
+        normalized["build_id"],
+        normalized["module"],
+    )
+    compressed = zlib.compress(plaintext, level=compression_level)
+    encrypted = encrypt_payload(
+        compressed,
+        key,
+        aad=header_json,
+        nonce=nonce,
+    )
+    return prefix + encrypted.nonce + encrypted.ciphertext
+
+
+def unpack(data: BytesLike, master_key: BytesLike) -> UnpackedModule:
+    """Authenticate, decrypt, and decompress one module container."""
+
+    parsed = parse_container(data)
+    key = derive_module_key(
+        master_key,
+        parsed.header["build_id"],
+        parsed.header["module"],
+    )
+    compressed = decrypt_payload(
+        parsed.ciphertext,
+        key,
+        parsed.nonce,
+        aad=parsed.associated_data,
+    )
+    try:
+        payload = zlib.decompress(compressed)
+    except zlib.error as exc:
+        raise ContainerError("authenticated payload is not valid zlib data") from exc
+    return UnpackedModule(parsed.header, payload)
+
+
+# Explicit names make call sites self-documenting while the concise aliases are
+# convenient for users of this module directly.
+pack_module = pack
+unpack_module = unpack
+
+
+__all__ = [
+    "COMPRESSION",
+    "FORMAT_VERSION",
+    "MAGIC",
+    "ModuleHeader",
+    "ParsedContainer",
+    "UnpackedModule",
+    "assemble_container",
+    "canonical_header_bytes",
+    "canonical_json_bytes",
+    "pack",
+    "pack_module",
+    "parse_container",
+    "unpack",
+    "unpack_module",
+    "validate_header",
+]