flashnode 0.2.0__tar.gz → 0.3.0__tar.gz

{flashnode-0.2.0/flashnode.egg-info → flashnode-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flashnode
-Version: 0.2.0
+Version: 0.3.0
 Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flashruntime<0.4,>=0.3
+Requires-Dist: flashruntime<0.5,>=0.4
 Requires-Dist: psutil>=5.9
 Requires-Dist: websockets>=12
 Requires-Dist: cryptography>=42
@@ -60,8 +60,17 @@ flashnode work --coordinator http://<coordinator>:8100
 #   FLASHNODE_WORKDIR=$HOME/.cache/flashnode   (macOS + colima: VM-visible workdirs)
 #   FLASHNODE_WORKDIR=C:\Users\<you>\.flashnode  (Windows: must be under a
 #                                                 directory Docker Desktop shares)
+#   FLASHNODE_LOCAL_DATA=patients=/srv/data/patients-2026,labs=/srv/labs
+#                                    lend local directories to tasks by LABEL
 ```
 
+`FLASHNODE_LOCAL_DATA` lets you offer data **without uploading it**. Only the
+label names (`patients`, `labs`) are advertised to the coordinator — never the
+paths — and a task that names a label in its `local_inputs` gets that directory
+bind-mounted **read-only** at `/work/inputs/<label>`. A task asking for a label
+this machine does not lend is refused, not run half-fed; a task that asks for
+nothing sees nothing, exactly as before.
+
 If the coordinator enforces per-machine authentication
 (`FLASHML_NODE_TOKENS` set server-side), save the bearer token you were
 given before running `work`:

flashnode-0.2.0/PKG-INFO → flashnode-0.3.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: flashnode
-Version: 0.2.0
-Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: flashruntime<0.4,>=0.3
-Requires-Dist: psutil>=5.9
-Requires-Dist: websockets>=12
-Requires-Dist: cryptography>=42
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Dynamic: license-file
-
 # FlashNode
 
 > **The open host agent of the FlashML system.** Install FlashNode on a
@@ -60,8 +43,17 @@ flashnode work --coordinator http://<coordinator>:8100
 #   FLASHNODE_WORKDIR=$HOME/.cache/flashnode   (macOS + colima: VM-visible workdirs)
 #   FLASHNODE_WORKDIR=C:\Users\<you>\.flashnode  (Windows: must be under a
 #                                                 directory Docker Desktop shares)
+#   FLASHNODE_LOCAL_DATA=patients=/srv/data/patients-2026,labs=/srv/labs
+#                                    lend local directories to tasks by LABEL
 ```
 
+`FLASHNODE_LOCAL_DATA` lets you offer data **without uploading it**. Only the
+label names (`patients`, `labs`) are advertised to the coordinator — never the
+paths — and a task that names a label in its `local_inputs` gets that directory
+bind-mounted **read-only** at `/work/inputs/<label>`. A task asking for a label
+this machine does not lend is refused, not run half-fed; a task that asks for
+nothing sees nothing, exactly as before.
+
 If the coordinator enforces per-machine authentication
 (`FLASHML_NODE_TOKENS` set server-side), save the bearer token you were
 given before running `work`:

flashnode-0.3.0/flashnode/__init__.py

@@ -0,0 +1,21 @@
+"""FlashNode: the open host agent of the FlashML system.
+
+Installed by resource contributors to safely execute distributed ML tasks.
+See README.md and docs/SYSTEM_OVERVIEW.md.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+# Read from installed metadata rather than hardcoding. A literal here is a
+# SECOND source of truth for the version, and it drifted the moment it
+# existed: 0.2.0 shipped to PyPI while this file still said 0.1.0, so
+# `flashnode --help` reported 0.1.0 and — far worse — every agent registered
+# with the coordinator as agent_version="0.1.0" regardless of what was
+# actually installed (inventory/capabilities.py). Any version-based decision
+# the coordinator makes would have been reading a constant.
+try:
+    __version__ = _pkg_version("flashnode")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

flashnode-0.3.0/flashnode/config/local_data.py

@@ -0,0 +1,111 @@
+"""Local datasets: data the host owner lends to tasks without uploading it.
+
+    FLASHNODE_LOCAL_DATA="patients=/srv/data/patients-2026,labs=/srv/labs"
+
+The owner names a directory on their machine and gives it a LABEL. The label
+is what the agent advertises to the coordinator (`NodeRegistration.
+local_datasets`, so the placement gate can route a job that needs `patients`
+to a machine that has it); the PATH never leaves this machine. That asymmetry
+is the feature — a path leaks the owner's directory layout, their username,
+and frequently the dataset's identity, and none of that is needed to schedule
+work.
+
+Two rules make the rest of the system safe to write:
+
+- **Fail closed on garbage** (same judgement as `HostPolicy` above): a
+  malformed value raises rather than yielding the entries that happened to
+  parse. Half-applying the owner's intent is the worst outcome — they believe
+  two directories are exposed, one is, and the disagreement surfaces hours
+  later as a job that never places.
+- **A label is a name, not a path fragment.** It is restricted to
+  ``[A-Za-z0-9._-]`` here, once, so that no consumer downstream has to defend
+  itself: it is a map key, and a single container-side directory segment. If
+  someone later joins it to a host path, the charset already forbids the
+  escape.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+__all__ = ["LocalDataError", "LABEL_RE", "check_label", "parse_local_data",
+           "load_local_data", "LOCAL_DATA_ENV"]
+
+LOCAL_DATA_ENV = "FLASHNODE_LOCAL_DATA"
+
+#: The whole alphabet a dataset label may use. Deliberately narrower than
+#: anything a filesystem accepts: '/', '..' and whitespace are the characters
+#: that turn a name into a traversal, and they are simply not expressible.
+LABEL_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+class LocalDataError(ValueError):
+    """The owner's `FLASHNODE_LOCAL_DATA` cannot be honoured as written."""
+
+
+def check_label(label: str) -> str:
+    """Return `label` if it is a legal dataset label; raise otherwise.
+
+    Shared by the parser (owner-supplied labels) and the mount builder
+    (payload-supplied labels) so both ends of the wire agree on what a label
+    is — one definition, not two that can drift.
+    """
+    if not LABEL_RE.match(label) or label in (".", ".."):
+        raise LocalDataError(
+            f"illegal local dataset label {label!r}: labels are names, not "
+            "paths — use only [A-Za-z0-9._-]"
+        )
+    return label
+
+
+def parse_local_data(raw: str | None) -> dict[str, str]:
+    """Parse ``"label=/path,other=/path2"`` into ``{label: path}``.
+
+    Unset, empty, or all-separators means the owner did not opt in, and that
+    is the normal case: an empty map, no mounts, nothing advertised.
+    """
+    result: dict[str, str] = {}
+    for entry in (raw or "").split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        label, sep, path = entry.partition("=")
+        label, path = label.strip(), path.strip()
+        if not sep or not label or not path:
+            raise LocalDataError(
+                f"malformed {LOCAL_DATA_ENV} entry {entry!r}: expected "
+                "label=/absolute/path"
+            )
+        check_label(label)
+        if not path.startswith("/") and ":" not in path:
+            # A relative path would resolve against whatever directory the
+            # agent happens to have been started in — never what the owner
+            # meant, and a moving target between a shell run and a systemd
+            # unit. (The ':' escape hatch is a Windows drive letter, which
+            # the next check then judges on its own terms.)
+            raise LocalDataError(
+                f"local dataset {label!r} path {path!r} is not absolute — "
+                "refusing to resolve it against the agent's working directory"
+            )
+        if ":" in path and not re.match(r"^[A-Za-z]:[\\/]", path):
+            # `docker -v` splits its argument on ':'. A source containing one
+            # silently re-reads as src:dst:opts — i.e. as a mount the owner
+            # did not write. A Windows drive letter is the one form that is
+            # both legitimate and rewritable (hardening._bind_mount_source).
+            raise LocalDataError(
+                f"local dataset {label!r} path {path!r} contains ':', which "
+                "cannot be used as a bind-mount source"
+            )
+        if label in result:
+            raise LocalDataError(
+                f"local dataset label {label!r} is mapped twice — refusing to "
+                "guess which directory the owner meant"
+            )
+        result[label] = path
+    return result
+
+
+def load_local_data(env: dict[str, str] | None = None) -> dict[str, str]:
+    """The host owner's dataset map, from the environment."""
+    return parse_local_data((env if env is not None else os.environ).get(LOCAL_DATA_ENV))

{flashnode-0.2.0 → flashnode-0.3.0}/flashnode/executor/argv_runner.py

@@ -70,7 +70,13 @@ class ArgvDockerRunner:
         name = container_name(payload.get("task_id"))
         command = [
             "docker", "run", "--rm", "--name", name,
-            *harden_args(workdir, cpus=self.cpus, memory_gb=self.memory_gb),
+            *harden_args(
+                workdir, cpus=self.cpus, memory_gb=self.memory_gb,
+                # The host owner's local datasets this task asked for. Refused
+                # here (before any subprocess) if this host does not lend them
+                # — see hardening.local_data_mounts.
+                local_inputs=payload.get("local_inputs"),
+            ),
             *env_args,
             image,          # argv follows the image, where docker treats it
             *argv,          # as the container command: leading '-' is inert

{flashnode-0.2.0 → flashnode-0.3.0}/flashnode/executor/docker_runner.py

@@ -75,7 +75,12 @@ class DockerRunner:
         name = container_name(payload.get("task_id"))
         argv = [
             "docker", "run", "--rm", "--name", name,
-            *harden_args(workdir, cpus=self.cpus, memory_gb=self.memory_gb),
+            *harden_args(
+                workdir, cpus=self.cpus, memory_gb=self.memory_gb,
+                # See hardening.local_data_mounts: read-only, only what the
+                # payload named, and a refusal if this host does not lend it.
+                local_inputs=payload.get("local_inputs"),
+            ),
             image,
             "python", "-m", module,
             "--spec", f"{CONTAINER_WORKDIR}/spec.json",

{flashnode-0.2.0 → flashnode-0.3.0}/flashnode/executor/hardening.py

@@ -16,6 +16,9 @@ import sys
 import uuid
 from pathlib import Path, PureWindowsPath
 
+from flashnode.config.local_data import LocalDataError, check_label, load_local_data
+from flashnode.executor.runner import TaskExecutionError
+
 CONTAINER_WORKDIR = "/work"
 
 # Docker container names must match [a-zA-Z0-9][a-zA-Z0-9_.-]*. We prefix
@@ -112,14 +115,91 @@ def _bind_mount_source(workdir: Path) -> str:
     return str(workdir)
 
 
+def local_data_mounts(
+    local_inputs: object,
+    available: dict[str, str] | None = None,
+) -> list[str]:
+    """`-v` flags binding the host owner's local datasets READ-ONLY under
+    `/work/inputs/<label>`, for the labels this payload asked for.
+
+    This is the half of the local-data feature that never uploads anything:
+    the bytes stay on the owner's disk and the task reads them in place. Three
+    properties are load-bearing.
+
+    - **`:ro`, always.** The owner lends the data; they do not hand a
+      stranger's code write access to it. There is no flag to turn this off.
+    - **Only what was requested.** A payload that names `patients` gets
+      `patients`. A host that also lends `labs` does not silently expose it to
+      a job that never asked — least privilege, per task.
+    - **Refuse rather than run half-fed** (AGENTS.md rule 3, fail closed). A
+      label this host has not mapped is a `TaskExecutionError` naming the
+      label — the *task* fails and requeues elsewhere; the agent lives. It
+      should not be reachable at all, because the coordinator's placement gate
+      reads the same advertisement this host published, so arriving here means
+      gate and host disagree — precisely the moment to stop, not to improvise
+      an empty directory the workload would read as "no patients".
+
+    `local_inputs` comes from an untrusted payload, so it is type-checked and
+    charset-checked here rather than trusted to be the list the compiler
+    produced. A label is never joined to a host path: it is a map key, and one
+    container-side directory segment.
+
+    `available` defaults to the host owner's `FLASHNODE_LOCAL_DATA` — read
+    only when a task actually asks for something, so a host whose value is
+    malformed fails the tasks that need it rather than every task on the
+    machine.
+    """
+    if local_inputs is None:
+        return []
+    if not isinstance(local_inputs, list) or not all(
+        isinstance(name, str) for name in local_inputs
+    ):
+        raise TaskExecutionError(
+            "payload 'local_inputs' must be a list of local dataset labels"
+        )
+    if not local_inputs:
+        return []
+    if available is None:
+        try:
+            available = load_local_data()
+        except LocalDataError as exc:
+            # Barely reachable — `discover()` parses the same value at startup
+            # and the agent refuses to register on a malformed one. If it ever
+            # is reached, a misconfigured host fails a task; it does not die.
+            raise TaskExecutionError(f"host local-data config is unusable: {exc}") from None
+    args: list[str] = []
+    for label in local_inputs:
+        try:
+            check_label(label)
+        except LocalDataError as exc:
+            raise TaskExecutionError(str(exc)) from None
+        if label not in available:
+            raise TaskExecutionError(
+                f"task requires local dataset {label!r}, which this host does "
+                "not provide — refusing to run"
+            )
+        source = _bind_mount_source(Path(available[label]))
+        args += ["-v", f"{source}:{CONTAINER_WORKDIR}/inputs/{label}:ro"]
+    return args
+
+
 def harden_args(
     workdir: Path,
     *,
     cpus: float,
     memory_gb: float,
     pids_limit: int = 512,
+    local_inputs: object = None,
+    local_data: dict[str, str] | None = None,
 ) -> list[str]:
-    """Docker flags common to every sandboxed task."""
+    """Docker flags common to every sandboxed task.
+
+    `local_inputs` is the payload's list of local dataset labels (None or []
+    for the overwhelmingly common task that needs none, and then the flags are
+    byte-for-byte what they were before the feature existed). `local_data` is
+    the host owner's label→path map; it defaults to their environment, so a
+    runner never has to know where the map comes from.
+    """
     return [
         # the job never reaches the volunteer's LAN or the internet; the
         # agent is the courier for inputs, outputs, and checkpoints
@@ -137,5 +217,8 @@ def harden_args(
         "--memory-swap", f"{memory_gb}g",
         "--ulimit", "nofile=1024:1024",
         "-v", f"{_bind_mount_source(workdir)}:{CONTAINER_WORKDIR}",
+        # After the workdir mount, never before: these land *inside* it, at
+        # /work/inputs/<label>, and the outer mount has to exist first.
+        *local_data_mounts(local_inputs, local_data),
         "-w", CONTAINER_WORKDIR,
     ]

{flashnode-0.2.0 → flashnode-0.3.0}/flashnode/inventory/capabilities.py

@@ -13,6 +13,7 @@ import socket
 
 import psutil
 
+from flashnode.config.local_data import load_local_data
 from flashruntime.protocol.v1alpha1 import (
     NodeCapabilities,
     NodeEnvironment,
@@ -110,6 +111,16 @@ def discover(node_id: str, kubernetes_node: str,
         # coordinator's module gate is fail-open (unlike argv_capable), so
         # the default here matches every caller that doesn't pass it.
         module_capable=module_capable,
+        # The LABELS of the datasets this host owner lends to tasks
+        # (FLASHNODE_LOCAL_DATA) — never the paths. The coordinator needs the
+        # names to place a job that requires `patients` on a machine that has
+        # it; it has no use for `/srv/data/patients-2026`, which would leak
+        # the owner's directory layout, their username, and often the
+        # dataset's identity off the machine the whole feature exists to keep
+        # the data on. Sorted so the wire form is stable across restarts.
+        # A malformed value raises out of here rather than advertising a
+        # subset: an owner who typed it wrong must find out at startup.
+        local_datasets=sorted(load_local_data()),
         pool=labels.get("flashml.dev/pool", os.environ.get("FLASHNODE_POOL", "local")),
         runtime_profile=os.environ.get("FLASHNODE_RUNTIME_PROFILE", "kubernetes"),
         labels=labels,

flashnode-0.2.0/README.md → flashnode-0.3.0/flashnode.egg-info/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.4
+Name: flashnode
+Version: 0.3.0
+Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flashruntime<0.5,>=0.4
+Requires-Dist: psutil>=5.9
+Requires-Dist: websockets>=12
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
 # FlashNode
 
 > **The open host agent of the FlashML system.** Install FlashNode on a
@@ -43,8 +60,17 @@ flashnode work --coordinator http://<coordinator>:8100
 #   FLASHNODE_WORKDIR=$HOME/.cache/flashnode   (macOS + colima: VM-visible workdirs)
 #   FLASHNODE_WORKDIR=C:\Users\<you>\.flashnode  (Windows: must be under a
 #                                                 directory Docker Desktop shares)
+#   FLASHNODE_LOCAL_DATA=patients=/srv/data/patients-2026,labs=/srv/labs
+#                                    lend local directories to tasks by LABEL
 ```
 
+`FLASHNODE_LOCAL_DATA` lets you offer data **without uploading it**. Only the
+label names (`patients`, `labs`) are advertised to the coordinator — never the
+paths — and a task that names a label in its `local_inputs` gets that directory
+bind-mounted **read-only** at `/work/inputs/<label>`. A task asking for a label
+this machine does not lend is refused, not run half-fed; a task that asks for
+nothing sees nothing, exactly as before.
+
 If the coordinator enforces per-machine authentication
 (`FLASHML_NODE_TOKENS` set server-side), save the bearer token you were
 given before running `work`:

{flashnode-0.2.0 → flashnode-0.3.0}/flashnode.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ flashnode/agent/kube.py
 flashnode/artifacts/__init__.py
 flashnode/benchmark/__init__.py
 flashnode/config/__init__.py
+flashnode/config/local_data.py
 flashnode/executor/__init__.py
 flashnode/executor/archives.py
 flashnode/executor/argv_runner.py
@@ -45,4 +46,5 @@ tests/test_hardening.py
 tests/test_hardening_platform.py
 tests/test_identity.py
 tests/test_images_allowlist.py
-tests/test_interfaces.py
+tests/test_interfaces.py
+tests/test_local_data.py

{flashnode-0.2.0 → flashnode-0.3.0}/flashnode.egg-info/requires.txt

@@ -1,4 +1,4 @@
-flashruntime<0.4,>=0.3
+flashruntime<0.5,>=0.4
 psutil>=5.9
 websockets>=12
 cryptography>=42

{flashnode-0.2.0 → flashnode-0.3.0}/pyproject.toml

@@ -4,10 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashnode"
-# 0.2.0 is the FIRST published release; 0.1.0 never reached PyPI. Released from
-# the Zolli-Labs/flashml monorepo by pushing a `flashnode-v0.2.0` tag, and only
-# AFTER flashruntime 0.3.0 is on PyPI — see the floor below.
-version = "0.2.0"
+# 0.3.0 lends a host directory to tasks by label (FLASHNODE_LOCAL_DATA), which
+# needs flashruntime 0.4's NodeRegistration.local_datasets to advertise what
+# this host can serve. (0.2.0 was the first published release; 0.2.1 fixed a
+# hardcoded __version__ that made every agent register as 0.1.0.) Released from
+# the Zolli-Labs/flashml monorepo by pushing a `flashnode-vX.Y.Z` tag, and only
+# AFTER the flashruntime floor below is on PyPI.
+version = "0.3.0"
 description = "Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -19,12 +22,14 @@ dependencies = [
     # coordinator's fail-open module gate happens to tolerate that, but
     # argv_capable's fail-closed gate does not.
     #
-    # Raised to >=0.3,<0.4 for the first published release. 0.3.0 is the first
-    # flashruntime that exists on PyPI at all, so any lower floor names
-    # something a volunteer cannot install. The upper bound is deliberate: this
-    # agent runs on machines we cannot reach, so it must never be silently
-    # upgraded across a protocol-breaking runtime release.
-    "flashruntime>=0.3,<0.4",
+    # Raised to >=0.4,<0.5: this agent advertises local_datasets, which only
+    # exists from flashruntime 0.4. On 0.3 pydantic silently ignores the extra
+    # kwarg, so the host would advertise nothing and the coordinator's gate
+    # would simply never place local-data work on it — fail-closed, but
+    # INVISIBLY, which is the worst way for a floor to be wrong. The upper
+    # bound is deliberate: this agent runs on machines we cannot reach, so it
+    # must never be silently upgraded across a protocol-breaking release.
+    "flashruntime>=0.4,<0.5",
     "psutil>=5.9",
     "websockets>=12",
     "cryptography>=42",

{flashnode-0.2.0 → flashnode-0.3.0}/tests/test_capabilities.py

@@ -108,3 +108,22 @@ def test_env_and_label_sandbox_capable_still_work_without_argv(monkeypatch):
     node_meta = {"metadata": {"labels": {"flashml.dev/sandbox-capable": "true"}}}
     reg = discover("node-1", kubernetes_node="", node_meta=node_meta, argv_capable=False)
     assert reg.sandbox_capable is True
+
+
+def test_registration_reports_the_installed_version():
+    """The coordinator's `agent_version` must be what is actually installed.
+
+    It was a hardcoded literal in flashnode/__init__.py, and it drifted the
+    first time it mattered: 0.2.0 shipped to PyPI while the literal still read
+    0.1.0, so every agent in the fleet would have registered as 0.1.0 no matter
+    what its owner had installed. Any version-based decision the coordinator
+    makes — refusing a too-old protocol, reporting upgrade coverage — would
+    have been reading a constant.
+
+    Compare against installed metadata rather than a literal here, or this
+    test becomes the third source of truth it exists to prevent.
+    """
+    from importlib.metadata import version
+
+    reg = discover("n-test", kubernetes_node="", node_meta=None)
+    assert reg.agent_version == version("flashnode")

flashnode-0.3.0/tests/test_local_data.py

@@ -0,0 +1,325 @@
+"""`FLASHNODE_LOCAL_DATA` — a host owner lends a directory to tasks by LABEL.
+
+    FLASHNODE_LOCAL_DATA="patients=/srv/data/patients-2026,labs=/srv/labs"
+
+Two invariants carry the whole feature and are what these tests exist to pin:
+
+1. **The data never moves.** Nothing is uploaded; the coordinator learns the
+   label NAMES and never the host paths. A path is host-private — it leaks the
+   owner's directory layout, their username, and often the dataset's identity.
+2. **A label is a name, never a path fragment.** It is matched against the
+   owner's map and used as one container-side directory segment; it is never
+   joined to a host path. The charset test below keeps that true even if
+   someone later changes the assumption.
+
+The mount assertions read the CONSTRUCTED argv, so they need no Docker daemon
+— same style as test_hardening.py.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from flashnode.config.local_data import (
+    LocalDataError,
+    load_local_data,
+    parse_local_data,
+)
+from flashnode.executor.argv_runner import ArgvDockerRunner
+from flashnode.executor.hardening import CONTAINER_WORKDIR, harden_args
+from flashnode.executor.runner import TaskExecutionError
+from flashnode.inventory.capabilities import discover
+
+ENV = "FLASHNODE_LOCAL_DATA"
+
+
+# -- parsing ------------------------------------------------------------------
+
+
+def test_parses_label_path_pairs():
+    assert parse_local_data("a=/x,b=/y") == {"a": "/x", "b": "/y"}
+
+
+def test_parses_a_single_pair_and_tolerates_surrounding_whitespace():
+    assert parse_local_data("  patients = /srv/data/patients-2026 ") == {
+        "patients": "/srv/data/patients-2026"
+    }
+
+
+@pytest.mark.parametrize("raw", [None, "", "   ", ",", " , "])
+def test_unset_or_empty_is_no_local_data(raw):
+    """The default path: a host that never opted in advertises nothing and
+    mounts nothing."""
+    assert parse_local_data(raw) == {}
+
+
+def test_load_local_data_reads_the_env_var(monkeypatch):
+    monkeypatch.setenv(ENV, "labs=/srv/labs")
+    assert load_local_data() == {"labs": "/srv/labs"}
+    monkeypatch.delenv(ENV)
+    assert load_local_data() == {}
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "good=/x,garbage",       # an entry with no '=' at all
+        "good=/x,=/y",           # empty label
+        "good=/x,b=",            # empty path
+        "good=/x,b=relative",    # a relative path resolves against the agent's
+                                 # cwd, which is not what the owner meant
+    ],
+)
+def test_a_malformed_entry_is_refused_not_partially_accepted(raw):
+    """Half-applying the owner's intent is the dangerous outcome: they believe
+    two directories are exposed, the agent exposes one, and the mismatch shows
+    up as an unplaceable job hours later. Refuse the whole value."""
+    with pytest.raises(LocalDataError):
+        parse_local_data(raw)
+
+
+def test_a_duplicate_label_is_refused():
+    """Two paths cannot both be `patients`; silently keeping the last one
+    would expose a directory the owner did not intend for that name."""
+    with pytest.raises(LocalDataError):
+        parse_local_data("patients=/srv/a,patients=/srv/b")
+
+
+@pytest.mark.parametrize(
+    "label",
+    ["pa/tients", "..", ".", "../../etc", "pat ients", "pat*", "pat:ients", "él"],
+)
+def test_a_label_outside_the_safe_charset_is_rejected(label):
+    """A label is never joined to a filesystem path — but it IS used as one
+    container-side directory segment, and it is the key an untrusted payload
+    looks up. Restricting it to [A-Za-z0-9._-] (and never '.'/'..') means a
+    later refactor that DOES join it to a path cannot escape a directory."""
+    with pytest.raises(LocalDataError) as exc:
+        parse_local_data(f"{label}=/srv/x")
+    assert label in str(exc.value)
+
+
+def test_a_path_that_cannot_be_a_bind_mount_source_is_refused():
+    """`docker -v` splits its argument on ':'. A host path containing one
+    would silently reinterpret as src:dst:opts — refuse it at parse time
+    rather than construct a mount that means something else."""
+    with pytest.raises(LocalDataError):
+        parse_local_data("labs=/srv/we:ird")
+
+
+# -- advertising: names travel, paths do not ----------------------------------
+
+
+def test_discover_advertises_the_label_names(monkeypatch):
+    monkeypatch.setenv(ENV, "patients=/srv/data/patients-2026,labs=/srv/labs")
+    reg = discover("node-1", kubernetes_node="", node_meta=None)
+    assert reg.local_datasets == ["labs", "patients"]   # sorted: stable on the wire
+
+
+def test_discover_never_sends_the_host_paths(monkeypatch):
+    """A host path is host-private. It must not travel to the coordinator in
+    any field — not local_datasets, not labels, not by accident."""
+    monkeypatch.setenv(ENV, "patients=/srv/data/patients-2026,labs=/srv/labs")
+    reg = discover("node-1", kubernetes_node="", node_meta=None)
+    wire = reg.model_dump_json()
+    assert "/srv/data/patients-2026" not in wire
+    assert "/srv/labs" not in wire
+    assert "/srv" not in wire
+    assert "patients" in wire and "labs" in wire        # the names DID travel
+
+
+def test_discover_advertises_nothing_when_the_owner_opted_out(monkeypatch):
+    monkeypatch.delenv(ENV, raising=False)
+    assert discover("node-1", kubernetes_node="", node_meta=None).local_datasets == []
+
+
+def test_discover_refuses_to_start_on_a_malformed_value(monkeypatch):
+    """Fail closed, like config/HostPolicy: the owner must learn their typo
+    now, not by wondering why their dataset is never used."""
+    monkeypatch.setenv(ENV, "patients=/srv/a,garbage")
+    with pytest.raises(LocalDataError):
+        discover("node-1", kubernetes_node="", node_meta=None)
+
+
+# -- mounting -----------------------------------------------------------------
+
+
+def test_requested_label_is_mounted_read_only_at_inputs(tmp_path):
+    args = harden_args(
+        tmp_path, cpus=1.0, memory_gb=1.0,
+        local_inputs=["patients"],
+        local_data={"patients": "/srv/data/patients-2026", "labs": "/srv/labs"},
+    )
+    assert f"/srv/data/patients-2026:{CONTAINER_WORKDIR}/inputs/patients:ro" in args
+    # exactly one -v beyond the workdir mount, and the label the task did NOT
+    # ask for is not mounted
+    assert not any("/srv/labs" in a for a in args)
+
+
+def test_the_mount_is_read_only_not_merely_present(tmp_path):
+    """Read-only is the entire consent model: the owner lends the data, they
+    do not hand a stranger's code write access to it."""
+    args = harden_args(
+        tmp_path, cpus=1.0, memory_gb=1.0,
+        local_inputs=["patients"], local_data={"patients": "/srv/p"},
+    )
+    mount = next(a for a in args if a.startswith("/srv/p:"))
+    assert mount.endswith(":ro")
+
+
+def test_several_labels_all_mount(tmp_path):
+    args = harden_args(
+        tmp_path, cpus=1.0, memory_gb=1.0,
+        local_inputs=["patients", "labs"],
+        local_data={"patients": "/srv/p", "labs": "/srv/l"},
+    )
+    assert f"/srv/p:{CONTAINER_WORKDIR}/inputs/patients:ro" in args
+    assert f"/srv/l:{CONTAINER_WORKDIR}/inputs/labs:ro" in args
+
+
+def test_a_label_the_host_has_not_mapped_is_refused_and_named(tmp_path):
+    with pytest.raises(TaskExecutionError) as exc:
+        harden_args(
+            tmp_path, cpus=1.0, memory_gb=1.0,
+            local_inputs=["patients"], local_data={"labs": "/srv/l"},
+        )
+    assert "patients" in str(exc.value)
+
+
+def test_a_hostile_label_in_the_payload_is_refused(tmp_path):
+    """The payload is attacker-influenced from job submission onward. It must
+    not be able to name a mount destination of its choosing."""
+    for label in ["../../root", "/etc", "a b", ".."]:
+        with pytest.raises(TaskExecutionError):
+            harden_args(
+                tmp_path, cpus=1.0, memory_gb=1.0,
+                local_inputs=[label], local_data={"labs": "/srv/l"},
+            )
+
+
+def test_local_inputs_must_be_a_list_of_strings(tmp_path):
+    for bad in ["patients", 3, [1], {"patients": "/x"}]:
+        with pytest.raises(TaskExecutionError):
+            harden_args(
+                tmp_path, cpus=1.0, memory_gb=1.0,
+                local_inputs=bad, local_data={"patients": "/srv/p"},
+            )
+
+
+def test_the_default_path_is_byte_for_byte_unchanged(tmp_path, monkeypatch):
+    """No FLASHNODE_LOCAL_DATA, no local_inputs: every existing host must
+    produce exactly the argv it produced before this feature existed."""
+    monkeypatch.delenv(ENV, raising=False)
+    before = harden_args(tmp_path, cpus=2.0, memory_gb=4.0)
+    for extra in ({}, {"local_inputs": None}, {"local_inputs": []}):
+        assert harden_args(tmp_path, cpus=2.0, memory_gb=4.0, **extra) == before
+
+
+def test_no_local_inputs_mounts_nothing_even_when_the_host_offers_data(tmp_path,
+                                                                       monkeypatch):
+    monkeypatch.setenv(ENV, "patients=/srv/p")
+    args = harden_args(tmp_path, cpus=1.0, memory_gb=1.0)
+    assert not any("/srv/p" in a for a in args)
+
+
+def test_a_broken_host_config_only_fails_the_tasks_that_need_it(tmp_path, monkeypatch):
+    """The owner's typo must not take down every unrelated task on the
+    machine — the map is read only when a task actually asks for a label."""
+    monkeypatch.setenv(ENV, "garbage")
+    harden_args(tmp_path, cpus=1.0, memory_gb=1.0)              # no request: fine
+    with pytest.raises(TaskExecutionError):
+        harden_args(tmp_path, cpus=1.0, memory_gb=1.0, local_inputs=["patients"])
+
+
+def test_the_host_map_defaults_to_the_env_var(tmp_path, monkeypatch):
+    """The runners do not have to know where the map comes from — the owner's
+    env var is the single source."""
+    monkeypatch.setenv(ENV, "patients=/srv/p")
+    args = harden_args(tmp_path, cpus=1.0, memory_gb=1.0, local_inputs=["patients"])
+    assert f"/srv/p:{CONTAINER_WORKDIR}/inputs/patients:ro" in args
+
+
+# -- the runners actually forward the request ---------------------------------
+#
+# A mount is only as real as the payload key reaching it: without these the
+# feature would be "implemented" in hardening.py and dead in every runner.
+
+
+def _argv_payload(**over):
+    base = {"argv": ["python", "train.py"], "image": "ghcr.io/zolli/trainer:1.0",
+            "task_id": "task-000", "local_inputs": ["patients"]}
+    base.update(over)
+    return base
+
+
+def _fake_ok_run(outdir: Path):
+    def run(cmd, **kw):
+        if cmd[:2] == ["docker", "run"]:
+            (outdir / "metrics.json").write_text("{}")
+        return mock.Mock(returncode=0, stdout=b"", stderr=b"")
+    return run
+
+
+def test_argv_runner_forwards_local_inputs_to_the_mount(tmp_path, monkeypatch):
+    monkeypatch.setenv(ENV, "patients=/srv/p")
+    runner = ArgvDockerRunner(allowed_images=frozenset({"ghcr.io/zolli/trainer:1.0"}))
+    with mock.patch("subprocess.run", side_effect=_fake_ok_run(tmp_path / "out")) as sp:
+        runner.run(_argv_payload(), tmp_path, {})
+    cmd = sp.call_args_list[0].args[0]
+    assert f"/srv/p:{CONTAINER_WORKDIR}/inputs/patients:ro" in cmd
+
+
+def test_argv_runner_refuses_a_task_this_host_cannot_serve(tmp_path, monkeypatch):
+    """This node should never have been leased the task (the coordinator's
+    placement gate reads the same advertisement), so reaching here means the
+    two disagree — fail the task, do not run it half-fed."""
+    monkeypatch.setenv(ENV, "labs=/srv/l")
+    runner = ArgvDockerRunner(allowed_images=frozenset({"ghcr.io/zolli/trainer:1.0"}))
+    with mock.patch("subprocess.run") as sp:
+        with pytest.raises(TaskExecutionError, match="patients"):
+            runner.run(_argv_payload(), tmp_path, {})
+    sp.assert_not_called()      # refused before docker was ever invoked
+
+
+def test_argv_runner_unchanged_without_local_inputs(tmp_path, monkeypatch):
+    monkeypatch.setenv(ENV, "patients=/srv/p")
+    runner = ArgvDockerRunner(allowed_images=frozenset({"ghcr.io/zolli/trainer:1.0"}))
+    payload = _argv_payload()
+    payload.pop("local_inputs")
+    with mock.patch("subprocess.run", side_effect=_fake_ok_run(tmp_path / "out")) as sp:
+        runner.run(payload, tmp_path, {})
+    assert not any("/srv/p" in a for a in sp.call_args_list[0].args[0])
+
+
+def test_docker_runner_forwards_local_inputs_to_the_mount(tmp_path, monkeypatch):
+    from flashnode.executor.docker_runner import DockerRunner
+
+    monkeypatch.setenv(ENV, "patients=/srv/p")
+    runner = DockerRunner(allowed_images=frozenset({"ghcr.io/zolli/trainer:1.0"}))
+    payload = {"module": "flashml_workloads.sgd_trainer",
+               "image": "ghcr.io/zolli/trainer:1.0", "task_id": "t1",
+               "local_inputs": ["patients"]}
+    with mock.patch("subprocess.run", side_effect=_fake_ok_run(tmp_path / "out")) as sp:
+        runner.run(payload, tmp_path, {})
+    cmd = sp.call_args_list[0].args[0]
+    assert f"/srv/p:{CONTAINER_WORKDIR}/inputs/patients:ro" in cmd
+
+
+def test_nothing_about_the_host_path_reaches_the_task_spec(tmp_path, monkeypatch):
+    """DockerRunner writes spec.json for the workload. The task sees the
+    container path; the host path is not the task's business either."""
+    from flashnode.executor.docker_runner import DockerRunner
+
+    monkeypatch.setenv(ENV, "patients=/srv/data/patients-2026")
+    runner = DockerRunner(allowed_images=frozenset({"ghcr.io/zolli/trainer:1.0"}))
+    payload = {"module": "flashml_workloads.sgd_trainer",
+               "image": "ghcr.io/zolli/trainer:1.0", "task_id": "t1",
+               "local_inputs": ["patients"]}
+    with mock.patch("subprocess.run", side_effect=_fake_ok_run(tmp_path / "out")):
+        runner.run(payload, tmp_path, {})
+    spec = json.loads((tmp_path / "spec.json").read_text())
+    assert "/srv/data/patients-2026" not in json.dumps(spec)

flashnode-0.2.0/flashnode/__init__.py

@@ -1,7 +0,0 @@
-"""FlashNode: the open host agent of the FlashML system.
-
-Installed by resource contributors to safely execute distributed ML tasks.
-See README.md and docs/SYSTEM_OVERVIEW.md.
-"""
-
-__version__ = "0.1.0"