Skip to content

Build and run agents you can see, understand and trust.

feat(service): add workspace artifact list_dir and read_file endpoints (#2187)

Ziyang Guoe55d4c367c94
diff --git a/src/agentscope/app/_app.py b/src/agentscope/app/_app.py
index fcda800b3..5f7822c54 100644
--- a/src/agentscope/app/_app.py
+++ b/src/agentscope/app/_app.py
@@ -1,5 +1,6 @@
# -*- coding: utf-8 -*-
"""AgentScope app factory."""
+import secrets
from typing import Type, TYPE_CHECKING, Any
from ._lifespan import lifespan
@@ -94,6 +95,7 @@ def create_app(
custom_subagent_templates: list[SubAgentTemplate] | None = None,
custom_agent_cls: Type[Agent] | None = None,
resource_access_policy: ResourceAccessPolicyBase | None = None,
+ download_secret: str | None = None,
title: str = "AgentScope",
version: str = __version__,
) -> FastAPI:
@@ -227,6 +229,13 @@ def create_app(
user. When ``None`` (default), a
:class:`DenyAllResourceAccessPolicy` is installed which
preserves the historical owner-isolated behavior.
+ download_secret (`str | None`, optional):
+ Signs the short-lived tokens that let a browser download a
+ workspace file by navigation. Defaults to a value generated
+ per process, which is fine for a single instance but **must
+ be set explicitly behind a load balancer** — otherwise a
+ token minted by one replica is rejected by the next, and
+ downloads fail at random.
title (`str`, defaults to ``"AgentScope"``):
OpenAPI title shown in the docs UI.
version (`str`, defaults to the package version):
@@ -257,6 +266,7 @@ def create_app(
)
app.state.mcp_hubs = _index_hubs(mcp_hubs, "MCP")
app.state.skill_hubs = _index_hubs(skill_hubs, "skill")
+ app.state.download_secret = download_secret or secrets.token_urlsafe(32)
# Parser / chunker / blob-store defaults only make sense when the
# KB feature is actually enabled. When ``knowledge_base_manager`` is
diff --git a/src/agentscope/app/_router/_schema/__init__.py b/src/agentscope/app/_router/_schema/__init__.py
index a6ac01b1a..5b649ff40 100644
--- a/src/agentscope/app/_router/_schema/__init__.py
+++ b/src/agentscope/app/_router/_schema/__init__.py
@@ -11,6 +11,8 @@ from ._workspace import (
AddFromLibraryResponse,
AddSkillRequest,
AddSkillsFromLibraryRequest,
+ DirectoryEntry,
+ DownloadTokenResponse,
MCPClientStatus,
ToolInfo,
)
@@ -87,6 +89,8 @@ __all__ = [
"AddFromLibraryResponse",
"AddSkillRequest",
"AddSkillsFromLibraryRequest",
+ "DirectoryEntry",
+ "DownloadTokenResponse",
"MCPClientStatus",
"ToolInfo",
# Agent
diff --git a/src/agentscope/app/_router/_schema/_workspace.py b/src/agentscope/app/_router/_schema/_workspace.py
index 40b905fa4..65ca5ced9 100644
--- a/src/agentscope/app/_router/_schema/_workspace.py
+++ b/src/agentscope/app/_router/_schema/_workspace.py
@@ -48,6 +48,43 @@ class AddFromLibraryResponse(BaseModel):
)
+class DirectoryEntry(BaseModel):
+ """One entry in a workspace directory listing."""
+
+ name: str = Field(
+ description="The entry name, without any leading directory.",
+ )
+ is_dir: bool = Field(
+ description="Whether the entry is itself a directory.",
+ )
+ size_bytes: int | None = Field(
+ default=None,
+ description=(
+ "File size in bytes. Always null for a directory, and null "
+ "for a file the backend could not stat."
+ ),
+ )
+ updated_at: float | None = Field(
+ default=None,
+ description="Last modification time as a Unix timestamp.",
+ )
+
+
+class DownloadTokenResponse(BaseModel):
+ """A capability authorizing one download of one path."""
+
+ token: str = Field(
+ description=(
+ "Pass as the ``token`` query parameter of "
+ "``GET /workspace/files``, in place of the ``X-User-ID`` "
+ "header. Valid for this path only."
+ ),
+ )
+ expires_at: float = Field(
+ description="Unix timestamp after which the token is refused.",
+ )
+
+
class ToolInfo(BaseModel):
"""The tool info."""
diff --git a/src/agentscope/app/_router/_workspace.py b/src/agentscope/app/_router/_workspace.py
index 4dcdb2d39..7946f2061 100644
--- a/src/agentscope/app/_router/_workspace.py
+++ b/src/agentscope/app/_router/_workspace.py
@@ -1,24 +1,34 @@
# -*- coding: utf-8 -*-
"""Workspace router — manage MCP clients and skills on a workspace."""
+import mimetypes
+from urllib.parse import quote
+
from fastapi import (
APIRouter,
Depends,
File,
Form,
+ Header,
HTTPException,
Query,
UploadFile,
status,
)
+from fastapi.responses import StreamingResponse
from pydantic import ValidationError
from ..deps import (
get_current_user_id,
+ get_download_secret,
get_skill_hubs,
get_storage,
get_workspace_manager,
)
from ..hub import SkillHubBase
+from .._service._download_token import (
+ sign_download_token,
+ verify_download_token,
+)
from .._service._skill_upload import (
SkillUploadError,
UploadManifest,
@@ -36,6 +46,8 @@ from ._schema import (
AddFromLibraryResponse,
AddSkillRequest,
AddSkillsFromLibraryRequest,
+ DirectoryEntry,
+ DownloadTokenResponse,
MCPClientStatus,
ToolInfo,
)
@@ -444,3 +456,192 @@ async def remove_skill(
workspace_manager,
)
await workspace.remove_skill(skill_name)
+
+
+# ---------------------------------------------------------------------------
+# File browsing endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/directories")
+async def list_workspace_directory(
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ path: str = Query(
+ default="",
+ description=(
+ "Absolute path, or one relative to the workspace root. "
+ "Empty lists the workspace root itself."
+ ),
+ ),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[DirectoryEntry]:
+ """List one directory level, reachable from a session's workspace.
+
+ Paths are not confined to the workspace root: for a sandboxed
+ backend the reachable filesystem is the sandbox, and for a local
+ one the caller is already trusted with the host.
+ """
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ backend = workspace.get_backend()
+ target = backend.abspath(path, cwd=workspace.workdir)
+
+ entry = await backend.stat(target)
+ if entry is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail="Directory not found.",
+ )
+ if not entry.is_dir:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail="Requested path is a file, not a directory.",
+ )
+
+ # One call for the whole directory: asking per entry would be one
+ # round trip each on a sandboxed backend, times three attributes.
+ return [
+ DirectoryEntry(
+ name=entry.name,
+ is_dir=entry.is_dir,
+ size_bytes=entry.size_bytes,
+ updated_at=entry.mtime,
+ )
+ for entry in await backend.scandir(target)
+ ]
+
+
+@workspace_router.post("/files/download-token")
+async def create_download_token(
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ path: str = Query(..., description="The path the token will authorize."),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+ secret: str = Depends(get_download_secret),
+) -> DownloadTokenResponse:
+ """Mint a short-lived token for a browser-native download.
+
+ The browser writes the response straight to disk only when it
+ issues the request itself, and such a request carries no custom
+ header — hence a credential in the URL. Fetching with ``X-User-ID``
+ instead works but holds the whole file in the tab.
+
+ Minting depends on the normal identity, so whatever replaces
+ ``X-User-ID`` guards this too.
+
+ The session is resolved here only to fail early: the download is a
+ browser navigation, so an error there surfaces as a raw error page
+ rather than something the UI can show.
+ """
+ await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ # Signed verbatim, not resolved: the download verifies against the
+ # query string it receives, and resolving needs a user the token
+ # has not been read yet to supply.
+ token, expires_at = sign_download_token(secret, user_id, path)
+ return DownloadTokenResponse(token=token, expires_at=expires_at)
+
+
+@workspace_router.get("/files")
+async def read_workspace_file(
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ path: str = Query(
+ ...,
+ description="Absolute path, or one relative to the workspace root.",
+ ),
+ download: bool = Query(
+ default=False,
+ description="Force a Content-Disposition attachment.",
+ ),
+ token: str
+ | None = Query(
+ default=None,
+ description=(
+ "A token from ``POST /workspace/files/download-token``, "
+ "accepted in place of the ``X-User-ID`` header so a browser "
+ "navigation can download the file directly."
+ ),
+ ),
+ x_user_id: str | None = Header(default=None),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+ secret: str = Depends(get_download_secret),
+) -> StreamingResponse:
+ """Stream one file out of a session's workspace.
+
+ The body is piped chunk by chunk rather than read whole: the API
+ process is shared, so one large download must not be able to
+ exhaust it for everyone else.
+ """
+ if token is not None:
+ try:
+ user_id = verify_download_token(secret, token, path)
+ except ValueError as e:
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail=str(e),
+ ) from e
+ elif x_user_id:
+ user_id = x_user_id
+ else:
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail="X-User-ID header or download token is required.",
+ )
+
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ backend = workspace.get_backend()
+ target = backend.abspath(path, cwd=workspace.workdir)
+ basename = backend.basename(target) or "download"
+
+ entry = await backend.stat(target)
+ if entry is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail="File not found.",
+ )
+ if entry.is_dir:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail="Requested path is a directory, not a file.",
+ )
+
+ headers: dict[str, str] = {}
+ # Lets the browser show real download progress instead of a
+ # spinner of unknown length; omitted when the backend cannot stat.
+ if entry.size_bytes is not None:
+ headers["Content-Length"] = str(entry.size_bytes)
+ if download:
+ headers[
+ "Content-Disposition"
+ ] = f"attachment; filename*=UTF-8''{quote(basename)}"
+
+ return StreamingResponse(
+ backend.read_stream(target),
+ media_type=(
+ mimetypes.guess_type(basename)[0] or "application/octet-stream"
+ ),
+ headers=headers,
+ )
diff --git a/src/agentscope/app/_service/_download_token.py b/src/agentscope/app/_service/_download_token.py
new file mode 100644
index 000000000..875fceac7
--- /dev/null
+++ b/src/agentscope/app/_service/_download_token.py
@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""Short-lived capability tokens for browser-native file downloads.
+
+A browser only streams a response to disk when it issues the request
+itself — a navigation or ``<a download>`` — and such a request cannot
+carry a custom header. Fetching with ``X-User-ID`` and building a blob
+works, but buffers the whole file in the tab.
+
+So the credential has to travel in the URL. A token minted here says
+"this exact user was already authenticated, and may read this exact
+path for the next minute" — a capability, not an identity. Only
+``GET /workspace/files`` accepts one, and minting depends on the normal
+identity dependency, so swapping in OAuth/JWT later changes where the
+capability comes from without touching how it is checked.
+"""
+import base64
+import hashlib
+import hmac
+import time
+
+# Long enough to survive a slow round trip and the user's click, short
+# enough that a token leaked through an access log or browser history
+# is already dead. There is no revocation list to fall back on.
+DEFAULT_DOWNLOAD_TOKEN_TTL = 60
+
+
+def _b64(raw: bytes) -> str:
+ """Encode without padding, which is not URL-safe to round-trip."""
+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _unb64(text: str) -> bytes:
+ """Reverse :func:`_b64`, restoring the stripped padding."""
+ return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def _signature(secret: str, expires_at: int, user_id: str, path: str) -> bytes:
+ """Compute the MAC binding an expiry, a user and a path together.
+
+ ``\\0`` separates the fields because it cannot occur in any of them,
+ so no combination of values can be re-cut into a different triple.
+
+ Args:
+ secret (`str`):
+ The app-wide signing secret.
+ expires_at (`int`):
+ Unix timestamp after which the token is refused.
+ user_id (`str`):
+ The user the capability was granted to.
+ path (`str`):
+ The one path the capability covers.
+
+ Returns:
+ `bytes`:
+ The raw HMAC-SHA256 digest.
+ """
+ message = f"{expires_at}\0{user_id}\0{path}".encode("utf-8")
+ return hmac.new(secret.encode("utf-8"), message, hashlib.sha256).digest()
+
+
+def sign_download_token(
+ secret: str,
+ user_id: str,
+ path: str,
+ ttl: int = DEFAULT_DOWNLOAD_TOKEN_TTL,
+) -> tuple[str, int]:
+ """Mint a token authorizing one download.
+
+ Args:
+ secret (`str`):
+ The app-wide signing secret.
+ user_id (`str`):
+ The already-authenticated caller.
+ path (`str`):
+ The path the token authorizes, verbatim as the download
+ request will send it.
+ ttl (`int`, defaults to 60):
+ Seconds the token stays valid.
+
+ Returns:
+ `tuple[str, int]`:
+ The token and its expiry as a Unix timestamp.
+ """
+ expires_at = int(time.time()) + ttl
+ signature = _signature(secret, expires_at, user_id, path)
+ token = f"{expires_at}.{_b64(user_id.encode('utf-8'))}.{_b64(signature)}"
+ return token, expires_at
+
+
+def verify_download_token(secret: str, token: str, path: str) -> str:
+ """Return the user a token was granted to, for this path.
+
+ The path is not read out of the token but re-derived from the
+ request, so a token for one file cannot be replayed against
+ another.
+
+ Args:
+ secret (`str`):
+ The app-wide signing secret.
+ token (`str`):
+ The token from the request.
+ path (`str`):
+ The path the request is asking for.
+
+ Returns:
+ `str`:
+ The user ID the token was minted for.
+
+ Raises:
+ `ValueError`:
+ The token is malformed, expired, or does not match.
+ """
+ try:
+ raw_expiry, raw_user, raw_signature = token.split(".")
+ expires_at = int(raw_expiry)
+ user_id = _unb64(raw_user).decode("utf-8")
+ signature = _unb64(raw_signature)
+ except (ValueError, UnicodeDecodeError) as e:
+ raise ValueError("Malformed download token.") from e
+
+ expected = _signature(secret, expires_at, user_id, path)
+ if not hmac.compare_digest(signature, expected):
+ raise ValueError("Invalid download token.")
+ if expires_at < time.time():
+ raise ValueError("Expired download token.")
+ return user_id
diff --git a/src/agentscope/app/deps.py b/src/agentscope/app/deps.py
index 255fb2575..78e93be9a 100644
--- a/src/agentscope/app/deps.py
+++ b/src/agentscope/app/deps.py
@@ -165,6 +165,18 @@ async def get_workspace_manager(request: Request) -> WorkspaceManagerBase:
return request.app.state.workspace_manager
+async def get_download_secret(request: Request) -> str:
+ """Return the secret that signs file-download tokens.
+
+ Args:
+ request (`Request`): The incoming FastAPI request.
+
+ Returns:
+ `str`: The signing secret stored in ``app.state``.
+ """
+ return request.app.state.download_secret
+
+
async def get_extra_agent_middlewares(
request: Request,
) -> AgentMiddlewareFactory | None:
diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.py
index 9593e6bfa..ed536d67c 100644
--- a/src/agentscope/tool/__init__.py
+++ b/src/agentscope/tool/__init__.py
@@ -16,6 +16,7 @@ from ._builtin import (
Read,
Write,
BackendBase,
+ DirEntry,
ExecResult,
LocalBackend,
)
@@ -44,6 +45,7 @@ __all__ = [
# Builtin tools
"BackendBase",
"LocalBackend",
+ "DirEntry",
"ExecResult",
"ResetTools",
"Bash",
diff --git a/src/agentscope/tool/_builtin/__init__.py b/src/agentscope/tool/_builtin/__init__.py
index 15755149e..ef17336fe 100644
--- a/src/agentscope/tool/_builtin/__init__.py
+++ b/src/agentscope/tool/_builtin/__init__.py
@@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
"""The builtin tools in agentscope."""
-from ._backend import BackendBase, ExecResult, LocalBackend
+from ._backend import BackendBase, DirEntry, ExecResult, LocalBackend
from ._bash import Bash
from ._edit import Edit
from ._glob import Glob
@@ -23,6 +23,7 @@ __all__ = [
"Read",
"Write",
"BackendBase",
+ "DirEntry",
"LocalBackend",
"ExecResult",
]
diff --git a/src/agentscope/tool/_builtin/_backend.py b/src/agentscope/tool/_builtin/_backend.py
index aaa0a773e..82b50b602 100644
--- a/src/agentscope/tool/_builtin/_backend.py
+++ b/src/agentscope/tool/_builtin/_backend.py
@@ -46,6 +46,15 @@ from typing import Any, AsyncIterator
import aiofiles
+# Chunk size for streamed reads. Large enough that a big file does not
+# turn into thousands of awaits, small enough to stay off the heap.
+DEFAULT_READ_CHUNK_SIZE = 1024 * 1024
+
+# One NUL-terminated record per entry, for the shell-based ``scandir``
+# and ``stat``. The name goes last because it is the only field that
+# may itself contain a tab, so a bounded split keeps it whole.
+_FIND_ENTRY_FORMAT = "%Y\\t%s\\t%T@\\t%f\\0"
+
# ── data class ─────────────────────────────────────────────────────────
@@ -74,6 +83,31 @@ class ExecResult:
return self.exit_code == 0
+@dataclass(frozen=True, slots=True)
+class DirEntry:
+ """One entry from :meth:`BackendBase.scandir`.
+
+ Mirrors :class:`os.DirEntry`: the metadata comes from the same
+ directory read as the name, so a listing costs one round trip
+ instead of one per entry plus one per attribute.
+
+ Attributes:
+ name: The entry's base name, without any leading directory.
+ is_dir: Whether the entry is a directory, following symlinks.
+ size_bytes: Size in bytes of a file. Always ``None`` for a
+ directory — its on-disk size says nothing a caller wants —
+ and ``None`` when it could not be determined (a broken
+ symlink, a vanished entry).
+ mtime: Modification time as a POSIX timestamp, or ``None``
+ for the same reasons.
+ """
+
+ name: str
+ is_dir: bool
+ size_bytes: int | None = None
+ mtime: float | None = None
+
+
# ── helpers ────────────────────────────────────────────────────────────
@@ -331,6 +365,33 @@ class BackendBase(ABC):
chunks = [chunk async for chunk in stream]
await self.write_file(path, b"".join(chunks))
+ async def read_stream(
+ self,
+ path: str,
+ chunk_size: int = DEFAULT_READ_CHUNK_SIZE,
+ ) -> AsyncIterator[bytes]:
+ """Read ``path`` as a byte stream.
+
+ The default reads the whole file through :meth:`read_file` and
+ re-slices it, so peak memory is the file size; only backends
+ that override this (``LocalBackend``) are constant-memory.
+ Overriding requires incremental access to ``exec_shell``
+ stdout, which the remote backends do not expose today.
+
+ Args:
+ path (`str`):
+ Path to the file inside the backend's environment.
+ chunk_size (`int`, defaults to 1 MiB):
+ The size of each yielded chunk.
+
+ Yields:
+ `bytes`:
+ Successive chunks of the file, in order.
+ """
+ data = await self.read_file(path)
+ for start in range(0, len(data), chunk_size):
+ yield data[start : start + chunk_size]
+
# ── derived filesystem ops (shell-based defaults) ──────────────
async def getcwd(self) -> str:
@@ -469,6 +530,133 @@ class BackendBase(ABC):
if part
]
+ async def scandir(self, path: str) -> list[DirEntry]:
+ """List one directory level with each entry's metadata.
+
+ The type, size and mtime come back from the same ``find`` run
+ as the names, so listing a directory of N entries costs one
+ round trip rather than 1 + 3N. Prefer this over
+ :meth:`list_dir` plus per-entry calls whenever the metadata is
+ wanted; ``find -printf`` is a GNU extension, so backends on
+ non-GNU userlands should override it.
+
+ ``%Y`` follows symlinks, matching what :meth:`is_dir` reports;
+ the size and mtime describe the link itself, which only
+ differs for the link's own few bytes.
+
+ Args:
+ path (`str`):
+ Directory to list inside the backend's environment.
+
+ Returns:
+ `list[DirEntry]`:
+ The immediate children, or an empty list if ``path``
+ does not exist or cannot be listed.
+ """
+ return await self._find_entries(
+ [
+ "find",
+ path,
+ "-mindepth",
+ "1",
+ "-maxdepth",
+ "1",
+ "-printf",
+ _FIND_ENTRY_FORMAT,
+ ],
+ )
+
+ async def stat(self, path: str) -> DirEntry | None:
+ """Return one path's type, size and mtime in a single call.
+
+ The single-path counterpart of :meth:`scandir`, the way
+ :func:`os.stat` sits beside :func:`os.scandir`. Prefer it over
+ asking :meth:`file_exists`, :meth:`is_dir` and
+ :meth:`stat_mtime` in turn, which is three round trips for what
+ one command answers.
+
+ Args:
+ path (`str`):
+ Path to stat inside the backend's environment.
+
+ Returns:
+ `DirEntry | None`:
+ The entry, or ``None`` if ``path`` does not exist.
+ ``name`` is the base name, as :meth:`scandir` reports
+ it.
+ """
+ entries = await self._find_entries(
+ ["find", path, "-maxdepth", "0", "-printf", _FIND_ENTRY_FORMAT],
+ skip_unresolvable=True,
+ )
+ return entries[0] if entries else None
+
+ async def _find_entries(
+ self,
+ command: list[str],
+ *,
+ skip_unresolvable: bool = False,
+ ) -> list[DirEntry]:
+ """Parse the records a ``_FIND_ENTRY_FORMAT`` run prints.
+
+ Args:
+ command (`list[str]`):
+ The ``find`` argv, already carrying the format.
+ skip_unresolvable (`bool`, defaults to ``False``):
+ Drop entries whose target could not be followed — a
+ dangling symlink, most often. :meth:`stat` wants this
+ (``os.stat`` follows the link and fails, and a caller
+ about to read the file must not be told it is there);
+ :meth:`scandir` does not, since ``os.scandir`` lists a
+ broken link like any other name.
+
+ Returns:
+ `list[DirEntry]`:
+ One entry per record, or an empty list when ``find``
+ failed (a missing path, most often).
+ """
+ result = await self.exec_shell(command)
+ if not result.ok():
+ return []
+
+ entries: list[DirEntry] = []
+ for record in result.stdout.split(b"\0"):
+ if not record:
+ continue
+ fields = record.decode("utf-8", errors="surrogateescape").split(
+ "\t",
+ 3,
+ )
+ if len(fields) != 4:
+ continue
+ kind, raw_size, raw_mtime, name = fields
+ try:
+ size: int | None = int(raw_size)
+ except ValueError:
+ size = None
+ try:
+ mtime: float | None = float(raw_mtime)
+ except ValueError:
+ mtime = None
+ # ``%Y`` reports N/L/? when it cannot follow the link. The
+ # size and mtime it still prints describe the link itself,
+ # which would read as a real 21-byte file; ``os.scandir``
+ # reports nothing there, so neither does this.
+ if kind in ("N", "L", "?"):
+ if skip_unresolvable:
+ continue
+ size, mtime = None, None
+ is_dir = kind == "d"
+ entries.append(
+ DirEntry(
+ name=name,
+ is_dir=is_dir,
+ size_bytes=None if is_dir else size,
+ mtime=mtime,
+ ),
+ )
+ return entries
+
async def stat_mtime(self, path: str) -> float | None:
"""Return the modification time of ``path``, or ``None``.
@@ -677,6 +865,27 @@ class LocalBackend(BackendBase):
async for chunk in stream:
await f.write(chunk)
+ async def read_stream(
+ self,
+ path: str,
+ chunk_size: int = DEFAULT_READ_CHUNK_SIZE,
+ ) -> AsyncIterator[bytes]:
+ """Read a local file chunk by chunk, never holding it whole.
+
+ Args:
+ path (`str`):
+ Path to the local file.
+ chunk_size (`int`, defaults to 1 MiB):
+ The size of each yielded chunk.
+
+ Yields:
+ `bytes`:
+ Successive chunks of the file, in order.
+ """
+ async with aiofiles.open(path, mode="rb") as f:
+ while chunk := await f.read(chunk_size):
+ yield chunk
+
async def getcwd(self) -> str:
"""Return the host process's current working directory.
@@ -756,6 +965,71 @@ class LocalBackend(BackendBase):
return results
return os.listdir(path)
+ async def scandir(self, path: str) -> list[DirEntry]:
+ """List a local directory with each entry's metadata.
+
+ ``os.scandir`` carries the type in the directory record itself,
+ so this is cheaper than ``os.listdir`` followed by a ``stat``
+ per entry — the same reason the base class batches its ``find``.
+
+ Args:
+ path (`str`):
+ Directory to list.
+
+ Returns:
+ `list[DirEntry]`:
+ The immediate children, or an empty list if ``path``
+ does not exist or cannot be listed.
+ """
+ entries: list[DirEntry] = []
+ try:
+ with os.scandir(path) as it:
+ for entry in it:
+ # A symlink can break, or the entry can vanish,
+ # between the listing and the stat.
+ try:
+ is_dir = entry.is_dir()
+ stat = entry.stat()
+ size, mtime = stat.st_size, stat.st_mtime
+ except OSError:
+ is_dir, size, mtime = False, None, None
+ entries.append(
+ DirEntry(
+ name=entry.name,
+ is_dir=is_dir,
+ size_bytes=None if is_dir else size,
+ mtime=mtime,
+ ),
+ )
+ except OSError:
+ return []
+ return entries
+
+ async def stat(self, path: str) -> DirEntry | None:
+ """Return one local path's type, size and mtime.
+
+ Args:
+ path (`str`):
+ Path to stat.
+
+ Returns:
+ `DirEntry | None`:
+ The entry, or ``None`` if ``path`` does not exist or
+ cannot be stat'd.
+ """
+ try:
+ # Follows symlinks, as ``os.DirEntry.stat`` does by default.
+ info = os.stat(path)
+ except OSError:
+ return None
+ is_dir = os.path.isdir(path)
+ return DirEntry(
+ name=os.path.basename(path),
+ is_dir=is_dir,
+ size_bytes=None if is_dir else info.st_size,
+ mtime=info.st_mtime,
+ )
+
async def stat_mtime(self, path: str) -> float | None:
"""Return the modification time of a local file.
diff --git a/tests/backend_local_test.py b/tests/backend_local_test.py
index 3d23366d9..e9e52305f 100644
--- a/tests/backend_local_test.py
+++ b/tests/backend_local_test.py
@@ -3,8 +3,9 @@
Exercises the three abstract primitives (``exec_shell``, ``read_file``,
``write_file``) plus the derived filesystem helpers (``file_exists``,
-``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) of the
-host-local backend, and the module-level ``normalize_newlines`` helper.
+``is_dir``, ``list_dir``, ``scandir``, ``read_stream``, ``stat_mtime``,
+``delete_path``) of the host-local backend, and the module-level
+``normalize_newlines`` helper.
``LocalBackend`` is designed to run on every platform (it spawns
programs from an argv list without a shell and implements the
@@ -265,6 +266,72 @@ class TestLocalBackendFilesystemHelpers(IsolatedAsyncioTestCase):
),
)
+ async def test_scandir_returns_metadata_per_entry(self) -> None:
+ """``scandir`` carries type, size and mtime with each name."""
+ await self.backend.write_file(
+ os.path.join(self.temp_dir.name, "f.txt"),
+ b"payload",
+ )
+ os.makedirs(os.path.join(self.temp_dir.name, "d"))
+ entries = {
+ e.name: e
+ for e in await self.backend.scandir(
+ self.temp_dir.name,
+ )
+ }
+ self.assertEqual(sorted(entries), ["d", "f.txt"])
+ self.assertFalse(entries["f.txt"].is_dir)
+ self.assertEqual(entries["f.txt"].size_bytes, 7)
+ self.assertIsNotNone(entries["f.txt"].mtime)
+ self.assertTrue(entries["d"].is_dir)
+ # A directory's own size is noise; the contract pins it to None.
+ self.assertIsNone(entries["d"].size_bytes)
+
+ async def test_stat_reports_file_and_directory(self) -> None:
+ """``stat`` answers type, size and mtime in one call."""
+ path = os.path.join(self.temp_dir.name, "f.txt")
+ await self.backend.write_file(path, b"payload")
+ entry = await self.backend.stat(path)
+ self.assertIsNotNone(entry)
+ self.assertEqual(entry.name, "f.txt")
+ self.assertFalse(entry.is_dir)
+ self.assertEqual(entry.size_bytes, 7)
+ self.assertIsNotNone(entry.mtime)
+
+ directory = await self.backend.stat(self.temp_dir.name)
+ self.assertTrue(directory.is_dir)
+ self.assertIsNone(directory.size_bytes)
+
+ async def test_stat_missing_path_returns_none(self) -> None:
+ """A path with nothing behind it stats to None, not an error."""
+ self.assertIsNone(
+ await self.backend.stat(
+ os.path.join(self.temp_dir.name, "missing"),
+ ),
+ )
+
+ async def test_scandir_missing_dir_returns_empty(self) -> None:
+ """An unlistable path yields no entries rather than raising."""
+ self.assertEqual(
+ await self.backend.scandir(
+ os.path.join(self.temp_dir.name, "missing"),
+ ),
+ [],
+ )
+
+ async def test_read_stream_chunks_without_buffering(self) -> None:
+ """``read_stream`` yields the file in ``chunk_size`` pieces."""
+ path = os.path.join(self.temp_dir.name, "f.txt")
+ await self.backend.write_file(path, b"abcdefg")
+ chunks = [c async for c in self.backend.read_stream(path, 3)]
+ self.assertEqual(chunks, [b"abc", b"def", b"g"])
+
+ async def test_read_stream_empty_file_yields_nothing(self) -> None:
+ """An empty file produces no chunks, not one empty chunk."""
+ path = os.path.join(self.temp_dir.name, "empty.txt")
+ await self.backend.write_file(path, b"")
+ self.assertEqual([c async for c in self.backend.read_stream(path)], [])
+
async def test_delete_path_file(self) -> None:
"""``delete_path`` removes a single file."""
path = os.path.join(self.temp_dir.name, "f.txt")
diff --git a/tests/service_workspace_files_test.py b/tests/service_workspace_files_test.py
new file mode 100644
index 000000000..0bf4fec4f
--- /dev/null
+++ b/tests/service_workspace_files_test.py
@@ -0,0 +1,595 @@
+# -*- coding: utf-8 -*-
+"""Tests for the workspace file-browsing endpoints.
+
+These are lightweight unit tests that do not require ``create_app``.
+Dependencies are injected by calling the endpoint coroutines directly,
+which avoids pulling a full FastAPI / Redis stack.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import time
+from typing import AsyncIterator
+from unittest import IsolatedAsyncioTestCase
+
+from fastapi import HTTPException, status
+
+from agentscope.app._router._workspace import (
+ create_download_token,
+ list_workspace_directory,
+ read_workspace_file,
+)
+from agentscope.app._service._download_token import (
+ sign_download_token,
+ verify_download_token,
+)
+from agentscope.app.storage import (
+ AgentData,
+ AgentRecord,
+ SessionConfig,
+ SessionRecord,
+ SessionSource,
+)
+from agentscope.agent import ContextConfig, ReActConfig
+from agentscope.state import AgentState
+from agentscope.tool import DirEntry
+
+SECRET = "test-signing-secret"
+
+# ---------------------------------------------------------------------------
+# Fake backend + workspace used by endpoint-level tests
+# ---------------------------------------------------------------------------
+
+
+class _FakeBackend:
+ """A tiny in-memory filesystem — posix paths only."""
+
+ def __init__(self, files: dict[str, bytes] | None = None) -> None:
+ self._files: dict[str, bytes] = {}
+ self._dirs: set[str] = {"/workspace"}
+ self.read_paths: list[str] = []
+ for p, data in (files or {}).items():
+ self._files[p] = data
+ self._ensure_parent_dirs(p)
+
+ def join_path(self, path: str, *paths: str) -> str:
+ """Join posix-style path components for the in-memory backend."""
+ return posixpath.join(path, *paths)
+
+ def _ensure_parent_dirs(self, file_path: str) -> None:
+ cur = posixpath.dirname(file_path)
+ while cur and cur not in self._dirs:
+ self._dirs.add(cur)
+ cur = posixpath.dirname(cur)
+
+ async def is_dir(self, path: str) -> bool:
+ """Return True when *path* is a tracked directory."""
+ return path in self._dirs
+
+ async def file_exists(self, path: str) -> bool:
+ """Return True when *path* is a tracked file or directory."""
+ return path in self._files or path in self._dirs
+
+ async def list_dir(
+ self,
+ path: str,
+ *,
+ recursive: bool = False,
+ ) -> list[str]:
+ """Return direct children of *path* sorted lexicographically."""
+ _ = recursive
+ out: set[str] = set()
+ for tracked in list(self._files) + list(self._dirs):
+ if posixpath.dirname(tracked) == path:
+ name = posixpath.basename(tracked)
+ if name:
+ out.add(name)
+ return sorted(out)
+
+ async def read_file(self, path: str) -> bytes:
+ """Return the raw bytes stored for *path*."""
+ self.read_paths.append(path)
+ if path not in self._files:
+ raise FileNotFoundError(path)
+ return self._files[path]
+
+ async def read_stream(
+ self,
+ path: str,
+ chunk_size: int = 4,
+ ) -> AsyncIterator[bytes]:
+ """Yield the stored bytes in small chunks, like a real backend."""
+ data = await self.read_file(path)
+ for start in range(0, len(data), chunk_size):
+ yield data[start : start + chunk_size]
+
+ def isabs(self, path: str) -> bool:
+ """Return whether *path* is absolute under POSIX semantics."""
+ return posixpath.isabs(path)
+
+ def normpath(self, path: str) -> str:
+ """Normalize a POSIX path."""
+ return posixpath.normpath(path)
+
+ def abspath(self, path: str, *, cwd: str) -> str:
+ """Resolve a relative POSIX path against *cwd*."""
+ return posixpath.normpath(
+ path if posixpath.isabs(path) else posixpath.join(cwd, path),
+ )
+
+ def basename(self, path: str) -> str:
+ """Return the final POSIX path component."""
+ return posixpath.basename(path)
+
+ async def write_file(self, path: str, data: bytes) -> bytes | None:
+ """Write *data* to *path* and ensure parent dirs exist."""
+ self._files[path] = data
+ self._ensure_parent_dirs(path)
+ return None
+
+ async def stat_mtime(self, path: str) -> float | None:
+ """Return a deterministic mtime value for tracked paths."""
+ if path in self._files or path in self._dirs:
+ return 1_700_000_000.0
+ return None
+
+ async def stat(self, path: str) -> DirEntry | None:
+ """Return one path's metadata, or None when it is not tracked."""
+ is_dir = path in self._dirs
+ if not is_dir and path not in self._files:
+ return None
+ return DirEntry(
+ name=posixpath.basename(path),
+ is_dir=is_dir,
+ size_bytes=None if is_dir else len(self._files[path]),
+ mtime=1_700_000_000.0,
+ )
+
+ async def scandir(self, path: str) -> list[DirEntry]:
+ """Return each child with its metadata, as one batch would."""
+ entries = []
+ for name in await self.list_dir(path):
+ child = posixpath.join(path, name)
+ is_dir = child in self._dirs
+ entries.append(
+ DirEntry(
+ name=name,
+ is_dir=is_dir,
+ size_bytes=(
+ None if is_dir else len(self._files.get(child, b""))
+ ),
+ mtime=1_700_000_000.0,
+ ),
+ )
+ return entries
+
+
+class _FakeWorkspace:
+ def __init__(self, backend: _FakeBackend) -> None:
+ self.workdir = "/workspace"
+ self._backend = backend
+
+ def get_backend(self) -> _FakeBackend:
+ """Expose the injected in-memory backend."""
+ return self._backend
+
+
+class _FakeWorkspaceManager:
+ def __init__(self, workspace: _FakeWorkspace) -> None:
+ self._ws = workspace
+
+ async def get_workspace(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ workspace_id: str | None = None,
+ ) -> _FakeWorkspace:
+ """Return the pre-seeded workspace, ignoring identifier args."""
+ _ = (user_id, agent_id, session_id, workspace_id)
+ return self._ws
+
+
+class _FakeStorage:
+ def __init__(self, records: list[SessionRecord]) -> None:
+ self._records = {(r.user_id, r.agent_id, r.id): r for r in records}
+
+ async def get_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> SessionRecord | None:
+ """Look up a seeded session record by composite key."""
+ return self._records.get((user_id, agent_id, session_id))
+
+
+def _make_session(
+ *,
+ user_id: str = "u",
+ agent_id: str = "a",
+ session_id: str = "s",
+ workspace_id: str = "ws-1",
+) -> SessionRecord:
+ return SessionRecord(
+ user_id=user_id,
+ agent_id=agent_id,
+ id=session_id,
+ source=SessionSource.USER,
+ state=AgentState(),
+ config=SessionConfig(
+ workspace_id=workspace_id,
+ name="test session",
+ ),
+ agent_snapshot=AgentRecord(
+ user_id=user_id,
+ source="user",
+ data=AgentData(
+ name="A",
+ context_config=ContextConfig(),
+ react_config=ReActConfig(),
+ ),
+ ),
+ )
+
+
+async def _collect(response: object) -> bytes:
+ """Drain a StreamingResponse body into bytes."""
+ chunks = [chunk async for chunk in response.body_iterator]
+ return b"".join(
+ c.encode("utf-8") if isinstance(c, str) else c for c in chunks
+ )
+
+
+# ---------------------------------------------------------------------------
+# Download tokens
+# ---------------------------------------------------------------------------
+
+
+class DownloadTokenTests(IsolatedAsyncioTestCase):
+ """Unit tests for the capability token itself."""
+
+ def test_roundtrip_returns_the_user(self) -> None:
+ """A freshly minted token verifies back to who it was for."""
+ token, expires_at = sign_download_token(SECRET, "alice", "/w/a.txt")
+ self.assertGreater(expires_at, time.time())
+ self.assertEqual(
+ verify_download_token(SECRET, token, "/w/a.txt"),
+ "alice",
+ )
+
+ def test_token_does_not_cover_another_path(self) -> None:
+ """The path is re-derived from the request, so replay fails."""
+ token, _ = sign_download_token(SECRET, "alice", "/w/a.txt")
+ with self.assertRaises(ValueError):
+ verify_download_token(SECRET, token, "/w/secret.txt")
+
+ def test_another_secret_is_rejected(self) -> None:
+ """A token minted elsewhere must not verify here."""
+ token, _ = sign_download_token("other-secret", "alice", "/w/a.txt")
+ with self.assertRaises(ValueError):
+ verify_download_token(SECRET, token, "/w/a.txt")
+
+ def test_expired_token_is_rejected(self) -> None:
+ """A TTL that has already passed makes the token useless."""
+ token, _ = sign_download_token(SECRET, "alice", "/w/a.txt", ttl=-1)
+ with self.assertRaises(ValueError):
+ verify_download_token(SECRET, token, "/w/a.txt")
+
+ def test_garbage_is_rejected(self) -> None:
+ """Malformed input must raise, not crash with an index error."""
+ for bad in ("", "not-a-token", "1.2", "x.y.z", "9999999999.YQ.YQ"):
+ with self.assertRaises(ValueError):
+ verify_download_token(SECRET, bad, "/w/a.txt")
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+class WorkspaceFileEndpointTests(IsolatedAsyncioTestCase):
+ """Call the file-browsing endpoints directly, bypassing FastAPI."""
+
+ async def asyncSetUp(self) -> None:
+ files = {
+ "/workspace/notes.txt": b"hello world",
+ "/workspace/subdir/report.md": b"# report\n\nbody\n",
+ "/elsewhere/outside.txt": b"outside the workspace",
+ }
+ self._backend = _FakeBackend(files=files)
+ self._workspace = _FakeWorkspace(self._backend)
+ self._wm = _FakeWorkspaceManager(self._workspace)
+ self._storage = _FakeStorage([_make_session()])
+
+ # ------------------------------------------------------------------
+ # directories
+ # ------------------------------------------------------------------
+
+ async def test_list_root(self) -> None:
+ """The workspace root lists its seeded files and directories."""
+ entries = await list_workspace_directory(
+ agent_id="a",
+ session_id="s",
+ path="",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ by_name = {e.name: e for e in entries}
+ self.assertEqual(sorted(by_name), ["notes.txt", "subdir"])
+ self.assertFalse(by_name["notes.txt"].is_dir)
+ self.assertEqual(by_name["notes.txt"].size_bytes, len(b"hello world"))
+ self.assertEqual(by_name["notes.txt"].updated_at, 1_700_000_000.0)
+ self.assertTrue(by_name["subdir"].is_dir)
+ self.assertIsNone(by_name["subdir"].size_bytes)
+ # Listing must not read file contents, or a directory of large
+ # files would pull all of them into memory.
+ self.assertEqual(self._backend.read_paths, [])
+
+ async def test_relative_path_resolves_against_workdir(self) -> None:
+ """A relative path is still convenient, and still works."""
+ entries = await list_workspace_directory(
+ agent_id="a",
+ session_id="s",
+ path="subdir",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ self.assertEqual([e.name for e in entries], ["report.md"])
+
+ async def test_absolute_path_outside_workspace_is_allowed(self) -> None:
+ """Browsing is not confined to the workspace root."""
+ entries = await list_workspace_directory(
+ agent_id="a",
+ session_id="s",
+ path="/elsewhere",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ self.assertEqual([e.name for e in entries], ["outside.txt"])
+
+ async def test_parent_traversal_is_allowed(self) -> None:
+ """``..`` is an ordinary path component now, not an attack."""
+ entries = await list_workspace_directory(
+ agent_id="a",
+ session_id="s",
+ path="../elsewhere",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ self.assertEqual([e.name for e in entries], ["outside.txt"])
+
+ async def test_missing_session_raises_404(self) -> None:
+ """An unknown session id must return a 404 HTTP error."""
+ with self.assertRaises(HTTPException) as ctx:
+ await list_workspace_directory(
+ agent_id="a",
+ session_id="does-not-exist",
+ path="",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ self.assertEqual(ctx.exception.status_code, status.HTTP_404_NOT_FOUND)
+
+ async def test_missing_directory_raises_404(self) -> None:
+ """Listing a path that does not exist raises a 404 error."""
+ with self.assertRaises(HTTPException) as ctx:
+ await list_workspace_directory(
+ agent_id="a",
+ session_id="s",
+ path="missing-dir",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ self.assertEqual(ctx.exception.status_code, status.HTTP_404_NOT_FOUND)
+
+ async def test_listing_a_file_raises_400(self) -> None:
+ """Listing a regular file is a client mistake, not a 404."""
+ with self.assertRaises(HTTPException) as ctx:
+ await list_workspace_directory(
+ agent_id="a",
+ session_id="s",
+ path="notes.txt",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ )
+ self.assertEqual(
+ ctx.exception.status_code,
+ status.HTTP_400_BAD_REQUEST,
+ )
+
+ # ------------------------------------------------------------------
+ # files
+ # ------------------------------------------------------------------
+
+ async def _read(self, **kwargs: object) -> object:
+ """Call the file endpoint with the shared fixtures filled in."""
+ return await read_workspace_file(
+ agent_id="a",
+ session_id="s",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ secret=SECRET,
+ **kwargs,
+ )
+
+ async def test_read_streams_content_with_inferred_type(self) -> None:
+ """The body arrives in chunks, typed from the file extension."""
+ response = await self._read(
+ path="notes.txt",
+ download=False,
+ token=None,
+ x_user_id="u",
+ )
+ self.assertEqual(response.media_type, "text/plain")
+ # Without this the browser can only show an indeterminate bar.
+ self.assertEqual(response.headers["content-length"], "11")
+ self.assertNotIn("content-disposition", response.headers)
+ self.assertEqual(await _collect(response), b"hello world")
+
+ async def test_unknown_extension_falls_back_to_octet_stream(self) -> None:
+ """An unguessable type must not become ``text/plain``."""
+ await self._backend.write_file("/workspace/blob.zzz", b"\x00\x01")
+ response = await self._read(
+ path="blob.zzz",
+ download=False,
+ token=None,
+ x_user_id="u",
+ )
+ self.assertEqual(response.media_type, "application/octet-stream")
+
+ async def test_download_sets_content_disposition(self) -> None:
+ """``download=true`` is what turns a preview into a save."""
+ response = await self._read(
+ path="notes.txt",
+ download=True,
+ token=None,
+ x_user_id="u",
+ )
+ self.assertEqual(
+ response.headers["content-disposition"],
+ "attachment; filename*=UTF-8''notes.txt",
+ )
+
+ async def test_absolute_path_outside_workspace_is_readable(self) -> None:
+ """Reading, like listing, is not confined to the workspace."""
+ response = await self._read(
+ path="/elsewhere/outside.txt",
+ download=False,
+ token=None,
+ x_user_id="u",
+ )
+ self.assertEqual(await _collect(response), b"outside the workspace")
+
+ async def test_missing_file_raises_404(self) -> None:
+ """A path with nothing behind it is a 404."""
+ with self.assertRaises(HTTPException) as ctx:
+ await self._read(
+ path="nope.txt",
+ download=False,
+ token=None,
+ x_user_id="u",
+ )
+ self.assertEqual(ctx.exception.status_code, status.HTTP_404_NOT_FOUND)
+
+ async def test_reading_a_directory_raises_400(self) -> None:
+ """Reading a directory is a client mistake, not a 404."""
+ with self.assertRaises(HTTPException) as ctx:
+ await self._read(
+ path="subdir",
+ download=False,
+ token=None,
+ x_user_id="u",
+ )
+ self.assertEqual(
+ ctx.exception.status_code,
+ status.HTTP_400_BAD_REQUEST,
+ )
+
+ # ------------------------------------------------------------------
+ # files — authentication
+ # ------------------------------------------------------------------
+
+ async def test_neither_header_nor_token_raises_401(self) -> None:
+ """The endpoint takes an optional header, not an absent guard."""
+ with self.assertRaises(HTTPException) as ctx:
+ await self._read(
+ path="notes.txt",
+ download=False,
+ token=None,
+ x_user_id=None,
+ )
+ self.assertEqual(
+ ctx.exception.status_code,
+ status.HTTP_401_UNAUTHORIZED,
+ )
+
+ async def test_token_stands_in_for_the_header(self) -> None:
+ """A minted token authorizes the download it was minted for."""
+ minted = await create_download_token(
+ agent_id="a",
+ session_id="s",
+ path="notes.txt",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ secret=SECRET,
+ )
+ # Sent back exactly as minted — the token binds the query
+ # string, since resolving it needs the user it has yet to yield.
+ response = await self._read(
+ path="notes.txt",
+ download=True,
+ token=minted.token,
+ x_user_id=None,
+ )
+ self.assertEqual(await _collect(response), b"hello world")
+
+ async def test_token_does_not_cover_the_resolved_path(self) -> None:
+ """Minting relative and downloading absolute is not the same."""
+ minted = await create_download_token(
+ agent_id="a",
+ session_id="s",
+ path="notes.txt",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ secret=SECRET,
+ )
+ with self.assertRaises(HTTPException) as ctx:
+ await self._read(
+ path="/workspace/notes.txt",
+ download=True,
+ token=minted.token,
+ x_user_id=None,
+ )
+ self.assertEqual(
+ ctx.exception.status_code,
+ status.HTTP_401_UNAUTHORIZED,
+ )
+
+ async def test_token_is_bound_to_its_path(self) -> None:
+ """A token for one file cannot be replayed against another."""
+ minted = await create_download_token(
+ agent_id="a",
+ session_id="s",
+ path="notes.txt",
+ user_id="u",
+ storage=self._storage,
+ workspace_manager=self._wm,
+ secret=SECRET,
+ )
+ with self.assertRaises(HTTPException) as ctx:
+ await self._read(
+ path="/elsewhere/outside.txt",
+ download=True,
+ token=minted.token,
+ x_user_id=None,
+ )
+ self.assertEqual(
+ ctx.exception.status_code,
+ status.HTTP_401_UNAUTHORIZED,
+ )
+
+ async def test_tampered_token_raises_401(self) -> None:
+ """An edited signature must not pass."""
+ token, _ = sign_download_token(SECRET, "u", "notes.txt")
+ with self.assertRaises(HTTPException) as ctx:
+ await self._read(
+ path="notes.txt",
+ download=True,
+ token=token[:-1] + ("A" if token[-1] != "A" else "B"),
+ x_user_id=None,
+ )
+ self.assertEqual(
+ ctx.exception.status_code,
+ status.HTTP_401_UNAUTHORIZED,
+ )