@zackbart/connecta 0.24.4 → 0.25.0

package/dist/routes/mcp.js

@@ -1,10 +1,12 @@
 import { createMcpHandler, isLegacyRequest, McpServer, WebStandardStreamableHTTPServerTransport, } from "@modelcontextprotocol/server";
+import { Effect, Exit, Result, Scope } from "effect";
 import { registerExecuteTool } from "../execute.js";
 import { ExecutorAdmissionError, } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
 import { intersectAccess } from "../connector-access.js";
 import { instructionsFor } from "../skills.js";
 import { msg } from "../errors.js";
+import { detach } from "../runtime/run.js";
 import { authorize, loggableValue, mayManageConnector, validateAuthPermissions, } from "./shared.js";
 export const MCP_CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
@@ -73,11 +75,16 @@ function requestAdmissionFailure(error) {
     }), { status: 503, headers });
 }
 /**
- * A request owns its permit through the response body, not merely until the
- * handler returns. This is what makes slow clients and response-stream failure
- * part of the same bounded lifecycle as success, error, and cancellation.
+ * Hand a response the Scope that holds what its request acquired.
+ *
+ * A request owns its permit and its McpServer through the response body, not
+ * merely until the handler returns. `close` runs once, on whichever comes
+ * first: the body is read to its end or fails, its reader cancels it, or the
+ * request's signal aborts. This is what makes slow clients and response-stream
+ * failure part of the same bounded lifecycle as success, error, and
+ * cancellation.
  */
