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

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;