common: add shared FLS binary download utilities

Add a shared module for FLS (Flasher) binary download utilities that can
be used by multiple drivers. Update flashers driver to use the shared
get_fls_github_url() function.

Signed-off-by: Benny Zlotnik <bzlotnik@redhat.com>
Assisted-by: claude-opus-4.5

Author: bennyz

python/Dockerfile

@@ -7,11 +7,17 @@ RUN dnf install -y make git && \
 COPY --from=uv /uv /uvx /bin/
 
 FROM fedora:43 AS product
-RUN dnf install -y python3 ustreamer libusb1 android-tools python3-libgpiod && \
+RUN dnf install -y python3 ustreamer libusb1 android-tools python3-libgpiod curl && \
     dnf clean all && \
     rm -rf /var/cache/dnf
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
+# Install FLS binary for OCI flashing support
+ARG FLS_VERSION=0.1.9
+RUN curl -L "https://github.com/jumpstarter-dev/fls/releases/download/${FLS_VERSION}/fls-$(uname -m)-linux" \
+    -o /usr/local/bin/fls && \
+    chmod +x /usr/local/bin/fls
+
 FROM builder AS wheels
 ADD . /src
 RUN make -C /src/python build

python/packages/jumpstarter-driver-flashers/jumpstarter_driver_flashers/client.py

@@ -25,6 +25,7 @@
 
 from jumpstarter.client.decorators import driver_click_group
 from jumpstarter.common.exceptions import ArgumentError, JumpstarterException
+from jumpstarter.common.fls import get_fls_github_url
 
 
 class FlashError(JumpstarterException):
