browxai 0.7.0

package/dist/util/secrets.js

@@ -0,0 +1,219 @@
+// Per-session sensitive-data masking. Pairs with the URL sanitiser at the
+// same egress boundary — both layers apply.
+//
+// Why it exists: browxai transcripts are shareable (adoption reports, GitHub
+// issue repros, eval datasets). An auth flow whose `fill({value:"hunter2"})`
+// arg, ActionResult, snapshot, console line, or WS frame echoes the real
+// password makes the transcript radioactive. The browser-use precedent:
+// the agent sees `<PASSWORD>`, the runtime substitutes the real value at
+// dispatch — so the password reaches the page, never the agent.
+//
+// Shape: the agent registers a secret with an alias name (`PASSWORD`, `OTP`)
+// and a real value. From then on:
+//   - `fill({value:"<PASSWORD>"})` / `press({key:"<OTP>"})` materialise the
+//     real value AT DISPATCH time (between the registry and Playwright).
+//   - Every egress sink that could carry the real value (network urls + frame
+//     payloads, console text, snapshot trees, find evidence) is scanned for
+//     the real value and rewrites occurrences back to `<PASSWORD>` before
+//     leaving the server.
+//
+// Sanitiser composition: the URL sanitiser is regex-based on URLs;
+// secrets-masking is literal-substring across arbitrary strings. They don't
+// fight — apply secrets-masking AFTER the URL sanitiser at each sink (the
+// URL sanitiser may have already redacted `?token=…`; the literal-value scan
+// still catches a secret that landed in a path / payload / header value).
+import { log } from "./logging.js";
+/**
+ * Per-session secrets registry. Bounded (32 secrets) to keep the per-sink
+ * scan O(secrets × text-len) sane; the realistic upper bound for an auth
+ * flow is small (password, OTP, maybe a couple of token-like values).
+ */
+export class SecretRegistry {
+    cap;
+    byName = new Map();
+    // Cached real-value strings sorted by descending length, so a value that
+    // is a prefix of another doesn't get masked into a partial alias.
+    cachedValuesDesc = null;
+    warnedOnce = false;
+    constructor(cap = 32) {
+        this.cap = cap;
+    }
+    /** Register or replace a secret by name. Names must match `^[A-Z][A-Z0-9_]*$`
+     *  — uppercase identifier, no whitespace, no angle brackets — so the
+     *  `<NAME>` mask is unambiguous. An empty `value` is rejected (would mask
+     *  the empty string everywhere and produce nothing useful). */
+    register(entry) {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(entry.name)) {
+            throw new Error(`register_secret: name "${entry.name}" must match /^[A-Z][A-Z0-9_]*$/ ` +
+                `(uppercase identifier, e.g. PASSWORD / OTP / SESSION_TOKEN) — the ` +
+                `\`<NAME>\` mask format is the stable contract for agents to recognise.`);
+        }
+        if (typeof entry.value !== "string" || entry.value.length === 0) {
+            throw new Error("register_secret: value must be a non-empty string");
+        }
+        if (!this.byName.has(entry.name) && this.byName.size >= this.cap) {
+            throw new Error(`register_secret: capacity ${this.cap} reached — remove an existing ` +
+                `secret (close_session or restart) before registering more`);
+        }
+        this.byName.set(entry.name, { ...entry });
+        this.cachedValuesDesc = null;
+        if (!this.warnedOnce) {
+            // Mirrors the eval / network-body / disableWebSecurity loud-warn posture
+            // (docs/threat-model.md "Loud one-time warnings"). The `secrets`
+            // capability is off by default; once registered, the egress-masking
+            // layer is engaged for the lifetime of the session.
+            log.warn("browxai: secrets capability is ENABLED — a sensitive value was registered. " +
+                "All egress sinks (ActionResult.network, network_read, network_body, " +
+                "ws_read, console_read, snapshot, find) now strip occurrences of the " +
+                "registered value and substitute `<NAME>` aliases. `fill`/`press` " +
+                "materialise `<NAME>` to the real value at dispatch time. The " +
+                "`screenshot` tool is a partial sink — see docs/tool-reference.md.");
+            this.warnedOnce = true;
+        }
+    }
+    /** List registered secret names (NEVER values). Useful for the
+     *  registration tool's confirmation reply + the per-action warning that
+     *  fires when a screenshot's page-text reveals one. */
+    names() {
+        return [...this.byName.keys()];
+    }
+    size() {
+        return this.byName.size;
+    }
+    /** Look up an entry by name. Internal — callers go through `materialize`
+     *  or `applyMask` so the real value never escapes this module by accident. */
+    lookup(name) {
+        return this.byName.get(name);
+    }
+    /**
+     * Dispatch-side: turn `<NAME>` (with optional surrounding whitespace OK,
+     * but the contract is exact `<NAME>`) into the real value, for `fill` /
+     * `press`. Strings that are NOT `<NAME>`-shaped pass through unchanged —
+     * the substitution is conservative on purpose so a plain string containing
+     * angle brackets stays a plain string.
+     *
+     * Returns the materialised string + a flag for the caller to label
+     * the dispatched-action descriptor (so the ActionResult records that a
+     * masked value was sent, not the value itself).
+     *
+     * `pageUrl` is consulted only when an entry has a `scope`; if scope is set
+     * and the current page URL doesn't contain it, the materialisation is
+     * REFUSED (returns ok:false) — substituting a secret on a wrong-origin page
+     * would leak it cross-site.
+     */
+    materialize(value, pageUrl) {
+        const m = /^<([A-Z][A-Z0-9_]*)>$/.exec(value);
+        if (!m)
+            return { ok: true, materialised: false, value };
+        const name = m[1];
+        const entry = this.lookup(name);
+        if (!entry) {
+            return {
+                ok: false,
+                materialised: false,
+                value,
+                error: `value "<${name}>" looks like a secret alias but no secret named ` +
+                    `"${name}" is registered on this session — call register_secret({name,value}) first`,
+            };
+        }
+        if (entry.scope && !pageUrl.toLowerCase().includes(entry.scope.toLowerCase())) {
+            return {
+                ok: false,
+                materialised: false,
+                value,
+                error: `secret "<${name}>" is scoped to "${entry.scope}" but the current ` +
+                    `page URL doesn't contain it — refusing to substitute (would leak ` +
+                    `the value cross-origin). Navigate to the scoped origin first, or ` +
+                    `re-register without a scope.`,
+            };
+        }
+        return { ok: true, materialised: true, value: entry.value, alias: name };
+    }
+    /** Egress-side: scan `text` for any registered real-value and rewrite each
+     *  occurrence to `<NAME>`. No-op when the registry is empty (the common
+     *  case — secrets is opt-in). Pure string replacement; safe to apply
+     *  multiple times (idempotent — `<NAME>` doesn't contain any registered
+     *  value, so won't re-match). Order: longest value first, so a value
+     *  that's a substring of another doesn't leave a partial leak. */
+    applyMaskInText(text) {
+        if (this.byName.size === 0 || !text)
+            return text;
+        let out = text;
+        for (const { name, value } of this.entriesByValueLenDesc()) {
+            if (!value)
+                continue;
+            // String split/join — no regex, so secret values containing regex
+            // metacharacters (e.g. `+`, `(`, `.`) work without escaping.
+            if (out.includes(value)) {
+                out = out.split(value).join(`<${name}>`);
+            }
+        }
+        return out;
+    }
+    /** Convenience: mask the string fields of an object/array recursively.
+     *  Non-string leaves pass through. Bounded depth (8) so a malformed input
+     *  can't blow the stack. Returns a new object — the input is not mutated. */
+    applyMaskDeep(obj, depth = 0) {
+        // Masking only rewrites string leaves, so the result has the same structure
+        // as the input. The recursion runs on `unknown` (every branch narrows with a
+        // real runtime check); the single `as T` is that structure-preserving contract.
+        return this.maskValue(obj, depth);
+    }
+    maskValue(obj, depth) {
+        if (this.byName.size === 0)
+            return obj;
+        if (depth > 8)
+            return obj;
+        if (typeof obj === "string")
+            return this.applyMaskInText(obj);
+        if (Array.isArray(obj))
+            return obj.map((v) => this.maskValue(v, depth + 1));
+        if (obj && typeof obj === "object") {
+            const out = {};
+            for (const [k, v] of Object.entries(obj)) {
+                out[k] = this.maskValue(v, depth + 1);
+            }
+            return out;
+        }
+        return obj;
+    }
+    /** Best-effort detection: does `text` contain any registered real-value?
+     *  Used by the screenshot tool's text-content sweep to decide whether to
+     *  emit the "screenshot may reveal registered secret values" warning. */
+    containsAnySecret(text) {
+        if (this.byName.size === 0 || !text)
+            return { hit: false, names: [] };
+        const names = [];
+        for (const { name, value } of this.entriesByValueLenDesc()) {
+            if (value && text.includes(value))
+                names.push(name);
+        }
+        return { hit: names.length > 0, names };
+    }
+    /** Internal: entries sorted by descending value-length, so longer values
+     *  mask before their shorter prefixes / substrings. Cached until the next
+     *  `register()`. */
+    entriesByValueLenDesc() {
+        if (this.cachedValuesDesc !== null) {
+            // cache invalidation by value-string change — we cache the *sorted name
+            // order* indirectly via re-walking each call when cache is invalidated.
+        }
+        const arr = [...this.byName.values()];
+        arr.sort((a, b) => b.value.length - a.value.length);
+        return arr;
+    }
+}
+/**
+ * Compose with the URL sanitiser: apply secrets-masking AFTER URL sanitisation.
+ * The two layers are independent — the URL sanitiser handles
+ * query/fragment/userinfo/token-paths (regex on URL structure); secrets-
+ * masking handles literal real-value substitution anywhere in the text.
+ *
+ * Helper exists so callers don't have to remember the ordering at every sink.
+ */
+export function composeUrlAndSecretsInText(text, urlSanitiser, registry) {
+    const afterUrl = urlSanitiser(text);
+    if (!registry)
+        return afterUrl;
+    return registry.applyMaskInText(afterUrl);
+}

