pyobfus-runtime 0.1.0__py3-none-any.whl

pyobfus_runtime/opacity.py

@@ -0,0 +1,210 @@
+"""Runtime support for P2-1 Selective Opacity L3 lazy materialization.
+
+The build-pass transformer (W3-B, separate commit) replaces the body of an
+``@opacity("encrypted")`` function with a stub and emits two module-level
+constants:
+
+    _CIPHER_<funcname> = b"<nonce(12) || ciphertext+tag>"
+    _LAYER_KEY = b"<32-byte-AES-256-key>"
+
+    @_l3_dispatch(_CIPHER_<funcname>, _LAYER_KEY)
+    def <funcname>(...):
+        pass  # body replaced at first call by the decrypted CodeType
+
+At first call to the wrapper, ``_l3_dispatch`` decrypts the cipher blob,
+``marshal.loads`` the plaintext into a ``CodeType``, and patches the stub's
+``__code__`` so that subsequent calls execute the real bytecode directly.
+
+The cached state ("did we decrypt yet?" + the decrypted ``CodeType``) lives
+in a **closure cell**, not as an attribute on either the wrapper or the
+stub, mirroring the hardening pattern in ``seal.py``: an attacker cannot
+pre-set ``stub._loaded = True`` to bypass decryption, because there is no
+``_loaded`` attribute -- the boolean only exists in the closure.
+
+**At-rest property** (the load-bearing patent claim):
+
+    Plaintext bytecode never exists in the build artifact and never exists
+    in the imported module before the first call. An attacker dumping
+    ``marshal.dumps(<imported_module>.critical.__code__)`` immediately
+    after import gets the *stub*'s code, not the protected function's
+    code. The protected code only materializes inside the closure cell,
+    only after the first call, only for the lifetime of the process.
+
+W3-A scope (this module): the runtime side. The build-tool helper
+``_encrypt_code`` is also in this module so the build pass and the
+runtime share a single encryption rule. Build-pass AST transformer is
+W3-B.
+
+Patent-gated. See PATENT_NOTES.md and docs/P2-1_DESIGN.md.
+"""
+
+from __future__ import annotations
+
+import functools
+import marshal
+import secrets
+import types
+from typing import Callable, TypeVar, cast
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+_F = TypeVar("_F", bound=Callable)
+
+_NONCE_SIZE = 12  # AES-GCM standard
+_KEY_SIZE = 32  # 256-bit AES key
+_TAG_SIZE = 16  # AES-GCM authentication tag
+_MIN_CIPHER_LEN = _NONCE_SIZE + _TAG_SIZE  # nonce + (zero-length-ct) + tag
+
+
+class OpacityRuntimeError(RuntimeError):
+    """Raised when L3 lazy materialization fails.
+
+    Possible causes (all surface uniformly to avoid leaking which one
+    triggered, in line with the failure-mode discipline established for
+    P2-10 and P2-11):
+
+      - wrong layer key (GCM tag mismatch)
+      - tampered cipher blob (GCM tag mismatch)
+      - truncated cipher blob (length check)
+      - corrupted plaintext (marshal.loads failure)
+      - unexpected payload type (decrypted to non-CodeType)
+    """
+
+
+def _encrypt_code(code: types.CodeType, key: bytes | bytearray) -> bytes:
+    """Build-time helper: encrypt a CodeType for L3 lazy materialization.
+
+    The build pass calls this once per L3-decorated function and embeds the
+    return value as ``_CIPHER_<funcname> = b"..."`` in the emitted module.
+
+    Args:
+        code: The compiled CodeType of the function being protected. Must
+            be a CodeType, not a function or lambda; callers should pass
+            ``func.__code__``.
+        key: 32-byte AES-256 key. The build pass either generates this
+            randomly per build (default) or derives it from a license /
+            device fingerprint (combination with P2-8 ``--bind-device``).
+
+    Returns:
+        ``nonce(12 bytes) || ciphertext_with_tag`` -- a single bytes object
+        ready to be embedded as a module constant.
+
+    Raises:
+        TypeError: if ``code`` is not a CodeType.
+        ValueError: if ``key`` is not exactly 32 bytes.
+
+    Note: nonce is generated with ``secrets.token_bytes`` (CSPRNG) per the
+    workspace ENGINEERING_BASELINE Tier 2 rule. Each call produces a unique
+    blob even for the same code + same key.
+    """
+    if not isinstance(code, types.CodeType):
+        raise TypeError(f"_encrypt_code expects a CodeType, got {type(code).__name__}")
+    if not isinstance(key, (bytes, bytearray)) or len(key) != _KEY_SIZE:
+        raise ValueError(
+            f"key must be exactly {_KEY_SIZE} bytes, got "
+            f"{len(key) if isinstance(key, (bytes, bytearray)) else type(key).__name__}"
+        )
+
+    plaintext = marshal.dumps(code)
+    nonce = secrets.token_bytes(_NONCE_SIZE)
+    aesgcm = AESGCM(bytes(key))
+    ciphertext_with_tag = cast(bytes, aesgcm.encrypt(nonce, plaintext, associated_data=None))
+    return nonce + ciphertext_with_tag
+
+
+def _decrypt_code(cipher: bytes | bytearray, key: bytes | bytearray) -> types.CodeType:
+    """Reverse of ``_encrypt_code``: cipher blob + key -> CodeType.
+
+    All failure modes raise ``OpacityRuntimeError`` with a generic message
+    so an attacker probing with crafted ciphers cannot distinguish "wrong
+    key" from "tampered blob" from "corrupted marshal" via the exception
+    type or message text.
+    """
+    if not isinstance(key, (bytes, bytearray)) or len(key) != _KEY_SIZE:
+        raise OpacityRuntimeError("L3 decryption failed: invalid key size")
+    if not isinstance(cipher, (bytes, bytearray)) or len(cipher) < _MIN_CIPHER_LEN:
+        raise OpacityRuntimeError("L3 decryption failed: cipher blob too short")
+
+    nonce = bytes(cipher[:_NONCE_SIZE])
+    ciphertext_with_tag = bytes(cipher[_NONCE_SIZE:])
+
+    aesgcm = AESGCM(bytes(key))
+    try:
+        plaintext = aesgcm.decrypt(nonce, ciphertext_with_tag, associated_data=None)
+    except InvalidTag as exc:
+        raise OpacityRuntimeError(
+            "L3 decryption failed (key mismatch or tampered ciphertext)"
+        ) from exc
+
+    try:
+        # S302: marshal.loads on attacker-controlled bytes is dangerous.
+        # Here the bytes are NOT attacker-controlled: AESGCM.decrypt()
+        # above raises InvalidTag on any modification or wrong key, so
+        # `plaintext` is provably what we encrypted at build time. The
+        # marshal payload's integrity is bound to the GCM tag, not its
+        # own structure.
+        code = marshal.loads(plaintext)  # noqa: S302
+    except Exception as exc:  # noqa: BLE001 -- marshal raises ValueError/EOFError/TypeError
+        raise OpacityRuntimeError("L3 decryption failed: corrupted payload") from exc
+
+    if not isinstance(code, types.CodeType):
+        raise OpacityRuntimeError(
+            f"L3 decryption failed: payload is {type(code).__name__}, expected CodeType"
+        )
+
+    return code
+
+
+def _l3_dispatch(cipher: bytes | bytearray, key: bytes | bytearray) -> Callable[[_F], _F]:
+    """Wrap an L3 stub function with first-call decrypt + ``__code__`` patch.
+
+    The build pass emits::
+
+        _CIPHER_critical = b"..."
+
+        @_l3_dispatch(_CIPHER_critical, _LAYER_KEY)
+        def critical(x):
+            pass  # discarded at first call
+
+    On the first call to ``critical``, the wrapper:
+
+      1. Calls ``_decrypt_code(cipher, key)`` -> CodeType
+      2. Sets ``stub.__code__ = decrypted_code`` so the stub's body is now
+         the protected function's body
+      3. Marks the closure-cell ``loaded`` flag True so subsequent calls
+         skip step 1-2
+
+    On subsequent calls, the wrapper does a single boolean check then
+    delegates to the patched stub.
+
+    The decrypted CodeType is held in a closure cell (not a function
+    attribute) so an attacker cannot pre-set
+    ``critical._loaded = True`` to skip the integrity-bound decryption.
+
+    Args:
+        cipher: ``nonce || ciphertext_with_tag`` produced by
+            ``_encrypt_code`` at build time.
+        key: 32-byte AES-256 key matching the one used at build time.
+
+    Returns:
+        A decorator that takes a stub function and returns the dispatch
+        wrapper.
+    """
+
+    def decorator(stub: _F) -> _F:
+        loaded = False
+        cached_code: types.CodeType | None = None  # noqa: F841 -- closure-held debug handle
+
+        @functools.wraps(stub)
+        def wrapper(*args, **kwargs):
+            nonlocal loaded, cached_code
+            if not loaded:
+                cached_code = _decrypt_code(cipher, key)
+                stub.__code__ = cached_code
+                loaded = True
+            return stub(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

pyobfus_runtime/policy.py

@@ -0,0 +1,108 @@
+"""Runtime platform-policy guard (P2-16).
+
+Generalizes PyArmor BCC's platform-restriction mode in pure Python: refuse
+to import an obfuscated module unless the running environment satisfies
+build-time-baked constraints on OS, minimum Python version, and/or CPU
+architecture (e.g. "this build is licensed for Linux production only").
+
+Follows the same module-top-guard-call shape as :func:`expire_check` /
+:func:`period_check` in :mod:`pyobfus_pro.license_binding` — a plain
+function call the build orchestrator injects at the top of the emitted
+module, raising a distinct error class on mismatch so the failure surfaces
+in the normal exception path rather than as a cryptic import error.
+
+Not part of the patent-gated P2-1/7/8/9/10/11 combination claims — this is
+a standalone environment check with no cryptographic binding, so unlike
+``--bind-device`` it does not affect ciphertext keys.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+from typing import Optional, Sequence, Tuple
+
+
+class RuntimePolicyError(RuntimeError):
+    """Raised when the running environment violates a build-time runtime policy.
+
+    Distinct from :class:`pyobfus_pro.license_binding.LicenseExpired` — this
+    is an environment mismatch (wrong OS / Python version / architecture),
+    not a time- or count-based license expiry.
+    """
+
+
+def _parse_python_min(python_min: str) -> Tuple[int, int]:
+    """Parse an ``"X.Y"`` minimum-Python-version string into a comparable tuple."""
+    parts = python_min.split(".")
+    if len(parts) < 2 or not all(p.isdigit() for p in parts[:2]):
+        raise RuntimePolicyError(
+            f"requires_runtime: python_min must be 'X.Y' (e.g. '3.10'), got {python_min!r}"
+        )
+    return (int(parts[0]), int(parts[1]))
+
+
+def requires_runtime(
+    os_allowed: Optional[Sequence[str]] = None,
+    python_min: Optional[str] = None,
+    arch_allowed: Optional[Sequence[str]] = None,
+    *,
+    current_os: Optional[str] = None,
+    current_python: Optional[Tuple[int, int]] = None,
+    current_arch: Optional[str] = None,
+) -> None:
+    """Enforce build-time platform constraints at import time.
+
+    Args:
+        os_allowed: Allowed :func:`platform.system` values (e.g.
+            ``("Linux", "Darwin")``). Case-insensitive. ``None``/empty means
+            no OS restriction.
+        python_min: Minimum required Python version as ``"X.Y"`` (e.g.
+            ``"3.10"``), compared against ``sys.version_info[:2]``. ``None``
+            means no minimum.
+        arch_allowed: Allowed :func:`platform.machine` values (e.g.
+            ``("x86_64", "arm64")``). Case-insensitive. Common aliases are
+            NOT normalized (``"x86_64"`` on Linux vs ``"AMD64"`` on Windows
+            are different strings) — list every alias your target platforms
+            actually report.
+        current_os: Override for :func:`platform.system` — testing aid;
+            production calls leave this ``None`` and use the real value.
+        current_python: Override for ``sys.version_info[:2]`` — testing aid;
+            production calls leave this ``None``.
+        current_arch: Override for :func:`platform.machine` — testing aid;
+            production calls leave this ``None``.
+
+    Raises:
+        RuntimePolicyError: if any supplied constraint is violated, or if
+            ``python_min`` is not a valid ``"X.Y"`` string.
+    """
+    if os_allowed:
+        resolved_os = current_os if current_os is not None else platform.system()
+        allowed_lower = {o.lower() for o in os_allowed}
+        if resolved_os.lower() not in allowed_lower:
+            raise RuntimePolicyError(
+                f"This build requires one of {tuple(os_allowed)!r}, "
+                f"but the current OS is {resolved_os!r}."
+            )
+
+    if python_min:
+        min_version = _parse_python_min(python_min)
+        resolved_version = current_python if current_python is not None else sys.version_info[:2]
+        if resolved_version < min_version:
+            raise RuntimePolicyError(
+                f"This build requires Python >= {python_min}, "
+                f"but the running interpreter is "
+                f"{resolved_version[0]}.{resolved_version[1]}."
+            )
+
+    if arch_allowed:
+        resolved_arch = current_arch if current_arch is not None else platform.machine()
+        allowed_lower = {a.lower() for a in arch_allowed}
+        if resolved_arch.lower() not in allowed_lower:
+            raise RuntimePolicyError(
+                f"This build requires one of {tuple(arch_allowed)!r}, "
+                f"but the current architecture is {resolved_arch!r}."
+            )
+
+
+__all__ = ["RuntimePolicyError", "requires_runtime"]

pyobfus_runtime/scrub.py

@@ -0,0 +1,227 @@
+"""Production-side traceback scrubbing for --scrub-traceback.
+
+When installed as ``sys.excepthook``, an unhandled exception in production
+code no longer prints the traceback to stderr. Instead, the traceback is
+serialized, encrypted asymmetrically with a build-time-baked public key,
+and emitted as an opaque error identifier of the form::
+
+    PYOBFUS-ERR:eyJhbGc...
+
+Customers report this identifier; the developer who has the corresponding
+private key reverses it back to the original traceback via
+:func:`unscrub_error_id`.
+
+This is the inverse of pyobfus Core's ``unmap`` flow (which deobfuscates a
+customer-visible traceback). ``unmap`` assumes the customer sends a trace
+that contains obfuscated names; ``scrub`` removes the assumption that the
+customer sees a trace at all.
+
+Encryption: hybrid asymmetric. RSA-2048-OAEP wraps a per-error random
+AES-256-GCM key; the AES key encrypts the traceback payload. This bounds
+RSA work to one short blob per error regardless of payload size, while the
+asymmetric envelope ensures the customer cannot decrypt errors emitted on
+their own machine.
+
+Patent-gated. See PATENT_NOTES.md and docs/P2-10_DESIGN.md.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import sys
+import traceback as _traceback
+from typing import cast
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+_NONCE_SIZE = 12  # AES-GCM standard
+_AES_KEY_SIZE = 32  # 256-bit
+_KEY_LENGTH_BYTES = 2  # length-prefix for the RSA-encrypted AES key (uint16)
+_DEFAULT_PREFIX = "PYOBFUS-ERR"
+_MIN_BLOB_LEN = _NONCE_SIZE + _KEY_LENGTH_BYTES
+
+
+class ScrubError(RuntimeError):
+    """Raised when scrubbing or unscrubbing fails (corrupt input, wrong key)."""
+
+
+def generate_keypair(*, key_size: int = 2048) -> tuple[bytes, bytes]:
+    """Generate a fresh RSA keypair for scrub/unscrub.
+
+    Args:
+        key_size: RSA modulus size. 2048 for production (default); smaller
+            sizes acceptable only for testing.
+
+    Returns:
+        ``(private_pem, public_pem)`` -- PEM-serialized PKCS#8 private key
+        and SubjectPublicKeyInfo public key. Bytes, not strings.
+    """
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=key_size)
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return private_pem, public_pem
+
+
+def _scrub_payload(payload: bytes, public_key_pem: bytes) -> str:
+    """Hybrid-encrypt ``payload`` to a URL-safe base64 string.
+
+    Blob format inside the b64::
+
+        nonce(12) | enc_key_len(2 BE) | enc_key | ciphertext
+    """
+    public_key = serialization.load_pem_public_key(public_key_pem)
+    if not isinstance(public_key, rsa.RSAPublicKey):
+        raise ScrubError("public_key_pem must be an RSA public key")
+
+    aes_key = os.urandom(_AES_KEY_SIZE)
+    nonce = os.urandom(_NONCE_SIZE)
+
+    aesgcm = AESGCM(aes_key)
+    ciphertext = aesgcm.encrypt(nonce, payload, associated_data=None)
+
+    enc_key = public_key.encrypt(
+        aes_key,
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None,
+        ),
+    )
+
+    blob = nonce + len(enc_key).to_bytes(_KEY_LENGTH_BYTES, "big") + enc_key + ciphertext
+    return base64.urlsafe_b64encode(blob).decode("ascii")
+
+
+def _unscrub_payload(error_id: str, private_key_pem: bytes) -> bytes:
+    """Decrypt an error ID produced by :func:`_scrub_payload`."""
+    try:
+        blob = base64.urlsafe_b64decode(error_id.encode("ascii"))
+    except (ValueError, UnicodeEncodeError) as exc:
+        raise ScrubError(f"error_id is not valid base64: {exc}") from exc
+
+    if len(blob) < _MIN_BLOB_LEN:
+        raise ScrubError("error_id is too short to contain a valid blob")
+
+    nonce = blob[:_NONCE_SIZE]
+    enc_key_len = int.from_bytes(blob[_NONCE_SIZE : _NONCE_SIZE + _KEY_LENGTH_BYTES], "big")
+    enc_key_start = _NONCE_SIZE + _KEY_LENGTH_BYTES
+    enc_key_end = enc_key_start + enc_key_len
+    if enc_key_end > len(blob):
+        raise ScrubError("error_id length prefix overruns blob")
+    enc_key = blob[enc_key_start:enc_key_end]
+    ciphertext = blob[enc_key_end:]
+
+    private_key = serialization.load_pem_private_key(private_key_pem, password=None)
+    if not isinstance(private_key, rsa.RSAPrivateKey):
+        raise ScrubError("private_key_pem must be an RSA private key")
+
+    try:
+        aes_key = private_key.decrypt(
+            enc_key,
+            padding.OAEP(
+                mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                algorithm=hashes.SHA256(),
+                label=None,
+            ),
+        )
+    except ValueError as exc:
+        raise ScrubError(f"unable to decrypt AES key (wrong private key?): {exc}") from exc
+
+    try:
+        return cast(bytes, AESGCM(aes_key).decrypt(nonce, ciphertext, associated_data=None))
+    except InvalidTag as exc:
+        raise ScrubError(f"unable to decrypt payload (corrupted blob): {exc}") from exc
+
+
+def scrub_traceback_text(traceback_text: str, public_key_pem: bytes) -> str:
+    """Encrypt a traceback string into an opaque base64 error ID (no prefix).
+
+    Args:
+        traceback_text: The full traceback text to encrypt.
+        public_key_pem: The build-time-embedded RSA public key.
+    """
+    return _scrub_payload(traceback_text.encode("utf-8"), public_key_pem)
+
+
+def unscrub_error_id(
+    error_id: str,
+    private_key_pem: bytes,
+    *,
+    prefix: str | None = None,
+) -> str:
+    """Decrypt an error ID back to the original traceback text.
+
+    Args:
+        error_id: An ID emitted by :func:`install_scrub_excepthook`. Both
+            the bare base64 blob and the prefixed form
+            ``"<prefix>:<blob>"`` are accepted.
+        private_key_pem: The private key matched to the public key used at
+            scrub time.
+        prefix: If specified, only IDs with this prefix are accepted; an ID
+            without ``:`` is rejected when ``prefix`` is non-None.
+            If None (default), any prefix is accepted and stripped, or a
+            bare blob is accepted as-is.
+
+    Returns:
+        The original traceback text.
+
+    Raises:
+        ScrubError: if the ID is malformed, the prefix doesn't match, or
+            decryption fails.
+    """
+    if ":" in error_id:
+        observed_prefix, blob = error_id.split(":", 1)
+        if prefix is not None and observed_prefix != prefix:
+            raise ScrubError(f"prefix mismatch: expected {prefix!r}, got {observed_prefix!r}")
+        error_id = blob
+    elif prefix is not None:
+        raise ScrubError(f"error_id missing required prefix {prefix!r}:")
+
+    return _unscrub_payload(error_id, private_key_pem).decode("utf-8")
+
+
+def install_scrub_excepthook(
+    public_key_pem: bytes,
+    *,
+    prefix: str = _DEFAULT_PREFIX,
+) -> None:
+    """Replace ``sys.excepthook`` so unhandled exceptions print only an opaque ID.
+
+    The hook captures the unhandled exception's full traceback, hybrid-
+    encrypts it with the supplied public key, and writes
+    ``"<prefix>:<base64>"`` to stderr. The customer never sees the original
+    traceback; the developer (with the matching private key) recovers it
+    via :func:`unscrub_error_id`.
+
+    On internal failure (e.g., malformed key, encryption error), the hook
+    emits ``"<prefix>:SCRUB_FAILED"`` rather than falling back to the
+    default traceback display -- falling back would leak the very stack
+    details we are protecting.
+
+    Args:
+        public_key_pem: The build-time-embedded RSA public key.
+        prefix: Identifier prepended to the error ID. Customers reporting
+            the error see this prefix; it helps them identify which error
+            format they are looking at.
+    """
+
+    def hook(exc_type, exc_value, exc_traceback):
+        try:
+            tb_text = "".join(_traceback.format_exception(exc_type, exc_value, exc_traceback))
+            error_id = scrub_traceback_text(tb_text, public_key_pem)
+            print(f"{prefix}:{error_id}", file=sys.stderr)
+        except Exception:  # noqa: BLE001 -- production hook must never re-raise
+            print(f"{prefix}:SCRUB_FAILED", file=sys.stderr)
+
+    sys.excepthook = hook