webgate 0.3.3__tar.gz → 0.4.1__tar.gz

{webgate-0.3.3 → webgate-0.4.1}/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## v0.4.1 (2026-04-15)
+
+### Features
+
+- **SSH session recording** -- when `WEBGATE_RECORD_SESSIONS=true`, every SSH terminal session is captured to an asciinema cast v2 file under `WEBGATE_RECORDINGS_DIR` (default `./recordings`). Both owner-only and shared sessions are recorded. A new `recordings` table tracks file path, server, user, start/end, duration and size.
+- **Built-in web replay** -- `📹 Recordings` button (top toolbar) opens a list with **▶ Play** / **DL** / **Del** actions. Play opens an asciinema-player tab that streams the cast directly from the API. Non-admins see only their own recordings; admins see everyone's.
+- **Compliance-grade audit trail** -- the recording captures the full PTY output that every participant saw, including pasted commands and environment, in a portable, replayable, vendor-independent format (you can also `asciinema play file.cast` locally).
+
+### Details
+
+- New `WEBGATE_RECORD_SESSIONS` and `WEBGATE_RECORDINGS_DIR` settings (both off / `./recordings` by default)
+- New `Recording` model + REST CRUD at `/api/recordings`
+- New `webgate.recordings.recorder.CastRecorder` writes asciinema cast v2 (JSON Lines) line-buffered, very low overhead
+- Hook in `SharedSession.broadcast` -- recorder receives the same byte stream as every WS client
+- Player endpoint accepts a `?token=` query param (Authorization header isn't available when opening a tab)
+
+### Verified
+
+End-to-end against a real container with `WEBGATE_RECORD_SESSIONS=true`:
+
+- Open SSH, run `echo HELLO_RECORDED` + `uname -n`, disconnect
+- DB row populated: `started_at`, `ended_at`, `duration_s=3.0`, `size_bytes=1142`
+- File on disk: valid asciinema v2 cast, captures welcome banner + commands + responses
+- Open `/api/recordings/{id}/play?token=...` in browser → asciinema-player loads, hit Play → terminal replays the captured commands
+
+---
+
+## 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

{webgate-0.3.3 → webgate-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webgate
-Version: 0.3.3
+Version: 0.4.1
 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,33 @@ flowchart TB
 ### Light Theme
 ![Light Theme](docs/screenshots/light-theme.png)
 
+### v0.4.1 — SSH Session Recording
+
+Set `WEBGATE_RECORD_SESSIONS=true` and every SSH session is captured to an asciinema cast v2 file. Replay in the browser with the embedded asciinema player, or download the `.cast` and `asciinema play` it locally.
+
+```bash
+docker run -e WEBGATE_RECORD_SESSIONS=true \
+  -e WEBGATE_RECORDINGS_DIR=/data/recordings \
+  -v webgate-data:/data \
+  kalexnolasco/webgate:0.4.1
+```
+
+| Recordings list | Replay in browser |
+| --- | --- |
+| ![Recordings](docs/screenshots/v0.4/04-recordings-modal.png) | ![Replay](docs/screenshots/v0.4/03-recording-replay.png) |
+
+Non-admins see only their own recordings; admins see everyone's. Each recording row has **▶ Play** (browser), **DL** (download `.cast`), and **Del**.
+
+### 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`).

{webgate-0.3.3 → webgate-0.4.1}/README.md

@@ -194,6 +194,33 @@ flowchart TB
 ### Light Theme
 ![Light Theme](docs/screenshots/light-theme.png)
 
+### v0.4.1 — SSH Session Recording
+
+Set `WEBGATE_RECORD_SESSIONS=true` and every SSH session is captured to an asciinema cast v2 file. Replay in the browser with the embedded asciinema player, or download the `.cast` and `asciinema play` it locally.
+
+```bash
+docker run -e WEBGATE_RECORD_SESSIONS=true \
+  -e WEBGATE_RECORDINGS_DIR=/data/recordings \
+  -v webgate-data:/data \
+  kalexnolasco/webgate:0.4.1
+```
+
+| Recordings list | Replay in browser |
+| --- | --- |
+| ![Recordings](docs/screenshots/v0.4/04-recordings-modal.png) | ![Replay](docs/screenshots/v0.4/03-recording-replay.png) |
+
+Non-admins see only their own recordings; admins see everyone's. Each recording row has **▶ Play** (browser), **DL** (download `.cast`), and **Del**.
+
+### 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`).

{webgate-0.3.3 → webgate-0.4.1}/pyproject.toml

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

{webgate-0.3.3 → webgate-0.4.1}/src/webgate/app.py

@@ -18,6 +18,7 @@ from webgate.files.pool import sftp_pool
 from webgate.files.routes import router as files_router
 from webgate.servers.monitor import server_monitor
 from webgate.servers.routes import router as servers_router
+from webgate.recordings.routes import router as recordings_router
 from webgate.snippets.routes import router as snippets_router
 from webgate.terminal.routes import router as terminal_router
 from webgate.webhooks.routes import router as webhooks_router
@@ -75,7 +76,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"},
@@ -93,6 +97,7 @@ def create_app() -> FastAPI:
     app.include_router(files_router)
     app.include_router(snippets_router)
     app.include_router(webhooks_router)
+    app.include_router(recordings_router)
 
     app.mount("/", StaticFiles(directory=str(settings.static_dir), html=True), name="static")
 

{webgate-0.3.3 → webgate-0.4.1}/src/webgate/config.py

@@ -13,6 +13,8 @@ class Settings(BaseSettings):
     allowed_origins: str = "*"
     root_path: str = ""  # URL prefix when served behind a reverse proxy (e.g. "/webgate")
     demo_mode: bool = False  # Read-only public demo: blocks writes, hides admin UI
+    record_sessions: bool = False  # Capture SSH sessions to asciinema cast files
+    recordings_dir: str = "./recordings"  # Where to store .cast files
     log_level: str = "info"
     session_timeout: int = 3600
     max_upload_size: int = 104857600  # 100MB

webgate-0.4.1/src/webgate/recordings/models.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from webgate.db.engine import Base
+
+
+class Recording(Base):
+    __tablename__ = "recordings"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    server_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("servers.id"), nullable=True
+    )
+    server_name: Mapped[str] = mapped_column(String(255), default="")
+    user_id: Mapped[int] = mapped_column(Integer, ForeignKey("users.id"))
+    username: Mapped[str] = mapped_column(String(255), default="")
+    file_path: Mapped[str] = mapped_column(Text)
+    started_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+    ended_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    duration_s: Mapped[float] = mapped_column(default=0.0)
+    size_bytes: Mapped[int] = mapped_column(Integer, default=0)
+
+
+class RecordingOut(BaseModel):
+    id: int
+    server_id: int | None
+    server_name: str
+    username: str
+    started_at: datetime
+    ended_at: datetime | None
+    duration_s: float
+    size_bytes: int
+
+    model_config = {"from_attributes": True}

webgate-0.4.1/src/webgate/recordings/recorder.py

@@ -0,0 +1,63 @@
+"""asciinema cast v2 writer.
+
+The cast format is JSON Lines:
+- First line: header object {"version": 2, "width": N, "height": N, "timestamp": <unix>}
+- Each subsequent line: [time_offset_seconds, "o" | "i", "data"]
+
+Reference: https://github.com/asciinema/asciinema/blob/develop/doc/asciicast-v2.md
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import time
+from pathlib import Path
+from typing import IO
+
+logger = logging.getLogger(__name__)
+
+
+class CastRecorder:
+    def __init__(self, path: Path, cols: int, rows: int) -> None:
+        self.path = path
+        self._fh: IO[str] | None = None
+        self._start = time.monotonic()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._fh = path.open("w", encoding="utf-8", buffering=1)  # line-buffered
+        header = {
+            "version": 2,
+            "width": cols,
+            "height": rows,
+            "timestamp": int(time.time()),
+            "env": {"TERM": "xterm-256color", "SHELL": "/bin/bash"},
+        }
+        self._fh.write(json.dumps(header) + "\n")
+
+    def write_output(self, data: str) -> None:
+        fh = self._fh
+        if fh is None or fh.closed:
+            return
+        try:
+            offset = time.monotonic() - self._start
+            fh.write(json.dumps([round(offset, 6), "o", data]) + "\n")
+        except Exception as e:
+            logger.warning("CastRecorder write failed for %s: %s", self.path, e)
+
+    @property
+    def duration(self) -> float:
+        return time.monotonic() - self._start
+
+    def close(self) -> int:
+        """Close the recorder and return the final byte size."""
+        fh = self._fh
+        self._fh = None
+        if fh is not None and not fh.closed:
+            with contextlib.suppress(Exception):
+                fh.flush()
+                fh.close()
+        try:
+            return self.path.stat().st_size
+        except OSError:
+            return 0

webgate-0.4.1/src/webgate/recordings/routes.py

@@ -0,0 +1,139 @@
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.responses import FileResponse, HTMLResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from webgate.auth.models import UserOut
+from webgate.auth.routes import get_current_user
+from webgate.auth.service import authenticate_api_key, decode_access_token, get_user_by_id
+from webgate.db.engine import get_session
+from webgate.recordings.models import Recording, RecordingOut
+
+
+async def _user_from_query_token(
+    token: str, session: AsyncSession
+) -> UserOut:
+    """Resolve a user from a JWT or API key passed via ?token= query. Used by
+    the play/download endpoints that open in a new browser tab where we can't
+    set an Authorization header."""
+    if token.startswith("wg_"):
+        u = await authenticate_api_key(session, token)
+    else:
+        payload = decode_access_token(token)
+        if not payload or not payload.get("sub"):
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+        u = await get_user_by_id(session, int(str(payload["sub"])))
+    if u is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+    return UserOut.model_validate(u)
+
+router = APIRouter(prefix="/api/recordings", tags=["recordings"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+CurrentUserDep = Annotated[UserOut, Depends(get_current_user)]
+
+
+@router.get("", response_model=list[RecordingOut])
+async def list_recordings(session: SessionDep, user: CurrentUserDep) -> list[Recording]:
+    stmt = select(Recording).order_by(Recording.started_at.desc())
+    if not user.is_admin:
+        stmt = stmt.where(Recording.user_id == user.id)
+    result = await session.execute(stmt)
+    return list(result.scalars().all())
+
+
+async def _get_recording_for(
+    session: AsyncSession, recording_id: int, user: UserOut
+) -> Recording:
+    stmt = select(Recording).where(Recording.id == recording_id)
+    if not user.is_admin:
+        stmt = stmt.where(Recording.user_id == user.id)
+    rec = (await session.execute(stmt)).scalar_one_or_none()
+    if rec is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Recording not found")
+    return rec
+
+
+@router.get("/{recording_id}/download")
+async def download_recording(
+    recording_id: int, session: SessionDep, token: Annotated[str, Query()]
+) -> FileResponse:
+    user = await _user_from_query_token(token, session)
+    rec = await _get_recording_for(session, recording_id, user)
+    p = Path(rec.file_path)
+    if not p.exists():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Recording file missing")
+    return FileResponse(
+        path=str(p), media_type="application/x-asciicast",
+        filename=f"webgate-{rec.id}-{rec.server_name}.cast",
+    )
+
+
+@router.get("/{recording_id}/play", response_class=HTMLResponse)
+async def play_recording(
+    recording_id: int, session: SessionDep, token: Annotated[str, Query()]
+) -> HTMLResponse:
+    user = await _user_from_query_token(token, session)
+    rec = await _get_recording_for(session, recording_id, user)
+    # Embed asciinema-player from CDN. The cast file is fetched via the
+    # download endpoint so JWT auth is honored.
+    started = rec.started_at.isoformat()
+    html = f"""<!doctype html>
+<html><head>
+<meta charset="utf-8">
+<title>webgate replay #{rec.id} — {rec.server_name}</title>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.css">
+<style>
+  body {{ background:#1a1b26; color:#c0caf5; font-family:system-ui,sans-serif; margin:0; padding:20px; }}
+  .meta {{ display:flex; gap:24px; font-size:13px; margin-bottom:16px; color:#9ba3c5; }}
+  .meta b {{ color:#fff; }}
+  #player {{ max-width:1100px; }}
+</style>
+</head><body>
+<div class=\"meta\">
+  <span>📹 <b>{rec.server_name}</b></span>
+  <span>👤 {rec.username}</span>
+  <span>🕒 {started}</span>
+  <span>⏱ {rec.duration_s:.1f}s</span>
+  <span>💾 {rec.size_bytes:,} bytes</span>
+</div>
+<div id=\"player\"></div>
+<script src=\"https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.min.js\"></script>
+<script>
+  AsciinemaPlayer.create('cast?token={token}', document.getElementById('player'),
+    {{ idleTimeLimit: 2, theme: 'tango', fit: 'width' }});
+</script>
+</body></html>"""
+    return HTMLResponse(content=html)
+
+
+@router.get("/{recording_id}/cast")
+async def cast_raw(
+    recording_id: int, session: SessionDep, token: Annotated[str, Query()]
+) -> FileResponse:
+    """Same as /download but returns the raw cast (no Content-Disposition) so
+    the embedded player can fetch it via XHR."""
+    user = await _user_from_query_token(token, session)
+    rec = await _get_recording_for(session, recording_id, user)
+    p = Path(rec.file_path)
+    if not p.exists():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Recording file missing")
+    return FileResponse(path=str(p), media_type="application/x-asciicast")
+
+
+@router.delete("/{recording_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_recording(
+    recording_id: int, session: SessionDep, user: CurrentUserDep
+) -> None:
+    rec = await _get_recording_for(session, recording_id, user)
+    p = Path(rec.file_path)
+    if p.exists():
+        try:
+            p.unlink()
+        except OSError:
+            pass
+    await session.delete(rec)
+    await session.commit()

{webgate-0.3.3 → webgate-0.4.1}/src/webgate/static/index.html

@@ -233,6 +233,7 @@ window._showToastImpl = function(message, type) {
             <button x-show="currentUser?.is_admin" @click="openUsersModal()" class="fz-btn" style="font-size:11px">Users</button>
             <button x-show="currentUser?.is_admin" @click="openAuditLog()" class="fz-btn" style="font-size:11px">Audit</button>
             <button x-show="currentUser?.is_admin" @click="openWebhooksModal()" class="fz-btn" style="font-size:11px">Webhooks</button>
+            <button @click="openRecordingsModal()" class="fz-btn" style="font-size:11px">📹 Recordings</button>
             <button @click="openApiKeysModal()" class="fz-btn" style="font-size:11px">Keys</button>
         </div>
         <div style="display:flex;align-items:center;gap:8px">
@@ -358,6 +359,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>
@@ -795,6 +799,49 @@ window._showToastImpl = function(message, type) {
     </div>
 </div>
 
+<!-- ======== RECORDINGS MODAL ======== -->
+<div x-show="showRecordingsModal" class="fz-modal-bg" @click.self="showRecordingsModal=false">
+    <div class="fz-modal" style="width:760px" @click.stop>
+        <div class="fz-modal-title">📹 Session Recordings</div>
+        <div class="fz-modal-body" style="padding:0;max-height:55vh;overflow-y:auto">
+            <table style="width:100%;font-size:12px;border-collapse:collapse">
+                <thead style="position:sticky;top:0;background:var(--btn-bg)">
+                    <tr>
+                        <th style="padding:8px 12px;border-bottom:1px solid var(--border);color:var(--text-secondary);font-size:10px;text-transform:uppercase;text-align:left">Server</th>
+                        <th style="padding:8px 12px;border-bottom:1px solid var(--border);color:var(--text-secondary);font-size:10px;text-transform:uppercase;text-align:left">User</th>
+                        <th style="padding:8px 12px;border-bottom:1px solid var(--border);color:var(--text-secondary);font-size:10px;text-transform:uppercase;text-align:left">Started</th>
+                        <th style="padding:8px 12px;border-bottom:1px solid var(--border);color:var(--text-secondary);font-size:10px;text-transform:uppercase;text-align:left">Duration</th>
+                        <th style="padding:8px 12px;border-bottom:1px solid var(--border);color:var(--text-secondary);font-size:10px;text-transform:uppercase;text-align:left">Size</th>
+                        <th style="padding:8px 12px;border-bottom:1px solid var(--border);color:var(--text-secondary);font-size:10px;text-transform:uppercase;width:160px"></th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <template x-for="r in recordings" :key="r.id">
+                        <tr style="border-bottom:1px solid var(--btn-bg)">
+                            <td style="padding:6px 12px;color:var(--text-primary);font-weight:500" x-text="r.server_name"></td>
+                            <td style="padding:6px 12px;color:var(--text-secondary)" x-text="r.username"></td>
+                            <td style="padding:6px 12px;color:var(--text-secondary);font-size:11px" x-text="new Date(r.started_at).toLocaleString()"></td>
+                            <td style="padding:6px 12px;color:var(--text-secondary);font-family:monospace" x-text="r.duration_s ? r.duration_s.toFixed(1) + 's' : '—'"></td>
+                            <td style="padding:6px 12px;color:var(--text-secondary);font-family:monospace" x-text="r.size_bytes ? (r.size_bytes < 1024 ? r.size_bytes + ' B' : (r.size_bytes/1024).toFixed(1) + ' KB') : '—'"></td>
+                            <td style="padding:6px 12px;display:flex;gap:4px">
+                                <a :href="BASE + '/api/recordings/' + r.id + '/play?token=' + encodeURIComponent(token)" target="_blank" class="fz-btn fz-btn-primary" style="font-size:10px;padding:2px 8px;text-decoration:none">▶ Play</a>
+                                <a :href="BASE + '/api/recordings/' + r.id + '/download?token=' + encodeURIComponent(token)" class="fz-btn" style="font-size:10px;padding:2px 8px;text-decoration:none">DL</a>
+                                <button @click="confirmDeleteRecording(r)" class="fz-btn fz-btn-danger" style="font-size:10px;padding:1px 6px">Del</button>
+                            </td>
+                        </tr>
+                    </template>
+                    <template x-if="recordings.length === 0">
+                        <tr><td colspan="6" style="padding:24px;text-align:center;color:var(--text-muted);font-size:12px">No recordings. Set <code>WEBGATE_RECORD_SESSIONS=true</code> on the server to start recording.</td></tr>
+                    </template>
+                </tbody>
+            </table>
+        </div>
+        <div class="fz-modal-footer">
+            <button @click="showRecordingsModal=false" class="fz-btn">Close</button>
+        </div>
+    </div>
+</div>
+
 <!-- ======== EDIT GROUPS MODAL ======== -->
 <div x-show="showGroupsModal" class="fz-modal-bg" @click.self="showGroupsModal=false">
     <div class="fz-modal" style="width:400px" @click.stop>
@@ -901,6 +948,7 @@ function app() {
         showAuditModal: false, auditEntries: [],
         showApiKeysModal: false, apiKeys: [], newApiKeyName: '', createdApiKey: null,
         showWebhooksModal: false, webhooks: [], newWebhook: { name: '', url: '', events: '*', secret: '' },
+        showRecordingsModal: false, recordings: [],
         view: 'dashboard',
         ssh: { host: '', port: 22, username: '', password: '' },
         servers: [], groups: [], selectedGroup: '', searchQuery: '',
@@ -963,12 +1011,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');
         },
@@ -1015,6 +1072,11 @@ function app() {
                 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(); } },
@@ -1083,6 +1145,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 +1282,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); });
@@ -1507,6 +1598,19 @@ function app() {
         async testWebhook(w) {
             try { await this.apiCall(`/api/webhooks/${w.id}/test`, { method: 'POST' }); this.showToast(`Test queued for "${w.name}"`); setTimeout(async () => { this.webhooks = await this.apiCall('/api/webhooks'); }, 1500); } catch (e) { this.showToast(e.message, 'error'); }
         },
+
+        // Recordings
+        get BASE() { return BASE; },
+        async openRecordingsModal() {
+            try { this.recordings = await this.apiCall('/api/recordings'); }
+            catch (e) { this.showToast(e.message, 'error'); return; }
+            this.showRecordingsModal = true;
+        },
+        async confirmDeleteRecording(r) {
+            if (!confirm(`Delete recording of "${r.server_name}" from ${new Date(r.started_at).toLocaleString()}?`)) return;
+            try { await this.apiCall(`/api/recordings/${r.id}`, { method: 'DELETE' }); this.recordings = await this.apiCall('/api/recordings'); this.showToast('Recording deleted'); }
+            catch (e) { this.showToast(e.message, 'error'); }
+        },
     };
 }
 </script>