package/dist/util/tokens.d.ts

@@ -0,0 +1,6 @@
+export declare function estimateTokens(text: string): number;
+/** Truncate `text` (line-wise) so its estimated token count is ≤ `maxTokens`. */
+export declare function truncateToBudget(text: string, maxTokens: number): {
+    text: string;
+    truncated: boolean;
+};

package/dist/util/tokens.js

@@ -0,0 +1,24 @@
+// Cheap token estimation + truncation helpers. ActionResult.snapshotDelta is the
+// elastic part of the structured result — when the budget is tight, we shrink it
+// first before dropping anything else.
+export function estimateTokens(text) {
+    // Order-of-magnitude estimate — 1 token ≈ 4 chars of English / structured text.
+    // We're not pricing API calls; we're sizing payloads. Good enough.
+    return Math.ceil(text.length / 4);
+}
+/** Truncate `text` (line-wise) so its estimated token count is ≤ `maxTokens`. */
+export function truncateToBudget(text, maxTokens) {
+    if (estimateTokens(text) <= maxTokens)
+        return { text, truncated: false };
+    const lines = text.split("\n");
+    // Keep dropping last lines until we fit; add a final "... [N more lines]" marker.
+    let kept = lines.length;
+    while (kept > 1) {
+        const candidate = lines.slice(0, kept).join("\n") + `\n... [+${lines.length - kept} more]`;
+        if (estimateTokens(candidate) <= maxTokens) {
+            return { text: candidate, truncated: true };
+        }
+        kept = Math.max(1, Math.floor(kept * 0.75));
+    }
+    return { text: `... [${lines.length} lines elided]`, truncated: true };
+}

