@bitseek/hermes-webui 0.1.0-beta.0 → 0.1.0

package/vendor/agent-frontend-shell/api/workspace.py

@@ -671,75 +671,233 @@ def validate_workspace_to_add(path: str) -> Path:
 def safe_resolve_ws(root: Path, requested: str) -> Path:
     """Resolve a relative path inside a workspace root, raising ValueError on traversal.
 
-    Symlinks whose *unresolved* path is within the workspace root are allowed —
-    the user placed them there intentionally.  Only raw ``..`` traversal outside
-    the root is blocked.
+    Both raw ``..`` traversal and symlink escapes are blocked.  Workspace file
+    APIs can be reached by browser UI actions and agent/tool calls, so a symlink
+    inside the workspace must not expand the trusted workspace boundary to an
+    arbitrary host path.
     """
-    import os
-    unresolved = root / requested
-    resolved = unresolved.resolve()
-    # Fast path: resolved path is inside root (covers most cases)
+    root_resolved = root.resolve()
+    resolved = (root / requested).resolve()
     try:
-        resolved.relative_to(root.resolve())
-        return resolved
-    except ValueError:
-        pass
-    # Symlink path: normalize '..' (without following symlinks) and check
-    # os.path.normpath collapses '..' but does NOT follow symlinks.
-    norm = Path(os.path.normpath(str(unresolved)))
-    try:
-        norm.relative_to(root)
+        resolved.relative_to(root_resolved)
     except ValueError:
         raise ValueError(f"Path traversal blocked: {requested}")
-    # Symlink points outside workspace root — additionally block system directories.
-    # Even if the user placed the symlink intentionally, prevent reads from
-    # /etc, /proc, /sys, /dev and other blocked roots (LLM agents can call
-    # read_file_content via tool calls, not just human users).
-    if _is_blocked_system_path(resolved):
-        raise ValueError(f"Path traversal blocked (system dir): {requested}")
     return resolved
 
 
