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

package/dist/services/tunnel/protocol/stream.js

@@ -0,0 +1,109 @@
+/**
+ * Debugg tunnel wire protocol v1 — one multiplexed stream as a node Duplex.
+ *
+ * A TunnelStream is the byte pipe for exactly one inbound browser connection.
+ * Both ends pipe it straight at a socket, so being a real Duplex (and honouring
+ * backpressure in both directions) is the whole point:
+ *
+ *   server:  socket.pipe(stream).pipe(socket)
+ *   client:  stream.pipe(net.connect(caddyLoopbackPort)).pipe(stream)
+ *
+ * Writes become DATA frames of at most MAX_DATA_PAYLOAD, gated by the stream's
+ * remaining credit. end() sends END. destroy() sends RST.
+ *
+ * All protocol state lives in the session; this class only forwards. The one
+ * piece of cleverness is the read() override, which is how the session learns
+ * how many bytes the application has actually consumed and therefore how much
+ * credit it may give back.
+ */
+import { Duplex } from 'node:stream';
+import { ErrorCode, MAX_DATA_PAYLOAD } from './constants.js';
+export class TunnelStream extends Duplex {
+    /** The stream id the server allocated. */
+    id;
+    /**
+     * Whitelisted OPEN metadata. Informational only — NEVER a dial target
+     * (see the SSRF note on bead debugg_ai_mcp-xkoh.1.2).
+     */
+    metadata;
+    host;
+    pendingResetCode;
+    pushedTotal = 0;
+    reportedConsumed = 0;
+    constructor(options) {
+        super({
+            // One frame's worth of writable buffer: enough to keep the wire busy,
+            // little enough that a piped producer is held back rather than drained.
+            writableHighWaterMark: MAX_DATA_PAYLOAD,
+            readableHighWaterMark: MAX_DATA_PAYLOAD,
+            allowHalfOpen: true,
+        });
+        this.id = options.id;
+        this.metadata = options.metadata;
+        this.host = options.host;
+    }
+    /**
+     * Abort both directions with RST(code). Defaults to ErrorCode.RESET. Use
+     * ErrorCode.UPSTREAM_UNREACHABLE when the local target could not be dialled,
+     * so the server can render DEBUGG_TUNNEL_UPSTREAM_REFUSED.
+     *
+     * Deliberately does not raise a local 'error': the side that chose to reset
+     * already knows, and an unhandled 'error' on a Duplex throws.
+     */
+    reset(code = ErrorCode.RESET) {
+        this.pendingResetCode = code;
+        this.destroy();
+    }
+    /**
+     * Hand the session's inbound bytes to the readable side.
+     *
+     * Never call push() directly: in flowing mode node delivers a pushed chunk
+     * straight to the 'data' listener without it ever entering the buffer or going
+     * through read(), so consumption has to be reconciled right here. Missing it
+     * means credit is never returned and a transfer larger than one window
+     * deadlocks — which is exactly what it did.
+     */
+    deliver(chunk) {
+        this.pushedTotal += chunk.length;
+        const accepted = this.push(chunk);
+        this.syncConsumed();
+        return accepted;
+    }
+    /** The peer half-closed: no more inbound bytes on this stream. */
+    deliverEnd() {
+        this.push(null);
+    }
+    /**
+     * Bytes that have left the readable buffer are bytes the application consumed,
+     * and those are what the session may grant back as WINDOW. Credit is never
+     * given for bytes still sitting in the buffer.
+     */
+    syncConsumed() {
+        const consumed = this.pushedTotal - this.readableLength;
+        const delta = consumed - this.reportedConsumed;
+        if (delta <= 0)
+            return;
+        this.reportedConsumed = consumed;
+        this.host.streamConsumed(this, delta);
+    }
+    read(size) {
+        const chunk = super.read(size);
+        this.syncConsumed();
+        return chunk;
+    }
+    _read() {
+        // Nothing to pull: the session pushes as DATA frames arrive, and flow
+        // control — not this callback — is what limits how much can be in flight.
+    }
+    _write(chunk, encoding, cb) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+        this.host.streamWrite(this, buf, cb);
+    }
+    _final(cb) {
+        this.host.streamFinal(this, cb);
+    }
+    _destroy(err, cb) {
+        this.host.streamDestroy(this, err, this.pendingResetCode);
+        cb(err);
+    }
+}

package/dist/services/tunnel/protocol/transport.js

