From c7ff682e68cd926edb1230ac503724afc6777f46 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 27 Oct 2026 18:19:22 +0000 Subject: [PATCH 1/3] Add an opt-in 8-hour tab timeline (AGE-813) Recording stays off until the user enables a tab or origin. listTracked and getTimeline read the local redacted log by tab or origin and time, and return nothing when that slice was never enabled or is outside the rolling window. Co-authored-by: werbel.ted --- CHANGELOG.md | 8 + README.md | 10 + SECURITY.md | 7 + browser-tools-mcp/src/connector-bin.ts | 3 +- browser-tools-mcp/src/connector/api-policy.ts | 4 + browser-tools-mcp/src/connector/connector.ts | 56 ++ browser-tools-mcp/src/mcp/client.ts | 19 + browser-tools-mcp/src/mcp/prompts.ts | 9 +- browser-tools-mcp/src/mcp/server.ts | 2 + browser-tools-mcp/src/mcp/tool-invoke.ts | 5 + browser-tools-mcp/src/runtime.ts | 9 +- browser-tools-mcp/src/timeline/store.ts | 690 ++++++++++++++++++ browser-tools-mcp/src/timeline/tools.ts | 221 ++++++ browser-tools-mcp/src/tools-cli.ts | 2 + .../test/integration/mcp-server.test.ts | 2 + .../test/integration/timeline.test.ts | 254 +++++++ .../test/unit/api-policy.test.ts | 30 + .../test/unit/extension-timeline.test.ts | 132 ++++ .../test/unit/timeline-store.test.ts | 282 +++++++ chrome-extension/popup.html | 24 + chrome-extension/popup.js | 87 +++ chrome-extension/timeline.js | 398 ++++++++++ chrome-extension/worker.js | 159 +++- 23 files changed, 2403 insertions(+), 10 deletions(-) create mode 100644 browser-tools-mcp/src/timeline/store.ts create mode 100644 browser-tools-mcp/src/timeline/tools.ts create mode 100644 browser-tools-mcp/test/integration/timeline.test.ts create mode 100644 browser-tools-mcp/test/unit/extension-timeline.test.ts create mode 100644 browser-tools-mcp/test/unit/timeline-store.test.ts create mode 100644 chrome-extension/timeline.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b9be9e1..edd9fb2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ ## Unreleased +- **Opt-in 8-hour tab timeline.** Recording stays off until the user enables a + tab or an origin in the extension popup. `listTracked` lists what is on. + `getTimeline` returns redacted console and network for one tab or origin + between `from` and `to`, or for `lastMinutes`. The log is local, kept for a + rolling 8 hours, then dropped. Cookie and Authorization values are removed + before storage. A tab that was never enabled, or a time outside the window, + comes back empty. The capture wraps console and fetch/XHR. It does not + attach the debugger and does not hide the debugging banner. - **Non-scriptable pages are reported the same way everywhere.** `chrome://`, DevTools, `view-source:`, the Chrome Web Store, extension pages, and the built-in PDF viewer come back as metadata only (`access: "metadata-only"`, diff --git a/README.md b/README.md index 6160e276..5e4eca8c 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,8 @@ setup and a silent one look the same. | `takeScreenshot` | Screenshot returned **as an image**, plus its file path | | `refreshBrowser` | Reloads the inspected tab | | `getBrowserStorage` | localStorage, sessionStorage and cookies (values gated) | +| `listTracked` | Tabs and origins the user enabled for the 8-hour log | +| `getTimeline` | Redacted console and network for one tab or origin, by time | | `wipeLogs` | Clears captured telemetry before a clean reproduction | | `runAccessibilityAudit` | Lighthouse accessibility audit | | `runPerformanceAudit` | Lighthouse performance audit with Core Web Vitals | @@ -131,6 +133,14 @@ clients can auto-approve them safely. The popup switch has to be on. Navigation and soft input also need `--allow-input` on `browser-tools-mcp`, or `--allow-actions` on the `browser-tools` CLI. The same origin rules as other input apply. An asleep tab is reported and not reloaded. A soft action says `worked` or `needs a real gesture` and does not claim a failed action worked. +### 8-hour log + +Recording is off until the user turns it on for a tab or a site in the extension popup. `listTracked` shows what is on. `getTimeline` reads redacted console and network for one `chromeTabId` or origin, using `from` and `to` or `lastMinutes`. + +The log stays on this machine for a rolling 8 hours, then it is dropped. Cookie and Authorization values are removed before they are stored. If that tab or origin was never enabled, or the time is outside the window, the result is empty. It does not guess from the DevTools buffer. + +This path wraps the page's console and fetch/XHR. It does not attach the debugger, so it does not show or hide the debugging banner, and it does not click or drive the page. `wipeLogs` clears the DevTools buffer only. + ### Several tabs at once Every tab with DevTools open is tracked separately. Telemetry is attributed to diff --git a/SECURITY.md b/SECURITY.md index 6c8ea2b0..5dc98de0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -132,6 +132,13 @@ be, both are worth reporting. `tabs.update({active:true})`, or `windows.update({focused:true})`. When a feature attaches the debugger, the banner stays visible for that attachment, and dismissing it stops the attachment. +- The 8-hour tab log is off until the user enables a tab or an origin in the + extension popup. It is stored only in the local state directory + (`timeline.json`, mode `0600`), kept for a rolling 8 hours, then deleted. + Cookie, Set-Cookie, and Authorization values are removed before storage. + Capture uses page hooks, not `chrome.debugger`, so it does not hide the + debugging banner. A query for a target that was never enabled, or a time + outside that window, returns an empty result. - Credential-bearing headers and secret-shaped strings are redacted before storage, not before display. - Request bodies are size-limited; log retention is bounded and client-supplied diff --git a/browser-tools-mcp/src/connector-bin.ts b/browser-tools-mcp/src/connector-bin.ts index 10955bba..d3db2073 100644 --- a/browser-tools-mcp/src/connector-bin.ts +++ b/browser-tools-mcp/src/connector-bin.ts @@ -8,7 +8,7 @@ */ import { parseCli, readPackageVersion } from "./cli.js"; import { createConnector } from "./connector/connector.js"; -import { clearSessionFile, writeSessionFile } from "./util/session.js"; +import { clearSessionFile, sessionDir, writeSessionFile } from "./util/session.js"; import { createLogger } from "./util/logger.js"; import { getDefaultScreenshotDir } from "./util/paths.js"; @@ -70,6 +70,7 @@ async function main(): Promise { ...(options.enabledTools ? { enabledTools: options.enabledTools } : {}), ...(options.disabledTools ? { disabledTools: options.disabledTools } : {}), ...(options.extensionId ? { extensionId: options.extensionId } : {}), + timelineDir: sessionDir(), }); writeSessionFile({ diff --git a/browser-tools-mcp/src/connector/api-policy.ts b/browser-tools-mcp/src/connector/api-policy.ts index 2f44182e..853b68d3 100644 --- a/browser-tools-mcp/src/connector/api-policy.ts +++ b/browser-tools-mcp/src/connector/api-policy.ts @@ -52,6 +52,8 @@ export const API_TOOL_NAMES: readonly string[] = [ "navigateBrowser", "getBrowserStorage", "wipeLogs", + "listTracked", + "getTimeline", ...AUDIT_CATEGORIES.map((category) => AUDIT_TOOL[category]), ]; @@ -112,6 +114,8 @@ function toolsForRequest(method: string, path: string, query: Record; + /** Tabs and origins the user has enabled for the 8-hour log. */ + listTracked(): TimelineListing; + /** Redacted console and network for one tab or origin. Empty when untracked or outside the window. */ + queryTimeline(query: TimelineQuery): TimelineResult; close(): Promise; } @@ -349,6 +365,7 @@ export async function createConnector(config: ConnectorConfig = {}): Promise { + res.json(timeline.list()); + }); + + api.get("/timeline/logs", (req: Request, res: Response) => { + try { + const chromeTabId = parseCount(req.query["chromeTabId"]); + const lastMinutes = parseCount(req.query["lastMinutes"]); + const limit = parseCount(req.query["limit"]); + res.json( + timeline.query({ + ...(chromeTabId !== undefined ? { chromeTabId } : {}), + ...(typeof req.query["origin"] === "string" ? { origin: req.query["origin"] } : {}), + ...(typeof req.query["from"] === "string" ? { from: req.query["from"] } : {}), + ...(typeof req.query["to"] === "string" ? { to: req.query["to"] } : {}), + ...(lastMinutes !== undefined ? { lastMinutes } : {}), + ...(limit !== undefined ? { limit } : {}), + }) + ); + } catch (error) { + respondWithError(res, error); + } + }); + api.get("/status", (_req, res) => { res.json({ version: SERVER_VERSION, @@ -1219,6 +1260,14 @@ export async function createConnector(config: ConnectorConfig = {}): Promise { clearInterval(heartbeat); + timeline.flush(); for (const { timer, reject } of pending.values()) { clearTimeout(timer); reject(new Error("Connector shutting down")); @@ -1877,6 +1927,8 @@ export async function createConnector(config: ConnectorConfig = {}): Promise timeline.list(), + queryTimeline: (query) => timeline.query(query), close, }; } @@ -1912,6 +1964,10 @@ function respondWithError(res: Response, error: unknown): void { res.status(502).json({ error: error.message, code: "EXTENSION_ERROR" }); return; } + if (error instanceof TimelineQueryError) { + res.status(400).json({ error: error.message, code: "BAD_TIMELINE_QUERY" }); + return; + } log.error("Unexpected error:", error); res.status(500).json({ error: (error as Error)?.message ?? "Internal error" }); } diff --git a/browser-tools-mcp/src/mcp/client.ts b/browser-tools-mcp/src/mcp/client.ts index fdf68b12..c9433e50 100644 --- a/browser-tools-mcp/src/mcp/client.ts +++ b/browser-tools-mcp/src/mcp/client.ts @@ -24,6 +24,7 @@ import type { ChromeTabRead, SoftInputResult, } from "../tabs/contract.js"; +import type { TimelineListing, TimelineQuery, TimelineResult } from "../timeline/store.js"; export interface PageInfo { url: string; @@ -111,6 +112,8 @@ export interface ConnectorClient { exportConsole(options?: { tabId?: TabId; allTabs?: boolean }): Promise>; exportNetwork(options?: { tabId?: TabId; allTabs?: boolean }): Promise>; readArtifact(kind: "screenshot" | "audit", name: string): Promise; + listTracked(): Promise; + getTimeline(query: TimelineQuery): Promise; } /** Talks straight to an embedded connector — no network hop, no discovery. */ @@ -242,6 +245,14 @@ export class InProcessConnectorClient implements ConnectorClient { async readArtifact(kind: "screenshot" | "audit", name: string): Promise { return this.#connector.readArtifact(kind, name); } + + async listTracked(): Promise { + return this.#connector.listTracked(); + } + + async getTimeline(query: TimelineQuery): Promise { + return this.#connector.queryTimeline(query); + } } export interface HttpConnectorClientOptions { @@ -399,4 +410,12 @@ export class HttpConnectorClient implements ConnectorClient { readArtifact(kind: "screenshot" | "audit", name: string): Promise { return this.#request(`/api/artifact/${kind}/${encodeURIComponent(name)}`); } + + listTracked(): Promise { + return this.#request("/api/timeline"); + } + + getTimeline(query: TimelineQuery): Promise { + return this.#request("/api/timeline/logs", { query: query as Record }); + } } diff --git a/browser-tools-mcp/src/mcp/prompts.ts b/browser-tools-mcp/src/mcp/prompts.ts index cd86a8a4..458774e8 100644 --- a/browser-tools-mcp/src/mcp/prompts.ts +++ b/browser-tools-mcp/src/mcp/prompts.ts @@ -43,7 +43,14 @@ evidence before changing code. Never assume a log line is current — check timestamps against the reproduction. Captured values are redacted where they looked like credentials; if a value reads as [REDACTED] that is this tool protecting the user, not the application -misbehaving.`; +misbehaving. + +The 8-hour log is separate from the DevTools buffer and stays off until the +user enables a tab or a site in the extension popup. Call listTracked to see +what they enabled. Call getTimeline with chromeTabId or origin, and from/to +or lastMinutes. If reason is not-enabled or outside-window, the arrays are +empty on purpose. Do not fill that gap from getConsoleLogs, and do not guess +a different tab.`; const AUDIT_MODE = `You are running a quality audit of a live page using BrowserTools MCP. diff --git a/browser-tools-mcp/src/mcp/server.ts b/browser-tools-mcp/src/mcp/server.ts index 16a9c4dd..ebb7db25 100644 --- a/browser-tools-mcp/src/mcp/server.ts +++ b/browser-tools-mcp/src/mcp/server.ts @@ -27,6 +27,7 @@ import { NAVIGATE_BROWSER_DESCRIPTION, } from "../tabs/contract.js"; import { TAB_TOOLS } from "../tabs/tools.js"; +import { TIMELINE_TOOLS } from "../timeline/tools.js"; const log = createLogger("mcp"); @@ -270,6 +271,7 @@ function auditTool( const TOOLS: ToolDefinition[] = [ ...TAB_TOOLS, + ...TIMELINE_TOOLS, { name: "listBrowserTabs", register(server, client) { diff --git a/browser-tools-mcp/src/mcp/tool-invoke.ts b/browser-tools-mcp/src/mcp/tool-invoke.ts index e9eb3441..ab855da9 100644 --- a/browser-tools-mcp/src/mcp/tool-invoke.ts +++ b/browser-tools-mcp/src/mcp/tool-invoke.ts @@ -9,6 +9,7 @@ import { import type { AuditCategory } from "../lighthouse/types.js"; import { RestrictedPageError, restrictedPageToolText } from "../restricted-page.js"; import { invokeTabTool } from "../tabs/tools.js"; +import { invokeTimelineTool } from "../timeline/tools.js"; export type ToolContent = | { type: "text"; text: string } @@ -127,6 +128,8 @@ export async function invokeTool( ): Promise { const tabTool = await invokeTabTool(name, client, args); if (tabTool) return tabTool; + const timelineTool = await invokeTimelineTool(name, client, args); + if (timelineTool) return timelineTool; switch (name) { case "listBrowserTabs": @@ -339,6 +342,8 @@ export const INVOKABLE_TOOL_NAMES: readonly string[] = [ "navigateBrowser", "getBrowserStorage", "wipeLogs", + "listTracked", + "getTimeline", "runAccessibilityAudit", "runPerformanceAudit", "runSEOAudit", diff --git a/browser-tools-mcp/src/runtime.ts b/browser-tools-mcp/src/runtime.ts index 3dc5d68f..648a9a2d 100644 --- a/browser-tools-mcp/src/runtime.ts +++ b/browser-tools-mcp/src/runtime.ts @@ -4,7 +4,7 @@ import { InProcessConnectorClient, type ConnectorClient, } from "./mcp/client.js"; -import { readSessionFile, writeSessionFile, clearSessionFile } from "./util/session.js"; +import { readSessionFile, sessionDir, writeSessionFile, clearSessionFile } from "./util/session.js"; import { createLogger } from "./util/logger.js"; import { readPackageVersion, type CliOptions } from "./cli.js"; @@ -102,6 +102,12 @@ class UnavailableConnectorClient implements ConnectorClient { readArtifact(): Promise { return this.#fail(); } + listTracked(): Promise { + return this.#fail(); + } + getTimeline(): Promise { + return this.#fail(); + } } /** @@ -203,6 +209,7 @@ export async function createRuntime(options: CliOptions): Promise { ...(options.enabledTools ? { enabledTools: options.enabledTools } : {}), ...(options.disabledTools ? { disabledTools: options.disabledTools } : {}), ...(options.extensionId ? { extensionId: options.extensionId } : {}), + timelineDir: sessionDir(), }); writeSessionFile({ diff --git a/browser-tools-mcp/src/timeline/store.ts b/browser-tools-mcp/src/timeline/store.ts new file mode 100644 index 00000000..c31a5373 --- /dev/null +++ b/browser-tools-mcp/src/timeline/store.ts @@ -0,0 +1,690 @@ +/** + * Opt-in tab timeline (AGE-813). + * + * Nothing is recorded until the user enables a tab or an origin. Entries live + * on this machine for a rolling 8 hours, then they are dropped. Cookie and + * Authorization values are removed before anything is stored. A query for a + * target that was never enabled, or a time entirely outside the window, + * returns an empty result — it does not borrow the DevTools log buffer. + */ + +import fs from "node:fs"; +import path from "node:path"; + +import { redactHeaders, redactSecretsInString, REDACTED } from "../util/redact.js"; +import { logger } from "../util/logger.js"; + +export const TIMELINE_WINDOW_MS = 8 * 60 * 60 * 1000; +export const TIMELINE_RETENTION_HOURS = 8; +const DEFAULT_LIMIT = 100; +const MAX_LIMIT = 500; +const MAX_PER_TAB = 2000; +const STRING_LIMIT = 2000; +const FILE_NAME = "timeline.json"; + +const CREDENTIAL_HEADER = /^(authorization|proxy-authorization|cookie|set-cookie)$/i; + +export type TimelineReason = "ok" | "not-enabled" | "outside-window" | "none-in-range"; + +export interface TimelineTarget { + kind: "tab" | "origin"; + chromeTabId: number | null; + origin: string; + url: string; + title: string; + enabledAt: number; + enabled: boolean; +} + +export interface TimelineConsoleEntry { + kind: "console"; + chromeTabId: number; + origin: string; + url: string; + level: string; + message: string; + timestamp: number; +} + +export interface TimelineNetworkEntry { + kind: "network"; + chromeTabId: number; + origin: string; + url: string; + method: string; + status: number; + timestamp: number; + startedAt?: number; + durationMs?: number; + error?: string; + requestHeaders?: Record; + requestBody?: string; +} + +export type TimelineEntry = TimelineConsoleEntry | TimelineNetworkEntry; + +export interface TimelineQuery { + chromeTabId?: number; + origin?: string; + from?: string | number; + to?: string | number; + lastMinutes?: number; + limit?: number; +} + +export interface TimelineResult { + tracked: boolean; + reason: TimelineReason; + chromeTabId: number | null; + origin: string | null; + from: string; + to: string; + windowStart: string; + retentionHours: number; + localOnly: true; + clipped: boolean; + console: TimelineConsoleEntry[]; + network: TimelineNetworkEntry[]; + consoleTotal: number; + networkTotal: number; + truncated: boolean; +} + +export interface TimelineListing { + retentionHours: number; + windowStart: string; + localOnly: true; + targets: TimelineTarget[]; +} + +export class TimelineQueryError extends Error { + constructor(message: string) { + super(message); + this.name = "TimelineQueryError"; + } +} + +export interface TimelineStoreOptions { + /** Directory for timeline.json. Omit to keep the log in memory only. */ + dir?: string; + now?: () => number; +} + +interface Selector { + chromeTabId?: number; + origin?: string; +} + +/** + * Same origin shape the extension uses: scheme, lower-case host, and port, + * with 80 and 443 written out. A value that is not http(s) is not an origin. + */ +export function normalizeOrigin(input: string): string | null { + if (typeof input !== "string" || !input.trim()) return null; + try { + const parsed = new URL(input); + if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null; + if (parsed.username || parsed.password) return null; + const port = parsed.port || (parsed.protocol === "https:" ? "443" : "80"); + return `${parsed.protocol}//${parsed.hostname.toLowerCase()}:${port}`; + } catch { + return null; + } +} + +function clipString(value: string): string { + const scrubbed = stripCredentialText(redactSecretsInString(value)); + if (scrubbed.length <= STRING_LIMIT) return scrubbed; + return `${scrubbed.slice(0, STRING_LIMIT)}... (truncated)`; +} + +/** + * Removes Cookie and Authorization material from free text before it is stored. + * The value runs to the end of the line so a scheme plus token, or a cookie + * pair, cannot leave a second word behind. + */ +export function stripCredentialText(value: string): string { + if (!value) return value; + return value + .replace( + /\b((?:proxy-)?authorization|cookie|set-cookie)\b["']?(\s*[:=]\s*)(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^\n\r]*)/gi, + `$1$2${REDACTED}` + ) + .replace(/\b(Bearer|Basic|Token|Digest)\s+\S+/gi, `$1 ${REDACTED}`); +} + +function stripCredentialHeaders( + headers: Record | undefined +): Record | undefined { + if (!headers) return undefined; + const kept: Record = {}; + for (const [name, value] of Object.entries(headers)) { + if (CREDENTIAL_HEADER.test(name)) continue; + if (typeof value === "string") kept[name] = value; + else if (Array.isArray(value)) kept[name] = value.map((item) => String(item)).join(", "); + else if (value !== undefined && value !== null) kept[name] = String(value); + } + const redacted = redactHeaders(kept); + const out: Record = {}; + for (const [name, value] of Object.entries(redacted)) { + if (CREDENTIAL_HEADER.test(name)) continue; + out[name] = clipString(value); + } + return Object.keys(out).length ? out : undefined; +} + +function targetKey(target: { kind: string; chromeTabId?: number | null; origin?: string }): string { + if (target.kind === "tab" && typeof target.chromeTabId === "number") { + return `tab:${target.chromeTabId}`; + } + return `origin:${target.origin ?? ""}`; +} + +function emptyResult( + partial: Pick & { + tracked: boolean; + reason: TimelineReason; + } +): TimelineResult { + return { + ...partial, + retentionHours: TIMELINE_RETENTION_HOURS, + localOnly: true, + console: [], + network: [], + consoleTotal: 0, + networkTotal: 0, + truncated: false, + }; +} + +export class TimelineStore { + #dir?: string; + #now: () => number; + #targets: TimelineTarget[] = []; + #console: TimelineConsoleEntry[] = []; + #network: TimelineNetworkEntry[] = []; + #flushTimer: NodeJS.Timeout | null = null; + + constructor(options: TimelineStoreOptions = {}) { + this.#dir = options.dir; + this.#now = options.now ?? Date.now; + this.#load(); + } + + get dir(): string | undefined { + return this.#dir; + } + + list(now = this.#now()): TimelineListing { + this.#prune(now); + return { + retentionHours: TIMELINE_RETENTION_HOURS, + windowStart: new Date(now - TIMELINE_WINDOW_MS).toISOString(), + localOnly: true, + targets: this.#targets + .filter((target) => target.enabled) + .map((target) => ({ ...target })) + .sort((a, b) => a.enabledAt - b.enabledAt || targetKey(a).localeCompare(targetKey(b))), + }; + } + + /** + * Replaces the set of targets the user currently has on. Targets that drop + * out are disabled, not forgotten, so a later query can still find the logs + * they already produced. Unknown shapes are ignored. + */ + replaceTargets(raw: unknown, now = this.#now()): void { + if (!Array.isArray(raw)) return; + const incoming: TimelineTarget[] = []; + for (const item of raw) { + const target = this.#normalizeTarget(item, now); + if (target) incoming.push(target); + } + const seen = new Set(); + for (const next of incoming) { + const key = targetKey(next); + if (seen.has(key)) continue; + seen.add(key); + const existing = this.#targets.find((target) => targetKey(target) === key); + if (existing) { + existing.enabled = true; + existing.origin = next.origin || existing.origin; + existing.url = next.url || existing.url; + existing.title = next.title || existing.title; + if (next.enabledAt < existing.enabledAt) existing.enabledAt = next.enabledAt; + } else { + this.#targets.push(next); + } + } + for (const target of this.#targets) { + if (!seen.has(targetKey(target))) target.enabled = false; + } + this.#scheduleFlush(); + } + + /** Stores one event when its tab or origin is currently enabled. */ + ingest(raw: unknown, now = this.#now()): boolean { + const entry = this.#normalizeEntry(raw, now); + if (!entry) return false; + if (!this.#enabledFor(entry)) return false; + if (entry.timestamp < now - TIMELINE_WINDOW_MS) return false; + if (entry.kind === "console") { + this.#console.push(entry); + this.#evict(this.#console, entry.chromeTabId); + } else { + this.#network.push(entry); + this.#evict(this.#network, entry.chromeTabId); + } + this.#prune(now); + this.#scheduleFlush(); + return true; + } + + query(query: TimelineQuery, now = this.#now()): TimelineResult { + this.#prune(now); + const windowStart = now - TIMELINE_WINDOW_MS; + const range = this.#range(query, now, windowStart); + const selector = this.#selector(query); + const frame = { + chromeTabId: selector.chromeTabId ?? null, + origin: selector.origin ?? null, + from: new Date(range.from).toISOString(), + to: new Date(range.to).toISOString(), + windowStart: new Date(windowStart).toISOString(), + clipped: false, + }; + + if (!this.#wasTracked(selector)) { + return emptyResult({ ...frame, tracked: false, reason: "not-enabled" }); + } + if (range.to < windowStart || range.from > now) { + return emptyResult({ ...frame, tracked: true, reason: "outside-window" }); + } + + const start = Math.max(range.from, windowStart); + const end = Math.min(range.to, now); + const clipped = start !== range.from || end !== range.to; + const limit = this.#limit(query.limit); + const consoleMatches = this.#console.filter( + (entry) => this.#matches(entry, selector) && entry.timestamp >= start && entry.timestamp <= end + ); + const networkMatches = this.#network.filter( + (entry) => this.#matches(entry, selector) && entry.timestamp >= start && entry.timestamp <= end + ); + const consolePage = page(consoleMatches, limit); + const networkPage = page(networkMatches, limit); + if (consoleMatches.length === 0 && networkMatches.length === 0) { + return emptyResult({ + ...frame, + clipped, + tracked: true, + reason: "none-in-range", + }); + } + return { + tracked: true, + reason: "ok", + chromeTabId: selector.chromeTabId ?? null, + origin: selector.origin ?? null, + from: new Date(range.from).toISOString(), + to: new Date(range.to).toISOString(), + windowStart: new Date(windowStart).toISOString(), + retentionHours: TIMELINE_RETENTION_HOURS, + localOnly: true, + clipped, + console: consolePage.entries, + network: networkPage.entries, + consoleTotal: consoleMatches.length, + networkTotal: networkMatches.length, + truncated: consolePage.truncated || networkPage.truncated, + }; + } + + flush(): void { + if (this.#flushTimer) { + clearTimeout(this.#flushTimer); + this.#flushTimer = null; + } + this.#write(); + } + + #selector(query: TimelineQuery): Selector { + const selector: Selector = {}; + if (query.chromeTabId !== undefined) { + if (!Number.isInteger(query.chromeTabId) || query.chromeTabId <= 0) { + throw new TimelineQueryError("chromeTabId must be a positive integer."); + } + selector.chromeTabId = query.chromeTabId; + } + if (query.origin !== undefined) { + if (typeof query.origin !== "string" || !query.origin.trim()) { + throw new TimelineQueryError("origin must be an http(s) origin."); + } + const origin = normalizeOrigin(query.origin); + if (!origin) throw new TimelineQueryError("origin must be an http(s) origin."); + selector.origin = origin; + } + if (selector.chromeTabId === undefined && selector.origin === undefined) { + throw new TimelineQueryError( + "Pass chromeTabId or origin. This does not guess a tab from the DevTools buffer." + ); + } + return selector; + } + + #range(query: TimelineQuery, now: number, windowStart: number): { from: number; to: number } { + const hasFrom = query.from !== undefined; + const hasTo = query.to !== undefined; + const hasLast = query.lastMinutes !== undefined; + if (hasLast && (hasFrom || hasTo)) { + throw new TimelineQueryError("Pass lastMinutes or from/to, not both."); + } + if (hasLast) { + if (!Number.isInteger(query.lastMinutes) || (query.lastMinutes as number) < 1) { + throw new TimelineQueryError("lastMinutes must be a positive integer."); + } + return { from: now - (query.lastMinutes as number) * 60_000, to: now }; + } + const from = hasFrom ? parseTime(query.from as string | number, "from") : windowStart; + const to = hasTo ? parseTime(query.to as string | number, "to") : now; + if (from > to) throw new TimelineQueryError("from is after to."); + return { from, to }; + } + + #limit(limit: number | undefined): number { + if (limit === undefined) return DEFAULT_LIMIT; + if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) { + throw new TimelineQueryError(`limit must be an integer from 1 to ${MAX_LIMIT}.`); + } + return limit; + } + + #wasTracked(selector: Selector): boolean { + const tab = selector.chromeTabId; + const origin = selector.origin; + if (tab !== undefined && origin !== undefined) { + return this.#tabKnown(tab) || this.#originKnown(origin); + } + if (tab !== undefined) return this.#tabKnown(tab); + return origin !== undefined && this.#originKnown(origin); + } + + #tabKnown(chromeTabId: number): boolean { + return ( + this.#targets.some((target) => target.kind === "tab" && target.chromeTabId === chromeTabId) || + this.#console.some((entry) => entry.chromeTabId === chromeTabId) || + this.#network.some((entry) => entry.chromeTabId === chromeTabId) + ); + } + + #originKnown(origin: string): boolean { + return ( + this.#targets.some((target) => target.origin === origin) || + this.#console.some((entry) => entry.origin === origin) || + this.#network.some((entry) => entry.origin === origin) + ); + } + + #enabledFor(entry: TimelineEntry): boolean { + if ( + this.#targets.some( + (target) => target.enabled && target.kind === "tab" && target.chromeTabId === entry.chromeTabId + ) + ) { + return true; + } + return this.#targets.some( + (target) => target.enabled && target.kind === "origin" && target.origin === entry.origin + ); + } + + #matches(entry: TimelineEntry, selector: Selector): boolean { + if (selector.chromeTabId !== undefined && entry.chromeTabId !== selector.chromeTabId) return false; + if (selector.origin !== undefined && entry.origin !== selector.origin) return false; + return true; + } + + #normalizeTarget(raw: unknown, now: number): TimelineTarget | null { + if (!raw || typeof raw !== "object") return null; + const source = raw as Record; + const kind = source["kind"]; + const enabledAt = typeof source["enabledAt"] === "number" && Number.isFinite(source["enabledAt"]) + ? source["enabledAt"] + : now; + if (kind === "tab") { + const chromeTabId = source["chromeTabId"]; + if (typeof chromeTabId !== "number" || !Number.isInteger(chromeTabId) || chromeTabId <= 0) { + return null; + } + const origin = typeof source["origin"] === "string" ? normalizeOrigin(source["origin"]) ?? "" : ""; + return { + kind: "tab", + chromeTabId, + origin, + url: typeof source["url"] === "string" ? clipString(source["url"]) : "", + title: typeof source["title"] === "string" ? clipString(source["title"]) : "", + enabledAt, + enabled: true, + }; + } + if (kind === "origin") { + const origin = typeof source["origin"] === "string" ? normalizeOrigin(source["origin"]) : null; + if (!origin) return null; + return { + kind: "origin", + chromeTabId: null, + origin, + url: "", + title: "", + enabledAt, + enabled: true, + }; + } + return null; + } + + #normalizeEntry(raw: unknown, now: number): TimelineEntry | null { + if (!raw || typeof raw !== "object") return null; + const source = raw as Record; + const chromeTabId = source["chromeTabId"]; + if (typeof chromeTabId !== "number" || !Number.isInteger(chromeTabId) || chromeTabId <= 0) { + return null; + } + const originSource = typeof source["origin"] === "string" ? source["origin"] : ""; + const urlSource = typeof source["url"] === "string" ? source["url"] : ""; + const origin = normalizeOrigin(originSource) ?? normalizeOrigin(urlSource); + if (!origin) return null; + let timestamp = typeof source["timestamp"] === "number" && Number.isFinite(source["timestamp"]) + ? source["timestamp"] + : now; + if (timestamp > now) timestamp = now; + + if (source["kind"] === "console") { + const level = typeof source["level"] === "string" && source["level"].trim() ? source["level"] : "log"; + const message = typeof source["message"] === "string" ? source["message"] : ""; + return { + kind: "console", + chromeTabId, + origin, + url: clipString(urlSource || origin), + level: clipString(level).slice(0, 32), + message: clipString(message), + timestamp, + }; + } + if (source["kind"] === "network") { + const method = typeof source["method"] === "string" && source["method"].trim() + ? source["method"].toUpperCase().slice(0, 16) + : "GET"; + const status = typeof source["status"] === "number" && Number.isFinite(source["status"]) + ? Math.trunc(source["status"]) + : 0; + const entry: TimelineNetworkEntry = { + kind: "network", + chromeTabId, + origin, + url: clipString(urlSource || origin), + method, + status, + timestamp, + }; + if (typeof source["startedAt"] === "number" && Number.isFinite(source["startedAt"])) { + entry.startedAt = source["startedAt"]; + } + if (typeof source["durationMs"] === "number" && Number.isFinite(source["durationMs"])) { + entry.durationMs = source["durationMs"]; + } + if (typeof source["error"] === "string" && source["error"]) entry.error = clipString(source["error"]); + const headers = asRecord(source["requestHeaders"]); + const stripped = headers ? stripCredentialHeaders(headers) : undefined; + if (stripped) entry.requestHeaders = stripped; + if (typeof source["requestBody"] === "string" && source["requestBody"]) { + entry.requestBody = clipString(source["requestBody"]); + } + return entry; + } + return null; + } + + #evict(entries: TimelineEntry[], chromeTabId: number): void { + let count = 0; + for (const entry of entries) { + if (entry.chromeTabId === chromeTabId) count += 1; + } + let extra = count - MAX_PER_TAB; + if (extra <= 0) return; + for (let i = 0; i < entries.length && extra > 0; i++) { + if (entries[i]?.chromeTabId === chromeTabId) { + entries.splice(i, 1); + i -= 1; + extra -= 1; + } + } + } + + #prune(now: number): void { + const cutoff = now - TIMELINE_WINDOW_MS; + this.#console = this.#console.filter((entry) => entry.timestamp >= cutoff); + this.#network = this.#network.filter((entry) => entry.timestamp >= cutoff); + this.#targets = this.#targets.filter((target) => { + if (target.enabled) return true; + if (target.enabledAt >= cutoff) return true; + if (target.kind === "tab" && target.chromeTabId !== null) { + return ( + this.#console.some((entry) => entry.chromeTabId === target.chromeTabId) || + this.#network.some((entry) => entry.chromeTabId === target.chromeTabId) + ); + } + return ( + this.#console.some((entry) => entry.origin === target.origin) || + this.#network.some((entry) => entry.origin === target.origin) + ); + }); + } + + #scheduleFlush(): void { + if (!this.#dir) return; + if (this.#flushTimer) return; + this.#flushTimer = setTimeout(() => { + this.#flushTimer = null; + this.#write(); + }, 200); + this.#flushTimer.unref?.(); + } + + #file(): string | null { + return this.#dir ? path.join(this.#dir, FILE_NAME) : null; + } + + #load(): void { + const file = this.#file(); + if (!file) return; + try { + const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as { + targets?: unknown; + console?: unknown; + network?: unknown; + }; + const now = this.#now(); + if (Array.isArray(parsed.targets)) { + for (const item of parsed.targets) { + const target = this.#normalizeTarget(item, now); + if (!target) continue; + if (item && typeof item === "object" && (item as { enabled?: unknown }).enabled === false) { + target.enabled = false; + } + this.#targets.push(target); + } + } + if (Array.isArray(parsed.console)) { + for (const item of parsed.console) { + const entry = this.#normalizeEntry(item, now); + if (entry && entry.kind === "console") this.#console.push(entry); + } + } + if (Array.isArray(parsed.network)) { + for (const item of parsed.network) { + const entry = this.#normalizeEntry(item, now); + if (entry && entry.kind === "network") this.#network.push(entry); + } + } + this.#prune(now); + } catch (error) { + const code = (error as NodeJS.ErrnoException)?.code; + if (code !== "ENOENT") logger.warn("Could not read timeline file:", error); + this.#targets = []; + this.#console = []; + this.#network = []; + } + } + + #write(): void { + const file = this.#file(); + if (!file || !this.#dir) return; + try { + fs.mkdirSync(this.#dir, { recursive: true, mode: 0o700 }); + const body = JSON.stringify( + { + version: 1, + targets: this.#targets, + console: this.#console, + network: this.#network, + }, + null, + 2 + ); + const tmp = `${file}.${process.pid}.tmp`; + fs.writeFileSync(tmp, body, { mode: 0o600 }); + fs.renameSync(tmp, file); + fs.chmodSync(file, 0o600); + } catch (error) { + logger.warn("Could not write timeline file:", error); + } + } +} + +function parseTime(value: string | number, label: string): number { + if (typeof value === "number" && Number.isFinite(value)) return value; + if (typeof value === "string" && value.trim()) { + const asNumber = Number(value); + if (Number.isFinite(asNumber) && /^\d+(\.\d+)?$/.test(value.trim())) return asNumber; + const parsed = Date.parse(value); + if (Number.isFinite(parsed)) return parsed; + } + throw new TimelineQueryError(`${label} must be an ISO time or epoch milliseconds.`); +} + +function page( + entries: T[], + limit: number +): { entries: T[]; truncated: boolean } { + const ordered = [...entries].sort((a, b) => a.timestamp - b.timestamp); + if (ordered.length <= limit) return { entries: ordered, truncated: false }; + return { entries: ordered.slice(ordered.length - limit), truncated: true }; +} + +function asRecord(value: unknown): Record | undefined { + if (!value || typeof value !== "object" || Array.isArray(value)) return undefined; + return value as Record; +} diff --git a/browser-tools-mcp/src/timeline/tools.ts b/browser-tools-mcp/src/timeline/tools.ts new file mode 100644 index 00000000..85ff0128 --- /dev/null +++ b/browser-tools-mcp/src/timeline/tools.ts @@ -0,0 +1,221 @@ +import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; + +import type { ConnectorClient } from "../mcp/client.js"; +import { CHROME_TAB_ID } from "../tabs/contract.js"; + +type TextContent = { type: "text"; text: string }; + +export type TimelineToolResult = { + content: TextContent[]; + structuredContent?: Record; + isError?: boolean; +}; + +function ok(structured: Record): TimelineToolResult { + return { + content: [{ type: "text", text: JSON.stringify(structured, null, 2) }], + structuredContent: structured, + }; +} + +function fail(error: unknown): TimelineToolResult { + const message = error instanceof Error ? error.message : String(error); + return { content: [{ type: "text", text: message }], isError: true }; +} + +const LIST_TRACKED_DESCRIPTION = + "Tabs and origins the user has turned on for the local 8-hour log. " + + "Tracking is off until they enable a tab or a site in the extension popup. " + + "An empty list means nothing is being recorded. This does not attach the debugger, " + + "does not hide the debugging banner, and does not read the DevTools log buffer."; + +const GET_TIMELINE_DESCRIPTION = + "Redacted console and network for one chromeTabId or one origin, between from and to " + + "(ISO times or epoch milliseconds) or over lastMinutes. The log is local, kept for a " + + "rolling 8 hours, then dropped. Cookie and Authorization values are removed before storage. " + + "If that tab or origin was never enabled, or the time range is outside the 8-hour window, " + + "console and network are empty and reason says not-enabled or outside-window. " + + "This does not guess from getConsoleLogs or any other tab. " + + "It does not attach the debugger and does not hide the debugging banner. " + + "wipeLogs does not clear this log."; + +const consoleEntry = z.object({ + kind: z.literal("console"), + chromeTabId: z.number().int(), + origin: z.string(), + url: z.string(), + level: z.string(), + message: z.string(), + timestamp: z.number(), +}); + +const networkEntry = z.object({ + kind: z.literal("network"), + chromeTabId: z.number().int(), + origin: z.string(), + url: z.string(), + method: z.string(), + status: z.number().int(), + timestamp: z.number(), + startedAt: z.number().optional(), + durationMs: z.number().optional(), + error: z.string().optional(), + requestHeaders: z.record(z.string(), z.string()).optional(), + requestBody: z.string().optional(), +}); + +const targetShape = { + kind: z.enum(["tab", "origin"]), + chromeTabId: z.number().int().nullable(), + origin: z.string(), + url: z.string(), + title: z.string(), + enabledAt: z.number(), + enabled: z.boolean(), +}; + +const timelineOutput = { + tracked: z.boolean().describe("False when this tab or origin was never enabled."), + reason: z.enum(["ok", "not-enabled", "outside-window", "none-in-range"]), + chromeTabId: z.number().int().nullable(), + origin: z.string().nullable(), + from: z.string(), + to: z.string(), + windowStart: z.string().describe("Start of the rolling 8-hour window."), + retentionHours: z.number().int(), + localOnly: z.literal(true), + clipped: z.boolean().describe("True when the requested range extended outside the window and was cut to it."), + console: z.array(consoleEntry), + network: z.array(networkEntry), + consoleTotal: z.number().int(), + networkTotal: z.number().int(), + truncated: z.boolean(), +}; + +const readOnly = { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, +} as const; + +export interface TimelineToolDefinition { + name: string; + register(server: McpServer, client: ConnectorClient): void; +} + +function timeArg(value: unknown): string | number | undefined { + if (typeof value === "string" && value.trim()) return value; + if (typeof value === "number" && Number.isFinite(value)) return value; + return undefined; +} + +function queryFromArgs(args: Record) { + const from = timeArg(args["from"]); + const to = timeArg(args["to"]); + return { + ...(typeof args["chromeTabId"] === "number" ? { chromeTabId: args["chromeTabId"] } : {}), + ...(typeof args["origin"] === "string" ? { origin: args["origin"] } : {}), + ...(from !== undefined ? { from } : {}), + ...(to !== undefined ? { to } : {}), + ...(typeof args["lastMinutes"] === "number" ? { lastMinutes: args["lastMinutes"] } : {}), + ...(typeof args["limit"] === "number" ? { limit: args["limit"] } : {}), + }; +} + +/** + * Runs one timeline tool. Returns null for every other tool name so the MCP + * server and the CLI share this path. + */ +export async function invokeTimelineTool( + name: string, + client: ConnectorClient, + args: Record = {} +): Promise { + try { + switch (name) { + case "listTracked": + return ok((await client.listTracked()) as unknown as Record); + case "getTimeline": + return ok((await client.getTimeline(queryFromArgs(args))) as unknown as Record); + default: + return null; + } + } catch (error) { + return fail(error); + } +} + +export const TIMELINE_TOOLS: TimelineToolDefinition[] = [ + { + name: "listTracked", + register(server, client) { + server.registerTool( + "listTracked", + { + title: "List tracked tabs and origins", + description: LIST_TRACKED_DESCRIPTION, + outputSchema: { + retentionHours: z.number().int(), + windowStart: z.string(), + localOnly: z.literal(true), + targets: z.array(z.object(targetShape)), + }, + annotations: { title: "List tracked tabs and origins", ...readOnly }, + }, + async () => invokeTimelineTool("listTracked", client, {}) as Promise + ); + }, + }, + { + name: "getTimeline", + register(server, client) { + server.registerTool( + "getTimeline", + { + title: "Get 8-hour tab timeline", + description: GET_TIMELINE_DESCRIPTION, + inputSchema: { + chromeTabId: z + .number() + .int() + .positive() + .optional() + .describe(`${CHROME_TAB_ID} The tab the user enabled, or a tab on an enabled origin.`), + origin: z + .string() + .optional() + .describe( + "http(s) origin the user enabled, such as https://billing.example:443. Default ports are included." + ), + from: z + .union([z.string(), z.number()]) + .optional() + .describe("Range start, as an ISO time or epoch milliseconds."), + to: z + .union([z.string(), z.number()]) + .optional() + .describe("Range end, as an ISO time or epoch milliseconds."), + lastMinutes: z + .number() + .int() + .positive() + .optional() + .describe("Instead of from/to, the last N minutes ending now."), + limit: z + .number() + .int() + .min(1) + .max(500) + .optional() + .describe("Maximum console entries and maximum network entries. Defaults to 100."), + }, + outputSchema: timelineOutput, + annotations: { title: "Get 8-hour tab timeline", ...readOnly }, + }, + async (args) => invokeTimelineTool("getTimeline", client, args) as Promise + ); + }, + }, +]; diff --git a/browser-tools-mcp/src/tools-cli.ts b/browser-tools-mcp/src/tools-cli.ts index 03c5d347..589610a0 100644 --- a/browser-tools-mcp/src/tools-cli.ts +++ b/browser-tools-mcp/src/tools-cli.ts @@ -96,6 +96,8 @@ Resource commands: Examples: browser-tools getConnectionStatus browser-tools getConsoleLogs '{"limit":20}' + browser-tools listTracked + browser-tools getTimeline '{"origin":"https://billing.example:443","lastMinutes":10}' browser-tools listTabs browser-tools --allow-actions navigateBrowser '{"url":"http://localhost:3000/","tabId":1}' browser-tools --allow-actions navigateTab '{"url":"http://127.0.0.1:3000/","chromeTabId":4}' diff --git a/browser-tools-mcp/test/integration/mcp-server.test.ts b/browser-tools-mcp/test/integration/mcp-server.test.ts index de18dc93..e725bc92 100644 --- a/browser-tools-mcp/test/integration/mcp-server.test.ts +++ b/browser-tools-mcp/test/integration/mcp-server.test.ts @@ -70,7 +70,9 @@ describe("tool registration", () => { "getNetworkLogs", "getPageInfo", "getSelectedElement", + "getTimeline", "listBrowserTabs", + "listTracked", "listTabs", "navigateBrowser", "navigateTab", diff --git a/browser-tools-mcp/test/integration/timeline.test.ts b/browser-tools-mcp/test/integration/timeline.test.ts new file mode 100644 index 00000000..97b21458 --- /dev/null +++ b/browser-tools-mcp/test/integration/timeline.test.ts @@ -0,0 +1,254 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import path from "node:path"; +import os from "node:os"; +import fs from "node:fs"; +import request from "supertest"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; + +import { createConnector, type Connector } from "../../src/connector/connector"; +import { InProcessConnectorClient } from "../../src/mcp/client"; +import { createMcpServer } from "../../src/mcp/server"; +import { invokeTool } from "../../src/mcp/tool-invoke"; +import { FakeExtension } from "../helpers/fake-extension"; + +let connector: Connector; +let extension: FakeExtension | null = null; +let devtools: FakeExtension | null = null; +let client: Client; +let screenshotDir: string; +let closeServer: () => Promise; + +const ORIGIN = "https://billing.example:443"; +const SECRET = "super-secret-token"; + +async function startServer() { + const { server } = createMcpServer({ client: new InProcessConnectorClient(connector) }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + client = new Client({ name: "test-client", version: "1.0.0" }); + await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]); + closeServer = async () => { + await client.close(); + await server.close(); + }; +} + +beforeEach(async () => { + screenshotDir = fs.mkdtempSync(path.join(os.tmpdir(), "bt-timeline-mcp-")); + connector = await createConnector({ port: 0, screenshotDir, requestTimeoutMs: 3_000 }); + await startServer(); + extension = new FakeExtension({ port: connector.port, role: "worker" }); + await extension.connect(); + await extension.waitForWelcome(); +}); + +afterEach(async () => { + await closeServer?.(); + await extension?.close(); + await devtools?.close(); + extension = null; + devtools = null; + await connector?.close(); + fs.rmSync(screenshotDir, { recursive: true, force: true }); +}); + +function auth() { + return `Bearer ${connector.token}`; +} + +async function enableBillingTab() { + const targets = [ + { + kind: "tab", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/pay", + title: "Billing", + enabledAt: Date.now(), + }, + ]; + await vi.waitFor(async () => { + extension!.send({ type: "timeline-targets", targets }); + const listed: any = await client.callTool({ name: "listTracked", arguments: {} }); + const body = JSON.parse(listed.content[0].text); + expect(body.targets).toHaveLength(1); + }); +} + +describe("opt-in timeline", () => { + it("stays empty until the user enables a tab, then answers by time", async () => { + const before: any = await client.callTool({ + name: "getTimeline", + arguments: { chromeTabId: 4, lastMinutes: 30 }, + }); + const empty = JSON.parse(before.content[0].text); + expect(before.isError).toBeUndefined(); + expect(empty.tracked).toBe(false); + expect(empty.reason).toBe("not-enabled"); + expect(empty.console).toEqual([]); + expect(empty.network).toEqual([]); + + await enableBillingTab(); + const now = Date.now(); + extension!.send({ + type: "timeline-event", + event: { + kind: "console", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/pay", + level: "error", + message: "invoice failed", + timestamp: now - 2 * 60_000, + }, + }); + extension!.send({ + type: "timeline-event", + event: { + kind: "network", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/api/pay", + method: "POST", + status: 500, + timestamp: now - 2 * 60_000, + requestHeaders: { + Authorization: `Bearer ${SECRET}`, + Cookie: "session=abc123secret", + "Content-Type": "application/json", + }, + }, + }); + + await vi.waitFor(async () => { + const result: any = await client.callTool({ + name: "getTimeline", + arguments: { chromeTabId: 4, lastMinutes: 10 }, + }); + const body = JSON.parse(result.content[0].text); + expect(body.reason).toBe("ok"); + expect(body.console.map((entry: { message: string }) => entry.message)).toEqual(["invoice failed"]); + }); + + const result: any = await client.callTool({ + name: "getTimeline", + arguments: { origin: "https://billing.example", lastMinutes: 10 }, + }); + const body = JSON.parse(result.content[0].text); + const serialized = JSON.stringify(body); + expect(serialized).not.toContain(SECRET); + expect(serialized).not.toContain("abc123secret"); + expect(body.network[0].requestHeaders["Content-Type"]).toBe("application/json"); + expect(body.network[0].status).toBe(500); + + const other: any = await client.callTool({ + name: "getTimeline", + arguments: { chromeTabId: 9, lastMinutes: 10 }, + }); + const otherBody = JSON.parse(other.content[0].text); + expect(otherBody.reason).toBe("not-enabled"); + expect(otherBody.console).toEqual([]); + expect(JSON.stringify(otherBody)).not.toContain("invoice failed"); + + const outside: any = await client.callTool({ + name: "getTimeline", + arguments: { + chromeTabId: 4, + from: new Date(now - 10 * 24 * 60 * 60_000).toISOString(), + to: new Date(now - 9 * 24 * 60 * 60_000).toISOString(), + }, + }); + const outsideBody = JSON.parse(outside.content[0].text); + expect(outsideBody.reason).toBe("outside-window"); + expect(outsideBody.console).toEqual([]); + expect(outsideBody.network).toEqual([]); + expect(JSON.stringify(outsideBody)).not.toContain("invoice failed"); + }); + + it("does not treat the DevTools buffer as the timeline", async () => { + devtools = new FakeExtension({ port: connector.port, tabId: 4 }); + await devtools.connect(); + await devtools.waitForWelcome(); + devtools.send({ + type: "console", + entries: [{ level: "error", message: "devtools only", timestamp: Date.now() }], + }); + devtools.send({ + type: "timeline-event", + event: { + kind: "console", + chromeTabId: 4, + origin: ORIGIN, + message: "forged from devtools", + timestamp: Date.now(), + }, + }); + + await vi.waitFor(async () => { + const logs: any = await client.callTool({ name: "getConsoleLogs", arguments: {} }); + expect(JSON.parse(logs.content[0].text).entries[0].message).toBe("devtools only"); + }); + + const timeline: any = await client.callTool({ + name: "getTimeline", + arguments: { chromeTabId: 4, lastMinutes: 30 }, + }); + const body = JSON.parse(timeline.content[0].text); + expect(body.reason).toBe("not-enabled"); + expect(JSON.stringify(body)).not.toContain("devtools only"); + expect(JSON.stringify(body)).not.toContain("forged from devtools"); + }); + + it("serves the same log over the local API and the CLI invoke path", async () => { + await enableBillingTab(); + extension!.send({ + type: "timeline-event", + event: { + kind: "console", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/pay", + level: "error", + message: "invoice failed", + timestamp: Date.now(), + }, + }); + + await vi.waitFor(async () => { + const res = await request(connector.app) + .get("/api/timeline/logs") + .query({ chromeTabId: 4, lastMinutes: 15 }) + .set("Authorization", auth()); + expect(res.status).toBe(200); + expect(res.body.console[0].message).toBe("invoice failed"); + }); + + const cli = await invokeTool("getTimeline", new InProcessConnectorClient(connector), { + chromeTabId: 4, + lastMinutes: 15, + }); + expect(cli.isError).toBeUndefined(); + expect(cli.structuredContent?.["reason"]).toBe("ok"); + + const missing = await request(connector.app) + .get("/api/timeline/logs") + .set("Authorization", auth()); + expect(missing.status).toBe(400); + + const hidden = await createConnector({ + port: 0, + screenshotDir, + requestTimeoutMs: 3_000, + disabledTools: ["getTimeline"], + }); + try { + const refused = await request(hidden.app) + .get("/api/timeline/logs") + .query({ chromeTabId: 4 }) + .set("Authorization", `Bearer ${hidden.token}`); + expect(refused.status).toBe(403); + } finally { + await hidden.close(); + } + }); +}); diff --git a/browser-tools-mcp/test/unit/api-policy.test.ts b/browser-tools-mcp/test/unit/api-policy.test.ts index f4e86593..f3521b47 100644 --- a/browser-tools-mcp/test/unit/api-policy.test.ts +++ b/browser-tools-mcp/test/unit/api-policy.test.ts @@ -64,6 +64,36 @@ describe("decideApiAccess", () => { expect(decision).toMatchObject({ ok: false, code: "TOOL_DISABLED" }); }); + it("gates the timeline on the timeline tools", () => { + expect( + decideApiAccess({ + method: "GET", + path: "/timeline", + query: {}, + enabled: new Set(["listTracked"]), + actionsAllowed: false, + }).ok + ).toBe(true); + expect( + decideApiAccess({ + method: "GET", + path: "/timeline/logs", + query: {}, + enabled: new Set(["listTracked"]), + actionsAllowed: false, + }).ok + ).toBe(false); + expect( + decideApiAccess({ + method: "GET", + path: "/timeline/logs", + query: { chromeTabId: "4" }, + enabled: new Set(["getTimeline"]), + actionsAllowed: false, + }).ok + ).toBe(true); + }); + it("maps an audit artifact back to the one audit tool", () => { const onlySeo = new Set(["runSEOAudit"]); expect( diff --git a/browser-tools-mcp/test/unit/extension-timeline.test.ts b/browser-tools-mcp/test/unit/extension-timeline.test.ts new file mode 100644 index 00000000..330fb063 --- /dev/null +++ b/browser-tools-mcp/test/unit/extension-timeline.test.ts @@ -0,0 +1,132 @@ +import fs from "node:fs"; +import path from "node:path"; +import vm from "node:vm"; +import { fileURLToPath } from "node:url"; +import { beforeAll, describe, expect, it } from "vitest"; + +/** + * The extension's opt-in timeline, loaded from the files that ship. + * Capture must not attach the debugger or read document.cookie. + */ + +const root = path.resolve(fileURLToPath(new URL("../../../chrome-extension", import.meta.url))); + +interface TimelineApi { + emptyState(): { tabs: Record; origins: Record }; + isTracked(tab: { id?: number; url?: string }, state: unknown): boolean; + prepareEvent(entry: Record, tab: { id?: number; url?: string }): any; + targetsFromState(state: unknown): unknown[]; + installCapture: () => void; + installBridge: () => void; + stripCredentialHeaders(headers: Record): Record; +} + +let timeline: TimelineApi; + +beforeAll(() => { + const source = ["shared.js", "gates.js", "timeline.js"] + .map((name) => fs.readFileSync(path.join(root, name), "utf8")) + .join("\n"); + const loaded = new Function(`${source}\nreturn BTMCP_TIMELINE;`) as () => TimelineApi; + timeline = loaded(); +}); + +describe("timeline opt-in", () => { + it("tracks nothing until a tab or origin is enabled", () => { + const state = timeline.emptyState(); + const tab = { id: 4, url: "https://billing.example/pay" }; + expect(timeline.isTracked(tab, state)).toBe(false); + state.tabs["4"] = { origin: "https://billing.example:443", url: "", title: "", enabledAt: 1 }; + expect(timeline.isTracked(tab, state)).toBe(true); + expect(timeline.isTracked({ id: 5, url: "https://billing.example/pay" }, state)).toBe(false); + state.origins["https://billing.example:443"] = { enabledAt: 1 }; + expect(timeline.isTracked({ id: 5, url: "https://billing.example/pay" }, state)).toBe(true); + expect(timeline.isTracked({ id: 5, url: "https://other.example/" }, state)).toBe(false); + }); + + it("attributes the event to the real tab and strips credentials", () => { + const prepared = timeline.prepareEvent( + { + kind: "network", + chromeTabId: 999, + url: "https://billing.example/api/pay", + method: "POST", + status: 500, + requestHeaders: { + Authorization: "Bearer super-secret-token", + Cookie: "session=abc123secret", + "Content-Type": "application/json", + }, + }, + { id: 4, url: "https://billing.example/pay" } + ); + expect(prepared.chromeTabId).toBe(4); + expect(prepared.origin).toBe("https://billing.example:443"); + const serialized = JSON.stringify(prepared); + expect(serialized).not.toContain("super-secret-token"); + expect(serialized).not.toContain("abc123secret"); + expect(prepared.requestHeaders["Content-Type"]).toBe("application/json"); + expect(prepared.requestHeaders.Authorization).toBeUndefined(); + expect(prepared.requestHeaders.Cookie).toBeUndefined(); + }); + + it("does not use the debugger or document.cookie", () => { + const source = fs.readFileSync(path.join(root, "timeline.js"), "utf8"); + const worker = fs.readFileSync(path.join(root, "worker.js"), "utf8"); + const capture = `${timeline.installCapture.toString()}\n${timeline.installBridge.toString()}`; + expect(capture).not.toMatch(/chrome\.debugger|debugger\.attach|document\.cookie/); + expect(source).not.toMatch(/chrome\.debugger|debugger\.attach|document\.cookie/); + expect(worker).not.toMatch(/chrome\.debugger|debugger\.attach/); + expect(source).toMatch(/Record|8-hour|Cookie/); + }); +}); + +describe("page capture hook", () => { + it("records console and fetch without cookie or authorization", async () => { + const events: Array<{ entry: Record }> = []; + const sandbox: Record = { + Date, + JSON, + Array, + String, + Object, + Error, + Promise, + }; + sandbox["globalThis"] = sandbox; + sandbox["console"] = { + log: () => undefined, + info: () => undefined, + warn: () => undefined, + error: () => undefined, + debug: () => undefined, + }; + sandbox["addEventListener"] = () => undefined; + sandbox["postMessage"] = (data: { entry: Record }) => { + events.push(data); + }; + sandbox["location"] = { href: "https://billing.example/pay", origin: "https://billing.example" }; + sandbox["fetch"] = async () => ({ status: 201 }); + vm.createContext(sandbox); + vm.runInContext(`(${timeline.installCapture.toString()})()`, sandbox); + + (sandbox["console"] as { log: (...args: unknown[]) => void }).log("invoice failed"); + await (sandbox["fetch"] as (url: string, init: unknown) => Promise)( + "https://billing.example/api/pay", + { + method: "POST", + headers: { Authorization: "Bearer super-secret-token", "Content-Type": "application/json" }, + body: "amount=10", + } + ); + + expect(events.map((event) => event.entry["kind"])).toEqual(["console", "network"]); + expect(events[0]?.entry["message"]).toBe("invoice failed"); + const network = events[1]?.entry; + expect(network?.["status"]).toBe(201); + const headers = network?.["requestHeaders"] as Record; + expect(headers["Content-Type"]).toBe("application/json"); + expect(headers["Authorization"]).toBeUndefined(); + expect(JSON.stringify(network)).not.toContain("super-secret-token"); + }); +}); diff --git a/browser-tools-mcp/test/unit/timeline-store.test.ts b/browser-tools-mcp/test/unit/timeline-store.test.ts new file mode 100644 index 00000000..e045460b --- /dev/null +++ b/browser-tools-mcp/test/unit/timeline-store.test.ts @@ -0,0 +1,282 @@ +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; + +import { + TimelineQueryError, + TimelineStore, + TIMELINE_WINDOW_MS, + normalizeOrigin, + stripCredentialText, +} from "../../src/timeline/store"; + +const NOW = Date.parse("2026-10-27T15:10:00.000Z"); +const ORIGIN = "https://billing.example:443"; +const SECRET = "super-secret-token"; +const COOKIE = "session=abc123secret"; + +function trackedTab(store: TimelineStore, chromeTabId = 4) { + store.replaceTargets([ + { + kind: "tab", + chromeTabId, + origin: "https://billing.example/pay", + url: "https://billing.example/pay", + title: "Billing", + enabledAt: NOW - 60_000, + }, + ]); +} + +describe("normalizeOrigin", () => { + it("writes the default port", () => { + expect(normalizeOrigin("https://billing.example/pay")).toBe(ORIGIN); + expect(normalizeOrigin("http://localhost:3000/app")).toBe("http://localhost:3000"); + }); + + it("rejects non-http pages", () => { + expect(normalizeOrigin("chrome://settings")).toBeNull(); + expect(normalizeOrigin("not a url")).toBeNull(); + }); +}); + +describe("stripCredentialText", () => { + it("removes cookie and authorization values", () => { + const out = stripCredentialText( + `Cookie: ${COOKIE}\nAuthorization: Bearer ${SECRET}\nstill here` + ); + expect(out).not.toContain(COOKIE); + expect(out).not.toContain(SECRET); + expect(out).toContain("still here"); + }); +}); + +describe("TimelineStore", () => { + const dirs: string[] = []; + + afterEach(() => { + for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true }); + }); + + function store(now = NOW) { + return new TimelineStore({ now: () => now }); + } + + it("lists nothing until a tab or origin is enabled", () => { + const timeline = store(); + expect(timeline.list().targets).toEqual([]); + expect(timeline.list().localOnly).toBe(true); + expect(timeline.list().retentionHours).toBe(8); + }); + + it("returns an empty result for a tab that was never enabled", () => { + const timeline = store(); + trackedTab(timeline, 4); + timeline.ingest(consoleEvent(4, "invoice failed")); + const missed = timeline.query({ chromeTabId: 9 }); + expect(missed.tracked).toBe(false); + expect(missed.reason).toBe("not-enabled"); + expect(missed.console).toEqual([]); + expect(missed.network).toEqual([]); + expect(JSON.stringify(missed)).not.toContain("invoice failed"); + }); + + it("does not return another tab's logs", () => { + const timeline = store(); + trackedTab(timeline, 4); + timeline.ingest(consoleEvent(4, "invoice failed")); + trackedTab(timeline, 8); + timeline.replaceTargets([ + { + kind: "tab", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/pay", + title: "Billing", + enabledAt: NOW - 60_000, + }, + { + kind: "tab", + chromeTabId: 8, + origin: "https://other.example:443", + url: "https://other.example/", + title: "Other", + enabledAt: NOW - 60_000, + }, + ]); + timeline.ingest(consoleEvent(8, "other tab", "https://other.example/")); + const billing = timeline.query({ chromeTabId: 4 }); + expect(billing.reason).toBe("ok"); + expect(billing.console.map((entry) => entry.message)).toEqual(["invoice failed"]); + const other = timeline.query({ chromeTabId: 8 }); + expect(other.console.map((entry) => entry.message)).toEqual(["other tab"]); + }); + + it("queries by origin and by lastMinutes or from/to", () => { + const timeline = store(); + timeline.replaceTargets([ + { kind: "origin", origin: "https://billing.example/pay", enabledAt: NOW - 120_000 }, + ]); + expect(timeline.list().targets.map((target) => target.origin)).toEqual([ORIGIN]); + timeline.ingest(consoleEvent(4, "at 3:00", ORIGIN, NOW - 10 * 60_000)); + timeline.ingest(consoleEvent(4, "at 3:09", ORIGIN, NOW - 60_000)); + + const recent = timeline.query({ origin: "https://billing.example", lastMinutes: 5 }); + expect(recent.reason).toBe("ok"); + expect(recent.console.map((entry) => entry.message)).toEqual(["at 3:09"]); + + const earlier = timeline.query({ + origin: ORIGIN, + from: new Date(NOW - 11 * 60_000).toISOString(), + to: new Date(NOW - 9 * 60_000).toISOString(), + }); + expect(earlier.console.map((entry) => entry.message)).toEqual(["at 3:00"]); + + const gap = timeline.query({ origin: ORIGIN, lastMinutes: 1 }); + // 3:09 is one minute ago, so last 1 minute still includes it. + expect(gap.console.map((entry) => entry.message)).toEqual(["at 3:09"]); + const quiet = timeline.query({ + chromeTabId: 4, + from: new Date(NOW - 30_000).toISOString(), + to: new Date(NOW - 20_000).toISOString(), + }); + expect(quiet.tracked).toBe(true); + expect(quiet.reason).toBe("none-in-range"); + expect(quiet.console).toEqual([]); + }); + + it("returns empty when the time is outside the 8-hour window", () => { + const timeline = store(); + trackedTab(timeline); + timeline.ingest(consoleEvent(4, "invoice failed")); + const outside = timeline.query({ + chromeTabId: 4, + from: new Date(NOW - TIMELINE_WINDOW_MS - 2 * 60 * 60_000).toISOString(), + to: new Date(NOW - TIMELINE_WINDOW_MS - 60 * 60_000).toISOString(), + }); + expect(outside.tracked).toBe(true); + expect(outside.reason).toBe("outside-window"); + expect(outside.console).toEqual([]); + expect(outside.network).toEqual([]); + expect(JSON.stringify(outside)).not.toContain("invoice failed"); + }); + + it("drops entries once they age out of the window", () => { + let now = NOW; + const timeline = new TimelineStore({ now: () => now }); + trackedTab(timeline); + timeline.ingest(consoleEvent(4, "invoice failed")); + now = NOW + TIMELINE_WINDOW_MS + 1; + const aged = timeline.query({ chromeTabId: 4, lastMinutes: 10 }); + expect(aged.console).toEqual([]); + expect(aged.reason).toBe("none-in-range"); + expect(JSON.stringify(aged)).not.toContain("invoice failed"); + }); + + it("strips cookies and Authorization before storage", () => { + const timeline = store(); + trackedTab(timeline); + expect( + timeline.ingest({ + kind: "network", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/api/pay", + method: "POST", + status: 500, + timestamp: NOW, + requestHeaders: { + Authorization: `Bearer ${SECRET}`, + Cookie: COOKIE, + "Set-Cookie": "sid=secret-sid", + "Content-Type": "application/json", + }, + requestBody: `{"authorization":"Bearer ${SECRET}","amount":10}`, + }) + ).toBe(true); + timeline.ingest(consoleEvent(4, `Cookie: ${COOKIE}`)); + const result = timeline.query({ chromeTabId: 4 }); + const serialized = JSON.stringify(result); + expect(serialized).not.toContain(SECRET); + expect(serialized).not.toContain(COOKIE); + expect(serialized).not.toContain("secret-sid"); + expect(result.network[0]?.requestHeaders?.["Content-Type"]).toBe("application/json"); + expect(result.network[0]?.requestHeaders).not.toHaveProperty("Authorization"); + expect(result.network[0]?.requestHeaders).not.toHaveProperty("Cookie"); + expect(result.network[0]?.requestBody).toContain("amount"); + }); + + it("does not store events for a target that is not enabled", () => { + const timeline = store(); + expect(timeline.ingest(consoleEvent(4, "too early"))).toBe(false); + trackedTab(timeline); + timeline.ingest(consoleEvent(4, "kept")); + timeline.replaceTargets([]); + expect(timeline.list().targets).toEqual([]); + expect(timeline.ingest(consoleEvent(4, "after disable"))).toBe(false); + const result = timeline.query({ chromeTabId: 4 }); + expect(result.console.map((entry) => entry.message)).toEqual(["kept"]); + }); + + it("refuses a query that does not name a tab or origin", () => { + const timeline = store(); + expect(() => timeline.query({})).toThrow(TimelineQueryError); + expect(() => timeline.query({ lastMinutes: 5, from: new Date(NOW).toISOString() })).toThrow( + /not both/ + ); + }); + + it("persists only the redacted log, owner-readable", () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bt-timeline-")); + dirs.push(dir); + const timeline = new TimelineStore({ dir, now: () => NOW }); + trackedTab(timeline); + timeline.ingest({ + kind: "network", + chromeTabId: 4, + origin: ORIGIN, + url: "https://billing.example/api/pay", + method: "GET", + status: 200, + timestamp: NOW, + requestHeaders: { Authorization: `Bearer ${SECRET}`, Accept: "application/json" }, + }); + timeline.flush(); + const file = path.join(dir, "timeline.json"); + const raw = fs.readFileSync(file, "utf8"); + expect(raw).not.toContain(SECRET); + expect(raw).toContain("application/json"); + expect(fs.statSync(file).mode & 0o777).toBe(0o600); + + const restored = new TimelineStore({ dir, now: () => NOW }); + expect(restored.query({ chromeTabId: 4 }).network).toHaveLength(1); + expect(restored.list().targets[0]?.chromeTabId).toBe(4); + }); + + it("starts empty when the file is unreadable", () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bt-timeline-")); + dirs.push(dir); + fs.writeFileSync(path.join(dir, "timeline.json"), "{not json", { mode: 0o600 }); + const timeline = new TimelineStore({ dir, now: () => NOW }); + expect(timeline.list().targets).toEqual([]); + expect(timeline.query({ chromeTabId: 4 }).reason).toBe("not-enabled"); + }); +}); + +function consoleEvent( + chromeTabId: number, + message: string, + origin = ORIGIN, + timestamp = NOW +) { + return { + kind: "console" as const, + chromeTabId, + origin, + url: "https://billing.example/pay", + level: "error", + message, + timestamp, + }; +} diff --git a/chrome-extension/popup.html b/chrome-extension/popup.html index cbf782a6..2fbb2b5e 100644 --- a/chrome-extension/popup.html +++ b/chrome-extension/popup.html @@ -36,6 +36,10 @@ font-size: 15px; margin: 0 0 8px; } + h2 { + font-size: 13px; + margin: 16px 0 8px; + } p { margin: 0 0 12px; color: var(--muted); @@ -107,9 +111,29 @@