+# ── Race-safe (TOCTOU) anchored open ─────────────────────────────────────────
+# safe_resolve_ws() validates a path, but if callers then re-open by pathname a
+# symlink swapped in AFTER the check could still escape the workspace. To close
+# that window we open the (already symlink-resolved) target component-by-component
+# from the workspace root using openat (dir_fd) + O_NOFOLLOW: every component must
+# be a real, non-symlink entry, so a component swapped to a symlink mid-flight is
+# refused. Legit in-workspace symlinks still work because safe_resolve_ws() has
+# already collapsed them to their real in-workspace target, and we walk that real
+# (symlink-free) path. Portable: uses os.supports_dir_fd where available (Linux,
+# macOS); on platforms without dir_fd support (Windows — where creating symlinks
+# also requires admin) we fall back to a plain pathname open, matching the prior
+# behaviour with no regression.
+
+_DIR_FD_OK = os.open in getattr(os, "supports_dir_fd", set())
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+
+
+def open_anchored_fd(workspace: Path, target: Path, *, want_dir: bool) -> int:
+    """Open ``target`` race-safely and return an owned file descriptor.
+
+    ``target`` must be the symlink-resolved path returned by safe_resolve_ws()
+    (i.e. already verified to live under the workspace). Raises FileNotFoundError
+    if a component is missing / wrong-type, or ValueError if a component was
+    swapped to a symlink (escape attempt). Caller owns and must close the fd.
+    """
+    root_resolved = workspace.resolve()
+    # Relative, symlink-free component list (resolve() already collapsed any links).
+    try:
+        rel_parts = target.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {target}") from None
+
+    if not _DIR_FD_OK:
+        # Windows / no openat: fall back to a plain pathname open. No new race
+        # protection, but no regression vs the prior path-based behaviour, and
+        # symlink creation needs admin on Windows anyway.
+        flags = os.O_RDONLY | (_O_DIRECTORY if want_dir else 0) | _O_NOFOLLOW
+        try:
+            return os.open(str(target), flags)
+        except OSError:
+            raise FileNotFoundError(f"Not found: {target}") from None
+
+    # Open the (trusted) workspace root. root_resolved is canonical (resolve()
+    # collapsed any symlinks to REACH it, e.g. macOS /tmp -> /private/tmp), so its
+    # final component is legitimately a real directory — O_NOFOLLOW here only fires
+    # if the root itself was raced into a symlink after resolve() (escape attempt).
+    fd = os.open(str(root_resolved), os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW)
+    try:
+        for i, part in enumerate(rel_parts):
+            is_last = i == len(rel_parts) - 1
+            want_directory = (not is_last) or want_dir
+            flags = os.O_RDONLY | _O_NOFOLLOW | (_O_DIRECTORY if want_directory else 0)
+            try:
+                nfd = os.open(part, flags, dir_fd=fd)
+            except OSError:
+                # ELOOP (component is a symlink — swapped in) or missing/wrong type.
+                raise FileNotFoundError(f"Not found: {target}") from None
+            os.close(fd)
+            fd = nfd
+        return fd
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        raise
+
+
+def open_anchored_create_fd(root: Path, dest: Path) -> int:
+    """Create ``dest`` for exclusive writing race-safely, anchored under ``root``.
+
+    Walks from ``root`` via openat + O_NOFOLLOW (creating missing intermediate
+    directories with mkdir(dir_fd=...)), then creates the leaf with
+    O_CREAT|O_EXCL|O_NOFOLLOW so a symlink raced into any component cannot
+    redirect the write outside ``root``. ``dest`` must be the resolved path and
+    must not already exist (callers dedup first). Raises ValueError if ``dest``
+    is not under ``root``, FileExistsError if it exists, FileNotFoundError if a
+    component was swapped to a symlink. Caller owns and must close the returned
+    write fd. On platforms without dir_fd support (Windows) falls back to a plain
+    exclusive create — no new race protection but no regression.
+    """
+    root_resolved = root.resolve()
+    try:
+        rel_parts = dest.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {dest}") from None
+    if not rel_parts:
+        raise ValueError(f"Invalid destination: {dest}")
+
+    if not _DIR_FD_OK:
+        # Windows / no openat: create parent dirs then exclusively create the leaf.
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        return os.open(str(dest), os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW, 0o644)
+
+    fd = os.open(str(root_resolved), os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW)
+    try:
+        for part in rel_parts[:-1]:
+            try:
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except FileNotFoundError:
+                os.mkdir(part, 0o755, dir_fd=fd)
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except OSError:
+                # ELOOP — component swapped to a symlink (escape attempt).
+                raise FileNotFoundError(f"Not found: {dest}") from None
+            os.close(fd)
+            fd = nfd
+        return os.open(
+            rel_parts[-1],
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW,
+            0o644,
+            dir_fd=fd,
+        )
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
+def make_anchored_dir(root: Path, dest: Path) -> None:
+    """Create directory ``dest`` (and any missing parents) race-safely under ``root``.
+
+    Walks from ``root`` via openat + O_NOFOLLOW, creating each missing component
+    with mkdir(dir_fd=...), so a symlink raced into any component cannot make the
+    server create directories outside ``root``. Idempotent (existing dirs are
+    fine). Raises ValueError if ``dest`` is not under ``root``, FileNotFoundError
+    if a component was swapped to a symlink. On platforms without dir_fd support
+    (Windows) falls back to a plain Path.mkdir — no regression.
+    """
+    root_resolved = root.resolve()
+    dest_resolved = dest.resolve()
+    if dest_resolved == root_resolved:
+        return
+    try:
+        rel_parts = dest_resolved.relative_to(root_resolved).parts
+    except ValueError:
+        raise ValueError(f"Path traversal blocked: {dest}") from None
+
+    if not _DIR_FD_OK:
+        dest.mkdir(parents=True, exist_ok=True)
+        return
+
+    fd = os.open(str(root_resolved), os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW)
+    try:
+        for part in rel_parts:
+            try:
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except FileNotFoundError:
+                os.mkdir(part, 0o755, dir_fd=fd)
+                nfd = os.open(part, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW, dir_fd=fd)
+            except OSError:
+                # ELOOP — component swapped to a symlink (escape attempt).
+                raise FileNotFoundError(f"Not found: {dest}") from None
+            os.close(fd)
+            fd = nfd
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
 def list_dir(workspace: Path, rel: str='.'):
     target = safe_resolve_ws(workspace, rel)
     if not target.is_dir():
         raise FileNotFoundError(f"Not a directory: {rel}")
     ws_resolved = workspace.resolve()
+    target_resolved = target.resolve()
     entries = []
