py-web-ssh 0.1.0__tar.gz → 0.1.2__tar.gz

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-web-ssh
-Version: 0.1.0
+Version: 0.1.2
 Summary: A Python web SSH client with xterm.js, reconnectable sessions, logs, and file transfer.
 License-Expression: MIT
 License-File: LICENSE
@@ -34,6 +34,7 @@ Description-Content-Type: text/markdown
 - 终端恢复：服务端保存 SSH 输出流，浏览器定期回传 xterm serialize 快照；重连时先恢复快照，再补放快照之后的输出。
 - 日志页面：`/sessions/{uuid}/logs` 展示完整连接、认证、错误和文件传输日志。
 - 文件传输：优先 SFTP；SFTP 不可用时参考 `simple-ssh-copy` 思路，使用远端 `base64` shell 命令 fallback 上传/下载。
+- 可选 PIN 门禁：服务端传入 `--pin` 后，网页启动时必须先输入正确 PIN；验证成功后浏览器会保存加盐哈希 cookie，后端会保护 HTTP API、日志页面、文件接口和 WebSocket。
 
 ## 安装
 
@@ -52,10 +53,16 @@ py-web-ssh
 或者：
 
 ```bash
-uvicorn webssh.app:app --host 127.0.0.1 --port 8000
+uvicorn webssh.app:app --host 0.0.0.0 --port 8022
 ```
 
-打开 <http://127.0.0.1:8000>。
+打开 <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 地址。
 

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/README.md

@@ -1,52 +1,59 @@
-# py-web-ssh
-
-一个基于 Python/FastAPI/Paramiko 的 Web SSH 客户端。前端使用 xterm.js 渲染真实终端控制序列，后端通过 WebSocket 转发 SSH 交互数据，并为每个网页客户端分配随机 UUID，支持同 UUID 断线重连、终端快照恢复、日志查看和文件上传下载。
-
-## 功能
-
-- SSH 交互终端：Paramiko 后端 `invoke_shell`，xterm.js 前端实时交互。
-- 登录方式：密码、浏览器上传私钥、私钥口令、SSH agent、服务端本机 `~/.ssh` 密钥、免口令/none auth。
-- Legacy 兼容：启动时按当前 Paramiko 运行时能力尽量启用旧 KEX/Cipher/MAC/HostKey/Pubkey 算法，并在日志中列出不可用算法。
-- UUID 会话：创建会话后返回 UUID，WebSocket 断开后可用同 UUID 重连。
-- 会话回收：同一个 UUID 如果所有浏览器连接都断开并且 5 分钟内无人重连，服务端会主动断开 SSH 并清理内存缓存。
-- 终端恢复：服务端保存 SSH 输出流，浏览器定期回传 xterm serialize 快照；重连时先恢复快照，再补放快照之后的输出。
-- 日志页面：`/sessions/{uuid}/logs` 展示完整连接、认证、错误和文件传输日志。
-- 文件传输：优先 SFTP；SFTP 不可用时参考 `simple-ssh-copy` 思路，使用远端 `base64` shell 命令 fallback 上传/下载。
-
-## 安装
-
-```bash
-python -m venv .venv
-.venv\Scripts\activate
-pip install -e .
-```
-
-## 启动
-
-```bash
-py-web-ssh
-```
-
-或者：
-
-```bash
-uvicorn webssh.app:app --host 127.0.0.1 --port 8000
-```
-
-打开 <http://127.0.0.1:8000>。
-
-前端默认从 jsDelivr 加载 xterm.js、fit addon 和 serialize addon。离线内网部署时，请把这些静态资源 vendoring 到 `webssh/static/` 并替换 `index.html` 里的 CDN 地址。
-
-## API 概览
-
-- `POST /api/sessions` 创建 SSH 会话。
-- `GET /api/sessions/{uuid}` 查看会话状态。
-- `GET /api/sessions/{uuid}/logs` 获取完整日志 JSON。
-- `DELETE /api/sessions/{uuid}` 主动断开 SSH。
-- `WS /ws/sessions/{uuid}` 终端输入、输出、resize、快照和断开控制。
-- `POST /api/sessions/{uuid}/files/upload` 上传文件，multipart 字段：`remote_path`、`file`。
-- `GET /api/sessions/{uuid}/files/download?remote_path=/path/file` 下载远端文件。
-
-## 安全提示
-
-这个项目默认面向可信内网或本机使用。私钥和口令只保存在进程内存中，不写入日志；如果要暴露到公网，请务必加 HTTPS、登录认证、CSRF/来源限制、审计和会话回收策略。
+# py-web-ssh
+
+一个基于 Python/FastAPI/Paramiko 的 Web SSH 客户端。前端使用 xterm.js 渲染真实终端控制序列，后端通过 WebSocket 转发 SSH 交互数据，并为每个网页客户端分配随机 UUID，支持同 UUID 断线重连、终端快照恢复、日志查看和文件上传下载。
+
+## 功能
+
+- SSH 交互终端：Paramiko 后端 `invoke_shell`，xterm.js 前端实时交互。
+- 登录方式：密码、浏览器上传私钥、私钥口令、SSH agent、服务端本机 `~/.ssh` 密钥、免口令/none auth。
+- Legacy 兼容：启动时按当前 Paramiko 运行时能力尽量启用旧 KEX/Cipher/MAC/HostKey/Pubkey 算法，并在日志中列出不可用算法。
+- UUID 会话：创建会话后返回 UUID，WebSocket 断开后可用同 UUID 重连。
+- 会话回收：同一个 UUID 如果所有浏览器连接都断开并且 5 分钟内无人重连，服务端会主动断开 SSH 并清理内存缓存。
+- 终端恢复：服务端保存 SSH 输出流，浏览器定期回传 xterm serialize 快照；重连时先恢复快照，再补放快照之后的输出。
+- 日志页面：`/sessions/{uuid}/logs` 展示完整连接、认证、错误和文件传输日志。
+- 文件传输：优先 SFTP；SFTP 不可用时参考 `simple-ssh-copy` 思路，使用远端 `base64` shell 命令 fallback 上传/下载。
+- 可选 PIN 门禁：服务端传入 `--pin` 后，网页启动时必须先输入正确 PIN；验证成功后浏览器会保存加盐哈希 cookie，后端会保护 HTTP API、日志页面、文件接口和 WebSocket。
+
+## 安装
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e .
+```
+
+## 启动
+
+```bash
+py-web-ssh
+```
+
+或者：
+
+```bash
+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 会话。
+- `GET /api/sessions/{uuid}` 查看会话状态。
+- `GET /api/sessions/{uuid}/logs` 获取完整日志 JSON。
+- `DELETE /api/sessions/{uuid}` 主动断开 SSH。
+- `WS /ws/sessions/{uuid}` 终端输入、输出、resize、快照和断开控制。
+- `POST /api/sessions/{uuid}/files/upload` 上传文件，multipart 字段：`remote_path`、`file`。
+- `GET /api/sessions/{uuid}/files/download?remote_path=/path/file` 下载远端文件。
+
+## 安全提示
+
+这个项目默认面向可信内网或本机使用。私钥和口令只保存在进程内存中，不写入日志；如果要暴露到公网，请务必加 HTTPS、登录认证、CSRF/来源限制、审计和会话回收策略。

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "py-web-ssh"
-version = "0.1.0"
+version = "0.1.2"
 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.0 → py_web_ssh-0.1.2}/webssh/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/webssh/app.py