@@ -0,0 +1,106 @@
+/**
+ * Debugg tunnel wire protocol v1 — transport seam.
+ *
+ * TunnelSession never touches a websocket directly. It talks to a FrameTransport,
+ * which is what lets the unit tests drive a session frame by frame (and with fake
+ * timers) while the integration tests run the same session over a real `ws`
+ * socket. `ws` is referenced only structurally here, so this module keeps its
+ * "node: built-ins only" property and stays embeddable in the tunnel server.
+ */
+/** RFC 6455: the connection dropped without a close handshake. */
+const ABNORMAL_CLOSURE = 1006;
+/** ws hands out Buffer, ArrayBuffer, or an array of Buffers for a fragmented message. */
+function toBytes(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    if (Array.isArray(data) && data.every((part) => Buffer.isBuffer(part)))
+        return Buffer.concat(data);
+    return undefined;
+}
+function reasonToString(reason) {
+    if (typeof reason === 'string')
+        return reason;
+    if (Buffer.isBuffer(reason))
+        return reason.toString('utf8');
+    if (reason instanceof ArrayBuffer)
+        return Buffer.from(reason).toString('utf8');
+    return '';
+}
+/**
+ * Adapt a ws WebSocket (client or server side) to a FrameTransport.
+ *
+ * Responsibilities: normalise inbound data to a Uint8Array, reject text messages
+ * as invalid, and make sure the session is told exactly once that the socket is
+ * gone — whichever of 'close' and 'error' happens to fire, and in whichever
+ * order.
+ */
+export function webSocketTransport(ws) {
+    let handlers;
+    let closed = false;
+    let socketError;
+    const reportClose = (code, reason) => {
+        if (closed)
+            return;
+        closed = true;
+        handlers?.onClose(code, reason);
+    };
+    return {
+        send(frame, cb) {
+            if (closed) {
+                cb(new Error('websocket is closed'));
+                return;
+            }
+            try {
+                ws.send(frame, (err) => cb(err ?? null));
+            }
+            catch (err) {
+                cb(err);
+            }
+        },
+        close(code, reason) {
+            try {
+                ws.close(code, reason);
+            }
+            catch {
+                /* already closing; the close event still settles the session */
+            }
+        },
+        terminate() {
+            try {
+                ws.terminate();
+            }
+            catch {
+                /* nothing left to tear down */
+            }
+        },
+        setHandlers(next) {
+            handlers = next;
+            ws.on('message', (data, isBinary) => {
+                if (closed)
+                    return;
+                if (!isBinary) {
+                    next.onInvalidMessage('text message');
+                    return;
+                }
+                const bytes = toBytes(data);
+                if (!bytes) {
+                    next.onInvalidMessage('message was not binary data');
+                    return;
+                }
+                next.onFrame(bytes);
+            });
+            ws.on('error', (err) => {
+                // ws emits 'close' after 'error' for a live socket, so hold the reason
+                // and let the close path report it — unless no close ever arrives.
+                socketError = err;
+            });
+            ws.on('close', (code, reason) => {
+                reportClose(code || ABNORMAL_CLOSURE, reasonToString(reason) || socketError?.message || '');
+            });
+        },
+    };
+}

package/dist/services/tunnel/transport.js

@@ -0,0 +1,15 @@
+/**
+ * TunnelTransport — the one step of tunnel creation that differs between ngrok
+ * and the debugg tunnel server.
+ *
+ * STUB (bead debugg_ai_mcp-xkoh.5.3, phase 2.1). Types and signatures only; the
+ * implementations arrive in phase 4.1 (debugg_ai_mcp-xkoh.5.7).
+ *
+ * Everything above this seam is unchanged: handlers, utils/tunnelContext.ts,
+ * the per-session Caddy instance, PortLock, URL rewriting, the retry ladder,
+ * the idle timer and the session keying all behave exactly as they do today
+ * (docs/debugg-tunnel-server-design-2026-09-19.md §5). TunnelManager picks an
+ * implementation from the provision response and calls it where it calls
+ * ngrok.connect() today.
+ */
+export {};

package/dist/services/tunnels.js

