webgate 0.3.2__tar.gz → 0.4.0__tar.gz

{webgate-0.3.2 → webgate-0.4.0}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## v0.4.0 (2026-04-15)
+
+### Features
+
+- **Shared terminal sessions** -- the killer feature. The owner of an active SSH terminal can click **🔗 Share** to mint a one-time URL; anyone they send it to can join the same live session. Output is broadcast to every participant, and any RW participant can type. Useful for pair debugging in production, onboarding juniors, or remote support.
+  - Backend: new `SharedSession` registry holds one `asyncssh` process per session and broadcasts its PTY output to N WebSockets. `_client_input_loop` multiplexes input from any RW client into the same `stdin`.
+  - Endpoints: `POST /api/terminal/share/{session_id}` mints/returns the token, `DELETE` revokes, `WS /api/ws/terminal/join/{token}?mode=rw|ro` attaches a joiner.
+  - Frontend: **🔗 Share** button copies the URL to clipboard; toolbar shows `👥 joined (rw|ro)` for participants. Pasting `?join=<token>` into the URL after login auto-attaches.
+  - Demo middleware whitelists `/api/terminal/share/*` so the public demo can showcase the feature.
+
+### Verified
+
+End-to-end with two browser sessions against the local container:
+
+- Owner opens SSH to `bastion`, clicks Share → token minted, URL copied
+- Joiner navigates to `?join=<token>` → "Joined session of demo on bastion (rw)"
+- Joiner types `echo HELLO_FROM_JOINER` → output appears in BOTH terminals
+- Owner types `uname -n` → output appears in BOTH terminals
+
+---
+
+## v0.3.3 (2026-04-15)
+
+### Fixed
+
+- Snippets toolbar was empty after a fresh login until the page was reloaded. `loadSnippets()` was only called from `init()` (which only runs when a token is already in localStorage). Now also called after a successful login and after a forced password change.
+
+### Docs
+
+- Added end-to-end UI screenshots for v0.3.x features: jump host, snippets toolbar, snippet execution, SFTP browse via jump, webhooks management modal with delivery telemetry, server form with Jump Via dropdown.
+- Browser-tested every UI flow with `playwright-cli` against both the live Fly.io demo and a local container.
+
+---
+
 ## v0.3.2 (2026-04-15)
 
 ### Features

