@mario.andreschak/mcp-browser 3.45.0 → 3.45.2

package/dist/runtime.js

@@ -4,6 +4,7 @@ import { lookup } from 'node:dns/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 import { chromium } from 'patchright';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 60_000;
@@ -11,6 +12,7 @@ const DEFAULT_IDLE_MS = 10 * 60_000;
 const DEFAULT_MAX_SESSIONS = 4;
 const DEFAULT_MAX_REDIRECTS = 10;
 const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+export const LEGACY_BROWSER_OWNER_SCOPE = 'legacy:anonymous';
 export function failureCategoryForCode(code) {
     if (code === 'CANCELLED')
         return 'cancelled';
@@ -36,8 +38,12 @@ let trustedContext;
 let trustedContextPromise;
 const launchStates = {};
 let runtimeRoot;
-let lastSessionId;
 const sessions = new Map();
+const reservations = new Map();
+const lastSessionIds = new Map();
+export function effectiveBrowserOwnerScope(ownerScope) {
+    return ownerScope?.trim() || LEGACY_BROWSER_OWNER_SCOPE;
+}
 export function integerEnv(name, fallback, min, max) {
     const raw = Number.parseInt(process.env[name] ?? '', 10);
     return Number.isFinite(raw) ? Math.min(max, Math.max(min, raw)) : fallback;
@@ -81,6 +87,15 @@ function allowServiceWorkers(mode) {
 function allowPrivateHosts() {
     return booleanEnv('FLUJO_BROWSER_ALLOW_PRIVATE_HOSTS') ?? true;
 }
+/**
+ * Browser navigation is deliberately open by default: this is an operator-run
+ * browser, and its primary job is to inspect the operator's local and remote
+ * applications. Deployments that need the former SSRF/origin policy can opt
+ * back into it explicitly.
+ */
+function navigationRestricted() {
+    return enabledEnv('FLUJO_BROWSER_RESTRICT_NAVIGATION');
+}
 function browserWindowVisibility() {
     const configured = process.env.FLUJO_BROWSER_WINDOW_VISIBILITY?.trim().toLowerCase();
     if (configured === 'offscreen' || configured === 'minimized')
@@ -103,10 +118,10 @@ export function defaultViewport() {
 export function timeoutMs(value) {
     if (value === undefined)
         return DEFAULT_TIMEOUT_MS;
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        throw new BrowserMcpError('INVALID_ARGUMENT', 'timeoutMs must be a finite number.');
-    }
-    return Math.min(MAX_TIMEOUT_MS, Math.max(1_000, Math.trunc(value)));
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(MAX_TIMEOUT_MS, Math.max(1_000, Math.trunc(parsed)));
 }
 function allowedOrigins() {
     const origins = new Set();
@@ -165,20 +180,54 @@ async function resolveHostAddresses(hostname) {
     dnsCache.set(hostname, { expiresAt: now + DNS_CACHE_TTL_MS, addresses });
     return addresses;
 }
+async function normalizeNavigationTarget(input) {
+    const raw = input.trim();
+    if (!raw)
+        throw new BrowserMcpError('INVALID_ARGUMENT', 'Provide a URL or local file path to navigate to.');
+    const windowsPath = /^[A-Za-z]:[\\/]/.test(raw);
+    const explicitPath = windowsPath || path.isAbsolute(raw) || raw.startsWith('./') || raw.startsWith('../');
+    if (explicitPath)
+        return pathToFileURL(path.resolve(raw));
+    try {
+        await fs.access(path.resolve(raw));
+        return pathToFileURL(path.resolve(raw));
+    }
+    catch {
+        // It is a URL or hostname, not an existing local path.
+    }
+    // A hostname followed by a numeric port (localhost:4200, app.test:3000)
+    // is not a URL scheme. Treat only :// or a non-numeric scheme payload as an
+    // explicit protocol.
+    if (!/^[A-Za-z][A-Za-z\d+.-]*:(?:\/\/|[^\d])/.test(raw)) {
+        const local = /^(?:localhost|127(?:\.\d{1,3}){3}|10(?:\.\d{1,3}){3}|192\.168(?:\.\d{1,3}){2}|172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}|\[?::1\]?|[^/\s]+\.local)(?::\d+)?(?:\/|$)/i.test(raw)
+            || /^[^/\s]+:\d+(?:\/|$)/.test(raw);
+        return new URL(`${local ? 'http' : 'https'}://${raw}`);
+    }
+    try {
+        return new URL(raw);
+    }
+    catch {
+        throw new BrowserMcpError('INVALID_ARGUMENT', `Could not understand the browser target ${JSON.stringify(raw)}.`);
+    }
+}
 export async function assertNavigationAllowed(input) {
     let url;
     try {
-        url = new URL(input);
+        url = await normalizeNavigationTarget(input);
     }
-    catch {
-        throw new BrowserMcpError('NAVIGATION_BLOCKED', 'The URL is malformed.');
+    catch (error) {
+        if (error instanceof BrowserMcpError)
+            throw error;
+        throw new BrowserMcpError('INVALID_ARGUMENT', `Could not understand the browser target ${JSON.stringify(input)}.`);
     }
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-        throw new BrowserMcpError('NAVIGATION_BLOCKED', 'Only HTTP and HTTPS URLs are allowed.');
+    if (!['http:', 'https:', 'file:'].includes(url.protocol) && !(url.protocol === 'about:' && url.href === 'about:blank')) {
+        throw new BrowserMcpError('INVALID_ARGUMENT', `The browser cannot navigate to ${url.protocol} targets. Use HTTP(S), a local file path, file://, or about:blank.`);
     }
     if (url.username || url.password) {
-        throw new BrowserMcpError('NAVIGATION_BLOCKED', 'URLs containing credentials are not allowed.');
+        throw new BrowserMcpError('INVALID_ARGUMENT', 'Remove embedded credentials from the URL and authenticate in the page instead.');
     }
+    if (!navigationRestricted() || url.protocol === 'file:' || url.protocol === 'about:')
+        return url;
     const configuredOrigins = allowedOrigins();
     if (configuredOrigins.size > 0 && !configuredOrigins.has(url.origin)) {
         throw new BrowserMcpError('NAVIGATION_BLOCKED', 'The URL origin is not allowed by browser policy.');
@@ -207,13 +256,6 @@ async function ensureRuntimeRoot() {
         runtimeRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'flujo-browser-'));
     return runtimeRoot;
 }
-function screenshotRoot() {
-    const configured = process.env.FLUJO_BROWSER_SCREENSHOT_DIR?.trim();
-    if (configured)
-        return path.resolve(configured);
-    const dataRoot = process.env.FLUJO_DATA_DIR?.trim() || process.cwd();
-    return path.resolve(dataRoot, 'screenshots', 'browser');
-}
 /** Persistence root for `browser_record_*` artifacts (WebM/WAV/muxed output). */
 export function recordingRoot() {
     const configured = process.env.FLUJO_BROWSER_RECORD_DIR?.trim();
@@ -229,16 +271,6 @@ export async function ensureScratchDir(prefix) {
     await fs.mkdir(dir, { recursive: true });
     return dir;
 }
-/** Persist the latest screenshot and return the absolute host path reported to MCP clients. */
-export async function writeScreenshotArtifact(sessionId, fullPage, png) {
-    if (!SESSION_ID_PATTERN.test(sessionId)) {
-        throw new BrowserMcpError('INVALID_ARGUMENT', 'A valid sessionId is required for screenshot storage.');
-    }
-    const filePath = path.join(screenshotRoot(), sessionId, fullPage ? 'full-page.png' : 'viewport.png');
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, png);
-    return path.resolve(filePath);
-}
 /**
  * Chromium flags that make embedded media behave the way a user expects.
  *
@@ -395,11 +427,13 @@ export async function acquireBrowser() {
                     sandboxBrowser = undefined;
                 delete launchStates.sandbox;
                 for (const [id, session] of sessions) {
-                    if (session.mode === 'sandbox')
+                    if (session.mode === 'sandbox') {
                         sessions.delete(id);
+                        if (lastSessionIds.get(effectiveBrowserOwnerScope(session.ownerScope)) === id) {
+                            lastSessionIds.delete(effectiveBrowserOwnerScope(session.ownerScope));
+                        }
+                    }
                 }
-                if (lastSessionId && !sessions.has(lastSessionId))
-                    lastSessionId = undefined;
             });
             return launched;
         }
@@ -456,11 +490,13 @@ async function acquireTrustedContext() {
                     trustedContext = undefined;
                 delete launchStates.trusted;
                 for (const [id, session] of sessions) {
-                    if (session.mode === 'trusted')
+                    if (session.mode === 'trusted') {
                         sessions.delete(id);
+                        if (lastSessionIds.get(effectiveBrowserOwnerScope(session.ownerScope)) === id) {
+                            lastSessionIds.delete(effectiveBrowserOwnerScope(session.ownerScope));
+                        }
+                    }
                 }
-                if (lastSessionId && !sessions.has(lastSessionId))
-                    lastSessionId = undefined;
             });
             return context;
         }
@@ -483,40 +519,99 @@ function validateSessionId(value) {
     }
     return value;
 }
+function sessionIdleMs() {
+    return integerEnv('FLUJO_BROWSER_IDLE_TIMEOUT_MS', DEFAULT_IDLE_MS, 10_000, 24 * 60 * 60_000);
+}
+function sessionOwner(session) {
+    return effectiveBrowserOwnerScope(session.ownerScope);
+}
 function touchSession(session) {
-    session.touchedAt = Date.now();
-    lastSessionId = session.id;
+    const now = Date.now();
+    session.touchedAt = now;
+    session.expiresAt = now + sessionIdleMs();
+    lastSessionIds.set(sessionOwner(session), session.id);
     return session;
 }
-function lastLiveSession(mode) {
-    const remembered = lastSessionId ? sessions.get(lastSessionId) : undefined;
-    if (remembered && !remembered.page.isClosed() && (!mode || remembered.mode === mode))
+function removeSessionEntry(session) {
+    if (sessions.get(session.id) !== session)
+        return;
+    session.lifecycleState = 'closing';
+    sessions.delete(session.id);
+    const ownerScope = sessionOwner(session);
+    if (lastSessionIds.get(ownerScope) === session.id)
+        lastSessionIds.delete(ownerScope);
+}
+async function shutdownSession(session) {
+    if (session.mode === 'trusted')
+        await session.page.close().catch(() => undefined);
+    else
+        await session.context.close().catch(() => undefined);
+}
+function purgeUnavailableSessions() {
+    const now = Date.now();
+    for (const session of sessions.values()) {
+        if (session.page.isClosed() || (session.expiresAt ?? (session.touchedAt + sessionIdleMs())) <= now) {
+            removeSessionEntry(session);
+            if (session.onExpire)
+                session.onExpire();
+            else
+                void shutdownSession(session);
+        }
+    }
+    for (const [id, reservation] of reservations) {
+        if (reservation.expiresAt <= now)
+            reservations.delete(id);
+    }
+}
+function lastLiveSession(ownerScope, mode) {
+    purgeUnavailableSessions();
+    const rememberedId = lastSessionIds.get(ownerScope);
+    const remembered = rememberedId ? sessions.get(rememberedId) : undefined;
+    if (remembered && sessionOwner(remembered) === ownerScope && (!mode || remembered.mode === mode))
         return remembered;
     let latest;
     for (const session of sessions.values()) {
-        if (session.page.isClosed()) {
-            sessions.delete(session.id);
-            continue;
-        }
-        if ((!mode || session.mode === mode) && (!latest || session.touchedAt >= latest.touchedAt))
+        if (sessionOwner(session) === ownerScope && (!mode || session.mode === mode) && (!latest || session.touchedAt >= latest.touchedAt)) {
             latest = session;
+        }
     }
-    lastSessionId = latest?.id;
+    if (latest)
+        lastSessionIds.set(ownerScope, latest.id);
+    else
+        lastSessionIds.delete(ownerScope);
     return latest;
 }
-async function closeSessionInternal(id) {
+export function reserveSession(id, ownerScopeInput, purpose = 'interactive') {
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput);
+    purgeUnavailableSessions();
+    const occupied = sessions.get(id);
+    if (occupied) {
+        if (sessionOwner(occupied) !== ownerScope)
+            throw new BrowserMcpError('NOT_FOUND', 'The browser session does not exist or has expired.');
+        throw new BrowserMcpError('INVALID_ARGUMENT', 'The browser session is already active.');
+    }
+    if (reservations.has(id))
+        throw new BrowserMcpError('SESSION_LIMIT', 'The browser session is already being opened.');
+    const maxSessions = integerEnv('FLUJO_BROWSER_MAX_SESSIONS', DEFAULT_MAX_SESSIONS, 1, 32);
+    if (sessions.size + reservations.size >= maxSessions) {
+        throw new BrowserMcpError('SESSION_LIMIT', `The browser session limit (${maxSessions}) has been reached.`);
+    }
+    const now = Date.now();
+    reservations.set(id, { id, ownerScope, purpose, createdAt: now, expiresAt: now + sessionIdleMs() });
+}
+export function releaseSessionReservation(id, ownerScopeInput) {
+    const reservation = reservations.get(id);
+    if (reservation && reservation.ownerScope === effectiveBrowserOwnerScope(ownerScopeInput))
+        reservations.delete(id);
+}
+async function closeSessionInternal(id, ownerScopeInput) {
     const session = sessions.get(id);
     if (!session)
         return false;
-    sessions.delete(id);
-    if (lastSessionId === id)
-        lastSessionId = undefined;
-    if (session.mode === 'trusted') {
-        await session.page.close().catch(() => undefined);
-    }
-    else {
-        await session.context.close().catch(() => undefined);
-    }
+    if (ownerScopeInput !== undefined && sessionOwner(session) !== effectiveBrowserOwnerScope(ownerScopeInput))
+        return false;
+    removeSessionEntry(session);
+    await shutdownSession(session);
     return true;
 }
 function policyDisplayUrl(rawUrl) {
@@ -543,6 +638,8 @@ function sessionForPage(page) {
 }
 /** Enforce the same SSRF/navigation policy on sessions, recordings, and capture contexts. */
 export async function installRequestPolicy(context) {
+    if (!navigationRestricted())
+        return;
     await context.route('**/*', async (route) => {
         const request = route.request();
         let session;
@@ -592,23 +689,20 @@ function reusableTrustedPage(context) {
     const used = new Set([...sessions.values()].map((session) => session.page));
     return context.pages().find((page) => !used.has(page) && !page.isClosed() && page.url() === 'about:blank');
 }
-export async function openSession(requestedId, signal) {
+export async function openSession(requestedId, signal, ownerScopeInput) {
     if (signal.aborted)
         throw new BrowserMcpError('CANCELLED', 'The browser request was cancelled.');
     const mode = browserMode();
-    if (requestedId === undefined || requestedId === '') {
-        const latest = lastLiveSession(mode);
-        if (latest)
-            return touchSession(latest);
-    }
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput);
     const id = validateSessionId(requestedId);
+    purgeUnavailableSessions();
     const existing = sessions.get(id);
-    if (existing)
+    if (existing) {
+        if (sessionOwner(existing) !== ownerScope)
+            throw new BrowserMcpError('NOT_FOUND', 'The browser session does not exist or has expired.');
         return touchSession(existing);
-    const maxSessions = integerEnv('FLUJO_BROWSER_MAX_SESSIONS', DEFAULT_MAX_SESSIONS, 1, 32);
-    if (sessions.size >= maxSessions) {
-        throw new BrowserMcpError('SESSION_LIMIT', `The browser session limit (${maxSessions}) has been reached.`);
     }
+    reserveSession(id, ownerScope, 'interactive');
     let context;
     let page;
     let closeCreatedPromise;
@@ -646,12 +740,20 @@ export async function openSession(requestedId, signal) {
             page = await context.newPage();
             await installRequestPolicy(context);
         }
+        const now = Date.now();
         const session = {
             id,
             mode,
+            ownerScope,
+            purpose: 'interactive',
+            lifecycleState: 'active',
+            viewportPolicy: 'resizable',
+            createdAt: now,
+            expiresAt: now + sessionIdleMs(),
+            gatewayToken: randomUUID(),
             context,
             page,
-            touchedAt: Date.now(),
+            touchedAt: now,
             documentRequests: 0,
             navigationBlocked: false,
             blockedRequestCount: 0,
@@ -660,11 +762,8 @@ export async function openSession(requestedId, signal) {
             throw new BrowserMcpError('CANCELLED', 'The browser request was cancelled.');
         }
         session.page.on('download', (download) => void download.cancel().catch(() => undefined));
-        session.page.on('close', () => {
-            sessions.delete(id);
-            if (lastSessionId === id)
-                lastSessionId = undefined;
-        });
+        session.page.on('close', () => removeSessionEntry(session));
+        reservations.delete(id);
         sessions.set(id, session);
         return touchSession(session);
     }
@@ -676,11 +775,29 @@ export async function openSession(requestedId, signal) {
         throw error;
     }
     finally {
+        releaseSessionReservation(id, ownerScope);
         signal.removeEventListener('abort', onAbort);
     }
 }
-/** Register a session created outside `openSession()` (used by the recording module, which owns its own context lifecycle). */
-export function registerSession(session) {
+/** Register a session created outside `openSession()` after reserving capacity synchronously. */
+export function registerSession(session, ownerScopeInput) {
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput ?? session.ownerScope);
+    const reservation = reservations.get(session.id);
+    if (!reservation)
+        reserveSession(session.id, ownerScope, session.purpose ?? 'interactive');
+    else if (reservation.ownerScope !== ownerScope) {
+        throw new BrowserMcpError('NOT_FOUND', 'The browser session reservation belongs to another owner.');
+    }
+    const now = Date.now();
+    session.ownerScope = ownerScope;
+    session.purpose ??= 'interactive';
+    session.lifecycleState = 'active';
+    session.viewportPolicy ??= 'resizable';
+    session.createdAt ??= now;
+    session.expiresAt = now + sessionIdleMs();
+    session.gatewayToken ??= randomUUID();
+    reservations.delete(session.id);
+    session.page.on('close', () => removeSessionEntry(session));
     sessions.set(session.id, session);
     return touchSession(session);
 }
@@ -718,9 +835,11 @@ export async function createCaptureContext(signal, viewport) {
         throw error;
     }
 }
-export function getSession(value) {
+export function getSession(value, ownerScopeInput) {
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput);
+    purgeUnavailableSessions();
     if (value === undefined || value === '') {
-        const latest = lastLiveSession();
+        const latest = lastLiveSession(ownerScope);
         if (!latest)
             throw new BrowserMcpError('NOT_FOUND', 'No active browser session exists.');
         return touchSession(latest);
@@ -729,23 +848,82 @@ export function getSession(value) {
         throw new BrowserMcpError('INVALID_ARGUMENT', 'A valid sessionId is required.');
     }
     const session = sessions.get(value);
-    if (!session || session.page.isClosed()) {
-        sessions.delete(value);
+    if (!session || sessionOwner(session) !== ownerScope) {
+        throw new BrowserMcpError('NOT_FOUND', 'The browser session does not exist or has expired.');
+    }
+    return touchSession(session);
+}
+export function getSessionForGateway(value, gatewayToken) {
+    purgeUnavailableSessions();
+    if (typeof value !== 'string' || !SESSION_ID_PATTERN.test(value) || typeof gatewayToken !== 'string') {
+        throw new BrowserMcpError('NOT_FOUND', 'The browser session does not exist or has expired.');
+    }
+    const session = sessions.get(value);
+    if (!session?.gatewayToken || session.gatewayToken !== gatewayToken) {
         throw new BrowserMcpError('NOT_FOUND', 'The browser session does not exist or has expired.');
     }
     return touchSession(session);
 }
-export async function closeSession(value) {
+export async function closeSession(value, ownerScopeInput) {
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput);
     if (value === undefined || value === '') {
-        const latest = lastLiveSession();
+        const latest = lastLiveSession(ownerScope);
         if (!latest)
             return false;
-        return closeSessionInternal(latest.id);
+        return closeSessionInternal(latest.id, ownerScope);
     }
     if (typeof value !== 'string' || !SESSION_ID_PATTERN.test(value)) {
         throw new BrowserMcpError('INVALID_ARGUMENT', 'A valid sessionId is required.');
     }
-    return closeSessionInternal(value);
+    return closeSessionInternal(value, ownerScope);
+}
+export function listSessions(ownerScopeInput) {
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput);
+    purgeUnavailableSessions();
+    const now = Date.now();
+    const owned = [...sessions.values()].filter((session) => sessionOwner(session) === ownerScope);
+    const reserved = [...reservations.values()].filter((entry) => entry.ownerScope === ownerScope);
+    const maxSessions = integerEnv('FLUJO_BROWSER_MAX_SESSIONS', DEFAULT_MAX_SESSIONS, 1, 32);
+    return {
+        success: true,
+        sessions: [
+            ...owned.map((session) => ({
+                sessionId: session.id,
+                purpose: session.purpose ?? 'interactive',
+                mode: session.mode,
+                state: session.lifecycleState ?? 'active',
+                viewportPolicy: session.viewportPolicy ?? 'resizable',
+                ageMs: now - (session.createdAt ?? session.touchedAt),
+                idleMs: now - session.touchedAt,
+                expiresAt: session.expiresAt ?? (session.touchedAt + sessionIdleMs()),
+            })),
+            ...reserved.map((entry) => ({
+                sessionId: entry.id,
+                purpose: entry.purpose,
+                state: 'reserved',
+                ageMs: now - entry.createdAt,
+                idleMs: 0,
+                expiresAt: entry.expiresAt,
+            })),
+        ],
+        capacity: {
+            used: sessions.size + reservations.size,
+            owned: owned.length + reserved.length,
+            limit: maxSessions,
+        },
+    };
+}
+export async function releaseOwnerScope(ownerScopeInput) {
+    const ownerScope = effectiveBrowserOwnerScope(ownerScopeInput);
+    const owned = [...sessions.values()].filter((session) => sessionOwner(session) === ownerScope);
+    for (const session of owned)
+        removeSessionEntry(session);
+    for (const [id, reservation] of reservations) {
+        if (reservation.ownerScope === ownerScope)
+            reservations.delete(id);
+    }
+    await Promise.all(owned.map((session) => shutdownSession(session)));
+    return { success: true, ownerScope, closed: owned.length };
 }
 export async function runCancellable(session, signal, operation) {
     if (signal.aborted) {
@@ -897,7 +1075,8 @@ export async function shutdownBrowserRuntime() {
     const activeTrusted = trustedContext;
     sandboxBrowser = undefined;
     trustedContext = undefined;
-    lastSessionId = undefined;
+    reservations.clear();
+    lastSessionIds.clear();
     delete launchStates.sandbox;
     delete launchStates.trusted;
     await activeTrusted?.close().catch(() => undefined);
@@ -909,12 +1088,7 @@ export async function shutdownBrowserRuntime() {
     }
 }
 const idleTimer = setInterval(() => {
-    const idleMs = integerEnv('FLUJO_BROWSER_IDLE_TIMEOUT_MS', DEFAULT_IDLE_MS, 10_000, 24 * 60 * 60_000);
-    const cutoff = Date.now() - idleMs;
-    for (const session of sessions.values()) {
-        if (session.touchedAt < cutoff)
-            void closeSessionInternal(session.id);
-    }
+    purgeUnavailableSessions();
 }, 30_000);
 idleTimer.unref();
 //# sourceMappingURL=runtime.js.map