-function releaseAdmissionWithResponse(response, lease, signal) {
+function closeWithBody(response, signal, close) {
     let released = false;
     let onAbort = () => { };
     const release = () => {
@@ -85,7 +92,7 @@ function releaseAdmissionWithResponse(response, lease, signal) {
             return;
         released = true;
         signal.removeEventListener("abort", onAbort);
-        lease.release();
+        close();
     };
     if (!response.body) {
         release();
@@ -133,6 +140,52 @@ function releaseAdmissionWithResponse(response, lease, signal) {
         headers: response.headers,
     });
 }
+/**
+ * Run a request's handler in a Scope that outlives it.
+ *
+ * The handler acquires into the scope and its response carries the scope
+ * out, for `closeWithBody` to close when the body ends. A handler that fails,
+ * or is interrupted because the request's signal aborted, closes it at once:
+ * nothing it acquired waits on a body that will never be read.
+ */
+function scopedToBody(handler, signal) {
+    return Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+        const scope = yield* Scope.make();
+        const exit = yield* Effect.exit(restore(Scope.provide(scope)(handler)));
+        if (Exit.isFailure(exit)) {
+            yield* Scope.close(scope, exit);
+            return yield* exit;
+        }
+        // Every finalizer in the scope is synchronous, so the close has run by
+        // the time detach returns: the permit is back, and handed to the next
+        // queued request, inside the read or cancel that ended the body.
+        return closeWithBody(exit.value, signal, () => {
+            void detach(Scope.close(scope, Exit.void));
+        });
+    }));
+}
+/**
+ * The request's admission permit, owned by its Scope.
+ *
+ * Admission goes through the controller's Promise rather than its Effect
+ * program (`acquireScoped`), on purpose. The pool is shared by every request
+ * in the isolate, and a queued request is handed its permit from inside the
+ * request whose body just ended. A fiber resumed there would authorize and
+ * serve this request in that one's I/O context, which workerd refuses;
+ * awaiting `acquire()`'s promise resumes it in its own.
+ *
+ * The wait stays interruptible, and a permit granted just as it was
+ * interrupted still arrives, later, to be released on arrival.
+ */
+function admitted(controller, signal) {
+    return Effect.acquireRelease(Effect.suspend(() => {
+        const pending = controller.acquire({ signal });
+        return Effect.tryPromise({ try: () => pending, catch: (error) => error })
+            .pipe(Effect.onInterrupt(() => Effect.sync(() => {
+            pending.then((lease) => lease.release(), () => { });
+        })));
+    }), (lease) => Effect.sync(() => lease.release()), { interruptible: true });
+}
 /**
  * 404 for any `?toolkit=` value, kept after the feature's retirement (#178).
  *
@@ -167,7 +220,11 @@ function toolkitRetired(logger) {
         },
     });
 }
-async function serveMcp(request, opts, baseUrl, actor, registry, canManageAuth, runtimeContext) {
+function serveMcp(request, opts, baseUrl, actor, registry, canManageAuth, runtimeContext) {
+    // Every McpServer the request builds is fresh and closes with its scope.
+    // The modern handler tears its own down after the exchange; the legacy
+    // transport never does, and neither may stay wired to an ended request.
+    const servers = [];
     const createServer = () => {
         const server = new McpServer(opts.serverInfo, {
             instructions: instructionsFor(),
@@ -240,26 +297,36 @@ async function serveMcp(request, opts, baseUrl, actor, registry, canManageAuth,
             ...(opts.hostCallTimeoutMs !== undefined
                 ? { hostCallTimeoutMs: opts.hostCallTimeoutMs }
                 : {}),
+            ...(opts.watchdogMs !== undefined
+                ? { watchdogMs: opts.watchdogMs }
+                : {}),
         });
+        servers.push(server);
         return server;
     };
-    // The v2 entry's built-in legacy fallback streams 2025 results as SSE.
-    // Connecta's established wire contract is JSON, so retain the documented
-    // user-land legacy branch with the same transport setting while the modern
-    // branch uses the fetch-native handler.
-    if (!(await isLegacyRequest(request))) {
-        return createMcpHandler(createServer, {
-            legacy: "reject",
-            onerror: (error) => opts.logger.error("[connecta] MCP handler error", error),
-        }).fetch(request);
-    }
-    // Fresh server + transport per legacy request, stateless and JSON-shaped.
-    const server = createServer();
-    const transport = new WebStandardStreamableHTTPServerTransport({
-        enableJsonResponse: true,
-    });
-    await server.connect(transport);
-    return transport.handleRequest(request);
+    const exchange = async () => {
+        // The v2 entry's built-in legacy fallback streams 2025 results as SSE.
+        // Connecta's established wire contract is JSON, so retain the documented
+        // user-land legacy branch with the same transport setting while the modern
+        // branch uses the fetch-native handler.
+        if (!(await isLegacyRequest(request))) {
+            return createMcpHandler(createServer, {
+                legacy: "reject",
+                onerror: (error) => opts.logger.error("[connecta] MCP handler error", error),
+            }).fetch(request);
+        }
+        // Fresh server + transport per legacy request, stateless and JSON-shaped.
+        const server = createServer();
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            enableJsonResponse: true,
+        });
+        await server.connect(transport);
+        return transport.handleRequest(request);
+    };
+    return Effect.addFinalizer(() => Effect.sync(() => {
+        for (const server of servers)
+            void server.close().catch(() => { });
+    })).pipe(Effect.andThen(Effect.promise(exchange)));
 }
 export function createMcpRoute(opts) {
     const configuredOrigins = opts.allowedOrigins;
@@ -322,10 +389,10 @@ export function createMcpRoute(opts) {
         lastAdmissionWarningAt = now;
         suppressedAdmissionWarnings = 0;
     };
-    async function routeMcp(context) {
+    function routeMcp(context) {
         const { path, request, baseUrl, runtimeContext, } = context;
         if (path !== "/mcp" && !path.startsWith("/mcp/"))
-            return null;
+            return Effect.succeed(null);
         const poolName = path === "/mcp" ? undefined : path.slice("/mcp/".length);
         const origin = request.headers.get("Origin");
         const allowed = origin === null || allowsOrigin(origin);
@@ -334,40 +401,39 @@ export function createMcpRoute(opts) {
         // local header check also guards OPTIONS before any provider metadata.
         const refusal = rejectOrigin(request);
         if (refusal)
-            return refusal;
-        if (request.method === "OPTIONS")
-            return cors(new Response(null, { status: 204 }));
-        let admission;
-        try {
-            admission = await opts.requestAdmission.acquire({
-                signal: request.signal,
-            });
-            if (admission.waitMs > 0) {
-                opts.logger.debug("[connecta] MCP request admitted after queue wait", {
-                    waitMs: admission.waitMs,
-                    active: opts.requestAdmission.activeCount,
-                    queued: opts.requestAdmission.queuedCount,
-                });
-            }
+            return Effect.succeed(refusal);
+        if (request.method === "OPTIONS") {
+            return Effect.succeed(cors(new Response(null, { status: 204 })));
         }
-        catch (error) {
-            if (error instanceof ExecutorAdmissionError &&
-                error.code === "executor_cancelled") {
-                throw request.signal.reason ?? error;
-            }
-            if (error instanceof ExecutorAdmissionError) {
+        return scopedToBody(Effect.gen(function* () {
+            const admission = yield* Effect.result(admitted(opts.requestAdmission, request.signal));
+            if (Result.isFailure(admission)) {
+                const error = admission.failure;
+                if (!(error instanceof ExecutorAdmissionError)) {
+                    return yield* Effect.fail(error);
+                }
+                if (error.code === "executor_cancelled") {
+                    return yield* Effect.fail(request.signal.reason ?? error);
+                }
                 if (error.code === "executor_overloaded") {
                     warnAdmissionRejected(error);
                 }
                 return cors(requestAdmissionFailure(error));
             }
-            throw error;
-        }
-        try {
-            const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
-            if (!authz.ok) {
-                return releaseAdmissionWithResponse(cors(authz.response), admission, request.signal);
+            if (admission.success.waitMs > 0) {
+                opts.logger.debug("[connecta] MCP request admitted after queue wait", {
+                    waitMs: admission.success.waitMs,
+                    active: opts.requestAdmission.activeCount,
+                    queued: opts.requestAdmission.queuedCount,
+                });
             }
+            // Promise code the fiber stops waiting on when the caller leaves. An
+            // Effect `authorize` would put Effect in the /activity bundle, which
+            // shares it, to save only the lookups an abandoned authorization
+            // finishes on its own.
+            const authz = yield* Effect.promise(() => authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity));
+            if (!authz.ok)
+                return cors(authz.response);
             // A pool endpoint narrows the identity's own view and nothing else. An
             // undeclared name, a grant that refuses, and a grant that throws are
             // one identical 404 so a credential never enumerates the other pools;
@@ -375,21 +441,18 @@ export function createMcpRoute(opts) {
             let access = authz;
             if (poolName !== undefined) {
                 const pool = opts.pools?.get(poolName);
-                let granted = false;
-                let reason = "undeclared";
-                if (pool) {
+                const reason = !pool ? "undeclared" : yield* Effect.promise(async () => {
                     try {
-                        granted = (await pool.grant(authz.identity)) === true;
-                        reason = granted ? "granted" : "refused";
+                        return (await pool.grant(authz.identity)) === true ? "granted" : "refused";
                     }
                     catch {
-                        reason = "grant threw";
+                        return "grant threw";
                     }
-                }
-                if (!pool || !granted) {
+                });
+                if (!pool || reason !== "granted") {
                     opts.logger.warn(`[connecta] refused /mcp/${poolName} with 404: pool ${reason}` +
                         (authz.actor.id ? ` for ${loggableValue(authz.actor.id)}` : ""));
-                    return releaseAdmissionWithResponse(cors(new Response("Not Found", { status: 404 })), admission, request.signal);
+                    return cors(new Response("Not Found", { status: 404 }));
                 }
                 access = intersectAccess(authz, pool.access);
             }
@@ -404,20 +467,16 @@ export function createMcpRoute(opts) {
                 });
             }
             catch (error) {
-                return releaseAdmissionWithResponse(cors(new Response(JSON.stringify({ error: msg(error) }), {
+                return cors(new Response(JSON.stringify({ error: msg(error) }), {
                     status: 403,
                     headers: { "Content-Type": "application/json" },
-                })), admission, request.signal);
+                }));
             }
             if (new URL(request.url).searchParams.has("toolkit")) {
-                return releaseAdmissionWithResponse(cors(toolkitRetired(opts.logger)), admission, request.signal);
+                return cors(toolkitRetired(opts.logger));
             }
-            return releaseAdmissionWithResponse(cors(await serveMcp(request, opts, baseUrl, authz.actor, scopedRegistry, id => { const connector = scopedRegistry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); }, runtimeContext)), admission, request.signal);
-        }
-        catch (error) {
-            admission.release();
-            throw error;
-        }
+            return cors(yield* serveMcp(request, opts, baseUrl, authz.actor, scopedRegistry, id => { const connector = scopedRegistry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); }, runtimeContext));
+        }), request.signal);
     }
     return { handle: routeMcp, rejectOrigin };
 }

package/dist/routes/oauth-management.js

@@ -1,70 +1,63 @@
-import { closeConnectorScope } from "../connector-scope.js";
+import { Effect, Result } from "effect";
+import { closeScope } from "../runtime/connector-scope.js";
 import { isSafeHttpUrl } from "../ui.js";
-import { authorizeUiIdentity, mayManageConnector, validateAuthPermissions, isSameOrigin, msg, privateJson, } from "./shared.js";
-async function handleOAuthManagementRequest(context, connectorId) {
-    const { request, baseUrl, opts, defer } = context;
-    if (!isSameOrigin(request, baseUrl)) {
-        return privateJson({ error: "same-origin request required" }, { status: 403 });
-    }
-    const authz = await authorizeUiIdentity(request, baseUrl, opts.auth, "OAuth management", context.runtimeContext, opts.identity);
-    if (!authz.ok)
-        return authz.response;
-    let registry;
-    try {
-        validateAuthPermissions(authz, opts.registry);
-        registry = opts.registry.scoped({
-            connectorIds: authz.connectorIds,
-            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
-            ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
-            ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
-        });
-    }
-    catch (error) {
-        return privateJson({ error: msg(error) }, { status: 403 });
-    }
-    const connector = registry.getConnector(connectorId);
-    if (!connector?.disconnectAuth || !connector.startAuth) {
-        return privateJson({ error: "unknown OAuth connector" }, { status: 404 });
-    }
-    if (!mayManageConnector(authz, connector))
-        return privateJson({ error: "credential management is not permitted" }, { status: 403 });
-    if (connector.authScope === "personal" && !authz.principalKey) {
-        return privateJson({ error: "forbidden" }, { status: 403 });
-    }
-    if (request.method !== "DELETE" && request.method !== "POST") {
-        return privateJson({ error: "method not allowed" }, { status: 405 });
-    }
-    const requestScope = {};
-    const ctx = registry.contextFor(connectorId, baseUrl, requestScope);
-    try {
-        let result;
-        let operationError;
-        try {
-            if (request.method === "DELETE") {
-                await connector.disconnectAuth(ctx);
-            }
-            else {
-                result = await connector.startAuth(ctx, { force: true });
-                if (result.authorizationUrl) {
-                    await registry.bindOAuthHandoff(connectorId, result.authorizationUrl);
-                }
-            }
+import { authorizedPerson, refuse, serveOperator, visibleRegistry, } from "./operator.js";
+import { mayManageConnector, isSameOrigin, msg, privateJson, } from "./shared.js";
+function oauthManagementRequest(context, connectorId) {
+    const { request, baseUrl, defer } = context;
+    return Effect.gen(function* () {
+        if (!isSameOrigin(request, baseUrl)) {
+            return yield* refuse("same-origin request required", 403);
         }
-        catch (error) {
-            operationError = error;
+        const authz = yield* authorizedPerson(context, "OAuth management");
+        const registry = yield* visibleRegistry(context, authz);
+        const connector = registry.getConnector(connectorId);
+        const disconnectAuth = connector?.disconnectAuth?.bind(connector);
+        const startAuth = connector?.startAuth?.bind(connector);
+        if (!connector || !disconnectAuth || !startAuth) {
+            return yield* refuse("unknown OAuth connector", 404);
         }
-        // The old grant and its cached catalog are invalid after either operation,
-        // including a partially failed physical cleanup whose epoch fence succeeded.
-        try {
-            await registry.invalidateStored(connectorId);
+        if (!mayManageConnector(authz, connector)) {
+            return yield* refuse("credential management is not permitted", 403);
         }
-        catch (error) {
-            operationError ??= error;
+        if (connector.authScope === "personal" && !authz.principalKey) {
+            return yield* refuse("forbidden", 403);
         }
-        if (operationError) {
-            return privateJson({ error: msg(operationError) }, { status: 400 });
+        const disconnecting = request.method === "DELETE";
+        if (!disconnecting && request.method !== "POST") {
+            return yield* refuse("method not allowed", 405);
         }
-        if (request.method === "DELETE") {
+        const ctx = registry.contextFor(connectorId, baseUrl, {});
+        // The connector scope this request opened ends with it, however it ends.
+        yield* Effect.addFinalizer(() => closeScope(connector, ctx, defer));
+        const operation = yield* Effect.result(Effect.tryPromise({
+            try: async () => {
+                if (disconnecting) {
+                    await disconnectAuth(ctx);
+                    return undefined;
+                }
+                const started = await startAuth(ctx, { force: true });
+                if (started.authorizationUrl) {
+                    await registry.bindOAuthHandoff(connectorId, started.authorizationUrl);
+                }
+                return started;
+            },
+            catch: (error) => error,
+        }));
+        // The old grant and its cached catalog are invalid after either operation,
+        // including a partially failed physical cleanup whose epoch fence succeeded.
+        const invalidated = yield* Effect.result(Effect.tryPromise({
+            try: () => registry.invalidateStored(connectorId),
+            catch: (error) => error,
+        }));
+        // A Result, not a caught value, decides whether it failed: a hook that
+        // rejects with no reason at all still failed.
+        if (Result.isFailure(operation))
+            return yield* refuse(msg(operation.failure), 400);
+        if (Result.isFailure(invalidated))
+            return yield* refuse(msg(invalidated.failure), 400);
+        const result = operation.success;
+        if (!result) {
             return new Response(null, {
                 status: 204,
                 headers: {
@@ -77,23 +70,18 @@ async function handleOAuthManagementRequest(context, connectorId) {
             ? result.authorizationUrl
             : undefined;
         if (result.state === "error") {
-            return privateJson({ error: result.message || "OAuth authorization could not start" }, { status: 502 });
+            return yield* refuse(result.message || "OAuth authorization could not start", 502);
         }
         if (result.state === "auth_required" && !authorizationUrl) {
-            return privateJson({
-                error: result.message ||
-                    "OAuth authorization requires consent but no safe URL is available",
-            }, { status: 502 });
+            return yield* refuse(result.message ||
+                "OAuth authorization requires consent but no safe URL is available", 502);
         }
         return privateJson({
             state: result.state,
             ...(result.message ? { message: result.message } : {}),
             ...(authorizationUrl ? { authorizationUrl } : {}),
         });
-    }
-    finally {
-        await closeConnectorScope(connector, ctx, defer);
-    }
+    }).pipe(Effect.scoped);
 }
 export async function routeOAuthManagement(context) {
     const match = /^\/ui\/oauth\/([a-z0-9_-]+)$/.exec(context.path);
@@ -105,5 +93,6 @@ export async function routeOAuthManagement(context) {
     if (context.request.method === "OPTIONS") {
         return privateJson({ error: "method not allowed" }, { status: 405 });
     }
-    return handleOAuthManagementRequest(context, connectorId);
+    // No signal: a disconnect that has started runs through to its invalidation.
+    return serveOperator(oauthManagementRequest(context, connectorId));
 }

package/dist/routes/oauth.js

@@ -1,5 +1,7 @@
+import { Effect } from "effect";
 import { oauthValueStorageKey } from "../auth/downstream-oauth.js";
 import { resolveBranding } from "../branding.js";
+import { oauthCallbackOutcome, providerErrorReason, } from "../oauth-callback-outcome.js";
 import { authorizeUiIdentity, mayManageConnector, validateAuthPermissions, loggableValue, msg, } from "./shared.js";
 function escapeHtml(value) {
     return value
@@ -8,8 +10,14 @@ function escapeHtml(value) {
         .replaceAll(">", ">")
         .replaceAll('"', """);
 }
-/** `body` is escaped — callback params and error messages are attacker-influenced. */
-function html(body, status = 200, branding, hasUi = false) {
+/**
+ * The callback's one page. It renders a reason from a closed set and that
+ * reason's fixed copy, so nothing the request carried — the provider's `error`
+ * parameter, an exchange failure's message — can reach the body. Escaping
+ * stays anyway: branding and the configured connector id are still strings.
+ */
+function html(reason, branding, hasUi = false, connectorId) {
+    const outcome = oauthCallbackOutcome(reason, connectorId);
     const brand = resolveBranding(branding);
     const title = brand.pageTitle;
     const owner = brand.ownerName
@@ -52,7 +60,10 @@ function html(body, status = 200, branding, hasUi = false) {
   a { color: inherit; text-decoration: underline; text-decoration-thickness: 1.5px;
     text-underline-offset: .22em; }
   a:hover { text-decoration-color: transparent; }
-  a:focus-visible { outline: 1px solid #000; outline-offset: 2px; }
+  a:focus-visible, summary:focus-visible { outline: 1px solid #000; outline-offset: 2px; }
+  summary { cursor: pointer; }
+  pre { font: 13px/1.5 ui-monospace, Menlo, Consolas, monospace; margin: .75rem 0 0;
+    padding: .75rem; white-space: pre-wrap; border: 1px solid #000; user-select: all; }
   @media (max-width: 36.99rem) {
     .grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
     .product { grid-column: 2; }
@@ -66,15 +77,16 @@ function html(body, status = 200, branding, hasUi = false) {
     ${owner}
     ${product}
   </header>
-  <main class="shell grid">
+  <main class="shell grid" data-oauth-callback="${outcome.reason}">
     <h1>Connection status</h1>
     <div class="copy">
-      <p>${escapeHtml(body)}</p>
+      <p>${escapeHtml(outcome.message)}</p>
+      ${outcome.fixPrompt ? `<details><summary>Fix prompt for a coding agent</summary><pre>${escapeHtml(outcome.fixPrompt)}</pre></details>` : ""}
       ${hasUi ? `<p><a href="/">Return to ${escapeHtml(brand.productName)}</a></p>` : ""}
     </div>
   </main>
 </body>
-</html>`, { status, headers: { "Content-Type": "text/html; charset=utf-8" } });
+</html>`, { status: outcome.status, headers: { "Content-Type": "text/html; charset=utf-8" } });
 }
 /**
  * Pay the storage read a real downstream-OAuth refusal pays, on the refusal
@@ -107,16 +119,29 @@ async function equalizeRefusalCost(context) {
         // Deliberately ignored — see above.
     }
 }
-export async function routeOAuthCallback(context) {
+/**
+ * The callback route as a step of the request's fiber, and the one step that
+ * the request's signal does not interrupt.
+ *
+ * An authorization code is single-use. Once a browser has delivered one, the
+ * handoff it consumes, the exchange, and the catalog invalidation after it are
+ * one commitment: abandoned halfway, a connector could hold fresh tokens
+ * behind a catalog still cached as unauthorized, or a consumed handoff with no
+ * exchange behind it. A caller that hangs up mid-exchange loses only the page.
+ */
+export function routeOAuthCallback(context) {
+    if (!context.path.startsWith("/oauth/callback/"))
+        return Effect.succeed(null);
+    return Effect.uninterruptible(Effect.promise(() => finishOAuthCallback(context)));
+}
+async function finishOAuthCallback(context) {
     const { path, url, baseUrl, opts } = context;
-    if (!path.startsWith("/oauth/callback/"))
-        return null;
     const error = url.searchParams.get("error");
     if (error)
-        return html(`Authorization denied: ${error}`, 400, opts.branding, Boolean(opts.ui));
+        return html(providerErrorReason(error), opts.branding, Boolean(opts.ui));
     const code = url.searchParams.get("code");
     if (!code)
-        return html("Missing authorization code.", 400, opts.branding, Boolean(opts.ui));
+        return html("invalid_callback", opts.branding, Boolean(opts.ui));
     const id = path.slice("/oauth/callback/".length);
     const state = url.searchParams.get("state");
     const callbackTarget = await opts.registry.oauthCallbackView(id, state);
@@ -130,8 +155,7 @@ export async function routeOAuthCallback(context) {
     const connectorContext = callbackRegistry
         ? callbackRegistry.contextFor(id, baseUrl)
         : opts.registry.contextFor(id, baseUrl);
-    const refused = () => html("Authorization could not be completed. Re-run authorization from " +
-        "connecta and try again.", 400, opts.branding, Boolean(opts.ui));
+    const refused = () => html("invalid_callback", opts.branding, Boolean(opts.ui));
     if (!connector || !connector.finishAuth) {
         await equalizeRefusalCost(connectorContext);
         return refused();
@@ -196,15 +220,19 @@ export async function routeOAuthCallback(context) {
             opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
                 `${loggableValue(id)} with 500: its principal handoff could not be ` +
                 `consumed (${loggableValue(msg(err))}). No authorization code was exchanged.`);
-            return html("Authorization could not be completed.", 500, opts.branding, Boolean(opts.ui));
+            return html("handoff_failed", opts.branding, Boolean(opts.ui), id);
         }
     }
     try {
         await connector.finishAuth(code, connectorContext, url.searchParams);
         await callbackRegistry.invalidateStored(id);
-        return html(`Connected "${id}". You can close this window.`, 200, opts.branding, Boolean(opts.ui));
+        return html("connected", opts.branding, Boolean(opts.ui), id);
     }
     catch (err) {
-        return html(`Authorization failed: ${msg(err)}`, 500, opts.branding, Boolean(opts.ui));
+        // The page names the reason and nothing else; what the exchange threw can
+        // quote a token endpoint's body, so it goes only to the operator log.
+        opts.logger.warn(`[connecta] OAuth callback for connector ${loggableValue(id)} failed ` +
+            `with 500: the authorization code exchange threw ${loggableValue(msg(err))}.`);
+        return html("exchange_failed", opts.branding, Boolean(opts.ui), id);
     }
 }