@modelprofile.com/browser-runtime 1.0.0

package/ts/mcp.ts

@@ -0,0 +1,230 @@
+import * as plugins from './plugins.js';
+import type { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
+import { BrowserRuntimeError } from './errors.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import type { IBrowserRuntimeMcpOptions } from './interfaces.js';
+import { validateAgentActionResult } from './actions.js';
+import {
+  validateBoundedString,
+  validateInteger,
+} from './utils.js';
+
+const parseBearerToken = (request: Request): string => {
+  const authorization = request.headers.get('authorization');
+  if (!authorization?.startsWith('Bearer ') || authorization.includes(',')) {
+    throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  }
+  return validateBoundedString(
+    authorization.slice('Bearer '.length),
+    'bearer capability',
+    16,
+    512,
+  );
+};
+
+const validateStringList = (value: unknown, name: string): string[] | undefined => {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 64) throw new BrowserRuntimeError('INVALID_INPUT');
+  return value.map((entry) => validateBoundedString(entry, name, 1, 2048));
+};
+
+export const createBrowserRuntimeMcpHttpHandler = (
+  runtime: BrowserRuntime,
+  options: IBrowserRuntimeMcpOptions,
+): plugins.smartmcp.ISmartMcpHttpHandler => {
+  if (!runtime || !options || typeof options.authenticateMcpRequest !== 'function') {
+    throw new BrowserRuntimeError('INVALID_INPUT');
+  }
+  const trustedOrigins = validateStringList(options.trustedOrigins, 'trustedOrigin');
+  const allowedHosts = validateStringList(options.allowedHosts, 'allowedHost');
+  if (options.allowMissingOrigin !== undefined && typeof options.allowMissingOrigin !== 'boolean') {
+    throw new BrowserRuntimeError('INVALID_INPUT');
+  }
+  const maxRequestBytes = options.maxRequestBytes === undefined
+    ? 256 * 1024
+    : validateInteger(options.maxRequestBytes, 'maxRequestBytes', 1024, 1024 * 1024);
+  const maxToolResultBytes = options.maxToolResultBytes === undefined
+    ? 256 * 1024
+    : validateInteger(options.maxToolResultBytes, 'maxToolResultBytes', 1024, 256 * 1024);
+
+  const withLease = async <T>(
+    context: plugins.smartmcp.ISmartMcpToolContext,
+    action: (lease: BrowserRuntimeLease, signal: AbortSignal) => Promise<T>,
+  ): Promise<T> => {
+    const peerId = validateBoundedString(context.authInfo?.clientId, 'peerId', 1, 128);
+    const capabilityToken = parseBearerToken(context.request);
+    const signal = AbortSignal.any([context.extra.signal, context.request.signal]);
+    signal.throwIfAborted();
+    const descriptor = runtime.authorizeCapability(capabilityToken, peerId, 'agent', 'mcp');
+    if (descriptor.capabilityId !== context.authInfo?.token) {
+      throw new BrowserRuntimeError('CAPABILITY_INVALID');
+    }
+    const lease = await runtime.acquireLease({
+      capabilityToken,
+      peerId,
+      expectedRole: 'agent',
+      expectedSource: 'mcp',
+      signal,
+    });
+    try {
+      signal.throwIfAborted();
+      return await action(lease, signal);
+    } finally {
+      await lease.release();
+    }
+  };
+
+  const tabIdSchema = plugins.smartmcp.z.string().min(1).max(128).optional();
+  const timeoutSchema = plugins.smartmcp.z.number().int().min(100).max(120_000).optional();
+  const tools: plugins.smartmcp.ISmartMcpToolDefinition[] = [
+    {
+      name: 'browser_snapshot',
+      description: 'Read bounded accessibility text from a browser tab.',
+      inputSchema: plugins.smartmcp.z.object({
+        tabId: tabIdSchema,
+        maxCharacters: plugins.smartmcp.z.number().int().min(256).max(50_000).optional(),
+      }).strict(),
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      handler: async (args, context) => withLease(context, async (lease, signal) => (
+        validateAgentActionResult(await lease.executeAgentAction({
+          action: 'snapshot',
+          ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
+          ...(typeof args.maxCharacters === 'number'
+            ? { maxCharacters: args.maxCharacters }
+            : {}),
+        }, { signal }))
+      )),
+    },
+    {
+      name: 'browser_navigate',
+      description: 'Navigate a browser tab to an HTTP or HTTPS URL.',
+      inputSchema: plugins.smartmcp.z.object({
+        url: plugins.smartmcp.z.string().min(1).max(8192),
+        tabId: tabIdSchema,
+        timeoutMs: timeoutSchema,
+      }).strict(),
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      handler: async (args, context) => withLease(context, async (lease, signal) => (
+        validateAgentActionResult(await lease.executeAgentAction({
+          action: 'navigate',
+          url: String(args.url),
+          ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
+          ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+        }, { signal }))
+      )),
+    },
+    {
+      name: 'browser_click',
+      description: 'Click an element selected from the observed page.',
+      inputSchema: plugins.smartmcp.z.object({
+        selector: plugins.smartmcp.z.string().min(1).max(4096),
+        tabId: tabIdSchema,
+        timeoutMs: timeoutSchema,
+      }).strict(),
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      handler: async (args, context) => withLease(context, async (lease, signal) => (
+        validateAgentActionResult(await lease.executeAgentAction({
+          action: 'click',
+          selector: String(args.selector),
+          ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
+          ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+        }, { signal }))
+      )),
+    },
+    {
+      name: 'browser_fill',
+      description: 'Fill an element selected from the observed page.',
+      inputSchema: plugins.smartmcp.z.object({
+        selector: plugins.smartmcp.z.string().min(1).max(4096),
+        text: plugins.smartmcp.z.string().max(100_000),
+        tabId: tabIdSchema,
+        timeoutMs: timeoutSchema,
+      }).strict(),
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      handler: async (args, context) => withLease(context, async (lease, signal) => (
+        validateAgentActionResult(await lease.executeAgentAction({
+          action: 'fill',
+          selector: String(args.selector),
+          text: String(args.text),
+          ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
+          ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+        }, { signal }))
+      )),
+    },
+    {
+      name: 'browser_press',
+      description: 'Press a key on an element selected from the observed page.',
+      inputSchema: plugins.smartmcp.z.object({
+        selector: plugins.smartmcp.z.string().min(1).max(4096),
+        key: plugins.smartmcp.z.string().min(1).max(64),
+        tabId: tabIdSchema,
+        timeoutMs: timeoutSchema,
+      }).strict(),
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      handler: async (args, context) => withLease(context, async (lease, signal) => (
+        validateAgentActionResult(await lease.executeAgentAction({
+          action: 'press',
+          selector: String(args.selector),
+          key: String(args.key),
+          ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
+          ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+        }, { signal }))
+      )),
+    },
+    {
+      name: 'browser_screenshot',
+      description: 'Capture a screenshot as bounded artifact metadata.',
+      inputSchema: plugins.smartmcp.z.object({
+        tabId: tabIdSchema,
+        format: plugins.smartmcp.z.enum(['jpeg', 'png']).optional(),
+        quality: plugins.smartmcp.z.number().int().min(0).max(100).optional(),
+      }).strict(),
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      handler: async (args, context) => withLease(context, async (lease, signal) => (
+        validateAgentActionResult(await lease.executeAgentAction({
+          action: 'screenshot',
+          ...(typeof args.tabId === 'string' ? { tabId: args.tabId } : {}),
+          ...(args.format === 'jpeg' || args.format === 'png' ? { format: args.format } : {}),
+          ...(typeof args.quality === 'number' ? { quality: args.quality } : {}),
+        }, { signal }))
+      )),
+    },
+  ];
+
+  return plugins.smartmcp.createSmartMcpHttpHandler({
+    name: '@modelprofile.com/browser-runtime',
+    version: commitinfo.version,
+    ...(trustedOrigins ? { trustedOrigins } : {}),
+    ...(allowedHosts ? { allowedHosts } : {}),
+    ...(options.allowMissingOrigin !== undefined
+      ? { allowMissingOrigin: options.allowMissingOrigin }
+      : {}),
+    maxRequestBytes,
+    maxToolResultBytes,
+    redactError: () => 'Browser tool execution failed.',
+    authorize: async ({ request }) => {
+      let peerId: string;
+      let capabilityToken: string;
+      try {
+        const authentication = await options.authenticateMcpRequest(request);
+        peerId = validateBoundedString(authentication?.peerId, 'peerId', 1, 128);
+        capabilityToken = parseBearerToken(request);
+        const descriptor = runtime.authorizeCapability(
+          capabilityToken,
+          peerId,
+          'agent',
+          'mcp',
+        );
+        return {
+          token: descriptor.capabilityId,
+          clientId: peerId,
+          scopes: ['browser'],
+          expiresAt: descriptor.expiresAt,
+        };
+      } catch {
+        return new Response('Unauthorized', { status: 401 });
+      }
+    },
+    tools,
+  });
+};

