Skip to content
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.md
index 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, diff
renders. 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 you
saw, refs to captures and file:line.
- Your deliverable is a VERDICT, delivered as the hand-off comment when you move your
diff --git a/coworker/server/app.py b/coworker/server/app.py
index 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.py
index 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.py
index 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 an
Content addressing buys three things: dedupe for free (the same screenshot attached
twice 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 point
when that widens.
@@ -18,7 +18,10 @@ when that widens.
from __future__ import annotations
import hashlib
+import os
import re
+import stat
+import tempfile
from pathlib import Path
from 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.py
index 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 1
result = _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.py
index 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.py
index 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 local
file to a work item — so the lead/reviewer can SEE what you did. Give it
a 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.py
index f4c69722..d881917e 100644
--- a/coworker/teams/store.py
+++ b/coworker/teams/store.py
@@ -657,6 +657,15 @@ class TeamStore:
return
raise 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.py
index 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 work
item 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_VERBS
if attachments is not None:
diff --git a/tests/test_board_image_lifecycle.py b/tests/test_board_image_lifecycle.py
new file mode 100644
index 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()