feat: harden dashboard server api

Author: douglasmonsky

README.md

@@ -203,9 +203,12 @@ Serve the dashboard with live aggregate refresh and lazy raw-context loading:
 
 ```bash
 codex-usage-tracker serve-dashboard --open
+codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
-When served this way, the dashboard gets a `Refresh` button plus a `Live` toggle that polls the localhost `/api/usage` endpoint every 10 seconds while the tab is visible. Each poll refreshes the SQLite aggregate index from local Codex logs and replaces the in-memory dashboard rows without embedding raw transcript content. Use the `Load` selector to fetch 5,000, 10,000, 20,000, or all aggregate calls; `--limit 0` also means all calls for CLI-generated dashboards. The table renders 500 rows or thread groups per page so larger histories remain responsive. Each call detail panel also gets a `Load context` action. Pressing it fetches only that call's logged turn context from the original local JSONL source. Tool output is omitted by default; the `Include tool output` action loads redacted, size-limited tool output for that call. None of this raw context is written to SQLite, CSV, or the generated HTML.
+When served this way, the dashboard gets a `Refresh` button plus a `Live` toggle that polls the localhost `/api/usage` endpoint every 10 seconds while the tab is visible. Refresh calls and `/api/context` require a random per-server token embedded in that generated dashboard, and the server rejects non-loopback `Host` or cross-origin `Origin` headers. Each poll refreshes the SQLite aggregate index from local Codex logs and replaces the in-memory dashboard rows without embedding raw transcript content. Use the `Load` selector to fetch 5,000, 10,000, 20,000, or all aggregate calls; `--limit 0` also means all calls for CLI-generated dashboards. The table renders 500 rows or thread groups per page so larger histories remain responsive. Each call detail panel also gets a `Load context` action when the context API is enabled. Pressing it fetches only that call's logged turn context from the original local JSONL source. Tool output is omitted by default; the `Include tool output` action loads redacted, size-limited tool output for that call. None of this raw context is written to SQLite, CSV, or the generated HTML.
+
+`serve-dashboard --context-api explicit` is the default and keeps context loading as an explicit per-row action. `serve-dashboard --no-context-api` or `--context-api disabled` serves live aggregate refresh while disabling `/api/context` entirely.
 
 Dashboard behavior:
 
@@ -370,6 +373,8 @@ The SQLite database is stored at `~/.codex-usage-tracker/usage.sqlite3` by defau
 
 Raw chat text and tool outputs are ignored by the parser and are never written to the tracker database, CSV exports, or generated dashboard HTML. `usage_call_context`, `codex-usage-tracker context`, and the `serve-dashboard` context endpoint read a single source JSONL file only when explicitly requested, redact common secret patterns, and cap returned text size.
 
+The localhost server binds only to loopback hosts, validates loopback `Host` and `Origin` headers, protects refresh/context API calls with a random per-server token, and can disable the context API entirely with `--no-context-api`.
+
 For MCP users, `usage_call_context` is additionally disabled unless the MCP server process has `CODEX_USAGE_TRACKER_ALLOW_RAW_CONTEXT=1` in its environment. Aggregate MCP tools do not require that opt-in.
 
 Cost estimates are calculated only from aggregate token fields and your local pricing config. They are omitted when no matching model price is configured. Pricing refreshes pull only OpenAI's public pricing markdown and do not send local usage data anywhere.

docs/dashboard-guide.md

@@ -33,6 +33,8 @@ codex-usage-tracker dashboard --open
 
 Static file mode can still filter, sort, and inspect aggregate call fields. It cannot refresh from logs or load raw context until you open the dashboard through `serve-dashboard`.
 
+The localhost server uses a random per-server token for refresh and context API calls, validates loopback `Host` and `Origin` headers, and can run as aggregate-only with `codex-usage-tracker serve-dashboard --no-context-api`.
+
 ## Insights View
 
 ![Insights view with ranked attention cards, investigation presets, and top threads by attention score.](assets/dashboard-insights.png)
@@ -114,6 +116,7 @@ When served from localhost, the details panel includes `Load context` and `Inclu
 - `Load context` fetches a size-limited, redacted context excerpt for only that call.
 - `Include tool output` repeats the request with tool output included, still redacted and capped.
 - Raw context is not written to SQLite, CSV, or the generated dashboard HTML.
+- If the server was started with `--no-context-api`, the context buttons stay disabled and the dashboard remains aggregate-only.
 
 ## Practical Workflow
 

src/codex_usage_tracker/cli.py