package/dist/util/url-sanitizer.d.ts

@@ -0,0 +1,19 @@
+/** A single path segment → itself, or `:id` when it looks like an identifier
+ *  or an opaque credential/token (numeric, UUID, long hex, or a long
+ *  high-entropy token). Conservative on length so human-readable route words
+ *  ("profile", "avatar", "v2") are preserved. */
+export declare function patterniseSegment(seg: string): string;
+/** Patternise every segment of a pathname. */
+export declare function patternisePath(pathname: string): string;
+/**
+ * Redact a single URL: keep scheme + host + patternised path; drop the query
+ * string, fragment, and any `user:pass@` userinfo. A present-but-stripped
+ * query/fragment is signalled with `?…` / `#…` so the agent still knows it
+ * existed without seeing its contents. Opaque schemes (`blob:`, `data:`)
+ * collapse to just the scheme — their body can itself embed a full URL.
+ * Non-URL input is returned unchanged.
+ */
+export declare function sanitizeUrl(raw: string): string;
+/** Replace every URL substring in arbitrary text with its sanitized form.
+ *  Leaves all non-URL text untouched. */
+export declare function sanitizeUrlsInText(text: string): string;

package/dist/util/url-sanitizer.js

@@ -0,0 +1,70 @@
+// Centralized URL/identity redaction for everything that leaves the server
+// carrying *captured* page traffic — HTTP request lists, WebSocket/SSE frame
+// endpoints, and URL substrings inside console / page-error text.
+//
+// browxai output is meant to be shareable (issue repros, adoption reports)
+// and the server is heading public, so this is a default-on posture, not a
+// per-call opt-in: credential / identity-bearing material (query strings,
+// fragments, userinfo, token-shaped path segments) is stripped at the egress
+// boundary while the analytically useful shape — scheme, host, path pattern —
+// is preserved. One implementation; HTTP / WS / SSE / console all route here.
+/** A single path segment → itself, or `:id` when it looks like an identifier
+ *  or an opaque credential/token (numeric, UUID, long hex, or a long
+ *  high-entropy token). Conservative on length so human-readable route words
+ *  ("profile", "avatar", "v2") are preserved. */
+export function patterniseSegment(seg) {
+    if (!seg)
+        return seg;
+    if (/^\d+$/.test(seg))
+        return ":id";
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(seg))
+        return ":id";
+    if (/^[0-9a-f]{12,}$/i.test(seg))
+        return ":id";
+    // Opaque token / JWT-ish: long, only token-safe chars, and mixes a letter
+    // with a digit (route words like "documentation" never match — no digit).
+    if (seg.length >= 20 &&
+        /^[A-Za-z0-9._~-]+$/.test(seg) &&
+        /[A-Za-z]/.test(seg) &&
+        /\d/.test(seg)) {
+        return ":id";
+    }
+    return seg;
+}
+/** Patternise every segment of a pathname. */
+export function patternisePath(pathname) {
+    return pathname.split("/").map(patterniseSegment).join("/");
+}
+/**
+ * Redact a single URL: keep scheme + host + patternised path; drop the query
+ * string, fragment, and any `user:pass@` userinfo. A present-but-stripped
+ * query/fragment is signalled with `?…` / `#…` so the agent still knows it
+ * existed without seeing its contents. Opaque schemes (`blob:`, `data:`)
+ * collapse to just the scheme — their body can itself embed a full URL.
+ * Non-URL input is returned unchanged.
+ */
+export function sanitizeUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return raw;
+    }
+    if (u.protocol === "blob:" || u.protocol === "data:")
+        return `${u.protocol}…`;
+    const path = patternisePath(u.pathname);
+    const q = u.search ? "?…" : "";
+    const frag = u.hash ? "#…" : "";
+    // u.origin excludes userinfo; for ws/wss/http/https it is `scheme://host`.
+    const base = u.origin && u.origin !== "null" ? u.origin : `${u.protocol}//${u.host}`;
+    return `${base}${path}${q}${frag}`;
+}
+// http(s)/ws(s) URL occurrences inside free text (console messages, page-error
+// strings). Bounded charset stops at the first whitespace / quote / angle.
+const URL_IN_TEXT = /\b(?:https?|wss?):\/\/[^\s"'<>`)\]}]+/gi;
+/** Replace every URL substring in arbitrary text with its sanitized form.
+ *  Leaves all non-URL text untouched. */
+export function sanitizeUrlsInText(text) {
+    return text.replace(URL_IN_TEXT, (m) => sanitizeUrl(m));
+}

package/dist/util/version.d.ts

@@ -0,0 +1,2 @@
+/** The browxai package version (package.json#version) — single source of truth. */
+export declare const PACKAGE_VERSION: string;

package/dist/util/version.js

@@ -0,0 +1,21 @@
+// Host package version — read once, synchronously, from package.json.
+//
+// The MCP handshake, the SDK client identities, and the plugin runtime's
+// host-version advisory all report this value. Deriving it from
+// package.json at module load means the version CANNOT drift from the
+// published one (the old hand-maintained constant shipped a 0.1.0
+// handshake on a 0.7.0 package).
+//
+// `createRequire` keeps the read synchronous and bundler-free. dist/ is
+// built by plain tsc (no bundler — see tsconfig.build.json), so the
+// compiled file lives at `dist/util/version.js` and `../../package.json`
+// resolves to the package root both there and from `src/util/` under tsx.
+// npm always includes package.json in the published tarball.
+import { createRequire } from "node:module";
+const requireFromHere = createRequire(import.meta.url);
+const pkg = requireFromHere("../../package.json");
+if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    throw new Error("browxai: package.json#version missing or empty — corrupt install");
+}
+/** The browxai package version (package.json#version) — single source of truth. */
+export const PACKAGE_VERSION = pkg.version;