@@ -2,13 +2,17 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import argparse
 from pathlib import Path
 from typing import Annotated
 
-from fastapi import FastAPI, File, Form, HTTPException, UploadFile, WebSocket, WebSocketDisconnect
+from fastapi import FastAPI, File, Form, HTTPException, Request, UploadFile, WebSocket, WebSocketDisconnect
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 
+from . import __version__
+from . import auth
+from .auth import add_pin_argument, configure_pin
 from .files import download_file, filename_for_download, upload_file
 from .models import ConnectRequest, CreateSessionResponse, FileTransferResponse
 from .session import SessionManager
@@ -16,17 +20,44 @@ from .session import SessionManager
 
 BASE_DIR = Path(__file__).resolve().parent
 STATIC_DIR = BASE_DIR / "static"
+PUBLIC_PATHS = {"/", "/api/auth/status", "/api/auth/login", "/favicon.ico"}
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_PORT = 8022
 
-app = FastAPI(title="py-web-ssh", version="0.1.0")
+app = FastAPI(title="py-web-ssh", version=__version__)
 app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 sessions = SessionManager()
 
 
+@app.middleware("http")
+async def require_pin_cookie(request: Request, call_next):
+    path = request.url.path
+    if path.startswith("/static/") or path in PUBLIC_PATHS or auth.pin_auth.is_request_authorized(request):
+        return await call_next(request)
+    return JSONResponse({"detail": "PIN authentication required."}, status_code=401)
+
+
 @app.get("/", response_class=HTMLResponse)
 def index() -> FileResponse:
     return FileResponse(STATIC_DIR / "index.html")
 
 
