kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/windows/signing.py

@@ -0,0 +1,168 @@
+r"""Authenticode signing hook for the Windows launcher (signing-windows).
+
+v1 ships kivyforge's own binaries and the default artifact **unsigned**, but the
+hook is first-class and optional from day one. Identity is always a
+certificate-store **thumbprint** in the configured ``store_scope`` — never a
+``.pfx`` path/password — so the same store ``signtool`` uses is the one the
+doctor certificate check inspects.
+
+Two backends behind a single :class:`Signer` protocol:
+
+* :class:`NullSigner` — the unconfigured default; leaves the artifact unsigned.
+* :class:`SigntoolSigner` — ``signtool sign /sha1 <thumbprint> /fd SHA256
+  /tr <timestamp_url> /td SHA256`` (adding ``/sm`` for ``store_scope=machine``),
+  always RFC-3161 timestamped.
+
+Signing runs on the ``dist/windows`` copy only, **after** the resource patch
+(a resource edit invalidates any signature) and **before** any external
+installer. Only the launcher ``.exe`` is signed; payload DLLs/``.pyd``s are
+**not** signed (not planned — onedir keeps it possible if ever needed).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from packaging.version import InvalidVersion, Version
+
+from . import WindowsBundleError
+
+# Windows version resources are four unsigned 16-bit integers.
+_U16_MAX = 0xFFFF
+
+# The fourth numeric field folds PEP 440 pre/post/dev into a single monotonic
+# 16-bit value so ordering is preserved: dev < alpha < beta < rc < final < post.
+# The string ProductVersion field always carries the full, human PEP 440 string.
+_PRE_TIER = {"a": 10000, "b": 20000, "rc": 30000}
+_FINAL_TIER = 40000
+_POST_TIER = 50000
+
+
+def _clamp(value: int, hi: int = _U16_MAX) -> int:
+    return max(0, min(value, hi))
+
+
+def pep440_to_file_version(version: str) -> str:
+    """Map a PEP 440 *version* to a deterministic ``a.b.c.d`` of four 16-bit ints.
+
+    ``a.b.c`` are ``release[0:3]`` (missing parts are 0). ``d`` folds the
+    pre/post/dev segment so that, for the same ``a.b.c``:
+    ``devN`` (``0+N``) < ``aN`` (``10000+N``) < ``bN`` (``20000+N``) <
+    ``rcN`` (``30000+N``) < final (``40000``) < ``postN`` (``50000+N``).
+    The result is therefore monotonic **within a single epoch** only. Epoch is
+    not representable in the four-field resource (``major`` already holds
+    ``release[0]``) and is carried only by the string ProductVersion, so a
+    cross-epoch numeric comparison may not order; an unparseable version degrades
+    to ``0.0.0.0``.
+    """
+    try:
+        v = Version(version)
+    except InvalidVersion:
+        return "0.0.0.0"
+    release = v.release
+    a = _clamp(release[0] if len(release) > 0 else 0)
+    b = _clamp(release[1] if len(release) > 1 else 0)
+    c = _clamp(release[2] if len(release) > 2 else 0)
+    if v.pre is not None:
+        letter, n = v.pre
+        d = _PRE_TIER.get(letter, _PRE_TIER["rc"]) + _clamp(n, 9999)
+    elif v.post is not None:
+        d = _POST_TIER + _clamp(v.post, 9999)
+    elif v.dev is not None:
+        d = _clamp(v.dev, 9999)
+    else:
+        d = _FINAL_TIER
+    return f"{a}.{b}.{c}.{_clamp(d)}"
+
+
+@runtime_checkable
+class Signer(Protocol):
+    """Signs a set of PE files in place (Windows-only, new to the codebase)."""
+
+    def sign(self, paths: Sequence[Path]) -> None: ...
+
+    @property
+    def configured(self) -> bool: ...
+
+
+@dataclass(frozen=True)
+class NullSigner:
+    """The unconfigured default: signing is a no-op, artifact stays unsigned."""
+
+    configured: bool = False
+
+    def sign(self, paths: Sequence[Path]) -> None:
+        return
+
+
+@dataclass(frozen=True)
+class SigntoolSigner:
+    """Authenticode signing via ``signtool`` against a cert-store thumbprint."""
+
+    thumbprint: str
+    timestamp_url: str
+    store_scope: str
+    signtool: str = "signtool"
+    configured: bool = True
+
+    def command(self, paths: Sequence[Path]) -> list[str]:
+        """The exact ``signtool`` argv for *paths* (pure; unit-tested directly)."""
+        argv = [
+            self.signtool,
+            "sign",
+            "/sha1",
+            self.thumbprint,
+            "/fd",
+            "SHA256",
+            "/tr",
+            self.timestamp_url,
+            "/td",
+            "SHA256",
+        ]
+        # /sm selects the LocalMachine store; without it signtool uses CurrentUser.
+        if self.store_scope == "machine":
+            argv.append("/sm")
+        argv += [str(p) for p in paths]
+        return argv
+
+    def sign(self, paths: Sequence[Path]) -> None:
+        if not paths:
+            return
+        argv = self.command(paths)
+        exe = shutil.which(self.signtool) or self.signtool
+        argv[0] = exe
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True)
+        except OSError as exc:
+            raise WindowsBundleError(
+                f"failed to run signtool ({self.signtool}): {exc}. signtool ships "
+                "with the Windows SDK and is Windows-only."
+            ) from exc
+        if proc.returncode != 0:
+            raise WindowsBundleError(
+                f"signtool failed (exit {proc.returncode}):\n"
+                f"{(proc.stderr or proc.stdout).strip()}\n"
+                "  Check the thumbprint, that the cert is in the configured "
+                "store_scope, and that the timestamp server is reachable."
+            )
+
+
+def select_signer(signing, *, signtool: str = "signtool") -> Signer:
+    """Pick the signer for a ``[tool.kivy.windows.signing]`` config.
+
+    Returns a :class:`SigntoolSigner` when a thumbprint is configured, else a
+    :class:`NullSigner` (unsigned artifact — the v1 default).
+    """
+    if not signing.configured:
+        return NullSigner()
+    return SigntoolSigner(
+        thumbprint=signing.thumbprint.replace(" ", "").upper(),
+        timestamp_url=signing.timestamp_url,
+        store_scope=signing.store_scope,
+        signtool=signtool,
+    )

kivyforge/platforms/windows/vendor/LICENSE.rcedit

@@ -0,0 +1,29 @@
+rcedit (https://github.com/electron/rcedit) — MIT License
+
+kivyforge vendors the prebuilt `rcedit-x64.exe` (v2.0.0) to patch the per-app
+icon and version resources into the launcher on Windows. It is redistributed
+unmodified under the terms below; the SHA-256 is pinned in this directory's
+SHA256SUMS and re-fetched/verified by `fetch_rcedit.py`.
+
+----------------------------------------------------------------------
+
+Copyright (c) 2013 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

kivyforge/platforms/windows/vendor/NOTICE

@@ -0,0 +1,17 @@
+Vendored Windows binaries — provenance
+=======================================
+
+launcher-amd64.exe
+  kivyforge's OWN onedir launcher. Built from kivyforge/platforms/windows/
+  launcher/launcher.c by that directory's build_launcher.py (MSVC, /Brepro
+  deterministic). Covered by kivyforge's own license. Nothing is vendored from
+  distlib/simple_launcher — that is a design reference only. The binary appends
+  nothing (no zip/timestamp tail), so it is byte-reproducible from source; CI
+  rebuilds it and byte-compares against this vendored copy.
+
+rcedit-x64.exe
+  Third-party: electron/rcedit v2.0.0 (MIT), redistributed unmodified to patch
+  the per-app icon and version resources into the launcher. See LICENSE.rcedit.
+  Source: https://github.com/electron/rcedit/releases/tag/v2.0.0
+
+Both binaries are SHA-256-pinned in SHA256SUMS and verified at use time.

kivyforge/platforms/windows/vendor/SHA256SUMS

@@ -0,0 +1,4 @@
+# SHA-256 of vendored Windows binaries (kivyforge).
+# Regenerate the launcher with: python -m kivyforge.platforms.windows.launcher.build_launcher build
+2b7f31aa0d81d918cd9fbe1b6c7fa77580f0b72e0b44bb1e2a055a05db19d041  launcher-amd64.exe
+3e7801db1a5edbec91b49a24a094aad776cb4515488ea5a4ca2289c400eade2a  rcedit-x64.exe

kivyforge/platforms/windows/vendor/TOOLSET.txt

@@ -0,0 +1,4 @@
+# MSVC VCTOOLSVERSION + Windows SDK used to build launcher-amd64.exe.
+# Re-vendor via the `revendor_launcher` CI workflow when either drifts.
+14.51.36231
+10.0.26100.0

kivyforge/platforms/windows/vendor/__init__.py

@@ -0,0 +1,12 @@
+"""Vendored prebuilt Windows binaries (windows-spec).
+
+Contains the compiled onedir launcher (``launcher-amd64.exe``, built from the
+in-repo C source by ``launcher/build_launcher.py``) and ``rcedit-x64.exe`` (the
+resource-patch tool, re-fetched/verified by ``fetch_rcedit.py``). Both are
+SHA-256-pinned in ``SHA256SUMS``; see ``LICENSE.rcedit`` and ``NOTICE`` for
+provenance.
+"""
+
+# arm64: add a second vendored launcher (launcher-arm64.exe) + its SHA256SUMS
+# entry + a pyproject package-data glob. rcedit-x64.exe is reused (emulated on
+# Arm64 Windows; it only edits PE resources). See arm64-windows.md §5, §10.

kivyforge/platforms/windows/vendor/fetch_rcedit.py

@@ -0,0 +1,97 @@
+"""Fetch + verify the vendored ``rcedit-x64.exe`` against its pinned SHA-256.
+
+rcedit is a third-party prebuilt tool (electron/rcedit, MIT). Rather than trust
+whatever is on disk, this script downloads the pinned release and verifies its
+SHA-256 against ``SHA256SUMS`` before writing it, so refreshing the vendored
+binary is reproducible and tamper-evident. Run it when bumping the pinned
+version (update ``RCEDIT_VERSION`` + the manifest hash together).
+
+    python -m kivyforge.platforms.windows.vendor.fetch_rcedit          # fetch+verify
+    python -m kivyforge.platforms.windows.vendor.fetch_rcedit --check  # verify only
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+import urllib.request
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+RCEDIT_NAME = "rcedit-x64.exe"
+RCEDIT_PATH = HERE / RCEDIT_NAME
+MANIFEST = HERE / "SHA256SUMS"
+
+RCEDIT_VERSION = "2.0.0"
+RCEDIT_URL = (
+    f"https://github.com/electron/rcedit/releases/download/v{RCEDIT_VERSION}/"
+    f"{RCEDIT_NAME}"
+)
+
+
+class RceditFetchError(Exception):
+    """rcedit could not be fetched or failed its SHA-256 verification."""
+
+
+def pinned_sha256() -> str:
+    if not MANIFEST.is_file():
+        raise RceditFetchError(f"manifest missing: {MANIFEST}")
+    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 name.strip() == RCEDIT_NAME:
+            return digest.strip()
+    raise RceditFetchError(f"{RCEDIT_NAME} has no pinned SHA-256 in {MANIFEST}.")
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def verify_only() -> int:
+    if not RCEDIT_PATH.is_file():
+        raise RceditFetchError(f"{RCEDIT_PATH} is missing; run without --check.")
+    actual = _sha256(RCEDIT_PATH.read_bytes())
+    expected = pinned_sha256()
+    if actual != expected:
+        raise RceditFetchError(
+            f"{RCEDIT_NAME} SHA-256 {actual} does not match the pin {expected}."
+        )
+    print(f"verified {RCEDIT_PATH} ({actual})")
+    return 0
+
+
+def fetch() -> int:
+    expected = pinned_sha256()
+    with urllib.request.urlopen(RCEDIT_URL, timeout=60) as resp:  # noqa: S310
+        data = resp.read()
+    actual = _sha256(data)
+    if actual != expected:
+        raise RceditFetchError(
+            f"downloaded {RCEDIT_NAME} SHA-256 {actual} does not match the pin "
+            f"{expected}; refusing to write. (Bump RCEDIT_VERSION + the manifest "
+            "together to update.)"
+        )
+    RCEDIT_PATH.write_bytes(data)
+    print(f"fetched {RCEDIT_PATH} ({actual})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check", action="store_true", help="verify the on-disk binary only."
+    )
+    args = parser.parse_args(argv)
+    try:
+        return verify_only() if args.check else fetch()
+    except (RceditFetchError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kivyforge/platforms/windows/wheels_stage.py

@@ -0,0 +1,139 @@
+r"""Install the locked wheels into the bundled prefix — a no-pip scheme installer.
+
+Wheels are fetched + SHA-256-verified from ``pylock.windows.toml`` (URL or
+vendored path) and unpacked directly. This is a **Windows-only, deterministic
+wheel-scheme installer**: it never resolves dependencies, never shells out to
+the host ``pip``, and never applies the host interpreter's compatibility rules —
+the lock already decided everything. Windows ships one arch (``amd64``) per
+onedir, so per package a single wheel satisfies coverage: a pure-Python
+(``py3-none-any``) wheel or a ``win_amd64`` wheel.
+
+arm64: this staging logic is already arch-generic (it routes by
+``wheel_arch(tag)``), so only this docstring's "one arch (amd64)" /
+"``win_amd64``" wording changes when ``win_arm64`` lands — no code change here.
+See arm64-windows.md §9.
+
+Scheme routing into the ``<bundle>\python`` prefix (the load-bearing part):
+
+* package root + ``.data/{purelib,platlib}`` -> ``Lib\site-packages``
+* ``.data/data`` -> the **prefix root** (so ``share\<dep>\bin`` lands at
+  ``<prefix>\share\<dep>\bin`` and survives) -- a site-packages-only copy
+  silently drops every SDL DLL and Kivy dies importing its window provider. This
+  is the real DLL-discovery invariant; "pip is load-bearing" it is not.
+* ``.data/scripts`` -> ``Scripts``
+* ``.data/headers`` -> ``Include``
+
+The shipped macOS/Linux ``_unpack`` is intentionally left untouched.
+"""
+
+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 WindowsBundleError
+from .lock import wheel_arch
+
+
+def stage_wheels(
+    packages: tuple[LockedPackage, ...],
+    arch: str,
+    prefix: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> None:
+    """Install every package's wheel for *arch* into the *prefix* schemes.
+
+    *prefix* is the staged CPython home (``<bundle>\\python``). Its existing
+    ``Lib\\site-packages`` (from the runtime archive) is preserved and installed
+    into; the runtime must already be staged.
+    """
+    cache = cache or ArtifactCache()
+    site_packages = prefix / "Lib" / "site-packages"
+    site_packages.mkdir(parents=True, exist_ok=True)
+
+    for pkg in packages:
+        wheel = _select_wheel(pkg, arch)
+        _install(_fetch(wheel, project_root, cache, no_cache), prefix, site_packages)
+
+
+def _select_wheel(pkg: LockedPackage, arch: str) -> LockedWheel:
+    """Pick the wheel to install: pure-Python, else the one covering *arch*."""
+    for wheel in pkg.wheels:
+        if wheel.is_pure_python:
+            return wheel
+    for wheel in pkg.wheels:
+        if any(wheel_arch(sub) == arch for sub in wheel.platform_tag.split(".")):
+            return wheel
+    raise WindowsBundleError(
+        f"{pkg.name} {pkg.version} has no wheel for arch {arch} in the lock.\n"
+        "  Re-run `kivyforge lock -p windows`."
+    )
+
+
+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 WindowsBundleError(str(exc)) from exc
+
+
+def _install(wheel: Path, prefix: Path, site_packages: Path) -> None:
+    """Unpack *wheel*, routing each install scheme to its prefix location."""
+    with zipfile.ZipFile(wheel) as zf:
+        _safe_extract(zf, site_packages)
+    # Route the .data schemes out of site-packages to their prefix locations.
+    # purelib/platlib stay in site-packages; the rest move relative to prefix.
+    scheme_targets = {
+        "purelib": site_packages,
+        "platlib": site_packages,
+        "data": prefix,
+        "scripts": prefix / "Scripts",
+        "headers": prefix / "Include",
+    }
+    for data_dir in list(site_packages.glob("*.data")):
+        for sub in sorted(p.name for p in data_dir.iterdir() if p.is_dir()):
+            target = scheme_targets.get(sub)
+            if target is None:
+                # An unknown scheme subdir: route to the prefix root by name so
+                # nothing declared in the wheel is silently dropped.
+                target = prefix / sub
+                _merge_tree(data_dir / sub, target)
+                continue
+            _merge_tree(data_dir / sub, target)
+        shutil.rmtree(data_dir, ignore_errors=True)
+
+
+def _merge_tree(src: Path, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    for item in src.iterdir():
+        target = dest / item.name
+        if item.is_dir():
+            _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 WindowsBundleError(f"unsafe path in wheel: {member!r}")
+    zf.extractall(target)  # noqa: S202 — members validated just above