package/dist/util/workspace.d.ts

@@ -0,0 +1,7 @@
+export interface Workspace {
+    /** Absolute path to the workspace root. */
+    readonly root: string;
+    /** Subdir helper — `workspace.sub("profile")` → `<root>/profile`, created if missing. */
+    sub(name: string): string;
+}
+export declare function resolveWorkspace(env?: NodeJS.ProcessEnv): Workspace;

package/dist/util/workspace.js

@@ -0,0 +1,22 @@
+// BROWX_WORKSPACE resolution + subpath helpers. The no-trace contract lives
+// or dies here: every write path browxai produces is rooted at this dir,
+// never at cwd. Resolved once at startup.
+import { homedir } from "node:os";
+import { existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+const DEFAULT_WORKSPACE = join(homedir(), ".browxai");
+export function resolveWorkspace(env = process.env) {
+    const raw = env.BROWX_WORKSPACE?.trim();
+    const root = raw ? resolve(raw.replace(/^~(?=$|\/)/, homedir())) : DEFAULT_WORKSPACE;
+    if (!existsSync(root))
+        mkdirSync(root, { recursive: true });
+    return {
+        root,
+        sub(name) {
+            const p = join(root, name);
+            if (!existsSync(p))
+                mkdirSync(p, { recursive: true });
+            return p;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "browxai",
+  "version": "0.7.0",
+  "description": "MCP-native, model-agnostic, agentic-first, multi-engine browser-control server.",
+  "author": "Kalebtec <security@kalebtec.com>",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "browser-automation",
+    "playwright",
+    "cdp",
+    "ai-agent",
+    "agentic",
+    "browser-control"
+  ],
+  "homepage": "https://browxai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kalebteccom/browxai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kalebteccom/browxai/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "bin": {
+    "browxai": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "//sideEffects": "RFC 0004 P2 / D1 (SECURITY-CRITICAL): the tool-metadata bootstrap import populates the derived TOOL_CAPABILITY / DEEP_TOOLS capability+engine gates. It MUST survive bundler tree-shaking — a dropped side-effect import would silently un-gate eval_js / register_secret / network_body. List the entry points that perform the bootstrap side-effect (and the bootstrap module itself) so they are never elided. NOT `false`.",
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/cli.js",
+    "./dist/server.js",
+    "./dist/sdk/index.js",
+    "./dist/tools/tool-metadata.js"
+  ],
+  "files": [
+    "dist",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks || true",
+    "prepublishOnly": "node scripts/audit-package-contents.mjs && pnpm typecheck && pnpm test && pnpm build",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js && pnpm --filter './packages/plugins/*' build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:keystone": "vitest run --config vitest.keystone.config.ts",
+    "bench:network": "tsx scripts/bench-network-envelope.ts",
+    "dev": "tsc -p tsconfig.json --watch",
+    "browxai": "tsx src/cli.ts",
+    "gen:sdk-types": "tsx scripts/gen-sdk-tool-types.ts",
+    "install-browser": "playwright-core install chromium",
+    "docs:dev": "pnpm --filter @browxai/website dev",
+    "docs:build": "pnpm --filter @browxai/website build",
+    "docs:preview": "pnpm --filter @browxai/website preview",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "depcruise": "depcruise --config .dependency-cruiser.cjs src",
+    "jscpd:check": "jscpd --config .jscpd.json",
+    "licenses:check": "license-checker-rseidelsohn --production --onlyAllow 'MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;0BSD;Unlicense;CC0-1.0'",
+    "licenses:notices": "license-checker-rseidelsohn --production --markdown",
+    "audit:prod": "pnpm audit --prod --audit-level=high",
+    "sbom": "cyclonedx-npm --output-format JSON --output-file sbom.cdx.json",
+    "depcheck": "depcheck"
+  },
+  "pnpm": {
+    "overrides": {
+      "hono": ">=4.12.21",
+      "qs": ">=6.15.2"
+    }
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,mjs,cjs}": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "playwright-core": "^1.48.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@cyclonedx/cyclonedx-npm": "^2.0.0",
+    "@eslint/js": "^9.12.0",
+    "@types/node": "^20.14.0",
+    "depcheck": "^1.4.7",
+    "dependency-cruiser": "^17.4.3",
+    "eslint": "^9.12.0",
+    "eslint-plugin-import-x": "^4.3.0",
+    "globals": "^15.11.0",
+    "jscpd": "^5.0.9",
+    "license-checker-rseidelsohn": "^4.4.2",
+    "lint-staged": "^15.2.10",
+    "prettier": "^3.3.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.8.0",
+    "vitest": "^2.0.0"
+  }
+}