Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

17.3 KB
Raw Blame
"""DELETE /file, POST /file/mkdir and POST /file/move: an app changing a session's workspace, through
the runner, which is the one process that acts as the session (see PUT /file).

What each must hold: nothing outside the workspace is reachable, by `..` or by a symlink; a symlink
is removed or renamed as itself, never as the file it points to; the nesting base's user files
(nanobot keeps them one level down) are found where GET /file finds them; and the answer names the
path inside the session directory, because that is where the gateway changes the checkpoint too.
"""
import os
import sys
from pathlib import Path

import pytest
from fastapi.testclient import TestClient

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
import server  # noqa: E402


@pytest.fixture
def ws(tmp_path, monkeypatch):
    root = tmp_path / "sess"
    root.mkdir()
    monkeypatch.setattr(server, "_SESSION_UIDS", False)
    monkeypatch.setattr(server, "_ws", lambda identifier="": str(root))
    return root


@pytest.fixture
def c():
    return TestClient(server.app)


def test_delete_a_file(ws, c):
    (ws / "a.txt").write_text("x")
    r = c.delete("/file", params={"identifier": "s", "path": "a.txt"})
    assert r.status_code == 200 and r.json()["path"] == "a.txt"
    assert not (ws / "a.txt").exists()


def test_delete_a_directory_with_everything_in_it(ws, c):
    (ws / "d" / "e").mkdir(parents=True)
    (ws / "d" / "e" / "f.txt").write_text("x")
    assert c.delete("/file", params={"identifier": "s", "path": "d"}).status_code == 200
    assert not (ws / "d").exists()


def test_delete_nothing_is_404(ws, c):
    assert c.delete("/file", params={"identifier": "s", "path": "nope.txt"}).status_code == 404


@pytest.mark.parametrize("path", ["../x", "../../etc/passwd", "a/../../x"])
def test_escapes_are_refused(ws, c, path):
    (ws.parent / "x").write_text("outside")
    assert c.delete("/file", params={"identifier": "s", "path": path}).status_code == 400
    assert c.post("/file/mkdir", params={"identifier": "s", "path": path}).status_code == 400
    (ws / "a.txt").write_text("x")
    assert c.post("/file/move", params={"identifier": "s", "path": "a.txt", "to": path}).status_code == 400
    assert (ws.parent / "x").read_text() == "outside"


def test_the_workspace_itself_is_not_a_path(ws, c):
    for p in ("", "/", "."):
        assert c.delete("/file", params={"identifier": "s", "path": p}).status_code in (400, 404)
    assert ws.is_dir()


def test_a_symlink_is_removed_not_its_target(ws, c):
    (ws / "real.txt").write_text("keep me")
    os.symlink(ws / "real.txt", ws / "link.txt")
    assert c.delete("/file", params={"identifier": "s", "path": "link.txt"}).status_code == 200
    assert not (ws / "link.txt").is_symlink() and (ws / "real.txt").read_text() == "keep me"


def test_a_symlink_out_of_the_workspace_is_removed_as_a_link(ws, c):
    outside = ws.parent / "secret.txt"
    outside.write_text("theirs")
    os.symlink(outside, ws / "escape")
    assert c.delete("/file", params={"identifier": "s", "path": "escape"}).status_code == 200
    assert outside.read_text() == "theirs"


def test_mkdir_makes_parents_and_is_idempotent(ws, c):
    r = c.post("/file/mkdir", params={"identifier": "s", "path": "a/b/c"})
    assert r.status_code == 200 and r.json()["created"] is True and (ws / "a" / "b" / "c").is_dir()
    r = c.post("/file/mkdir", params={"identifier": "s", "path": "a/b/c"})
    assert r.status_code == 200 and r.json()["created"] is False


def test_mkdir_over_a_file_is_409(ws, c):
    (ws / "a").write_text("x")
    assert c.post("/file/mkdir", params={"identifier": "s", "path": "a"}).status_code == 409
    assert c.post("/file/mkdir", params={"identifier": "s", "path": "a/b"}).status_code == 409


def test_move_a_file_into_a_new_directory(ws, c):
    (ws / "a.txt").write_text("x")
    r = c.post("/file/move", params={"identifier": "s", "path": "a.txt", "to": "notes/b.txt"})
    assert r.status_code == 200 and r.json() == {"ok": True, "path": "a.txt", "to": "notes/b.txt"}
    assert (ws / "notes" / "b.txt").read_text() == "x" and not (ws / "a.txt").exists()


def test_move_a_directory(ws, c):
    (ws / "d").mkdir()
    (ws / "d" / "f.txt").write_text("x")
    assert c.post("/file/move", params={"identifier": "s", "path": "d", "to": "e"}).status_code == 200
    assert (ws / "e" / "f.txt").read_text() == "x" and not (ws / "d").exists()


