@browserstack/mcp-server 2.1.0 → 2.2.0-beta.1

package/dist/tools/ask-browserstack/types.js

@@ -11,14 +11,4 @@
 // describe text in register.ts, and the two a11y handoffs in tool-handoff.ts — which stop
 // pointing here precisely because the call would now be rejected.
 export const PRODUCTS = ["tm", "tra"];
-export const ASK_STATUSES = [
-    "ok",
-    "blocked",
-    "error",
-    "rate_limited",
-    // Deferred only: the run reached an ask and is PARKED, not finished. Distinct from
-    // `blocked` (a human said no) and from `error` (nothing is waiting) — this one is the
-    // only status a caller is invited to come back from, and the only one carrying a
-    // `run_id`.
-    "needs_approval",
-];
+export const ASK_STATUSES = ["ok", "blocked", "error", "rate_limited"];

package/dist/tools/automate-utils/fetch-screenshots.js

@@ -2,7 +2,6 @@ import { assertOkResponse, maybeCompressBase64 } from "../../lib/utils.js";
 import { SessionType } from "../../lib/constants.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { apiClient } from "../../lib/apiClient.js";
-import globalConfig from "../../config.js";
 async function extractScreenshotUrls(sessionId, sessionType, config) {
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
@@ -37,24 +36,23 @@ async function extractScreenshotUrls(sessionId, sessionType, config) {
     }
     return urls;
 }
