The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Browser uploads staged in a profile home, and the receipt ``file.attach`` redeems.
``POST /api/chat/file-upload`` publishes a picked file at ``<profile home>/uploads/web-<hex>-<name>``
and returns a ``staged_upload`` descriptor: that path, the profile home and this installation's id.
The gateway's ``file.attach`` trusts the descriptor only after resolving it back to exactly that
layout, so the writer and the reader of the layout live here together. The file routes read a staged
file back from this host by the same layout when the profile's workspace is an SSH machine.
A named profile that is missing or deleted is refused on both sides by the rule every named-home
write follows (``hermes_constants.assert_named_profile_home_live`` / ``mkdir_under_hermes_home``):
an upload never recreates a deleted home, and a receipt from one is never redeemed.
"""
from __future__ import annotations
from contextlib import contextmanager, suppress
import os
from pathlib import Path
import re
import secrets
import stat
import time
from fastapi import HTTPException
from hermes_constants import WEBAPP_ATTACHMENT_MAX_BYTES
from hermes_cli.install_identity import get_install_id
from hermes_cli.web_deps import late
_is_current_profile = late("_is_current_profile", "hermes_cli.web_server_profiles")
_resolve_profile_dir = late("_resolve_profile_dir", "hermes_cli.web_server_profiles")
_UPLOADS_DIR = "uploads"
_STAGED_PREFIX = "web-"
_CHUNK_BYTES = 1024 * 1024
_UPLOAD_RETENTION_SECONDS = 7 * 24 * 60 * 60
_SAFE_FILENAME = re.compile(r"[^A-Za-z0-9._-]+")
def _safe_filename(value: str | None) -> str:
name = Path(str(value or "attachment"))
# Sanitizing the whole name would turn an all-non-ASCII stem into a
# leading dot, then strip the extension separator needed by read_file.
stem = _SAFE_FILENAME.sub("-", name.stem).strip(".-") or "attachment"
suffix = _SAFE_FILENAME.sub("-", name.suffix).rstrip(".-")[:119]
return stem[:120 - len(suffix)] + suffix
def _prune_stale_uploads(root: Path, *, now: float | None = None) -> None:
"""Bound abandoned browser-picker staging without following symlinks."""
cutoff = (time.time() if now is None else now) - _UPLOAD_RETENTION_SECONDS
try:
entries = list(root.iterdir())
except OSError:
return
for entry in entries:
if not entry.name.startswith(_STAGED_PREFIX):
continue
try:
metadata = entry.stat(follow_symlinks=False)
if stat.S_ISREG(metadata.st_mode) and metadata.st_mtime < cutoff:
entry.unlink()
except OSError:
continue
@contextmanager
def removed_on_failure(target: Path):
"""Unlink a partially published file; a cleanup error never masks the cause."""
try:
yield
except BaseException:
with suppress(OSError):
target.unlink(missing_ok=True)
raise
def resolve_upload_home(profile: str | None) -> Path:
"""Resolve the profile home an upload is published into, with ``_profile_scope``'s 400/404s.
Without entering that scope: nothing here reads config or secrets, so an upload must not queue
on its process-wide skills lock or wait on its secret-source hydration. A named home that is
missing or deleted is a 404.
"""
from hermes_constants import assert_named_profile_home_live, get_hermes_home
if _is_current_profile(profile):
home = get_hermes_home()
else:
home = _resolve_profile_dir(profile.strip())
try:
assert_named_profile_home_live(home)
except FileNotFoundError as exc:
raise HTTPException(status_code=404, detail="Profile home is unavailable") from exc
return home
def ensure_profile_subdir(
home: Path,
name: str,
*,
denied: str,
failed: str,
mode: int | None = None,
) -> Path:
"""``<home>/<name>``, created without ever recreating a missing or deleted named home.
That case is a 404 (``mkdir_under_hermes_home``). Other directory errors are 403 *denied* and
500 ``"<failed>: <exc>"``; *mode* is applied inside that mapping.
"""
from hermes_constants import mkdir_under_hermes_home
directory = home / name
try:
mkdir_under_hermes_home(directory)
if mode is not None:
directory.chmod(mode)
except FileNotFoundError as exc:
raise HTTPException(status_code=404, detail="Profile was deleted during upload") from exc
except PermissionError as exc:
raise HTTPException(status_code=403, detail=denied) from exc
except OSError as exc:
raise HTTPException(status_code=500, detail=f"{failed}: {exc}") from exc
return directory
def publish_staged_upload(staged, profile_home: Path, filename: str) -> Path:
"""Publish staged bytes as a new owner-only file under ``<profile_home>/uploads``."""
from hermes_constants import assert_named_profile_home_live
upload_root = ensure_profile_subdir(
profile_home,
_UPLOADS_DIR,
denied="Upload directory is not writable",
failed="Could not create upload directory",
mode=0o700,
)
_prune_stale_uploads(upload_root)
target = upload_root / f"{_STAGED_PREFIX}{secrets.token_hex(8)}-{_safe_filename(filename)}"
try:
with removed_on_failure(target):
fd = os.open(
target,
os.O_WRONLY | os.O_CREAT | os.O_EXCL,
0o600,
)
with os.fdopen(fd, "wb") as handle:
staged.seek(0)
while chunk := staged.read(_CHUNK_BYTES):
handle.write(chunk)
handle.flush()
os.fsync(handle.fileno())
# A deletion recorded while the bytes were written wins: never report a path in it.
assert_named_profile_home_live(profile_home)
return target
except FileNotFoundError as exc:
raise HTTPException(status_code=404, detail="Profile was deleted during upload") from exc
except OSError as exc:
raise HTTPException(status_code=500, detail=f"Could not stage file: {exc}") from exc
def staged_upload_descriptor(path: Path, profile_home: Path) -> dict | None:
"""The ``staged_upload`` receipt for a published file, or None without an install identity."""
install_id = get_install_id()
if not install_id:
# Identity is already persisted by Hermes. If it is unavailable, keep
# the legacy path/byte-upload flow rather than invent an ephemeral id.
return None
return {
"install_id": install_id,
"path": str(path),
"profile_home": str(profile_home),
}
def parse_staged_upload(descriptor: object) -> tuple[str, str]:
"""``(profile_home, path)`` of a descriptor this installation issued.
Checked before the source is touched. A replacement backend at the same URL has a different
install id, and the source bytes alone never authorize reuse.
"""
if not isinstance(descriptor, dict):
raise ValueError("invalid staged upload")
install_id = get_install_id()
if not install_id or descriptor.get("install_id") != install_id:
raise ValueError("Staged attachment belongs to another Hermes backend; select the file again")
raw_home = descriptor.get("profile_home")
raw_path = descriptor.get("path")
if not isinstance(raw_home, str) or not raw_home or not isinstance(raw_path, str) or not raw_path:
raise ValueError("invalid staged upload source")
return raw_home, raw_path
def resolve_staged_upload(home: Path, raw_path: str) -> Path:
"""The staged regular file *raw_path* names under *home*, within the browser size cap.
The check is anchored on *home*, never on where the descriptor's path claims to point. A named
*home* that is missing or deleted raises ``FileNotFoundError``: its receipts are void.
"""
from hermes_constants import assert_named_profile_home_live
assert_named_profile_home_live(home)
source = Path(raw_path)
if source.is_symlink():
raise ValueError("staged upload is no longer a regular file")
source = source.resolve(strict=True)
if (
source.parent != (home / _UPLOADS_DIR).resolve(strict=True)
or not source.name.startswith(_STAGED_PREFIX)
or not source.is_file()
):
raise ValueError("staged upload is outside its source profile")
if source.stat().st_size > WEBAPP_ATTACHMENT_MAX_BYTES:
raise ValueError("staged upload exceeds the browser attachment size limit")
return source
def is_staged_upload(home: Path, target: Path) -> bool:
"""Whether the resolved *target* is a file the upload route staged for *home*: a regular file
directly in its uploads folder, named with the staged prefix."""
try:
uploads = (home / _UPLOADS_DIR).resolve(strict=True)
except (OSError, RuntimeError):
return False
return target.parent == uploads and target.name.startswith(_STAGED_PREFIX) and target.is_file()