def test_move_never_overwrites(ws, c):
    (ws / "a.txt").write_text("a")
    (ws / "b.txt").write_text("b")
    assert c.post("/file/move", params={"identifier": "s", "path": "a.txt", "to": "b.txt"}).status_code == 409
    assert (ws / "b.txt").read_text() == "b" and (ws / "a.txt").read_text() == "a"


def test_move_into_itself_is_refused(ws, c):
    (ws / "d").mkdir()
    assert c.post("/file/move", params={"identifier": "s", "path": "d", "to": "d/inner"}).status_code == 400
    assert (ws / "d").is_dir()


def test_move_of_nothing_is_404(ws, c):
    assert c.post("/file/move", params={"identifier": "s", "path": "nope", "to": "x"}).status_code == 404


def test_the_nesting_base_finds_user_files_one_level_down(ws, c):
    """nanobot's user files live in the agent's directory; the answer names them inside the
    session directory, which is where they are in the checkpoint."""
    (ws / ".harness").mkdir()
    (ws / ".harness" / "agent-subdir").write_text("workspace")
    (ws / "workspace").mkdir()
    (ws / "workspace" / "deck.json").write_text("{}")
    r = c.post("/file/move", params={"identifier": "s", "path": "deck.json", "to": "old/deck.json"})
    assert r.status_code == 200
    assert r.json()["path"] == "workspace/deck.json" and r.json()["to"] == "workspace/old/deck.json"
    assert (ws / "workspace" / "old" / "deck.json").exists()
    r = c.delete("/file", params={"identifier": "s", "path": "old"})
    assert r.status_code == 200 and r.json()["path"] == "workspace/old"


# ── what the review of #478 found ─────────────────────────────────────────────────────────────
def _nanobot(ws):
    (ws / ".harness").mkdir()
    (ws / ".harness" / "agent-subdir").write_text("workspace")
    (ws / ".git" / "info").mkdir(parents=True)
    (ws / ".git" / "info" / "exclude").write_text(
        "# runner\nworkspace/.nanobot/\nworkspace/skills/\nworkspace/memory/\nworkspace/AGENTS.md\n")
    (ws / "workspace" / "skills" / "s").mkdir(parents=True)
    (ws / "workspace" / "skills" / "s" / "SKILL.md").write_text("skill")
    (ws / "workspace" / "AGENTS.md").write_text("doc")
    (ws / "workspace" / "deck.json").write_text("{}")


def test_the_nesting_base_s_own_directory_is_not_a_user_path(ws, c):
    """DELETE workspace would have removed nanobot's whole working directory."""
    _nanobot(ws)
    assert c.delete("/file", params={"identifier": "s", "path": "workspace"}).status_code == 404
    assert c.post("/file/move", params={"identifier": "s", "path": "workspace", "to": "w2"}).status_code == 404
    assert (ws / "workspace" / "deck.json").exists() and (ws / "workspace" / "skills").is_dir()


@pytest.mark.parametrize("call", [
    ("delete", {"path": "skills"}), ("delete", {"path": "AGENTS.md"}),
    ("delete", {"path": "skills/s/SKILL.md"}), ("move", {"path": "skills", "to": "s2"}),
    ("move", {"path": "deck.json", "to": "skills/deck.json"}), ("mkdir", {"path": "memory/new"}),
    # PUT is the fourth route into the workspace and belongs in this table: `AGENTS.md` replaces the
    # base's own instructions where the agent reads them, and `memory/notes.txt` lands at the session
    # root, which the next turn adopts into the excluded directory.
    ("put", {"path": "AGENTS.md"}), ("put", {"path": "memory/notes.txt"})])
def test_the_base_s_excluded_machinery_is_refused(ws, c, call):
    _nanobot(ws)
    op, params = call
    if op == "delete":
        r = c.delete("/file", params={"identifier": "s", **params})
    elif op == "put":
        r = c.put("/file", params={"identifier": "s", **params}, content=b"OVERWRITTEN BY AN APP")
    else:
        r = c.post(f"/file/{op}", params={"identifier": "s", **params})
    assert r.status_code == 400
    # the contents, not just the names: a put that was let through leaves the file there, overwritten
    assert (ws / "workspace" / "skills" / "s" / "SKILL.md").read_text() == "skill"
    assert (ws / "workspace" / "AGENTS.md").read_text() == "doc"
    assert not list(ws.rglob("notes.txt")) and not (ws / "workspace" / "memory").exists()


