files.py 63 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411
  1. """Managed-files, chat image upload, /api/media and /api/fs dashboard routes.
  2. Helpers/state that tests monkeypatch on ``web_server`` stay there and are
  3. reached through the late-binding seam (cycle-safe).
  4. """
  5. import asyncio
  6. import base64
  7. import binascii
  8. import contextlib
  9. import hashlib
  10. import logging
  11. import mimetypes
  12. import os
  13. import re
  14. import secrets
  15. import shutil
  16. import stat
  17. import subprocess
  18. import sys
  19. import tempfile
  20. import urllib.parse
  21. from datetime import datetime
  22. from pathlib import Path, PurePosixPath
  23. from typing import Any, Dict, Optional
  24. from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
  25. from fastapi.responses import FileResponse, JSONResponse, Response, StreamingResponse
  26. from hermes_cli import web_server_file_tickets as file_tickets
  27. from hermes_cli._subprocess_compat import windows_hide_flags
  28. from hermes_cli.home_data_layout import SECRET_CACHE_STORES
  29. from hermes_cli.sqlite_safe_read import LiveConnectionError, offline_file_access
  30. from hermes_cli.staged_uploads import (
  31. ensure_profile_subdir, is_staged_upload, removed_on_failure, resolve_upload_home,
  32. )
  33. from hermes_cli.web_deps import late
  34. from hermes_cli.web_server_remote_media import remote_media_response
  35. from hermes_cli.web_upload_limit import CHAT_IMAGE_MAX_BYTES
  36. from hermes_cli.web_server_surface import route_on
  37. from hermes_cli.web_server_files import (
  38. SANDBOX_NOT_FOUND, _agent_fs_path, _agent_path_scope, _file_url_path, _fs_path, _hosted_fs_read_guard,
  39. _is_unmapped_container_path, _managed_file_entry, _managed_response_meta, _resolve_managed_path,
  40. _session_workspace,
  41. )
  42. from hermes_cli.web_models import (
  43. ChatImageUpload, FileTicketRequest, FsWriteText, ManagedDirectoryCreate, ManagedFileDelete,
  44. ManagedFileUpload,
  45. )
  46. router = APIRouter()
  47. logger = logging.getLogger(__name__)
  48. # Late-bound so a test's monkeypatch on the owning module wins at call time.
  49. _profile_scope = late("_profile_scope", "hermes_cli.web_server_profiles")
  50. get_hermes_home = late("get_hermes_home", "hermes_cli.config")
  51. load_config = late("load_config", "hermes_cli.config")
  52. load_env = late("load_env", "hermes_cli.config")
  53. _require_token = late("_require_token")
  54. # Image types GET /api/media serves — extension-allowlisted so an authenticated
  55. # caller can't pull non-image files through it.
  56. _MEDIA_CONTENT_TYPES = {
  57. ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
  58. ".webp": "image/webp", ".svg": "image/svg+xml", ".bmp": "image/bmp", ".ico": "image/x-icon",
  59. }
  60. _MEDIA_MAX_BYTES = 25 * 1024 * 1024
  61. _STREAMABLE_MEDIA_EXTENSIONS = frozenset({
  62. ".avi", ".flac", ".m4a", ".mkv", ".mov", ".mp3", ".mp4", ".ogg", ".opus", ".wav", ".webm",
  63. })
  64. _FS_READDIR_HIDDEN = {
  65. ".git", ".hg", ".svn", ".cache", ".next", ".turbo", ".venv", "__pycache__",
  66. "build", "dist", "node_modules", "target", "venv",
  67. }
  68. # Basenames the managed-files API must never list, read or download: credential
  69. # stores that become live secrets in the browsable tree the moment an operator
  70. # points the managed root at HERMES_HOME. Mirrors the two canonical guards
  71. # (agent.file_safety.get_read_block_error, gateway.platforms.base
  72. # ._ROOT_CREDENTIAL_FILES) so the Files tab never lags behind them.
  73. # These typically contain credentials (API keys, tokens) and exposing them through the dashboard file
  74. # browser is a security leak — see issue #57505.
  75. _SENSITIVE_MANAGED_FILE_BASENAMES = frozenset({
  76. "auth.json", "auth.lock", "credentials", "config.yaml", ".anthropic_oauth.json",
  77. "google_token.json", "google_oauth_pending.json", "google_oauth.json",
  78. "webhook_subscriptions.json",
  79. *(PurePosixPath(store).name for store in SECRET_CACHE_STORES), # secret caches, Photon sidecar token
  80. ".git-credentials", # git's credential-store cache (file_safety blocks it too)
  81. })
  82. # Directory names whose whole subtree is credential material (the canonical
  83. # guards deny these as trees: _ROOT_CREDENTIAL_DIRS and the mcp-tokens/ prefix
  84. # match). The browser can descend into subdirs, so a basename-only guard would
  85. # still expose ``mcp-tokens/<server>.json``; match on ANY path component so the
  86. # trees are blocked wherever they sit under the root, no HERMES_HOME resolution.
  87. _SENSITIVE_MANAGED_DIR_NAMES = frozenset({"mcp-tokens", "pairing"})
  88. def _is_sensitive_filename(name: str) -> bool:
  89. """Basename denylist: ``.env`` / ``.env.<suffix>`` / ``.envrc`` plus the
  90. credential-store basenames. Case-insensitive so ``.ENV`` / ``Auth.JSON``
  91. on case-insensitive mounts can't slip past. Basename-only — call sites use
  92. :func:`_is_sensitive_path`, which adds the credential-directory check."""
  93. lowered = name.lower()
  94. if lowered == ".env" or lowered.startswith(".env.") or lowered == ".envrc":
  95. return True
  96. return lowered in _SENSITIVE_MANAGED_FILE_BASENAMES
  97. def _is_sensitive_path(path: Path) -> bool:
  98. """True when the basename is sensitive OR any path component (case-
  99. insensitive) is a credential directory. Read-side guard (list/read/
  100. download); the write endpoints are a separate threat class.
  101. Read-side only: this guards list/read/download (the #57505 exfil surface). The write endpoints
  102. (upload/mkdir/delete) are a separate threat class handled by the write-path checks; extending this guard
  103. to them is out of scope for this fix.
  104. """
  105. if _is_sensitive_filename(path.name):
  106. return True
  107. return any(part.lower() in _SENSITIVE_MANAGED_DIR_NAMES for part in path.parts)
  108. _FS_TEXT_SOURCE_MAX_BYTES = 64 * 1024 * 1024
  109. _FS_TEXT_PREVIEW_MAX_BYTES = 512 * 1024
  110. # Spot-editor save ceiling: the editor only opens non-truncated text (<= the
  111. # preview cap), so this guards against a pasted megablob, not expected payloads.
  112. _FS_TEXT_WRITE_MAX_BYTES = 8 * 1024 * 1024
  113. _FS_PREVIEW_LANGUAGE_BY_EXT = {
  114. ".c": "c", ".conf": "ini", ".cpp": "cpp", ".css": "css", ".csv": "csv", ".go": "go",
  115. ".graphql": "graphql", ".h": "c", ".hpp": "cpp", ".html": "html", ".java": "java",
  116. ".js": "javascript", ".json": "json", ".jsx": "jsx", ".kt": "kotlin", ".lua": "lua",
  117. ".md": "markdown", ".mjs": "javascript", ".py": "python", ".rb": "ruby", ".rs": "rust",
  118. ".sh": "shell", ".sql": "sql", ".svg": "xml", ".toml": "toml", ".ts": "typescript",
  119. ".tsx": "tsx", ".txt": "text", ".xml": "xml", ".yaml": "yaml", ".yml": "yaml", ".zsh": "shell",
  120. }
  121. _FS_MIME_TYPES = {
  122. ".avi": "video/x-msvideo", ".bmp": "image/bmp", ".flac": "audio/flac", ".gif": "image/gif",
  123. ".jpeg": "image/jpeg", ".jpg": "image/jpeg", ".m4a": "audio/mp4", ".mkv": "video/x-matroska",
  124. ".mov": "video/quicktime", ".mp3": "audio/mpeg", ".mp4": "video/mp4", ".ogg": "audio/ogg",
  125. ".opus": "audio/ogg; codecs=opus", ".png": "image/png", ".svg": "image/svg+xml",
  126. ".wav": "audio/wav", ".webm": "video/webm", ".webp": "image/webp",
  127. }
  128. def _fs_mime_type(path: Path) -> str:
  129. suffix = path.suffix.lower()
  130. if suffix in _FS_MIME_TYPES:
  131. return _FS_MIME_TYPES[suffix]
  132. guessed, _ = mimetypes.guess_type(str(path))
  133. return guessed or "application/octet-stream"
  134. def _fs_looks_binary(data: bytes) -> bool:
  135. if not data:
  136. return False
  137. if b"\0" in data:
  138. return True
  139. suspicious = sum(1 for byte in data if byte < 32 and byte not in {9, 10, 13})
  140. return suspicious / len(data) > 0.12
  141. @contextlib.contextmanager
  142. def _io_errors(denied: str, failed: str):
  143. """PermissionError -> 403 ``denied``; other OSError -> 500 ``"<failed>: <exc>"``."""
  144. try:
  145. yield
  146. except PermissionError:
  147. raise HTTPException(status_code=403, detail=denied)
  148. except OSError as exc:
  149. raise HTTPException(status_code=500, detail=f"{failed}: {exc}")
  150. def _fs_sandbox_not_found_detail(path: Path, profile_home: Optional[Path] = None) -> str:
  151. """Distinguish an untranslated agent-sandbox path from a plain missing file."""
  152. unmapped = _is_unmapped_container_path(path.as_posix(), profile_home=profile_home)
  153. return SANDBOX_NOT_FOUND if unmapped else "File not found"
  154. def _fs_regular_file(path: Path, profile_home: Optional[Path] = None) -> tuple[Path, os.stat_result]:
  155. # The caller already resolved *path* (a file: URL decoded once); decoding it again here would
  156. # read the name report%2fsecret.txt as report/secret.txt.
  157. target = _fs_path(str(path), decode_fallback=False)
  158. try:
  159. st = target.stat()
  160. except (FileNotFoundError, NotADirectoryError):
  161. raise HTTPException(status_code=404, detail=_fs_sandbox_not_found_detail(target, profile_home))
  162. except PermissionError:
  163. raise HTTPException(status_code=403, detail="File is not readable")
  164. except OSError as exc:
  165. raise HTTPException(status_code=400, detail=str(exc) or "Invalid path")
  166. if stat.S_ISDIR(st.st_mode):
  167. raise HTTPException(status_code=400, detail="Path points to a directory")
  168. if not stat.S_ISREG(st.st_mode):
  169. raise HTTPException(status_code=400, detail="Only regular files can be read")
  170. if _is_sensitive_path(target):
  171. raise HTTPException(status_code=403, detail="Access to sensitive files is not allowed")
  172. return target, st
  173. @contextlib.contextmanager
  174. def _serve_offline(target: Path):
  175. """Hold ``offline_file_access`` for serving ``target``; 409 while a SQLite connection to it is live.
  176. Callers keep the block open through the file's close: a raw close cancels this process's
  177. SQLite POSIX locks on it."""
  178. try:
  179. with offline_file_access(target, what="serve"):
  180. yield
  181. except LiveConnectionError as exc:
  182. raise HTTPException(status_code=409, detail=str(exc)) from exc
  183. def _refuse_live_database(target: Path) -> None:
  184. """Point-in-time 409 before streaming ``target`` while a SQLite connection to it is live.
  185. ``FileResponse`` opens and closes the file in-process, and that raw close cancels the
  186. connection's POSIX locks. The registry lock can't be held across a streamed response
  187. (never across an await/yield), so streamed routes only get this admission check. It
  188. takes the global registry lock, which other threads hold across whole-file reads, so
  189. call it via ``asyncio.to_thread``."""
  190. with _serve_offline(target):
  191. pass
  192. def _fs_read_bytes(target: Path, limit: Optional[int] = None) -> bytes:
  193. """Read (a prefix of) ``target``; 403/400 on failure, 409 while a SQLite connection to it is live."""
  194. try:
  195. with _serve_offline(target):
  196. if limit is None:
  197. return target.read_bytes()
  198. with target.open("rb") as handle:
  199. return handle.read(limit)
  200. except PermissionError:
  201. raise HTTPException(status_code=403, detail="File is not readable")
  202. except OSError as exc:
  203. raise HTTPException(status_code=400, detail=str(exc) or "File read failed")
  204. def _fs_find_git_root(start: Path) -> str | None:
  205. directory = start
  206. for _ in range(50):
  207. try:
  208. if (directory / ".git").exists():
  209. return str(directory)
  210. except OSError:
  211. return None
  212. parent = directory.parent
  213. if parent == directory:
  214. return None
  215. directory = parent
  216. return None
  217. def _fs_default_cwd(profile: Optional[str] = None) -> str:
  218. """The host folder a new session or browser terminal of *profile* starts in: its
  219. ``terminal.cwd`` when that names a folder, else the home folder."""
  220. from tools.terminal_scope import TerminalPolicyUnavailable, build_profile_terminal_scope
  221. with _profile_scope(profile) as scoped:
  222. if scoped is None:
  223. # The serving process's own profile: its startup bridged terminal.cwd into
  224. # TERMINAL_CWD. A placeholder terminal.cwd counts as unset, so TERMINAL_CWD answers.
  225. cfg_terminal = load_config().get("terminal") or {}
  226. candidates = (cfg_terminal.get("cwd"), os.environ.get("TERMINAL_CWD"))
  227. else:
  228. # Another profile served by this process: the TERMINAL_CWD its own turns run under
  229. # (config.yaml over .env), never this process's environment.
  230. try:
  231. candidates = (build_profile_terminal_scope(scoped).get("TERMINAL_CWD"),)
  232. except TerminalPolicyUnavailable:
  233. candidates = ()
  234. for raw in candidates:
  235. raw = str(raw or "").strip()
  236. if raw in {"", ".", "auto", "cwd"}:
  237. continue
  238. try:
  239. candidate = Path(raw).expanduser().resolve(strict=False)
  240. if candidate.is_dir():
  241. return str(candidate)
  242. except (OSError, RuntimeError):
  243. pass
  244. return str(Path.home())
  245. def _fs_git_branch(cwd: str) -> str:
  246. try:
  247. # git emits UTF-8 (branch names, localized "not a git repository" stderr); the locale codec
  248. # (cp936 on zh-CN Windows) raised inside communicate()'s reader threads on every poll (#83851).
  249. run_kwargs: dict[str, Any] = {"capture_output": True, "text": True, "encoding": "utf-8",
  250. "errors": "replace", "timeout": 2}
  251. if sys.platform == "win32":
  252. run_kwargs["creationflags"] = windows_hide_flags()
  253. result = subprocess.run(["git", "-C", cwd, "branch", "--show-current"], **run_kwargs, check=False)
  254. return result.stdout.strip() if result.returncode == 0 else ""
  255. except Exception:
  256. return ""
  257. def _fs_backend(profile: Optional[str] = None):
  258. """Return the profile's SSH workspace adapter, or None for host-local FS.
  259. Only an uncached adapter dials the host: the profile's first file request since the server
  260. started, or the first after a setting the adapter is built from changes. When that dial fails,
  261. or the settings cannot dial at all (no host or user, no ``ssh`` on PATH), the request answers
  262. 503 ``SSH workspace is unavailable`` and the log names the cause the 503 hides. A cached
  263. adapter is not re-dialed here: a host that goes down after it connected fails the read itself,
  264. which each route answers on its own.
  265. """
  266. from hermes_cli.ssh_workspace_fs import SshWorkspaceFsError, get_ssh_workspace_fs
  267. with _profile_scope(profile):
  268. terminal = dict(load_config().get("terminal") or {})
  269. profile_env = load_env()
  270. for key, env_name in {
  271. "ssh_host": "TERMINAL_SSH_HOST",
  272. "ssh_user": "TERMINAL_SSH_USER",
  273. "ssh_port": "TERMINAL_SSH_PORT",
  274. "ssh_key": "TERMINAL_SSH_KEY",
  275. }.items():
  276. if not terminal.get(key) and profile_env.get(env_name):
  277. terminal[key] = profile_env[env_name]
  278. profile_key = (profile or "current").strip().lower() or "current"
  279. try:
  280. return get_ssh_workspace_fs(profile_key, terminal)
  281. except SshWorkspaceFsError as exc:
  282. logger.warning("SSH workspace for profile %s is unavailable: %s", profile_key, exc.__cause__ or exc)
  283. _raise_fs_backend_error(exc)
  284. def _chat_image_dir(home: Path) -> Path:
  285. """Where browser image pastes land: the profile's canonical image staging dir on this host
  286. (``gateway.platforms.base.get_image_cache_dir``), the only one attachment admission accepts."""
  287. from hermes_constants import get_hermes_dir
  288. return get_hermes_dir("cache/images", "image_cache", home=home)
  289. def _is_host_file(path: str, profile: Optional[str]) -> bool:
  290. """Whether *path* is a file the profile keeps on this host even when its workspace is an SSH
  291. machine, read back to be previewed and sent: a browser paste in its image cache, or a file the
  292. browser's picker staged in its uploads folder. Only a file directly in one of those two folders
  293. counts, after resolving symlinks and ``..``, so an SSH profile reads no other host file here.
  294. A ``file:`` URL counts by the native path it names, decoded once as ``_fs_path`` decodes it."""
  295. if path.lower().startswith("file:"):
  296. try:
  297. path = _file_url_path(path)
  298. except ValueError:
  299. return False
  300. if not Path(path).is_absolute():
  301. return False
  302. try:
  303. target = Path(path).resolve(strict=True)
  304. except (OSError, RuntimeError, ValueError): # ValueError: a decoded NUL (``%00``)
  305. return False # not on this host: the workspace's to answer
  306. with _profile_scope(profile):
  307. home = get_hermes_home()
  308. cache = _chat_image_dir(home)
  309. try:
  310. if target.parent == cache.resolve(strict=True):
  311. return True
  312. except (OSError, RuntimeError):
  313. pass
  314. return is_staged_upload(home, target)
  315. def _remote_fs_backend(path: str, profile: Optional[str]):
  316. """The SSH workspace reader for *path*, or None when this host owns it. The host's pastes and
  317. staged uploads are checked before the SSH machine is dialed, so they read back while that
  318. machine is down; every other path is the SSH machine's to answer (see ``_fs_backend``)."""
  319. if _is_host_file(path, profile):
  320. return None
  321. return _fs_backend(profile)
  322. def _raise_fs_backend_error(exc: Exception) -> None:
  323. from hermes_cli.ssh_workspace_fs import SshWorkspaceFsError
  324. if not isinstance(exc, SshWorkspaceFsError):
  325. raise exc
  326. status = {
  327. "EACCES": 403,
  328. "ECONN": 503,
  329. "EFBIG": 413,
  330. "EINVAL": 400,
  331. "EIO": 502,
  332. "ENOENT": 404,
  333. "ENOTREG": 400,
  334. }.get(exc.code, 400)
  335. detail = {
  336. "EACCES": "File is not readable",
  337. "ECONN": "SSH workspace is unavailable",
  338. "EFBIG": "File too large",
  339. "EINVAL": "Invalid path",
  340. "EIO": "SSH workspace request failed",
  341. "ENOENT": "File not found",
  342. "ENOTREG": "Only regular files can be read",
  343. }.get(exc.code, str(exc) or "Filesystem request failed")
  344. raise HTTPException(status_code=status, detail=detail)
  345. def _media_serve_roots() -> list[Path]:
  346. """Directories GET /api/media may read: where the agent and attach pipeline
  347. actually write media (images, screenshots, cache). Stops an authenticated
  348. client reading image-suffixed files anywhere else on disk."""
  349. home = get_hermes_home()
  350. out: list[Path] = []
  351. for root in (home / "images", home / "screenshots", home / "cache"):
  352. try:
  353. out.append(root.resolve())
  354. except (OSError, RuntimeError):
  355. continue
  356. return out
  357. def _read_base64_file(path: Path) -> str:
  358. """Read and encode a bounded file from a worker thread; 409 while a SQLite connection to it is live."""
  359. with _serve_offline(path):
  360. data = path.read_bytes()
  361. # Encode after release: only the open/read/close needs the registry lock.
  362. return base64.b64encode(data).decode("ascii")
  363. @router.get("/api/media")
  364. async def get_media(path: str):
  365. """Return a gateway-local image as a base64 data URL for remote clients
  366. that can't read this machine's disk. Auth-gated; restricted to the image
  367. allowlist, a size cap AND the resolved (symlink-safe) media roots."""
  368. try:
  369. target = Path(path).expanduser().resolve()
  370. except (OSError, RuntimeError):
  371. raise HTTPException(status_code=400, detail="Invalid path")
  372. if target.suffix.lower() not in _MEDIA_CONTENT_TYPES:
  373. raise HTTPException(status_code=415, detail="Unsupported media type")
  374. roots = _media_serve_roots()
  375. if not any(target == root or root in target.parents for root in roots):
  376. raise HTTPException(status_code=403, detail="Path outside media roots")
  377. if not target.is_file():
  378. raise HTTPException(status_code=404, detail="File not found")
  379. if target.stat().st_size > _MEDIA_MAX_BYTES:
  380. raise HTTPException(status_code=413, detail="File too large")
  381. encoded = await asyncio.to_thread(_read_base64_file, target)
  382. return {"data_url": f"data:{_MEDIA_CONTENT_TYPES[target.suffix.lower()]};base64,{encoded}"}
  383. # Remote image URLs an authenticated proxy may fetch for a client that cannot
  384. # reach the CDN itself (#74564: a Desktop on a restricted network renders an
  385. # agent-generated FAL image inline; the direct link is blocked, but the GATEWAY
  386. # hosts a working route to the CDN and already holds the generation credentials).
  387. # Host-allowlisted + size-capped like the rest of the media surface.
  388. _MEDIA_PROXY_ALLOWED_HOSTS = (
  389. "fal.media", "fal.run", "v3.fal.media", "storage.googleapis.com",
  390. "*.fal.media", "*.fal.run",
  391. )
  392. _MEDIA_PROXY_TIMEOUT_S = 20.0
  393. def _media_proxy_host_allowed(host: str) -> bool:
  394. host = host.lower().rstrip(".")
  395. return any(
  396. host == allowed.lstrip("*.") or (allowed.startswith("*.") and host.endswith(allowed[1:]))
  397. for allowed in _MEDIA_PROXY_ALLOWED_HOSTS
  398. )
  399. @router.get("/api/media/proxy")
  400. async def proxy_remote_media(url: str, request: Request):
  401. """Fetch a remote image URL the gateway can reach but the client cannot
  402. (#74564), returning the same ``data_url`` shape as ``/api/media``. Only
  403. allowlisted image CDNs; the bytes stay behind the size cap."""
  404. _require_token(request)
  405. try:
  406. parsed = urllib.parse.urlparse((url or "").strip())
  407. except ValueError as exc:
  408. raise HTTPException(status_code=400, detail="A remote image URL is required") from exc
  409. if parsed.scheme not in ("http", "https") or not parsed.hostname:
  410. raise HTTPException(status_code=400, detail="A remote image URL is required")
  411. if not _media_proxy_host_allowed(parsed.hostname):
  412. raise HTTPException(status_code=403, detail="Image host not allowed")
  413. if not parsed.path or Path(parsed.path).suffix.lower() not in _MEDIA_CONTENT_TYPES:
  414. # Generated-image CDN URLs are content-hash paths with no extension;
  415. # a missing extension is expected, so only reject explicit non-image
  416. # extensions and let content type be sniffed from the response.
  417. if Path(parsed.path).suffix and Path(parsed.path).suffix.lower() not in _MEDIA_CONTENT_TYPES:
  418. raise HTTPException(status_code=415, detail="Unsupported media type")
  419. import httpx
  420. try:
  421. async with httpx.AsyncClient(timeout=_MEDIA_PROXY_TIMEOUT_S, follow_redirects=True) as client:
  422. response = await client.get(url)
  423. except Exception as exc:
  424. raise HTTPException(status_code=502, detail=f"Image fetch failed: {exc}")
  425. if response.status_code != 200:
  426. raise HTTPException(status_code=502, detail=f"Image fetch returned HTTP {response.status_code}")
  427. content_type = (response.headers.get("content-type") or "").split(";")[0].strip().lower()
  428. if content_type not in _MEDIA_CONTENT_TYPES.values():
  429. raise HTTPException(status_code=415, detail="Unsupported media type")
  430. data = response.content
  431. if len(data) > _MEDIA_MAX_BYTES:
  432. raise HTTPException(status_code=413, detail="File too large")
  433. encoded = base64.b64encode(data).decode("ascii")
  434. return {"data_url": f"data:{content_type};base64,{encoded}"}
  435. def _decode_data_url(data_url: str) -> tuple[bytes, str]:
  436. from hermes_cli.web_server import _MANAGED_FILE_MAX_BYTES
  437. text = (data_url or "").strip()
  438. if not text.startswith("data:") or "," not in text:
  439. raise HTTPException(status_code=400, detail="Upload payload must be a data URL")
  440. header, encoded = text.split(",", 1)
  441. mime_type = header[5:].split(";", 1)[0] or "application/octet-stream"
  442. if ";base64" not in header:
  443. raise HTTPException(status_code=400, detail="Upload payload must be base64 encoded")
  444. try:
  445. data = base64.b64decode(encoded, validate=True)
  446. except (binascii.Error, ValueError):
  447. raise HTTPException(status_code=400, detail="Upload payload is not valid base64")
  448. if len(data) > _MANAGED_FILE_MAX_BYTES:
  449. raise HTTPException(status_code=413, detail="File is too large")
  450. return data, mime_type
  451. _CHAT_IMAGE_UPLOAD_MAX_BYTES = CHAT_IMAGE_MAX_BYTES
  452. _CHAT_IMAGE_ALLOWED_EXTENSIONS = frozenset({".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"})
  453. _CHAT_IMAGE_MAGIC: tuple[tuple[bytes, str], ...] = (
  454. (b"\x89PNG\r\n\x1a\n", ".png"), (b"\xff\xd8\xff", ".jpg"),
  455. (b"GIF87a", ".gif"), (b"GIF89a", ".gif"), (b"BM", ".bmp"),
  456. )
  457. def _sanitize_chat_image_filename(filename: str | None) -> str:
  458. candidate = Path(str(filename or "").strip()).name
  459. candidate = re.sub(r"[\x00-\x1f]+", "_", candidate)
  460. return candidate.strip().strip(".") or "pasted-image"
  461. def _chat_image_extension(data: bytes) -> str | None:
  462. head = data[:16]
  463. if head.startswith(b"RIFF") and head[8:12] == b"WEBP":
  464. return ".webp"
  465. for sig, ext in _CHAT_IMAGE_MAGIC:
  466. if head.startswith(sig):
  467. return ext
  468. return None
  469. def _decode_chat_image_upload(payload: ChatImageUpload) -> tuple[bytes, str, str]:
  470. data, mime_type = _decode_data_url(payload.data_url)
  471. if not mime_type.lower().startswith("image/"):
  472. raise HTTPException(status_code=400, detail="Upload payload must be an image")
  473. if len(data) > _CHAT_IMAGE_UPLOAD_MAX_BYTES:
  474. mb = _CHAT_IMAGE_UPLOAD_MAX_BYTES // (1024 * 1024)
  475. raise HTTPException(status_code=413, detail=f"Image is too large; cap is {mb} MB")
  476. ext = _chat_image_extension(data)
  477. if ext not in _CHAT_IMAGE_ALLOWED_EXTENSIONS:
  478. raise HTTPException(status_code=400, detail="Unsupported image type")
  479. return data, mime_type, ext
  480. @router.post("/api/chat/image-upload")
  481. async def upload_chat_image(payload: ChatImageUpload, profile: Optional[str] = None):
  482. """Persist a browser clipboard image where the embedded TUI can read it.
  483. Browser clipboard bytes aren't visible to the server-side clipboard, so the
  484. /chat page uploads them here and drives the TUI's ``/image <path>`` with
  485. the returned gateway-visible path under ``HERMES_HOME/images/`` (the same
  486. dir ``clipboard.paste`` / ``image.attach`` use).
  487. """
  488. def _run():
  489. data, mime_type, ext = _decode_chat_image_upload(payload)
  490. home = resolve_upload_home(profile)
  491. from hermes_constants import apply_secure_dir_policy, assert_named_profile_home_live
  492. img_dir = ensure_profile_subdir(
  493. home,
  494. str(_chat_image_dir(home).relative_to(home)),
  495. denied="Image directory is not writable",
  496. failed="Could not create image directory",
  497. )
  498. apply_secure_dir_policy(img_dir, home=home)
  499. stem = Path(_sanitize_chat_image_filename(payload.filename)).stem or "pasted-image"
  500. stem = re.sub(r"[^A-Za-z0-9_.-]+", "_", stem).strip("._-") or "pasted-image"
  501. ts = datetime.now().strftime("%Y%m%d_%H%M%S")
  502. target = img_dir / f"dashboard_{ts}_{secrets.token_hex(4)}_{stem}{ext}"
  503. with removed_on_failure(target):
  504. with _io_errors("Image directory is not writable", "Could not write image"):
  505. target.write_bytes(data)
  506. try:
  507. # A deletion recorded while the bytes were written wins: never report a path in it.
  508. assert_named_profile_home_live(home)
  509. except FileNotFoundError as exc:
  510. raise HTTPException(status_code=404, detail="Profile was deleted during upload") from exc
  511. return {
  512. "ok": True,
  513. "path": str(target),
  514. "name": target.name,
  515. "bytes": len(data),
  516. "mime_type": mime_type,
  517. }
  518. # The body does file I/O: keep it off the loop. It resolves the profile home without
  519. # entering _profile_scope, so a paste never queues behind its process-wide skills lock.
  520. return await asyncio.to_thread(_run)
  521. @router.get("/api/files")
  522. def list_managed_files(request: Request, path: Optional[str] = None):
  523. policy, target, display_path = _resolve_managed_path(path, request)
  524. if not target.exists():
  525. raise HTTPException(status_code=404, detail="Path not found")
  526. if not target.is_dir():
  527. raise HTTPException(status_code=400, detail="Path is not a directory")
  528. with _io_errors("Directory is not readable", "Could not read directory"), os.scandir(target) as scan:
  529. entries = []
  530. for entry in scan:
  531. entry_path = Path(entry.path)
  532. if _is_sensitive_path(entry_path):
  533. continue
  534. metadata = _managed_file_entry(policy, entry_path, skip_missing=True)
  535. if metadata is not None:
  536. entries.append(metadata)
  537. entries.sort(key=lambda item: (not item["is_directory"], str(item["name"]).lower()))
  538. locked_root = policy.locked_root
  539. parent = None
  540. if target.parent != target and (locked_root is None or target != locked_root):
  541. parent = str(target.parent)
  542. return {"path": display_path, "parent": parent, "entries": entries, **_managed_response_meta(policy)}
  543. def _managed_readable_file(
  544. request: Request, path: str, *, create_root: bool = True,
  545. ) -> tuple[Any, Path, str, int, str]:
  546. """Resolve + guard a managed file for reading: existence, regular file,
  547. sensitive-path denylist. Returns (policy, target, display_path, max_bytes,
  548. mime_type). Callers own the live-SQLite 409 (held through the read for
  549. /api/files/read, point-in-time for streamed responses)."""
  550. from hermes_cli.web_server import _MANAGED_FILE_MAX_BYTES
  551. policy, target, display_path = _resolve_managed_path(
  552. path, request, create_root=create_root, for_agent_read=True,
  553. )
  554. if not target.exists():
  555. raise HTTPException(status_code=404, detail="File not found")
  556. if not target.is_file():
  557. raise HTTPException(status_code=400, detail="Path is not a file")
  558. if _is_sensitive_path(target):
  559. raise HTTPException(status_code=403, detail="Access to sensitive files is not allowed")
  560. mime_type = mimetypes.guess_type(target.name)[0] or "application/octet-stream"
  561. return policy, target, display_path, _MANAGED_FILE_MAX_BYTES, mime_type
  562. def _managed_file_size(target: Path, max_bytes: int) -> int:
  563. try:
  564. size = target.stat().st_size
  565. except OSError as exc:
  566. raise HTTPException(status_code=500, detail=f"Could not stat file: {exc}")
  567. if size > max_bytes:
  568. raise HTTPException(status_code=413, detail="File is too large")
  569. return size
  570. @router.get("/api/files/read")
  571. def read_managed_file(request: Request, path: str):
  572. policy, target, display_path, max_bytes, mime_type = _managed_readable_file(request, path)
  573. size = _managed_file_size(target, max_bytes)
  574. with _io_errors("File is not readable", "Could not read file"):
  575. encoded = _read_base64_file(target)
  576. # Rendered here, on the worker: returned as a dict, the multi-MB data URL would be serialized on the event loop.
  577. return JSONResponse({
  578. "name": target.name,
  579. "path": display_path,
  580. "size": size,
  581. "mime_type": mime_type,
  582. "data_url": f"data:{mime_type};base64,{encoded}",
  583. **_managed_response_meta(policy),
  584. })
  585. async def _managed_file_response(
  586. request: Request,
  587. path: str,
  588. *,
  589. content_disposition_type: str,
  590. media_only: bool = False,
  591. ) -> FileResponse:
  592. """Range-aware response after applying managed-file policy. A player source
  593. (``media_only``) has no size cap: it is served from disk one Range at a
  594. time, as an SSH profile's clip already is, so a long recording plays."""
  595. authority = getattr(request.state, "file_ticket_authority", None)
  596. if authority is not None:
  597. from hermes_cli.web_server_file_response import OpenedFileResponse
  598. return OpenedFileResponse(
  599. path=str(authority.target),
  600. opener=lambda: _open_ticket_file(request, authority, media_only=media_only),
  601. media_type=_fs_mime_type(authority.target),
  602. filename=authority.target.name,
  603. content_disposition_type=content_disposition_type,
  604. headers={"X-Content-Type-Options": "nosniff"} if media_only else None,
  605. )
  606. _policy, target, _display_path, max_bytes, mime_type = _managed_readable_file(request, path)
  607. if media_only and target.suffix.lower() not in _STREAMABLE_MEDIA_EXTENSIONS:
  608. raise HTTPException(status_code=415, detail="Unsupported media type")
  609. if not media_only:
  610. _managed_file_size(target, max_bytes)
  611. await asyncio.to_thread(_refuse_live_database, target)
  612. return FileResponse(
  613. path=str(target),
  614. media_type=mime_type,
  615. filename=target.name,
  616. content_disposition_type=content_disposition_type,
  617. headers={"X-Content-Type-Options": "nosniff"} if media_only else None,
  618. )
  619. def _open_ticket_file(request: Request, authority: file_tickets.FileAuthority, *, media_only: bool):
  620. """Check the ticket's profile homes are still live and pin the file the ticket names."""
  621. def checked():
  622. _policy, target, _display, max_bytes, _mime = _managed_readable_file(
  623. request, str(authority.target), create_root=False,
  624. )
  625. if media_only and target.suffix.lower() not in _STREAMABLE_MEDIA_EXTENSIONS:
  626. raise HTTPException(status_code=415, detail="Unsupported media type")
  627. return target, None if media_only else max_bytes
  628. return _pin_ticket_file(authority, checked)
  629. def _pin_ticket_file(authority: file_tickets.FileAuthority, checked):
  630. """Open the host file *authority* names once its profile homes are still live and ``checked()``
  631. (the route's own read rules) returns that same file and its size cap (None: no cap)."""
  632. try:
  633. authority.check_live()
  634. target, max_bytes = checked()
  635. if target != authority.target:
  636. raise HTTPException(status_code=403, detail="File ticket target changed")
  637. _refuse_live_database(target)
  638. handle = target.open("rb")
  639. try:
  640. opened = os.fstat(handle.fileno())
  641. if not stat.S_ISREG(opened.st_mode):
  642. raise HTTPException(status_code=400, detail="Only regular files can be read")
  643. if max_bytes is not None and opened.st_size > max_bytes:
  644. raise HTTPException(status_code=413, detail="File is too large")
  645. return handle
  646. except BaseException:
  647. handle.close()
  648. raise
  649. except FileNotFoundError as exc:
  650. raise HTTPException(status_code=404, detail="File ticket profile or resource is unavailable") from exc
  651. except PermissionError as exc:
  652. raise HTTPException(status_code=403, detail="File is not readable") from exc
  653. @router.post("/api/files/ticket", dependencies=[Depends(route_on("browser_files"))])
  654. async def issue_file_ticket(payload: FileTicketRequest, request: Request):
  655. """Ticket a browser download/media URL instead of putting the session token in it."""
  656. from hermes_cli.web_routers.sessions import _history_profile_home
  657. from hermes_constants import named_profile_home
  658. def owner_home():
  659. return Path(_history_profile_home(payload.profile))
  660. def capture():
  661. _policy, target, _display, _max, _mime = _managed_readable_file(request, path, create_root=False)
  662. homes = [owner]
  663. target_home = named_profile_home(target)
  664. if target_home is not None and target_home not in homes:
  665. homes.append(target_home)
  666. authority = file_tickets.FileAuthority(target, tuple(homes))
  667. authority.check_live()
  668. return authority
  669. try:
  670. # Capture the session/profile owner BEFORE looking up its cwd. The file
  671. # may be outside that home, but the ticket must still die with its owner.
  672. owner = await asyncio.to_thread(owner_home)
  673. # Before the backend is chosen: an SSH profile's ticket checks its session too.
  674. session = await _fs_owned_session(payload.session_id, payload.profile)
  675. if payload.route == "download":
  676. authority = await _fs_download_authority(
  677. request, payload.path, payload.profile, payload.session_id, owner, session,
  678. )
  679. else:
  680. # An SSH profile's clip is captured on its SSH machine; a host-staged file on this host.
  681. authority = await _remote_file_authority(payload.path, payload.profile, owner, _remote_stream_target)
  682. path = payload.path
  683. if authority is None and (payload.session_id is not None or path.lower().startswith("file:")):
  684. path = str(await _fs_download_path(path, payload.profile, payload.session_id, session=session))
  685. if authority is None:
  686. authority = await asyncio.to_thread(capture)
  687. except FileNotFoundError as exc:
  688. raise HTTPException(status_code=404, detail="File ticket profile is unavailable") from exc
  689. query = {"path": payload.path, "profile": payload.profile, "session_id": payload.session_id}
  690. ticket = file_tickets.mint(
  691. payload.route, {key: value for key, value in query.items() if value is not None}, authority=authority,
  692. session_token=file_tickets.session_token_of(request),
  693. )
  694. return JSONResponse({"ticket": ticket}, headers={"Cache-Control": "no-store"})
  695. @router.get("/api/files/download")
  696. async def download_managed_file(request: Request, path: str):
  697. """Stream a managed file as an attachment download.
  698. ``auth_middleware`` also accepts the session token as ``?token=`` here so a
  699. shell/browser-opened download (no session header) still authenticates.
  700. Chromium marks ``<audio>``/``<video>`` subresource requests via
  701. ``Sec-Fetch-Dest``; those are served inline for Desktop builds that still
  702. use this route as their player source, attachment semantics otherwise.
  703. """
  704. fetch_destination = request.headers.get("sec-fetch-dest", "").lower()
  705. is_media_subresource = fetch_destination in {"audio", "video"}
  706. return await _managed_file_response(
  707. request,
  708. path,
  709. content_disposition_type="inline" if is_media_subresource else "attachment",
  710. media_only=is_media_subresource,
  711. )
  712. @router.get("/api/files/stream")
  713. @router.head("/api/files/stream")
  714. async def stream_managed_file(
  715. request: Request, path: str, profile: Optional[str] = None, session_id: Optional[str] = None,
  716. ):
  717. """Stream managed audio/video inline with HTTP Range support — Electron's
  718. media pipeline may reject an attachment response as an ``<audio>``/
  719. ``<video>`` source. Browser media elements authenticate with a reusable
  720. path-bound ``?ticket=``; the session token is never accepted in this URL.
  721. No size cap (Range-served); sensitive guard and MIME detection as download. A
  722. ``session_id`` resolves ``/workspace`` in that session's own sandbox, as the
  723. ticket route does. An SSH profile's clip streams from its SSH machine
  724. (``_remote_fs_backend``, the rule download uses), one Range at a time.
  725. Every request checks its ``session_id`` first, a ticketed one included."""
  726. session = await _fs_owned_session(session_id, profile)
  727. authority = getattr(request.state, "file_ticket_authority", None)
  728. if authority is not None and authority.workspace is not None:
  729. target, size = await _ticketed_remote_target(authority, _remote_stream_target)
  730. return remote_media_response(request, authority.workspace, target, size, _fs_mime_type(Path(target)))
  731. if authority is None:
  732. backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
  733. if backend is not None:
  734. target, size = await asyncio.to_thread(_remote_stream_target, backend, path)
  735. return remote_media_response(request, backend, target, size, _fs_mime_type(Path(target)))
  736. if session_id is not None or path.lower().startswith("file:"):
  737. path = str(await _fs_download_path(path, profile, session_id, session=session))
  738. return await _managed_file_response(request, path, content_disposition_type="inline", media_only=True)
  739. def _managed_write_target(path: str, request: Request, overwrite: bool):
  740. policy, target, display_path = _resolve_managed_path(path, request, for_write=True)
  741. if target.exists() and target.is_dir():
  742. raise HTTPException(status_code=409, detail="A directory already exists at that path")
  743. if target.exists() and not overwrite:
  744. raise HTTPException(status_code=409, detail="File already exists")
  745. return policy, target, display_path
  746. def _managed_write_result(policy, target: Path, display_path: str) -> dict:
  747. return {
  748. "ok": True,
  749. "entry": _managed_file_entry(policy, target),
  750. "path": display_path,
  751. **_managed_response_meta(policy),
  752. }
  753. @router.post("/api/files/upload")
  754. def upload_managed_file(payload: ManagedFileUpload, request: Request):
  755. policy, target, display_path = _managed_write_target(payload.path, request, payload.overwrite)
  756. data, _mime_type = _decode_data_url(payload.data_url)
  757. with _io_errors("File is not writable", "Could not write file"):
  758. target.parent.mkdir(parents=True, exist_ok=True)
  759. target.write_bytes(data)
  760. return _managed_write_result(policy, target, display_path)
  761. async def stream_upload_to_path(
  762. file: UploadFile,
  763. target: Path,
  764. *,
  765. too_large: str,
  766. not_writable: str,
  767. write_failed: str,
  768. ) -> int:
  769. """Stream a multipart upload to ``target`` in chunks; returns bytes written.
  770. Writes a sibling temp file first so a partial/aborted upload never clobbers
  771. an existing file, enforces ``_MANAGED_FILE_MAX_BYTES`` as it goes (413
  772. ``too_large``), then atomically renames into place. The temp file is
  773. removed on EVERY non-success exit — including asyncio.CancelledError when a
  774. browser aborts a large upload mid-stream.
  775. """
  776. from hermes_cli.web_server import _MANAGED_FILE_MAX_BYTES, _UPLOAD_CHUNK_BYTES
  777. tmp_fd, tmp_name = tempfile.mkstemp(prefix=f".{target.name}.", suffix=".upload", dir=str(target.parent))
  778. tmp_path = Path(tmp_name)
  779. total = 0
  780. renamed = False
  781. try:
  782. with os.fdopen(tmp_fd, "wb") as out:
  783. while True:
  784. chunk = await file.read(_UPLOAD_CHUNK_BYTES)
  785. if not chunk:
  786. break
  787. total += len(chunk)
  788. if total > _MANAGED_FILE_MAX_BYTES:
  789. raise HTTPException(status_code=413, detail=too_large)
  790. # Only the read stays on the event loop, so an abort still reaches the cleanup below.
  791. await asyncio.to_thread(out.write, chunk)
  792. await asyncio.to_thread(os.replace, tmp_path, target)
  793. renamed = True
  794. except PermissionError:
  795. raise HTTPException(status_code=403, detail=not_writable)
  796. except OSError as exc:
  797. raise HTTPException(status_code=500, detail=f"{write_failed}: {exc}")
  798. finally:
  799. if not renamed:
  800. tmp_path.unlink(missing_ok=True)
  801. await file.close()
  802. return total
  803. @router.post("/api/files/upload-stream")
  804. async def upload_managed_file_stream(
  805. request: Request,
  806. file: UploadFile = File(...),
  807. path: str = Form(...),
  808. overwrite: bool = Form(True),
  809. ):
  810. """Chunked multipart upload: constant memory and no base64 inflation, unlike
  811. the JSON data-URL endpoint that trips proxy body-size limits on large archives."""
  812. policy, target, display_path = _managed_write_target(path, request, overwrite)
  813. with _io_errors("File is not writable", "Could not create parent directory"):
  814. target.parent.mkdir(parents=True, exist_ok=True)
  815. await stream_upload_to_path(
  816. file, target,
  817. too_large="File is too large",
  818. not_writable="File is not writable",
  819. write_failed="Could not write file",
  820. )
  821. return _managed_write_result(policy, target, display_path)
  822. @router.post("/api/files/mkdir")
  823. def create_managed_directory(payload: ManagedDirectoryCreate, request: Request):
  824. policy, target, display_path = _resolve_managed_path(payload.path, request, for_write=True)
  825. if target.exists() and not target.is_dir():
  826. raise HTTPException(status_code=409, detail="A file already exists at that path")
  827. with _io_errors("Directory is not writable", "Could not create directory"):
  828. target.mkdir(parents=True, exist_ok=True)
  829. return _managed_write_result(policy, target, display_path)
  830. @router.delete("/api/files")
  831. def delete_managed_file(payload: ManagedFileDelete, request: Request):
  832. policy, target, display_path = _resolve_managed_path(payload.path, request)
  833. if policy.locked_root is not None and target == policy.locked_root:
  834. raise HTTPException(status_code=400, detail="Cannot delete the managed files root")
  835. if target.parent == target:
  836. raise HTTPException(status_code=400, detail="Cannot delete the filesystem root")
  837. if not target.exists():
  838. raise HTTPException(status_code=404, detail="Path not found")
  839. try:
  840. if target.is_dir():
  841. if payload.recursive:
  842. shutil.rmtree(target)
  843. else:
  844. target.rmdir()
  845. else:
  846. target.unlink()
  847. except OSError as exc:
  848. status_code = 409 if target.is_dir() and not payload.recursive else 500
  849. raise HTTPException(status_code=status_code, detail=f"Could not delete path: {exc}")
  850. return {"ok": True, "path": display_path, **_managed_response_meta(policy)}
  851. _FS_LIST_ERRNO = (
  852. (FileNotFoundError, "ENOENT"),
  853. (NotADirectoryError, "ENOTDIR"),
  854. (PermissionError, "EACCES"),
  855. )
  856. def _fs_list_entries(target: Path) -> list[dict[str, Any]]:
  857. entries = []
  858. with os.scandir(target) as scan:
  859. for entry in scan:
  860. if entry.name in _FS_READDIR_HIDDEN or _is_sensitive_path(Path(entry.path)):
  861. continue
  862. entries.append({
  863. "name": entry.name,
  864. "path": str(target / entry.name),
  865. "isDirectory": entry.is_dir(follow_symlinks=False),
  866. })
  867. entries.sort(key=lambda item: (not item["isDirectory"], item["name"].lower(), item["name"]))
  868. return entries
  869. @router.get("/api/fs/list")
  870. async def fs_list(path: str, request: Request, profile: Optional[str] = None):
  871. backend = await asyncio.to_thread(_fs_backend, profile)
  872. if backend is not None:
  873. try:
  874. return await asyncio.to_thread(backend.list_dir, path, _FS_READDIR_HIDDEN)
  875. except Exception as exc:
  876. _raise_fs_backend_error(exc)
  877. target = _agent_fs_path(path, profile_home=_fs_profile_home(profile))
  878. _hosted_fs_read_guard(target, request)
  879. try:
  880. # The scan stats every entry (a network share answers in seconds): off the event loop.
  881. return {"entries": await asyncio.to_thread(_fs_list_entries, target)}
  882. except OSError as exc:
  883. for exc_type, code in _FS_LIST_ERRNO:
  884. if isinstance(exc, exc_type):
  885. return {"entries": [], "error": code}
  886. return {"entries": [], "error": getattr(exc, "strerror", None) or "read-error"}
  887. @router.get("/api/fs/read-text")
  888. async def fs_read_text(
  889. path: str, request: Request = None, profile: Optional[str] = None, session_id: Optional[str] = None,
  890. ):
  891. session = await _fs_owned_session(session_id, profile)
  892. # A staged paste or pick previews from this host, as read-data-url reads it back to send.
  893. backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
  894. if backend is not None:
  895. try:
  896. data, size, target = await asyncio.to_thread(
  897. backend.read_bytes,
  898. path,
  899. max_bytes=_FS_TEXT_SOURCE_MAX_BYTES,
  900. read_limit=_FS_TEXT_PREVIEW_MAX_BYTES,
  901. )
  902. except Exception as exc:
  903. _raise_fs_backend_error(exc)
  904. target_path = Path(target)
  905. return {
  906. "binary": _fs_looks_binary(data[:4096]),
  907. "byteSize": size,
  908. "language": _FS_PREVIEW_LANGUAGE_BY_EXT.get(target_path.suffix.lower(), "text"),
  909. "mimeType": _fs_mime_type(target_path),
  910. "path": target,
  911. "text": data.decode("utf-8", errors="replace"),
  912. "truncated": size > _FS_TEXT_PREVIEW_MAX_BYTES,
  913. }
  914. profile_home = _fs_profile_home(profile)
  915. # A session's /workspace is its own sandbox, resolved as download resolves it.
  916. target = await _fs_download_path(path, profile, session_id, session=session)
  917. # The same staged-file exception read-data-url makes under a locked files root.
  918. if not await asyncio.to_thread(_is_host_file, str(target), profile):
  919. _hosted_fs_read_guard(target, request)
  920. target, st = _fs_regular_file(target, profile_home)
  921. if st.st_size > _FS_TEXT_SOURCE_MAX_BYTES:
  922. raise HTTPException(status_code=413, detail="File too large")
  923. data = await asyncio.to_thread(
  924. _fs_read_bytes, target, min(st.st_size, _FS_TEXT_PREVIEW_MAX_BYTES),
  925. )
  926. return {
  927. "binary": _fs_looks_binary(data[:4096]),
  928. "byteSize": st.st_size,
  929. "language": _FS_PREVIEW_LANGUAGE_BY_EXT.get(target.suffix.lower(), "text"),
  930. "mimeType": _fs_mime_type(target),
  931. "path": str(target),
  932. "text": data.decode("utf-8", errors="replace"),
  933. "truncated": st.st_size > _FS_TEXT_PREVIEW_MAX_BYTES,
  934. }
  935. @router.post("/api/fs/write-text")
  936. async def fs_write_text(payload: FsWriteText, profile: Optional[str] = None):
  937. """Overwrite (or create) a UTF-8 text file for the in-app spot editor.
  938. Mirrors the Electron ``hermes:fs:writeText`` hardening: path validated by
  939. ``_fs_path``, the parent must already exist (never build trees), only
  940. regular files may be replaced, payload size-capped, staged to a sibling
  941. temp file and ``os.replace``-d so a crash can't truncate the original.
  942. Stale-on-disk detection is the client's job (re-read before save). The
  943. target resolves as ``read-text`` resolves it, ``session_id`` included, so a
  944. file saves to the same place it was read from.
  945. """
  946. text = payload.content or ""
  947. session = await _fs_owned_session(payload.session_id, profile)
  948. # Save where read-text read: a staged paste or pick on this host, all else on the SSH machine.
  949. backend = await asyncio.to_thread(_remote_fs_backend, payload.path, profile)
  950. if backend is not None:
  951. try:
  952. target, byte_size = await asyncio.to_thread(
  953. backend.write_text,
  954. payload.path,
  955. text,
  956. max_bytes=_FS_TEXT_WRITE_MAX_BYTES,
  957. )
  958. except Exception as exc:
  959. _raise_fs_backend_error(exc)
  960. return {"ok": True, "path": target, "byteSize": byte_size}
  961. target = await _fs_download_path(
  962. payload.path, profile, payload.session_id, session=session, decode_fallback=False, own_sandbox_only=True,
  963. )
  964. if len(text.encode("utf-8")) > _FS_TEXT_WRITE_MAX_BYTES:
  965. raise HTTPException(status_code=413, detail="Content too large")
  966. try:
  967. st: Optional[os.stat_result] = target.stat()
  968. except FileNotFoundError:
  969. st = None
  970. except PermissionError:
  971. raise HTTPException(status_code=403, detail="File is not writable")
  972. except OSError as exc:
  973. raise HTTPException(status_code=400, detail=str(exc) or "Invalid path")
  974. if st is not None and stat.S_ISDIR(st.st_mode):
  975. raise HTTPException(status_code=400, detail="Path points to a directory")
  976. if st is not None and not stat.S_ISREG(st.st_mode):
  977. raise HTTPException(status_code=400, detail="Only regular files can be written")
  978. if not target.parent.is_dir():
  979. raise HTTPException(status_code=400, detail="Parent directory does not exist")
  980. tmp = target.with_name(f".{target.name}.hermes-tmp-{os.getpid()}")
  981. try:
  982. tmp.write_text(text, encoding="utf-8")
  983. os.replace(tmp, target)
  984. except PermissionError:
  985. tmp.unlink(missing_ok=True)
  986. raise HTTPException(status_code=403, detail="File is not writable")
  987. except OSError as exc:
  988. tmp.unlink(missing_ok=True)
  989. raise HTTPException(status_code=500, detail=f"Could not write file: {exc}")
  990. return {"ok": True, "path": str(target), "byteSize": len(text.encode("utf-8"))}
  991. async def _fs_download_path(
  992. path: str, profile: Optional[str], session_id: Optional[str], *, session: Optional[dict] = None,
  993. decode_fallback: bool = True, own_sandbox_only: bool = False,
  994. ) -> Path:
  995. # Resolve container paths in the requested profile's sandbox, not the active one's.
  996. # A write passes decode_fallback=False: it must never land on a decoded twin of its name.
  997. # A session's write also passes own_sandbox_only: reads fall back to the shared sandbox
  998. # when the session's own copy is gone, a Save must not (409 instead).
  999. # *session* is the row the route's _fs_owned_session already returned for *session_id*;
  1000. # a caller that passes none gets the same lookup here.
  1001. profile_home = _fs_profile_home(profile)
  1002. if session_id is not None:
  1003. if session is None:
  1004. session = await _fs_owned_session(session_id, profile)
  1005. # Validate ownership even for absolute paths; never trust a client cwd.
  1006. cwd = (session or {}).get("cwd") or ""
  1007. # The profile's scope qualifies the key its turns registered the session's workspace under.
  1008. with _agent_path_scope(profile_home):
  1009. workspace_key, workspace_cwd = _session_workspace(session_id, cwd)
  1010. return _agent_fs_path(
  1011. path, cwd=cwd, profile_home=profile_home, workspace_key=workspace_key,
  1012. workspace_cwd=workspace_cwd, decode_fallback=decode_fallback, own_sandbox_only=own_sandbox_only,
  1013. )
  1014. return _agent_fs_path(path, profile_home=profile_home, decode_fallback=decode_fallback)
  1015. async def _fs_owned_session(session_id: Optional[str], profile: Optional[str]) -> Optional[dict]:
  1016. """The session *session_id* names, looked up in *profile*'s own sessions, or None when the
  1017. request names none. A blank id, or one that profile does not own, is 404. A route that takes a
  1018. ``session_id`` calls this before it picks a backend, so an SSH profile refuses the same
  1019. sessions a host or Docker one does."""
  1020. if session_id is None:
  1021. return None
  1022. from hermes_cli.web_routers.sessions import get_session_detail
  1023. if not session_id.strip():
  1024. raise HTTPException(status_code=404, detail="Session not found")
  1025. return await get_session_detail(session_id, profile)
  1026. def _fs_profile_home(profile: Optional[str]) -> Optional[Path]:
  1027. """HERMES_HOME of a requested profile (404/400 on an unknown one), None for the request's
  1028. own profile (omitted, ``""`` or ``current``, as ``_is_current_profile`` reads them)."""
  1029. from hermes_cli.web_server_cron import _cron_profile_home
  1030. from hermes_cli.web_server_profiles import _is_current_profile
  1031. if _is_current_profile(profile):
  1032. return None
  1033. return _cron_profile_home(profile)[1]
  1034. @router.get("/api/fs/read-data-url")
  1035. async def fs_read_data_url(
  1036. path: str, request: Request, profile: Optional[str] = None, session_id: Optional[str] = None,
  1037. ):
  1038. from hermes_cli.web_server import _FS_DATA_URL_MAX_BYTES
  1039. session = await _fs_owned_session(session_id, profile)
  1040. backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
  1041. if backend is not None:
  1042. try:
  1043. data, _size, target = await asyncio.to_thread(
  1044. backend.read_bytes, path, max_bytes=_FS_DATA_URL_MAX_BYTES
  1045. )
  1046. except Exception as exc:
  1047. _raise_fs_backend_error(exc)
  1048. encoded = base64.b64encode(data).decode("ascii")
  1049. return {"dataUrl": f"data:{_fs_mime_type(Path(target))};base64,{encoded}"}
  1050. target = await _fs_download_path(path, profile, session_id, session=session)
  1051. # A browser paste or pick reads back to be sent wherever a locked files root sits: the server
  1052. # wrote it into the profile's own image cache or staged uploads, outside the managed tree.
  1053. if not await asyncio.to_thread(_is_host_file, str(target), profile):
  1054. _hosted_fs_read_guard(target, request)
  1055. target, st = _fs_regular_file(target, _fs_profile_home(profile))
  1056. if st.st_size > _FS_DATA_URL_MAX_BYTES:
  1057. raise HTTPException(status_code=413, detail="File too large")
  1058. # A transcript image is read again on every remount. The browser keeps the body in its own
  1059. # HTTP cache and revalidates each time, so an unchanged file costs a 304 instead of its bytes
  1060. # over a slow link, and a rewritten one is fetched fresh.
  1061. validators = {"Cache-Control": "private, no-cache", "ETag": _fs_etag(target, st)}
  1062. if {validators["ETag"], "*"} & _if_none_match(request):
  1063. return Response(status_code=304, headers=validators)
  1064. def _render() -> JSONResponse:
  1065. encoded = base64.b64encode(_fs_read_bytes(target)).decode("ascii")
  1066. return JSONResponse({"dataUrl": f"data:{_fs_mime_type(target)};base64,{encoded}"}, headers=validators)
  1067. # Read, encode and render off the event loop: up to 16 MB inline stalls every other request (and /api/ws).
  1068. return await asyncio.to_thread(_render)
  1069. def _fs_etag(target: Path, st: os.stat_result) -> str:
  1070. """A validator that changes whenever the file at *target* does."""
  1071. identity = f"{target}\0{st.st_dev}\0{st.st_ino}\0{st.st_size}\0{st.st_mtime_ns}"
  1072. return '"' + hashlib.sha256(identity.encode("utf-8", "surrogateescape")).hexdigest()[:32] + '"'
  1073. def _if_none_match(request: Request) -> set[str]:
  1074. return {tag.strip().removeprefix("W/") for tag in request.headers.get("if-none-match", "").split(",")}
  1075. def _remote_download_target(backend, path: str) -> tuple[str, int]:
  1076. """*path* resolved on the SSH workspace to a regular file a download may read, and its size."""
  1077. from hermes_cli.ssh_workspace_fs import SshWorkspaceFsError
  1078. try:
  1079. target, size = backend.inspect_file(path)
  1080. except SshWorkspaceFsError as exc:
  1081. _raise_fs_backend_error(exc)
  1082. if _is_sensitive_path(Path(target)):
  1083. raise HTTPException(status_code=403, detail="Access to sensitive files is not allowed")
  1084. return target, size
  1085. def _remote_stream_target(backend, path: str) -> tuple[str, int]:
  1086. """*path* on the SSH workspace as media the stream route may serve, and its size: download's
  1087. checks, then the host stream's media-type check. No size cap: served one Range at a time."""
  1088. target, size = _remote_download_target(backend, path)
  1089. if PurePosixPath(target).suffix.lower() not in _STREAMABLE_MEDIA_EXTENSIONS:
  1090. raise HTTPException(status_code=415, detail="Unsupported media type")
  1091. return target, size
  1092. async def _remote_file_authority(
  1093. path: str, profile: Optional[str], owner: Path, inspect,
  1094. ) -> Optional[file_tickets.FileAuthority]:
  1095. """A ticket's authority for *path* on the profile's SSH workspace, checked by *inspect*
  1096. (download's or the stream's rules), or None when this host owns the path."""
  1097. backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
  1098. if backend is None:
  1099. return None
  1100. target, _size = await asyncio.to_thread(inspect, backend, path)
  1101. authority = file_tickets.FileAuthority(PurePosixPath(target), (owner,), workspace=backend)
  1102. await asyncio.to_thread(authority.check_live)
  1103. return authority
  1104. async def _ticketed_remote_target(authority: file_tickets.FileAuthority, inspect) -> tuple[str, int]:
  1105. """The SSH file a ticket captured, re-checked by *inspect* while its profile is still live."""
  1106. try:
  1107. await asyncio.to_thread(authority.check_live)
  1108. except FileNotFoundError as exc:
  1109. raise HTTPException(status_code=404, detail="File ticket profile or resource is unavailable") from exc
  1110. target, size = await asyncio.to_thread(inspect, authority.workspace, str(authority.target))
  1111. if target != str(authority.target):
  1112. raise HTTPException(status_code=403, detail="File ticket target changed")
  1113. return target, size
  1114. def _remote_download_response(request: Optional[Request], backend, target: str, size: int) -> Response:
  1115. """*target* streamed from the SSH workspace as an attachment; a HEAD reads none of it."""
  1116. target_path = Path(target)
  1117. filename = urllib.parse.quote(target_path.name)
  1118. headers = {"Content-Disposition": f"attachment; filename*=UTF-8''{filename}"}
  1119. media_type = _fs_mime_type(target_path)
  1120. if request is not None and request.method == "HEAD":
  1121. return Response(media_type=media_type, headers={**headers, "Content-Length": str(size)})
  1122. return StreamingResponse(backend.stream_file(target), media_type=media_type, headers=headers)
  1123. async def _fs_download_authority(
  1124. request: Request, path: str, profile: Optional[str], session_id: Optional[str], owner: Path,
  1125. session: Optional[dict] = None,
  1126. ) -> file_tickets.FileAuthority:
  1127. """The file ``/api/fs/download`` serves for this query, captured for a download ticket: on the
  1128. profile's SSH workspace when it has one, else on this host under the same read rules."""
  1129. from hermes_constants import named_profile_home
  1130. remote = await _remote_file_authority(path, profile, owner, _remote_download_target)
  1131. if remote is not None:
  1132. return remote
  1133. local = await _fs_download_path(path, profile, session_id, session=session)
  1134. def capture():
  1135. _hosted_fs_read_guard(local, request)
  1136. target, _st = _fs_regular_file(local, _fs_profile_home(profile))
  1137. homes = [owner]
  1138. target_home = named_profile_home(target)
  1139. if target_home is not None and target_home not in homes:
  1140. homes.append(target_home)
  1141. authority = file_tickets.FileAuthority(target, tuple(homes))
  1142. authority.check_live()
  1143. return authority
  1144. return await asyncio.to_thread(capture)
  1145. async def _ticketed_fs_download(
  1146. request: Request, authority: file_tickets.FileAuthority, profile: Optional[str],
  1147. ) -> Response:
  1148. """Serve the file a download ticket captured while its profile homes are still live."""
  1149. if authority.workspace is not None:
  1150. target, size = await _ticketed_remote_target(authority, _remote_download_target)
  1151. return _remote_download_response(request, authority.workspace, target, size)
  1152. from hermes_cli.web_server_file_response import OpenedFileResponse
  1153. def checked():
  1154. _hosted_fs_read_guard(authority.target, request)
  1155. target, _st = _fs_regular_file(authority.target, _fs_profile_home(profile))
  1156. return target, None
  1157. return OpenedFileResponse(
  1158. path=str(authority.target),
  1159. opener=lambda: _pin_ticket_file(authority, checked),
  1160. media_type=_fs_mime_type(authority.target),
  1161. filename=authority.target.name,
  1162. content_disposition_type="attachment",
  1163. )
  1164. @router.get("/api/fs/download")
  1165. @router.head("/api/fs/download")
  1166. async def fs_download(
  1167. path: str, request: Request = None, profile: Optional[str] = None, session_id: Optional[str] = None,
  1168. ):
  1169. """A workspace file as an attachment: from the profile's SSH workspace when it has one, else
  1170. from this host. A browser download link authenticates with a path-bound ``?ticket=``."""
  1171. session = await _fs_owned_session(session_id, profile)
  1172. authority = getattr(getattr(request, "state", None), "file_ticket_authority", None)
  1173. if authority is not None:
  1174. return await _ticketed_fs_download(request, authority, profile)
  1175. backend = await asyncio.to_thread(_remote_fs_backend, path, profile)
  1176. if backend is not None:
  1177. target, size = await asyncio.to_thread(_remote_download_target, backend, path)
  1178. return _remote_download_response(request, backend, target, size)
  1179. target = await _fs_download_path(path, profile, session_id, session=session)
  1180. _hosted_fs_read_guard(target, request)
  1181. target, _st = _fs_regular_file(target, _fs_profile_home(profile))
  1182. await asyncio.to_thread(_refuse_live_database, target)
  1183. return FileResponse(
  1184. path=str(target),
  1185. media_type=_fs_mime_type(target),
  1186. filename=target.name,
  1187. content_disposition_type="attachment",
  1188. )
  1189. @router.get("/api/fs/git-root")
  1190. async def fs_git_root(path: str, profile: Optional[str] = None):
  1191. backend = await asyncio.to_thread(_fs_backend, profile)
  1192. if backend is not None:
  1193. try:
  1194. return {"root": await asyncio.to_thread(backend.git_root, path)}
  1195. except Exception as exc:
  1196. _raise_fs_backend_error(exc)
  1197. target = _fs_path(path)
  1198. try:
  1199. st = target.stat()
  1200. start = target if stat.S_ISDIR(st.st_mode) else target.parent
  1201. except OSError:
  1202. start = target
  1203. return {"root": _fs_find_git_root(start)}
  1204. @router.get("/api/fs/default-cwd")
  1205. async def fs_default_cwd(profile: Optional[str] = None):
  1206. backend = await asyncio.to_thread(_fs_backend, profile)
  1207. if backend is not None:
  1208. cwd = backend.cwd
  1209. try:
  1210. branch = await asyncio.to_thread(backend.git_branch, cwd)
  1211. except Exception as exc:
  1212. _raise_fs_backend_error(exc)
  1213. return {"cwd": cwd, "branch": branch}
  1214. cwd = await asyncio.to_thread(_fs_default_cwd, profile)
  1215. return {"cwd": cwd, "branch": await asyncio.to_thread(_fs_git_branch, cwd)} # a git subprocess