@@ -302,6 +302,17 @@ def _add_dashboard_parsers(
     serve.add_argument("--host", default="127.0.0.1")
     serve.add_argument("--port", type=int, default=8765)
     serve.add_argument("--context-chars", type=int, default=DEFAULT_CONTEXT_CHARS)
+    serve.add_argument(
+        "--context-api",
+        choices=["explicit", "disabled"],
+        default="explicit",
+        help="Enable explicit per-row context loading or disable the context API.",
+    )
+    serve.add_argument(
+        "--no-context-api",
+        action="store_true",
+        help="Serve aggregate dashboard refresh only and disable /api/context.",
+    )
     serve.add_argument("--open", action="store_true")
     serve.add_argument(
         "--refresh",
@@ -656,6 +667,7 @@ def _run_serve_dashboard(args: argparse.Namespace) -> int:
         open_browser=args.open,
         codex_home=args.codex_home,
         include_archived=args.include_archived,
+        context_api="disabled" if args.no_context_api else args.context_api,
     )
     return 0
 

src/codex_usage_tracker/dashboard.py

@@ -36,6 +36,8 @@ def dashboard_payload(
     pricing_path: Path = DEFAULT_PRICING_PATH,
     allowance_path: Path = DEFAULT_ALLOWANCE_PATH,
     since: str | None = None,
+    api_token: str | None = None,
+    context_api_enabled: bool = False,
 ) -> dict[str, object]:
     """Return aggregate-only dashboard data without rendering HTML."""
 
@@ -70,6 +72,8 @@ def dashboard_payload(
         "limit_label": "All" if normalized_limit is None else str(normalized_limit),
         "parser_diagnostics": parser_diagnostics,
         "parser_adapter": metadata.get("parser_adapter"),
+        "api_token": api_token or "",
+        "context_api_enabled": context_api_enabled,
     }
 
 
@@ -80,6 +84,8 @@ def generate_dashboard(
     pricing_path: Path = DEFAULT_PRICING_PATH,
     allowance_path: Path = DEFAULT_ALLOWANCE_PATH,
     since: str | None = None,
+    api_token: str | None = None,
+    context_api_enabled: bool = False,
 ) -> Path:
     output_path.parent.mkdir(parents=True, exist_ok=True)
     guide_href = _dashboard_guide_href(output_path)
@@ -93,6 +99,8 @@ def generate_dashboard(
             pricing_path=pricing_path,
             allowance_path=allowance_path,
             since=since,
+            api_token=api_token,
+            context_api_enabled=context_api_enabled,
         ),
         ensure_ascii=True,
     ).replace("</", "<\\/")

src/codex_usage_tracker/plugin_data/dashboard/dashboard.js

@@ -8,6 +8,8 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
     let allowanceWindows = Array.isArray(initialPayload.allowance_windows) ? initialPayload.allowance_windows : [];
     let allowanceError = initialPayload.allowance_error || '';
     let parserDiagnostics = initialPayload.parser_diagnostics || {};
+    let apiToken = initialPayload.api_token || '';
+    let contextApiEnabled = Boolean(initialPayload.context_api_enabled);
     let totalAvailableRows = Number(initialPayload.total_available_rows || data.length);
     let loadedLimit = payloadLimit(initialPayload);
     const rowsEl = document.getElementById('rows');
