davinci-resolve-mcp 2.97.7 → 2.98.0

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.98.0
+
+**The control panel could be driven by any web page you visited.** Reported
+privately, with the chain worked out end to end. Fixed here; the transport
+state file and panel pidfile move out of shared locations at the same time.
+
+### Security
+
+- **`GET /api/mcp/status` handed out the networked-transport bearer token to
+  anyone who could reach the port.** It was the one privileged route with no
+  loopback check, and its payload included the token that authenticates the
+  `--transport streamable-http` MCP instance — i.e. full Resolve control.
+- **No Host or Origin check, and POST bodies of any Content-Type were parsed.**
+  A page on any site could POST to the panel (CSRF), and a DNS-rebinding page
+  could read its responses. Chained: visit a page → it starts the networked
+  transport via `/api/mcp/transport/start` → reads the token from
+  `/api/mcp/status` → owns the MCP toolset.
+- **The bind address was a tool parameter.** `open_control_panel(host=...)`
+  passed straight through, so a prompt could put the unauthenticated panel on
+  `0.0.0.0`.
+
+  What changed:
+
+  - **Per-launch bearer token on every route except the static shell at `/`.**
+    `open_control_panel` mints `secrets.token_urlsafe(32)`, passes it to the
+    child through the environment (not argv, which `ps` shows to every local
+    user), records it 0600, and returns the URL with the token in the
+    **fragment** (`http://127.0.0.1:8765/#token=…`) — browsers never send
+    fragments, so it stays out of request lines and logs. The panel JS keeps
+    it in `localStorage`, sends `Authorization: Bearer …` on every fetch, and
+    exchanges it once (`POST /api/session`) for an `HttpOnly; SameSite=Strict`
+    cookie so thumbnail `<img>` loads work. A bare `http://127.0.0.1:8765` now
+    shows a "Control panel locked" screen pointing back to `open_control_panel`.
+  - **A single gate at the top of `do_GET`/`do_POST`:** `Host` must be a
+    loopback host (defeats DNS rebinding); `Origin`, when present, must be a
+    loopback origin (defeats CSRF); `POST` must be
+    `Content-Type: application/json` (a cross-site form cannot send it, and a
+    cross-site `fetch()` with it needs a CORS preflight the panel never
+    answers). Each check fails closed with 403/415 before any route runs.
+  - **`host` is no longer an AI knob.** `open_control_panel` refuses anything
+    but `127.0.0.1` / `localhost` / `::1` with no override, and
+    `src.analysis_dashboard --host` does the same at argparse — matching the
+    free-edition bridge, which already threw on non-loopback.
+  - **Secrets on disk are private.** The transport state file
+    (`mcp_transport.json`, holds the transport token) leaves
+    `tempfile.gettempdir()`, and the panel pidfile (now holds the panel token)
+    leaves `~/Documents`; both live under `~/.davinci-resolve-mcp/` (0700),
+    written 0600 via the new `src/utils/private_state.py`, with a best-effort
+    `icacls` restriction on Windows. `DAVINCI_RESOLVE_MCP_STATE_DIR` overrides
+    the directory.
+  - **The launcher still recognises a panel it has no token for.** A panel
+    that survived an MCP restart from before this scheme answers 401 with a
+    self-identifying body; `open_control_panel` reports it as `stale_running`
+    (nobody can log in to it) with the `force_restart=true` remediation
+    instead of handing out an unusable URL.
+
+  `SECURITY.md` previously said the server "does not expose a network
+  listener"; it now describes both opt-in local HTTP surfaces (panel and
+  networked transport) and their posture. Kept as-is: the default port stays
+  8765 (with Host/Origin/token in place its guessability is not the barrier)
+  and the transport token is still shown in the panel's MCP card, now behind
+  the panel's own auth.
+
+### Added
+
+- `tests.test_control_panel_auth` boots the real `Handler` on an ephemeral
+  port and asserts each guard over HTTP: `/api/mcp/status` 401 without the
+  token and no transport secret in the 401 body; non-loopback `Host` rejected
+  even with a valid token; `localhost` / `[::1]` / bare `127.0.0.1` accepted;
+  cross-site `Origin` rejected; non-JSON POST → 415; no CORS preflight answer;
+  cookie issued only via bearer, `HttpOnly` + `SameSite=Strict`, then
+  sufficient on its own; wrong token / wrong cookie → 401; the static shell
+  never contains the token. Plus the launcher's 401-probe recognition, the
+  `host=0.0.0.0` refusal, and 0600 on the private state files.
+  `tests.test_open_control_panel` gains the token-unknown → `stale_running`
+  case and asserts the issued URL is the token-bearing one.
+
 ## What's New in v2.97.7
 
 **`grab_and_export` deleted files it never created.** Reported in

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.97.7-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.98.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-35%20(353%20full)-blue.svg)](#server-modes)
@@ -103,7 +103,7 @@ Launch the single-user local control panel from the repository root:
 venv/bin/python -m src.control_panel
 ```
 
-The command starts a localhost server and opens the control panel in your browser. To have an AI coding agent do this, ask: **"Open the Resolve MCP control panel for this repo."** Agents should use `venv/bin/python -m src.control_panel` unless your Python environment is already active. Persisted analysis jobs refresh the local search index automatically after successful slices; the manual Build Index action is for rebuilding from existing reports.
+The command starts a loopback-only server and opens the control panel in your browser at a URL that carries a per-launch access token (`http://127.0.0.1:8765/#token=…`) — use that exact URL; the panel refuses requests without it. To have an AI coding agent do this, ask: **"Open the Resolve MCP control panel for this repo."** Agents should use `venv/bin/python -m src.control_panel` unless your Python environment is already active. Persisted analysis jobs refresh the local search index automatically after successful slices; the manual Build Index action is for rebuilding from existing reports.
 
 ## Server Modes
 
@@ -266,7 +266,7 @@ This project treats camera originals and source media as immutable. Analysis too
 
 ## Security Posture
 
-The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. See [Security Policy](SECURITY.md) for operational boundaries, confirmation guidance, and vulnerability reporting.
+The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. The two opt-in local HTTP surfaces — the control panel and the networked MCP transport — bind loopback only and require a per-launch bearer token on every request, with Host/Origin checks against DNS rebinding and CSRF. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. See [Security Policy](SECURITY.md) for operational boundaries, confirmation guidance, and vulnerability reporting.
 
 ## Key Stats
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.97.7-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.98.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-35%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.97.7 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.98.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -75,7 +75,7 @@ launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
 venv/bin/python -m src.control_panel
 ```
 
-该命令启动一个 localhost 服务器并在浏览器中打开控制面板。想让 AI 编码助手代劳，可以说：**"Open the Resolve MCP control panel for this repo."** 除非你的 Python 环境已激活，否则 agent 应使用 `venv/bin/python -m src.control_panel`。持久化的分析任务在切片成功后会自动刷新本地搜索索引；手动的 Build Index 按钮用于从已有报告重建索引。
+该命令启动一个仅绑定回环地址的服务器，并在浏览器中以带每次启动令牌的 URL（`http://127.0.0.1:8765/#token=…`）打开控制面板——请使用这个完整 URL，面板会拒绝不带令牌的请求。想让 AI 编码助手代劳，可以说：**"Open the Resolve MCP control panel for this repo."** 除非你的 Python 环境已激活，否则 agent 应使用 `venv/bin/python -m src.control_panel`。持久化的分析任务在切片成功后会自动刷新本地搜索索引；手动的 Build Index 按钮用于从已有报告重建索引。
 
 ## 服务器模式
 
@@ -190,7 +190,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 ## 安全态势
 
-默认服务器是由你的 MCP 客户端启动的本地 stdio 进程；它不暴露网络监听器，也没有内置多用户认证面。工具元数据包含面向 MCP 客户端的安全提示（只读、破坏性、幂等、外部资源操作）。操作边界、确认指引和漏洞报告见 [安全策略](SECURITY.md)。
+默认服务器是由你的 MCP 客户端启动的本地 stdio 进程；它不暴露网络监听器，也没有内置多用户认证面。两个可选的本地 HTTP 面——控制面板与联网 MCP 传输——仅绑定回环地址，每个请求都需要每次启动生成的 bearer 令牌，并校验 Host/Origin 以防 DNS 重绑定和 CSRF。工具元数据包含面向 MCP 客户端的安全提示（只读、破坏性、幂等、外部资源操作）。操作边界、确认指引和漏洞报告见 [安全策略](SECURITY.md)。
 
 ## 关键数据
 

package/SECURITY.md

@@ -6,10 +6,45 @@
 Resolve Studio through the official Resolve Scripting API. It is intended to run
 under the same local user account that operates Resolve.
 
-The default server does not expose a network listener, HTTP API, remote shell, or
+The default stdio server does not expose a network listener, remote shell, or
 multi-user authentication surface. Access control is delegated to the MCP client
 that launches the stdio process and to the local operating-system user session.
 
+Two opt-in surfaces DO open local HTTP listeners, and both are hardened the same
+way:
+
+- **The control panel** (`resolve_control action=open_control_panel`,
+  `python -m src.control_panel`) — a single-user browser UI on
+  `127.0.0.1:8765` by default.
+- **The networked MCP transport** (`--transport sse|streamable-http`) — a
+  second MCP instance for remote clients, on `127.0.0.1:8000` by default.
+
+Their posture:
+
+- **Loopback only.** The panel refuses any bind host other than
+  `127.0.0.1` / `localhost` / `::1` — the bind address is not a tool parameter
+  an AI can widen. The transport defaults to loopback and logs a loud warning
+  if `DAVINCI_MCP_HOST` points elsewhere.
+- **Bearer token on every request.** Each panel launch generates a fresh
+  `secrets.token_urlsafe(32)` token, passed to the child via environment (not
+  argv) and delivered to the browser in the URL fragment (`#token=…`), which
+  never reaches the server or its logs. Every route except the static shell at
+  `/` returns 401 without it (`Authorization: Bearer …`, or the HttpOnly,
+  `SameSite=Strict` session cookie the panel exchanges it for so image loads
+  work). The transport requires `Authorization: Bearer <token>` on every request.
+- **DNS-rebinding and CSRF guards.** The panel rejects any request whose
+  `Host` header is not a loopback host, any request carrying a non-loopback
+  `Origin`, and any `POST` that is not `Content-Type: application/json`. It
+  never answers a CORS preflight, so no third-party page can call it.
+- **Secrets on disk are private.** The panel's pidfile (token + pid + URL) and
+  the transport's state file (token + URL) live under
+  `~/.davinci-resolve-mcp/` (0700) and are written 0600 — never in a shared
+  temp directory or `~/Documents`.
+
+If you find a route that can be reached without the token, or a way to satisfy
+the Host/Origin checks from a non-loopback page, that is a security bug — please
+report it (see below).
+
 ## Operational Boundaries
 
 - Keep Resolve external scripting set to **Local** unless you have a separate,

package/docs/SKILL.md

@@ -327,7 +327,10 @@ venv/bin/python -m src.control_panel
 
 The command starts the local control panel and opens the default browser. Use
 `--no-open` when running in a headless context, then give the user the printed
-localhost URL. The panel is local and single-user; it is an operational surface
+localhost URL **exactly as printed** — it carries a per-launch bearer token in
+its fragment (`#token=…`) and the panel refuses every request without it. The
+panel binds loopback only (a non-loopback host is refused, no override) and is
+single-user; it is an operational surface
 for server status, Resolve clips, source-safe analysis jobs, preferences, and
 diagnostics as those sections are added.
 

package/docs/guides/control-panel.md

@@ -5,8 +5,17 @@ for inspecting Resolve state, running source-safe media analysis, drilling into
 analyzed clips and shots, fixing analysis output inline, reviewing timeline
 edit history, driving Resolve's local AI operations, and managing preferences.
 
-The panel is a local HTTP server (default `http://127.0.0.1:8765`). It does not
-expose a network listener beyond loopback and does not modify source media.
+The panel is a local HTTP server (default `http://127.0.0.1:8765`). It binds
+loopback only — a non-loopback `--host` / `host` is refused, with no override —
+and does not modify source media.
+
+Every launch mints a per-launch bearer token. The launcher hands it to the
+browser in the URL fragment (`http://127.0.0.1:8765/#token=…`); the panel
+answers 401 to every request that doesn't carry it, so **use the exact URL the
+launcher prints or `open_control_panel` returns** — a bare
+`http://127.0.0.1:8765` shows a "Control panel locked" screen. Requests with a
+non-loopback `Host` or `Origin`, or a non-JSON `POST`, are rejected outright
+(DNS-rebinding / CSRF guards). See `SECURITY.md` for the full posture.
 
 ## Launching the panel
 
@@ -22,7 +31,11 @@ resolve_control(action="open_control_panel")
 ```
 
 Once running, `resolve_control(action="control_panel_status")` checks the
-pidfile and `resolve_control(action="close_control_panel")` stops it.
+pidfile (`~/.davinci-resolve-mcp/control_panel.json`, 0600 — it holds the
+token) and returns the token-bearing URL; `resolve_control(action="close_control_panel")`
+stops it. A panel whose token is not on record (e.g. one that survived an MCP
+restart from before this scheme) is reported as `stale_running`; re-call
+`open_control_panel` with `force_restart=true` to relaunch it.
 
 ## Navigation and deep links
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.97.7"
+VERSION = "2.98.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.97.7",
+  "version": "2.98.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -9,6 +9,7 @@ import hashlib
 import json
 import os
 import re
+import secrets
 import sqlite3
 import sys
 import threading
@@ -5048,6 +5049,44 @@ HTML = r"""<!doctype html>
   <script>
     /* CONTROL_PANEL_I18N */
 
+    // ─── Panel auth ─────────────────────────────────────────────────────
+    // The launcher hands the per-launch bearer token over in the URL
+    // fragment (#token=…). Fragments never leave the browser, so the token
+    // is not in any request line or log. It is kept in localStorage for this
+    // origin, sent as Authorization on every fetch, and exchanged once for an
+    // HttpOnly cookie (POST /api/session) so <img src="/api/…"> loads work.
+    const PANEL_TOKEN_KEY = 'davinci_panel_token';
+    function captureLaunchToken() {
+      const m = window.location.hash.match(/^#token=([A-Za-z0-9_-]+)(?:&(.*))?$/);
+      if (!m) return;
+      try { localStorage.setItem(PANEL_TOKEN_KEY, m[1]); } catch (_) { /* private mode */ }
+      const rest = m[2] ? `#${m[2]}` : window.location.pathname + window.location.search;
+      history.replaceState(null, '', rest);
+    }
+    function panelToken() {
+      try { return localStorage.getItem(PANEL_TOKEN_KEY) || ''; } catch (_) { return ''; }
+    }
+    function authHeaders(extra = {}) {
+      const token = panelToken();
+      return token ? { Authorization: `Bearer ${token}`, ...extra } : { ...extra };
+    }
+    // Runs before anything else in this script so no request goes out tokenless.
+    captureLaunchToken();
+    let panelLockShown = false;
+    function showPanelLocked() {
+      if (panelLockShown) return;
+      panelLockShown = true;
+      document.body.innerHTML = `
+        <div style="min-height:100vh;display:flex;align-items:center;justify-content:center;background:#0b0f14;color:#e6edf3;font:14px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;">
+          <div style="max-width:520px;padding:32px;border:1px solid #1f2937;border-radius:8px;background:#111827;">
+            <div style="font-size:18px;font-weight:600;margin-bottom:8px;">Control panel locked</div>
+            <div style="color:#9ca3af;">This panel only answers to the URL it was launched with — the one containing its
+            per-launch token. Ask your MCP client to run
+            <code style="color:#1E90FF;">resolve_control(action="open_control_panel")</code>
+            and open the URL it returns.</div>
+          </div>
+        </div>`;
+    }
     const state = {
       boot: null,
       projects: null,
@@ -5228,9 +5267,13 @@ HTML = r"""<!doctype html>
 
     async function api(path, options = {}) {
       const res = await fetch(path, {
-        headers: { 'Content-Type': 'application/json' },
         ...options,
+        headers: authHeaders({ 'Content-Type': 'application/json', ...(options.headers || {}) }),
       });
+      if (res.status === 401) {
+        showPanelLocked();
+        throw new Error('Control panel is not authorized — reopen it from your MCP client.');
+      }
       const payload = await res.json();
       if (!res.ok || payload.success === false) {
         throw new Error(payload.error || res.statusText);
@@ -6463,6 +6506,13 @@ HTML = r"""<!doctype html>
     }
 
     async function boot() {
+      if (!panelToken()) {
+        showPanelLocked();
+        return;
+      }
+      // Exchange the bearer token for the HttpOnly session cookie first so
+      // thumbnail <img> loads (which cannot carry headers) are authorized.
+      await api('/api/session', { method: 'POST', body: '{}' });
       state.boot = await api('/api/boot');
       state.activeContext = state.boot.active_context || {
         project_name: state.boot.project_name,
@@ -6627,9 +6677,10 @@ HTML = r"""<!doctype html>
         // No `limit` param: the server applies the media_analysis.inventory_limit
         // preference, and sending one here would override what the user configured.
         const query = options.silent ? '?probe=0&reuse=1' : '';
-        const headers = {};
+        const headers = authHeaders();
         if (state.mediaETag) headers['If-None-Match'] = state.mediaETag;
         const res = await fetch(`/api/resolve/media${query}`, { headers, cache: 'no-store' });
+        if (res.status === 401) { showPanelLocked(); return; }
         state.mediaLastRefresh = new Date();
         state.resolveMediaStale = false;
         if (res.status === 304) return;
@@ -11593,7 +11644,7 @@ HTML = r"""<!doctype html>
       if (!Array.isArray(clipIds) || !clipIds.length) return;
       const result = await fetch('/api/clips/export', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: authHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ clip_ids: clipIds, format }),
       });
       if (!result.ok) {
@@ -14429,6 +14480,75 @@ def _request_is_loopback(handler: BaseHTTPRequestHandler) -> bool:
     return addr in {"127.0.0.1", "::1", "localhost"}
 
 
+# ─── Panel request gate ───────────────────────────────────────────────────────
+# Every request passes through Handler._gate() before any route runs:
+#   1. Host header must name a loopback host  → defeats DNS rebinding.
+#   2. Origin header (when present) must be a loopback origin → defeats CSRF
+#      from any web page (browsers always attach Origin to cross-site POSTs).
+#   3. POST bodies must be application/json → a cross-site form post can't
+#      satisfy it, and a cross-site fetch() with that header needs a CORS
+#      preflight, which this server never answers.
+#   4. Everything except the static shell at "/" needs the panel bearer token
+#      (Authorization header, or the HttpOnly cookie set by POST /api/session
+#      so <img> loads work). The token is generated per launch and handed to
+#      the browser in the URL fragment, which never reaches the server.
+PANEL_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "[::1]"})
+PANEL_PUBLIC_GET_PATHS = frozenset({"/"})
+PANEL_COOKIE_NAME = "davinci_panel_token"
+PANEL_TOKEN_ENV = "DAVINCI_PANEL_TOKEN"
+
+
+def resolve_panel_token() -> str:
+    """Token from $DAVINCI_PANEL_TOKEN (set by the MCP launcher) or a fresh one."""
+    return os.environ.get(PANEL_TOKEN_ENV) or secrets.token_urlsafe(32)
+
+
+def _host_header_name(value: Optional[str]) -> str:
+    """Return the host part of a Host header (port stripped, lowercased)."""
+    raw = (value or "").strip().lower()
+    if not raw:
+        return ""
+    if raw.startswith("["):
+        end = raw.find("]")
+        return raw[: end + 1] if end != -1 else raw
+    if raw.count(":") == 1:
+        return raw.split(":", 1)[0]
+    return raw
+
+
+def _host_is_loopback(value: Optional[str]) -> bool:
+    return _host_header_name(value) in PANEL_LOOPBACK_HOSTS
+
+
+def _origin_is_loopback(value: Optional[str]) -> bool:
+    try:
+        parsed = urlparse((value or "").strip())
+    except ValueError:
+        return False
+    if parsed.scheme not in {"http", "https"}:
+        return False
+    host = (parsed.hostname or "").lower()
+    return host in PANEL_LOOPBACK_HOSTS
+
+
+def _cookie_value(cookie_header: Optional[str], name: str) -> Optional[str]:
+    for part in (cookie_header or "").split(";"):
+        key, sep, val = part.strip().partition("=")
+        if sep and key.strip() == name:
+            return val.strip()
+    return None
+
+
+def _request_presents_token(handler: BaseHTTPRequestHandler, token: str) -> bool:
+    if not token:
+        return False
+    auth = handler.headers.get("Authorization") or ""
+    if auth.startswith("Bearer ") and secrets.compare_digest(auth[len("Bearer "):].strip(), token):
+        return True
+    cookie = _cookie_value(handler.headers.get("Cookie"), PANEL_COOKIE_NAME)
+    return bool(cookie) and secrets.compare_digest(cookie, token)
+
+
 def _launch_claude_code_terminal() -> Dict[str, Any]:
     """Open a Terminal/iTerm window at the MCP server's project root running
     the ``claude`` CLI. macOS only — other platforms return a clipboard-only
@@ -15155,6 +15275,7 @@ def _inventory_prefs() -> Tuple[int, Optional[set]]:
 
 class Handler(BaseHTTPRequestHandler):
     state: DashboardState
+    token: str = ""
 
     def log_message(self, fmt: str, *args: Any) -> None:
         return
@@ -15243,14 +15364,77 @@ class Handler(BaseHTTPRequestHandler):
             return {}
         return payload if isinstance(payload, dict) else {}
 
+    def _gate(self) -> bool:
+        """Run the request through the panel security gate; False = already answered."""
+        path = urlparse(self.path).path
+        if not _host_is_loopback(self.headers.get("Host")):
+            self._json(
+                {"success": False, "error": "Rejected: Host header is not a loopback host (DNS-rebinding guard)."},
+                HTTPStatus.FORBIDDEN,
+            )
+            return False
+        origin = self.headers.get("Origin")
+        if origin is not None and not _origin_is_loopback(origin):
+            self._json(
+                {"success": False, "error": "Rejected: cross-site origin (CSRF guard)."},
+                HTTPStatus.FORBIDDEN,
+            )
+            return False
+        if self.command == "POST":
+            ctype = (self.headers.get("Content-Type") or "").split(";", 1)[0].strip().lower()
+            if ctype != "application/json":
+                self._json(
+                    {"success": False, "error": "POST requests must be Content-Type: application/json."},
+                    HTTPStatus.UNSUPPORTED_MEDIA_TYPE,
+                )
+                return False
+        if self.command == "GET" and path in PANEL_PUBLIC_GET_PATHS:
+            return True
+        if _request_presents_token(self, getattr(self, "token", "") or ""):
+            return True
+        # The launcher probes this on 401 to recognise a live panel + its version
+        # without a token, so the payload names itself.
+        self._json(
+            {
+                "success": False,
+                "error": "unauthorized: this control panel requires its launch token. "
+                         "Reopen it from your MCP client (resolve_control action=open_control_panel) "
+                         "and use the returned URL.",
+                "panel": "davinci-resolve-mcp",
+                "mcp_version": _mcp_version(),
+            },
+            HTTPStatus.UNAUTHORIZED,
+        )
+        return False
+
+    def _set_session_cookie(self) -> None:
+        """POST /api/session (bearer-authenticated) → HttpOnly cookie for <img> loads."""
+        raw = json.dumps({"success": True}).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(raw)))
+        self.send_header(
+            "Set-Cookie",
+            f"{PANEL_COOKIE_NAME}={self.token}; Path=/; HttpOnly; SameSite=Strict",
+        )
+        self.end_headers()
+        self.wfile.write(raw)
+
     def do_GET(self) -> None:
         try:
+            if not self._gate():
+                return
             self._route_get()
         except Exception as exc:  # pragma: no cover - runtime safety for dashboard users
             self._json({"success": False, "error": str(exc)}, HTTPStatus.INTERNAL_SERVER_ERROR)
 
     def do_POST(self) -> None:
         try:
+            if not self._gate():
+                return
+            if urlparse(self.path).path == "/api/session":
+                self._set_session_cookie()
+                return
             self._route_post()
         except Exception as exc:  # pragma: no cover
             self._json({"success": False, "error": str(exc)}, HTTPStatus.INTERNAL_SERVER_ERROR)
@@ -15920,9 +16104,19 @@ class Handler(BaseHTTPRequestHandler):
         self._json({"success": False, "error": "Not found"}, HTTPStatus.NOT_FOUND)
 
 
+def _loopback_host(value: str) -> str:
+    """argparse type: the panel binds loopback only — anything else is refused."""
+    if value not in PANEL_LOOPBACK_HOSTS:
+        raise argparse.ArgumentTypeError(
+            f"control panel host must be loopback (127.0.0.1 / localhost / ::1), got {value!r} — "
+            "the panel is a single-user local UI and is never bound to a routable interface"
+        )
+    return value
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Run the local Resolve MCP control panel.")
-    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--host", default="127.0.0.1", type=_loopback_host)
     parser.add_argument("--port", type=int, default=8765)
     parser.add_argument("--project-name", default="Dashboard Analysis")
     parser.add_argument("--project-id", default="dashboard")
@@ -15955,10 +16149,15 @@ def main() -> None:
     args = parse_args()
     state = DashboardState(args.project_name, args.project_id, args.analysis_root)
     Handler.state = state
+    Handler.token = resolve_panel_token()
     server = ThreadingHTTPServer((args.host, args.port), Handler)
-    url = f"http://{args.host}:{args.port}"
-    print(f"DaVinci Resolve MCP: {url}")
-    print(f"Project analysis root: {state.project_root}")
+    # The token rides in the URL fragment: browsers keep fragments client-side,
+    # so it never appears in a request line, proxy log, or Referer.
+    url = f"http://{args.host}:{args.port}/#token={Handler.token}"
+    # flush: under --no-open the URL (with its token) is the only handle the
+    # operator gets, and a piped/redirected stdout would otherwise hold it back.
+    print(f"DaVinci Resolve MCP: {url}", flush=True)
+    print(f"Project analysis root: {state.project_root}", flush=True)
     threading.Thread(target=_warm_inventory_cache, args=(state.project_root,), daemon=True).start()
     if args.open:
         webbrowser.open(url)

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.97.7"
+VERSION = "2.98.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.97.7"
+VERSION = "2.98.0"
 
 import base64
 import os
@@ -14452,9 +14452,13 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         the preset is then named after the file, so pass name when the preset
         should be called something the filename does not say.
       export_user_preferences_preset(name, path) -> {success}  — Resolve 21.0.4+
-      open_control_panel(port?, host?, open_browser?) -> {success, url, pid, port, status}
+      open_control_panel(port?, open_browser?, force_restart?) -> {success, url, pid, port, status}
         — Launches the analysis control panel (src/analysis_dashboard.py) as a background process.
-          Idempotent: returns the existing URL if already running.
+          Idempotent: returns the existing URL if already running. Binds
+          127.0.0.1 ONLY — a `host` other than loopback is refused, there is no
+          override. The returned url carries a per-launch bearer token in its
+          fragment (#token=…); the panel refuses every request without it, so
+          give the user that exact URL, not a bare http://127.0.0.1:8765.
       control_panel_status() -> {running, pid, port, url}
       close_control_panel() -> {success, was_running}
       save_state() -> {state_token, page, current_timeline_id, current_timecode, selected_clip_ids}
@@ -15119,7 +15123,10 @@ def _v2_list_corrections(project_root: str, p: Dict[str, Any]) -> Dict[str, Any]
 # ─── V2 P12: Control panel lifecycle ──────────────────────────────────────────
 
 def _control_panel_pidfile() -> str:
-    return os.path.expanduser("~/Documents/davinci-resolve-mcp-analysis/.control_panel.pid")
+    # Holds the panel's per-launch bearer token alongside pid/port, so it lives
+    # in the 0700 private state dir and is written 0600 — not in ~/Documents.
+    from src.utils.private_state import private_state_dir
+    return os.path.join(private_state_dir(), "control_panel.json")
 
 
 def _control_panel_read_state() -> Optional[Dict[str, Any]]:
@@ -15134,6 +15141,15 @@ def _control_panel_read_state() -> Optional[Dict[str, Any]]:
         return None
 
 
+def _control_panel_read_token() -> Optional[str]:
+    state = _control_panel_read_state() or {}
+    token = state.get("token")
+    return str(token) if token else None
+
+
+_CONTROL_PANEL_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
+
+
 def _control_panel_pid_alive(pid: int) -> bool:
     """Check whether a PID is alive on this OS without killing it."""
     if not pid or pid <= 0:
@@ -15204,24 +15220,40 @@ def _pick_dashboard_python(repo_root: str) -> Tuple[str, Optional[str]]:
     return _sys.executable, "sys.executable"
 
 
-def _control_panel_probe(host: str, port: int, timeout: float = 1.5) -> Dict[str, Any]:
+def _control_panel_probe(host: str, port: int, timeout: float = 1.5,
+                         token: Optional[str] = None) -> Dict[str, Any]:
     """Probe a port to see whether a dashboard is listening and what version.
 
     Returns ``{"is_dashboard": bool, "version": Optional[str]}``.
 
     - ``is_dashboard`` is True when /api/boot responds with a recognizable
