EvolutionAPI
diff --git a/‎dashboard/backend/app.py‎
Lines changed: 20 additions & 0 deletions b/‎dashboard/backend/app.py‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎dashboard/backend/plugin_loader.py‎
Lines changed: 32 additions & 8 deletions b/‎dashboard/backend/plugin_loader.py‎
Lines changed: 32 additions & 8 deletions
diff --git a/‎dashboard/backend/routes/plugins.py‎
Lines changed: 38 additions & 6 deletions b/‎dashboard/backend/routes/plugins.py‎
Lines changed: 38 additions & 6 deletions
diff --git a/‎dashboard/backend/routes/terminal_proxy.py‎
Lines changed: 204 additions & 0 deletions b/‎dashboard/backend/routes/terminal_proxy.py‎
Lines changed: 204 additions & 0 deletions
@@ -834,6 +834,7 @@ def auth_middleware():
 from routes.mempalace import bp as mempalace_bp
 from routes.tasks import bp as tasks_bp
 from routes.triggers import bp as triggers_bp
+from routes.terminal_proxy import bp as terminal_proxy_bp, register_websocket_proxy as _register_terminal_ws
 from routes.backups import bp as backups_bp
 from routes.providers import bp as providers_bp
 from routes.settings import bp as settings_bp
@@ -887,6 +888,25 @@ def auth_middleware():
 app.register_blueprint(mempalace_bp)
 app.register_blueprint(tasks_bp)
 app.register_blueprint(triggers_bp)
+app.register_blueprint(terminal_proxy_bp)
+
+# Mount the terminal-server WebSocket proxy on the same Sock instance the
+# rest of the app uses. Done after the blueprint is registered so route
+# names are unique. Without this, browsers connecting from a host other
+# than the one running the Node terminal-server (LAN, Tailscale Funnel,
+# SSH tunnel without the dynamic port forwarded) cannot reach it directly
+# due to CORS preflight + private-network-access policies.
+try:
+    from flask_sock import Sock as _Sock
+    _terminal_sock = _Sock(app)
+    _register_terminal_ws(_terminal_sock)
+except Exception as _exc:
+    import logging as _logging
+    _logging.getLogger(__name__).warning(
+        "terminal_proxy: failed to mount WebSocket proxy: %s — terminal "
+        "interactions will require direct access to the terminal-server port.",
+        _exc,
+    )
 app.register_blueprint(backups_bp)
 app.register_blueprint(providers_bp)
 app.register_blueprint(settings_bp)
 
@@ -290,10 +290,23 @@ def resolve_source(source_url: str, auth_token: str | None = None) -> Path:
             staging_slug = f"{owner}-{repo}-{ref}".replace("/", "-")
             try:
                 return PluginInstaller.fetch_from_tarball(tar_url, staging_slug, auth_token=auth_token)
-            except RuntimeError:
-                # fallback: try as tag ref
+            except RuntimeError as branch_err:
+                # fallback: try as tag ref. If that also fails, surface a
+                # unified error so the caller knows both branch and tag
+                # namespaces were tried — otherwise the bare
+                # "refs/tags/<ref>: 404" message is misleading when the ref
+                # was actually a branch name.
                 tar_url_tag = f"https://codeload.github.com/{owner}/{repo}/tar.gz/refs/tags/{ref}"
-                return PluginInstaller.fetch_from_tarball(tar_url_tag, staging_slug, auth_token=auth_token)
+                try:
+                    return PluginInstaller.fetch_from_tarball(
+                        tar_url_tag, staging_slug, auth_token=auth_token
+                    )
+                except RuntimeError as tag_err:
+                    raise RuntimeError(
+                        f"ref '{ref}' not found in {owner}/{repo} "
+                        f"(tried branches and tags). "
+                        f"Branch: {branch_err}. Tag: {tag_err}."
+                    ) from tag_err
 
         if s.startswith("https://"):
             # Use a safe staging slug derived from the URL
@@ -477,12 +490,23 @@ def resolve_source_with_sha(
                     tar_url, staging_slug, auth_token=auth_token
                 )
                 return path, sha
-            except RuntimeError:
+            except RuntimeError as branch_err:
                 tar_url_tag = f"https://codeload.github.com/{owner}/{repo}/tar.gz/refs/tags/{ref}"
