flashnode 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

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/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/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/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/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.1.dist-info → flashnode-0.3.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flashnode
-Version: 0.2.1
+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.1.dist-info → flashnode-0.3.0.dist-info}/RECORD

@@ -6,12 +6,13 @@ flashnode/agent/kube.py,sha256=3olz_oVv0RdDNogFwakiXyUD-q8J7PKVZ5_pABWiQew,1400
 flashnode/artifacts/__init__.py,sha256=J3VdNm08o0AL1kLD_cjsxmGgm8e_uhwnljvYMI5nmek,177
 flashnode/benchmark/__init__.py,sha256=YC66KYR-W7NANMtV0Y8kpixdzBxslgsaK9mDYaDxbBI,4168
 flashnode/config/__init__.py,sha256=t6C8iJkWyIGJmdv9kqh30iFkcw6vkdy73UkPnvDbZhs,4404
+flashnode/config/local_data.py,sha256=Q-eFDd9BM7UkHkA9SYN4Mcv3xBFsTeSuZMjQIKqPxFc,4919
 flashnode/executor/__init__.py,sha256=6wQKrF-0zl5jAU21_xkeNA3P3iQ5jhbx0IFUlXdjkNU,1035
 flashnode/executor/archives.py,sha256=HsFpwR_MyICSp7wkw4Wr_4rmobvnaT_d2l2I6LSNJkI,12472
-flashnode/executor/argv_runner.py,sha256=OuvInw5s6QWqdGaLNrYg70NzGVpel98oeuRU5c_XMbg,5284
+flashnode/executor/argv_runner.py,sha256=fKc9Fk0RdJdFVAWAzKEvqLp8cLtvxQALaTBj0QeWszk,5586
 flashnode/executor/client.py,sha256=0mSkjIrb1M66Jz9ofL-OqM7fu13arrMjEqTfKgYl2a8,7473
-flashnode/executor/docker_runner.py,sha256=J9Ym1nY18RvFSbnA5b71Zu-PV8Lf34mHF-rQ6YpNh7I,5072
-flashnode/executor/hardening.py,sha256=xha8ab-gM16qAsqEXk0s_zywcmsV323f5cODJ_Jf9Gc,5984
+flashnode/executor/docker_runner.py,sha256=6o6rB7RarSoAd3I1UGB6le92d6J5flNJ7IArI6G4Grw,5315
+flashnode/executor/hardening.py,sha256=irdvMGMbupbBJdzsCfLWN6PHmSDlXRGMSqMCIcMaWtg,9969
 flashnode/executor/images.py,sha256=OGJt36m1HKwUOErN_MR_sixG3gxIFKH8htfTVK7Opeg,7563
 flashnode/executor/loop.py,sha256=E_gBh6A-T3oEQmR-lvYDR2k5NXrYSySX61RIiOgy4To,16847
 flashnode/executor/runner.py,sha256=AT6M80QDB9p8GFIpT7rgym2Tus-IUNnh5eBpIPavyx0,4218
@@ -20,11 +21,11 @@ flashnode/identity/credentials.py,sha256=y-OGUYEyv5J5z_FUT01tSYWGdpPfC9z0F6sX5Ay
 flashnode/identity/enrol.py,sha256=GHvBLQDWdCTfDR45CQ1C70Jd00wFINfcxzvcDRC4ofg,6622
 flashnode/identity/store.py,sha256=ZGCPhSiH63PAE3GRPGrlhlc2nNPgstDSMtNPu4N-OCE,1734
 flashnode/inventory/__init__.py,sha256=epNMD283icBq-jjg5rN0u51tpSWm1RTw8PhkAXr88fM,193
-flashnode/inventory/capabilities.py,sha256=XyE3pAVHG5Tvsk6kslJtx7vo5UXWYP4ZOiVgEym5FpY,4602
+flashnode/inventory/capabilities.py,sha256=3jMrE7Ua41O5FqU_keoNz8t4ExagDZgqYFGxVHmEfa4,5377
 flashnode/telemetry/__init__.py,sha256=MRJ99bQykL1do3dQYMNiQABmYhTuEkgZdfsm5Np0KD4,3363
-flashnode-0.2.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-flashnode-0.2.1.dist-info/METADATA,sha256=tiJGSxIxWrAco9mnh9eBOQZS8tk-GIyazdm6_MfnYNE,7522
-flashnode-0.2.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-flashnode-0.2.1.dist-info/entry_points.txt,sha256=rn0W3v0MU8yhzp6b3j9frGA92h5bN3vgqMQRuYAoBkM,55
-flashnode-0.2.1.dist-info/top_level.txt,sha256=BErbFoSvml51DxXayRtL5l8_1p59Z4XnC2bmKeaWdBo,10
-flashnode-0.2.1.dist-info/RECORD,,
+flashnode-0.3.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+flashnode-0.3.0.dist-info/METADATA,sha256=4LPXSLr0DK4mv7R9Z1amKxAb_FRe5qrs58-MCNJ0Yho,8114
+flashnode-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+flashnode-0.3.0.dist-info/entry_points.txt,sha256=rn0W3v0MU8yhzp6b3j9frGA92h5bN3vgqMQRuYAoBkM,55
+flashnode-0.3.0.dist-info/top_level.txt,sha256=BErbFoSvml51DxXayRtL5l8_1p59Z4XnC2bmKeaWdBo,10
+flashnode-0.3.0.dist-info/RECORD,,