website-agent-server 0.1.0__tar.gz

website_agent_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGN_2015
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

website_agent_server-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: website-agent-server
+Version: 0.1.0
+Summary: A server-side browser proxy that lets clients operate websites without direct remote connections.
+License-File: LICENSE
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: fastapi (>=0.115)
+Requires-Dist: playwright (>=1.48)
+Requires-Dist: python-multipart (>=0.0.9)
+Requires-Dist: uvicorn[standard] (>=0.30)
+Description-Content-Type: text/markdown
+
+# Website Agent Server
+
+English | [中文](README.zh-CN.md)
+
+Website Agent Server is a Python server-side browser proxy. The client never loads the target website directly. It connects only to this server, receives rendered browser frames, and sends mouse, keyboard, input method, clipboard, wheel, file upload, and navigation events back to the server.
+
+## How It Works
+
+- FastAPI serves the local control UI, HTTP API, and WebSocket endpoint.
+- Playwright launches Chromium on the server.
+- The target website runs inside the server-side browser context.
+- The client receives binary WebSocket image frames: JPEG screenshots by default, or PNG frames when `--screenshot-quality 100` is used.
+- User actions are replayed into Chromium by the server.
+- IME text, paste, copy, cut, downloads, file chooser actions, cookie management, and ordinary media element audio are brokered through local server endpoints.
+
+Because the remote page is never embedded as HTML in the client, page scripts, link clicks, images, XHR/fetch calls, WebSocket connections, and form submissions are performed by the server-side browser.
+
+## Setup
+
+Create or reuse the repository-root virtual environment:
+
+```powershell
+python -m venv venv
+venv\Scripts\python.exe -m pip install -r requirements.txt
+venv\Scripts\python.exe -m playwright install chromium
+```
+
+## Run
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server
+```
+
+Open [http://127.0.0.1:8000](http://127.0.0.1:8000), enter a website URL, and operate the remote site through the rendered viewport. By default the server listens on all interfaces, so LAN clients can also connect with the server machine's LAN IP.
+
+If a target URL is entered without an `http://` or `https://` prefix, the server first probes HTTPS. It uses HTTPS when the TLS service is available, otherwise it falls back to HTTP. The same rule applies to `--lock-url` and `/lock_url/...` paths.
+
+You can lock only one client by putting the target URL in the server URL path:
+
+```text
+http://127.0.0.1:8000/lock_url/https/example.com/path
+```
+
+That client opens the target immediately and hides the browser option controls. Other clients that open `/` keep the normal URL picker. Query strings and fragments are preserved, for example `/lock_url/https/example.com/path?x=1#section`.
+
+## Command-Line Configuration
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --port 8080 --headed
+```
+
+Require a PIN before clients can use the proxy:
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --pin 123456
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--host` | `0.0.0.0` | Server bind host. Use `127.0.0.1` to restrict access to this machine. |
+| `--port` | `8000` | Server port. |
+| `--headed` | disabled | Run Chromium with a visible browser window. |
+| `--ignore-https-errors` | disabled | Ignore remote TLS certificate errors. |
+| `--allow-private-hosts` | disabled | Allow navigation and resource requests to private, local, or reserved networks. |
+| `--session-ttl-seconds` | `600` | Disconnected client session and client browser context lifetime. A client can reconnect to its cached browser session during this window. |
+| `--navigation-timeout-ms` | `30000` | Navigation timeout. |
+| `--frame-interval-seconds` | `0.18` | Screenshot streaming interval. |
+| `--screenshot-quality` | `95` | Frame quality from 1 to 100. Values below 100 use JPEG; 100 uses PNG. |
+| `--media-frame-interval-seconds` | `0.35` | Screenshot streaming interval while remote media is playing. |
+| `--media-screenshot-quality` | `80` | JPEG quality while remote media is playing. Ignored when `--screenshot-quality 100` enables PNG. |
+| `--min-viewport-width` | `320` | Minimum remote viewport width. |
+| `--min-viewport-height` | `240` | Minimum remote viewport height. |
+| `--max-viewport-width` | `1920` | Maximum remote viewport width. |
+| `--max-viewport-height` | `1600` | Maximum remote viewport height. |
+| `--data-dir` | `.agent-data` | Runtime downloads and temporary uploads directory. |
+| `--pin` | disabled | Require this PIN before clients can access the proxy UI, API, or WebSocket. |
+| `--lock-url` | disabled | Open this URL automatically and hide/disable browser option controls such as Back, Forward, Cookie, Quit, and address navigation. PIN authentication still applies when configured. |
+
+Private and local network targets are blocked by default to reduce SSRF risk. Use `--allow-private-hosts` only when you trust the users who can access the proxy.
+
+Because LAN access is enabled by default, prefer using a PIN:
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --pin 123456
+```
+
+If the proxy itself also needs to open LAN or localhost target URLs, enable private hosts explicitly:
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --allow-private-hosts --pin 123456
+```
+
+Each client receives exactly one server-side Playwright `BrowserContext`, keyed only by its local `session-uuid` cookie. Contexts are never shared by IP address, target host, port, URL path, or device class. If the same client opens another target URL before its UUID expires, the old page is closed and the same context is reused, including storage partitions, service workers, permissions, and other browser context state.
+
+Mobile clients use a mobile Playwright browser profile with a narrow viewport, touch support, a mobile Chromium user agent, and mobile Client Hints so upstream responsive sites can select their mobile layout.
+
+The local `session-uuid` cookie only identifies the Website Agent client, not the remote site. If the local page refreshes or the WebSocket drops, the server uses that cookie to reconnect the same client to its existing browser session. Disconnected browser sessions and idle client contexts are removed after `--session-ttl-seconds`, which is 10 minutes by default. When a UUID is removed, its BrowserContext, browsing history, cookies, localStorage, IndexedDB, download files, upload files, and in-memory session records are removed together.
+
+Uvicorn's WebSocket ping keepalive is disabled because mobile browsers may suspend sockets while loading, switching apps, or sleeping. The client reconnect path and session TTL handle those drops without printing keepalive tracebacks.
+
+Audio from ordinary server-side `<audio>` and `<video>` elements is captured in the page with `captureStream()` or a WebAudio fallback and forwarded over a dedicated WebSocket as WebM/Opus chunks, separate from screenshot frames. The server-side page is not relied on for audible playback. When remote media is playing, screenshot streaming automatically uses `--media-frame-interval-seconds` and `--media-screenshot-quality` to reduce CPU and network pressure. This does not cover DRM media, WebRTC calls, pure WebAudio graphs, browser UI sounds, or system-level mixed audio.
+
+## Limitations
+
+This project proxies interaction by streaming rendered browser frames, not by rewriting HTML. That keeps remote network access on the server, but it also means the client sees a bitmap viewport rather than native DOM nodes. Browser extension APIs, local client certificates, DRM-protected media, and some system dialogs are outside the current scope.
+