{webgate-0.3.2 → webgate-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webgate
-Version: 0.3.2
+Version: 0.4.0
 Summary: Self-hosted web application for remote server management via SSH terminal and SFTP file browser
 Project-URL: Homepage, https://github.com/kalexnolasco/webgate
 Project-URL: Documentation, https://kalexnolasco.github.io/webgate/
@@ -242,6 +242,53 @@ flowchart TB
 ### Light Theme
 ![Light Theme](docs/screenshots/light-theme.png)
 
+### v0.4.0 — Shared Terminal Sessions
+
+Pair-debugging or onboarding from anywhere: the owner clicks **🔗 Share** in the terminal toolbar, copies the URL, and any colleague who opens it joins the same live session. Output is broadcast to every participant; any RW participant can type.
+
+| Owner | Joiner |
+| --- | --- |
+| ![Owner view](docs/screenshots/v0.4/01-shared-terminal-owner.png) | ![Joiner view](docs/screenshots/v0.4/02-shared-terminal-joiner.png) |
+
+The `?join=<token>` URL parameter is recognized after login -- a joiner can be sent the URL directly even if they aren't logged in yet.
+
+### v0.3.x — Operations Pack
+
+These screenshots come from the live demo at https://webgate-demo.fly.dev (login `demo` / `demo`).
+
+#### Demo banner on login
+![Demo banner](docs/screenshots/v0.3/01-login-demo-banner.png)
+
+#### Site Manager with jump-host indicator
+The `↺` next to `internal-app` means it tunnels through `bastion`.
+
+![Dashboard with jump host](docs/screenshots/v0.3/02-dashboard-jump-host.png)
+
+#### Terminal with snippets toolbar
+Click a snippet button to send `command + Enter` to the active session. Right-click to delete, `+` to create.
+
+![Terminal snippets](docs/screenshots/v0.3/03-terminal-snippets-jump.png)
+
+#### Snippet executed
+Clicking `ls -lah` sent the command and the output appears in the terminal.
+
+![Snippet executed](docs/screenshots/v0.3/04-snippet-executed.png)
+
+#### SFTP via jump host
+Browsing the `internal-app` filesystem — the SFTP connection is also tunneled through the bastion.
+
+![SFTP via jump](docs/screenshots/v0.3/05-sftp-via-jump.png)
+
+#### Webhooks management (admin)
+Per-event subscription, optional HMAC signing, last delivery status.
+
+![Webhooks modal](docs/screenshots/v0.3/06-webhooks-modal.png)
+
+#### Add Server form with Jump Via dropdown
+Pick any other registered server as the bastion.
+
+![Add Server with Jump Via](docs/screenshots/v0.3/08-add-server-jump-via.png)
+
 ## Quick Start
 
 ### Docker (recommended)

{webgate-0.3.2 → webgate-0.4.0}/README.md

@@ -194,6 +194,53 @@ flowchart TB
 ### Light Theme
 ![Light Theme](docs/screenshots/light-theme.png)
 
+### v0.4.0 — Shared Terminal Sessions
+
+Pair-debugging or onboarding from anywhere: the owner clicks **🔗 Share** in the terminal toolbar, copies the URL, and any colleague who opens it joins the same live session. Output is broadcast to every participant; any RW participant can type.
+
+| Owner | Joiner |
+| --- | --- |
+| ![Owner view](docs/screenshots/v0.4/01-shared-terminal-owner.png) | ![Joiner view](docs/screenshots/v0.4/02-shared-terminal-joiner.png) |
+
+The `?join=<token>` URL parameter is recognized after login -- a joiner can be sent the URL directly even if they aren't logged in yet.
+
+### v0.3.x — Operations Pack
+
+These screenshots come from the live demo at https://webgate-demo.fly.dev (login `demo` / `demo`).
+
+#### Demo banner on login
+![Demo banner](docs/screenshots/v0.3/01-login-demo-banner.png)
+
+#### Site Manager with jump-host indicator
+The `↺` next to `internal-app` means it tunnels through `bastion`.
+
+![Dashboard with jump host](docs/screenshots/v0.3/02-dashboard-jump-host.png)
+
+#### Terminal with snippets toolbar
+Click a snippet button to send `command + Enter` to the active session. Right-click to delete, `+` to create.
+
+![Terminal snippets](docs/screenshots/v0.3/03-terminal-snippets-jump.png)
+
+#### Snippet executed
+Clicking `ls -lah` sent the command and the output appears in the terminal.
+
+![Snippet executed](docs/screenshots/v0.3/04-snippet-executed.png)
+
+#### SFTP via jump host
+Browsing the `internal-app` filesystem — the SFTP connection is also tunneled through the bastion.
+
+![SFTP via jump](docs/screenshots/v0.3/05-sftp-via-jump.png)
+
+#### Webhooks management (admin)
+Per-event subscription, optional HMAC signing, last delivery status.
+
+![Webhooks modal](docs/screenshots/v0.3/06-webhooks-modal.png)
+
+#### Add Server form with Jump Via dropdown
+Pick any other registered server as the bastion.
+
+![Add Server with Jump Via](docs/screenshots/v0.3/08-add-server-jump-via.png)
+
 ## Quick Start
 
 ### Docker (recommended)

webgate-0.4.0/after-reload.yaml

@@ -0,0 +1,64 @@
+- generic [ref=e2]:
+  - generic [ref=e3]:
+    - text: 🎮
+    - strong [ref=e4]: Demo mode
+    - text: — login with
+    - code [ref=e5]: demo
+    - text: /
+    - code [ref=e6]: demo
+    - text: · read-only (servers cannot be added or modified) · state resets hourly ·
+    - link "GitHub" [ref=e7] [cursor=pointer]:
+      - /url: https://github.com/kalexnolasco/webgate
+  - generic [ref=e8]:
+    - generic [ref=e9]:
+      - generic [ref=e10]:
+        - generic [ref=e11]: webgate
+        - button "Site Manager" [ref=e12] [cursor=pointer]
+        - button "Keys" [ref=e13] [cursor=pointer]
+      - generic [ref=e14]:
+        - generic [ref=e15]: demo
+        - 'button "2FA: Off" [ref=e16] [cursor=pointer]'
+        - button "☀️" [ref=e17] [cursor=pointer]
+        - button "Logout" [ref=e18] [cursor=pointer]
+    - generic [ref=e19]:
+      - generic [ref=e20]: "Host:"
+      - textbox "hostname" [ref=e21]
+      - generic [ref=e22]: "Username:"
+      - textbox "user" [ref=e23]
+      - generic [ref=e24]: "Password:"
+      - textbox [ref=e25]
+      - generic [ref=e26]: "Port:"
+      - spinbutton [ref=e27]: "22"
+      - button "Quickconnect ▶" [ref=e28] [cursor=pointer]
+    - generic [ref=e29]:
+      - generic [ref=e51]: 8:17:34 PM Connecting to 127.0.0.1:22...
+      - generic [ref=e52]: 8:17:34 PM webgate initialized
+      - generic [ref=e53]: "8:17:34 PM Connected: internal-app"
+    - generic [ref=e31]:
+      - generic [ref=e32] [cursor=pointer]: 💻 Site Manager
+      - generic [ref=e54] [cursor=pointer]:
+        - generic [ref=e55]: ⌨ internal-app
+        - generic [ref=e56]: ×
+    - generic [ref=e58]:
+      - generic [ref=e59]:
+        - generic [ref=e60]: "Snippets:"
+        - button "disk usage" [ref=e61] [cursor=pointer]
+        - button "ls -lah" [ref=e62] [cursor=pointer]
+        - button "top procs" [ref=e63] [cursor=pointer]
+        - button "uptime" [ref=e64] [cursor=pointer]
+        - button "+" [ref=e65] [cursor=pointer]
+      - generic [ref=e69]:
+        - textbox "Terminal input" [ref=e70]
+        - generic [ref=e71]:
+          - generic [ref=e73]: "Linux 1853454a533968 6.12.47-fly #1 SMP PREEMPT_DYNAMIC Wed Mar 25 00:13:15 UTC 2026 x86_64"
+          - generic [ref=e76]: The programs included with the Debian GNU/Linux system are free software;
+          - generic [ref=e78]: the exact distribution terms for each program are described in the
+          - generic [ref=e80]: individual files in /usr/share/doc/*/copyright.
+          - generic [ref=e83]: Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
+          - generic [ref=e85]: permitted by applicable law.
+          - generic [ref=e86]:
+            - generic [ref=e87]: demo@1853454a533968
+            - generic [ref=e88]: ":"
+            - generic [ref=e89]: ~
+            - generic [ref=e90]: $
+    - generic [ref=e50]: "SSH: internal-app"

{webgate-0.3.2 → webgate-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webgate"
-version = "0.3.2"
+version = "0.4.0"
 description = "Self-hosted web application for remote server management via SSH terminal and SFTP file browser"
 readme = "README.md"
 license = "MIT"

{webgate-0.3.2 → webgate-0.4.0}/src/webgate/app.py

@@ -75,7 +75,10 @@ def create_app() -> FastAPI:
         @app.middleware("http")
         async def _demo_readonly(request: Request, call_next):  # pyright: ignore[reportUnusedFunction]
             path = request.url.path
-            if request.method in WRITE_METHODS and path.startswith("/api/") and path not in WRITE_ALLOWLIST:
+            # Allow share-token mint/revoke even in demo mode so the shared
+            # terminal feature can be exercised from the public demo.
+            allowed = path in WRITE_ALLOWLIST or path.startswith("/api/terminal/share/")
+            if request.method in WRITE_METHODS and path.startswith("/api/") and not allowed:
                 return JSONResponse(
                     status_code=403,
                     content={"detail": "Demo mode: write operations are disabled"},

{webgate-0.3.2 → webgate-0.4.0}/src/webgate/static/index.html

@@ -358,6 +358,9 @@ window._showToastImpl = function(message, type) {
                             <button @click="runSnippet(tab, s)" @contextmenu.prevent="confirmDeleteSnippet(s)" class="fz-btn" style="font-size:11px;padding:2px 8px" :title="(s.description || s.command) + ' (right-click to delete)'" x-text="s.name"></button>
                         </template>
                         <button @click="promptNewSnippet()" class="fz-btn" style="font-size:11px;padding:2px 8px" title="Create new snippet">+</button>
+                        <span style="flex:1"></span>
+                        <button x-show="tab._sessionId && !tab._isJoined" @click="shareSession(tab)" class="fz-btn" style="font-size:11px;padding:2px 8px" :style="tab._shareToken ? 'color:var(--success);border-color:var(--success)' : ''" :title="tab._shareToken ? 'Click to copy URL again' : 'Generate a share URL for this session'" x-text="tab._shareToken ? '🔗 Shared' : '🔗 Share'"></button>
+                        <span x-show="tab._isJoined" style="font-size:11px;color:var(--accent)" :title="'Joined session as ' + (tab._joinMode || 'rw')" x-text="'👥 joined (' + (tab._joinMode || 'rw') + ')'"></span>
                     </div>
                     <div style="flex:1;min-height:0" :id="tab.id"></div>
                 </div>
@@ -963,12 +966,21 @@ function app() {
         async init() {
             document.documentElement.dataset.theme = this.theme;
             try { const cfg = await this.apiCall('/api/config'); this.demoMode = !!cfg.demo_mode; } catch {}
+            // Pick up ?join=<token>[&mode=ro|rw] from the URL after auth
+            const params = new URLSearchParams(location.search);
+            this._pendingJoinToken = params.get('join');
+            this._pendingJoinMode = params.get('mode') === 'ro' ? 'ro' : 'rw';
             if (this.token) {
                 await this.fetchMe();
                 if (this.currentUser?.must_change_password) return;
                 await this.loadServers(); await this.loadGroups(); await this.loadStatuses(); await this.loadSnippets();
                 setInterval(() => this.loadStatuses(), 30000);
                 this._restoreTabs();
+                if (this._pendingJoinToken) {
+                    this.joinSharedSession(this._pendingJoinToken, this._pendingJoinMode);
+                    history.replaceState({}, '', BASE + '/');
+                    this._pendingJoinToken = null;
+                }
             }
             this.log('status', 'webgate initialized');
         },
@@ -1012,9 +1024,14 @@ function app() {
                 this.totpRequired = false; this.totpCode = ''; this.tempToken = '';
                 await this.fetchMe();
                 if (this.currentUser?.must_change_password) { this.showChangePassword = true; return; }
-                await this.loadServers(); await this.loadGroups();
+                await this.loadServers(); await this.loadGroups(); await this.loadStatuses(); await this.loadSnippets();
                 this.username = ''; this.password = '';
                 this.log('status', 'Logged in as ' + this.currentUser?.username);
+                if (this._pendingJoinToken) {
+                    this.joinSharedSession(this._pendingJoinToken, this._pendingJoinMode);
+                    history.replaceState({}, '', BASE + '/');
+                    this._pendingJoinToken = null;
+                }
             } catch (e) { this.showToast(e.message, 'error'); }
         },
         async fetchMe() { try { this.currentUser = await this.apiCall('/api/auth/me'); } catch { this.logout(); } },
@@ -1023,7 +1040,7 @@ function app() {
             try {
                 await this.apiCall('/api/auth/change-password', { method: 'POST', body: JSON.stringify({ new_password: this.newPassword }) });
                 this.showChangePassword = false; this.newPassword = ''; this.confirmPassword = '';
-                await this.fetchMe(); await this.loadServers(); await this.loadGroups();
+                await this.fetchMe(); await this.loadServers(); await this.loadGroups(); await this.loadStatuses(); await this.loadSnippets();
                 this.username = ''; this.password = '';
                 this.showToast('Password changed');
                 this.log('status', 'Logged in as ' + this.currentUser?.username);
@@ -1083,6 +1100,23 @@ function app() {
             tab._ws.send(s.command + '\r');
             this.log('cmd', `Sent snippet "${s.name}"`);
         },
+
+        // Shared sessions
+        async shareSession(tab) {
+            if (!tab._sessionId) { this.showToast('Session not ready yet', 'error'); return; }
+            try {
+                const res = await this.apiCall(`/api/terminal/share/${tab._sessionId}`, { method: 'POST' });
+                tab._shareToken = res.token;
+                const url = `${location.origin}${BASE}/?join=${res.token}`;
+                try { await navigator.clipboard.writeText(url); this.showToast('Share URL copied to clipboard'); }
+                catch { prompt('Copy this share URL:', url); }
+                this.log('status', `Shared session URL: ${url}`);
+            } catch (e) { this.showToast(e.message, 'error'); }
+        },
+        joinSharedSession(token, mode = 'rw') {
+            const tab = this._createTab('terminal', `shared (${mode})`, { _isJoined: true, _joinMode: mode });
+            this.$nextTick(() => this._initTerminal(tab, `/api/ws/terminal/join/${token}?mode=${mode}`, {}));
+        },
         async loadStatuses() { try { this.serverStatuses = await this.apiCall('/api/servers/status'); } catch {} },
         async loadGroups() { try { this.groups = await this.apiCall('/api/servers/groups'); } catch {} },
         resetServerForm() { this.editingServerId = null; this.serverForm = { name: '', hostname: '', port: 22, username: '', auth_method: 'password', password: '', private_key: '', keyFileName: '', group: '', tagsStr: '', description: '', ssh_enabled: true, sftp_enabled: true, sftp_read_only: false, sftp_allowed_paths_str: '', jump_via_id: null }; },
@@ -1203,10 +1237,22 @@ function app() {
             requestAnimationFrame(() => {
                 fitAddon.fit();
                 const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
-                const ws = new WebSocket(`${protocol}//${location.host}${BASE}${wsPath}?token=${encodeURIComponent(this.token)}`);
+                const sep = wsPath.includes('?') ? '&' : '?';
+                const ws = new WebSocket(`${protocol}//${location.host}${BASE}${wsPath}${sep}token=${encodeURIComponent(this.token)}`);
                 tab._ws = ws;
                 ws.onopen = () => { ws.send(JSON.stringify({ ...connInfo, cols: term.cols, rows: term.rows })); this.log('status', `Connected: ${tab.title}`); };
-                ws.onmessage = (e) => term.write(e.data);
+                ws.onmessage = (e) => {
+                    // Backend may send a control JSON frame (session id on connect, join ack)
+                    if (typeof e.data === 'string' && e.data.startsWith('{')) {
+                        try {
+                            const ctrl = JSON.parse(e.data);
+                            if (ctrl.type === 'session') { tab._sessionId = ctrl.session_id; return; }
+                            if (ctrl.type === 'joined') { tab._isJoined = true; tab._joinMode = ctrl.mode; this.log('status', `Joined session of ${ctrl.owner} on ${ctrl.server} (${ctrl.mode})`); return; }
+                            if (ctrl.type === 'error') { this.log('error', ctrl.message); return; }
+                        } catch {}
+                    }
+                    term.write(e.data);
+                };
                 ws.onerror = () => this.log('error', `Connection error: ${tab.title}`);
                 ws.onclose = (e) => { if (e.code === 4001) this.log('error', 'Authentication failed'); this.log('status', `Disconnected: ${tab.title}`); term.write('\r\n\x1b[31m--- Disconnected ---\x1b[0m\r\n'); };
                 term.onData(data => { if (ws.readyState === WebSocket.OPEN) ws.send(data); });

{webgate-0.3.2 → webgate-0.4.0}/src/webgate/terminal/routes.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect, status
 
 from webgate.audit.service import log_action
 from webgate.auth.models import UserOut
+from webgate.auth.routes import get_current_user
 from webgate.auth.service import get_user_by_id
 from webgate.db.engine import async_session_factory
 from webgate.servers.service import (
@@ -12,11 +15,41 @@ from webgate.servers.service import (
     resolve_jump_creds,
     update_last_connected,
 )
-from webgate.terminal.ws_handler import authenticate_websocket, handle_terminal_ws
+from webgate.terminal.shared import manager as shared_manager
+from webgate.terminal.ws_handler import authenticate_websocket, handle_join_ws, handle_terminal_ws
 from webgate.webhooks.dispatcher import fire as fire_webhook
 
 router = APIRouter(tags=["terminal"])
 
+CurrentUserDep = Annotated[UserOut, Depends(get_current_user)]
+
+
+@router.post("/api/terminal/share/{session_id}")
+async def create_share_token(session_id: str, user: CurrentUserDep) -> dict[str, object]:
+    """Mint a shareable token for an active terminal session. Only the
+    session owner may share; other users will get 403."""
+    sess = shared_manager.get_by_id(session_id)
+    if sess is None or sess.closed:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not active")
+    if sess.owner_username != user.username:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Only the session owner can share")
+    token = shared_manager.mint_token(session_id)
+    return {
+        "token": token,
+        "server": sess.server_label,
+        "participants": len(sess.participants),
+    }
+
+
+@router.delete("/api/terminal/share/{session_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def revoke_share_token(session_id: str, user: CurrentUserDep) -> None:
+    sess = shared_manager.get_by_id(session_id)
+    if sess is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not active")
+    if sess.owner_username != user.username:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Only the session owner can revoke")
+    shared_manager.revoke_token(session_id)
+
 
 @router.websocket("/api/ws/terminal/quick")
 async def ws_terminal_quick(ws: WebSocket) -> None:
@@ -45,15 +78,11 @@ async def ws_terminal_quick(ws: WebSocket) -> None:
         await ws.close(code=1008)
         return
 
+    payload_username = str(payload.get("username", "user")) if payload else "user"
     await handle_terminal_ws(
-        ws,
-        host=host,
-        port=port,
-        username=username,
-        password=password,
-        private_key=private_key,
-        cols=cols,
-        rows=rows,
+        ws, host=host, port=port, username=username,
+        password=password, private_key=private_key, cols=cols, rows=rows,
+        owner_username=payload_username, server_label=f"{username}@{host}",
     )
 
 
@@ -123,4 +152,19 @@ async def ws_terminal_server(ws: WebSocket, server_id: int) -> None:
         cols=cols,
         rows=rows,
         jump_kwargs=jump_kwargs,
+        owner_username=user_out.username,
+        server_label=server.name,
     )
+
+
+@router.websocket("/api/ws/terminal/join/{token}")
+async def ws_terminal_join(ws: WebSocket, token: str, mode: str = "rw") -> None:
+    """Join an existing shared SSH session via its share token."""
+    payload = await authenticate_websocket(ws)
+    if payload is None:
+        await ws.close(code=4001, reason="Unauthorized")
+        return
+    username = str(payload.get("username", "guest"))
+    if mode not in ("rw", "ro"):
+        mode = "ro"
+    await handle_join_ws(ws, share_token=token, username=username, mode=mode)

webgate-0.4.0/src/webgate/terminal/shared.py

@@ -0,0 +1,129 @@
+"""Shared SSH session manager.
+
+A SharedSession owns ONE asyncssh process and broadcasts its output to many
+connected WebSocket clients. Any client (in `rw` mode) may also send input.
+
+Lifecycle:
+- Owner opens an SSH terminal → handle_terminal_ws registers a SharedSession
+  with a generated session_id (no share token yet).
+- Owner clicks "Share" → POST /api/terminal/share/{session_id} mints a token
+  and stores it on the SharedSession.
+- Joiner connects WS /api/ws/terminal/join/{token} → added as RW or RO client.
+- Owner closes their tab → SharedSession is torn down, all joiners disconnected.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import secrets
+from dataclasses import dataclass, field
+
+from fastapi import WebSocket
+
+from webgate.terminal.ssh_session import SSHSession
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Participant:
+    ws: WebSocket
+    username: str
+    mode: str = "rw"  # "rw" or "ro"
+
+
+@dataclass
+class SharedSession:
+    session_id: str
+    server_label: str
+    owner_username: str
+    ssh: SSHSession
+    participants: list[Participant] = field(default_factory=list)
+    share_token: str | None = None  # set when owner clicks "Share"
+    closed: bool = False
+
+    async def broadcast(self, text: str) -> None:
+        dead: list[Participant] = []
+        for p in self.participants:
+            try:
+                await p.ws.send_text(text)
+            except Exception:
+                dead.append(p)
+        for p in dead:
+            self.participants.remove(p)
+
+    async def write_input(self, data: str, from_username: str) -> None:
+        # Only RW participants can drive input; ROs are no-ops.
+        sender = next((p for p in self.participants if p.username == from_username), None)
+        if sender is None or sender.mode != "rw":
+            return
+        await self.ssh.write(data)
+
+    async def close(self) -> None:
+        if self.closed:
+            return
+        self.closed = True
+        for p in self.participants:
+            with contextlib.suppress(Exception):
+                await p.ws.close()
+        self.participants.clear()
+        await self.ssh.close()
+
+
+class SharedSessionManager:
+    """In-memory registry of active shared SSH sessions."""
+
+    def __init__(self) -> None:
+        self._by_id: dict[str, SharedSession] = {}
+        self._by_token: dict[str, SharedSession] = {}
+
+    def new_session_id(self) -> str:
+        return secrets.token_urlsafe(12)
+
+    def register(self, sess: SharedSession) -> None:
+        self._by_id[sess.session_id] = sess
+
+    def unregister(self, session_id: str) -> SharedSession | None:
+        sess = self._by_id.pop(session_id, None)
+        if sess and sess.share_token:
+            self._by_token.pop(sess.share_token, None)
+        return sess
+
+    def get_by_id(self, session_id: str) -> SharedSession | None:
+        return self._by_id.get(session_id)
+
+    def get_by_token(self, token: str) -> SharedSession | None:
+        return self._by_token.get(token)
+
+    def mint_token(self, session_id: str) -> str | None:
+        sess = self._by_id.get(session_id)
+        if sess is None or sess.closed:
+            return None
+        if sess.share_token is None:
+            sess.share_token = secrets.token_urlsafe(16)
+            self._by_token[sess.share_token] = sess
+        return sess.share_token
+
+    def revoke_token(self, session_id: str) -> None:
+        sess = self._by_id.get(session_id)
+        if sess and sess.share_token:
+            self._by_token.pop(sess.share_token, None)
+            sess.share_token = None
+
+    async def run_read_loop(self, sess: SharedSession) -> None:
+        """Single read loop per shared session. Broadcasts SSH output to all
+        clients. Returns when the SSH session ends or is closed."""
+        try:
+            while not sess.ssh.is_closed and not sess.closed:
+                data = await sess.ssh.read()
+                if data is None:
+                    break
+                await sess.broadcast(data)
+        finally:
+            await sess.close()
+
+
+# Module-level singleton
+manager = SharedSessionManager()

webgate-0.4.0/src/webgate/terminal/ws_handler.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+from webgate.auth.service import authenticate_api_key, decode_access_token
+from webgate.db.engine import async_session_factory
+from webgate.terminal.shared import Participant, SharedSession, manager
+from webgate.terminal.ssh_session import SSHSession
+
+logger = logging.getLogger(__name__)
+
+
+async def authenticate_websocket(ws: WebSocket) -> dict[str, object] | None:
+    token = ws.query_params.get("token")
+    if not token:
+        return None
+
+    # Support API key authentication (keys start with "wg_")
+    if token.startswith("wg_"):
+        async with async_session_factory() as session:
+            user = await authenticate_api_key(session, token)
+            if user:
+                return {"sub": str(user.id), "username": user.username}
+            return None
+
+    payload = decode_access_token(token)
+    return payload
+
+
+async def handle_terminal_ws(
+    ws: WebSocket,
+    host: str,
+    port: int,
+    username: str,
+    password: str | None = None,
+    private_key: str | None = None,
+    cols: int = 80,
+    rows: int = 24,
+    jump_kwargs: dict[str, object] | None = None,
+    owner_username: str = "owner",
+    server_label: str | None = None,
+) -> None:
+    """Open an SSH session as the owner. The session is registered with the
+    shared-session manager so other users can join via a share token."""
+    session = SSHSession(
+        host=host, port=port, username=username,
+        password=password, private_key=private_key, jump_kwargs=jump_kwargs,
+    )
+    try:
+        await session.connect(cols=cols, rows=rows)
+    except Exception as e:
+        logger.error("SSH connection failed: %s", e)
+        await ws.send_json({"type": "error", "message": f"SSH connection failed: {e}"})
+        await ws.close(code=1011)
+        return
+
+    sess = SharedSession(
+        session_id=manager.new_session_id(),
+        server_label=server_label or f"{username}@{host}",
+        owner_username=owner_username,
+        ssh=session,
+    )
+    sess.participants.append(Participant(ws=ws, username=owner_username, mode="rw"))
+    manager.register(sess)
+
+    # Tell the owner their session_id so the UI can build a share URL.
+    with contextlib.suppress(Exception):
+        await ws.send_text(json.dumps({"type": "session", "session_id": sess.session_id}))
+
+    read_task = asyncio.create_task(manager.run_read_loop(sess))
+    try:
+        await _client_input_loop(ws, session, sess, owner_username)
+    finally:
+        read_task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await read_task
+        manager.unregister(sess.session_id)
+
+
+async def handle_join_ws(ws: WebSocket, share_token: str, username: str, mode: str) -> None:
+    """Attach a joiner to an existing SharedSession via its share token."""
+    sess = manager.get_by_token(share_token)
+    if sess is None or sess.closed:
+        await ws.close(code=4004, reason="Share session not found or closed")
+        return
+    await ws.accept()
+    participant = Participant(ws=ws, username=username, mode=mode)
+    sess.participants.append(participant)
+    with contextlib.suppress(Exception):
+        await ws.send_text(json.dumps({
+            "type": "joined",
+            "server": sess.server_label,
+            "owner": sess.owner_username,
+            "mode": mode,
+        }))
+    try:
+        await _client_input_loop(ws, sess.ssh, sess, username)
+    finally:
+        if participant in sess.participants:
+            sess.participants.remove(participant)
+
+
+async def _client_input_loop(
+    ws: WebSocket, ssh: SSHSession, sess: SharedSession, username: str,
+) -> None:
+    """Receives input + control messages from one client and dispatches to
+    the SSH process via the shared session (RO clients can only resize)."""
+    try:
+        while True:
+            message = await ws.receive_text()
+            try:
+                raw: object = json.loads(message)
+                if isinstance(raw, dict):
+                    parsed: dict[str, object] = raw  # pyright: ignore[reportUnknownVariableType]
+                    if parsed.get("type") == "resize":
+                        c = parsed.get("cols", 80)
+                        r = parsed.get("rows", 24)
+                        await ssh.resize(int(str(c)), int(str(r)))
+                        continue
+            except (json.JSONDecodeError, KeyError, ValueError):
+                pass
+            await sess.write_input(message, username)
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        pass

webgate-0.3.2/src/webgate/terminal/ws_handler.py

@@ -1,102 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import contextlib
-import json
-import logging
-
-from fastapi import WebSocket, WebSocketDisconnect
-
-from webgate.auth.service import authenticate_api_key, decode_access_token
-from webgate.db.engine import async_session_factory
-from webgate.terminal.ssh_session import SSHSession
-
-logger = logging.getLogger(__name__)
-
-
-async def authenticate_websocket(ws: WebSocket) -> dict[str, object] | None:
-    token = ws.query_params.get("token")
-    if not token:
-        return None
-
-    # Support API key authentication (keys start with "wg_")
-    if token.startswith("wg_"):
-        async with async_session_factory() as session:
-            user = await authenticate_api_key(session, token)
-            if user:
-                return {"sub": str(user.id), "username": user.username}
-            return None
-
-    payload = decode_access_token(token)
-    return payload
-
-
-async def handle_terminal_ws(
-    ws: WebSocket,
-    host: str,
-    port: int,
-    username: str,
-    password: str | None = None,
-    private_key: str | None = None,
-    cols: int = 80,
-    rows: int = 24,
-    jump_kwargs: dict[str, object] | None = None,
-) -> None:
-    session = SSHSession(
-        host=host,
-        port=port,
-        username=username,
-        password=password,
-        private_key=private_key,
-        jump_kwargs=jump_kwargs,
-    )
-
-    try:
-        await session.connect(cols=cols, rows=rows)
-    except Exception as e:
-        logger.error("SSH connection failed: %s", e)
-        await ws.send_json({"type": "error", "message": f"SSH connection failed: {e}"})
-        await ws.close(code=1011)
-        return
-
-    async def ssh_to_ws() -> None:
-        try:
-            while not session.is_closed:
-                data = await session.read()
-                if data is None:
-                    break
-                await ws.send_text(data)
-        except Exception:
-            pass
-        finally:
-            if not session.is_closed:
-                await session.close()
-            with contextlib.suppress(Exception):
-                await ws.close()
-
-    read_task = asyncio.create_task(ssh_to_ws())
-
-    try:
-        while True:
-            message = await ws.receive_text()
-            try:
-                raw: object = json.loads(message)
-                if isinstance(raw, dict):
-                    parsed: dict[str, object] = raw  # pyright: ignore[reportUnknownVariableType]
-                    if parsed.get("type") == "resize":
-                        c = parsed.get("cols", 80)
-                        r = parsed.get("rows", 24)
-                        await session.resize(int(str(c)), int(str(r)))
-                        continue
-            except (json.JSONDecodeError, KeyError, ValueError):
-                pass
-            await session.write(message)
-    except WebSocketDisconnect:
-        pass
-    except Exception:
-        pass
-    finally:
-        read_task.cancel()
-        with contextlib.suppress(asyncio.CancelledError):
-            await read_task
-        await session.close()