@@ -533,8 +534,8 @@ def _flash_with_fls(
             self._download_fls_binary(console, prompt, fls_binary_url, f"Failed to download FLS from {fls_binary_url}")
         elif fls_version != "":
             self.logger.info(f"Downloading FLS version {fls_version} from GitHub releases")
-            # Download fls binary to the target device (until it is available on the target device)
-            fls_url = f"https://github.com/jumpstarter-dev/fls/releases/download/{fls_version}/fls-aarch64-linux"
+            # Download fls binary to the target device (always aarch64 for target devices)
+            fls_url = get_fls_github_url(fls_version, arch="aarch64")
             self._download_fls_binary(console, prompt, fls_url, f"Failed to download FLS from {fls_url}")
 
         # Flash the image

python/packages/jumpstarter/jumpstarter/common/__init__.py

@@ -1,4 +1,13 @@
+from .fls import download_fls, get_fls_binary, get_fls_github_url
 from .metadata import Metadata
 from .tempfile import TemporarySocket, TemporaryTcpListener, TemporaryUnixListener
 
-__all__ = ["Metadata", "TemporarySocket", "TemporaryUnixListener", "TemporaryTcpListener"]
+__all__ = [
+    "Metadata",
+    "TemporarySocket",
+    "TemporaryUnixListener",
+    "TemporaryTcpListener",
+    "download_fls",
+    "get_fls_binary",
+    "get_fls_github_url",
+]

python/packages/jumpstarter/jumpstarter/common/fls.py

@@ -0,0 +1,115 @@
+"""FLS (Flasher) binary utilities.
+
+This module provides functions for locating the FLS binary tool
+used for flashing devices via fastboot with OCI image support.
+
+FLS is pre-installed in the container image for security and reliability,
+with optional configuration-based overrides for testing and flexibility.
+"""
+
+import logging
+import os
+import platform
+import tempfile
+import urllib.request
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+FLS_GITHUB_REPO = "jumpstarter-dev/fls"
+
+
+def get_fls_github_url(version: str, arch: str | None = None) -> str:
+    """Get GitHub release URL for FLS version.
+
+    Args:
+        version: FLS version (e.g., "0.1.9")
+        arch: Target architecture (e.g., "aarch64", "x86_64"). If None,
+              auto-detects from current platform.
+
+    Returns:
+        Download URL for the architecture-appropriate binary
+    """
+    if arch is None:
+        arch = platform.machine().lower()
+    else:
+        arch = arch.lower()
+    if arch in ("aarch64", "arm64"):
+        binary_name = "fls-aarch64-linux"
+    elif arch in ("x86_64", "amd64"):
+        binary_name = "fls-x86_64-linux"
+    else:
+        binary_name = "fls-aarch64-linux"  # Default to aarch64
+
+    return f"https://github.com/{FLS_GITHUB_REPO}/releases/download/{version}/{binary_name}"
+
+
+def download_fls(url: str) -> str:
+    """Download FLS binary from URL to a temp file.
+
+    Args:
+        url: URL to download FLS binary from
+
+    Returns:
+        Path to the downloaded binary
+
+    Raises:
+        RuntimeError: If download fails
+    """
+    fd, binary_path = tempfile.mkstemp(prefix="fls-")
+    os.close(fd)
+    try:
+        logger.info(f"Downloading FLS binary from: {url}")
+        urllib.request.urlretrieve(url, binary_path)
+        Path(binary_path).chmod(0o755)
+        logger.info(f"FLS binary downloaded to: {binary_path}")
+        return binary_path
+    except Exception as e:
+        Path(binary_path).unlink(missing_ok=True)
+        logger.error(f"Failed to download FLS from {url}: {e}")
+        raise RuntimeError(f"Failed to download FLS from {url}: {e}") from e
+
+
+def get_fls_binary(
+    fls_version: str | None = None,
+    fls_binary_url: str | None = None,
+    allow_custom_binaries: bool = False,
+) -> str:
+    """Get path to FLS binary with configuration-based overrides.
+
+    Args:
+        fls_version: Optional FLS version to download from GitHub releases
+        fls_binary_url: Custom URL to download FLS binary from
+        allow_custom_binaries: Whether custom binary URLs are allowed
+
+    Returns:
+        Path to the FLS binary
+
+    Raises:
+        RuntimeError: If custom binary URL provided but not allowed
+
+    Note:
+        Priority order:
+        1. fls_binary_url (if allow_custom_binaries=True)
+        2. fls_version from GitHub releases
+        3. Pre-installed system binary
+    """
+    if fls_binary_url:
+        if not allow_custom_binaries:
+            raise RuntimeError(
+                "Custom FLS binary URLs are disabled for security. "
+                "Set allow_custom_binaries=True in driver configuration to enable."
+            )
+        logger.warning(
+            f"⚠️  SECURITY: Downloading custom FLS binary from {fls_binary_url}. "
+            "Ensure this URL is trusted and secure."
+        )
+        return download_fls(fls_binary_url)
+
+    if fls_version:
+        github_url = get_fls_github_url(fls_version)
+        logger.warning(f"Downloading FLS version {fls_version} from GitHub: {github_url}")
+        return download_fls(github_url)
+
+    logger.debug("Using pre-installed FLS from system PATH")
+    return "fls"

python/packages/jumpstarter/jumpstarter/common/fls_test.py

@@ -0,0 +1,86 @@
+from unittest.mock import patch
+
+import pytest
+
+from .fls import download_fls, get_fls_binary, get_fls_github_url
+
+
+@pytest.mark.parametrize(
+    "arch,version,expected_binary",
+    [
+        ("aarch64", "0.1.9", "fls-aarch64-linux"),
+        ("arm64", "0.1.9", "fls-aarch64-linux"),
+        ("x86_64", "0.2.0", "fls-x86_64-linux"),
+        ("amd64", "0.2.0", "fls-x86_64-linux"),
+        ("unknown", "0.1.9", "fls-aarch64-linux"),  # defaults to aarch64
+    ],
+)
+def test_get_fls_github_url_auto_detect(arch, version, expected_binary):
+    """Test architecture auto-detection from platform.machine()"""
+    with patch("platform.machine", return_value=arch):
+        url = get_fls_github_url(version)
+        assert url == f"https://github.com/jumpstarter-dev/fls/releases/download/{version}/{expected_binary}"
+
+
+@pytest.mark.parametrize(
+    "arch,version,expected_binary",
+    [
+        ("aarch64", "0.1.9", "fls-aarch64-linux"),
+        ("AARCH64", "0.1.9", "fls-aarch64-linux"),  # case insensitive
+        ("x86_64", "0.2.0", "fls-x86_64-linux"),
+    ],
+)
+def test_get_fls_github_url_explicit_arch(arch, version, expected_binary):
+    """Test explicit architecture parameter (used by flashers for target device)"""
+    url = get_fls_github_url(version, arch=arch)
+    assert url == f"https://github.com/jumpstarter-dev/fls/releases/download/{version}/{expected_binary}"
+
+
+def test_get_fls_binary_with_custom_url():
+    with patch("jumpstarter.common.fls.download_fls", return_value="/tmp/custom-fls") as mock_download:
+        result = get_fls_binary(fls_binary_url="https://example.com/fls", allow_custom_binaries=True)
+
+        mock_download.assert_called_once_with("https://example.com/fls")
+        assert result == "/tmp/custom-fls"
+
+
+def test_get_fls_binary_custom_url_security_check():
+    """Test that custom URLs are blocked when allow_custom_binaries=False."""
+    with pytest.raises(RuntimeError, match="Custom FLS binary URLs are disabled for security"):
+        get_fls_binary(fls_binary_url="https://example.com/fls", allow_custom_binaries=False)
+
+
+def test_get_fls_binary_with_version():
+    with patch("jumpstarter.common.fls.download_fls", return_value="/tmp/fls-0.1.9") as mock_download:
+        with patch("jumpstarter.common.fls.get_fls_github_url", return_value="https://github.com/...") as mock_url:
+            result = get_fls_binary(fls_version="0.1.9")
+
+            mock_url.assert_called_once_with("0.1.9")
+            mock_download.assert_called_once()
+            assert result == "/tmp/fls-0.1.9"
+
+
+def test_get_fls_binary_falls_back_to_path():
+    result = get_fls_binary()
+    assert result == "fls"
+
+
+def test_download_fls_success():
+    with patch("urllib.request.urlretrieve") as mock_retrieve:
+        with patch("tempfile.mkstemp", return_value=(99, "/tmp/fls-test")):
+            with patch("os.close") as mock_close:
+                with patch("pathlib.Path.chmod"):
+                    result = download_fls("https://example.com/fls")
+
+                    mock_close.assert_called_once_with(99)
+                    mock_retrieve.assert_called_once_with("https://example.com/fls", "/tmp/fls-test")
+                    assert result == "/tmp/fls-test"
+
+
+def test_download_fls_failure():
+    with patch("urllib.request.urlretrieve", side_effect=Exception("Network error")):
+        with patch("tempfile.mkstemp", return_value=(99, "/tmp/fls-test")):
+            with patch("os.close"):
+                with patch("pathlib.Path.unlink"):
+                    with pytest.raises(RuntimeError, match="Failed to download FLS"):
+                        download_fls("https://example.com/fls")