package/ts/plugins.ts

@@ -0,0 +1,28 @@
+// node native scope
+import { Buffer } from 'node:buffer';
+import * as crypto from 'node:crypto';
+import * as dns from 'node:dns';
+import * as fs from 'node:fs';
+import * as fsPromises from 'node:fs/promises';
+import * as http from 'node:http';
+import * as net from 'node:net';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as stream from 'node:stream';
+import * as tls from 'node:tls';
+import * as url from 'node:url';
+
+export { Buffer, crypto, dns, fs, fsPromises, http, net, os, path, stream, tls, url };
+
+// foss.global scopes
+import * as flexharness from '@modelprofile.com/flexharness';
+import * as smartagent from '@push.rocks/smartagent';
+import * as smartmcp from '@push.rocks/smartmcp';
+import * as smartpuppeteer from '@push.rocks/smartpuppeteer';
+
+export { flexharness, smartagent, smartmcp, smartpuppeteer };
+
+// third-party scope
+import ipaddr from 'ipaddr.js';
+
+export { ipaddr };

package/ts/utils.ts

@@ -0,0 +1,188 @@
+import * as plugins from './plugins.js';
+import { BrowserRuntimeError } from './errors.js';
+
+export const validateBoundedString = (
+  value: unknown,
+  name: string,
+  minimum: number,
+  maximum: number,
+): string => {
+  if (typeof value !== 'string') {
+    throw new BrowserRuntimeError('INVALID_INPUT', `${name} must be a string`);
+  }
+  const normalized = value.trim();
+  if (normalized.length < minimum || normalized.length > maximum) {
+    throw new BrowserRuntimeError(
+      'INVALID_INPUT',
+      `${name} must contain between ${minimum} and ${maximum} characters`,
+    );
+  }
+  return normalized;
+};
+
+export const validateInteger = (
+  value: unknown,
+  name: string,
+  minimum: number,
+  maximum: number,
+): number => {
+  if (!Number.isInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new BrowserRuntimeError(
+      'INVALID_INPUT',
+      `${name} must be an integer between ${minimum} and ${maximum}`,
+    );
+  }
+  return value as number;
+};
+
+export const validateOptionalInteger = (
+  value: unknown,
+  name: string,
+  minimum: number,
+  maximum: number,
+  defaultValue: number,
+): number => value === undefined
+  ? defaultValue
+  : validateInteger(value, name, minimum, maximum);
+
+export const validateExactKeys = (
+  value: unknown,
+  allowedKeys: readonly string[],
+  name: string,
+): Record<string, unknown> => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new BrowserRuntimeError('INVALID_INPUT', `${name} must be an object`);
+  }
+  const record = value as Record<string, unknown>;
+  const allowed = new Set(allowedKeys);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) {
+      throw new BrowserRuntimeError('INVALID_INPUT', `${name} contains an unsupported field`);
+    }
+  }
+  return record;
+};
+
+export const randomId = (bytes = 24): string => plugins.crypto.randomBytes(bytes).toString('base64url');
+
+export const digestToken = (token: string): plugins.Buffer => plugins.crypto
+  .createHash('sha256')
+  .update(token, 'utf8')
+  .digest();
+
+export const digestsEqual = (left: plugins.Buffer, right: plugins.Buffer): boolean => (
+  left.byteLength === right.byteLength && plugins.crypto.timingSafeEqual(left, right)
+);
+
+export const delay = (milliseconds: number): Promise<void> => new Promise((resolve) => {
+  const timer = setTimeout(resolve, milliseconds);
+  timer.unref();
+});
+
+export const waitBounded = async <T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+): Promise<{ settled: true; value: T } | { settled: false }> => {
+  const timeout = Symbol('timeout');
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<typeof timeout>((resolve) => {
+    timer = setTimeout(() => resolve(timeout), timeoutMs);
+    timer.unref();
+  });
+  try {
+    const result = await Promise.race([promise, timeoutPromise]);
+    return result === timeout
+      ? { settled: false }
+      : { settled: true, value: result as T };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+};
+
+export const truncateString = (value: string, maximum = 2048): string => (
+  value.length <= maximum ? value : value.slice(0, maximum)
+);
+
+export const assertJsonWithoutBytes = (value: unknown, maxBytes = 256 * 1024): void => {
+  const seen = new WeakSet<object>();
+  const visit = (current: unknown, depth: number): void => {
+    if (depth > 24) {
+      throw new BrowserRuntimeError('PROTOCOL_ERROR');
+    }
+    if (
+      current instanceof Uint8Array
+      || current instanceof ArrayBuffer
+      || ArrayBuffer.isView(current)
+    ) {
+      throw new BrowserRuntimeError('PROTOCOL_ERROR');
+    }
+    if (!current || typeof current !== 'object') {
+      if (
+        typeof current === 'bigint'
+        || typeof current === 'function'
+        || typeof current === 'symbol'
+        || typeof current === 'undefined'
+        || (typeof current === 'number' && !Number.isFinite(current))
+      ) {
+        throw new BrowserRuntimeError('PROTOCOL_ERROR');
+      }
+      return;
+    }
+    if (seen.has(current)) {
+      throw new BrowserRuntimeError('PROTOCOL_ERROR');
+    }
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (const entry of current) visit(entry, depth + 1);
+      return;
+    }
+    const prototype = Object.getPrototypeOf(current);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new BrowserRuntimeError('PROTOCOL_ERROR');
+    }
+    for (const entry of Object.values(current as Record<string, unknown>)) {
+      visit(entry, depth + 1);
+    }
+  };
+  visit(value, 0);
+  const serialized = JSON.stringify(value);
+  if (plugins.Buffer.byteLength(serialized, 'utf8') > maxBytes) {
+    throw new BrowserRuntimeError('PROTOCOL_ERROR');
+  }
+};
+
+export class TransitionMutex {
+  private locked = false;
+  private waiters: Array<() => void> = [];
+
+  public tryAcquire(): (() => void) | undefined {
+    if (this.locked) return undefined;
+    this.locked = true;
+    return this.createRelease();
+  }
+
+  public async acquire(): Promise<() => void> {
+    const immediate = this.tryAcquire();
+    if (immediate) return immediate;
+    await new Promise<void>((resolve) => this.waiters.push(resolve));
+    return this.createRelease();
+  }
+
+  public get busy(): boolean {
+    return this.locked;
+  }
+
+  private createRelease(): () => void {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const next = this.waiters.shift();
+      if (next) {
+        next();
+      } else {
+        this.locked = false;
+      }
+    };
+  }
+}