@@ -1126,10 +1128,13 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
     }
     function contextControls(row) {
       const fileMode = window.location.protocol === 'file:';
-      const disabled = fileMode ? ' disabled' : '';
+      const apiUnavailable = !contextApiEnabled || !apiToken;
+      const disabled = fileMode || apiUnavailable ? ' disabled' : '';
       const hint = fileMode
         ? 'Open this dashboard with codex-usage-tracker serve-dashboard to load raw context on demand.'
-        : 'Context is not embedded in this dashboard. Press a button to read this call from the local JSONL source.';
+        : apiUnavailable
+          ? 'Context loading is disabled for this dashboard server. Restart with --context-api explicit to enable explicit row actions.'
+          : 'Context is not embedded in this dashboard. Press a button to read this call from the local JSONL source.';
       return `
         <div class="context-actions">
           <button class="context-button" type="button" data-context-load${disabled}>Load context</button>
@@ -1156,7 +1161,10 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
       if (includeToolOutput) params.set('include_tool_output', '1');
       try {
         const response = await fetch(`/api/context?${params.toString()}`, {
-          headers: { 'Accept': 'application/json' },
+          headers: {
+            'Accept': 'application/json',
+            'X-Codex-Usage-Token': apiToken,
+          },
           cache: 'no-store',
         });
         if (!response.ok) {
@@ -1374,6 +1382,8 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
       allowanceWindows = Array.isArray(nextPayload.allowance_windows) ? nextPayload.allowance_windows : [];
       allowanceError = nextPayload.allowance_error || '';
       parserDiagnostics = nextPayload.parser_diagnostics || {};
+      apiToken = nextPayload.api_token || apiToken;
+      contextApiEnabled = Boolean(nextPayload.context_api_enabled);
       totalAvailableRows = Number(nextPayload.total_available_rows || data.length);
       loadedLimit = payloadLimit(nextPayload);
       rebuildDashboardIndexes();
@@ -1397,7 +1407,10 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
       try {
         const params = new URLSearchParams({ refresh: '1', limit: loadLimitEl.value, _: String(Date.now()) });
         const response = await fetch(`/api/usage?${params.toString()}`, {
-          headers: { 'Accept': 'application/json' },
+          headers: {
+            'Accept': 'application/json',
+            'X-Codex-Usage-Token': apiToken,
+          },
           cache: 'no-store',
         });
         if (!response.ok) {

src/codex_usage_tracker/plugin_data/docs/dashboard-guide.html

@@ -83,6 +83,7 @@ <h2>Open The Dashboard</h2>
 codex-usage-tracker serve-dashboard --open</code></pre>
     <p>For optional allowance context, run <code>codex-usage-tracker init-allowance</code> and copy current 5-hour or weekly remaining usage from Codex Usage or <code>/status</code> into the local template.</p>
     <p>The server enables live aggregate refresh and on-demand context loading. Static file mode can still filter, sort, and inspect aggregate fields, but cannot refresh logs or load context.</p>
+    <p>The localhost server uses a random per-server token for refresh and context API calls, validates loopback <code>Host</code> and <code>Origin</code> headers, and can run as aggregate-only with <code>codex-usage-tracker serve-dashboard --no-context-api</code>.</p>
 
     <h2>Insights View</h2>
     <img src="assets/dashboard-insights.png" alt="Insights view with ranked attention cards, investigation presets, and top threads by attention score.">
@@ -112,7 +113,7 @@ <h2>Threads View</h2>
 
     <h2>Details And Context</h2>
     <img src="assets/dashboard-details.png" alt="Details panel showing aggregate usage fields for a selected call.">
-    <p>The details panel shows primary cost, Codex credits, allowance impact, cache, context, pricing, and next-action signals first. It then groups thread narrative, token/pricing breakdowns, collapsed raw identifiers, and source metadata. When served from localhost, <code>Load context</code> fetches one redacted, size-limited source excerpt on demand.</p>
+    <p>The details panel shows primary cost, Codex credits, allowance impact, cache, context, pricing, and next-action signals first. It then groups thread narrative, token/pricing breakdowns, collapsed raw identifiers, and source metadata. When served from localhost with the context API enabled, <code>Load context</code> fetches one redacted, size-limited source excerpt on demand. When started with <code>--no-context-api</code>, context buttons stay disabled and the dashboard remains aggregate-only.</p>
 
     <h2>Investigating Long Chat Growth</h2>
     <p class="note">Prompt caching helps, but cached input is not free. Long-running chats can carry a large cached prefix into later turns, so usage can climb quickly even when the visible request looks small.</p>

src/codex_usage_tracker/server.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import json
+import hmac
+import secrets
 import sqlite3
 import threading
 import webbrowser
@@ -38,17 +40,23 @@ def serve_dashboard(
     open_browser: bool = False,
     codex_home: Path = DEFAULT_CODEX_HOME,
     include_archived: bool = False,
+    context_api: str = "explicit",
 ) -> None:
     """Generate and serve the dashboard plus a localhost-only context endpoint."""
 
     _validate_loopback_host(host)
+    _validate_context_api_mode(context_api)
+    api_token = secrets.token_urlsafe(32)
+    context_api_enabled = context_api != "disabled"
     output = generate_dashboard(
         db_path=db_path,
         output_path=output_path,
         limit=limit,
         pricing_path=pricing_path,
         allowance_path=allowance_path,
         since=since,
+        api_token=api_token,
+        context_api_enabled=context_api_enabled,
     )
     handler = partial(
         _UsageDashboardHandler,
@@ -62,12 +70,16 @@ def serve_dashboard(
         include_archived=include_archived,
         dashboard_name=output.name,
         context_chars=context_chars,
+        api_token=api_token,
+        context_api_enabled=context_api_enabled,
         refresh_lock=threading.Lock(),
     )
     server = ThreadingHTTPServer((host, port), handler)
     url = f"http://{_url_host(host)}:{port}/{output.name}"
     print(f"Serving Codex usage dashboard at {url}")
-    print("Aggregate rows refresh through /api/usage; raw context is loaded only through /api/context after a row action.")
+    context_mode = "enabled for explicit row actions" if context_api_enabled else "disabled"
+    print("Aggregate rows refresh through /api/usage with a per-server token.")
+    print(f"Raw context API is {context_mode}; context is never embedded in the dashboard HTML.")
     if open_browser:
         webbrowser.open(url)
     try:
@@ -91,6 +103,8 @@ def __init__(
         include_archived: bool,
         dashboard_name: str,
         context_chars: int,
+        api_token: str,
+        context_api_enabled: bool,
         refresh_lock: threading.Lock,
         **kwargs: object,
     ) -> None:
@@ -103,11 +117,16 @@ def __init__(
         self._include_archived = include_archived
         self._dashboard_name = dashboard_name
         self._context_chars = context_chars
+        self._api_token = api_token
+        self._context_api_enabled = context_api_enabled
         self._refresh_lock = refresh_lock
         super().__init__(*args, **kwargs)
 
     def do_GET(self) -> None:  # noqa: N802 - stdlib hook name
         parsed = urlparse(self.path)
+        if not self._request_origin_allowed():
+            self._send_json(HTTPStatus.FORBIDDEN, {"error": "Request host or origin is not allowed"})
+            return
         if parsed.path == "/api/context":
             self._handle_context(parsed.query)
             return
@@ -123,8 +142,8 @@ def end_headers(self) -> None:
         self.send_header("Referrer-Policy", "no-referrer")
         self.send_header(
             "Content-Security-Policy",
-            "default-src 'self'; script-src 'self' 'unsafe-inline'; "
-            "style-src 'self' 'unsafe-inline'; connect-src 'self'; "
+            "default-src 'self'; script-src 'self'; "
+            "style-src 'self'; connect-src 'self'; "
             "img-src 'self' data:; object-src 'none'; base-uri 'none'",
         )
         super().end_headers()
@@ -136,6 +155,15 @@ def log_message(self, format: str, *args: object) -> None:
 
     def _handle_context(self, query: str) -> None:
         params = parse_qs(query)
+        if not self._context_api_enabled:
+            self._send_json(
+                HTTPStatus.FORBIDDEN,
+                {"error": "Context API is disabled for this dashboard server."},
+            )
+            return
+        if not self._has_valid_api_token(params):
+            self._send_json(HTTPStatus.FORBIDDEN, {"error": "Valid API token is required"})
+            return
         record_id = _first(params.get("record_id"))
         if not record_id:
             self._send_json(
@@ -177,6 +205,12 @@ def _handle_usage(self, query: str) -> None:
         refresh_result = None
         try:
             if _truthy(_first(params.get("refresh"))):
+                if not self._has_valid_api_token(params):
+                    self._send_json(
+                        HTTPStatus.FORBIDDEN,
+                        {"error": "Valid API token is required for refresh"},
+                    )
+                    return
                 with self._refresh_lock:
                     result = refresh_usage_index(
                         codex_home=self._codex_home,
@@ -197,6 +231,8 @@ def _handle_usage(self, query: str) -> None:
                 pricing_path=self._pricing_path,
                 allowance_path=self._allowance_path,
                 since=self._since,
+                api_token=self._api_token,
+                context_api_enabled=self._context_api_enabled,
             )
         except sqlite3.Error as exc:
             self._send_json(
@@ -214,6 +250,25 @@ def _handle_usage(self, query: str) -> None:
         payload["refresh_result"] = refresh_result
         self._send_json(HTTPStatus.OK, payload)
 
+    def _request_origin_allowed(self) -> bool:
+        if not _allowed_loopback_host(_host_header_name(self.headers.get("Host"))):
+            return False
+        origin = self.headers.get("Origin")
+        if not origin:
+            return True
+        parsed = urlparse(origin)
+        if parsed.scheme not in {"http", "https"}:
+            return False
+        if not _allowed_loopback_host(parsed.hostname):
+            return False
+        if parsed.port is not None and parsed.port != self.server.server_port:
+            return False
+        return True
+
+    def _has_valid_api_token(self, params: dict[str, list[str]]) -> bool:
+        provided = self.headers.get("X-Codex-Usage-Token") or _first(params.get("api_token")) or ""
+        return hmac.compare_digest(str(provided), self._api_token)
+
     def _send_json(self, status: HTTPStatus, payload: dict[str, object]) -> None:
         body = json.dumps(payload, ensure_ascii=True).encode("utf-8")
         self.send_response(status)
@@ -263,5 +318,31 @@ def _validate_loopback_host(host: str) -> None:
         raise ValueError("serve-dashboard refuses to expose raw context off localhost")
 
 
+def _validate_context_api_mode(mode: str) -> None:
+    if mode not in {"explicit", "disabled"}:
+        raise ValueError("--context-api must be explicit or disabled")
+
+
+def _allowed_loopback_host(host: str | None) -> bool:
+    if not host:
+        return False
+    if host == "localhost":
+        return True
+    try:
+        return ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _host_header_name(value: str | None) -> str | None:
+    if not value:
+        return None
+    host = value.strip()
+    if host.startswith("["):
+        end = host.find("]")
+        return host[1:end] if end > 0 else None
+    return host.split(":", 1)[0]
+
+
 def _url_host(host: str) -> str:
     return f"[{host}]" if ":" in host and not host.startswith("[") else host