website_agent_server-0.1.0/README.md

@@ -0,0 +1,105 @@
+# Website Agent Server
+
+English | [中文](README.zh-CN.md)
+
+Website Agent Server is a Python server-side browser proxy. The client never loads the target website directly. It connects only to this server, receives rendered browser frames, and sends mouse, keyboard, input method, clipboard, wheel, file upload, and navigation events back to the server.
+
+## How It Works
+
+- FastAPI serves the local control UI, HTTP API, and WebSocket endpoint.
+- Playwright launches Chromium on the server.
+- The target website runs inside the server-side browser context.
+- The client receives binary WebSocket image frames: JPEG screenshots by default, or PNG frames when `--screenshot-quality 100` is used.
+- User actions are replayed into Chromium by the server.
+- IME text, paste, copy, cut, downloads, file chooser actions, cookie management, and ordinary media element audio are brokered through local server endpoints.
+
+Because the remote page is never embedded as HTML in the client, page scripts, link clicks, images, XHR/fetch calls, WebSocket connections, and form submissions are performed by the server-side browser.
+
+## Setup
+
+Create or reuse the repository-root virtual environment:
+
+```powershell
+python -m venv venv
+venv\Scripts\python.exe -m pip install -r requirements.txt
+venv\Scripts\python.exe -m playwright install chromium
+```
+
+## Run
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server
+```
+
+Open [http://127.0.0.1:8000](http://127.0.0.1:8000), enter a website URL, and operate the remote site through the rendered viewport. By default the server listens on all interfaces, so LAN clients can also connect with the server machine's LAN IP.
+
+If a target URL is entered without an `http://` or `https://` prefix, the server first probes HTTPS. It uses HTTPS when the TLS service is available, otherwise it falls back to HTTP. The same rule applies to `--lock-url` and `/lock_url/...` paths.
+
+You can lock only one client by putting the target URL in the server URL path:
+
+```text
+http://127.0.0.1:8000/lock_url/https/example.com/path
+```
+
+That client opens the target immediately and hides the browser option controls. Other clients that open `/` keep the normal URL picker. Query strings and fragments are preserved, for example `/lock_url/https/example.com/path?x=1#section`.
+
+## Command-Line Configuration
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --port 8080 --headed
+```
+
+Require a PIN before clients can use the proxy:
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --pin 123456
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--host` | `0.0.0.0` | Server bind host. Use `127.0.0.1` to restrict access to this machine. |
+| `--port` | `8000` | Server port. |
+| `--headed` | disabled | Run Chromium with a visible browser window. |
+| `--ignore-https-errors` | disabled | Ignore remote TLS certificate errors. |
+| `--allow-private-hosts` | disabled | Allow navigation and resource requests to private, local, or reserved networks. |
+| `--session-ttl-seconds` | `600` | Disconnected client session and client browser context lifetime. A client can reconnect to its cached browser session during this window. |
+| `--navigation-timeout-ms` | `30000` | Navigation timeout. |
+| `--frame-interval-seconds` | `0.18` | Screenshot streaming interval. |
+| `--screenshot-quality` | `95` | Frame quality from 1 to 100. Values below 100 use JPEG; 100 uses PNG. |
+| `--media-frame-interval-seconds` | `0.35` | Screenshot streaming interval while remote media is playing. |
+| `--media-screenshot-quality` | `80` | JPEG quality while remote media is playing. Ignored when `--screenshot-quality 100` enables PNG. |
+| `--min-viewport-width` | `320` | Minimum remote viewport width. |
+| `--min-viewport-height` | `240` | Minimum remote viewport height. |
+| `--max-viewport-width` | `1920` | Maximum remote viewport width. |
+| `--max-viewport-height` | `1600` | Maximum remote viewport height. |
+| `--data-dir` | `.agent-data` | Runtime downloads and temporary uploads directory. |
+| `--pin` | disabled | Require this PIN before clients can access the proxy UI, API, or WebSocket. |
+| `--lock-url` | disabled | Open this URL automatically and hide/disable browser option controls such as Back, Forward, Cookie, Quit, and address navigation. PIN authentication still applies when configured. |
+
+Private and local network targets are blocked by default to reduce SSRF risk. Use `--allow-private-hosts` only when you trust the users who can access the proxy.
+
+Because LAN access is enabled by default, prefer using a PIN:
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --pin 123456
+```
+
+If the proxy itself also needs to open LAN or localhost target URLs, enable private hosts explicitly:
+
+```powershell
+venv\Scripts\python.exe -m website_agent_server --allow-private-hosts --pin 123456
+```
+
+Each client receives exactly one server-side Playwright `BrowserContext`, keyed only by its local `session-uuid` cookie. Contexts are never shared by IP address, target host, port, URL path, or device class. If the same client opens another target URL before its UUID expires, the old page is closed and the same context is reused, including storage partitions, service workers, permissions, and other browser context state.
+
+Mobile clients use a mobile Playwright browser profile with a narrow viewport, touch support, a mobile Chromium user agent, and mobile Client Hints so upstream responsive sites can select their mobile layout.
+
+The local `session-uuid` cookie only identifies the Website Agent client, not the remote site. If the local page refreshes or the WebSocket drops, the server uses that cookie to reconnect the same client to its existing browser session. Disconnected browser sessions and idle client contexts are removed after `--session-ttl-seconds`, which is 10 minutes by default. When a UUID is removed, its BrowserContext, browsing history, cookies, localStorage, IndexedDB, download files, upload files, and in-memory session records are removed together.
+
+Uvicorn's WebSocket ping keepalive is disabled because mobile browsers may suspend sockets while loading, switching apps, or sleeping. The client reconnect path and session TTL handle those drops without printing keepalive tracebacks.
+
+Audio from ordinary server-side `<audio>` and `<video>` elements is captured in the page with `captureStream()` or a WebAudio fallback and forwarded over a dedicated WebSocket as WebM/Opus chunks, separate from screenshot frames. The server-side page is not relied on for audible playback. When remote media is playing, screenshot streaming automatically uses `--media-frame-interval-seconds` and `--media-screenshot-quality` to reduce CPU and network pressure. This does not cover DRM media, WebRTC calls, pure WebAudio graphs, browser UI sounds, or system-level mixed audio.
+
+## Limitations
+
+This project proxies interaction by streaming rendered browser frames, not by rewriting HTML. That keeps remote network access on the server, but it also means the client sees a bitmap viewport rather than native DOM nodes. Browser extension APIs, local client certificates, DRM-protected media, and some system dialogs are outside the current scope.

website_agent_server-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "website-agent-server"
+version = "0.1.0"
+description = "A server-side browser proxy that lets clients operate websites without direct remote connections."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+  "playwright>=1.48",
+  "python-multipart>=0.0.9",
+]
+
+[project.scripts]
+website-agent-server = "website_agent_server.__main__:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

website_agent_server-0.1.0/website_agent_server/__init__.py

@@ -0,0 +1,3 @@
+"""Website Agent Server package."""
+
+__version__ = "0.1.0"

website_agent_server-0.1.0/website_agent_server/__main__.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+from pathlib import Path
+
+import uvicorn
+
+from .config import settings
+from .url_policy import HostAccessPolicy
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="website-agent-server",
+        description="Run the server-side browser proxy.",
+    )
+    parser.add_argument("--host", default=settings.host, help="Server bind host.")
+    parser.add_argument("--port", type=int, default=settings.port, help="Server port.")
+    parser.add_argument(
+        "--headed",
+        action="store_true",
+        help="Run Chromium with a visible browser window.",
+    )
+    parser.add_argument(
+        "--ignore-https-errors",
+        action="store_true",
+        help="Ignore remote TLS certificate errors.",
+    )
+    parser.add_argument(
+        "--allow-private-hosts",
+        action="store_true",
+        help="Allow private, local, and reserved network targets.",
+    )
+    parser.add_argument(
+        "--session-ttl-seconds",
+        type=int,
+        default=settings.session_ttl_seconds,
+        help="Idle session lifetime in seconds.",
+    )
+    parser.add_argument(
+        "--navigation-timeout-ms",
+        type=int,
+        default=settings.navigation_timeout_ms,
+        help="Navigation timeout in milliseconds.",
+    )
+    parser.add_argument(
+        "--frame-interval-seconds",
+        type=float,
+        default=settings.frame_interval_seconds,
+        help="Screenshot streaming interval in seconds.",
+    )
+    parser.add_argument(
+        "--screenshot-quality",
+        type=int,
+        default=settings.screenshot_quality,
+        help="Screenshot quality from 1 to 100. Values below 100 use JPEG; 100 uses PNG.",
+    )
+    parser.add_argument(
+        "--media-frame-interval-seconds",
+        type=float,
+        default=settings.media_frame_interval_seconds,
+        help="Screenshot streaming interval while remote media is playing.",
+    )
+    parser.add_argument(
+        "--media-screenshot-quality",
+        type=int,
+        default=settings.media_screenshot_quality,
+        help="JPEG screenshot quality while remote media is playing. Ignored when screenshot quality is 100.",
+    )
+    parser.add_argument(
+        "--min-viewport-width",
+        type=int,
+        default=settings.min_viewport_width,
+        help="Minimum remote viewport width.",
+    )
+    parser.add_argument(
+        "--min-viewport-height",
+        type=int,
+        default=settings.min_viewport_height,
+        help="Minimum remote viewport height.",
+    )
+    parser.add_argument(
+        "--max-viewport-width",
+        type=int,
+        default=settings.max_viewport_width,
+        help="Maximum remote viewport width.",
+    )
+    parser.add_argument(
+        "--max-viewport-height",
+        type=int,
+        default=settings.max_viewport_height,
+        help="Maximum remote viewport height.",
+    )
+    parser.add_argument(
+        "--data-dir",
+        type=Path,
+        default=settings.data_dir,
+        help="Runtime downloads and temporary uploads directory.",
+    )
+    parser.add_argument(
+        "--pin",
+        default=None,
+        help="Require this PIN before clients can use the proxy.",
+    )
+    parser.add_argument(
+        "--lock-url",
+        default=None,
+        help="Lock the UI to this initial URL and disable browser option controls.",
+    )
+    return parser
+
+
+async def apply_args(args: argparse.Namespace) -> None:
+    settings.host = args.host
+    settings.port = args.port
+    settings.headless = not args.headed
+    settings.ignore_https_errors = args.ignore_https_errors
+    settings.allow_private_hosts = args.allow_private_hosts
+    settings.session_ttl_seconds = args.session_ttl_seconds
+    settings.navigation_timeout_ms = args.navigation_timeout_ms
+    settings.frame_interval_seconds = args.frame_interval_seconds
+    settings.screenshot_quality = max(1, min(100, args.screenshot_quality))
+    settings.media_frame_interval_seconds = max(0.05, args.media_frame_interval_seconds)
+    settings.media_screenshot_quality = max(1, min(99, args.media_screenshot_quality))
+    settings.min_viewport_width = args.min_viewport_width
+    settings.min_viewport_height = args.min_viewport_height
+    settings.max_viewport_width = args.max_viewport_width
+    settings.max_viewport_height = args.max_viewport_height
+    settings.data_dir = args.data_dir.resolve()
+    settings.pin = args.pin
+    if args.lock_url:
+        lock_url_policy = HostAccessPolicy(settings.allow_private_hosts)
+        settings.lock_url = await lock_url_policy.ensure_navigation_url_allowed(
+            args.lock_url,
+            verify_https=not settings.ignore_https_errors,
+        )
+    else:
+        settings.lock_url = None
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        asyncio.run(apply_args(args))
+    except ValueError as exc:
+        parser.error(str(exc))
+    uvicorn.run(
+        "website_agent_server.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=False,
+        ws_ping_interval=None,
+    )
+
+
+if __name__ == "__main__":
+    main()

website_agent_server-0.1.0/website_agent_server/auth.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import hmac
+import secrets
+from hashlib import sha256
+
+from fastapi import HTTPException, Request, WebSocket, status
+from starlette.responses import Response
+
+from .config import Settings
+
+
+class PinAuth:
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        self._secret = secrets.token_urlsafe(32)
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.settings.pin)
+
+    def verify_pin(self, pin: str) -> bool:
+        expected = self.settings.pin or ""
+        return hmac.compare_digest(pin, expected)
+
+    def token(self) -> str:
+        if not self.settings.pin:
+            return ""
+        digest = hmac.new(
+            self._secret.encode("utf-8"),
+            self.settings.pin.encode("utf-8"),
+            sha256,
+        ).hexdigest()
+        return digest
+
+    def is_request_allowed(self, request: Request) -> bool:
+        if not self.enabled:
+            return True
+        token = request.cookies.get(self.settings.auth_cookie_name, "")
+        return hmac.compare_digest(token, self.token())
+
+    def require_request(self, request: Request) -> None:
+        if not self.is_request_allowed(request):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="PIN required.",
+            )
+
+    def is_websocket_allowed(self, websocket: WebSocket) -> bool:
+        if not self.enabled:
+            return True
+        token = websocket.cookies.get(self.settings.auth_cookie_name, "")
+        return hmac.compare_digest(token, self.token())
+
+    def set_cookie(self, response: Response) -> None:
+        response.set_cookie(
+            self.settings.auth_cookie_name,
+            self.token(),
+            max_age=self.settings.auth_cookie_max_age,
+            httponly=True,
+            samesite="lax",
+            secure=False,
+            path="/",
+        )
+
+    def clear_cookie(self, response: Response) -> None:
+        response.delete_cookie(self.settings.auth_cookie_name, path="/")