@@ -4,6 +4,7 @@
  * Called before executeWorkflow so the tunnel URL is known before execution starts.
  */
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { isValidTunnelDomain, registerTunnelDomain, } from '../utils/tunnelDomains.js';
 /**
  * Typed error thrown by provision() when the backend/ngrok path fails.
  * Carries diagnostic fields a retry wrapper (bead 7nx) can use to decide
@@ -80,11 +81,29 @@ export function classifyProvisionError(err) {
 }
 const DEFAULT_BACKOFF_MS = [500, 1500, 3000];
 const DEFAULT_MAX_ATTEMPTS = 3;
+/** The transports this client can actually drive, best first. */
+export const SUPPORTED_TRANSPORTS = Object.freeze(['debugg', 'ngrok']);
+/** A relay URL must be wss, except against a loopback backend (local dev, tests). */
+function isAcceptableRelayUrl(relayUrl) {
+    let url;
+    try {
+        url = new URL(relayUrl);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === 'wss:')
+        return true;
+    if (url.protocol !== 'ws:')
+        return false;
+    const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+}
 export const createTunnelsService = (tx) => {
     async function provision(purpose = 'workflow') {
         let response;
         try {
-            response = await tx.post('api/v1/tunnels/', { purpose });
+            response = await tx.post('api/v1/tunnels/', { purpose, transports: [...SUPPORTED_TRANSPORTS] });
         }
         catch (err) {
             throw classifyProvisionError(err);
@@ -95,12 +114,61 @@ export const createTunnelsService = (tx) => {
                 retryable: false,
             });
         }
-        return {
+        // No `transport` means an old backend that predates negotiation, which only
+        // ever hands out ngrok keys.
+        const transport = (response.transport ?? 'ngrok');
+        if (!SUPPORTED_TRANSPORTS.includes(transport)) {
+            throw new TunnelProvisionError({
+                message: `Tunnel provisioning selected transport "${response.transport}", which this client cannot speak ` +
+                    `(it offered ${SUPPORTED_TRANSPORTS.join(', ')}). Update @debugg-ai/debugg-ai-mcp.`,
+                retryable: false,
+            });
+        }
+        const result = {
             tunnelId: response.tunnelId,
             tunnelKey: response.tunnelKey,
             keyId: response.keyId,
             expiresAt: response.expiresAt,
+            transport,
         };
+        if (transport === 'debugg') {
+            // Every one of these is non-retryable: retrying cannot turn a malformed
+            // response into a usable one, and TunnelManager must never be handed a
+            // debugg token with nowhere to send it.
+            if (!response.relayUrl || !response.tunnelDomain) {
+                throw new TunnelProvisionError({
+                    message: 'Tunnel provisioning selected the debugg transport but omitted relayUrl or tunnelDomain',
+                    retryable: false,
+                });
+            }
+            if (!isAcceptableRelayUrl(response.relayUrl)) {
+                throw new TunnelProvisionError({
+                    message: `Tunnel provisioning returned a relayUrl that is not wss (${response.relayUrl}); ` +
+                        'refusing to send the tunnel key over it',
+                    retryable: false,
+                });
+            }
+            if (!isValidTunnelDomain(response.tunnelDomain)) {
+                throw new TunnelProvisionError({
+                    message: `Tunnel provisioning returned an unusable tunnelDomain (${response.tunnelDomain})`,
+                    retryable: false,
+                });
+            }
+            // Registering it here is what stops a tunnel URL leaking: everything that
+            // recognises or rewrites a tunnel hostname reads this same registry, so a
+            // domain the backend moves to is covered the moment it is handed to us.
+            registerTunnelDomain(response.tunnelDomain, 'debugg');
+            result.relayUrl = response.relayUrl;
+            result.tunnelDomain = response.tunnelDomain;
+        }
+        return result;
+    }
+    async function revoke(provisionInfo) {
+        if (provisionInfo.transport === 'debugg') {
+            await tx.post(`api/v1/tunnels/${provisionInfo.tunnelId}/revoke/`, {});
+            return;
+        }
+        await tx.post('api/v1/ngrok/revoke/', { ngrokKeyId: provisionInfo.keyId });
     }
     async function provisionWithRetry(opts = {}) {
         const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
@@ -144,5 +212,5 @@ export const createTunnelsService = (tx) => {
             retryable: false,
         });
     }
-    return { provision, provisionWithRetry };
+    return { provision, provisionWithRetry, revoke };
 };

package/dist/services/verdictAdapter.js