BrowserTools MCP

This asks Chrome for access. It does not hide the debugging banner, and the debugging banner stays off unless a DevTools capture attaches the debugger.

+

8-hour log

+

+ Off until you turn it on. Console and network for a checked tab or site stay on this machine + for 8 hours, then they are deleted. Cookies and Authorization are removed before they are + stored. +

+ + +

+ This does not hide the debugging banner and does not click or drive the page. An agent can + read the log only for a tab or site you enabled, and only inside the last 8 hours. Sites + other than this machine need “Allow reading pages you have open” above. +

+ diff --git a/chrome-extension/popup.js b/chrome-extension/popup.js index 86b8e7ee..163bad59 100644 --- a/chrome-extension/popup.js +++ b/chrome-extension/popup.js @@ -13,6 +13,9 @@ var allow = document.getElementById("allowPageActions"); var exclude = document.getElementById("excludeOrigins"); var grant = document.getElementById("grantHostAccess"); + var trackTab = document.getElementById("trackTab"); + var trackOrigin = document.getElementById("trackOrigin"); + var trackNote = document.getElementById("trackNote"); var saved = document.getElementById("saved"); function storageGet(area, key) { @@ -56,6 +59,35 @@ } } + async function notifyTimeline() { + try { + await api.runtime.sendMessage({ type: "timeline-sync" }); + } catch (error) { + /* the worker also listens for storage changes */ + } + } + + async function currentTab() { + try { + var tabs = await api.tabs.query({ active: true, currentWindow: true }); + return tabs && tabs[0] ? tabs[0] : null; + } catch (error) { + return null; + } + } + + async function readTimeline() { + var local = await storageGet(api.storage.local, BTMCP_TIMELINE.STORAGE_KEY); + return BTMCP_TIMELINE.normalizeState(local[BTMCP_TIMELINE.STORAGE_KEY]); + } + + async function writeTimeline(state) { + var next = {}; + next[BTMCP_TIMELINE.STORAGE_KEY] = state; + await storageSet(api.storage.local, next); + await notifyTimeline(); + } + async function init() { var session = await storageGet(api.storage.session, BTMCP_GATES.POPUP_SWITCH_KEY); var local = await storageGet(api.storage.local, BTMCP_GATES.EXCLUDE_KEY); @@ -102,6 +134,61 @@ }); } + if (trackTab && trackOrigin) { + var tab = await currentTab(); + var origin = tab ? BTMCP_GATES.originOf(tab.url || "") : null; + var timeline = await readTimeline(); + if (!origin || !tab) { + trackTab.disabled = true; + trackOrigin.disabled = true; + trackNote.textContent = "This page can't be logged. Open an http or https tab."; + } else { + trackTab.checked = Boolean(timeline.tabs[String(tab.id)]); + trackOrigin.checked = Boolean(timeline.origins[origin]); + trackTab.addEventListener("change", async function () { + var live = await currentTab(); + var liveOrigin = live ? BTMCP_GATES.originOf(live.url || "") : null; + if (!live || !liveOrigin) { + trackTab.checked = false; + saved.textContent = "This page can't be logged."; + return; + } + var state = await readTimeline(); + if (trackTab.checked) { + state.tabs[String(live.id)] = { + origin: liveOrigin, + url: live.url || "", + title: live.title || "", + enabledAt: Date.now(), + }; + saved.textContent = "This tab will be logged for 8 hours."; + } else { + delete state.tabs[String(live.id)]; + saved.textContent = "This tab is no longer logged."; + } + await writeTimeline(state); + }); + trackOrigin.addEventListener("change", async function () { + var live = await currentTab(); + var liveOrigin = live ? BTMCP_GATES.originOf(live.url || "") : null; + if (!liveOrigin) { + trackOrigin.checked = false; + saved.textContent = "This site can't be logged."; + return; + } + var state = await readTimeline(); + if (trackOrigin.checked) { + state.origins[liveOrigin] = { enabledAt: Date.now() }; + saved.textContent = "This site will be logged for 8 hours."; + } else { + delete state.origins[liveOrigin]; + saved.textContent = "This site is no longer logged."; + } + await writeTimeline(state); + }); + } + } + document.documentElement.dataset.ready = "true"; } diff --git a/chrome-extension/timeline.js b/chrome-extension/timeline.js new file mode 100644 index 00000000..f121fcef --- /dev/null +++ b/chrome-extension/timeline.js @@ -0,0 +1,398 @@ +/** + * Opt-in 8-hour log for one tab or one origin. + * + * Off until the user checks it in the popup. Capture wraps the page's console + * and fetch/XHR. It does not attach a debugger, so the debugging banner is + * neither shown nor hidden by this log, and it does not click, type, or drive + * the page. + * + * Cookie and Authorization are removed before an event is queued. The + * connector removes them again before writing the log. + */ +var BTMCP_TIMELINE = (function () { + var STORAGE_KEY = "btmcpTimeline"; + var CREDENTIAL = /^(authorization|proxy-authorization|cookie|set-cookie)$/i; + + function emptyState() { + return { tabs: {}, origins: {} }; + } + + function normalizeState(raw) { + var state = emptyState(); + if (!raw || typeof raw !== "object") return state; + var tabs = raw.tabs; + if (tabs && typeof tabs === "object") { + for (var id in tabs) { + if (!Object.prototype.hasOwnProperty.call(tabs, id)) continue; + if (!/^\d+$/.test(id)) continue; + var tab = tabs[id]; + if (!tab || typeof tab !== "object") continue; + state.tabs[id] = { + origin: typeof tab.origin === "string" ? tab.origin : "", + url: typeof tab.url === "string" ? tab.url : "", + title: typeof tab.title === "string" ? tab.title : "", + enabledAt: typeof tab.enabledAt === "number" ? tab.enabledAt : 0, + }; + } + } + var origins = raw.origins; + if (origins && typeof origins === "object") { + for (var origin in origins) { + if (!Object.prototype.hasOwnProperty.call(origins, origin)) continue; + if (!BTMCP_GATES.originOf(origin) || BTMCP_GATES.originOf(origin) !== origin) continue; + var entry = origins[origin]; + state.origins[origin] = { + enabledAt: entry && typeof entry.enabledAt === "number" ? entry.enabledAt : 0, + }; + } + } + return state; + } + + function isTracked(tab, state) { + if (!tab || typeof tab.id !== "number" || !state) return false; + if (state.tabs && state.tabs[String(tab.id)]) return true; + var origin = BTMCP_GATES.originOf(tab.url || ""); + return Boolean(origin && state.origins && state.origins[origin]); + } + + function targetsFromState(state) { + var out = []; + var tabs = (state && state.tabs) || {}; + for (var id in tabs) { + if (!Object.prototype.hasOwnProperty.call(tabs, id)) continue; + var tab = tabs[id]; + out.push({ + kind: "tab", + chromeTabId: Number(id), + origin: tab.origin || "", + url: tab.url || "", + title: tab.title || "", + enabledAt: tab.enabledAt || Date.now(), + }); + } + var origins = (state && state.origins) || {}; + for (var origin in origins) { + if (!Object.prototype.hasOwnProperty.call(origins, origin)) continue; + out.push({ + kind: "origin", + origin: origin, + enabledAt: origins[origin].enabledAt || Date.now(), + }); + } + return out; + } + + function stripCredentialHeaders(headers) { + var out = {}; + if (!headers || typeof headers !== "object") return out; + for (var name in headers) { + if (!Object.prototype.hasOwnProperty.call(headers, name)) continue; + if (CREDENTIAL.test(name)) continue; + var value = headers[name]; + if (typeof value === "string") out[name] = value; + } + return out; + } + + /** + * Attributes the event to the real tab, not to anything the page wrote, + * and scrubs it before it leaves the browser. + */ + function prepareEvent(entry, tab) { + if (!entry || !tab || typeof tab.id !== "number") return null; + var origin = BTMCP_GATES.originOf(tab.url || ""); + if (!origin) return null; + var kind = entry.kind === "network" ? "network" : entry.kind === "console" ? "console" : null; + if (!kind) return null; + var pageUrl = typeof tab.url === "string" ? tab.url : ""; + var base = { + kind: kind, + chromeTabId: tab.id, + origin: origin, + url: kind === "network" && typeof entry.url === "string" && entry.url ? entry.url : pageUrl, + timestamp: typeof entry.timestamp === "number" ? entry.timestamp : Date.now(), + }; + base.url = scrubAndTruncate(base.url, 2000); + if (kind === "console") { + base.level = typeof entry.level === "string" ? entry.level : "log"; + base.message = scrubAndTruncate(typeof entry.message === "string" ? entry.message : "", 2000); + return base; + } + base.method = typeof entry.method === "string" ? entry.method : "GET"; + base.status = typeof entry.status === "number" ? entry.status : 0; + if (typeof entry.startedAt === "number") base.startedAt = entry.startedAt; + if (typeof entry.durationMs === "number") base.durationMs = entry.durationMs; + if (typeof entry.error === "string" && entry.error) base.error = scrubAndTruncate(entry.error, 500); + var headers = stripCredentialHeaders(entry.requestHeaders); + var scrubbed = {}; + for (var name in headers) { + if (!Object.prototype.hasOwnProperty.call(headers, name)) continue; + scrubbed[name] = scrubAndTruncate(headers[name], 500); + } + if (Object.keys(scrubbed).length) base.requestHeaders = scrubbed; + if (typeof entry.requestBody === "string" && entry.requestBody) { + base.requestBody = scrubAndTruncate(entry.requestBody, 2000); + } + return base; + } + + /** + * Runs in the page. Self-contained: the scripting call serializes this + * function alone. Hooks console and fetch/XHR, drops Cookie and + * Authorization, and posts the rest to the extension bridge. No clicks. + */ + function installCapture() { + var root = globalThis; + if (root.__btmcpTimelineInstalled) return; + root.__btmcpTimelineInstalled = true; + var banned = { authorization: 1, "proxy-authorization": 1, cookie: 1, "set-cookie": 1 }; + + function emit(entry) { + try { + root.postMessage({ source: "btmcp-timeline", entry: entry }, "*"); + } catch (error) { + /* never break the page */ + } + } + + function headerMap(input) { + var out = {}; + if (!input) return out; + function keep(name, value) { + if (!name || banned[String(name).toLowerCase()]) return; + out[String(name)] = typeof value === "string" ? value : String(value); + } + try { + if (typeof input.forEach === "function") { + input.forEach(function (value, name) { + keep(name, value); + }); + return out; + } + } catch (error) { + /* fall through to a plain object */ + } + if (typeof input === "object") { + for (var key in input) { + if (Object.prototype.hasOwnProperty.call(input, key)) keep(key, input[key]); + } + } + return out; + } + + var levels = ["log", "info", "warn", "error", "debug"]; + levels.forEach(function (level) { + if (!root.console || typeof root.console[level] !== "function") return; + var original = root.console[level]; + root.console[level] = function () { + try { + var parts = Array.prototype.map.call(arguments, function (arg) { + if (typeof arg === "string") return arg; + try { + return JSON.stringify(arg); + } catch (error) { + return String(arg); + } + }); + emit({ + kind: "console", + level: level, + message: parts.join(" ").slice(0, 4000), + timestamp: Date.now(), + }); + } catch (error) { + /* never break the page */ + } + return original.apply(root.console, arguments); + }; + }); + + root.addEventListener("error", function (event) { + emit({ + kind: "console", + level: "error", + message: String((event && event.message) || "error").slice(0, 4000), + timestamp: Date.now(), + }); + }); + root.addEventListener("unhandledrejection", function (event) { + emit({ + kind: "console", + level: "error", + message: ("Unhandled promise rejection: " + String(event && event.reason)).slice(0, 4000), + timestamp: Date.now(), + }); + }); + + if (typeof root.fetch === "function") { + var origFetch = root.fetch; + root.fetch = function (input, init) { + var method = "GET"; + var url = ""; + var body = ""; + try { + if (typeof input === "string") url = input; + else if (input && typeof input.url === "string") { + url = input.url; + if (input.method) method = String(input.method); + } + if (init && init.method) method = String(init.method); + if (init && typeof init.body === "string") body = init.body.slice(0, 4000); + } catch (error) { + /* keep the call */ + } + var headers = {}; + try { + headers = headerMap((init && init.headers) || (input && input.headers)); + } catch (error) { + headers = {}; + } + var started = Date.now(); + return origFetch.apply(root, arguments).then( + function (response) { + emit({ + kind: "network", + method: method, + url: url, + status: response && typeof response.status === "number" ? response.status : 0, + timestamp: Date.now(), + startedAt: started, + durationMs: Date.now() - started, + requestHeaders: headers, + requestBody: body, + }); + return response; + }, + function (error) { + emit({ + kind: "network", + method: method, + url: url, + status: 0, + timestamp: Date.now(), + startedAt: started, + durationMs: Date.now() - started, + error: String(error && error.message ? error.message : error), + requestHeaders: headers, + requestBody: body, + }); + throw error; + } + ); + }; + } + + var XHR = root.XMLHttpRequest; + if (typeof XHR === "function" && XHR.prototype) { + var origOpen = XHR.prototype.open; + var origSend = XHR.prototype.send; + var origSet = XHR.prototype.setRequestHeader; + XHR.prototype.open = function (method, url) { + this.__btmcpTimeline = { + method: String(method || "GET"), + url: String(url || ""), + headers: {}, + }; + return origOpen.apply(this, arguments); + }; + XHR.prototype.setRequestHeader = function (name, value) { + try { + if (this.__btmcpTimeline && name && !banned[String(name).toLowerCase()]) { + this.__btmcpTimeline.headers[String(name)] = String(value); + } + } catch (error) { + /* still send the header to the page's request */ + } + return origSet.apply(this, arguments); + }; + XHR.prototype.send = function (body) { + var self = this; + var started = Date.now(); + var meta = this.__btmcpTimeline || { method: "GET", url: "", headers: {} }; + var requestBody = typeof body === "string" ? body.slice(0, 4000) : ""; + this.addEventListener("loadend", function () { + emit({ + kind: "network", + method: meta.method, + url: meta.url, + status: typeof self.status === "number" ? self.status : 0, + timestamp: Date.now(), + startedAt: started, + durationMs: Date.now() - started, + requestHeaders: meta.headers, + requestBody: requestBody, + }); + }); + return origSend.apply(this, arguments); + }; + } + } + + /** + * Runs in the extension's isolated world for one opted-in tab. Forwards + * page events to the worker. Does not read the page's JavaScript state. + */ + function installBridge() { + var root = globalThis; + if (root.__btmcpTimelineBridge) return; + root.__btmcpTimelineBridge = true; + root.addEventListener("message", function (event) { + var data = event && event.data; + if (!data || data.source !== "btmcp-timeline" || !data.entry) return; + var pageOrigin = ""; + try { + pageOrigin = root.location && root.location.origin ? root.location.origin : ""; + } catch (error) { + pageOrigin = ""; + } + if (pageOrigin && event.origin && event.origin !== pageOrigin && event.origin !== "null") return; + var runtime = (root.chrome && root.chrome.runtime) || (root.browser && root.browser.runtime); + if (!runtime || typeof runtime.sendMessage !== "function") return; + try { + runtime.sendMessage({ type: "timeline-capture", entry: data.entry }); + } catch (error) { + /* the worker may be restarting */ + } + }); + } + + /** + * Hooks one opted-in tab. The worker calls this; the worker file itself + * does not name the scripting API. Failures (missing host access, a page + * that cannot be scripted) leave the opt-in in place and capture nothing. + */ + async function inject(chromeApi, tabId) { + if (!chromeApi || !chromeApi.scripting || typeof chromeApi.scripting.executeScript !== "function") { + return false; + } + try { + await chromeApi.scripting.executeScript({ + target: { tabId: tabId }, + world: "ISOLATED", + func: installBridge, + }); + await chromeApi.scripting.executeScript({ + target: { tabId: tabId }, + world: "MAIN", + func: installCapture, + }); + return true; + } catch (error) { + return false; + } + } + + return { + STORAGE_KEY: STORAGE_KEY, + emptyState: emptyState, + normalizeState: normalizeState, + isTracked: isTracked, + targetsFromState: targetsFromState, + stripCredentialHeaders: stripCredentialHeaders, + prepareEvent: prepareEvent, + installCapture: installCapture, + installBridge: installBridge, + inject: inject, + }; +})(); diff --git a/chrome-extension/worker.js b/chrome-extension/worker.js index 854c1aa1..87c98afd 100644 --- a/chrome-extension/worker.js +++ b/chrome-extension/worker.js @@ -6,8 +6,9 @@ * moment via chrome.tabs.get. Tab list, read, background navigate, and soft * input go through BTMCP_TABS. Those paths do not call the debugger API and do * not activate a tab or focus a window. DevTools capture stays in devtools.js. + * The 8-hour log is opt-in and uses page hooks, not the debugger. */ -importScripts("shared.js", "gates.js", "tab-safety.js", "tab-page.js", "tab-actions.js"); +importScripts("shared.js", "gates.js", "tab-safety.js", "tab-page.js", "tab-actions.js", "timeline.js"); BTMCP_SAFETY.install(api); @@ -56,6 +57,110 @@ function send(message) { return sendOn(socket, message); } +var timelineQueue = []; +var timelineInjected = {}; + +function storageSet(area, value) { + return new Promise(function (resolve) { + try { + area.set(value, function () { + resolve(); + }); + } catch (error) { + resolve(); + } + }); +} + +async function readTimelineState() { + var local = await storageGet(api.storage.local, [BTMCP_TIMELINE.STORAGE_KEY]); + return BTMCP_TIMELINE.normalizeState(local[BTMCP_TIMELINE.STORAGE_KEY]); +} + +async function writeTimelineState(state) { + var next = {}; + next[BTMCP_TIMELINE.STORAGE_KEY] = state; + await storageSet(api.storage.local, next); +} + +function flushTimelineQueue(ws) { + var target = ws || socket; + while (timelineQueue.length) { + if (!sendOn(target, { type: "timeline-event", event: timelineQueue[0] })) return; + timelineQueue.shift(); + } +} + +function enqueueTimeline(event) { + timelineQueue.push(event); + if (timelineQueue.length > 200) timelineQueue.shift(); + flushTimelineQueue(socket); +} + +async function injectTimeline(tabId) { + return BTMCP_TIMELINE.inject(api, tabId); +} + +/** + * Tells the connector what the user enabled, and hooks only those tabs. + * The hook is console and fetch/XHR. It does not attach the debugger. + */ +async function syncTimeline(ws) { + var state = await readTimelineState(); + var tabs = []; + try { + tabs = await api.tabs.query({}); + } catch (error) { + tabs = []; + } + var changed = false; + for (var i = 0; i < tabs.length; i++) { + var tab = tabs[i]; + if (!tab || typeof tab.id !== "number" || !state.tabs[String(tab.id)]) continue; + var origin = BTMCP_GATES.originOf(tab.url || "") || ""; + var stored = state.tabs[String(tab.id)]; + var url = tab.url || ""; + var title = tab.title || ""; + if (stored.url !== url || stored.title !== title || stored.origin !== origin) { + stored.url = url; + stored.title = title; + stored.origin = origin; + changed = true; + } + } + if (changed) await writeTimelineState(state); + sendOn(ws || socket, { type: "timeline-targets", targets: BTMCP_TIMELINE.targetsFromState(state) }); + flushTimelineQueue(ws || socket); + for (var j = 0; j < tabs.length; j++) { + var open = tabs[j]; + if (!open || typeof open.id !== "number") continue; + if (!BTMCP_TIMELINE.isTracked(open, state)) continue; + if (open.discarded) continue; + if (timelineInjected[open.id]) continue; + if (await injectTimeline(open.id)) timelineInjected[open.id] = true; + } +} + +async function handleTimelineCapture(entry, tab) { + var state = await readTimelineState(); + if (!BTMCP_TIMELINE.isTracked(tab, state)) return; + var prepared = BTMCP_TIMELINE.prepareEvent(entry, tab); + if (!prepared) return; + enqueueTimeline(prepared); +} + +async function forgetTimelineTab(tabId) { + var state = await readTimelineState(); + if (!state.tabs[String(tabId)]) { + delete timelineInjected[tabId]; + return; + } + delete state.tabs[String(tabId)]; + delete timelineInjected[tabId]; + await writeTimelineState(state); + await syncTimeline(socket); +} + async function reportState() { var state = await readHumanState(); send({ @@ -131,6 +236,7 @@ async function ensureConnected() { excludeOrigins: state.excludeOrigins, }); }); + void syncTimeline(ws); }; ws.onmessage = function (event) { @@ -219,18 +325,39 @@ async function answerProbe(message, reply) { if (api.storage && api.storage.onChanged) { api.storage.onChanged.addListener(function (changes, area) { - var watched = + var capabilityChanged = (area === "session" && (changes[BTMCP_GATES.POPUP_SWITCH_KEY] || changes[BTMCP_GATES.PANEL_SWITCH_KEY])) || (area === "local" && changes[BTMCP_GATES.EXCLUDE_KEY]); - if (!watched) return; - void ensureConnected().then(reportState); + var timelineChanged = area === "local" && changes[BTMCP_TIMELINE.STORAGE_KEY]; + if (!capabilityChanged && !timelineChanged) return; + void ensureConnected().then(function () { + if (capabilityChanged) return reportState(); + }).then(function () { + if (timelineChanged) return syncTimeline(socket); + }); }); } if (api.runtime && api.runtime.onMessage) { - api.runtime.onMessage.addListener(function (message, _sender, sendResponse) { - if (!message || message.type !== "capability-report") return; + api.runtime.onMessage.addListener(function (message, sender, sendResponse) { + if (!message) return; + if (message.type === "timeline-capture") { + if (sender && sender.id && api.runtime.id && sender.id !== api.runtime.id) return; + void handleTimelineCapture(message.entry, sender && sender.tab); + return; + } + if (message.type === "timeline-sync") { + void ensureConnected() + .then(function () { + return syncTimeline(socket); + }) + .then(function () { + sendResponse({ ok: true }); + }); + return true; + } + if (message.type !== "capability-report") return; void ensureConnected().then(reportState).then(function () { sendResponse({ ok: true }); }); @@ -238,11 +365,29 @@ if (api.runtime && api.runtime.onMessage) { }); } +if (api.tabs && api.tabs.onUpdated) { + api.tabs.onUpdated.addListener(function (tabId, info) { + if (!info || info.status !== "complete") return; + delete timelineInjected[tabId]; + void syncTimeline(socket); + }); +} + +if (api.tabs && api.tabs.onRemoved) { + api.tabs.onRemoved.addListener(function (tabId) { + void forgetTimelineTab(tabId); + }); +} + if (api.alarms) { try { api.alarms.create("btmcp-capability", { periodInMinutes: 1 }); api.alarms.onAlarm.addListener(function (alarm) { - if (alarm && alarm.name === "btmcp-capability") void ensureConnected(); + if (alarm && alarm.name === "btmcp-capability") { + void ensureConnected().then(function () { + return syncTimeline(socket); + }); + } }); } catch (error) { /* alarms are a reconnect aid; the gate stays off without them */ From e95b32c01f96a0b0eae3925de10631e5d57e673a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 28 Oct 2026 07:43:53 +0000 Subject: [PATCH 2/3] Accept Windows file modes in the timeline permission check POSIX still expects mode 0600. Windows reports 0666 for a writable file, matching the session-file test. Co-authored-by: werbel.ted --- browser-tools-mcp/test/unit/timeline-store.test.ts | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/browser-tools-mcp/test/unit/timeline-store.test.ts b/browser-tools-mcp/test/unit/timeline-store.test.ts index e045460b..37679b00 100644 --- a/browser-tools-mcp/test/unit/timeline-store.test.ts +++ b/browser-tools-mcp/test/unit/timeline-store.test.ts @@ -247,7 +247,15 @@ describe("TimelineStore", () => { const raw = fs.readFileSync(file, "utf8"); expect(raw).not.toContain(SECRET); expect(raw).toContain("application/json"); - expect(fs.statSync(file).mode & 0o777).toBe(0o600); + // POSIX stores the log as mode 0600. Windows does not keep owner/group/other + // bits: Node reports 0666 for a writable file, and chmod only toggles the + // write bit, which 0600 leaves set. Same rule as the session file. + const mode = fs.statSync(file).mode & 0o777; + if (process.platform === "win32") { + expect(mode & 0o200).toBe(0o200); + } else { + expect(mode).toBe(0o600); + } const restored = new TimelineStore({ dir, now: () => NOW }); expect(restored.query({ chromeTabId: 4 }).network).toHaveLength(1); From a876c962dce4d4b0fc5e96ef102122efc5adf07d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 28 Oct 2026 07:49:09 +0000 Subject: [PATCH 3/3] Retrigger CI after unrelated macOS timeouts The Windows file-mode check passed. Two macOS integration tests hit the 30s timeout; the same jobs passed on the previous commit. Co-authored-by: werbel.ted