@browserstack/mcp-server 1.5.1-beta.2 → 2.0.0-beta.1

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);
+    }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Strip the PII we can identify by SHAPE from agent-written intent text, before it is
+ * recorded as telemetry.
+ *
+ * Regex only, no model call: this runs on every capability search and write, so it must
+ * be deterministic, allocation-light and incapable of adding latency or a failure mode.
+ *
+ * WHAT THIS CANNOT DO, and must not be described as doing: a person's NAME has no shape.
+ * "assign this to Priya Sharma" is PII and passes through untouched, because no pattern
+ * separates a person from a project ("Payments Regression") without destroying the field's
+ * value. Physical addresses are the same. Redaction here REDUCES exposure; it does not
+ * eliminate it, and the sign-off should be read on those terms.
+ */
+/**
+ * The ceiling on any redacted field.
+ *
+ * The rules above catch PII by shape, and the header is explicit that a person's NAME has
+ * none — so the longer the recorded string, the more unshaped personal detail rides along
+ * with it. A cap does not make the field safe; it bounds how much escapes when redaction
+ * misses, which it will. 512 leaves an ordinary query or change summary intact.
+ *
+ * This existed, was removed, and the doc comment kept claiming it for two commits. Both
+ * fields it guards are free text an agent writes from what the user said.
+ */
+export declare const MAX_LENGTH = 512;
+/**
+ * Returns the text with shape-identifiable PII replaced, capped at `MAX_LENGTH`.
+ *
+ * FAILS CLOSED: any throw returns undefined, so the caller records no field rather than
+ * the raw value. Non-string and empty input yields undefined for the same reason.
+ */
+export declare function redact(text: unknown): string | undefined;
+/** The rule names, for documenting what is covered. */
+export declare const REDACTED_TYPES: string[];

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