def test_a_flat_base_s_excluded_files_are_refused(ws, c):
    (ws / ".git" / "info").mkdir(parents=True)
    (ws / ".git" / "info" / "exclude").write_text("SOUL.md\nmemory/\n")
    (ws / "SOUL.md").write_text("s")
    (ws / "notes.md").write_text("n")
    assert c.delete("/file", params={"identifier": "s", "path": "SOUL.md"}).status_code == 400
    assert c.put("/file", params={"identifier": "s", "path": "SOUL.md"},
                 content=b"OVERWRITTEN BY AN APP").status_code == 400
    assert c.put("/file", params={"identifier": "s", "path": "memory/notes.txt"},
                 content=b"in").status_code == 400
    # and an ordinary workspace path still writes: the refusal reaches the base's machinery only
    assert c.put("/file", params={"identifier": "s", "path": "notes.md"}, content=b"ok").status_code == 200
    assert c.delete("/file", params={"identifier": "s", "path": "notes.md"}).status_code == 200
    assert (ws / "SOUL.md").read_text() == "s" and not (ws / "memory").exists()


def test_a_file_written_at_the_root_between_turns_is_still_reachable(ws, c):
    """An app's PUT lands at the session root until the next turn adopts it into the agent's directory."""
    _nanobot(ws)
    (ws / "sheet.json").write_text("rows")
    r = c.post("/file/move", params={"identifier": "s", "path": "sheet.json", "to": "kept.json"})
    assert r.status_code == 200 and (ws / "kept.json").read_text() == "rows"


def test_a_move_under_a_file_is_409(ws, c):
    (ws / "notes.txt").write_text("n")
    (ws / "a.md").write_text("a")
    r = c.post("/file/move", params={"identifier": "s", "path": "a.md", "to": "notes.txt/a.md"})
    assert r.status_code == 409 and (ws / "a.md").exists()


def test_a_new_folder_on_the_nesting_base_goes_in_the_agent_s_directory(ws, c):
    """Where the checkpoint's copy of the change puts it (backing.tar_change), so the two agree."""
    _nanobot(ws)
    r = c.post("/file/mkdir", params={"identifier": "s", "path": "slides/old"})
    assert r.status_code == 200 and r.json()["path"] == "workspace/slides/old"
    assert (ws / "workspace" / "slides" / "old").is_dir() and not (ws / "slides").exists()
    (ws / "workspace" / "notes").write_text("a file")
    assert c.post("/file/mkdir", params={"identifier": "s", "path": "notes/x"}).status_code == 409


def test_an_existing_root_folder_is_found_before_a_new_one_is_made(ws, c):
    """A folder an app's PUT made at the root between turns is the one mkdir answers for."""
    _nanobot(ws)
    (ws / "data").mkdir()
    r = c.post("/file/mkdir", params={"identifier": "s", "path": "data"})
    assert r.status_code == 200 and r.json()["created"] is False and not (ws / "workspace" / "data").exists()


@pytest.mark.parametrize("rel", ["skills", "skills/x", "workspace/skills", "workspace/skills/s/SKILL.md",
                                 "workspace", "workspace/deck.json", "SOUL.md", "SOUL.md.bak", "memory",
                                 "memory/a", "memo", "workspace/AGENTS.md", "workspace/AGENTS.mdx"])
def test_the_protection_rule_is_the_gateway_s(rel):
    """The runner and the gateway's checkpoint path each apply it; the two must agree."""
    sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "gateway"))
    import backing  # noqa: E402
    pats = ("workspace/skills/", "workspace/AGENTS.md", "SOUL.md", "memory/")
    assert server._ws_protected(rel, pats) == backing.ws_protected(rel, pats)


def test_a_put_replaces_the_nesting_base_s_file_where_it_is(ws, c):
    """Written at the root it sat beside the agent's copy, which every read found first."""
    _nanobot(ws)
    r = c.put("/file", params={"identifier": "s", "path": "deck.json"}, content=b'{"v":2}')
    assert r.status_code == 200 and r.json()["path"] == "workspace/deck.json"
    assert (ws / "workspace" / "deck.json").read_bytes() == b'{"v":2}' and not (ws / "deck.json").exists()
    r = c.put("/file", params={"identifier": "s", "path": "new.json"}, content=b"n")
    assert r.json()["path"] == "new.json"                     # a new file: the root, adopted next turn


def test_a_delete_on_the_nesting_base_removes_every_copy(ws, c):
    _nanobot(ws)
    (ws / "notes.md").write_text("app")                       # an older PUT, beside the agent's copy
    (ws / "workspace" / "notes.md").write_text("agent")
    assert c.delete("/file", params={"identifier": "s", "path": "notes.md"}).status_code == 200
    assert not (ws / "notes.md").exists() and not (ws / "workspace" / "notes.md").exists()