+@app.get("/api/auth/status")
+def auth_status() -> JSONResponse:
+    return JSONResponse(auth.pin_auth.status_payload())
+
+
+@app.post("/api/auth/login")
+async def auth_login(request: Request) -> JSONResponse:
+    payload = await request.json()
+    pin = str(payload.get("pin", ""))
+    if not auth.pin_auth.verify_pin(pin):
+        raise HTTPException(status_code=401, detail="Invalid PIN.")
+    response = JSONResponse({"ok": True, "enabled": auth.pin_auth.enabled})
+    auth.pin_auth.set_cookie(response, pin)
+    return response
+
+
 @app.get("/sessions/{session_id}/logs", response_class=HTMLResponse)
 def logs_page(session_id: str) -> HTMLResponse:
     html = (STATIC_DIR / "logs.html").read_text(encoding="utf-8")
@@ -121,6 +152,10 @@ def download(session_id: str, remote_path: str) -> StreamingResponse:
 
 @app.websocket("/ws/sessions/{session_id}")
 async def websocket_session(websocket: WebSocket, session_id: str) -> None:
+    if not auth.pin_auth.is_websocket_authorized(websocket):
+        await websocket.close(code=4401, reason="PIN authentication required")
+        return
+
     session = sessions.get(session_id)
     if session is None:
         await websocket.close(code=4404, reason="Session not found")
@@ -190,10 +225,21 @@ def _content_length(upload: UploadFile) -> int | None:
     return None
 
 
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="py-web-ssh")
+    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)
+    return parser
+
+
 def main() -> None:
     import uvicorn
 
-    uvicorn.run("webssh.app:app", host="127.0.0.1", port=8000, reload=False)
+    args = build_arg_parser().parse_args()
+
+    configure_pin(args.pin)
+    uvicorn.run("webssh.app:app", host=args.host, port=args.port, reload=False)
 
 
 if __name__ == "__main__":

py_web_ssh-0.1.2/webssh/auth.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import hmac
+import secrets
+from dataclasses import dataclass
+
+from fastapi import HTTPException, Request, Response, WebSocket
+
+
+COOKIE_NAME = "py_web_ssh_pin"
+
+
+@dataclass
+class PinAuth:
+    pin_hash: str | None = None
+    secret: str = ""
+
+    @classmethod
+    def disabled(cls) -> "PinAuth":
+        return cls(pin_hash=None, secret=secrets.token_hex(32))
+
+    @classmethod
+    def from_pin(cls, pin: str | None) -> "PinAuth":
+        if not pin:
+            return cls.disabled()
+        return cls(pin_hash=_hash_pin(pin), secret=secrets.token_hex(32))
+
+    @property
+    def enabled(self) -> bool:
+        return self.pin_hash is not None
+
+    def status_payload(self) -> dict[str, bool]:
+        return {"enabled": self.enabled}
+
+    def verify_pin(self, pin: str) -> bool:
+        if not self.enabled:
+            return True
+        return hmac.compare_digest(_hash_pin(pin), self.pin_hash or "")
+
+    def set_cookie(self, response: Response, pin: str) -> None:
+        if not self.enabled:
+            return
+        salt = secrets.token_hex(16)
+        digest = _hash_with_salt(pin, salt)
+        signature = self._signature(salt, digest)
+        response.set_cookie(
+            COOKIE_NAME,
+            f"{salt}:{digest}:{signature}",
+            httponly=True,
+            samesite="lax",
+            secure=False,
+            path="/",
+            max_age=7 * 24 * 60 * 60,
+        )
+
+    def clear_cookie(self, response: Response) -> None:
+        response.delete_cookie(COOKIE_NAME, path="/")
+
+    def is_request_authorized(self, request: Request) -> bool:
+        if not self.enabled:
+            return True
+        return self._valid_cookie(request.cookies.get(COOKIE_NAME))
+
+    def is_websocket_authorized(self, websocket: WebSocket) -> bool:
+        if not self.enabled:
+            return True
+        return self._valid_cookie(websocket.cookies.get(COOKIE_NAME))
+
+    def require_request(self, request: Request) -> None:
+        if not self.is_request_authorized(request):
+            raise HTTPException(status_code=401, detail="PIN authentication required.")
+
+    def _valid_cookie(self, value: str | None) -> bool:
+        if not value:
+            return False
+        try:
+            salt, digest, signature = value.split(":", 2)
+        except ValueError:
+            return False
+        if not hmac.compare_digest(signature, self._signature(salt, digest)):
+            return False
+        for candidate_pin_hash in [self.pin_hash]:
+            if candidate_pin_hash and hmac.compare_digest(digest, _rehash_pin_hash(candidate_pin_hash, salt)):
+                return True
+        return False
+
+    def _signature(self, salt: str, digest: str) -> str:
+        return hmac.new(
+            self.secret.encode("utf-8"),
+            f"{salt}:{digest}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+
+pin_auth = PinAuth.disabled()
+
+
+def configure_pin(pin: str | None) -> None:
+    global pin_auth
+    pin_auth = PinAuth.from_pin(pin)
+
+
+def add_pin_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--pin",
+        default=None,
+        help="Require this PIN before the web client can access SSH APIs.",
+    )
+
+
+def _hash_pin(pin: str) -> str:
+    return hashlib.sha256(pin.encode("utf-8")).hexdigest()
+
+
+def _hash_with_salt(pin: str, salt: str) -> str:
+    return _rehash_pin_hash(_hash_pin(pin), salt)
+
+
+def _rehash_pin_hash(pin_hash: str, salt: str) -> str:
+    return hashlib.sha256(f"{salt}:{pin_hash}".encode("utf-8")).hexdigest()

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/webssh/static/app.js