@@ -0,0 +1,98 @@
+/**
+ * Strip the PII we can identify by SHAPE from agent-written intent text, before it is
+ * recorded as telemetry.
+ *
+ * Regex only, no model call: this runs on every capability search and write, so it must
+ * be deterministic, allocation-light and incapable of adding latency or a failure mode.
+ *
+ * WHAT THIS CANNOT DO, and must not be described as doing: a person's NAME has no shape.
+ * "assign this to Priya Sharma" is PII and passes through untouched, because no pattern
+ * separates a person from a project ("Payments Regression") without destroying the field's
+ * value. Physical addresses are the same. Redaction here REDUCES exposure; it does not
+ * eliminate it, and the sign-off should be read on those terms.
+ */
+/**
+ * Ordered: earlier rules win. Every rule matches a SHAPE, never a word list — nothing here
+ * needs updating when a product renames a field or a new customer appears.
+ */
+const RULES = [
+    // Credentials inside a URL, before the email rule so `user:pass@host` is not
+    // half-matched as an address.
+    {
+        name: "url_credentials",
+        pattern: /\b(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi,
+        replacement: "$1[redacted]@",
+    },
+    {
+        name: "email",
+        pattern: /\b[\w.%+-]+@[\w.-]+\.[a-z]{2,}\b/gi,
+        replacement: "[email]",
+    },
+    // JWT: three base64url segments.
+    {
+        name: "jwt",
+        pattern: /\beyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]{8,}\b/g,
+        replacement: "[token]",
+    },
+    // A long opaque run — access keys, API keys, session ids. Requires BOTH a digit and a
+    // letter, so ordinary long words ("internationalisation") are never matched. This is
+    // the rule that catches a pasted credential regardless of how it was introduced, which
+    // is why no vocabulary of labels ("api_key", "bearer", ...) is hardcoded: guessing the
+    // wording a product uses is exactly the assumption that fails.
+    {
+        name: "opaque_token",
+        pattern: /\b(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{20,}\b/g,
+        replacement: "[token]",
+    },
+    {
+        name: "ipv4",
+        pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+        replacement: "[ip]",
+    },
+    // Phone: optional country prefix, then digit groups with separators. Requires a
+    // separator or a `+`, so a bare digit run falls to long_number instead.
+    {
+        name: "phone",
+        pattern: /(?:\+\d{1,3}[\s.-]?)?(?:\(\d{2,4}\)[\s.-]?)?\d{3,5}[\s.-]\d{3,5}(?:[\s.-]\d{2,5})?\b/g,
+        replacement: "[phone]",
+    },
+    // Long bare digit runs: account ids, card numbers, unseparated phone numbers.
+    { name: "long_number", pattern: /\b\d{9,}\b/g, replacement: "[number]" },
+];
+/**
+ * The ceiling on any redacted field.
+ *
+ * The rules above catch PII by shape, and the header is explicit that a person's NAME has
+ * none — so the longer the recorded string, the more unshaped personal detail rides along
+ * with it. A cap does not make the field safe; it bounds how much escapes when redaction
+ * misses, which it will. 512 leaves an ordinary query or change summary intact.
+ *
+ * This existed, was removed, and the doc comment kept claiming it for two commits. Both
+ * fields it guards are free text an agent writes from what the user said.
+ */
+export const MAX_LENGTH = 512;
+/**
+ * Returns the text with shape-identifiable PII replaced, capped at `MAX_LENGTH`.
+ *
+ * FAILS CLOSED: any throw returns undefined, so the caller records no field rather than
+ * the raw value. Non-string and empty input yields undefined for the same reason.
+ */
+export function redact(text) {
+    try {
+        if (typeof text !== "string")
+            return undefined;
+        let out = text.replace(/\s+/g, " ").trim();
+        if (!out)
+            return undefined;
+        for (const rule of RULES)
+            out = out.replace(rule.pattern, rule.replacement);
+        // Truncate AFTER redacting, so a value that would have been replaced cannot be split
+        // across the boundary and leave its first half in the clear.
+        return out.length > MAX_LENGTH ? `${out.slice(0, MAX_LENGTH)}…` : out;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The rule names, for documenting what is covered. */
+export const REDACTED_TYPES = RULES.map((r) => r.name);

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

@@ -0,0 +1,48 @@
+/**
+ * The tool surface: four discovery tools plus ONE invoke tool.
+ *
+ * Discovery is deliberately two steps. `searchCapability` returns a shortlist — enough to
+ * CHOOSE — and `describeCapability` returns the contract for the one chosen. Parameters and
+ * response shapes are 86% of a full record and are needed once, not eight times: measured
+ * over eight queries, ~8.6k tokens a search becomes ~1.1k, and even describing every result
+ * still costs less than the single fat call did.
+ *
+ * ONE invoke tool means one set of MCP annotations, so they describe the whole surface
+ * honestly: it can write (not read-only) and it can never delete, because destructive
+ * endpoints are refused before binding. Write consent therefore rests on `user_permission`
+ * enforced HERE rather than on a client-side hint — which is the one thing a separate
+ * read/write tool pair was buying.
+ */
+import { McpServer, RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+import { Credentials, Transport } from "./egress.js";
+import { CapabilityRegistry } from "./index-loader.js";
+export declare const PERMISSION_VALUES: readonly ["not_asked", "granted", "denied"];
+/**
+ * The search-side twin of `user_permission`: did a human choose the product, or did you?
+ *
+ * No `denied`. A refused write is a thing the caller must not do; a refused product choice
+ * is not a state — the user either named one, in which case you search it, or has not been
+ * asked, in which case there is nothing to search yet.
+ */
+export declare const PRODUCT_CHOICE_VALUES: readonly ["not_asked", "user_confirmed"];
+export interface RegistryDeps {
+    registry: CapabilityRegistry;
+    /**
+     * Per-product base URL. Never baked into the artifact — it is environment AND account
+     * specific: tm is region-sharded, so this is resolved per call, not once at startup.
+     */
+    baseUrlFor: (product: string) => Promise<string>;
+    credentialsFor: () => Credentials;
+    transport?: Transport;
+}
+/**
+ * The tool-adder the server factory calls.
+ *
+ * Registers NOTHING when the artifact is absent or unreadable, rather than throwing: a
+ * missing index is a packaging problem, and taking the whole MCP server down with it would
+ * remove every other product's tools too. The reason is logged so it is not silent.
+ */
+export declare function addCapabilityRegistryToolsFromConfig(server: McpServer, config: BrowserStackConfig): Record<string, RegisteredTool>;
+export declare function addCapabilityRegistryTools(server: McpServer, deps: RegistryDeps, config?: BrowserStackConfig): Record<string, RegisteredTool>;
+export default addCapabilityRegistryToolsFromConfig;