Pentest fixes: pin the runtime source host, evict rather than refuse; say on the page that llama.cpp is fetched

distinct_agent/runtime.py

@@ -89,21 +89,42 @@ class RuntimeVerificationError(RuntimeUnavailable):
     """The bytes arrived but did not match the recorded digest."""
 
 
+def permitted_source(url: str) -> bool:
+    """Whether this worker is willing to fetch a runtime from ``url`` at all.
+
+    THE FIRST URL NEEDS THE SAME CHECK AS EVERY REDIRECT.
+
+    The redirect handler below refuses to follow a hop off GitHub, which is the
+    obvious half of the rule; the half that a penetration test found missing was
+    the URL the download *starts* at. That one comes out of a JSON file, so
+    anybody who could alter ``llama_runtime.json`` -- a bad commit, a merged
+    pull request nobody read closely, a tampered checkout -- could point every
+    volunteer's worker at a host of their choosing and have it make the request.
+
+    The recorded digest still means no substituted *file* is ever installed, so
+    this was not a path to running someone else's code. It was still an
+    arbitrary outbound request made by every worker that updated, which is a
+    thing worth having and not a thing worth leaving lying around. Now the
+    allowlist is applied where the URL is read, so a pin pointing anywhere else
+    is not a download that fails: it is a pin that does not count as recorded.
+    """
+
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme != "https":
+        return False
+    host = (parsed.hostname or "").casefold().rstrip(".")
+    if not host:
+        return False
+    return any(
+        host == allowed or host.endswith("." + allowed)
+        for allowed in RUNTIME_REDIRECT_HOSTS
+    )
+
+
 class _RuntimeRedirects(urllib.request.HTTPRedirectHandler):
     max_redirections = 10
 
-    @staticmethod
-    def _permitted(url: str) -> bool:
-        parsed = urllib.parse.urlsplit(url)
-        if parsed.scheme != "https":
-            return False
-        host = (parsed.hostname or "").casefold().rstrip(".")
-        if not host:
-            return False
-        return any(
-            host == allowed or host.endswith("." + allowed)
-            for allowed in RUNTIME_REDIRECT_HOSTS
-        )
+    _permitted = staticmethod(permitted_source)
 
     def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D102
         if not self._permitted(newurl):
@@ -134,7 +155,7 @@ class RuntimePin:
 
     @property
     def recorded(self) -> bool:
-        return bool(self.url and len(self.sha256) == 64)
+        return bool(self.url and len(self.sha256) == 64 and permitted_source(self.url))
 
 
 def platform_key(system: str = "", machine: str = "") -> str:
