kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/macos/runtime_stage.py

@@ -0,0 +1,110 @@
+"""Acquire + normalize the bundled CPython runtime for the ``.app``.
+
+Consumes the provider-agnostic runtime pin from ``pylock.macos.toml`` (per-arch
+URL + SHA-256), fetches + verifies the arm64 archive, extracts it, and produces
+the **canonical relocatable CPython tree**. Nothing downstream (launcher,
+bundler, signing) knows or cares which provider produced it — the whole point of
+the runtime-provider seam.
+
+macOS is arm64-only, so there is no second arch and no ``lipo`` merge: the
+extracted tree ships as-is.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tarfile
+import tempfile
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+from kivyforge.lock.wheelruntime.model import PythonRuntime
+from kivyforge.lock.wheelruntime.runtime import (
+    RuntimeProviderError,
+    normalized_runtime_root,
+)
+
+from . import AppBundleError
+
+
+def stage_runtime(
+    runtime: PythonRuntime,
+    arch: str,
+    home: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> Path:
+    """Materialize the runtime for *arch* at *home*; return *home*.
+
+    *home* is the final CPython home directory (whose ``bin/python3`` the
+    launcher execs). It is emptied and recreated. Deliberately placed under the
+    bundle's ``Resources/`` (not ``Frameworks/``): a unix-prefix Python tree
+    under ``Frameworks/`` trips ``codesign``'s framework auto-discovery on
+    non-framework subdirs (e.g. ``lib/tk*``), whereas ``Resources`` content is
+    sealed as data and the Mach-O files are signed individually.
+    """
+    cache = cache or ArtifactCache()
+
+    tmp = Path(tempfile.mkdtemp(prefix="kivy-runtime-"))
+    try:
+        artifact = runtime.artifact_for(arch)
+        if artifact is None:
+            raise AppBundleError(
+                f"the lock has no {arch} runtime artifact; re-run "
+                f"`kivyforge lock -p macos` (locked archs: "
+                f"{', '.join(a.arch for a in runtime.artifacts)})."
+            )
+        archive = _fetch(artifact, arch, project_root, cache, no_cache)
+        extracted = _extract(archive, tmp / arch, runtime.provider)
+
+        if home.exists():
+            shutil.rmtree(home)
+        home.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(extracted, home, symlinks=True)
+        return home
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _fetch(artifact, arch, project_root, cache, no_cache) -> Path:
+    filename = artifact.url.rsplit("/", 1)[-1] or f"python-{arch}.tar.gz"
+    try:
+        return fetch_artifact(
+            name=f"python runtime ({arch})",
+            sha256=artifact.sha256,
+            filename=filename,
+            url=artifact.url,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except DownloadError as exc:
+        raise AppBundleError(str(exc)) from exc
+
+
+def _extract(archive: Path, into: Path, provider: str) -> Path:
+    into.mkdir(parents=True, exist_ok=True)
+    try:
+        with tarfile.open(archive, "r:*") as tf:
+            _safe_extractall(tf, into)
+    except (tarfile.TarError, OSError) as exc:
+        raise AppBundleError(f"failed to extract {archive.name}: {exc}") from exc
+    try:
+        return normalized_runtime_root(provider, into)
+    except RuntimeProviderError as exc:
+        raise AppBundleError(f"{archive.name}: {exc}") from exc
+
+
+def _safe_extractall(tf: tarfile.TarFile, into: Path) -> None:
+    """Extract, rejecting members that would escape *into* (path traversal)."""
+    base = into.resolve()
+    for member in tf.getmembers():
+        target = (into / member.name).resolve()
+        if not (target == base or base in target.parents):
+            raise AppBundleError(f"unsafe path in archive: {member.name!r}")
+    # Paths are validated above; fully_trusted preserves the runtime's
+    # permissions and symlinks (the restrictive filters would rewrite them).
+    tf.extractall(into, filter="fully_trusted")  # noqa: S202 — members validated just above

kivyforge/platforms/macos/signing.py

@@ -0,0 +1,78 @@
+"""Code signing of the assembled ``.app`` (macos-spec).
+
+Two tiers, both **inside-out** — every nested Mach-O (the runtime's
+``python3``/``libpython``/``.dylib`` and the wheels' ``.so`` extensions) is
+signed first, deepest first, then the ``.app`` bundle last — because signing
+the bundle seals a hash of its already-signed contents:
+
+- **Ad-hoc** (``codesign --sign -``): the mandatory Apple-Silicon floor (the
+  kernel refuses to run unsigned arm64 Mach-O). Integrity only, no trust.
+- **Developer ID** (``--sign <identity> --options runtime --timestamp``): the
+  distribution tier. Hardened Runtime + a secure timestamp are notarization
+  requirements; the main executable additionally carries entitlements that a
+  hardened Python bundle needs (see ``DEFAULT_HARDENED_ENTITLEMENTS``).
+"""
+
+from __future__ import annotations
+
+import plistlib
+import tempfile
+from pathlib import Path
+
+from .machotools import codesign_adhoc, codesign_identity, is_macho
+
+# Hardened-Runtime entitlements a bundled CPython app needs by default:
+# - allow-unsigned-executable-memory: ctypes/cffi trampolines allocate W+X
+#   pages, which the Hardened Runtime otherwise forbids.
+# - disable-library-validation: the app loads wheel `.so`/`.dylib` binaries
+#   signed by other teams (or re-signed here); library validation would
+#   require every image to share the app's team ID.
+# Users may override either (or add more) via [tool.kivy.macos.entitlements].
+DEFAULT_HARDENED_ENTITLEMENTS: dict[str, object] = {
+    "com.apple.security.cs.allow-unsigned-executable-memory": True,
+    "com.apple.security.cs.disable-library-validation": True,
+}
+
+
+def sign_bundle_adhoc(app: Path) -> int:
+    """Ad-hoc sign every Mach-O in *app*, then *app* itself; return the count.
+
+    Returns the number of ``codesign`` invocations (nested binaries + the bundle),
+    which callers use for a one-line progress message.
+    """
+    machos = _machos_inside_out(app)
+    for macho in machos:
+        codesign_adhoc(macho)
+    codesign_adhoc(app)
+    return len(machos) + 1
+
+
+def sign_bundle_developer_id(
+    app: Path,
+    identity: str,
+    *,
+    extra_entitlements: dict[str, object] | None = None,
+) -> int:
+    """Developer ID deep-sign *app* for distribution; return the codesign count.
+
+    Nested Mach-O binaries get Hardened Runtime + timestamp; the ``.app`` seal
+    (which signs the main executable) additionally carries the merged
+    entitlements (defaults + ``[tool.kivy.macos.entitlements]``, user wins).
+    """
+    entitlements = {**DEFAULT_HARDENED_ENTITLEMENTS, **(extra_entitlements or {})}
+    machos = _machos_inside_out(app)
+    with tempfile.TemporaryDirectory(prefix="kivyforge-ent-") as tmp:
+        ent_file = Path(tmp) / "entitlements.plist"
+        with ent_file.open("wb") as fh:
+            plistlib.dump(entitlements, fh)
+        for macho in machos:
+            codesign_identity(macho, identity)
+        codesign_identity(app, identity, entitlements=ent_file)
+    return len(machos) + 1
+
+
+def _machos_inside_out(app: Path) -> list[Path]:
+    """Every Mach-O under *app*, deepest paths first (containers sign last)."""
+    machos = [p for p in app.rglob("*") if is_macho(p)]
+    machos.sort(key=lambda p: len(p.parts), reverse=True)
+    return machos

kivyforge/platforms/macos/wheels_stage.py

@@ -0,0 +1,108 @@
+"""Install the locked wheels into the ``.app``'s ``lib/`` (site-packages).
+
+Wheels are fetched + SHA-256-verified from ``pylock.macos.toml`` (URL or vendored
+path) and unpacked directly — no pip, so the bundler is independent of the host
+interpreter's version/arch.
+
+macOS builds are arm64-only, so exactly one wheel is unpacked per package and
+there is no ``lipo`` merge. A ``universal2`` wheel is still perfectly valid — it
+*contains* arm64 — which is why the arch match accepts it alongside a thin
+``arm64`` wheel and a pure-Python one.
+"""
+
+from __future__ import annotations
+
+import shutil
+import zipfile
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+from kivyforge.lock.model import LockedPackage, LockedWheel
+
+from . import AppBundleError
+from .lock import wheel_arch
+
+
+def stage_wheels(
+    packages: tuple[LockedPackage, ...],
+    arch: str,
+    lib_dir: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> None:
+    """Unpack every package's wheel for *arch* into *lib_dir*."""
+    cache = cache or ArtifactCache()
+    if lib_dir.exists():
+        shutil.rmtree(lib_dir)
+    lib_dir.mkdir(parents=True)
+
+    for pkg in packages:
+        wheel = _select_wheel(pkg, arch)
+        _unpack(_fetch(wheel, project_root, cache, no_cache), lib_dir)
+
+
+def _select_wheel(pkg: LockedPackage, arch: str) -> LockedWheel:
+    """The one wheel to unpack for *arch*.
+
+    Pure-Python and ``universal2`` wheels both satisfy an arm64 build — the
+    latter *contains* arm64 — as does a thin ``arm64`` wheel.
+    """
+    for wheel in pkg.wheels:
+        if wheel.is_pure_python:
+            return wheel
+        if wheel_arch(wheel.platform_tag) in ("universal2", arch):
+            return wheel
+    raise AppBundleError(
+        f"{pkg.name} {pkg.version} has no {arch} wheel in the lock.\n"
+        f"  Re-run `kivyforge lock -p macos`."
+    )
+
+
+def _fetch(wheel: LockedWheel, project_root, cache, no_cache) -> Path:
+    try:
+        return fetch_artifact(
+            name=wheel.name,
+            sha256=wheel.sha256,
+            filename=wheel.name,
+            url=wheel.url,
+            path=wheel.path,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except DownloadError as exc:
+        raise AppBundleError(str(exc)) from exc
+
+
+def _unpack(wheel: Path, target: Path) -> None:
+    """Extract a wheel into *target*, normalizing ``.data/{purelib,platlib}``."""
+    with zipfile.ZipFile(wheel) as zf:
+        _safe_extract(zf, target)
+    for data_dir in list(target.glob("*.data")):
+        for sub in ("purelib", "platlib"):
+            src = data_dir / sub
+            if src.is_dir():
+                _merge_tree(src, target)
+        shutil.rmtree(data_dir, ignore_errors=True)
+
+
+def _merge_tree(src: Path, dest: Path) -> None:
+    for item in src.iterdir():
+        target = dest / item.name
+        if item.is_dir():
+            target.mkdir(exist_ok=True)
+            _merge_tree(item, target)
+        else:
+            shutil.copy2(item, target)
+
+
+def _safe_extract(zf: zipfile.ZipFile, target: Path) -> None:
+    base = target.resolve()
+    for member in zf.namelist():
+        resolved = (target / member).resolve()
+        if not (resolved == base or base in resolved.parents):
+            raise AppBundleError(f"unsafe path in wheel: {member!r}")
+    zf.extractall(target)  # noqa: S202 — members validated just above

kivyforge/platforms/windows/__init__.py

@@ -0,0 +1,133 @@
+"""Windows platform backend (windows-spec).
+
+Produces a run-from-folder ``onedir`` bundle: a prebuilt windowed-subsystem
+launcher ``.exe`` beside a whole python-build-standalone prefix, the app source,
+a generated bootstrap, and the declared native-binaries channel. Windows is the
+host default on Windows, so a Windows box with ``[tool.kivy.windows]`` configured
+resolves to this backend without ``-p``. It requires a Windows host: the bundled
+runtime is an MSVC amd64 build and the resource/signing tools are Windows-only.
+"""
+
+from __future__ import annotations
+
+import platform as _platform
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..base import HostCapabilityError, Platform
+
+if TYPE_CHECKING:
+    from kivyforge.doctor.result import CheckResult
+
+
+class WindowsBundleError(Exception):
+    """A Windows onedir bundling failure surfaced with an actionable message."""
+
+
+class WindowsPlatform(Platform):
+    name = "windows"
+    aliases = ("win",)
+    # Windows is a desktop target built on its own OS, so Windows maps to it as
+    # the host default (resolution-chain step 3).
+    host_system = "Windows"
+    # The onedir folder is both the dev-run target and the shipped distributable;
+    # installers stay permanently external (windows-spec). Folder is the only
+    # package format.
+    package_formats = ("folder",)
+
+    def check_host_capability(self, *, host_system: str | None = None) -> None:
+        # arm64: keep gating on the OS only, never the host CPU. Building an
+        # arm64 onedir needs no build-time compilation (runtime + wheels are
+        # fetched per target arch, the launcher is prebuilt/vendored, rcedit is
+        # emulated), so cross-arch builds are the intended model: an x64 Windows
+        # host should cross-build arm64 bundles (and vice versa) with no arm64
+        # hardware. The only host-CPU coupling is the msvcp140.dll System32
+        # fallback, which arm64 removes by pinning msvcp140.dll as an artifact
+        # (see runtime_stage.py). Do NOT add a host==target check. arm64-windows.md §7.
+        host = host_system if host_system is not None else _platform.system()
+        if host != "Windows":
+            raise HostCapabilityError(
+                "building for Windows requires a Windows host; "
+                f"this host is {host!r}.\n"
+                "  The onedir bundle stages an MSVC amd64 python-build-standalone "
+                "runtime and uses Windows-only tools (rcedit, signtool).\n"
+                "  Run `kivyforge doctor -p windows` on a Windows box to check "
+                "the setup."
+            )
+
+    def build(
+        self,
+        project_root: Path,
+        *,
+        target: str | None,
+        arch: str | None,
+        no_verify_lock: bool,
+        no_cache: bool,
+        team_id: str | None,
+        signing_identity: str | None,
+        export_method: str,
+        debug: bool = False,
+        fmt: str | None = None,
+        abi: str | None = None,
+    ) -> None:
+        self.reject_ios_only_target(target)
+        from .cli import windows_build
+
+        windows_build(
+            project_root,
+            arch=arch,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+        )
+
+    def run(
+        self,
+        project_root: Path,
+        *,
+        target: str,
+        arch: str | None,
+        destination: str | None,
+        no_build: bool,
+    ) -> None:
+        from .cli import windows_run
+
+        windows_run(project_root, arch=arch, no_build=no_build)
+
+    def package(
+        self,
+        project_root: Path,
+        *,
+        fmt: str,
+        arch: str | None,
+        team_id: str | None,
+        signing_identity: str | None,
+        export_method: str,
+        notarize: bool | None,
+        notary_profile: str | None,
+        no_verify_lock: bool,
+        no_cache: bool,
+        abi: str | None = None,
+        keystore: str | None = None,
+        key_alias: str | None = None,
+    ) -> None:
+        from .cli import windows_package
+
+        windows_package(
+            project_root,
+            fmt=fmt,
+            arch=arch,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+        )
+
+    def status(self, project_root: Path) -> None:
+        from .cli import windows_status
+
+        windows_status(project_root)
+
+    def doctor(
+        self, cwd: Path, *, kivyforge_version: str, offline: bool
+    ) -> list[CheckResult]:
+        from .doctor import windows_doctor
+
+        return windows_doctor(cwd, kivyforge_version=kivyforge_version, offline=offline)

kivyforge/platforms/windows/assets.py

@@ -0,0 +1,76 @@
+"""Access + integrity-check the vendored Windows binaries (windows-spec).
+
+The onedir bundler consumes two prebuilt binaries shipped inside the package:
+the launcher (``launcher-amd64.exe``) and the resource-patch tool
+(``rcedit-x64.exe``). This module locates them and verifies each against the
+SHA-256 pinned in ``vendor/SHA256SUMS`` before use, so a corrupted or
+tampered-with vendored asset fails loudly instead of ending up in a shipped app.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from . import WindowsBundleError
+
+VENDOR_DIR = Path(__file__).resolve().parent / "vendor"
+MANIFEST = VENDOR_DIR / "SHA256SUMS"
+LAUNCHER_NAME = "launcher-amd64.exe"
+RCEDIT_NAME = "rcedit-x64.exe"
+
+
+def read_manifest() -> dict[str, str]:
+    """Parse ``vendor/SHA256SUMS`` into ``{filename: sha256}``."""
+    if not MANIFEST.is_file():
+        raise WindowsBundleError(
+            f"vendored-binary manifest missing: {MANIFEST}. The kivyforge "
+            "install is incomplete."
+        )
+    entries: dict[str, str] = {}
+    for line in MANIFEST.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        digest, _, name = line.partition("  ")
+        if digest and name:
+            entries[name.strip()] = digest.strip()
+    return entries
+
+
+def _verified_asset(name: str, *, human: str) -> Path:
+    path = VENDOR_DIR / name
+    if not path.is_file():
+        raise WindowsBundleError(
+            f"the vendored {human} ({name}) is missing from the kivyforge "
+            f"install at {path}.\n"
+            "  It is built/fetched in CI; a source checkout may need "
+            "`python -m kivyforge.platforms.windows.launcher.build_launcher build` "
+            "(launcher) or "
+            "`python -m kivyforge.platforms.windows.vendor.fetch_rcedit` (rcedit)."
+        )
+    expected = read_manifest().get(name)
+    if not expected:
+        raise WindowsBundleError(
+            f"the vendored {human} ({name}) has no pinned SHA-256 in {MANIFEST}."
+        )
+    actual = hashlib.sha256(path.read_bytes()).hexdigest()
+    if actual != expected:
+        raise WindowsBundleError(
+            f"the vendored {human} ({name}) failed its integrity check:\n"
+            f"  expected sha256 {expected}\n  actual   sha256 {actual}\n"
+            "  Refuse to ship a tampered/corrupted binary; re-vendor it."
+        )
+    return path
+
+
+def vendored_launcher() -> Path:
+    """The verified prebuilt launcher (``launcher-amd64.exe``)."""
+    # arm64: take a target-arch argument and select launcher-<arch>.exe (rcedit
+    # stays x64 — it is emulated and only edits resources). See arm64-windows.md §5.
+    return _verified_asset(LAUNCHER_NAME, human="launcher")
+
+
+def vendored_rcedit() -> Path:
+    """The verified prebuilt resource editor (``rcedit-x64.exe``)."""
+    return _verified_asset(RCEDIT_NAME, human="rcedit resource editor")