-                path, sha = PluginInstaller.fetch_from_tarball_with_sha(
-                    tar_url_tag, staging_slug, auth_token=auth_token
-                )
-                return path, sha
+                try:
+                    path, sha = PluginInstaller.fetch_from_tarball_with_sha(
+                        tar_url_tag, staging_slug, auth_token=auth_token
+                    )
+                    return path, sha
+                except RuntimeError as tag_err:
+                    # Both branch and tag namespaces exhausted — raise a
+                    # unified error rather than the bare tag 404 so callers
+                    # can distinguish ref-not-found from private-repo auth
+                    # failures. Kept in sync with ``resolve_source`` above.
+                    raise RuntimeError(
+                        f"ref '{ref}' not found in {owner}/{repo} "
+                        f"(tried branches and tags). "
+                        f"Branch: {branch_err}. Tag: {tag_err}."
+                    ) from tag_err
 
         # Plain https:// tarball
         staging_slug = re.sub(r"[^a-zA-Z0-9_-]+", "-", s)[-80:]
 
@@ -2158,7 +2158,10 @@ def serve_widget(slug: str, subpath: str):
 # ---------------------------------------------------------------------------
 
 # Module-level preview cache: key=(slug, source_url), value=(fetched_at_float, result_dict)
-_PREVIEW_CACHE: dict[tuple[str, str], tuple[float, dict]] = {}
+# Cache key: (slug, source_url, has_auth_token). has_auth_token flag prevents
+# leaking private-repo previews to unauthenticated callers — the value of the
+# token is deliberately not part of the key (no secrets in memory indices).
+_PREVIEW_CACHE: dict[tuple[str, str, bool], tuple[float, dict]] = {}
 _PREVIEW_CACHE_LOCK = threading.Lock()
 _PREVIEW_CACHE_TTL = 300  # seconds
 
@@ -2264,7 +2267,9 @@ def _extract_ids_and_entries(manifest: dict) -> dict[str, dict[str, Any]]:
     return added, removed, modified
 
 
-def _compute_preview(slug: str, source_url: str) -> dict:
+def _compute_preview(
+    slug: str, source_url: str, auth_token: str | None = None
+) -> dict:
     """Fetch candidate manifest and compute diff against installed manifest.
 
     Pure read-only: no DB writes, no file writes to plugins/{slug}/.
@@ -2273,6 +2278,12 @@ def _compute_preview(slug: str, source_url: str) -> dict:
     tarball_sha7 derivation: SHA256 of sorted manifest.files SHAs concatenated.
     If manifest.files is empty, falls back to SHA256 of serialized manifest JSON.
     First 7 chars of the hex digest are returned (deterministic, no re-download needed).
+
+    Args:
+        slug: Installed plugin slug.
+        source_url: Candidate source (github:..., https://...).
+        auth_token: Optional GitHub PAT — required for private repos. Sent as
+            ``Authorization: token <pat>`` header by ``resolve_source``.
     """
     from plugin_schema import load_plugin_manifest
     from plugin_loader import PluginInstaller, _parse_version
@@ -2316,7 +2327,7 @@ def _compute_preview(slug: str, source_url: str) -> dict:
 
     # Resolve candidate source (may hit network / tmp — outside the lock)
     try:
-        new_plugin_dir = PluginInstaller.resolve_source(source_url)
+        new_plugin_dir = PluginInstaller.resolve_source(source_url, auth_token=auth_token)
     except ValueError as exc:
         raise ValueError(f"invalid_source: {exc}") from exc
     except RuntimeError as exc:
@@ -2422,6 +2433,11 @@ def preview_plugin_update(slug: str):
     """Read-only diff preview before applying an update.
 
     Query param: ?source=<url>  (defaults to installed source_url when omitted)
+    Optional header ``X-Plugin-Auth-Token``: GitHub PAT required to fetch
+    candidate from a private repository (same semantics as ``auth_token`` on
+    ``POST /api/plugins/preview``). Kept out of the query string so it does
+    not leak into access logs.
+
     Returns 200 with diff JSON (or up_to_date: true).
     Never writes to disk or DB.
     """
@@ -2440,7 +2456,12 @@ def preview_plugin_update(slug: str):
     if not source_url:
         return jsonify({"error": "invalid_source", "message": "No source URL provided and none stored"}), 400
 
