Python
Harden board-owned image attachments and local retention
Rohit C Prasad443e50e15f8c
diff --git a/coworker/personas/builtin/test-worker/manifest.md b/coworker/personas/builtin/test-worker/manifest.mdindex 7b0dead0..5f47911c 100644--- a/coworker/personas/builtin/test-worker/manifest.md+++ b/coworker/personas/builtin/test-worker/manifest.md@@ -31,8 +31,11 @@ How you verify:works, verify what you can and say exactly which checks you couldn't run.- Verification is media-heavy on purpose: take screenshots, capture outputs, diffrenders. That cost lands in YOUR context so the builder's stays for building. Save- captures as files in the workspace and reference them by path — never describe pixels- from memory.+ captures as files in your granted workspace or scratch directory — never describe+ pixels from memory. Use attach_image(item, path, caption) on your verification item+ to copy screenshots into the board's durable, machine-local store. Check that the+ call succeeded and cite the returned attachment reference, not just the source path.+ The caption should identify the criterion, expected/actual behavior and tested revision.- Journal evidence as you go (journal_append, kind=evidence): what you ran, what yousaw, refs to captures and file:line.- Your deliverable is a VERDICT, delivered as the hand-off comment when you move yourdiff --git a/coworker/server/app.py b/coworker/server/app.pyindex b4a40597..a75384c1 100644--- a/coworker/server/app.py+++ b/coworker/server/app.py@@ -1025,6 +1025,9 @@ def create_app(manager: SessionManager) -> FastAPI:body = body or {}def run(actor):+ manager.team_store.require_attachment_write(+ str(body.get("space", "")), actor, int(body.get("id", 0))+ )raw = str(body.get("data_b64", ""))# Cheap pre-decode bound: base64 is ~4/3 of the payload, so anything# multiples over the cap is refused before allocating the decode.diff --git a/coworker/server/manager.py b/coworker/server/manager.pyindex 77526027..db1e0b26 100644--- a/coworker/server/manager.py+++ b/coworker/server/manager.py@@ -2589,6 +2589,9 @@ class SessionManager:space=space,actor=actor,attachments=self.attachment_store,+ # Resolve live grants at call time, including scratch and directories+ # added or revoked since this engine was built. No engine => no access.+ roots=lambda: getattr(self._engines.get(session_id), "roots", []),) + journal_tools(self.journal_store, actor=actor, space=space)diff --git a/coworker/teams/attachments.py b/coworker/teams/attachments.pyindex 90acb9fe..7482eb1f 100644--- a/coworker/teams/attachments.py+++ b/coworker/teams/attachments.py@@ -8,8 +8,8 @@ state dir, bridged into the board as a normal comment event carrying anContent addressing buys three things: dedupe for free (the same screenshot attachedtwice stores once), immutability by construction (the ref can never dangle onto-changed bytes), and location independence — on a hosted board the same ref resolves-to object storage instead of this directory.+changed bytes), and independence from agent workspaces. Boards and their attachment+store stay on this machine; cross-machine sync is not implemented.Scope is images-only and ~10MB to start; the allowlist is the policy choke pointwhen that widens.@@ -18,7 +18,10 @@ when that widens.from __future__ import annotationsimport hashlib+import osimport re+import stat+import tempfilefrom pathlib import Pathfrom typing import Optional@@ -59,10 +62,25 @@ class AttachmentStore:stored = f"{hashlib.sha256(data).hexdigest()}.{ext}"self.root.mkdir(parents=True, exist_ok=True)target = self.root / stored- if not target.exists():- tmp = target.with_suffix(target.suffix + ".tmp")- tmp.write_bytes(data)- tmp.replace(target)+ if target.exists():+ if target.is_symlink() or target.stat().st_size != len(data) or target.read_bytes() != data:+ raise BoardError("stored attachment failed integrity verification")+ else:+ # Unique staging files: concurrent identical captures must not share+ # a .tmp name. Only complete, flushed bytes become visible to readers.+ tmp = None+ try:+ with tempfile.NamedTemporaryFile(dir=self.root, prefix=".attachment-", delete=False) as file:+ tmp = Path(file.name)+ file.write(data)+ file.flush()+ os.fsync(file.fileno())+ tmp.replace(target)+ if target.read_bytes() != data:+ raise BoardError("stored attachment failed integrity verification")+ finally:+ if tmp is not None:+ tmp.unlink(missing_ok=True)safe_name = Path(filename).name.replace("#", "_")return f"{ATTACHMENT_SCHEME}{stored}#{safe_name}"@@ -71,7 +89,7 @@ class AttachmentStore:check is the traversal guard — nothing else reaches the filesystem."""stored = validate_stored_name(stored)path = self.root / stored- if not path.exists():+ if path.is_symlink() or not path.is_file():raise BoardNotFoundError("attachment not found")return path@@ -79,6 +97,39 @@ class AttachmentStore:return _IMAGE_TYPES.get(stored.rsplit(".", 1)[-1], "application/octet-stream")+def read_image_file(path: str | Path, *, roots=None) -> tuple[bytes, str]:+ """Read a bounded regular file. Agent callers MUST supply current granted roots.++ None is reserved for operator CLI/MCP callers with their own filesystem access;+ an empty agent root list fails closed. Relative agent paths use the primary root.+ """+ from ..roots import normalize_roots++ allowed = normalize_roots(roots) if roots is not None else None+ source = Path(path).expanduser()+ if allowed is not None:+ if not allowed:+ raise BoardError("no session directory is available for attachments")+ if not source.is_absolute():+ source = allowed[0].path / source+ source = source.resolve()+ if allowed is not None and not any(source.is_relative_to(r.path) for r in allowed):+ raise BoardError("attachment is outside the session's directories")+ # O_NONBLOCK prevents special files such as FIFOs from hanging the tool;+ # O_NOFOLLOW rejects a leaf swapped to a symlink after resolution.+ flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)+ fd = os.open(source, flags)+ with os.fdopen(fd, "rb") as file:+ info = os.fstat(file.fileno())+ if not stat.S_ISREG(info.st_mode):+ raise BoardError("attachment must be a regular file")+ if info.st_size > MAX_ATTACHMENT_BYTES:+ raise BoardError("attachment exceeds 10MB")+ data = file.read(MAX_ATTACHMENT_BYTES + 1)+ _validate(data, source.name)+ return data, source.name++def stored_name(ref: str) -> Optional[str]:"""`attachment://<hash>.<ext>#<name>` → `<hash>.<ext>`; None for other refs."""if not ref.startswith(ATTACHMENT_SCHEME):diff --git a/coworker/teams/cli.py b/coworker/teams/cli.pyindex 0294778e..8a3bfbea 100644--- a/coworker/teams/cli.py+++ b/coworker/teams/cli.py@@ -348,12 +348,15 @@ def _cmd_assign(args) -> int:def _cmd_attach(args) -> int:- source = Path(args.file).expanduser()- if not source.is_file():- print(f"error: no such file: {source}", file=sys.stderr)+ from .attachments import read_image_file++ try:+ data, name = read_image_file(args.file)+ except (BoardError, ValueError, OSError) as error:+ print(f"error: {error}", file=sys.stderr)return 1result = _dialect(args).attach(- _space(args), args.id, source.read_bytes(), source.name, caption=args.caption+ _space(args), args.id, data, name, caption=args.caption)ref = result.get("ref") or next((r for r in (result.get("payload") or {}).get("refs", [])), ""diff --git a/coworker/teams/dialect.py b/coworker/teams/dialect.pyindex 71fcbd4e..8fdf66af 100644--- a/coworker/teams/dialect.py+++ b/coworker/teams/dialect.py@@ -222,6 +222,7 @@ class LocalDialect:# authority IS attach authority (workers attach on their slice only).if self.attachments is None:raise BoardError("no attachment store is attached to this board")+ self.store.require_attachment_write(space, self.actor, item_id)ref = self.attachments.put(data, filename)return self.store.attach_ref(space,diff --git a/coworker/teams/mcp_server.py b/coworker/teams/mcp_server.pyindex 82f3c380..acf7e829 100644--- a/coworker/teams/mcp_server.py+++ b/coworker/teams/mcp_server.py@@ -104,17 +104,18 @@ def build(dialect, *, space: str):"""Attach a screenshot or image (png/jpg/gif/webp, ≤10MB) from a localfile to a work item — so the lead/reviewer can SEE what you did. Give ita caption saying what the image shows. Great with review hand-offs."""- from pathlib import Path as _Path+ from .attachments import read_image_file- source = _Path(path).expanduser()- if not source.is_file():- return {"error": f"no such file: {path}"}+ try:+ data, name = read_image_file(path)+ except (BoardError, ValueError, OSError) as error:+ return {"error": str(error)}return _safe(dialect.attach,space,item,- source.read_bytes(),- source.name,+ data,+ name,caption=caption,)diff --git a/coworker/teams/store.py b/coworker/teams/store.pyindex f4c69722..d881917e 100644--- a/coworker/teams/store.py+++ b/coworker/teams/store.py@@ -657,6 +657,15 @@ class TeamStore:returnraise BoardNotFoundError("attachment not found")+ def require_attachment_write(self, space: str, actor: Actor, item_id: int) -> None:+ """Check before reading/copying a capture; attach_ref rechecks at publication."""+ if isinstance(item_id, bool) or not isinstance(item_id, int) or item_id <= 0:+ raise BoardError("item must be a positive integer")+ with self._lock:+ self._item(space, item_id)+ if actor.role == Role.WORKER and item_id not in self._worker_slice(space, actor.id):+ raise AuthorityError("worker may only attach to its assigned items and items linked to them")+def attach_ref(self,space: str,@@ -680,14 +689,8 @@ class TeamStore:raise BoardError(f"not an attachment ref: {ref!r}")stored = validate_stored_name(stored)with self._lock:+ self.require_attachment_write(space, actor, item_id)item = self._item(space, item_id)- if actor.role == Role.WORKER and item_id not in self._worker_slice(- space, actor.id- ):- raise AuthorityError(- f"worker {actor.id} may only comment on its assigned items"- " and items linked to them"- )return self.append_event(space,ITEM_COMMENTED,diff --git a/coworker/teams/tools.py b/coworker/teams/tools.pyindex 7c2ac6b6..ce3e4594 100644--- a/coworker/teams/tools.py+++ b/coworker/teams/tools.py@@ -74,6 +74,7 @@ def board_tools(actor: Actor,taint: Callable[[], bool] = lambda: False,attachments=None,+ roots: Callable[[], list] = lambda: [],) -> list:"""The board verbs for one agent, pre-bound to its space and identity.@@ -178,25 +179,19 @@ def board_tools(def attach_image(item: int, path: str, caption: str = "") -> dict:"""Attach a screenshot or image file (png/jpg/gif/webp, ≤10MB) to a workitem so the lead/reviewer can SEE what you did — pair it with your review- hand-off. `caption` says what the image shows."""- from pathlib import Path as _Path+ hand-off. Copies the image into OpenWorker's machine-local board store;+ the original/worktree can be removed after success. Use a path within+ your granted directories. `caption` says what the image proves."""+ from .attachments import read_image_file- source = _Path(path).expanduser()- if not source.is_file():- return {"error": f"no such file: {path}"}try:- ref = attachments.put(source.read_bytes(), source.name)- except (BoardError, ValueError) as error:+ store.require_attachment_write(space, actor, item)+ data, name = read_image_file(path, roots=roots())+ ref = attachments.put(data, name)+ event = store.attach_ref(space, actor, item, caption or f"attached {name}", ref, taint=taint())+ return {**event, "ref": ref, "stored": True}+ except (BoardError, ValueError, OSError) as error:return {"error": str(error)}- return _call(- store.attach_ref,- space,- actor,- item,- caption or f"attached {source.name}",- ref,- taint=taint(),- )verbs = LEAD_VERBS if actor.role in (Role.USER, Role.LEAD) else WORKER_VERBSif attachments is not None:diff --git a/tests/test_board_image_lifecycle.py b/tests/test_board_image_lifecycle.pynew file mode 100644index 00000000..1d5f1af7--- /dev/null+++ b/tests/test_board_image_lifecycle.py@@ -0,0 +1,184 @@+"""Board-owned copies survive capture/worktree cleanup, with bounded scoped ingestion."""+import base64+from concurrent.futures import ThreadPoolExecutor+from pathlib import Path+import subprocess++import pytest+from fastapi.testclient import TestClient++from coworker.roots import RootDir+from coworker.server.app import create_app+from coworker.teams import Actor, BoardError, Role+from coworker.teams.attachments import AttachmentStore, MAX_ATTACHMENT_BYTES, read_image_file, stored_name+from coworker.teams.tools import board_tools+from test_team_live_gaps import manager+from test_team_reader_recovery import create_item++PNG = base64.b64decode("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aD1sAAAAASUVORK5CYII=")+++def attach_tool(manager, roots):+ team = manager.teams.for_lead_session("lead")+ return next(t for t in board_tools(+ manager.team_store, space=team.space, actor=Actor(id="sam", role=Role.WORKER),+ attachments=manager.attachment_store, roots=lambda: roots,+ ) if t.__name__ == "attach_image")+++def test_image_survives_source_deletion_and_actual_worktree_removal(manager, tmp_path):+ repo, checkout = tmp_path / "source-repo", tmp_path / "worker-checkout"+ repo.mkdir()+ def git(*args):+ subprocess.run(["git", "-c", "user.name=Rohit C Prasad", "-c", "[email protected]",+ "-c", "core.hooksPath=/dev/null", *args], cwd=repo, check=True, capture_output=True)+ git("init")+ git("commit", "--allow-empty", "-m", "Initialize synthetic attachment test")+ git("worktree", "add", "--detach", str(checkout), "HEAD")+ source = checkout / "proof.png"+ source.write_bytes(PNG)+ space, _, item = create_item(manager)+ result = attach_tool(manager, [RootDir(checkout)])(item["id"], "proof.png", "Criterion: invoice total is correct")+ assert result["stored"] is True+ ref = result["ref"]+ stored = stored_name(ref)+ assert manager.attachment_store.path_for(stored).parent != checkout+ source.unlink()+ git("worktree", "remove", str(checkout))+ assert not checkout.exists()+ # Re-open the blob store and retrieve through the board's authenticated API,+ # not a workspace file URL. The board remains on its original machine.+ manager.attachment_store = AttachmentStore(manager.attachment_store.root)+ client = TestClient(create_app(manager))+ response = client.get("/v1/sessions/lead/board/attachment", params={"name": stored})+ assert response.status_code == 200+ assert response.headers["content-type"] == "image/png"+ assert response.content == PNG+ detail = manager.team_store.get_item(space, item["id"], actor=Actor(id="lead", role=Role.LEAD))+ assert detail["comments"][-1]["body"] == "Criterion: invoice total is correct"+ assert ref in detail["refs"]+++def test_agent_attachment_tracks_live_grants_and_resolves_relative_paths(manager, tmp_path):+ _, _, item = create_item(manager)+ workspace, extra = tmp_path / "workspace", tmp_path / "extra"+ workspace.mkdir(); extra.mkdir()+ (workspace / "proof.png").write_bytes(PNG)+ (extra / "proof.png").write_bytes(PNG)+ roots = [RootDir(workspace)]+ attach = attach_tool(manager, roots)+ assert attach(item["id"], "proof.png")["stored"]+ assert "error" in attach(item["id"], str(extra / "proof.png"))+ roots.append(RootDir(extra))+ assert attach(item["id"], str(extra / "proof.png"))["stored"]+ roots.clear()+ assert "error" in attach(item["id"], str(workspace / "proof.png"))+++def test_wrong_item_denied_before_reading_or_storing(manager, tmp_path, monkeypatch):+ _, _, item = create_item(manager, "maya")+ def forbidden(*args, **kwargs):+ pytest.fail("unauthorized attachment must not read a file")+ monkeypatch.setattr("coworker.teams.attachments.read_image_file", forbidden)+ result = attach_tool(manager, [RootDir(tmp_path)])(item["id"], "proof.png")+ assert "error" in result+ assert not manager.attachment_store.root.exists()+++def test_escape_and_symlink_to_ungranted_file_are_denied(tmp_path):+ root = tmp_path / "workspace"+ root.mkdir()+ outside = tmp_path / "private.png"+ outside.write_bytes(PNG)+ (root / "escape.png").symlink_to(outside)+ for path in ("../private.png", "escape.png", str(outside)):+ with pytest.raises(BoardError, match="outside"):+ read_image_file(path, roots=[RootDir(root)])+++def test_special_files_and_oversize_inputs_are_refused(tmp_path):+ source = tmp_path / "large.png"+ with source.open("wb") as file:+ file.truncate(MAX_ATTACHMENT_BYTES + 1)+ with pytest.raises(BoardError, match="10MB"):+ read_image_file(source, roots=[RootDir(tmp_path)])+ with pytest.raises((BoardError, OSError)):+ read_image_file(tmp_path, roots=[RootDir(tmp_path)])+++def test_concurrent_identical_uploads_dedupe_without_shared_temp_race(tmp_path):+ store = AttachmentStore(tmp_path / "attachments")+ with ThreadPoolExecutor(max_workers=8) as pool:+ refs = list(pool.map(lambda i: store.put(PNG, f"shot-{i}.png"), range(32)))+ assert len({stored_name(ref) for ref in refs}) == 1+ assert store.path_for(stored_name(refs[0])).read_bytes() == PNG+ assert len(list(store.root.iterdir())) == 1+++def test_corrupt_existing_copy_is_not_reported_as_success(tmp_path):+ store = AttachmentStore(tmp_path / "attachments")+ ref = store.put(PNG, "proof.png")+ store.path_for(stored_name(ref)).write_bytes(b"corrupt")+ with pytest.raises(BoardError, match="integrity"):+ store.put(PNG, "proof.png")+++def test_failed_copy_does_not_publish_board_evidence(manager, tmp_path, monkeypatch):+ space, _, item = create_item(manager)+ (tmp_path / "proof.png").write_bytes(PNG)+ def fail(*args):+ raise OSError("disk full")+ monkeypatch.setattr(manager.attachment_store, "put", fail)+ result = attach_tool(manager, [RootDir(tmp_path)])(item["id"], "proof.png")+ assert result == {"error": "disk full"}+ assert not manager.team_store.get_item(space, item["id"], actor=Actor(id="lead", role=Role.LEAD))["refs"]+++def test_manager_agent_tool_uses_current_engine_roots(manager, tmp_path):+ engine = manager.get_engine("lead")+ tools = manager._team_tools_for("lead", type("Agent", (), {"team": "lead", "name": "swe-lead"})(),+ manager.session_store.load("lead"), manager.default_workspace)+ attach = next(t for t in tools if t.__name__ == "attach_image")+ _, _, item = create_item(manager)+ source = Path(manager.default_workspace) / "proof.png"+ source.write_bytes(PNG)+ assert attach(item["id"], str(source))["stored"]+ engine.roots.clear()+ assert "error" in attach(item["id"], str(source))+++def test_failed_atomic_publish_leaves_no_success_or_staging_file(tmp_path, monkeypatch):+ store = AttachmentStore(tmp_path / "attachments")+ def fail(*args):+ raise OSError("publish failed")+ monkeypatch.setattr(Path, "replace", fail)+ with pytest.raises(OSError, match="publish failed"):+ store.put(PNG, "proof.png")+ assert list(store.root.iterdir()) == []+++def test_source_changes_do_not_change_attached_bytes(manager, tmp_path):+ _, _, item = create_item(manager)+ source = tmp_path / "proof.png"+ source.write_bytes(PNG)+ result = attach_tool(manager, [RootDir(tmp_path)])(item["id"], str(source))+ source.write_bytes(b"overwritten by a later capture")+ assert manager.attachment_store.path_for(stored_name(result["ref"])).read_bytes() == PNG++[email protected]("item_id", [0, -1, True, "1"])+def test_attachment_rejects_invalid_item_ids_before_read(manager, tmp_path, item_id):+ result = attach_tool(manager, [RootDir(tmp_path)])(item_id, "not-present.png")+ assert "positive integer" in result["error"]+++def test_wrong_item_on_http_upload_does_not_create_blob(manager):+ _, _, item = create_item(manager, "maya")+ token = manager.board_tokens.mint("sam", "worker")+ client = TestClient(create_app(manager))+ result = client.post("/v1/board/items/attach", headers={"Authorization": f"Bearer {token}"}, json={+ "space": manager.teams.for_lead_session("lead").space, "id": item["id"],+ "filename": "proof.png", "data_b64": base64.b64encode(PNG).decode(),+ })+ assert result.status_code in (400, 403)+ assert not manager.attachment_store.root.exists()