-      dashboard payload (``success: true`` plus a project field). This lets
-      callers distinguish an older dashboard that predates the
-      ``mcp_version`` surface from a non-dashboard process squatting on the
-      port.
+      dashboard payload (``success: true`` plus a project field), OR answers
+      401 with the panel's self-identifying body (a live panel whose token we
+      do not hold). This lets callers distinguish an older dashboard that
+      predates the ``mcp_version`` surface from a non-dashboard process
+      squatting on the port.
     - ``version`` is the reported MCP version, or None if the dashboard
       predates the field.
     """
+    import urllib.error
     import urllib.request
     url = f"http://{host}:{port}/api/boot"
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
     try:
-        with urllib.request.urlopen(url, timeout=timeout) as resp:
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
             payload = json.loads(resp.read().decode("utf-8") or "{}")
+    except urllib.error.HTTPError as exc:
+        if exc.code != 401:
+            return {"is_dashboard": False, "version": None}
+        try:
+            payload = json.loads(exc.read().decode("utf-8") or "{}")
+        except Exception:
+            return {"is_dashboard": False, "version": None}
+        if not isinstance(payload, dict) or payload.get("panel") != "davinci-resolve-mcp":
+            return {"is_dashboard": False, "version": None}
+        version = payload.get("mcp_version")
+        return {"is_dashboard": True, "version": str(version) if version else None}
     except Exception:
         return {"is_dashboard": False, "version": None}
     if not isinstance(payload, dict):
@@ -15271,7 +15303,13 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
     import socket
     import time as _t
 
-    host = p.get("host") or "127.0.0.1"
+    host = str(p.get("host") or "127.0.0.1")
+    if host not in _CONTROL_PANEL_LOOPBACK_HOSTS:
+        return _err(
+            f"host={host!r} refused: the control panel binds loopback only "
+            "(127.0.0.1 / localhost / ::1). It is a single-user local UI and is "
+            "never exposed to the network — there is no override.",
+        )
     port = int(p.get("port") or 8765)
     force_restart = _media_analysis_bool(p.get("force_restart", p.get("forceRestart")), False)
 
@@ -15290,27 +15328,36 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
     live_version = VERSION
 
     if port_pid is not None and not force_restart:
-        probe = _control_panel_probe(host, port)
-        tracked_url = (existing or {}).get("url") if existing.get("running") else None
-        url = tracked_url or f"http://{host}:{port}"
+        tracked = existing if existing.get("running") else {}
+        tracked_token = _control_panel_read_token() if tracked else None
+        probe = _control_panel_probe(host, port, token=tracked_token)
+        url = tracked.get("url") or f"http://{host}:{port}"
         if probe["is_dashboard"]:
             remote_version = probe["version"]
             # Compare with explicit None handling: an older dashboard that
             # predates the mcp_version field is also stale — it can't honor
-            # newer surfaces and the caller needs to know.
-            if remote_version != live_version:
+            # newer surfaces and the caller needs to know. A panel whose token
+            # we don't hold (untracked survivor) is unusable too: nobody can
+            # log in to it, so it must be relaunched.
+            if remote_version != live_version or not tracked_token:
                 reported = remote_version or "unknown (predates the mcp_version field)"
+                why = (
+                    f"The running control panel reports version {reported} but the "
+                    f"MCP server is at {live_version}."
+                    if remote_version != live_version else
+                    "The running control panel's launch token is not on record, so "
+                    "its URL cannot be issued."
+                )
                 return {
                     "success": True,
                     "status": "stale_running",
-                    "url": url,
+                    "url": url if tracked_token else None,
                     "pid": port_pid,
                     "port": port,
                     "running_version": remote_version,
                     "live_version": live_version,
                     "remediation": (
-                        f"The running control panel reports version {reported} but the "
-                        f"MCP server is at {live_version}. Re-call open_control_panel with "
+                        f"{why} Re-call open_control_panel with "
                         "force_restart=true to terminate the stale process and relaunch."
                     ),
                 }
@@ -15377,6 +15424,14 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
     else:
         cmd.append("--no-open")
 
+    # Per-launch bearer token. Passed via the environment (never argv, which
+    # `ps` would show to every local user) and recorded 0600 in the pidfile so
+    # later status/already-running calls can hand out the same URL.
+    import secrets as _secrets
+    panel_token = _secrets.token_urlsafe(32)
+    child_env = dict(os.environ)
+    child_env["DAVINCI_PANEL_TOKEN"] = panel_token
+
     # Detach so the dashboard outlives this MCP call.
     log_path = os.path.join(os.path.expanduser("~/Documents/davinci-resolve-mcp-analysis"), ".control_panel.log")
     try:
@@ -15389,6 +15444,7 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
         proc = subprocess.Popen(
             cmd,
             cwd=repo_root,
+            env=child_env,
             stdout=log_handle,
             stderr=subprocess.STDOUT,
             stdin=subprocess.DEVNULL,
@@ -15437,13 +15493,16 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
             f"(pid {proc.pid}). Check {log_path} for details.",
         )
 
-    # Write the pidfile so subsequent calls find it
-    url = f"http://{host}:{port}"
+    # Write the pidfile so subsequent calls find it. The token travels in the
+    # URL fragment — browsers never send fragments, so it stays out of every
+    # request line and log.
+    url = f"http://{host}:{port}/#token={panel_token}"
     state = {
         "pid": proc.pid,
         "port": port,
         "host": host,
         "url": url,
+        "token": panel_token,
         "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
         "project_name": project_name,
         "project_id": project_id,
@@ -15453,9 +15512,8 @@ def _open_control_panel(p: Dict[str, Any]) -> Dict[str, Any]:
         "python_source": python_source,
     }
     try:
-        os.makedirs(os.path.dirname(_control_panel_pidfile()), exist_ok=True)
-        with open(_control_panel_pidfile(), "w", encoding="utf-8") as handle:
-            json.dump(state, handle, indent=2)
+        from src.utils.private_state import write_private_json
+        write_private_json(_control_panel_pidfile(), state)
     except OSError:
         pass  # non-fatal; status-check will just spawn a new one next time
 

package/src/utils/mcp_transport.py

@@ -4,7 +4,8 @@ stdio remains the default. The `sse` and `streamable-http` modes bind to
 loopback (127.0.0.1) by default and REQUIRE a bearer token on every request, so
 turning networking on never silently exposes Resolve. The token comes from
 ``$DAVINCI_MCP_TOKEN`` or is generated and logged at startup. A small state file
-lets the control panel show the live connection URL + token.
+(0600, under the per-user private state dir — never a shared tempdir) lets the
+control panel show the live connection URL + token.
 
 Security posture:
 - Default host is loopback; a non-loopback bind logs a loud warning.
@@ -16,14 +17,19 @@ import json
 import logging
 import os
 import secrets
-import tempfile
 import time
 
+from src.utils.private_state import private_state_dir, write_private_json
+
 logger = logging.getLogger("davinci-resolve-mcp")
 
-TRANSPORT_STATE_PATH = os.path.join(
-    tempfile.gettempdir(), "davinci_resolve_mcp_transport.json"
-)
+
+def _state_path() -> str:
+    return os.path.join(private_state_dir(), "mcp_transport.json")
+
+
+# Resolved lazily so DAVINCI_RESOLVE_MCP_STATE_DIR set by a test harness is honored.
+TRANSPORT_STATE_PATH = _state_path()
 LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
 
 
@@ -32,7 +38,7 @@ def resolve_token():
     tok = os.environ.get("DAVINCI_MCP_TOKEN")
     if tok:
         return tok, False
-    return secrets.token_urlsafe(24), True
+    return secrets.token_urlsafe(32), True
 
 
 def _auth_middleware_cls(token):
@@ -56,17 +62,16 @@ def _auth_middleware_cls(token):
 
 def write_transport_state(transport, host, port, token):
     try:
-        with open(TRANSPORT_STATE_PATH, "w", encoding="utf-8") as fh:
-            json.dump({
-                "transport": transport,
-                "host": host,
-                "port": port,
-                "url": f"http://{host}:{port}",
-                "token": token,
-                "loopback": host in LOOPBACK_HOSTS,
-                "pid": os.getpid(),
-                "started_at": time.time(),
-            }, fh)
+        write_private_json(TRANSPORT_STATE_PATH, {
+            "transport": transport,
+            "host": host,
+            "port": port,
+            "url": f"http://{host}:{port}",
+            "token": token,
+            "loopback": host in LOOPBACK_HOSTS,
+            "pid": os.getpid(),
+            "started_at": time.time(),
+        })
     except OSError as exc:
         logger.warning("could not write transport state: %s", exc)
 

package/src/utils/private_state.py

@@ -0,0 +1,67 @@
+"""Per-user private state files (tokens, pidfiles) — never in a shared tempdir.
+
+Two callers keep secrets on disk: the control-panel launcher (its bearer token
++ pid) and the networked MCP transport (its bearer token + URL). Both used to
+land in world-readable locations (``~/Documents/...`` and ``tempfile.gettempdir()``).
+This module gives them one home under the user's HOME with 0700/0600 modes.
+
+``DAVINCI_RESOLVE_MCP_STATE_DIR`` overrides the directory (tests, sandboxes).
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from typing import Any, Dict
+
+
+def private_state_dir() -> str:
+    override = os.environ.get("DAVINCI_RESOLVE_MCP_STATE_DIR")
+    path = override or os.path.join(os.path.expanduser("~"), ".davinci-resolve-mcp")
+    try:
+        os.makedirs(path, mode=0o700, exist_ok=True)
+        if sys.platform != "win32":
+            os.chmod(path, 0o700)
+    except OSError:
+        pass
+    return path
+
+
+def _restrict_windows_acl(path: str) -> None:
+    """Best-effort: strip inherited ACEs and grant only the current user."""
+    user = os.environ.get("USERNAME")
+    if not user:
+        return
+    try:
+        subprocess.run(
+            ["icacls", path, "/inheritance:r", "/grant:r", f"{user}:F"],
+            capture_output=True, timeout=5, check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def write_private_file(path: str, text: str) -> None:
+    """Write ``text`` to ``path`` readable only by the current user (0600).
+
+    Replaces any existing file so a previously wider mode never survives.
+    """
+    parent = os.path.dirname(path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    try:
+        os.remove(path)
+    except OSError:
+        pass
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    if sys.platform == "win32":
+        _restrict_windows_acl(path)
+    else:
+        os.chmod(path, 0o600)
+
+
+def write_private_json(path: str, payload: Dict[str, Any]) -> None:
+    write_private_file(path, json.dumps(payload, indent=2))