@@ -267,6 +288,13 @@ def ensure(
         return existing
 
     resolved = key or platform_key()
+    raw = load_pins(pins_path).get(resolved)
+    if raw is not None and raw.url and not permitted_source(raw.url):
+        raise RuntimeUnavailable(
+            f"the recorded llama.cpp source for {resolved} is {raw.url!r}, which is "
+            "not GitHub. Nothing was fetched. A pin that points anywhere else has "
+            "been tampered with; report it rather than working around it."
+        )
     pin = pin_for(resolved, pins_path)
     if pin is None:
         raise RuntimeUnavailable(

distinct_server/control_plane.py

@@ -367,11 +367,37 @@ class ControlPlane:
             except ValueError as exc:
                 raise ValidationError("claim code is not a usable code") from exc
 
-            unclaimed = sum(1 for record in self._agents.values() if record.claim_digest)
-            if unclaimed >= self.limits.max_unclaimed_agents:
-                raise CapacityError(
-                    "too many workers are waiting to be claimed; try again shortly"
-                )
+            # A FULL POOL MUST NOT BE A CLOSED DOOR.
+            #
+            # A penetration test filled this pool from one unauthenticated
+            # client at about six registrations a second, and the ceiling then
+            # did exactly what a ceiling does: it refused everybody, including
+            # the volunteer who had just started a worker for the first time.
+            # Protecting the registry by turning the feature off for real users
+            # is the wrong trade, and it is the trade an attacker was choosing.
+            #
+            # So a full pool evicts its oldest waiter instead. A legitimate
+            # registration now always succeeds; what a flood costs is the slot
+            # of whoever registered longest ago, and a flood mostly evicts its
+            # own earlier entries because it owns nearly all of them.
+            #
+            # RESIDUAL RISK, STATED RATHER THAN PAPERED OVER. Sustained flooding
+            # can still evict a real worker in the window between it printing a
+            # code and its owner typing that code in. The worker says so, in
+            # those words, and starting it again gives a fresh code. Closing
+            # that gap properly needs per-source limiting, which this layer
+            # cannot do: it has no address, by design. The place for it is the
+            # route in front, and it is not pretended to be here.
+            waiting = sorted(
+                (
+                    (record.claim_expires_at, agent_id)
+                    for agent_id, record in self._agents.items()
+                    if record.claim_digest
+                ),
+            )
+            while len(waiting) >= self.limits.max_unclaimed_agents:
+                _, oldest = waiting.pop(0)
+                del self._agents[oldest]
             if len(self._agents) >= self.limits.max_agents:
                 raise CapacityError("agent registry is full")
             if any(

distinct_server/models.py

@@ -81,7 +81,7 @@ class ControlPlaneLimits:
     #: How long an unclaimed worker waits to be claimed before the server
     #: forgets it. Long enough to walk to the browser, short enough that an
     #: abandoned worker does not hold a slot.
-    claim_ttl_seconds: float = 900.0
+    claim_ttl_seconds: float = 600.0
     poll_interval_seconds: float = 5.0
     missed_polls_before_offline: int = 3
     # A floor on the offline threshold so that lowering the poll interval

distinct_server/render.py

@@ -336,32 +336,40 @@ def join_this_server(
         "a <code>setup.py</code> this project does not have.</p>"
     )
 
-    # STEP THREE EXISTS BECAUSE THE PAGE SENT PEOPLE INTO A WALL IT NEVER
-    # MENTIONED.
+    # STEP THREE IS NOT "GO AND FETCH A DEPENDENCY".
     #
-    # The panel used to be clone, install, run. A volunteer who followed it
-    # exactly got through all three and then met "This worker has no llama.cpp
-    # to run a model with" from the agent -- a requirement the page had never
-    # named, after a wait long enough to feel like the install had worked.
-    # Their words: the setup "is not the same as what is on the website".
+    # It was, briefly, and that was a bad answer to a fair complaint. The panel
+    # first said nothing about llama.cpp at all, so a volunteer got through
+    # every step and then met "this worker has no llama.cpp to run a model
+    # with" -- a requirement the page had never named. The fix for that was a
+    # step telling them to go to another project's releases page, pick the
+    # right build out of a dozen, unzip it and edit their PATH, and the
+    # reaction to that was the right one: *why do I have to provide this, it
+    # should be baked into the repo*.
     #
-    # llama.cpp genuinely is a separate program, and it genuinely is optional:
-    # a worker with no runner still pairs and still offers every tool and skill
-    # in the library, which is most of what this network does. So this is a
-    # step with two honest endings rather than a prerequisite dressed as a
-    # warning, and the run command in step four follows whichever was chosen.
+    # It cannot be in the repository -- a llama.cpp release is around a hundred
+    # megabytes per platform per accelerator, and a Space clone would carry all
+    # of them -- but "not in the repository" was never the same thing as "your
+    # problem". The worker now fetches the pinned build itself and verifies it
+    # against a recorded SHA-256 before installing it, exactly as it already
+    # did for model weights. See distinct_agent/runtime.py.
+    #
+    # So this step is no longer an instruction. It is a description of what the
+    # command in the next step will do, which is here because a worker that
+    # quietly downloads twenty megabytes should say so first.
     runner = (
-        '<p class="c-join__note">A model needs a program to run it, and that program '
-        "is <strong>llama.cpp</strong> — a separate project, not part of this one. "
-        'Download a build from <a class="c-join__link" href="https://github.com/'
-        'ggml-org/llama.cpp/releases" target="_blank" rel="noopener noreferrer">'
-        "github.com/ggml-org/llama.cpp/releases</a>, unzip it, and put "
-        "<code>llama-server</code> on your PATH — or drop it in a <code>runtime</code> "
-        "folder beside this one, where the worker looks first.</p>"
-        '<p class="c-join__note">Not interested in running models? Add '
-        "<code>--demo-runner</code> to the command in the next step. The worker still "
-        "pairs, and still runs every tool and skill in the library on your machine; "
-        "only the model's own replies are absent. You can add llama.cpp later.</p>"
+        '<p class="c-join__note">Nothing to install by hand. A model needs '
+        "<strong>llama.cpp</strong> to run it, and the worker fetches the pinned "
+        "build on its first start — about 20 MB — then checks it against a "
+        "recorded SHA-256 before installing it. If the bytes do not match, "
+        "nothing is installed and it says so.</p>"
+        '<p class="c-join__note">Already have a build you would rather use, or '
+        "want a CUDA or Metal one? Pass "
+        "<code>--llama-server /path/to/llama-server</code> and nothing is "
+        "downloaded. On a metered connection, <code>--no-fetch-runtime</code> "
+        "stops it fetching anything. And <code>--demo-runner</code> starts the "
+        "worker with no model at all — it still joins, and still runs every tool "
+        "and skill in the library.</p>"
     )
 
     # STEP FOUR: the run, with this server's address and this browser's own
@@ -408,7 +416,7 @@ def join_this_server(
         f"{install}</div></li>"
         '<li class="c-step-num"><span class="c-step-num__n">3</span>'
         '<div class="c-step-num__body">'
-        '<p class="c-step-num__head">Get something to run the models with</p>'
+        '<p class="c-step-num__head">What it needs to run a model</p>'
         f"{runner}</div></li>"
         '<li class="c-step-num"><span class="c-step-num__n">4</span>'
         '<div class="c-step-num__body"><p class="c-step-num__head">Run it, and claim it</p>'

tests/test_claim_flow.py

@@ -111,15 +111,48 @@ def test_an_unclaimed_worker_expires(plane: ControlPlane) -> None:
         plane.claim_agent(code, "user:alice", now=later)
 
 
-def test_unclaimed_registrations_have_a_ceiling(plane: ControlPlane) -> None:
+def test_the_unclaimed_pool_is_bounded(plane: ControlPlane) -> None:
     """The one unauthenticated write on this server cannot be accumulated."""
 
-    made = 0
+    for _ in range(plane.limits.max_unclaimed_agents * 3):
+        plane.register_unclaimed(_caps(), new_pairing_code())
+    waiting = sum(1 for r in plane._agents.values() if r.claim_digest)
+    assert waiting <= plane.limits.max_unclaimed_agents
+
+
+def test_a_flood_never_locks_a_real_volunteer_out(plane: ControlPlane) -> None:
+    """A full pool evicts its oldest waiter rather than refusing everybody.
+
+    Refusing is what an attacker filling the pool is trying to buy: the feature
+    turned off for real users. The oldest waiter loses its slot instead, and a
+    flood mostly evicts its own earlier entries.
+    """
+
+    for index in range(plane.limits.max_unclaimed_agents):
+        plane.register_unclaimed(_caps(f"flood{index}"), new_pairing_code(), now=1000.0 + index)
+
+    mine = new_pairing_code()
+    credential = plane.register_unclaimed(_caps("volunteer"), mine, now=2000.0)
+    assert plane.claim_state(credential.agent_id, now=2000.0) == "waiting"
+    assert plane.claim_agent(mine, "user:alice", now=2000.0) == credential.agent_id
+
+
+def test_the_registry_itself_still_has_a_hard_ceiling(plane: ControlPlane) -> None:
+    """Eviction bounds the unclaimed pool; claimed agents are still capped."""
+
+    codes = [new_pairing_code() for _ in range(plane.limits.max_unclaimed_agents)]
+    for index, code in enumerate(codes):
+        plane.register_unclaimed(_caps(f"w{index}"), code)
+    for index, code in enumerate(codes):
+        plane.claim_agent(code, f"user:{index}")
+    made = len(codes)
     with pytest.raises(CapacityError):
-        for _ in range(plane.limits.max_unclaimed_agents + 10):
-            plane.register_unclaimed(_caps(), new_pairing_code())
+        while made < plane.limits.max_agents + 10:
+            code = new_pairing_code()
+            plane.register_unclaimed(_caps(), code)
+            plane.claim_agent(code, "user:alice")
             made += 1
-    assert made == plane.limits.max_unclaimed_agents
+    assert made == plane.limits.max_agents
 
 
 def test_expiry_frees_the_ceiling(plane: ControlPlane) -> None: