py-web-ssh 0.1.4__tar.gz → 0.1.6__tar.gz

{py_web_ssh-0.1.4 → py_web_ssh-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-web-ssh
-Version: 0.1.4
+Version: 0.1.6
 Summary: A Python web SSH client with xterm.js, reconnectable sessions, logs, and file transfer.
 License-Expression: MIT
 License-File: LICENSE
@@ -33,8 +33,10 @@ Description-Content-Type: text/markdown
 - 会话回收：同一个 UUID 如果所有浏览器连接都断开并且 5 分钟内无人重连，服务端会主动断开 SSH 并清理内存缓存。
 - 终端恢复：服务端保存 SSH 输出流，浏览器定期回传 xterm serialize 快照；重连时先恢复快照，再补放快照之后的输出。
 - 日志页面：`/sessions/{uuid}/logs` 展示完整连接、认证、错误和文件传输日志。
-- 文件传输：优先 SFTP；SFTP 不可用时参考 `simple-ssh-copy` 思路，使用远端 `base64` shell 命令 fallback 上传/下载。
+- 文件传输：参考 `simple-ssh-copy` 思路，不使用 SFTP/SCP；每次传输都按连接配置新建独立 SSH 连接，使用远端 `base64` shell 命令上传/下载。上传先写远端临时文件，完成后再 `mv` 到最终路径，并支持进度显示和取消。
 - 可选 PIN 门禁：服务端传入 `--pin` 后，网页启动时必须先输入正确 PIN；验证成功后浏览器会保存加盐哈希 cookie，后端会保护 HTTP API、日志页面、文件接口和 WebSocket。
+- 启动锁定策略：支持 `--lock-host`、`--lock-username`、`--lock-pwd`、`--lock-private-key`，可从服务端强制绑定目标主机、用户名、密码和服务端侧私钥文件。前端会锁定或隐藏对应控件，后端仍会校验并覆盖敏感字段。
+- 中英双语：默认英文，网页和日志页都支持中英切换；语言选择会长期保存到 `py_web_ssh_lang` cookie。
 - 浏览器客户端 session：首次访问时服务端会分配独立的浏览器 session UUID，并写入 HttpOnly cookie；它与 SSH 会话 UUID 分离。
 - 左侧控制面板：连接、会话、文件三个栏目改为互斥折叠面板，一次最多展开一个，也可以全部折叠。
 
@@ -66,10 +68,21 @@ uvicorn webssh.app:app --host 0.0.0.0 --port 8022
 py-web-ssh --pin 123456
 ```
 
+锁定连接目标或凭据：
+
+```bash
+py-web-ssh --lock-host server.example.com --lock-username deploy
+py-web-ssh --lock-pwd 'ssh-password'
+py-web-ssh --lock-private-key C:\secrets\id_ed25519
+```
+
+`--lock-pwd` 和 `--lock-private-key` 的值只在服务端使用，不会通过配置接口发送给浏览器。`--lock-private-key` 指向的是服务端本机文件路径，不是浏览器上传的文件。
+
 前端默认从 jsDelivr 加载 xterm.js、fit addon 和 serialize addon。离线内网部署时，请把这些静态资源 vendoring 到 `webssh/static/` 并替换 `index.html` 里的 CDN 地址。
 
 ## API 概览
 
+- `GET /api/config` 查看非敏感的服务端公开配置和锁定状态。
 - `POST /api/sessions` 创建 SSH 会话。
 - `GET /api/sessions/{uuid}` 查看会话状态。
 - `GET /api/sessions/{uuid}/logs` 获取完整日志 JSON。

{py_web_ssh-0.1.4 → py_web_ssh-0.1.6}/README.md

@@ -11,8 +11,10 @@
 - 会话回收：同一个 UUID 如果所有浏览器连接都断开并且 5 分钟内无人重连，服务端会主动断开 SSH 并清理内存缓存。
 - 终端恢复：服务端保存 SSH 输出流，浏览器定期回传 xterm serialize 快照；重连时先恢复快照，再补放快照之后的输出。
 - 日志页面：`/sessions/{uuid}/logs` 展示完整连接、认证、错误和文件传输日志。
-- 文件传输：优先 SFTP；SFTP 不可用时参考 `simple-ssh-copy` 思路，使用远端 `base64` shell 命令 fallback 上传/下载。
+- 文件传输：参考 `simple-ssh-copy` 思路，不使用 SFTP/SCP；每次传输都按连接配置新建独立 SSH 连接，使用远端 `base64` shell 命令上传/下载。上传先写远端临时文件，完成后再 `mv` 到最终路径，并支持进度显示和取消。
 - 可选 PIN 门禁：服务端传入 `--pin` 后，网页启动时必须先输入正确 PIN；验证成功后浏览器会保存加盐哈希 cookie，后端会保护 HTTP API、日志页面、文件接口和 WebSocket。
+- 启动锁定策略：支持 `--lock-host`、`--lock-username`、`--lock-pwd`、`--lock-private-key`，可从服务端强制绑定目标主机、用户名、密码和服务端侧私钥文件。前端会锁定或隐藏对应控件，后端仍会校验并覆盖敏感字段。
+- 中英双语：默认英文，网页和日志页都支持中英切换；语言选择会长期保存到 `py_web_ssh_lang` cookie。
 - 浏览器客户端 session：首次访问时服务端会分配独立的浏览器 session UUID，并写入 HttpOnly cookie；它与 SSH 会话 UUID 分离。
 - 左侧控制面板：连接、会话、文件三个栏目改为互斥折叠面板，一次最多展开一个，也可以全部折叠。
 
@@ -38,17 +40,28 @@ uvicorn webssh.app:app --host 0.0.0.0 --port 8022
 
 打开 <http://127.0.0.1:8022>。
 
-启用 PIN：
-
-```bash
-py-web-ssh --pin 123456
-```
-
-前端默认从 jsDelivr 加载 xterm.js、fit addon 和 serialize addon。离线内网部署时，请把这些静态资源 vendoring 到 `webssh/static/` 并替换 `index.html` 里的 CDN 地址。
-
-## API 概览
-
-- `POST /api/sessions` 创建 SSH 会话。
+启用 PIN：
+
+```bash
+py-web-ssh --pin 123456
+```
+
+锁定连接目标或凭据：
+
+```bash
+py-web-ssh --lock-host server.example.com --lock-username deploy
+py-web-ssh --lock-pwd 'ssh-password'
+py-web-ssh --lock-private-key C:\secrets\id_ed25519
+```
+
+`--lock-pwd` 和 `--lock-private-key` 的值只在服务端使用，不会通过配置接口发送给浏览器。`--lock-private-key` 指向的是服务端本机文件路径，不是浏览器上传的文件。
+
+前端默认从 jsDelivr 加载 xterm.js、fit addon 和 serialize addon。离线内网部署时，请把这些静态资源 vendoring 到 `webssh/static/` 并替换 `index.html` 里的 CDN 地址。
+
+## API 概览
+
+- `GET /api/config` 查看非敏感的服务端公开配置和锁定状态。
+- `POST /api/sessions` 创建 SSH 会话。
 - `GET /api/sessions/{uuid}` 查看会话状态。
 - `GET /api/sessions/{uuid}/logs` 获取完整日志 JSON。
 - `DELETE /api/sessions/{uuid}` 主动断开 SSH。

{py_web_ssh-0.1.4 → py_web_ssh-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "py-web-ssh"
-version = "0.1.4"
+version = "0.1.6"
 description = "A Python web SSH client with xterm.js, reconnectable sessions, logs, and file transfer."
 readme = "README.md"
 requires-python = ">=3.10"

{py_web_ssh-0.1.4 → py_web_ssh-0.1.6}/webssh/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.4"
+__version__ = "0.1.6"

{py_web_ssh-0.1.4 → py_web_ssh-0.1.6}/webssh/app.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import asyncio
-import base64
 import argparse
+import base64
 from pathlib import Path
 from typing import Annotated
 
@@ -14,9 +14,17 @@ from . import __version__
 from . import auth
 from .auth import add_pin_argument, configure_pin
 from .client_session import ensure_client_session_cookie
-from .files import download_file, filename_for_download, upload_file
+from .files import (
+    FileTransferCancelled,
+    download_file_via_ssh,
+    filename_for_download,
+    upload_file_via_ssh,
+)
 from .models import ConnectRequest, CreateSessionResponse, FileTransferResponse
+from .runtime_config import add_runtime_lock_arguments, configure_runtime_locks
+from . import runtime_config as runtime_config_module
 from .session import SessionManager
+from .transfers import TransferManager
 
 
 BASE_DIR = Path(__file__).resolve().parent
@@ -28,6 +36,7 @@ DEFAULT_PORT = 8022
 app = FastAPI(title="py-web-ssh", version=__version__)
 app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 sessions = SessionManager()
+transfers = TransferManager()
 
 
 @app.middleware("http")
@@ -53,8 +62,18 @@ def index() -> FileResponse:
 
 
 @app.get("/api/auth/status")
-def auth_status() -> JSONResponse:
-    return JSONResponse(auth.pin_auth.status_payload())
+def auth_status(request: Request) -> JSONResponse:
+    return JSONResponse(
+        {
+            **auth.pin_auth.status_payload(),
+            "authorized": auth.pin_auth.is_request_authorized(request),
+        }
+    )
+
+
+@app.get("/api/config")
+def public_config() -> JSONResponse:
+    return JSONResponse(runtime_config_module.runtime_config.public_payload())
 
 
 @app.post("/api/auth/login")
@@ -76,7 +95,8 @@ def logs_page(session_id: str) -> HTMLResponse:
 
 @app.post("/api/sessions", response_model=CreateSessionResponse)
 def create_session(config: ConnectRequest) -> CreateSessionResponse:
-    session = sessions.create(config)
+    locked_config = runtime_config_module.runtime_config.apply_to_connect_request(config)
+    session = sessions.create(locked_config)
     return CreateSessionResponse(
         session_id=session.id,
         logs_url=f"/sessions/{session.id}/logs",
@@ -118,19 +138,35 @@ def upload(
     session_id: str,
     remote_path: Annotated[str, Form(min_length=1)],
     file: Annotated[UploadFile, File()],
+    transfer_id: Annotated[str | None, Form()] = None,
+    total_bytes: Annotated[int | None, Form()] = None,
 ) -> FileTransferResponse:
     session = _require_session(session_id)
+    tracker = transfers.get(transfer_id) if transfer_id else None
+    if transfer_id and tracker is None:
+        raise HTTPException(status_code=404, detail="Transfer not found.")
+    if tracker is None:
+        tracker = transfers.create_upload(total_bytes or _content_length(file), remote_path)
     try:
-        method, transferred = upload_file(
-            session.ssh_client,
+        method, transferred = upload_file_via_ssh(
+            session.config,
             file.file,
             remote_path,
-            _content_length(file),
+            total_bytes or _content_length(file),
+            cancel_event=tracker.cancel_event,
+            progress=tracker.update_progress,
         )
+    except FileTransferCancelled as exc:
+        message = f"File upload cancelled: {exc}"
+        tracker.cancelled(message)
+        session.log("warning", message, None)
+        raise HTTPException(status_code=499, detail=message) from exc
     except Exception as exc:
+        tracker.fail(str(exc))
         session.log("error", f"File upload failed: {exc}", None)
         raise HTTPException(status_code=500, detail=str(exc)) from exc
     message = f"Uploaded {transferred} bytes to {remote_path} using {method}."
+    tracker.complete(transferred, message)
     session.log("info", message, None)
     return FileTransferResponse(
         ok=True,
@@ -138,14 +174,63 @@ def upload(
         bytes_transferred=transferred,
         remote_path=remote_path,
         message=message,
+        transfer_id=tracker.id,
     )
 
 
+@app.post("/api/sessions/{session_id}/files/uploads")
+async def create_upload_task(session_id: str, request: Request) -> JSONResponse:
+    _require_session(session_id)
+    payload = await request.json()
+    remote_path = str(payload.get("remote_path", "")).strip()
+    if not remote_path:
+        raise HTTPException(status_code=422, detail="remote_path is required.")
+    total_bytes = payload.get("total_bytes")
+    if total_bytes is not None:
+        total_bytes = int(total_bytes)
+    tracker = transfers.create_upload(total_bytes, remote_path)
+    return JSONResponse(
+        {
+            "transfer_id": tracker.id,
+            "state": tracker.status().state,
+            "remote_path": remote_path,
+            "total_bytes": total_bytes,
+        }
+    )
+
+
+@app.get("/api/transfers/{transfer_id}")
+def get_transfer(transfer_id: str) -> JSONResponse:
+    tracker = transfers.get(transfer_id)
+    if tracker is None:
+        raise HTTPException(status_code=404, detail="Transfer not found.")
+    status = tracker.status()
+    return JSONResponse(
+        {
+            "transfer_id": status.transfer_id,
+            "state": status.state,
+            "bytes_transferred": status.bytes_transferred,
+            "total_bytes": status.total_bytes,
+            "remote_path": status.remote_path,
+            "message": status.message,
+            "created_at": status.created_at.isoformat(),
+            "updated_at": status.updated_at.isoformat(),
+        }
+    )
+
+
+@app.delete("/api/transfers/{transfer_id}")
+def cancel_transfer(transfer_id: str) -> JSONResponse:
+    if not transfers.cancel(transfer_id):
+        raise HTTPException(status_code=404, detail="Transfer not found.")
+    return JSONResponse({"ok": True})
+
+
 @app.get("/api/sessions/{session_id}/files/download")
 def download(session_id: str, remote_path: str) -> StreamingResponse:
     session = _require_session(session_id)
     try:
-        method, stream = download_file(session.ssh_client, remote_path)
+        method, stream = download_file_via_ssh(session.config, remote_path)
     except Exception as exc:
         session.log("error", f"File download failed: {exc}", None)
         raise HTTPException(status_code=500, detail=str(exc)) from exc
@@ -240,6 +325,7 @@ def build_arg_parser() -> argparse.ArgumentParser:
     parser.add_argument("--host", default=DEFAULT_HOST, help="Host interface to bind.")
     parser.add_argument("--port", type=int, default=DEFAULT_PORT, help="Port to listen on.")
     add_pin_argument(parser)
+    add_runtime_lock_arguments(parser)
     return parser
 
 
@@ -249,6 +335,12 @@ def main() -> None:
     args = build_arg_parser().parse_args()
 
     configure_pin(args.pin)
+    configure_runtime_locks(
+        lock_host=args.lock_host,
+        lock_username=args.lock_username,
+        lock_password=args.lock_pwd,
+        lock_private_key=args.lock_private_key,
+    )
     uvicorn.run("webssh.app:app", host=args.host, port=args.port, reload=False)
 
 

py_web_ssh-0.1.6/webssh/files.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+import posixpath
+import shlex
+import threading
+import uuid
+from collections.abc import Callable, Iterator
+from typing import BinaryIO
+
+from .models import ConnectRequest
+from .ssh_client import connect_ssh
+
+
+class FileTransferError(RuntimeError):
+    pass
+
+
+class FileTransferCancelled(FileTransferError):
+    pass
+
+
+ProgressCallback = Callable[[int], None]
+
+
+def upload_file_via_ssh(
+    config: ConnectRequest,
+    source: BinaryIO,
+    remote_path: str,
+    size: int | None,
+    cancel_event: threading.Event | None = None,
+    progress: ProgressCallback | None = None,
+) -> tuple[str, int]:
+    """Upload using only an SSH exec channel and POSIX-ish shell commands.
+
+    This intentionally does not use SFTP or SCP. It follows the simple-ssh-copy
+    style: stream base64 into a remote shell, decode into a temporary file, and
+    atomically move the temp file into place after the complete upload succeeds.
+    """
+
+    connected = connect_ssh(config, lambda _level, _message, _details=None: None)
+    client = connected.client
+    remote_dir = posixpath.dirname(remote_path) or "."
+    temp_path = posixpath.join(remote_dir, f".py-web-ssh-upload-{uuid.uuid4().hex}.tmp")
+    command = _upload_command(remote_dir, temp_path, remote_path)
+    stdin = stdout = stderr = None
+    transferred = 0
+    try:
+        stdin, stdout, stderr = client.exec_command(f"sh -c {shlex.quote(command)}")
+        while True:
+            if cancel_event and cancel_event.is_set():
+                raise FileTransferCancelled("Upload cancelled by client.")
+            chunk = source.read(48 * 1024)
+            if not chunk:
+                break
+            transferred += len(chunk)
+            stdin.write(base64.b64encode(chunk).decode("ascii"))
+            stdin.write("\n")
+            stdin.flush()
+            if progress:
+                progress(transferred)
+
+        if cancel_event and cancel_event.is_set():
+            raise FileTransferCancelled("Upload cancelled by client.")
+
+        stdin.channel.shutdown_write()
+        exit_code = stdout.channel.recv_exit_status()
+        error_text = stderr.read().decode("utf-8", errors="replace")
+    except FileTransferCancelled:
+        _close_transport(client)
+        raise
+    except Exception as exc:
+        _close_transport(client)
+        raise FileTransferError(f"SSH shell upload failed: {exc}") from exc
+    finally:
+        for stream in (stdin, stdout, stderr):
+            if stream is not None:
+                try:
+                    stream.close()
+                except Exception:
+                    pass
+        client.close()
+
+    if exit_code != 0:
+        raise FileTransferError(f"Remote upload command failed with exit code {exit_code}: {error_text}")
+    if size is not None and transferred != size:
+        raise FileTransferError(f"Uploaded {transferred} bytes, expected {size} bytes.")
+    return "shell", transferred
+
+
+def download_file_via_ssh(config: ConnectRequest, remote_path: str) -> tuple[str, Iterator[bytes]]:
+    connected = connect_ssh(config, lambda _level, _message, _details=None: None)
+    client = connected.client
+    command = f"base64 < {shlex.quote(remote_path)}"
+    stdin, stdout, stderr = client.exec_command(f"sh -c {shlex.quote(command)}")
+    stdin.close()
+
+    def iterator() -> Iterator[bytes]:
+        buffered = b""
+        try:
+            while True:
+                chunk = stdout.channel.recv(64 * 1024)
+                if not chunk:
+                    break
+                buffered += b"".join(chunk.split())
+                keep = len(buffered) % 4
+                ready = buffered[:-keep] if keep else buffered
+                buffered = buffered[-keep:] if keep else b""
+                if ready:
+                    yield base64.b64decode(ready)
+            if buffered:
+                yield base64.b64decode(buffered)
+            exit_code = stdout.channel.recv_exit_status()
+            error_text = stderr.read().decode("utf-8", errors="replace")
+            if exit_code != 0:
+                raise FileTransferError(
+                    f"Remote download command failed with exit code {exit_code}: {error_text}"
+                )
+        except binascii.Error as exc:
+            raise FileTransferError(f"Remote command returned invalid base64: {exc}") from exc
+        finally:
+            stdout.close()
+            stderr.close()
+            client.close()
+
+    return "shell", iterator()
+
+
+def _upload_command(remote_dir: str, temp_path: str, remote_path: str) -> str:
+    quoted_temp = shlex.quote(temp_path)
+    return "\n".join(
+        [
+            "set -e",
+            f"mkdir -p -- {shlex.quote(remote_dir)}",
+            f"tmp={quoted_temp}",
+            "cleanup() { rm -f -- \"$tmp\"; }",
+            "trap cleanup EXIT HUP INT TERM",
+            f"if printf '' | base64 -d >/dev/null 2>&1; then base64 -d > {quoted_temp}; "
+            f"else base64 -D > {quoted_temp}; fi",
+            f"mv -- {quoted_temp} {shlex.quote(remote_path)}",
+            "trap - EXIT",
+        ]
+    )
+
+
+def _close_transport(client) -> None:
+    try:
+        transport = client.get_transport()
+        if transport is not None:
+            transport.close()
+    except Exception:
+        pass
+    try:
+        client.close()
+    except Exception:
+        pass
+
+
+def filename_for_download(remote_path: str) -> str:
+    name = posixpath.basename(remote_path.rstrip("/")) or "download.bin"
+    return os.path.basename(name)

{py_web_ssh-0.1.4 → py_web_ssh-0.1.6}/webssh/models.py

@@ -70,7 +70,8 @@ class SessionSummary(BaseModel):
 
 class FileTransferResponse(BaseModel):
     ok: bool
-    method: Literal["sftp", "shell"]
+    method: Literal["shell"]
     bytes_transferred: int
     remote_path: str
     message: str
+    transfer_id: str | None = None

py_web_ssh-0.1.6/webssh/runtime_config.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastapi import HTTPException
+
+from .models import ConnectRequest
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    lock_host: str | None = None
+    lock_username: str | None = None
+    lock_password: str | None = None
+    lock_private_key_path: Path | None = None
+
+    @property
+    def lock_password_enabled(self) -> bool:
+        return self.lock_password is not None
+
+    @property
+    def lock_private_key_enabled(self) -> bool:
+        return self.lock_private_key_path is not None
+
+    def public_payload(self) -> dict[str, object]:
+        return {
+            "locks": {
+                "host": {"enabled": self.lock_host is not None, "value": self.lock_host},
+                "username": {"enabled": self.lock_username is not None, "value": self.lock_username},
+                "password": {"enabled": self.lock_password_enabled},
+                "private_key": {"enabled": self.lock_private_key_enabled},
+            }
+        }
+
+    def apply_to_connect_request(self, incoming: ConnectRequest) -> ConnectRequest:
+        data = incoming.model_dump()
+
+        if self.lock_host is not None:
+            requested = str(data.get("host") or "").strip()
+            if requested and requested != self.lock_host:
+                raise HTTPException(status_code=403, detail="Host is locked by the server.")
+            data["host"] = self.lock_host
+
+        if self.lock_username is not None:
+            requested = str(data.get("username") or "").strip()
+            if requested and requested != self.lock_username:
+                raise HTTPException(status_code=403, detail="Username is locked by the server.")
+            data["username"] = self.lock_username
+
+        if self.lock_password is not None:
+            data["password"] = self.lock_password
+
+        if self.lock_private_key_path is not None:
+            data["private_key"] = _read_locked_private_key(self.lock_private_key_path)
+
+        return ConnectRequest.model_validate(data)
+
+
+runtime_config = RuntimeConfig()
+
+
+def configure_runtime_locks(
+    *,
+    lock_host: str | None = None,
+    lock_username: str | None = None,
+    lock_password: str | None = None,
+    lock_private_key: str | None = None,
+) -> None:
+    global runtime_config
+    key_path = Path(lock_private_key).expanduser().resolve() if lock_private_key else None
+    if key_path is not None:
+        _read_locked_private_key(key_path)
+    runtime_config = RuntimeConfig(
+        lock_host=_blank_to_none(lock_host),
+        lock_username=_blank_to_none(lock_username),
+        lock_password=lock_password if lock_password is not None else None,
+        lock_private_key_path=key_path,
+    )
+
+
+def add_runtime_lock_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--lock-host",
+        default=None,
+        metavar="HOST",
+        help="Only allow SSH connections to this host or domain.",
+    )
+    parser.add_argument(
+        "--lock-username",
+        default=None,
+        metavar="USERNAME",
+        help="Only allow SSH connections with this username.",
+    )
+    parser.add_argument(
+        "--lock-pwd",
+        default=None,
+        metavar="PASSWORD",
+        help="Bind this SSH password server-side. It is never sent to the browser.",
+    )
+    parser.add_argument(
+        "--lock-private-key",
+        default=None,
+        metavar="KEY_FILE",
+        help="Bind this server-side SSH private key file. It is never sent to the browser.",
+    )
+
+
+def _read_locked_private_key(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"Could not read locked private key file {path}: {exc}") from exc
+
+
+def _blank_to_none(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None