kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/artifacts/frameworks.py

@@ -0,0 +1,240 @@
+"""Populate ``<app>-ios/Frameworks/`` from wheels and xcframework archives (spec 03/06).
+
+Two sources land in ``Frameworks/``:
+
+1. **Wheel-embedded xcframeworks** — a wheel may ship a ``<pkg>.frameworks/``
+   directory containing one or more ``<name>.xcframework`` trees (for the
+   canonical Kivy app, ANGLE + the SDL3 family ride inside the kivy wheel).
+   ``kivyforge build`` walks installed wheels and copies each one out.
+2. **Standalone native xcframework archives** — ``[[tool.kivyforge.xcframeworks]]``
+   entries, extracted from a zip/tar.gz (honoring ``archive_member`` when the
+   archive holds more than one xcframework).
+
+A duplicate-framework policy (spec 06) guards against two sources providing the
+same ``<name>.xcframework``: identical content (same tree hash) is deduplicated
+silently, while a basename collision with differing content fails the build,
+naming both providers and their hashes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import plistlib
+import shutil
+import tarfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class FrameworkConflict(Exception):
+    """Two artifacts provide the same ``<name>.xcframework`` with differing content."""
+
+
+@dataclass(frozen=True)
+class PlacedFramework:
+    """A framework staged into ``Frameworks/``, with provenance for conflict checks."""
+
+    path: Path
+    origin: str
+    tree_hash: str
+
+
+def copy_wheel_frameworks(
+    pip_deps: Path,
+    frameworks_dir: Path,
+    *,
+    existing: dict[str, PlacedFramework] | None = None,
+) -> list[str]:
+    """Copy every ``*.xcframework`` found under any ``*.frameworks/`` dir.
+
+    Returns the names placed during this call. Two artifacts that share a
+    framework basename are deduplicated when their content trees hash equal, and
+    raise ``FrameworkConflict`` (naming both providers) when they differ.
+
+    ``existing`` is a shared registry threaded across the multiple pip-deps
+    slices (and into native xcframework extraction) so cross-source duplicates
+    are reconciled against everything already staged.
+
+    After copying, wheel staging dirs (``kivy.frameworks``, ``.frameworks``, …)
+    are removed from ``pip-deps/`` so Copy Bundle Resources does not ship
+    duplicate xcframework trees inside the app bundle.
+    """
+    frameworks_dir.mkdir(parents=True, exist_ok=True)
+    registry = existing if existing is not None else {}
+    placed: set[str] = set()
+    embedded_dirs: list[Path] = []
+    for frameworks_subdir in sorted(pip_deps.glob("*.frameworks")):
+        if not frameworks_subdir.is_dir():
+            continue
+        embedded_dirs.append(frameworks_subdir)
+        for xc in sorted(frameworks_subdir.glob("*.xcframework")):
+            _place(xc, frameworks_dir, registry, origin=str(frameworks_subdir.name))
+            placed.add(xc.name)
+    for subdir in embedded_dirs:
+        shutil.rmtree(subdir)
+    return sorted(placed)
+
+
+def extract_xcframework_archive(
+    archive: Path,
+    frameworks_dir: Path,
+    *,
+    name: str,
+    archive_format: str = "zip",
+    archive_member: str | None = None,
+    existing: dict[str, PlacedFramework] | None = None,
+) -> Path:
+    """Extract a native ``.xcframework`` from an archive into ``Frameworks/``.
+
+    ``archive_member`` names the exact ``.xcframework`` directory inside the
+    archive when auto-detection (single top-level ``.xcframework``) is
+    insufficient. Returns the destination path. ``existing`` is the shared
+    registry used to dedupe identical duplicates and reject conflicting ones.
+    """
+    frameworks_dir.mkdir(parents=True, exist_ok=True)
+    registry = existing if existing is not None else {}
+    import tempfile
+
+    with tempfile.TemporaryDirectory(prefix="kivy-xc-") as tmp:
+        tmp_dir = Path(tmp)
+        _unpack(archive, tmp_dir, archive_format)
+        xc_dir = _locate_xcframework(tmp_dir, archive_member, name=name)
+        return _place(xc_dir, frameworks_dir, registry, origin=archive.name)
+
+
+def read_xcframework_slices(xcframework: Path) -> tuple[str, ...]:
+    """Return the slice identifiers declared in an ``.xcframework`` root plist.
+
+    These are the ``LibraryIdentifier`` values from ``Info.plist``'s
+    ``AvailableLibraries`` (e.g. ``ios-arm64``, ``ios-arm64_x86_64-simulator``),
+    returned sorted for a deterministic lockfile. ``kivyforge lock`` records them
+    so the lock advertises which device/simulator slices an artifact ships.
+    """
+    info = xcframework / "Info.plist"
+    try:
+        with open(info, "rb") as fh:
+            data = plistlib.load(fh)
+    except OSError as exc:
+        raise FileNotFoundError(
+            f"{xcframework.name}: missing or unreadable Info.plist ({exc})."
+        ) from exc
+    libraries = data.get("AvailableLibraries", [])
+    identifiers = [
+        lib["LibraryIdentifier"]
+        for lib in libraries
+        if isinstance(lib, dict) and lib.get("LibraryIdentifier")
+    ]
+    return tuple(sorted(identifiers))
+
+
+def _unpack(archive: Path, dest: Path, archive_format: str) -> None:
+    if archive_format == "zip":
+        with zipfile.ZipFile(archive) as zf:
+            zf.extractall(dest)
+    elif archive_format in ("tar.gz", "tgz", "targz"):
+        with tarfile.open(archive, "r:gz") as tf:
+            # filter="data" rejects path traversal, absolute paths, and
+            # unsafe special files (Python 3.12+ / PEP 706).
+            tf.extractall(dest, filter="data")
+    else:
+        raise ValueError(f"unsupported archive_format {archive_format!r} (zip|tar.gz)")
+
+
+def _locate_xcframework(root: Path, archive_member: str | None, *, name: str) -> Path:
+    if archive_member:
+        candidate = root / archive_member
+        if not candidate.is_dir():
+            raise FileNotFoundError(
+                f"{name}: archive_member {archive_member!r} not found in archive."
+            )
+        return candidate
+    matches = [p for p in root.rglob("*.xcframework") if p.is_dir()]
+    if not matches:
+        raise FileNotFoundError(f"{name}: no .xcframework found in archive.")
+    # Auto-detect only considers the shallowest depth (the "top level").
+    min_depth = min(len(p.relative_to(root).parts) for p in matches)
+    top = [p for p in matches if len(p.relative_to(root).parts) == min_depth]
+    if len(top) == 1:
+        return top[0]
+    raise FrameworkConflict(
+        f"{name}: archive contains multiple .xcframework directories "
+        f"({', '.join(sorted(p.name for p in top))}); set archive_member to pick one."
+    )
+
+
+def _place(
+    src: Path,
+    frameworks_dir: Path,
+    registry: dict[str, PlacedFramework],
+    *,
+    origin: str,
+) -> Path:
+    """Stage ``src`` into ``Frameworks/`` applying the duplicate policy (spec 06).
+
+    Identical content (matching tree hash) already staged under the same
+    basename is deduplicated silently; differing content raises
+    ``FrameworkConflict`` naming both providers and their hashes.
+    """
+    dest = frameworks_dir / src.name
+    new_hash = _tree_hash(src)
+    prior = registry.get(src.name)
+    if prior is not None:
+        if prior.tree_hash == new_hash:
+            # Same artifact from two sources (or the same wheel across slices):
+            # keep the copy already staged, emit nothing.
+            return prior.path
+        raise FrameworkConflict(
+            f"{src.name} is provided by two sources with different contents:\n"
+            f"  - {prior.origin} (sha256 {prior.tree_hash})\n"
+            f"  - {origin} (sha256 {new_hash})\n"
+            "  Pin a single provider, or remove the duplicate. kivyforge does not "
+            "pick a winner: a version mismatch can link yet crash at runtime."
+        )
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+    _normalize_framework_plists(dest)
+    registry[src.name] = PlacedFramework(path=dest, origin=origin, tree_hash=new_hash)
+    return dest
+
+
+def _tree_hash(root: Path) -> str:
+    """Deterministic SHA-256 over a directory tree's structure and file contents.
+
+    Walks entries in sorted relative-path order, framing each with a type tag
+    (file/dir/symlink), its relative path, and — for files — a length-prefixed
+    stream of contents, so two trees hash equal iff their layout and bytes match.
+    """
+    h = hashlib.sha256()
+    for path in sorted(root.rglob("*"), key=lambda p: p.relative_to(root).as_posix()):
+        rel = path.relative_to(root).as_posix().encode("utf-8")
+        if path.is_symlink():
+            target = path.readlink().as_posix().encode("utf-8")
+            h.update(b"L\0" + rel + b"\0" + target + b"\0")
+        elif path.is_dir():
+            h.update(b"D\0" + rel + b"\0")
+        elif path.is_file():
+            size = path.stat().st_size
+            h.update(b"F\0" + rel + b"\0" + str(size).encode("ascii") + b"\0")
+            with open(path, "rb") as fh:
+                for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+                    h.update(chunk)
+    return h.hexdigest()
+
+
+def _normalize_framework_plists(xcframework: Path) -> None:
+    """Ensure each embedded ``.framework`` has a root ``Info.plist``.
+
+    Some upstream wheels (e.g. KivyThorVG) ship the plist only under
+    ``Resources/``; Xcode's bundle validation requires it at the framework root.
+    """
+    for fw in xcframework.rglob("*.framework"):
+        if not fw.is_dir():
+            continue
+        root_plist = fw / "Info.plist"
+        if root_plist.is_file():
+            continue
+        resources_plist = fw / "Resources" / "Info.plist"
+        if resources_plist.is_file():
+            shutil.copy2(resources_plist, root_plist)

kivyforge/artifacts/native_stage_util.py

@@ -0,0 +1,346 @@
+"""Platform-neutral native-binary staging mechanics (shared by desktop backends).
+
+Each desktop backend declares a ``[tool.kivy.<platform>.native.binaries]``
+channel whose entries are fetched + SHA-256-verified from the platform lock and
+staged into the bundle's ``bin`` directory — a single native file copied in with
+its exec bit set, or a ``.zip`` / ``.tar.gz`` / ``.tgz`` of several extracted
+with a path-traversal guard. ``bin/`` is a single flat namespace, so two entries
+staging to the same path is a hard error (a silent clobber otherwise).
+
+This module owns the mechanics so the security-sensitive ``_safe_extract``
+(zip path-traversal) and the ``tarfile`` ``filter="data"`` extractor live in
+exactly one audited place. It raises the neutral
+:class:`NativeStageError`; each backend's thin wrapper translates that into its
+own bundle-error type (the ``NativeBinaryResolverError`` →
+``WheelRuntimeBuildError`` pattern used in the lock builder).
+"""
+
+from __future__ import annotations
+
+import shutil
+import stat
+import sys
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+from kivyforge.artifacts.verify import HashMismatch
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from kivyforge.lock.wheelruntime.model import LockedNativeBinary
+
+# Reserved DOS device names (case-insensitive), illegal as a path component on
+# Windows even with an extension (``NUL.dll`` is still reserved).
+_WINDOWS_RESERVED = frozenset(
+    {
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        *(f"COM{i}" for i in range(1, 10)),
+        *(f"LPT{i}" for i in range(1, 10)),
+    }
+)
+
+
+class NativeStageError(Exception):
+    """A native-binary staging failure (translated to the caller's bundle error)."""
+
+
+def stage_binaries(
+    binaries: tuple[LockedNativeBinary, ...],
+    parent_dir: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+    bin_label: str,
+    casefold: bool = False,
+    reject_windows_names: bool = False,
+    validate: Callable[[Path], None] | None = None,
+) -> None:
+    """Stage every pinned native binary into ``parent_dir/bin``.
+
+    ``bin/`` is created under *parent_dir* only when *binaries* is non-empty
+    (no empty ``bin/``). *bin_label* is the human-readable path used in the
+    collision message (e.g. ``"Contents/Resources/bin"`` or ``"usr/bin"``).
+
+    Windows-facing options (defaults keep macOS/Linux behavior unchanged):
+    *casefold* keys the collision check case-insensitively (so ``SDK.dll`` and
+    ``sdk.dll`` collide on a case-insensitive filesystem); *reject_windows_names*
+    rejects members that are reserved DOS device names, contain ``:`` (alternate
+    data streams), or end in a dot/space; *validate* is called on each staged
+    file (e.g. a PE architecture check).
+    """
+    if not binaries:
+        return
+    cache = cache or ArtifactCache()
+    bin_dir = parent_dir / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    # bin/ is a single flat namespace (helpers run by name off PATH; libraries
+    # load by path/soname), so two entries must never stage a file to the same
+    # path — the second would silently clobber the first. Track every claimed
+    # path and fail loudly instead.
+    claimed: dict[str, str] = {}
+    for entry in binaries:
+        _stage_one(
+            entry,
+            bin_dir,
+            claimed,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+            bin_label=bin_label,
+            casefold=casefold,
+            reject_windows_names=reject_windows_names,
+            validate=validate,
+        )
+
+
+def _stage_one(
+    entry: LockedNativeBinary,
+    bin_dir: Path,
+    claimed: dict[str, str],
+    *,
+    project_root: Path,
+    cache: ArtifactCache,
+    no_cache: bool,
+    bin_label: str,
+    casefold: bool,
+    reject_windows_names: bool,
+    validate: Callable[[Path], None] | None,
+) -> None:
+    source = entry.url or entry.path or ""
+    # Stage single files under their *source* basename (copied "as-is") so a
+    # library keeps its extension for by-path/by-name loads.
+    filename = source.rsplit("/", 1)[-1] or entry.name
+    fetched = _fetch(entry, filename, project_root, cache, no_cache)
+    lowered = source.lower()
+    if lowered.endswith(".zip"):
+        _extract_zip(
+            fetched,
+            bin_dir,
+            claimed,
+            entry.name,
+            bin_label,
+            casefold=casefold,
+            reject_windows_names=reject_windows_names,
+            validate=validate,
+        )
+    elif lowered.endswith((".tar.gz", ".tgz")):
+        _extract_tar(
+            fetched,
+            bin_dir,
+            claimed,
+            entry.name,
+            bin_label,
+            casefold=casefold,
+            reject_windows_names=reject_windows_names,
+            validate=validate,
+        )
+    else:
+        rel = Path(filename)
+        if reject_windows_names:
+            _reject_windows_unsafe(rel, entry.name, bin_label)
+        _claim(claimed, rel, entry.name, bin_label, casefold=casefold)
+        dest = bin_dir / rel
+        shutil.copy2(fetched, dest)
+        _make_executable(dest)
+        if validate is not None:
+            validate(dest)
+
+
+def _fetch(
+    entry: LockedNativeBinary,
+    filename: str,
+    project_root: Path,
+    cache: ArtifactCache,
+    no_cache: bool,
+) -> Path:
+    try:
+        return fetch_artifact(
+            name=entry.name,
+            sha256=entry.sha256,
+            filename=filename,
+            url=entry.url,
+            path=entry.path,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except (DownloadError, HashMismatch) as exc:
+        raise NativeStageError(str(exc)) from exc
+
+
+def _extract_zip(
+    archive: Path,
+    bin_dir: Path,
+    claimed: dict[str, str],
+    entry_name: str,
+    bin_label: str,
+    *,
+    casefold: bool = False,
+    reject_windows_names: bool = False,
+    validate: Callable[[Path], None] | None = None,
+) -> None:
+    with tempfile.TemporaryDirectory(prefix="kivy-nb-stage-") as tmp:
+        staged = Path(tmp)
+        with zipfile.ZipFile(archive) as zf:
+            if reject_windows_names:
+                _reject_windows_unsafe_names(zf.namelist(), entry_name, bin_label)
+            _safe_extract(zf, staged)
+        for src in sorted(staged.rglob("*")):
+            if not src.is_file():
+                continue
+            rel = src.relative_to(staged)
+            _claim(claimed, rel, entry_name, bin_label, casefold=casefold)
+            dest = bin_dir / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dest)
+            _make_executable(dest)
+            if validate is not None:
+                validate(dest)
+
+
+def _extract_tar(
+    archive: Path,
+    bin_dir: Path,
+    claimed: dict[str, str],
+    entry_name: str,
+    bin_label: str,
+    *,
+    casefold: bool = False,
+    reject_windows_names: bool = False,
+    validate: Callable[[Path], None] | None = None,
+) -> None:
+    """Extract a ``.tar.gz`` / ``.tgz`` into ``bin_dir`` with the same guards as zip.
+
+    ``.tar.gz`` is the dominant distribution format for Linux SDKs; without this
+    a tarball ``source`` would land in ``bin/`` as one opaque, exec-bit'd file.
+    Uses ``tarfile``'s hardened ``filter="data"`` extractor — the tar analog of
+    :func:`_safe_extract` — which strips symlinks/hardlinks/device nodes and
+    rejects absolute/escaping members (more important for tar than zip, since
+    tar *restores* symlinks and special files).
+    """
+    with tempfile.TemporaryDirectory(prefix="kivy-nb-stage-") as tmp:
+        staged = Path(tmp)
+        try:
+            with tarfile.open(archive, "r:*") as tf:
+                if reject_windows_names:
+                    _reject_windows_unsafe_names(tf.getnames(), entry_name, bin_label)
+                tf.extractall(staged, filter="data")  # noqa: S202 — hardened filter
+        except tarfile.FilterError as exc:
+            raise NativeStageError(
+                f"unsafe path in native-binary archive: {exc}"
+            ) from exc
+        except tarfile.TarError as exc:
+            raise NativeStageError(
+                f"could not read native-binary archive {archive.name}: {exc}"
+            ) from exc
+        for src in sorted(staged.rglob("*")):
+            # The "data" filter drops symlinks/special files; copy only regular
+            # files (a lingering symlink is skipped rather than dereferenced).
+            if src.is_symlink() or not src.is_file():
+                continue
+            rel = src.relative_to(staged)
+            _claim(claimed, rel, entry_name, bin_label, casefold=casefold)
+            dest = bin_dir / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dest)
+            _make_executable(dest)
+            if validate is not None:
+                validate(dest)
+
+
+def _claim(
+    claimed: dict[str, str],
+    rel: Path,
+    entry_name: str,
+    bin_label: str,
+    *,
+    casefold: bool = False,
+) -> None:
+    """Reserve ``bin/<rel>`` for *entry_name*; raise if already taken.
+
+    Prevents one native-binary entry from silently overwriting another (two
+    single files with the same basename, two zips sharing a member path, or a
+    single file colliding with a zip member). When *casefold* is set the key is
+    lowercased, so ``SDK.dll`` and ``sdk.dll`` collide on a case-insensitive
+    target filesystem (Windows).
+    """
+    key = rel.as_posix()
+    if casefold:
+        key = key.lower()
+    prev = claimed.get(key)
+    if prev is not None:
+        owners = entry_name if prev == entry_name else f"{prev!r} and {entry_name!r}"
+        raise NativeStageError(
+            f"native binaries stage colliding path bin/{key} "
+            f"({'duplicate inside ' + owners if prev == entry_name else owners}).\n"
+            f"  Every native binary must stage to a unique path in "
+            f"{bin_label}. Rename the artifact (or its source), or "
+            f"drop the duplicate, so no two entries write the same file."
+        )
+    claimed[key] = entry_name
+
+
+def _make_executable(path: Path) -> None:
+    # NTFS has no POSIX exec bit; "executable" is determined by extension/loader.
+    # Skip explicitly on Windows so the POSIX chmod is a documented no-op there.
+    if sys.platform == "win32":
+        return
+    mode = path.stat().st_mode
+    path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _reject_windows_unsafe_names(
+    names: Iterable[str], entry_name: str, bin_label: str
+) -> None:
+    """Reject any archive member illegal on Windows (reserved / ADS / trailing)."""
+    for name in names:
+        _reject_windows_unsafe(Path(name.replace("\\", "/")), entry_name, bin_label)
+
+
+def _reject_windows_unsafe(rel: Path, entry_name: str, bin_label: str) -> None:
+    """Raise if any component of *rel* is illegal on a Windows filesystem.
+
+    Reserved DOS device names (``NUL``, ``COM1`` ...), alternate data streams
+    (a ``:`` in a component), and trailing dots/spaces (which Windows silently
+    strips, changing the staged name) are all rejected loudly rather than
+    producing a surprising or unusable ``bin/`` layout.
+    """
+    for part in rel.parts:
+        if not part or part in (".", ".."):
+            continue
+        if ":" in part:
+            raise NativeStageError(
+                f"native binary {entry_name!r} stages a path with an alternate "
+                f"data stream (':') in {bin_label}/{rel.as_posix()!r}; rename it."
+            )
+        if part != part.rstrip(" ."):
+            raise NativeStageError(
+                f"native binary {entry_name!r} stages a component ending in a dot "
+                f"or space ({part!r}) in {bin_label}; Windows would silently strip "
+                "it. Rename the artifact."
+            )
+        stem = part.split(".", 1)[0].upper()
+        if stem in _WINDOWS_RESERVED:
+            raise NativeStageError(
+                f"native binary {entry_name!r} stages a reserved Windows device "
+                f"name ({part!r}) in {bin_label}; rename the artifact."
+            )
+
+
+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 NativeStageError(f"unsafe path in native-binary archive: {member!r}")
+    zf.extractall(target)  # noqa: S202 — members validated just above