@@ -27,10 +27,34 @@ export const KNOWN_OUTCOMES = ['pass', 'fail', 'inconclusive', 'error', 'timeout
 const KNOWN = new Set(KNOWN_OUTCOMES);
 /** Credential sources that mean "the caller named this account for this run". */
 const CALLER_SPECIFIED_SOURCES = new Set(['task', 'explicit', 'credential_id']);
-/** True when this login used an environment default rather than a named account. */
+/**
+ * True when this login's credential CAME FROM the environment rather than a
+ * named account. Says nothing about whether it was ever used — a refused
+ * `offscope_host` skip carries an env source too. See credentialSubstitutions.
+ */
 export function isEnvironmentDefault(login) {
     return !!login.source && !CALLER_SPECIFIED_SOURCES.has(login.source);
 }
+/**
+ * The logins that really did substitute an environment default for an account
+ * the caller named (bead b5x6). All three must hold:
+ *   - the credential came from the environment (isEnvironmentDefault);
+ *   - it was actually submitted — a refused or skipped login typed nothing, so
+ *     "signed in with an environment default" would be false (client runs
+ *     2d4970a6, 146f081f);
+ *   - it names an account, and not one the caller asked for — the environment's
+ *     stored credential can BE the requested account, and a warning that lists
+ *     X as both requested and used contradicts itself (client run 146f081f).
+ * Identities compare trimmed and case-insensitively (they are emails).
+ */
+export function credentialSubstitutions(logins, namedIdentities) {
+    const norm = (s) => s.trim().toLowerCase();
+    const named = new Set(namedIdentities.filter((u) => typeof u === 'string' && u.trim() !== '').map(norm));
+    return (logins ?? []).filter((l) => isEnvironmentDefault(l)
+        && l.submitted === true
+        && typeof l.username === 'string' && l.username.trim() !== ''
+        && !named.has(norm(l.username)));
+}
 /**
  * Map a workflow execution onto the MCP relay verdict. Never throws.
  */

package/dist/tools/environment.js

@@ -12,12 +12,14 @@ const CRED_ITEM = {
 const DESCRIPTION = `Manage environments (and their login credentials) under a project. Pass an "action":
   - "get"    {uuid, projectUuid?} → one environment with credentials inline (passwords never returned).
   - "list"   {projectUuid?, q?, page?, pageSize?} → paginated environments. projectUuid auto-resolves from the git repo if omitted.
-  - "create" {name, url, description?, projectUuid?, credentials?} → create an env, optionally seeding credentials.
-  - "update" {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?} → patch env + manage credentials.
+  - "create" {name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?} → create an env, optionally seeding credentials.
+  - "update" {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?} → patch env + manage credentials.
   - "delete" {uuid, projectUuid?, confirm?} → delete env (DESTRUCTIVE; requires confirmation).
   - "sessions" {uuid, username?, credentialId?} → captured login sessions this env is holding, and whether each would be reused.
   - "clearSessions" {uuid, username?, credentialId?, confirm?} → invalidate them so the next run logs in for real.
 
+CROSS-DOMAIN SSO: a run only types this environment's credentials on the app's own host (and its subdomains); a login on any other host is refused as offscope_host. If your identity provider lives on a different domain than the app, add the IdP host to authorizedCredentialHosts — bare hostnames like "auth.example.com", no scheme/path/port/wildcard. The response echoes the saved list; if it reports authorizedCredentialHostsWarning, the server did not persist it.
+
 SESSIONS: runs reuse a warm authenticated session per account instead of logging in every time. That is why a check can report "no login form" — it was already signed in. Use "sessions" to see whose session is held, "clearSessions" to drop it, or pass freshSession:true on a single check_app_in_browser call to bypass reuse without clearing anything.`;
 export function buildEnvironmentTool() {
     return {
@@ -41,6 +43,7 @@ export function buildEnvironmentTool() {
                 addCredentials: { type: 'array', items: CRED_ITEM, description: '[update] Add credentials.' },
                 updateCredentials: { type: 'array', items: { type: 'object', properties: { uuid: { type: 'string' }, label: { type: 'string' }, username: { type: 'string' }, password: { type: 'string' }, role: { type: 'string' } }, required: ['uuid'], additionalProperties: false }, description: '[update] Patch credentials by UUID.' },
                 removeCredentialIds: { type: 'array', items: { type: 'string' }, description: '[update] Delete credentials by UUID.' },
+                authorizedCredentialHosts: { type: 'array', items: { type: 'string' }, description: "[create/update] Hosts where the run may enter this environment's credentials besides the app's own host, e.g. your identity provider for cross-domain SSO. Bare hostnames only (auth.example.com). On update this REPLACES the list; [] clears it." },
                 username: { type: 'string', description: '[sessions/clearSessions] Narrow to one account. Matched case-insensitively.' },
                 credentialId: { type: 'string', description: '[sessions/clearSessions] Narrow to one stored credential by UUID.' },
                 confirm: { type: 'boolean', description: '[delete/clearSessions] Set true to confirm (when the client cannot prompt). clearSessions only needs it when no username/credentialId narrows it.' },

package/dist/tools/testPageChanges.js

@@ -112,7 +112,7 @@ export function buildTestPageChangesTool(ctx) {
                 },
                 auth: {
                     type: "object",
-                    description: "Optional auth-precondition for a 'log in THEN deep-navigate' check. Set precondition:'login' to authenticate first, then land on deepUrl. Use this instead of hoping the agent signs itself in at a login wall. Pass username/password here to pin WHICH account it authenticates as; omit them to use the environment's default credential.",
+                    description: "Optional auth-precondition for a 'log in THEN deep-navigate' check. Set precondition:'login' to authenticate first, then land on deepUrl. Use this instead of hoping the agent signs itself in at a login wall. Pass username/password here to pin WHICH account it authenticates as; omit them to use the environment's default credential. Cross-domain SSO (sign-in page on a different domain than the app): add that IdP host to the environment's authorizedCredentialHosts (environment tool), or the login there is refused as offscope_host.",
                     properties: {
                         environmentId: {
                             type: "string",

package/dist/types/index.js

@@ -126,12 +126,38 @@ const CredentialSeedSchema = z.object({
     password: z.string().min(1, 'password is required'),
     role: z.string().min(1).optional(),
 }).strict();
+/**
+ * One entry of an environment's authorizedCredentialHosts (bead q4d4): a bare
+ * hostname where a run may type this environment's credentials besides the
+ * app's own host — typically the identity provider of a cross-domain SSO app.
+ * The backend matches it against a URL's lowercased hostname, exactly, so a
+ * scheme, path, port or wildcard could never match anything; reject them here
+ * with the reason instead of storing a host that silently does nothing.
+ */
+const HOSTNAME_RE = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))*$/;
+const AuthorizedCredentialHostSchema = z.string().trim().toLowerCase().superRefine((h, ctx) => {
+    const bad = (message) => ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+    if (h === '')
+        return bad('host must not be empty');
+    if (h.includes('://'))
+        return bad(`'${h}' has a scheme — pass the bare hostname (e.g. auth.example.com), not a URL`);
+    if (h.includes('/'))
+        return bad(`'${h}' has a path — pass the bare hostname only (e.g. auth.example.com)`);
+    if (h.includes('*'))
+        return bad(`'${h}' is a wildcard — list each host explicitly (subdomains of the app's own host are already in scope)`);
+    if (h.includes(':'))
+        return bad(`'${h}' has a port — pass the bare hostname; hosts are matched without a port`);
+    if (h.length > 253 || !HOSTNAME_RE.test(h))
+        return bad(`'${h}' is not a valid hostname`);
+});
+const AuthorizedCredentialHostsSchema = z.array(AuthorizedCredentialHostSchema).max(50, 'at most 50 hosts');
 export const CreateEnvironmentInputSchema = z.object({
     name: z.string().min(1, 'name is required'),
     url: z.string().url('url is required for standard environments'),
     description: z.string().optional(),
     projectUuid: z.string().uuid().optional(),
     credentials: z.array(CredentialSeedSchema).optional(),
+    authorizedCredentialHosts: AuthorizedCredentialHostsSchema.optional(),
 }).strict();
 const CredentialUpdateSchema = z.object({
     uuid: z.string().uuid(),
@@ -149,6 +175,7 @@ export const UpdateEnvironmentInputSchema = z.object({
     addCredentials: z.array(CredentialSeedSchema).optional(),
     updateCredentials: z.array(CredentialUpdateSchema).optional(),
     removeCredentialIds: z.array(z.string().uuid()).optional(),
+    authorizedCredentialHosts: AuthorizedCredentialHostsSchema.optional(),
 }).strict();
 export const DeleteEnvironmentInputSchema = z.object({
     uuid: z.string().uuid(),
@@ -326,8 +353,8 @@ export const ProjectInputSchema = z.discriminatedUnion('action', [
 export const EnvironmentInputSchema = z.discriminatedUnion('action', [
     z.object({ action: z.literal('get'), uuid: z.string().uuid(), projectUuid: z.string().uuid().optional() }).strict(),
     z.object({ action: z.literal('list'), projectUuid: z.string().uuid().optional(), q: z.string().min(1).optional(), page: _page, pageSize: _pageSize }).strict(),
-    z.object({ action: z.literal('create'), name: z.string().min(1), url: z.string().url('url is required for standard environments'), description: z.string().optional(), projectUuid: z.string().uuid().optional(), credentials: z.array(CredentialSeedSchema).optional() }).strict(),
-    z.object({ action: z.literal('update'), uuid: z.string().uuid(), name: z.string().min(1).optional(), url: z.string().url().optional(), description: z.string().optional(), projectUuid: z.string().uuid().optional(), addCredentials: z.array(CredentialSeedSchema).optional(), updateCredentials: z.array(CredentialUpdateSchema).optional(), removeCredentialIds: z.array(z.string().uuid()).optional() }).strict(),
+    z.object({ action: z.literal('create'), name: z.string().min(1), url: z.string().url('url is required for standard environments'), description: z.string().optional(), projectUuid: z.string().uuid().optional(), credentials: z.array(CredentialSeedSchema).optional(), authorizedCredentialHosts: AuthorizedCredentialHostsSchema.optional() }).strict(),
+    z.object({ action: z.literal('update'), uuid: z.string().uuid(), name: z.string().min(1).optional(), url: z.string().url().optional(), description: z.string().optional(), projectUuid: z.string().uuid().optional(), addCredentials: z.array(CredentialSeedSchema).optional(), updateCredentials: z.array(CredentialUpdateSchema).optional(), removeCredentialIds: z.array(z.string().uuid()).optional(), authorizedCredentialHosts: AuthorizedCredentialHostsSchema.optional() }).strict(),
     z.object({ action: z.literal('delete'), uuid: z.string().uuid(), projectUuid: z.string().uuid().optional(), confirm: z.boolean().optional() }).strict(),
     // Captured authenticated sessions (sentinal-cs1hn.5). The backend holds a warm
     // session per account and restores it to skip login; these two actions make that

package/dist/utils/authorizedCredentialHosts.js

@@ -0,0 +1,38 @@
+/**
+ * Echo check for an environment's authorizedCredentialHosts (bead q4d4).
+ *
+ * The MCP ships this field before every backend accepts it (sentinal-oj7dp.23).
+ * A backend that does not know the field ignores it and still answers 200, so a
+ * create/update "succeeds" whether or not the hosts were saved. The only proof
+ * is the response echoing them back — so when it doesn't, say so loudly instead
+ * of letting the caller believe cross-domain SSO is now configured.
+ */
+const norm = (hosts) => new Set(hosts.map((h) => h.trim().toLowerCase()));
+/**
+ * Compare the requested hosts with the backend's echo. Returns a warning when
+ * they differ (as sets, case-insensitively — the backend normalizes), or
+ * undefined when the echo confirms them. `op` shapes the advice: a create has
+ * already created the environment, so a retry of create would duplicate it.
+ */
+export function checkAuthorizedCredentialHostsEcho(requested, returned, op) {
+    const echoed = Array.isArray(returned) ? returned : null;
+    if (echoed) {
+        const want = norm(requested);
+        const got = norm(echoed);
+        if (want.size === got.size && [...want].every((h) => got.has(h)))
+            return undefined;
+    }
+    const hosts = requested.length > 0 ? requested.join(', ') : '(an empty list)';
+    const why = echoed
+        ? `The backend did not persist authorizedCredentialHosts as requested: it holds [${echoed.join(', ')}], not [${requested.join(', ')}].`
+        : 'The backend did not persist authorizedCredentialHosts: it is not yet supported on this DebuggAI server ' +
+            '(the response did not echo the hosts back).';
+    const applied = op === 'create'
+        ? 'The environment itself WAS created, with any credentials listed here — do not re-run create; ' +
+            'set the hosts later with environment {action:"update"}.'
+        : 'Everything else in this update was applied.';
+    const consequence = requested.length > 0
+        ? ` Until the hosts are saved, check_app_in_browser will still refuse to enter credentials on ${hosts} (offscope_host).`
+        : '';
+    return { requested, returned: echoed, message: `${why} ${applied}${consequence}` };
+}