@@ -4,6 +4,10 @@ const statusElement = document.querySelector("#status");
 const sessionInput = document.querySelector("#session-id");
 const sessionLabel = document.querySelector("#session-label");
 const logsLink = document.querySelector("#logs-link");
+const pinGate = document.querySelector("#pin-gate");
+const pinForm = document.querySelector("#pin-form");
+const pinInput = document.querySelector("#pin-input");
+const pinError = document.querySelector("#pin-error");
 
 const term = new Terminal({
   cursorBlink: true,
@@ -51,6 +55,8 @@ if (activeSessionId) {
   updateSessionUi(activeSessionId);
 }
 
+checkPinGate();
+
 window.addEventListener("resize", () => {
   fitAddon.fit();
   sendResize();
@@ -100,6 +106,24 @@ document.querySelector("#connect-form").addEventListener("submit", async (event)
   connectWebSocket(activeSessionId);
 });
 
+pinForm.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  pinError.textContent = "";
+  const response = await fetch("/api/auth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ pin: pinInput.value }),
+  });
+  if (!response.ok) {
+    pinError.textContent = "Invalid PIN.";
+    pinInput.select();
+    return;
+  }
+  pinInput.value = "";
+  pinGate.classList.add("hidden");
+  setStatus("Ready");
+});
+
 document.querySelector("#reconnect").addEventListener("click", () => {
   const id = sessionInput.value.trim();
   if (id) {
@@ -183,13 +207,29 @@ function connectWebSocket(sessionId) {
   });
   socket.addEventListener("close", () => {
     if (ws !== socket) return;
-    setStatus("WebSocket 已断开，可重连");
+    setStatus("WebSocket closed; reconnect is available");
   });
   socket.addEventListener("error", () => {
     if (ws === socket) setStatus("WebSocket 错误");
   });
 }
 
+async function checkPinGate() {
+  const response = await fetch("/api/auth/status");
+  if (!response.ok) {
+    pinGate.classList.remove("hidden");
+    pinInput.focus();
+    return;
+  }
+  const status = await response.json();
+  if (status.enabled) {
+    pinGate.classList.remove("hidden");
+    pinInput.focus();
+  } else {
+    pinGate.classList.add("hidden");
+  }
+}
+
 async function handleMessage(message) {
   if (message.type === "session") {
     appendLogLine(`绑定会话 ${message.session_id}`);

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/webssh/static/index.html

@@ -8,6 +8,17 @@
     <link rel="stylesheet" href="/static/styles.css" />
   </head>
   <body>
+    <div id="pin-gate" class="pin-gate" aria-live="polite">
+      <form id="pin-form" class="pin-box">
+        <h2>PIN required</h2>
+        <label>
+          PIN
+          <input id="pin-input" type="password" autocomplete="current-password" />
+        </label>
+        <button class="primary" type="submit">Unlock</button>
+        <p id="pin-error" class="pin-error"></p>
+      </form>
+    </div>
     <main class="app-shell">
       <aside class="sidebar">
         <header class="brand">

{py_web_ssh-0.1.0 → py_web_ssh-0.1.2}/webssh/static/styles.css

@@ -24,6 +24,42 @@ body {
     Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 }
 
+.pin-gate {
+  position: fixed;
+  inset: 0;
+  z-index: 10;
+  display: grid;
+  place-items: center;
+  background: rgba(10, 14, 18, 0.92);
+  padding: 20px;
+}
+
+.pin-gate.hidden {
+  display: none;
+}
+
+.pin-box {
+  display: grid;
+  width: min(360px, 100%);
+  gap: 14px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  padding: 18px;
+}
+
+.pin-box h2 {
+  margin: 0;
+  font-size: 18px;
+}
+
+.pin-error {
+  min-height: 18px;
+  margin: 0;
+  color: var(--danger);
+  font-size: 13px;
+}
+
 button,
 input {
   font: inherit;