-async function fetchAndCompress(url) {
-    const response = await apiClient.get({ url, responseType: "arraybuffer" });
-    // Axios returns response.data as a Buffer for binary data
-    const base64 = Buffer.from(response.data).toString("base64");
-    return { url, base64: await maybeCompressBase64(base64) };
-}
 //Converts screenshot URLs to base64 encoded images
 async function convertUrlsToBase64(urls) {
-    // Hosted pods are memory-constrained: process one image at a time. Local runs
-    // keep the concurrent path.
-    if (globalConfig.REMOTE_MCP) {
-        const screenshots = [];
-        for (const url of urls) {
-            screenshots.push(await fetchAndCompress(url));
-        }
-        return screenshots;
-    }
-    return Promise.all(urls.map(fetchAndCompress));
+    const screenshots = await Promise.all(urls.map(async (url) => {
+        const response = await apiClient.get({
+            url,
+            responseType: "arraybuffer",
+        });
+        // Axios returns response.data as a Buffer for binary data
+        const base64 = Buffer.from(response.data).toString("base64");
+        // Compress the base64 image if needed
+        const compressedBase64 = await maybeCompressBase64(base64);
+        return {
+            url,
+            base64: compressedBase64,
+        };
+    }));
+    return screenshots;
 }
 //Fetches and converts screenshot URLs to base64 encoded images
 export async function fetchAutomationScreenshots(sessionId, sessionType = SessionType.Automate, config) {

package/dist/tools/capability-registry/bind.js

@@ -230,6 +230,15 @@ function coerceType(value, param, label = param.name) {
         if (expected === "integer" && !Number.isInteger(parsed)) {
             throw new InvocationError(`'${label}' must be a whole number, not ${JSON.stringify(raw)}`);
         }
+        // Past 2^53 `Number` rounds: TRA's 17-digit unique-error cluster ids came back as a
+        // neighbouring id, so the call silently targeted the wrong cluster. Keep the caller's
+        // exact digits instead — path and query serialise a string identically, and a JSON body
+        // carrying a digit string still binds to a Long on the server.
+        if (expected === "integer" &&
+            !Number.isSafeInteger(parsed) &&
+            /^-?\d+$/.test(raw)) {
+            return raw;
+        }
         return parsed;
     }
     if (expected === "boolean") {
@@ -280,6 +289,12 @@ function place(root, pointer, value) {
     }
     cursor[segments[segments.length - 1]] = value;
 }
+const MAP_KEY = /^[A-Za-z0-9][\w.-]*$/;
+function keyedParam(group, params) {
+    if (group !== "body")
+        return undefined;
+    return params.find((param) => /^\{\w+\}$/.test(param.name));
+}
 const GROUPS = [
     { group: "path_params", declared: "path_params" },
     { group: "query", declared: "query" },
@@ -298,9 +313,10 @@ export function bind(capability, args) {
         }
         const params = capability[declared] || [];
         const byName = new Map(params.map((param) => [param.name, param]));
+        const keyed = keyedParam(group, params);
         // Unknown arguments are an error rather than being dropped: silently ignoring a
         // misspelled filter would return a larger result set that looks like a correct answer.
-        const unknown = Object.keys(supplied).filter((name) => !byName.has(name));
+        const unknown = Object.keys(supplied).filter((name) => !byName.has(name) && !keyed);
         if (unknown.length > 0) {
             // A CALLER WHO SENT THE WRAPPER WE BUILD DESERVES TO BE TOLD SO.
             //
@@ -331,7 +347,10 @@ export function bind(capability, args) {
                     : ""));
         }
         for (const [name, raw] of Object.entries(supplied)) {
-            const param = byName.get(name);
+            const param = byName.get(name) ?? keyed;
+            if (param === keyed && !MAP_KEY.test(name)) {
+                throw new InvocationError(`'${name}' is not a usable ${keyed.name} key: use the id exactly as a read returned it`);
+            }
             const value = coerce(raw, param);
             if (group === "path_params") {
                 // Encode with nothing exempt: a `/` inside a path value would otherwise rewrite the
@@ -339,7 +358,10 @@ export function bind(capability, args) {
                 path = path.replaceAll(`{${name}}`, encodeURIComponent(pathSegment(value, name)));
             }
             else if (group === "body") {
-                place(body, param.json_path || `/${name}`, value);
+                const pointer = param.json_path || `/${param.name}`;
+                place(body, param === keyed && !byName.has(name)
+                    ? pointer.replace(keyed.name, name)
+                    : pointer, value);
             }
             else {
                 query[name] = value;
@@ -354,9 +376,14 @@ export function bind(capability, args) {
         if (group === "query")
             continue;
         const supplied = args[group] || {};
-        for (const param of capability[declared] ||
-            []) {
-            if (param.required && !(param.name in supplied))
+        const params = capability[declared] || [];
+        const keyed = keyedParam(group, params);
+        const declaredNames = new Set(params.map((param) => param.name));
+        for (const param of params) {
+            const present = param.name in supplied ||
+                (param === keyed &&
+                    Object.keys(supplied).some((name) => !declaredNames.has(name)));
+            if (param.required && !present)
                 missing.push(param.name);
         }
     }
@@ -367,5 +394,14 @@ export function bind(capability, args) {
     if (leftover) {
         throw new InvocationError(`path placeholder(s) not supplied: ${leftover.join(", ")}`);
     }
-    return { path, query, body: Object.keys(body).length > 0 ? body : undefined };
+    // An explicitly supplied empty body is still a body. Dropping it sent no request body at
+    // all, and a route with a required @RequestBody (TRA close_build, whose guidance says to
+    // send `{}`) answered 400 "Invalid request payload". GET/HEAD never carry one.
+    const sentEmptyBody = args.body !== undefined &&
+        !["GET", "HEAD"].includes(capability.method.toUpperCase());
+    return {
+        path,
+        query,
+        body: Object.keys(body).length > 0 || sentEmptyBody ? body : undefined,
+    };
 }

package/dist/tools/capability-registry/discovery.js

@@ -79,7 +79,9 @@ export async function discoverBaseUrl(product, source, credentials, transport) {
             `set probe_path in its index`);
     }
     // The same scheme the invocation will use, so a host that answers here answers there.
-    const headers = authHeaders(credentials, source.auth);
+    // Minted ONCE for the whole probe, not per candidate: the token is the caller's identity
+    // and does not vary by which region answers.
+    const headers = await authHeaders(credentials, source.auth, product);
     const failures = [];
     for (const candidate of candidates) {
         const response = await transport("GET", `${candidate}${path}`, headers, {});

package/dist/tools/capability-registry/egress.d.ts

@@ -16,11 +16,10 @@
  * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
  * credentials are wrong.
  */
+import { TokenTransport } from "../../lib/central-oauth.js";
 import { AuthScheme } from "./types.js";
-export interface Credentials {
-    username: string;
-    accessKey: string;
-}
+export type { Credentials } from "../../lib/central-oauth.js";
+import type { Credentials } from "../../lib/central-oauth.js";
 export interface HttpResponse {
     status: number;
     body: unknown;
@@ -39,6 +38,14 @@ export declare const DEFAULT_AUTH: AuthScheme;
  * the common case, not a hypothetical.
  */
 export declare function renderTemplate(template: string, credentials: Credentials): string;
-export declare function authHeaders(credentials: Credentials, auth?: AuthScheme): Record<string, string>;
+/**
+ * The headers for one outbound call.
+ *
+ * ASYNC BECAUSE ONE SCHEME NEEDS A ROUND TRIP. `apiKey` and `http` are pure string work, but
+ * `oauth2` exchanges the caller's credentials for a JWT before anything can be sent, and
+ * there was nowhere to put that while this was synchronous. Both call sites were already
+ * inside async functions, so the cost is two `await`s.
+ */
+export declare function authHeaders(credentials: Credentials, auth?: AuthScheme, product?: string, tokenTransport?: TokenTransport): Promise<Record<string, string>>;
 /** A fetch-based transport. Redirects are NOT followed. */
 export declare function fetchTransport(timeoutMs?: number): Transport;

package/dist/tools/capability-registry/egress.js

@@ -16,7 +16,9 @@
  * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
  * credentials are wrong.
  */
+import { fetchTokenTransport, } from "../../lib/central-oauth.js";
 import { InvocationError } from "./index-loader.js";
+import { bearerToken } from "./oauth.js";
 /** What this server can put into a credential template. Nothing else is fillable. */
 const PLACEHOLDERS = ["username", "access_key"];
 /** The historical default, and what an index without an `auth` block still gets. */
@@ -48,7 +50,15 @@ export function renderTemplate(template, credentials) {
         .replaceAll("{username}", credentials.username)
         .replaceAll("{access_key}", credentials.accessKey);
 }
-export function authHeaders(credentials, auth = DEFAULT_AUTH) {
+/**
+ * The headers for one outbound call.
+ *
+ * ASYNC BECAUSE ONE SCHEME NEEDS A ROUND TRIP. `apiKey` and `http` are pure string work, but
+ * `oauth2` exchanges the caller's credentials for a JWT before anything can be sent, and
+ * there was nowhere to put that while this was synchronous. Both call sites were already
+ * inside async functions, so the cost is two `await`s.
+ */
+export async function authHeaders(credentials, auth = DEFAULT_AUTH, product = "this product", tokenTransport = fetchTokenTransport()) {
     if (!credentials?.username || !credentials?.accessKey) {
         // Refusing here beats sending unauthenticated and surfacing the product's 401, which
         // reads like the user's problem when it is our missing configuration.
@@ -59,6 +69,19 @@ export function authHeaders(credentials, auth = DEFAULT_AUTH) {
         "request-source": "ai-chatbot",
         "Content-Type": "application/json",
     };
+    if (auth.type === "oauth2") {
+        // Refused rather than ignored, which is the same call `in: cookie` and `in: query` get
+        // below: a field that looks like it selects behaviour and does not is how someone
+        // spends an afternoon on a 401 they were never going to be able to explain.
+        const stray = ["in", "name", "template"].filter((field) => auth[field] !== undefined);
+        if (stray.length > 0) {
+            throw new InvocationError(`oauth2 auth does not take ${stray.join(", ")}: a bearer token's presentation is ` +
+                `fixed at 'Authorization: Bearer' (RFC 6750). Remove ${stray.length > 1 ? "them" : "it"}, ` +
+                `or use apiKey if this product really does read a different header.`);
+        }
+        const token = await bearerToken(product, auth, credentials, tokenTransport);
+        return { Authorization: `Bearer ${token}`, ...common };
+    }
     const value = renderTemplate(auth.template || DEFAULT_AUTH.template, credentials);
     if (auth.type === "apiKey") {
         // Header only. `cookie` needs a session this server does not have, and `query` would

package/dist/tools/capability-registry/oauth.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bearer-JWT auth for products whose API does not accept `Api-Token`.
+ *
+ * The registry was built on "the caller's credentials, forwarded — never a token this server
+ * mints", and this is the first product that cannot work that way. The security property is
+ * unchanged: the exchange uses the caller's own username and access key, the JWT carries
+ * their `user_id`/`group_id` as signed claims, and the scopes narrow it BELOW what the raw
+ * credential could do. What changes is that a token is now minted rather than formatted, so
+ * the sentence to hold onto is "the server grants nothing beyond the caller's own identity",
+ * not "the server mints nothing".
+ *
+ * The mint itself lives in `lib/central-oauth.ts` and is shared with `askBrowserStackAI`.
+ * This module is only the part that is the registry's: where the endpoint and scopes come
+ * from, what a product is allowed to ask for, and how a failure is worded.
+ */
+import { Credentials, TokenTransport } from "../../lib/central-oauth.js";
+import { AuthScheme } from "./types.js";
+/**
+ * Where a central-OAuth JWT is minted, when a product does not name its own.
+ *
+ * Staging, for anyone setting the override:
+ *   CAPABILITY_REGISTRY_AUTH_TOKEN_URL = https://auth-preprod.bsstag.com/oauth2/v2/token
+ */
+export declare const DEFAULT_AUTH_TOKEN_URL = "https://auth.browserstack.com/oauth2/v2/token";
+/**
+ * The default scope set, and why it is a PAIR.
+ *
+ * `ai_agent` is the scope a product's gate matches on. `oauth_user_profile` is not extra
+ * authority — it is what makes the scope obtainable through the username+access_key flow at
+ * all, and this is measured rather than assumed: `ai_agent` alone comes back
+ * `400 invalid_request`, the pair mints, and the granted token's `scopes` claim carries both.
+ *
+ * Deliberately NOT `ask-browserstack`'s `CENTRAL_SCOPE`, which pairs `ai_agent_notify`
+ * instead — Atlas names its own so that changing this one cannot silently change what Atlas
+ * is authorised for.
+ */
+export declare const DEFAULT_SCOPES: readonly ["ai_agent", "oauth_user_profile"];
+/**
+ * Small, because the registry uses the token for ONE HTTP call.
+ *
+ * Nothing here holds it for the length of a run the way Atlas does, so this only has to
+ * cover clock skew and the flight time of the request it opens.
+ */
+export declare const REFRESH_SKEW_MS = 60000;
+/** For tests, and for anything that legitimately re-resolves. */
+export declare function resetOAuthAnnouncements(): void;
+/**
+ * Three rungs: the operator's override, then the product's declaration, then the built-in.
+ *
+ * Matching `base_url`, where config is explicitly "a default, not the last word" — a
+ * deployment pointed at staging must not be overruled by whatever an index happens to carry.
+ */
+export declare function resolveTokenUrl(product: string, auth?: AuthScheme): string;
+/** Two rungs. A scope does not vary by deployment the way a host does, so there is no env one. */
+export declare function resolveScope(auth?: AuthScheme): string;
+/**
+ * The Bearer value for one invocation.
+ *
+ * Cached per user for the life of the token when this process serves one caller, and not at
+ * all when it serves many — `mintCentralToken` is handed `cacheEnabled` rather than deciding
+ * for itself, because the rule is about THIS deployment, not about the mint.
+ */
+export declare function bearerToken(product: string, auth: AuthScheme | undefined, credentials: Credentials, transport: TokenTransport): Promise<string>;

package/dist/tools/capability-registry/oauth.js

@@ -0,0 +1,176 @@
+/**
+ * Bearer-JWT auth for products whose API does not accept `Api-Token`.
+ *
+ * The registry was built on "the caller's credentials, forwarded — never a token this server
+ * mints", and this is the first product that cannot work that way. The security property is
+ * unchanged: the exchange uses the caller's own username and access key, the JWT carries
+ * their `user_id`/`group_id` as signed claims, and the scopes narrow it BELOW what the raw
+ * credential could do. What changes is that a token is now minted rather than formatted, so
+ * the sentence to hold onto is "the server grants nothing beyond the caller's own identity",
+ * not "the server mints nothing".
+ *
+ * The mint itself lives in `lib/central-oauth.ts` and is shared with `askBrowserStackAI`.
+ * This module is only the part that is the registry's: where the endpoint and scopes come
+ * from, what a product is allowed to ask for, and how a failure is worded.
+ */
+import appConfig from "../../config.js";
+import logger from "../../logger.js";
+import { CentralAuthError, mintCentralToken, normaliseScopes, } from "../../lib/central-oauth.js";
+import { InvocationError } from "./index-loader.js";
+/**
+ * Where a central-OAuth JWT is minted, when a product does not name its own.
+ *
+ * Staging, for anyone setting the override:
+ *   CAPABILITY_REGISTRY_AUTH_TOKEN_URL = https://auth-preprod.bsstag.com/oauth2/v2/token
+ */
+export const DEFAULT_AUTH_TOKEN_URL = "https://auth.browserstack.com/oauth2/v2/token";
+/**
+ * The default scope set, and why it is a PAIR.
+ *
+ * `ai_agent` is the scope a product's gate matches on. `oauth_user_profile` is not extra
+ * authority — it is what makes the scope obtainable through the username+access_key flow at
+ * all, and this is measured rather than assumed: `ai_agent` alone comes back
+ * `400 invalid_request`, the pair mints, and the granted token's `scopes` claim carries both.
+ *
+ * Deliberately NOT `ask-browserstack`'s `CENTRAL_SCOPE`, which pairs `ai_agent_notify`
+ * instead — Atlas names its own so that changing this one cannot silently change what Atlas
+ * is authorised for.
+ */
+export const DEFAULT_SCOPES = ["ai_agent", "oauth_user_profile"];
+/**
+ * Small, because the registry uses the token for ONE HTTP call.
+ *
+ * Nothing here holds it for the length of a run the way Atlas does, so this only has to
+ * cover clock skew and the flight time of the request it opens.
+ */
+export const REFRESH_SKEW_MS = 60_000;
+/**
+ * Hosts a PRODUCT INDEX may name as its token endpoint.
+ *
+ * The index is a data file that ships to public npm and is read at startup. Letting it name
+ * an arbitrary `token_url` would let a file decide where the caller's username and access key
+ * get POSTed — so the file declares intent and this list bounds it. An operator setting the
+ * environment variable is a deliberate act and is trusted; shipping an index is not.
+ */
+const ALLOWED_TOKEN_HOSTS = [
+    "auth.browserstack.com",
+    "auth-preprod.bsstag.com",
+];
+/** Announced once per distinct resolution, so a wrong endpoint is a log line, not a deduction. */
+const announced = new Set();
+/** For tests, and for anything that legitimately re-resolves. */
+export function resetOAuthAnnouncements() {
+    announced.clear();
+}
+function announce(product, url, source) {
+    const line = `${product}|${url}|${source}`;
+    if (announced.has(line))
+        return;
+    announced.add(line);
+    logger.info("capability registry: %s mints its token at %s (source: %s)", product, url, source);
+}
+function assertMintable(url, product) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new InvocationError(`product '${product}' declares a token_url that is not a URL: ${JSON.stringify(url)}`);
+    }
+    // Same rule as the product call itself: credentials are never attached over plaintext.
+    if (parsed.protocol !== "https:") {
+        throw new InvocationError(`product '${product}' declares a token_url that is not https. The caller's ` +
+            `credentials are sent to it, so plaintext is refused.`);
+    }
+    if (!ALLOWED_TOKEN_HOSTS.includes(parsed.hostname)) {
+        throw new InvocationError(`product '${product}' declares a token_url on an unrecognised host ` +
+            `'${parsed.hostname}'. An index may only mint against ${ALLOWED_TOKEN_HOSTS.join(" or ")}; ` +
+            `set CAPABILITY_REGISTRY_AUTH_TOKEN_URL if this deployment really does mint elsewhere.`);
+    }
+    return url.replace(/\/+$/, "");
+}
+/**
+ * Three rungs: the operator's override, then the product's declaration, then the built-in.
+ *
+ * Matching `base_url`, where config is explicitly "a default, not the last word" — a
+ * deployment pointed at staging must not be overruled by whatever an index happens to carry.
+ */
+export function resolveTokenUrl(product, auth) {
+    const explicit = process.env.CAPABILITY_REGISTRY_AUTH_TOKEN_URL;
+    if (explicit && explicit.trim()) {
+        const url = explicit.trim().replace(/\/+$/, "");
+        announce(product, url, "env");
+        return url;
+    }
+    if (auth?.token_url && auth.token_url.trim()) {
+        const url = assertMintable(auth.token_url.trim(), product);
+        announce(product, url, "index");
+        return url;
+    }
+    announce(product, DEFAULT_AUTH_TOKEN_URL, "default");
+    return DEFAULT_AUTH_TOKEN_URL;
+}
+/** Two rungs. A scope does not vary by deployment the way a host does, so there is no env one. */
+export function resolveScope(auth) {
+    const declared = auth?.scopes;
+    if (Array.isArray(declared) && declared.length > 0)
+        return normaliseScopes(declared);
+    return normaliseScopes([...DEFAULT_SCOPES]);
+}
+/**
+ * A failure to mint is not a failure of the product, and must not read like one.
+ *
+ * Nothing from the token endpoint's body reaches these messages — it can echo the access key
+ * straight back. Only the classification and the status do.
+ */
+function toInvocationError(error, product) {
+    if (!(error instanceof CentralAuthError))
+        return error;
+    const prefix = `token_mint_failed: could not sign in to '${product}'`;
+    switch (error.kind) {
+        case "no_credentials":
+            return new InvocationError(`${prefix}: BrowserStack username and access key are required`);
+        case "unreachable":
+            return new InvocationError(`${prefix}: BrowserStack auth could not be reached. This is a connectivity or ` +
+                `auth-server problem, not a problem with your credentials. Nothing was sent to ` +
+                `'${product}'.`);
+        case "server_error":
+            return new InvocationError(`${prefix}: BrowserStack auth is unavailable (HTTP ${error.status}). YOUR ` +
+                `CREDENTIALS ARE NOT THE PROBLEM — a 5xx is the auth service failing, not a ` +
+                `rejection. Nothing was sent to '${product}'.`);
+        case "refused_scope":
+            return new InvocationError(`${prefix}: BrowserStack auth would not issue a token for the scope ` +
+                `"${error.scope}" (HTTP ${error.status}). YOUR CREDENTIALS ARE NOT THE PROBLEM — ` +
+                `this is a provisioning problem and the scope has to be enabled for this account ` +
+                `or application. This server will NOT retry with a weaker scope. Nothing was ` +
+                `sent to '${product}'.`);
+        case "refused_credentials":
+            return new InvocationError(`${prefix}: your BrowserStack credentials were rejected by BrowserStack auth ` +
+                `(HTTP ${error.status}). Nothing was sent to '${product}'.`);
+        default:
+            return new InvocationError(`${prefix}: BrowserStack auth answered HTTP ${error.status} without issuing a ` +
+                `token. Nothing was sent to '${product}'.`);
+    }
+}
+/**
+ * The Bearer value for one invocation.
+ *
+ * Cached per user for the life of the token when this process serves one caller, and not at
+ * all when it serves many — `mintCentralToken` is handed `cacheEnabled` rather than deciding
+ * for itself, because the rule is about THIS deployment, not about the mint.
+ */
+export async function bearerToken(product, auth, credentials, transport) {
+    try {
+        return await mintCentralToken({
+            url: resolveTokenUrl(product, auth),
+            scope: resolveScope(auth),
+            credentials,
+            transport,
+            refreshSkewMs: REFRESH_SKEW_MS,
+            cacheEnabled: !appConfig.REMOTE_MCP,
+        });
+    }
+    catch (error) {
+        throw toInvocationError(error, product);
+    }
+}