kivyforge/artifacts/runtime.py

@@ -0,0 +1,65 @@
+"""Pluggable Python-runtime adapter (plan cross-cutting decision).
+
+``PythonOrgRuntime`` provides the canonical iOS Python xcframework from
+python.org (3.15+). The ``PythonRuntime`` Protocol keeps the interface
+stable if a second runtime is ever needed.
+
+See specs 02/03/06 for the canonical target details.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class RuntimeArtifact:
+    version: str
+    url: str
+    # Archive container; python.org ships a gzipped tarball.
+    archive_format: str = "tar.gz"
+
+
+class PythonRuntime(Protocol):
+    name: str
+
+    def xcframework_artifact(self, version: str) -> RuntimeArtifact:
+        """The downloadable Python.xcframework archive for ``version``."""
+        ...
+
+    def build_python_invocation(
+        self, *, xcframework: str, app: str, pip_deps: str
+    ) -> str:
+        """The 'Build Python' Run Script body that wires .so -> .framework."""
+        ...
+
+
+class PythonOrgRuntime:
+    """Canonical runtime: python.org Python.xcframework + ``install_python``."""
+
+    name = "python.org"
+
+    URL_TEMPLATE = (
+        "https://www.python.org/ftp/python/{version}/"
+        "python-{version}-iOS-XCframework.tar.gz"
+    )
+
+    def xcframework_artifact(self, version: str) -> RuntimeArtifact:
+        return RuntimeArtifact(
+            version=version, url=self.URL_TEMPLATE.format(version=version)
+        )
+
+    def build_python_invocation(
+        self, *, xcframework: str, app: str, pip_deps: str
+    ) -> str:
+        # python.org ships `install_python` inside the xcframework; it walks
+        # `app/` + `pip-deps/`, converts each `.so` to a per-module framework,
+        # and leaves a `.fwork` marker (Python 3.15 iOS docs §7.2.2 step 7).
+        return f"install_python {xcframework} {app} {pip_deps}"
+
+
+def get_runtime(name: str = "python.org", **kwargs) -> PythonRuntime:
+    if name in ("python.org", "pythonorg", "python_org"):
+        return PythonOrgRuntime()
+    raise ValueError(f"unknown python runtime {name!r} (expected python.org)")

kivyforge/artifacts/verify.py

@@ -0,0 +1,45 @@
+"""SHA-256 verification for downloaded/vendored artifacts (spec 03)."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+_CHUNK = 1 << 20  # 1 MiB
+
+
+class HashMismatch(Exception):
+    """Raised when an artifact's SHA-256 does not match the lockfile pin."""
+
+    def __init__(self, *, name: str, source: str, expected: str, actual: str) -> None:
+        self.name = name
+        self.source = source
+        self.expected = expected
+        self.actual = actual
+        super().__init__(
+            f"SHA-256 mismatch for {name}\n"
+            f"  source:   {source}\n"
+            f"  expected: {expected}\n"
+            f"  actual:   {actual}\n"
+            f"  The artifact may have been tampered with, or the source registry "
+            f"replaced it. Re-run `kivyforge lock`, and report the source if this "
+            f"persists."
+        )
+
+
+def sha256_file(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(_CHUNK), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def verify_file(path: str | Path, expected: str, *, name: str, source: str) -> None:
+    actual = sha256_file(path)
+    if actual != expected:
+        raise HashMismatch(name=name, source=source, expected=expected, actual=actual)