tokentrace 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.19.0] - 2026-06-04
+
+### Security
+
+- **The local dashboard now enforces a request perimeter.** All `/api/*` routes
+  go through `middleware.ts`, which rejects requests whose `Host` is not a
+  loopback name (defeating DNS-rebinding that would otherwise let a malicious
+  web page read your local data as "same-origin") and blocks cross-site
+  state-changing requests (defeating CSRF that could silently re-point the
+  scanner, change settings, or wipe imported data). Non-browser clients (CLI,
+  curl) are unaffected.
+- **File-preview endpoints are now contained.** `/api/parser-debug/preview` and
+  `/api/import-profile-preview` previously read any caller-supplied path. They
+  now resolve symlinks and only read files under your home directory, the OS
+  temp directory, or explicitly configured import folders, returning `403` for
+  anything else. This removes an arbitrary-file-read surface.
+- **`tokentrace serve` refuses non-loopback binds by default.** Binding to
+  `0.0.0.0` or a LAN address (via `--hostname` or `TOKENTRACE_HOSTNAME`) now
+  errors with guidance, since the dashboard is unauthenticated. Set
+  `TOKENTRACE_ALLOW_REMOTE=1` to override deliberately.
+- **Security response headers added.** The dashboard now sends a strict
+  same-origin `Content-Security-Policy`, `X-Frame-Options: DENY`,
+  `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, and a
+  restrictive `Permissions-Policy` (anti-clickjacking and anti-sniffing).
+
 ## [0.18.1] - 2026-05-28
 
 ### Fixed

package/app/api/import-profile-preview/route.ts

@@ -1,6 +1,8 @@
 import { NextResponse } from "next/server";
+import { getAppSettings } from "@/src/db/settings";
 import { readJsonObject } from "@/src/lib/api-json";
 import { buildImportProfilePreview } from "@/src/lib/import-profile-preview";
+import { PathAccessError, pathAccessStatus, resolveReadablePath } from "@/src/lib/path-access";
 
 export const dynamic = "force-dynamic";
 
@@ -11,9 +13,22 @@ export async function POST(request: Request) {
   if (typeof filePath !== "string" || !filePath.trim()) {
     return NextResponse.json({ error: "filePath is required." }, { status: 400 });
   }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = await resolveReadablePath(filePath, {
+      extraRoots: getAppSettings().customFolders
+    });
+  } catch (error) {
+    if (error instanceof PathAccessError) {
+      return NextResponse.json({ error: error.message }, { status: pathAccessStatus(error.code) });
+    }
+    return NextResponse.json({ error: "Preview failed." }, { status: 400 });
+  }
+
   try {
     const preview = await buildImportProfilePreview({
-      filePath: filePath.trim(),
+      filePath: resolvedPath,
       storeRawMessageContent: parsed.body.storeRawMessageContent === true
     });
     return NextResponse.json(preview);

package/app/api/parser-debug/preview/route.ts

@@ -1,7 +1,9 @@
 import fs from "node:fs/promises";
 import { NextResponse } from "next/server";
+import { getAppSettings } from "@/src/db/settings";
 import { adapters } from "@/src/ingestion/adapters";
 import type { FileCandidate, NormalizedInteraction } from "@/src/ingestion/types";
+import { PathAccessError, pathAccessStatus, resolveReadablePath } from "@/src/lib/path-access";
 
 export const dynamic = "force-dynamic";
 
@@ -18,10 +20,10 @@ export async function POST(request: Request) {
     return NextResponse.json({ error: "Request body must be JSON." }, { status: 400 });
   }
 
-  const filePath = typeof body.path === "string" ? body.path.trim() : "";
+  const requestedPath = typeof body.path === "string" ? body.path.trim() : "";
   const parserId = typeof body.parserId === "string" ? body.parserId.trim() : "";
 
-  if (!filePath) {
+  if (!requestedPath) {
     return NextResponse.json({ error: "path is required" }, { status: 400 });
   }
   if (!parserId) {
@@ -36,11 +38,23 @@ export async function POST(request: Request) {
     );
   }
 
+  let filePath: string;
+  try {
+    filePath = await resolveReadablePath(requestedPath, {
+      extraRoots: getAppSettings().customFolders
+    });
+  } catch (error) {
+    if (error instanceof PathAccessError) {
+      return NextResponse.json({ error: error.message }, { status: pathAccessStatus(error.code) });
+    }
+    return NextResponse.json({ error: `file not found: ${requestedPath}` }, { status: 404 });
+  }
+
   let stat;
   try {
     stat = await fs.stat(filePath);
   } catch {
-    return NextResponse.json({ error: `file not found: ${filePath}` }, { status: 404 });
+    return NextResponse.json({ error: `file not found: ${requestedPath}` }, { status: 404 });
   }
 
   const candidate: FileCandidate = {

package/next.config.mjs

@@ -16,17 +16,54 @@ const productionExperimentalConfig =
     ? { ...baseExperimental, serverMinification: false }
     : baseExperimental;
 
+// Defense-in-depth response headers for the local dashboard. The CSP keeps all
+// resource loads same-origin (no third-party script/connect surface), and the
+// frame protections block clickjacking of the unauthenticated UI. 'unsafe-inline'
+// is required because Next.js injects inline bootstrap/hydration scripts and
+// styles; everything else is locked to 'self'.
+const securityHeaders = [
+  { key: "X-Frame-Options", value: "DENY" },
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  { key: "Referrer-Policy", value: "no-referrer" },
+  { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=(), interest-cohort=()" },
+  {
+    key: "Content-Security-Policy",
+    value: [
+      "default-src 'self'",
+      "script-src 'self' 'unsafe-inline'",
+      "style-src 'self' 'unsafe-inline'",
+      "img-src 'self' data: blob:",
+      "font-src 'self' data:",
+      "connect-src 'self'",
+      "object-src 'none'",
+      "base-uri 'self'",
+      "form-action 'self'",
+      "frame-ancestors 'none'"
+    ].join("; ")
+  }
+];
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   allowedDevOrigins: ["localhost", "127.0.0.1"],
   devIndicators: false,
   experimental: productionExperimentalConfig,
+  // The published package ships source and runs `next build` on the end user's
+  // machine at first `tokentrace serve`. Production installs omit devDependencies
+  // such as @types/better-sqlite3, so Next's build-time type check cannot pass
+  // there. Type safety is enforced in development and CI via `npm run verify`
+  // (`tsc --noEmit`); this only disables the redundant check during the
+  // user-machine build. Do not remove without making the user-side build
+  // type-check-free another way.
   typescript: {
     ignoreBuildErrors: true
   },
   serverExternalPackages: ["better-sqlite3"],
   outputFileTracingRoot: projectRoot,
-  typedRoutes: false
+  typedRoutes: false,
+  async headers() {
+    return [{ source: "/:path*", headers: securityHeaders }];
+  }
 };
 
 // Bundle analyzer — install @next/bundle-analyzer as an optional devDep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokentrace",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "mcpName": "io.github.abhiyoheswaran1/tokentrace",
   "description": "Local-first dashboard for AI CLI token, cost, and session analytics.",
   "author": {

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/abhiyoheswaran1/tokentrace",
     "source": "github"
   },
-  "version": "0.18.1",
+  "version": "0.19.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "tokentrace",
-      "version": "0.18.1",
+      "version": "0.19.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/serve.d.ts

@@ -0,0 +1,32 @@
+export interface ServeOptions {
+  help: boolean;
+  hostname: string;
+  port: number | null;
+  openBrowser: boolean;
+}
+
+export interface ResolvedServePort {
+  port: number;
+  fixed: boolean;
+}
+
+export interface ServeContext {
+  appDataDir(): string;
+  nextBin(): string;
+  runtimeEnv(): NodeJS.ProcessEnv;
+}
+
+export function parsePort(value: unknown): number;
+export function parseServeOptions(args: string[], env?: NodeJS.ProcessEnv): ServeOptions;
+export function isLoopbackHostname(hostname: unknown): boolean;
+export function assertHostnameAllowed(
+  hostname: string,
+  env?: Record<string, string | undefined>
+): void;
+export function startupProgress(step: string, detail?: string): void;
+export function formatServeError(
+  error: unknown,
+  options?: { hostname?: string; port?: number | null }
+): string;
+export function resolveServePort(options: ServeOptions): Promise<ResolvedServePort>;
+export function serve(context: ServeContext, args?: string[]): Promise<void>;

package/src/cli/serve.js

@@ -16,6 +16,28 @@ export function parsePort(value) {
   return port;
 }
 
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
+
+export function isLoopbackHostname(hostname) {
+  return LOOPBACK_HOSTNAMES.has(String(hostname ?? "").trim().toLowerCase());
+}
+
+/**
+ * The dashboard ships no authentication, so binding it to anything other than
+ * loopback exposes local AI usage data and the file-preview endpoints to the
+ * network. Refuse non-loopback binds unless the operator explicitly opts in.
+ */
+export function assertHostnameAllowed(hostname, env = process.env) {
+  if (isLoopbackHostname(hostname)) return;
+  if (env.TOKENTRACE_ALLOW_REMOTE === "1") return;
+  throw new Error(
+    `Refusing to bind TokenTrace to non-loopback host "${hostname}". ` +
+      "The dashboard has no authentication, so this would expose your local AI usage data " +
+      "and file-preview endpoints to the network. " +
+      "Re-run with --hostname 127.0.0.1, or set TOKENTRACE_ALLOW_REMOTE=1 to override (not recommended)."
+  );
+}
+
 export function parseServeOptions(args, env = process.env) {
   const options = {
     help: false,
@@ -119,6 +141,7 @@ export async function serve(context, args = []) {
   let child = null;
 
   try {
+    assertHostnameAllowed(hostname);
     let resolvedPort = null;
     if (options.port != null) {
       resolvedPort = await resolveServePort(options);

package/src/lib/path-access.ts

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { expandHome } from "@/src/ingestion/discovery";
+
+/**
+ * Containment for endpoints that read a caller-supplied file path (parser
+ * previews, import-profile previews).
+ *
+ * The dashboard's perimeter (see request-guard) already blocks remote and
+ * cross-site callers, so the only legitimate caller is the user's own browser.
+ * This module is defense-in-depth: even a same-origin request may only read
+ * files under directories that could plausibly hold AI usage logs — the user's
+ * home directory, the OS temp directory, and any explicitly configured import
+ * folders. That keeps the feature usable (CLI logs live under $HOME) while
+ * ensuring the dashboard can never be turned into a reader for `/etc/*`,
+ * `/root/*`, other users' home directories, or files reached via symlink
+ * escapes.
+ */
+
+export type PathAccessErrorCode = "invalid" | "not_found" | "forbidden";
+
+export class PathAccessError extends Error {
+  readonly code: PathAccessErrorCode;
+
+  constructor(code: PathAccessErrorCode, message: string) {
+    super(message);
+    this.name = "PathAccessError";
+    this.code = code;
+  }
+}
+
+/** HTTP status that best matches each failure mode. */
+export function pathAccessStatus(code: PathAccessErrorCode): number {
+  switch (code) {
+    case "invalid":
+      return 400;
+    case "not_found":
+      return 404;
+    case "forbidden":
+      return 403;
+  }
+}
+
+async function realpathOrNull(target: string): Promise<string | null> {
+  try {
+    return await fs.realpath(target);
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve and de-duplicate the directories the dashboard may read from. */
+export async function getAllowedReadRoots(extraRoots: string[] = []): Promise<string[]> {
+  const base = [os.homedir(), os.tmpdir(), ...extraRoots.map((root) => expandHome(root.trim()))];
+  const resolved = await Promise.all(
+    base.filter(Boolean).map((root) => realpathOrNull(path.resolve(root)))
+  );
+  return Array.from(new Set(resolved.filter((root): root is string => Boolean(root))));
+}
+
+function isWithinRoot(target: string, root: string): boolean {
+  if (target === root) return true;
+  const rel = path.relative(root, target);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * Validate a caller-supplied path and return its fully resolved (symlink-free)
+ * form. Throws {@link PathAccessError} with a `code` that maps to an HTTP status
+ * via {@link pathAccessStatus}.
+ */
+export async function resolveReadablePath(
+  input: unknown,
+  options: { extraRoots?: string[] } = {}
+): Promise<string> {
+  const expanded = typeof input === "string" ? expandHome(input.trim()) : "";
+  if (!expanded) {
+    throw new PathAccessError("invalid", "A file path is required.");
+  }
+  if (!path.isAbsolute(expanded)) {
+    throw new PathAccessError("invalid", "File path must be absolute.");
+  }
+
+  const real = await realpathOrNull(expanded);
+  if (!real) {
+    throw new PathAccessError("not_found", `File not found: ${expanded}`);
+  }
+
+  const roots = await getAllowedReadRoots(options.extraRoots);
+  if (!roots.some((root) => isWithinRoot(real, root))) {
+    throw new PathAccessError(
+      "forbidden",
+      "Path is outside the allowed import directories (home, temp, and configured folders)."
+    );
+  }
+
+  return real;
+}

package/src/lib/request-guard.ts

@@ -0,0 +1,119 @@
+/**
+ * Perimeter guard for the local dashboard's HTTP surface.
+ *
+ * The dashboard is unauthenticated by design (local-first, single user), so it
+ * relies entirely on *who can reach it* and *who is allowed to drive it*:
+ *
+ *  - Host allowlist: rejects requests whose `Host` header is not a loopback
+ *    name. This defeats DNS-rebinding attacks, where a malicious page rebinds
+ *    its own domain to 127.0.0.1 to turn cross-origin reads into "same-origin"
+ *    ones. A rebound request still carries the attacker's `Host`.
+ *  - Cross-site write protection: rejects state-changing requests that a
+ *    browser reports as cross-site (or that carry a non-loopback `Origin`).
+ *    This defeats CSRF, where a malicious page silently POSTs to the dashboard.
+ *
+ * Non-browser clients (CLI, curl) send neither `Origin` nor `Sec-Fetch-*` and
+ * are allowed through — the threat model is a browser being weaponised by a
+ * third-party site, not the user's own tooling.
+ *
+ * This module is intentionally dependency-free so it can run in the Next.js
+ * middleware (edge) runtime and be unit-tested in isolation.
+ */
+
+export type RequestGuardInput = {
+  method: string;
+  host: string | null | undefined;
+  origin?: string | null;
+  secFetchSite?: string | null;
+};
+
+export type RequestGuardEnv = {
+  TOKENTRACE_ALLOW_REMOTE?: string;
+};
+
+export type RequestGuardResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/** Extract the lowercased hostname from a `Host`/authority value, dropping any port. */
+function hostnameOf(value: string): string {
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return "";
+  // Bracketed IPv6 literal, optionally with a port: [::1]:3030
+  if (trimmed.startsWith("[")) {
+    const end = trimmed.indexOf("]");
+    return end === -1 ? trimmed : trimmed.slice(0, end + 1);
+  }
+  // Bare IPv6 (multiple colons) has no port suffix we can strip safely.
+  if (trimmed.split(":").length > 2) return trimmed;
+  const colon = trimmed.indexOf(":");
+  const host = colon === -1 ? trimmed : trimmed.slice(0, colon);
+  // Treat the FQDN trailing-dot form ("localhost.") as the bare name. This only
+  // ever loosens matching toward the canonical name, never across it.
+  return host.endsWith(".") ? host.slice(0, -1) : host;
+}
+
+function isLoopbackAuthority(value: string | null | undefined): boolean {
+  if (!value) return false;
+  return LOOPBACK_HOSTNAMES.has(hostnameOf(value));
+}
+
+function originIsLoopback(origin: string | null | undefined): boolean {
+  if (!origin) return false;
+  try {
+    return LOOPBACK_HOSTNAMES.has(new URL(origin).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function evaluateRequestGuard(
+  input: RequestGuardInput,
+  env: RequestGuardEnv = {}
+): RequestGuardResult {
+  const allowRemote = env.TOKENTRACE_ALLOW_REMOTE === "1";
+
+  if (!allowRemote && !isLoopbackAuthority(input.host)) {
+    return {
+      ok: false,
+      status: 421,
+      error:
+        "Request Host is not a recognised local address. TokenTrace only serves loopback hosts unless TOKENTRACE_ALLOW_REMOTE=1."
+    };
+  }
+
+  const method = input.method.toUpperCase();
+  if (SAFE_METHODS.has(method)) {
+    return { ok: true };
+  }
+
+  if (allowRemote) {
+    return { ok: true };
+  }
+
+  const secFetchSite = input.secFetchSite?.toLowerCase();
+  if (secFetchSite) {
+    if (secFetchSite === "same-origin" || secFetchSite === "none") {
+      return { ok: true };
+    }
+    return {
+      ok: false,
+      status: 403,
+      error: "Cross-site request blocked. TokenTrace only accepts same-origin writes."
+    };
+  }
+
+  // No Sec-Fetch-Site (older browser or non-browser client): fall back to Origin.
+  if (input.origin && !originIsLoopback(input.origin)) {
+    return {
+      ok: false,
+      status: 403,
+      error: "Cross-origin request blocked. TokenTrace only accepts same-origin writes."
+    };
+  }
+
+  return { ok: true };
+}