@debugg-ai/debugg-ai-mcp 4.3.0 → 4.4.0

package/dist/utils/tunnelDomains.js

@@ -0,0 +1,113 @@
+/**
+ * The hostnames a tunnel can live on, and which transport serves each one.
+ *
+ * During the migration a single MCP process can hold an ngrok tunnel and a
+ * debugg tunnel at the same time, so every place that recognises a tunnel
+ * hostname has to know both. The one that matters to users is
+ * `replaceTunnelUrls`: it is what keeps a tunnel hostname out of every tool
+ * response, so a domain it does not know is a URL that leaks to the caller.
+ *
+ * A provision response may name a domain we do not ship (the backend moving
+ * `tunnel.debugg.ai` elsewhere, or a staging host), so domains can be
+ * registered at runtime — that is what lets the server move without an MCP
+ * release, the same reasoning as `relayUrl`.
+ *
+ * Imports NOTHING, deliberately: utils/urlParser.ts, utils/localReachability.ts
+ * and services/ngrok/tunnelManager.ts all depend on it, and it must never be
+ * the module that creates a cycle.
+ */
+const BUILT_IN_DOMAINS = Object.freeze([
+    { domain: 'ngrok.debugg.ai', transport: 'ngrok' },
+    { domain: 'tunnel.debugg.ai', transport: 'debugg' },
+]);
+const domains = new Map(BUILT_IN_DOMAINS.map((d) => [d.domain, d.transport]));
+/**
+ * A tunnel domain must be a lowercase DNS name of at least THREE labels.
+ *
+ * The label count is a safety rule, not a style one: a registered domain
+ * becomes a rewrite target, so accepting `debugg.ai` would make
+ * `replaceTunnelUrls` rewrite every real product link in a backend response
+ * (`https://app.debugg.ai/runs/1`) into the caller's localhost origin.
+ */
+export function isValidTunnelDomain(domain) {
+    if (typeof domain !== 'string')
+        return false;
+    if (domain.length > 253)
+        return false;
+    const labels = domain.split('.');
+    if (labels.length < 3)
+        return false;
+    return labels.every((label) => /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
+}
+/**
+ * Teach this process about a tunnel domain. Idempotent, and safe to call on
+ * every provision. Returns false for a domain that fails validation, so a
+ * caller can turn that into an error rather than silently trusting it.
+ */
+export function registerTunnelDomain(domain, transport) {
+    if (!isValidTunnelDomain(domain))
+        return false;
+    domains.set(domain, transport);
+    return true;
+}
+/** Every known domain, built-in and registered. */
+export function knownTunnelDomains() {
+    return [...domains.entries()].map(([domain, transport]) => ({ domain, transport }));
+}
+/** The known domain a host sits under, or undefined. Accepts a host or a full URL. */
+export function tunnelDomainFor(hostOrUrl) {
+    const host = hostOf(hostOrUrl);
+    if (!host)
+        return undefined;
+    for (const [domain, transport] of domains) {
+        // A tunnel host is always `<label>.<domain>` — never the bare domain.
+        if (host.length > domain.length + 1 && host.endsWith(`.${domain}`)) {
+            return { domain, transport };
+        }
+    }
+    return undefined;
+}
+export function isTunnelHost(hostOrUrl) {
+    return tunnelDomainFor(hostOrUrl) !== undefined;
+}
+/** The tunnel id (the leftmost label) of a tunnel host, or null. */
+export function extractTunnelIdFromHost(hostOrUrl) {
+    const host = hostOf(hostOrUrl);
+    const info = host ? tunnelDomainFor(host) : undefined;
+    if (!host || !info)
+        return null;
+    const label = host.slice(0, host.length - info.domain.length - 1);
+    return label.includes('.') ? null : label;
+}
+/**
+ * `https?://<label>.<known domain>` as one alternation, for whole-string
+ * rewriting. Rebuilt per call because the set can grow at runtime; these are
+ * short lists and the callers are not hot loops.
+ */
+export function tunnelUrlPattern() {
+    const alternatives = [...domains.keys()].map(escapeRegExp).join('|');
+    return new RegExp(`https?:\\/\\/[^\\s/"']+\\.(?:${alternatives})`, 'g');
+}
+function hostOf(hostOrUrl) {
+    if (typeof hostOrUrl !== 'string' || hostOrUrl.length === 0)
+        return undefined;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(hostOrUrl)) {
+        try {
+            return new URL(hostOrUrl).hostname.toLowerCase();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // A bare host, possibly with a port.
+    return hostOrUrl.split('/')[0].split(':')[0].toLowerCase();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Test hook: drop every runtime-registered domain, keeping the built-ins. */
+export function _resetTunnelDomainsForTests() {
+    domains.clear();
+    for (const { domain, transport } of BUILT_IN_DOMAINS)
+        domains.set(domain, transport);
+}

package/dist/utils/urlParser.js

@@ -2,6 +2,7 @@
  * URL Parser Utilities
  * Helper functions for parsing and validating URLs, specifically for detecting localhost URLs
  */
+import { tunnelUrlPattern } from './tunnelDomains.js';
 /**
  * Normalize a user-supplied URL string before validation.
  * Handles bare hostnames without a scheme (e.g. "localhost:3000" → "http://localhost:3000").
@@ -87,13 +88,18 @@ export function isLocalhostUrl(urlString) {
     }
 }
 /**
- * Replace ngrok tunnel URLs with the original localhost origin in any string/object.
+ * Replace tunnel URLs with the original localhost origin in any string/object.
  * Used to sanitize backend responses that contain internal tunnel URLs before
  * returning them to callers who only know the original localhost address.
+ *
+ * Covers EVERY known tunnel domain (utils/tunnelDomains.ts), not just ngrok's:
+ * during the migration one session can hold an ngrok tunnel and another a
+ * debugg tunnel, and a domain this does not know is a hostname that leaks to
+ * the caller.
  */
 export function replaceTunnelUrls(value, localhostOrigin) {
     if (typeof value === 'string') {
-        return value.replace(/https?:\/\/[^\s/"]+\.ngrok\.debugg\.ai/g, localhostOrigin.replace(/\/$/, ''));
+        return value.replace(tunnelUrlPattern(), localhostOrigin.replace(/\/$/, ''));
     }
     if (Array.isArray(value)) {
         return value.map(item => replaceTunnelUrls(item, localhostOrigin));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",
@@ -65,6 +65,7 @@
     "posthog-node": "^5.26.0",
     "uuid": "^11.1.0",
     "winston": "^3.15.0",
+    "ws": "^8.21.3",
     "zod": "^3.25.32"
   },
   "devDependencies": {
@@ -73,6 +74,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.24",
     "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.18.1",
     "eslint": "^10.2.0",
     "jest": "^30.0.5",
     "jest-environment-jsdom": "^30.0.5",