-    for item in sorted(target.iterdir(), key=lambda p: (not p.is_symlink(), p.is_file(), p.name.lower())):
-        if item.is_symlink():
-            # Resolve the symlink target and check if it stays within workspace
+
+    def _process(name, is_symlink, raw_link, lstat_result, reachable):
+        """Append one directory entry. ``raw_link`` is the os.readlink() result
+        for symlinks (else None); ``lstat_result`` is an os.stat_result obtained
+        with follow_symlinks=False (else None); ``reachable`` is False when a
+        follow_symlinks=True stat raised (broken target or symlink loop)."""
+        if is_symlink:
+            if raw_link is None:
+                return
+            # A symlink whose follow-stat raised (ELOOP / broken target) can never
+            # be opened — filter it. This catches mutual/self loops portably across
+            # Python versions where Path.resolve() loop handling differs (3.11
+            # raises RuntimeError, 3.13 can return a path), so do not rely on
+            # resolve() raising for cycle detection.
+            if not reachable:
+                return
             try:
-                link_target = item.resolve()
-            except OSError:
-                continue
-            # Cycle detection: skip if symlink points back to current dir,
-            # workspace root, or any ancestor of current dir.
-            # This must run REGARDLESS of whether target is inside workspace.
-            if (link_target == target.resolve() or link_target == target
-                    or link_target == ws_resolved):
-                continue
+                link_target = (target_resolved / raw_link).resolve()
+            except (OSError, RuntimeError):
+                return
+            # Cycle detection: skip if symlink points back to current dir or root.
+            if link_target == target_resolved or link_target == ws_resolved:
+                return
             try:
-                target.resolve().relative_to(link_target)
-                # target is under link_target — link_target is an ancestor → cycle
-                continue
+                target_resolved.relative_to(link_target)
+                return  # target is under link_target — ancestor → cycle
             except ValueError:
                 pass
-            # Block symlinks that resolve to system directories.
+            # Hide symlinks that resolve outside the workspace (can never be opened).
+            try:
+                link_target.relative_to(ws_resolved)
+            except ValueError:
+                return
             if _is_blocked_system_path(link_target):
-                continue
+                return
             is_dir = link_target.is_dir()
-            # Keep the display path relative to workspace (don't follow the link)
-            display_path = str(Path(item.name))
+            display_path = name
             if rel and rel != '.':
                 display_path = rel + '/' + display_path