def test_a_move_on_the_nesting_base_leaves_no_copy_under_the_old_name(ws, c):
    """A root copy left behind would be adopted back under the old name next turn."""
    _nanobot(ws)
    (ws / "a.md").write_text("root")
    (ws / "workspace" / "a.md").write_text("agent")
    r = c.post("/file/move", params={"identifier": "s", "path": "a.md", "to": "b.md"})
    assert r.status_code == 200 and (ws / "workspace" / "b.md").read_text() == "agent"
    assert not (ws / "a.md").exists() and not (ws / "workspace" / "a.md").exists()


def test_a_put_of_a_new_file_goes_into_a_folder_the_agent_has(ws, c):
    _nanobot(ws)
    (ws / "workspace" / "notes").mkdir()
    r = c.put("/file", params={"identifier": "s", "path": "notes/new.md"}, content=b"n")
    assert r.status_code == 200 and (ws / "workspace" / "notes" / "new.md").read_bytes() == b"n"
    assert not (ws / "notes").exists()


# ── what the maintainer review of #478 found ──────────────────────────────────────────────────
# The routes check a path and then change it, as the runner, which is root under the write-wall. A
# process the session left running between turns can swap a checked directory for a symlink in that
# gap. Each test makes the swap at the gap (the hook the route calls between its check and its
# change) and holds that nothing outside the workspace is touched: the change fails instead.
def _outside(ws):
    out = ws.parent / "outside"
    out.mkdir()
    (out / "x.txt").write_text("theirs")
    return out


def _swap_in_link(ws, name, target):
    import shutil
    if (ws / name).is_dir():
        shutil.rmtree(ws / name)
    os.symlink(target, ws / name)


def test_a_delete_does_not_follow_a_directory_swapped_for_a_link(ws, c, monkeypatch):
    out = _outside(ws)
    (ws / "d").mkdir()
    (ws / "d" / "x.txt").write_text("mine")
    monkeypatch.setattr(server, "_refuse_protected", lambda *_a: _swap_in_link(ws, "d", out))
    assert c.delete("/file", params={"identifier": "s", "path": "d/x.txt"}).status_code == 500
    assert (out / "x.txt").read_text() == "theirs"


def test_a_move_does_not_follow_a_directory_swapped_for_a_link(ws, c, monkeypatch):
    out = _outside(ws)
    (ws / "a.txt").write_text("mine")
    (ws / "e").mkdir()
    monkeypatch.setattr(server, "_refuse_protected", lambda *_a: _swap_in_link(ws, "e", out))
    r = c.post("/file/move", params={"identifier": "s", "path": "a.txt", "to": "e/a.txt"})
    assert r.status_code == 409                # a link where a directory would be, as a file there is
    assert not (out / "a.txt").exists() and (ws / "a.txt").read_text() == "mine"


def test_a_mkdir_does_not_follow_a_directory_swapped_for_a_link(ws, c, monkeypatch):
    out = _outside(ws)
    (ws / "d").mkdir()
    monkeypatch.setattr(server, "_refuse_protected", lambda *_a: _swap_in_link(ws, "d", out))
    assert c.post("/file/mkdir", params={"identifier": "s", "path": "d/new"}).status_code == 409
    assert not (out / "new").exists()


def test_a_put_does_not_follow_a_directory_swapped_for_a_link(ws, c, monkeypatch):
    out = _outside(ws)
    (ws / "d").mkdir()
    monkeypatch.setattr(server, "_isolate_session", lambda *_a: _swap_in_link(ws, "d", out))
    r = c.put("/file", params={"identifier": "s", "path": "d/x.txt"}, content=b"app")
    assert r.status_code == 500
    assert (out / "x.txt").read_text() == "theirs" and sorted(p.name for p in out.iterdir()) == ["x.txt"]


def test_a_put_of_the_workspace_itself_is_refused(ws, c):
    """Before, it wrote its temporary file into the directory that holds every session's workspace."""
    for p in (".", "/"):
        assert c.put("/file", params={"identifier": "s", "path": p}, content=b"x").status_code == 400
    assert sorted(q.name for q in ws.parent.iterdir()) == ["sess"]


@pytest.mark.parametrize("root_file,path,to", [("app.json", "deck.json", "app.json"),
                                               ("sheet.json", "sheet.json", "deck.json")])
def test_a_move_onto_a_name_taken_on_the_other_side_is_409(ws, c, root_file, path, to):
    """nanobot: measured on the 0.35.0-rc.1 candidate, moving the agent's deck.json onto the app's
    root app.json answered 200, and the moved file shadowed the app's for good (adoption never moves
    over a name the agent's directory has)."""
    _nanobot(ws)
    (ws / root_file).write_text("the app's")
    r = c.post("/file/move", params={"identifier": "s", "path": path, "to": to})
    assert r.status_code == 409
    assert (ws / root_file).read_text() == "the app's" and (ws / "workspace" / "deck.json").read_text() == "{}"