-    cache_key = (slug, source_url)
+    # Optional GitHub PAT for private repos (header only — never logged)
+    auth_token = request.headers.get("X-Plugin-Auth-Token") or None
+
+    # Cache key includes auth_token presence (not value) to avoid sharing
+    # private-repo results across unauthenticated requests.
+    cache_key = (slug, source_url, bool(auth_token))
 
     # Cache read — lock only around dict access, not network I/O
     with _PREVIEW_CACHE_LOCK:
@@ -2452,7 +2473,7 @@ def preview_plugin_update(slug: str):
 
     # Cache miss — compute outside lock
     try:
-        result = _compute_preview(slug, source_url)
+        result = _compute_preview(slug, source_url, auth_token=auth_token)
     except ValueError as exc:
         msg = str(exc)
         if msg.startswith("invalid_source:"):
@@ -2543,10 +2564,21 @@ def update_plugin(slug: str):
         data = request.get_json(force=True, silent=True) or {}
         source_url = data.get("source_url", installed_source)
 
+        # Optional GitHub PAT for private repos. Mirrors /api/plugins/install —
+        # body field first, falling back to ``X-Plugin-Auth-Token`` header for
+        # callers that reuse the same header they sent to update/preview.
+        auth_token = (
+            data.get("auth_token")
+            or request.headers.get("X-Plugin-Auth-Token")
+            or None
+        )
+
         # 3. Resolve new plugin source (accepts local path, github:..., https://...)
         from plugin_loader import PluginInstaller
         try:
-            new_plugin_dir = PluginInstaller.resolve_source(source_url)
+            new_plugin_dir = PluginInstaller.resolve_source(
+                source_url, auth_token=auth_token
+            )
         except ValueError as exc:
             return jsonify({"error": "invalid_source", "message": str(exc)}), 400
         except RuntimeError as exc:
 
@@ -0,0 +1,204 @@
+"""Proxy HTTP and WebSocket traffic to the local terminal-server.
+
+The terminal-server (Node, dashboard/terminal-server/bin/server.js) binds to
+a random port (commonly 32352) on 0.0.0.0. Browsers connecting to the
+dashboard from a different host than `localhost` historically had to hit
+that port directly, which fails in three common scenarios:
+
+1. Browsing via SSH tunnel (`ssh -L 8080:localhost:8080`) — only port 8080
+   is forwarded, the random terminal-server port is not.
+2. Browsing via a public tunnel (Tailscale Funnel, Cloudflare Tunnel, an
+   nginx reverse proxy on a VPS) — only the dashboard port is exposed.
+3. Browsing on a LAN where macOS Application Firewall hasn't whitelisted
+   the random port for the Node binary.
+
+Mounting a proxy on the same Flask app the user is already authenticated
+to fixes all three: the terminal-server is reachable wherever the
+dashboard is reachable, on the same origin, with no extra ports to
+expose.
+
+This module is intentionally minimal — it forwards bytes both ways for
+HTTP and WebSocket; it does not inspect or rewrite payloads.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+
+import requests
+from flask import Blueprint, Response, request, stream_with_context
+from flask_login import current_user, login_required
+
+log = logging.getLogger(__name__)
+
+bp = Blueprint("terminal_proxy", __name__)
+
+# Where the local terminal-server lives. The Node script defaults to 32352
+# but can be overridden — keep this in sync via env var.
+TERMINAL_HOST = os.environ.get("TERMINAL_SERVER_HOST", "127.0.0.1")
+TERMINAL_PORT = int(os.environ.get("TERMINAL_SERVER_PORT", "32352"))
+TERMINAL_HTTP_BASE = f"http://{TERMINAL_HOST}:{TERMINAL_PORT}"
+TERMINAL_WS_BASE = f"ws://{TERMINAL_HOST}:{TERMINAL_PORT}"
+
+# Hop-by-hop headers that must not be forwarded (RFC 7230 §6.1).
+_HOP_BY_HOP = frozenset(
+    {
+        "connection",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "te",
+        "trailers",
+        "transfer-encoding",
+        "upgrade",
+        "host",
+        "content-length",  # let requests/Flask compute it
+    }
+)
+
+
+def _forward_headers(src: dict[str, str]) -> dict[str, str]:
+    """Strip hop-by-hop headers before forwarding either direction."""
+    return {k: v for k, v in src.items() if k.lower() not in _HOP_BY_HOP}
+
+
+# ---------------------------------------------------------------------------
+# HTTP proxy — covers /api/health, /api/sessions/*, /api/notifications/*, etc.
+# ---------------------------------------------------------------------------
+
+@bp.route(
+    "/terminal/<path:subpath>",
+    methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+)
+@bp.route("/terminal", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"])
+@login_required
+def proxy_http(subpath: str = ""):
+    """Forward HTTP traffic to the local terminal-server."""
+    target = f"{TERMINAL_HTTP_BASE}/{subpath}"
+    if request.query_string:
+        target = f"{target}?{request.query_string.decode('latin-1')}"
+
+    try:
+        upstream = requests.request(
+            method=request.method,
+            url=target,
+            headers=_forward_headers(dict(request.headers)),
+            data=request.get_data(),
+            allow_redirects=False,
+            stream=True,
+            timeout=30,
+        )
+    except requests.exceptions.ConnectionError:
+        return (
+            "Terminal-server is not running. Start it via `make terminal-server` "
+            "or `node dashboard/terminal-server/bin/server.js --dev`.",
+            503,
+        )
+    except requests.exceptions.Timeout:
+        return "Terminal-server timed out.", 504
+
+    # Pass through status, body, headers (minus hop-by-hop).
+    response = Response(
+        stream_with_context(upstream.iter_content(chunk_size=8192)),
+        status=upstream.status_code,
+    )
+    for key, value in upstream.headers.items():
+        if key.lower() not in _HOP_BY_HOP:
+            response.headers[key] = value
+    return response
+
+
+# ---------------------------------------------------------------------------
+# WebSocket proxy — terminal stream + notifications
+# ---------------------------------------------------------------------------
+# Registered at app-creation time via `register_websocket_proxy(sock)` so
+# we can use the shared `flask_sock.Sock` instance the rest of the app uses.
+
+def register_websocket_proxy(sock) -> None:
+    """Register the /terminal/ws WebSocket proxy on the given Sock instance.
+
+    Why not a plain `@bp.route` decorator: flask-sock requires its own
+    `@sock.route(...)` decorator, and the Sock instance is created in
+    ``app.py``. Calling this from there keeps the dependency one-way.
+    """
+    try:
+        from websocket import create_connection  # type: ignore
+    except ImportError:
+        log.warning(
+            "terminal_proxy.register_websocket_proxy: websocket-client not "
+            "installed; WebSocket proxy disabled. Add `websocket-client` "
+            "to dependencies."
+        )
+        return
+
+    @sock.route("/terminal/ws")
+    def proxy_ws(client_ws):
+        """Bidirectional bridge: browser <-> Flask <-> terminal-server.
+
+        Auth: the global ``auth_middleware`` only gates ``/api/*`` and
+        ``/ws/*`` paths, so a request to ``/terminal/ws`` is *not* checked
+        upstream. Without the explicit ``current_user.is_authenticated``
+        guard below, anyone able to reach the dashboard (LAN, Tailscale
+        Funnel, Cloudflare Tunnel, public VPS) could open a PTY on the
+        host. flask-login's session cookie is read from the WS upgrade
+        request, so this works the same as ``@login_required`` on HTTP
+        routes.
+        """
+        if not current_user.is_authenticated:
+            try:
+                client_ws.close(reason="auth required")
+            except Exception:
+                pass
+            return
+
+        target = f"{TERMINAL_WS_BASE}/ws"
+        try:
+            upstream = create_connection(target, timeout=10)
+        except Exception as exc:
+            log.warning("terminal_proxy: upstream WS connect failed: %s", exc)
+            try:
+                client_ws.close(reason=f"upstream unreachable: {exc}")
+            except Exception:
+                pass
+            return
+
+        stop = threading.Event()
+
+        def _pump_upstream_to_client():
+            try:
+                while not stop.is_set():
+                    msg = upstream.recv()
+                    if msg is None or msg == b"":
+                        break
+                    if isinstance(msg, bytes):
+                        client_ws.send(msg)
+                    else:
+                        client_ws.send(msg)
+            except Exception:
+                pass
+            finally:
+                stop.set()
+                try:
+                    client_ws.close()
+                except Exception:
+                    pass
+
+        t = threading.Thread(target=_pump_upstream_to_client, daemon=True)
+        t.start()
+
+        try:
+            while not stop.is_set():
+                msg = client_ws.receive(timeout=30)
+                if msg is None:
+                    break
+                upstream.send(msg)
+        except Exception:
+            pass
+        finally:
+            stop.set()
+            try:
+                upstream.close()
+            except Exception:
+                pass