-            try:
-                item_stat = item.lstat()
-                mtime_ns = item_stat.st_mtime_ns
-            except OSError:
-                mtime_ns = None
+            mtime_ns = lstat_result.st_mtime_ns if lstat_result is not None else None
             entry = {
-                'name': item.name,
+                'name': name,
                 'path': display_path,
                 'type': 'symlink',
                 'target': str(link_target),
@@ -753,27 +911,118 @@ def list_dir(workspace: Path, rel: str='.'):
                     entry['size'] = None
             entries.append(entry)
         else:
-            # Use rel-based path so entries under symlink targets (outside
-            # the workspace root) still get a valid workspace-relative path.
-            entry_path = item.name
+            entry_path = name
             if rel and rel != '.':
-                entry_path = rel + '/' + item.name
-            try:
-                item_stat = item.stat()
-                size = item_stat.st_size if item.is_file() else None
-                mtime_ns = item_stat.st_mtime_ns
-            except OSError:
+                entry_path = rel + '/' + name
+            if lstat_result is not None:
+                is_file = stat.S_ISREG(lstat_result.st_mode)
+                size = lstat_result.st_size if is_file else None
+                mtime_ns = lstat_result.st_mtime_ns
+                is_dir_entry = stat.S_ISDIR(lstat_result.st_mode)
+            else:
                 size = None
                 mtime_ns = None
+                is_dir_entry = False
             entries.append({
-                'name': item.name,
+                'name': name,
                 'path': entry_path,
-                'type': 'dir' if item.is_dir() else 'file',
+                'type': 'dir' if is_dir_entry else 'file',
                 'size': size,
                 'mtime_ns': mtime_ns,
             })
-        if len(entries) >= 200:
-            break
+
+    if _DIR_FD_OK:
+        # #3398 TOCTOU hardening (Linux/macOS): open the directory via an anchored
+        # openat-walk (O_NOFOLLOW on every component) and enumerate via the verified
+        # fd (os.scandir(fd) + fd-relative fstatat/readlinkat), so a path component
+        # swapped to an escaping symlink after safe_resolve_ws() cannot redirect the
+        # listing.
+        def _sort_key_de(de):
+            try:
+                is_link = de.is_symlink()
+            except OSError:
+                is_link = False
+            is_file = False
+            if not is_link:
+                try:
+                    is_file = de.is_file()
+                except OSError:
+                    pass
+            return (not is_link, is_file, de.name.lower())
+
+        dir_fd = open_anchored_fd(workspace, target, want_dir=True)
+        try:
+            st = os.fstat(dir_fd)
+            if not stat.S_ISDIR(st.st_mode):
+                raise FileNotFoundError(f"Not a directory: {rel}")
+            with os.scandir(dir_fd) as scan:
+                scandir_entries = sorted(scan, key=_sort_key_de)
+            for de in scandir_entries:
+                name = de.name
+                is_symlink = de.is_symlink()
+                raw_link = None
+                if is_symlink:
+                    try:
+                        raw_link = os.readlink(name, dir_fd=dir_fd)
+                    except OSError:
+                        raw_link = None
+                try:
+                    lst = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+                except OSError:
+                    lst = None
+                # reachable: follow-stat succeeds (filters ELOOP/broken symlinks).
+                reachable = True
+                if is_symlink:
+                    try:
+                        os.stat(name, dir_fd=dir_fd, follow_symlinks=True)
+                    except OSError:
+                        reachable = False
+                _process(name, is_symlink, raw_link, lst, reachable)
+                if len(entries) >= 200:
+                    break
+        finally:
+            try:
+                os.close(dir_fd)
+            except OSError:
+                pass
+    else:
+        # Portability fallback (Windows / no dir_fd): path-based enumeration after
+        # safe_resolve_ws(). No anchored-fd race protection on these platforms, but
+        # no regression vs the prior behaviour (creating symlinks on Windows needs
+        # admin anyway), and safe_resolve_ws() still blocks the static escape.
+        def _sort_key_p(p: Path):
+            is_link = p.is_symlink()
+            is_file = False
+            if not is_link:
+                try:
+                    is_file = p.is_file()
+                except OSError:
+                    pass
+            return (not is_link, is_file, p.name.lower())
+
+        for item in sorted(target.iterdir(), key=_sort_key_p):
+            name = item.name
+            is_symlink = item.is_symlink()
+            raw_link = None
+            if is_symlink:
+                try:
+                    raw_link = os.readlink(str(item))
+                except OSError:
+                    raw_link = None
+            try:
+                lst = item.lstat()
+            except OSError:
+                lst = None
+            # reachable: follow-stat succeeds (filters ELOOP/broken symlinks).
+            reachable = True
+            if is_symlink:
+                try:
+                    os.stat(str(item), follow_symlinks=True)
+                except OSError:
+                    reachable = False
+            _process(name, is_symlink, raw_link, lst, reachable)
+            if len(entries) >= 200:
+                break
     return entries
 
 
@@ -805,11 +1054,20 @@ def read_file_content(workspace: Path, rel: str) -> dict:
     target = safe_resolve_ws(workspace, rel)
     if not target.is_file():
         raise FileNotFoundError(f"Not a file: {rel}")
-    size = target.stat().st_size
-    if size > MAX_FILE_BYTES:
-        raise ValueError(f"File too large ({size} bytes, max {MAX_FILE_BYTES})")
-    content = target.read_text(encoding='utf-8', errors='replace')
-    return {'path': rel, 'content': content, 'size': size, 'lines': content.count('\n') + 1}
+    # #3398 TOCTOU hardening: open the resolved file via an anchored openat-walk
+    # (O_NOFOLLOW on every component) so a path swapped to an escaping symlink
+    # after safe_resolve_ws() cannot be followed, then read from the fd (not the
+    # pathname) so the bytes returned are guaranteed to be the verified file.
+    fd = open_anchored_fd(workspace, target, want_dir=False)
+    with os.fdopen(fd, 'rb', closefd=True) as fh:
+        st = os.fstat(fh.fileno())
+        if not stat.S_ISREG(st.st_mode):
+            raise FileNotFoundError(f"Not a file: {rel}")
+        if st.st_size > MAX_FILE_BYTES:
+            raise ValueError(f"File too large ({st.st_size} bytes, max {MAX_FILE_BYTES})")
+        raw = fh.read(MAX_FILE_BYTES + 1)
+    content = raw.decode('utf-8', errors='replace')
+    return {'path': rel, 'content': content, 'size': len(raw), 'lines': content.count('\n') + 1}
 
 
 # ── Git detection ──────────────────────────────────────────────────────────

package/vendor/agent-frontend-shell/bitseek_docs/en/00-Installation.md

@@ -0,0 +1,174 @@
+# Installation and Startup of BitSeek Claw
+
+This guide explains how to install and start BitSeek Claw (Hermes WebUI).
+
+## System Requirements
+
+- **Operating System**: macOS, Linux, or WSL2 (Windows requires WSL2)
+- **Python**: 3.8 or higher
+- **Hermes Agent**: Requires pre-installed Hermes Agent
+
+## Installation Steps
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/your-repo/agent-frontend-shell.git
+cd agent-frontend-shell
+```
+
+### 2. Environment Configuration
+
+#### Method 1: Using `.env` File (Recommended)
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit the .env file to configure necessary parameters
+nano .env
+```
+
+#### Method 2: Setting Environment Variables Directly
+
+```bash
+export HERMES_WEBUI_HOST=127.0.0.1
+export HERMES_WEBUI_PORT=8787
+export HERMES_HOME=~/.hermes
+```
+
+### 3. Starting the Service
+
+#### Method 1: Using Startup Script (Recommended)
+
+```bash
+# Start using start.sh
+./start.sh
+```
+
+#### Method 2: Using Python Launcher
+
+```bash
+# Start using bootstrap.py (automatically checks dependencies)
+python3 bootstrap.py
+```
+
+#### Method 3: Using Control Script
+
+```bash
+# Manage service using ctl.sh
+./ctl.sh start
+```
+
+## Startup Parameters
+
+### Environment Variable Configuration
+
+| Variable Name | Default Value | Description |
+|---------------|---------------|-------------|
+| `HERMES_WEBUI_HOST` | `127.0.0.1` | Listening address |
+| `HERMES_WEBUI_PORT` | `8787` | Listening port |
+| `HERMES_HOME` | `~/.hermes` | Hermes main directory |
+| `HERMES_WEBUI_STATE_DIR` | - | State directory path |
+| `HERMES_WEBUI_DEFAULT_WORKSPACE` | - | Default workspace path |
+
+### Startup Options
+
+```bash
+# Start with specific port
+HERMES_WEBUI_PORT=8888 ./start.sh
+
+# Start with specific host and port
+HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PORT=8787 ./start.sh
+
+# Start with custom state directory
+HERMES_WEBUI_STATE_DIR=/tmp/hermes-state ./start.sh
+```
+
+## Accessing the Interface
+
+After successful startup, access in your browser:
+
+```
+http://localhost:8787
+```
+
+### First-time Access
+
+1. Open your browser and navigate to the above address
+2. First-time access will enter the **First Run Wizard**
+3. Follow the wizard prompts to configure:
+   - AI provider settings (e.g., OpenAI, Anthropic, etc.)
+   - API key configuration
+   - Basic preference settings
+
+## Docker Deployment
+
+### Single Container Deployment
+
+```bash
+# Using Docker Compose
+docker-compose up -d
+
+# Or using custom configuration
+docker-compose -f docker-compose.custom.yml up -d
+```
+
+### Multi-container Deployment
+
+```bash
+# Three-container architecture
+docker-compose -f docker-compose.three-container.yml up -d
+
+# Two-container architecture
+docker-compose -f docker-compose.two-container.yml up -d
+```
+
+## Common Issues
+
+### Port in Use
+
+```bash
+# Check port usage
+lsof -i :8787
+
+# Use a different port
+HERMES_WEBUI_PORT=8788 ./start.sh
+```
+
+### Permission Issues
+
+```bash
+# Ensure scripts have execute permissions
+chmod +x start.sh
+chmod +x ctl.sh
+chmod +x bootstrap.py
+```
+
+### Missing Dependencies
+
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Or use a virtual environment
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Stopping the Service
+
+```bash
+# Stop using control script
+./ctl.sh stop
+
+# Or find and terminate the process
+pkill -f "python.*server.py"
+```
+
+## Next Steps
+
+After installation and startup, please refer to:
+- **[Overview](01-Overview.md)** - Understand the interface layout
+- **[Page Operations](02-Page-Operations.md)** - Learn specific operations