@agent-native/core 0.163.3 → 0.164.1

package/dist/server/core-routes-plugin.js

@@ -1,4 +1,4 @@
-import { assertBodySize, defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getHeader, getCookie, setCookie, deleteCookie, getRequestURL, getRequestIP, readRawBody, } from "h3";
+import { assertBodySize, defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getHeader, getRequestURL, getRequestIP, readRawBody, } from "h3";
 import { readMultipartFormData } from "h3";
 import { DEFAULT_MODEL } from "../agent/default-model.js";
 import { registerBuiltinEngines } from "../agent/engine/builtin.js";
@@ -21,9 +21,10 @@ import { registerBuiltinNotificationChannels } from "../notifications/channels.j
 import { createNotificationsHandler } from "../notifications/routes.js";
 import { getOrgContext } from "../org/context.js";
 import { createProgressHandler } from "../progress/routes.js";
+import { decryptSecretValue, encryptSecretValue } from "../secrets/crypto.js";
 import { registerFrameworkSecrets } from "../secrets/register-framework-secrets.js";
 import { createListSecretsHandler, createWriteSecretHandler, createTestSecretHandler, createAdHocSecretHandler, } from "../secrets/routes.js";
-import { getSetting, putSetting, deleteSetting } from "../settings/store.js";
+import { getSetting, putSetting, deleteSetting, mutateSetting, listSettingsByPrefix, } from "../settings/store.js";
 import { getUserSetting, putUserSetting, deleteUserSetting, } from "../settings/user-settings.js";
 import { ANALYTICS_CLIENT_PLATFORM_PROPERTY } from "../shared/analytics-platform.js";
 import { EMPTY_SPECULATION_RULES, resolveSsrCacheHeaders, } from "../shared/cache-control.js";
@@ -41,7 +42,8 @@ import { readAnalyticsClientPlatformHeader, readBrowserSessionIdHeader, } from "
 import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
 import { getAppName } from "./app-name.js";
 import { getSession } from "./auth.js";
-import { BUILDER_CONNECT_PARAM, BUILDER_CONNECT_OWNER_COOKIE, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, BUILDER_STATE_PARAM, appendBuilderConnectToken, builderConnectTrackingProperties, buildBuilderCliAuthUrl, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderCliAuthCallbackOriginForEvent, getBuilderBrowserOriginForEvent, resolveBuilderCallbackReturnUrl, getBuilderBrowserStatusForEvent, resolveBuilderBranchProjectId, resolveBuilderPreviewRelayParentOrigin, resolveBuilderPreviewRelayTargetOrigin, resolveSafePreviewUrl, runBuilderAgent, signBuilderCallbackState, signBuilderPreviewRelayState, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, verifyBuilderCallbackStateAndGetOwner, signBuilderConnectToken, } from "./builder-browser.js";
+import { BUILDER_CONNECT_PARAM, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, appendBuilderConnectToken, builderConnectTrackingProperties, createBuilderConnectState, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderBrowserOriginForEvent, getBuilderBrowserStatusForEvent, isBuilderConnectCallbackUrlAllowed, isSignedBuilderConnectState, resolveBuilderBranchProjectId, resolveBuilderConnectCallbackUrl, resolveBuilderPreviewRelayParentOrigin, runBuilderAgent, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, } from "./builder-browser.js";
+import { BUILDER_OAUTH_SCOPE, deleteBuilderOAuthSession, finishBuilderOAuthAuthorization, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, startBuilderOAuthAuthorization, } from "./builder-oauth.js";
 import { captureError, registerErrorCaptureProvider } from "./capture-error.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { canUseDeployCredentialFallbackForRequest, prefetchSecrets, readDeployCredentialEnv, resolveSecret, } from "./credential-provider.js";
@@ -601,37 +603,68 @@ async function trackBuilderLifecycle(event, name, userEmail, properties = {}) {
         ...properties,
     }, { userId: userEmail });
 }
-function getBuilderConnectOwnerCookiePath() {
-    return getAppBasePath() || "/";
+function isAgentNativeAnonymousOwner(email) {
+    return /^anon-[^@]+@agent-native\.com$/i.test(email ?? "");
 }
-function readBuilderConnectOwnerCookie(event) {
-    return verifyBuilderConnectTokenAndGetOwner(getCookie(event, BUILDER_CONNECT_OWNER_COOKIE));
+export function isBuilderConnectCallbackOwner(pendingOwner, sessionOwner) {
+    return Boolean(sessionOwner && sessionOwner === pendingOwner);
 }
-function setBuilderConnectOwnerCookie(event, ownerEmail) {
-    setCookie(event, BUILDER_CONNECT_OWNER_COOKIE, signBuilderConnectToken(ownerEmail), {
-        httpOnly: true,
-        sameSite: "lax",
-        secure: getOrigin(event).startsWith("https://"),
-        path: getBuilderConnectOwnerCookiePath(),
-        maxAge: 10 * 60,
-    });
+export async function consumeBuilderConnectPendingState(state, dependencies = { mutate: mutateSetting, remove: deleteSetting }) {
+    if (!isSignedBuilderConnectState(state))
+        return null;
+    const pendingKey = `builder-connect-pending:${state}`;
+    try {
+        const pending = await dependencies.mutate(pendingKey, (current) => {
+            if (!current || current.consumed === true) {
+                throw new Error("Builder connect flow is missing or consumed.");
+            }
+            return { ...current, consumed: true, consumedAt: Date.now() };
+        });
+        await dependencies.remove(pendingKey).catch(() => false); // coercion-ok: row already marked consumed; delete is cleanup
+        return pending;
+    }
+    catch {
+        // coercion-ok: missing, consumed, or unreadable pending rows all deny the
+        // callback the same way so attackers cannot probe storage errors.
+        return null;
+    }
 }
-function clearBuilderConnectOwnerCookie(event) {
-    deleteCookie(event, BUILDER_CONNECT_OWNER_COOKIE, {
-        path: getBuilderConnectOwnerCookiePath(),
-    });
+export async function readBuilderConnectPendingState(state, read = getSetting) {
+    if (!isSignedBuilderConnectState(state))
+        return null;
+    try {
+        const pending = await read(`builder-connect-pending:${state}`);
+        if (!pending || pending.consumed === true)
+            return null;
+        return pending;
+    }
+    catch {
+        // coercion-ok: missing, consumed, or unreadable pending rows all deny the
+        // callback the same way so attackers cannot probe storage errors.
+        return null;
+    }
 }
-function isAgentNativeAnonymousOwner(email) {
-    return /^anon-[^@]+@agent-native\.com$/i.test(email ?? "");
+const BUILDER_CONNECT_PENDING_PREFIX = "builder-connect-pending:";
+export async function purgeExpiredBuilderConnectPendingStates(now = Date.now(), dependencies = { list: listSettingsByPrefix, remove: deleteSetting }) {
+    const rows = await dependencies.list(BUILDER_CONNECT_PENDING_PREFIX);
+    let deleted = 0;
+    for (const row of rows) {
+        const expiresAt = row.value.expiresAt;
+        if (typeof expiresAt === "number" && expiresAt > now)
+            continue;
+        const removed = await dependencies.remove(row.key).catch(() => false); // coercion-ok: expired pending cleanup is best-effort; a failed delete is retried on the next connect
+        if (removed)
+            deleted += 1;
+    }
+    return deleted;
 }
 export async function resolveBuilderOwnerContextForRequest(event, options = {}, mode) {
     const searchParams = getFrameworkRouteRequestUrl(event).searchParams;
+    // OAuth callback is session-bound; only the connect trampoline still uses a
+    // signed connect token for anonymous docs/app popup ownership.
     const signedOwner = mode === "connect"
         ? verifyBuilderConnectTokenAndGetOwner(searchParams.get(BUILDER_CONNECT_PARAM))
-        : mode === "callback"
-            ? verifyBuilderCallbackStateAndGetOwner(searchParams.get(BUILDER_STATE_PARAM))
-            : null;
-    const cookieOwner = mode === "callback" ? readBuilderConnectOwnerCookie(event) : null;
+        : null;
     const session = await (options.getSessionForEvent ?? getSession)(event).catch(() => null);
     if (session?.email) {
         if (signedOwner &&
@@ -656,9 +689,6 @@ export async function resolveBuilderOwnerContextForRequest(event, options = {},
             anonymous: isAgentNativeAnonymousOwner(signedOwner),
         };
     }
-    if (cookieOwner) {
-        return { email: cookieOwner, session: null, anonymous: false };
-    }
     const anonymousOwner = await options.anonymousOwner?.(event);
     if (anonymousOwner) {
         return { email: anonymousOwner, session: null, anonymous: true };
@@ -1417,32 +1447,17 @@ export function createCoreRoutesPlugin(options = {}) {
             mountDbAdminRoutes(nitroApp, { routePrefix: P });
             const resolveBuilderOwnerContext = async (event, mode) => resolveBuilderOwnerContextForRequest(event, { anonymousOwner: options.anonymousOwner }, mode);
             const builderStatusHandler = defineEventHandler(async (event) => {
+                setResponseHeader(event, "Cache-Control", "no-store");
                 const envStatus = getBuilderBrowserStatusForEvent(event);
                 const ownerContext = await resolveBuilderOwnerContext(event);
                 const userEmail = ownerContext.email;
                 const withConnectToken = (status) => {
                     if (!userEmail)
                         return status;
-                    const previewOrigin = getBuilderBrowserOriginForEvent(event);
-                    const callbackOrigin = getBuilderCliAuthCallbackOriginForEvent(event);
-                    const statusWithConnectToken = {
+                    return {
                         ...status,
                         connectUrl: appendBuilderConnectToken(status.connectUrl, userEmail),
                     };
-                    // Direct cli-auth only works when the callback lands on the same
-                    // deployment that minted the signed state. Builder/Fusion previews
-                    // often need a gateway callback origin; in that case use the
-                    // /builder/connect trampoline so it can write the pending-connect
-                    // row that the gateway callback validates against.
-                    if (previewOrigin.replace(/\/+$/, "") !==
-                        callbackOrigin.replace(/\/+$/, "")) {
-                        return statusWithConnectToken;
-                    }
-                    const cliAuthUrl = buildBuilderCliAuthUrl(callbackOrigin, signBuilderCallbackState(userEmail), { previewOrigin });
-                    return {
-                        ...statusWithConnectToken,
-                        cliAuthUrl,
-                    };
                 };
                 // Pass the user's active orgId so status reads can fall back to
                 // org-scoped credentials and branch project IDs. Without it, an
@@ -1504,6 +1519,77 @@ export function createCoreRoutesPlugin(options = {}) {
                     catch {
                         // settings store unavailable — fall through
                     }
+                    if (userEmail) {
+                        let oauthAccess = null;
+                        let hasOAuthCustody = false;
+                        try {
+                            hasOAuthCustody = await hasBuilderOAuthSession(userEmail);
+                        }
+                        catch {
+                            return withConnectToken({
+                                ...requestStatus,
+                                configured: false,
+                                credentialSource: "user",
+                                privateKeyConfigured: false,
+                                publicKeyConfigured: false,
+                                connectError: {
+                                    message: "Builder connection status could not be read. Retry in a moment.",
+                                    at: Date.now(),
+                                },
+                            });
+                        }
+                        if (hasOAuthCustody) {
+                            try {
+                                oauthAccess = await resolveBuilderOAuthRequestAccess({
+                                    ownerEmail: userEmail,
+                                    requiredScope: BUILDER_OAUTH_SCOPE,
+                                });
+                            }
+                            catch {
+                                oauthAccess = null;
+                            }
+                        }
+                        if (oauthAccess) {
+                            let privateKeyConfigured = false;
+                            let publicKeyConfigured = false;
+                            let orgName = "Builder OAuth";
+                            try {
+                                const { resolveBuilderCredentials } = await import("./credential-provider.js");
+                                const creds = await resolveBuilderCredentials();
+                                privateKeyConfigured = !!creds.privateKey;
+                                publicKeyConfigured = !!creds.publicKey;
+                                if (typeof creds.orgName === "string" && creds.orgName) {
+                                    orgName = creds.orgName;
+                                }
+                            }
+                            catch {
+                                // coercion-ok: OAuth already proves the chat gateway; missing
+                                // key flags only hide code-change send until secrets are readable.
+                            }
+                            return withConnectToken({
+                                ...requestStatus,
+                                configured: true,
+                                credentialSource: "user",
+                                privateKeyConfigured,
+                                publicKeyConfigured,
+                                orgName,
+                                spaces: [],
+                            });
+                        }
+                        if (hasOAuthCustody) {
+                            return withConnectToken({
+                                ...requestStatus,
+                                configured: false,
+                                credentialSource: "user",
+                                privateKeyConfigured: false,
+                                publicKeyConfigured: false,
+                                connectError: {
+                                    message: "Builder access expired. Reconnect Builder.io.",
+                                    at: Date.now(),
+                                },
+                            });
+                        }
+                    }
                     // Read request-scoped Builder credentials first; deploy env is only
                     // the fallback. This keeps a root/local BUILDER_PRIVATE_KEY from
                     // blocking a user from connecting their own Builder account.
@@ -1530,7 +1616,7 @@ export function createCoreRoutesPlugin(options = {}) {
                                 isFreeAccount: undefined,
                                 credentialSource: credentialSource ?? undefined,
                                 // Surface durable credential rejection separately from
-                                // one-shot cli-auth callback failures. The reconnect UI keeps
+                                // one-shot OAuth callback failures. The reconnect UI keeps
                                 // polling through authError while the user chooses a new
                                 // Builder space; connectError means the active callback itself
                                 // failed and should stop the flow.
@@ -1630,7 +1716,7 @@ export function createCoreRoutesPlugin(options = {}) {
             });
             mountBuilderStatusRouteAliases((path, handler) => getH3App(nitroApp).use(path, handler), P, builderStatusHandler);
             // How long a pending-connect row is valid. Must be long enough for
-            // the user to complete the Builder CLI-auth flow, but short enough
+            // the user to complete the Builder OAuth flow, but short enough
             // that a stale row from an abandoned attempt doesn't accept a new
             // callback minutes later.
             const BUILDER_CONNECT_PENDING_TTL_MS = 10 * 60 * 1000; // 10 min
@@ -1667,7 +1753,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 // session-bound so the worst case degrades to the prior behavior.
                 return true;
             }
-            // Lightweight 302 to the Builder CLI-auth URL. Lets clients do
+            // Lightweight 302 to Builder's authorization endpoint. Lets clients do
             // `window.open('/_agent-native/builder/connect', '_blank')` synchronously
             // inside a click handler, avoiding the popup-blocker downgrade that
             // happens when an await sits before window.open.
@@ -1684,13 +1770,12 @@ export function createCoreRoutesPlugin(options = {}) {
             //      request with the navigation context. We allow `same-origin` or
             //      `none` (typed/bookmark/extension); cross-site / same-site without
             //      a valid connect token are rejected.
-            //   3. Pending row keyed by session email + bound nonce — the callback
+            //   3. Pending row keyed by signed OAuth state — the callback
             //      requires both a valid session and a one-time row that this
             //      handler wrote during the same flow. Without the same-origin
             //      gate or connect token above, an attacker could prime the row from
-            //      cross-site and then trick the victim into hitting a callback URL
-            //      with attacker-controlled p-key/api-key, hijacking the victim's
-            //      account.
+            //      cross-site and then trick the victim into completing an
+            //      attacker-initiated authorization flow.
             getH3App(nitroApp).use(`${P}/builder/connect`, defineEventHandler(async (event) => {
                 const ownerContext = await resolveBuilderOwnerContext(event, "connect");
                 const ownerEmail = ownerContext.email;
@@ -1698,6 +1783,16 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseStatus(event, 401);
                     return { error: "Authentication required" };
                 }
+                if (ownerContext.anonymous ||
+                    isAgentNativeAnonymousOwner(ownerEmail)) {
+                    setResponseStatus(event, 401);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage("Sign in to connect Builder.", {
+                        title: "Sign in required",
+                        body: "Builder OAuth is tied to a signed-in account. Sign in, then try Connect Builder again.",
+                        parentOrigin: getBuilderBrowserOriginForEvent(event),
+                    });
+                }
                 const requestUrl = getFrameworkRouteRequestUrl(event);
                 const connectToken = requestUrl.searchParams.get(BUILDER_CONNECT_PARAM);
                 const connectTokenOwner = verifyBuilderConnectTokenAndGetOwner(connectToken);
@@ -1751,65 +1846,42 @@ export function createCoreRoutesPlugin(options = {}) {
                 catch {
                     // No prior error row — fine
                 }
-                const previewOrigin = getBuilderBrowserOriginForEvent(event).replace(/\/+$/, "");
-                const callbackOrigin = getBuilderCliAuthCallbackOriginForEvent(event).replace(/\/+$/, "");
-                let relay;
-                if (previewOrigin !== callbackOrigin) {
-                    try {
-                        relay = signBuilderPreviewRelayState({
-                            ownerEmail,
-                            targetOrigin: resolveBuilderPreviewRelayTargetOrigin(previewOrigin),
-                            basePath: getAppBasePath(),
-                        });
-                    }
-                    catch (err) {
-                        const msg = err instanceof Error
-                            ? err.message
-                            : "Builder preview relay is not configured.";
-                        setResponseStatus(event, 503);
-                        setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                        return createBuilderBrowserCallbackErrorPage(msg, {
-                            title: "Builder preview connection isn't configured",
-                            body: "This preview needs its secure Builder callback relay configured before authorization can start.",
-                            closeHint: "Close this popup and ask the preview owner to finish Builder relay setup.",
-                            parentOrigin: previewOrigin,
-                        });
-                    }
-                }
-                let pendingOrgId = null;
-                let pendingRole = null;
-                if (!ownerContext.anonymous) {
-                    try {
-                        const orgContext = await getOrgContext(event);
-                        pendingOrgId = orgContext.orgId ?? null;
-                        pendingRole = orgContext.role ?? null;
-                    }
-                    catch {
-                        // The pending owner remains user-scoped when org context is absent.
-                    }
+                const callbackUrl = resolveBuilderConnectCallbackUrl(event);
+                if (!callbackUrl ||
+                    !isBuilderConnectCallbackUrlAllowed(callbackUrl, event)) {
+                    const msg = "This deployment cannot start Builder OAuth from the current origin.";
+                    setResponseStatus(event, 400);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(msg, {
+                        title: "Builder connection is unavailable here",
+                        body: "Open this app on its public HTTPS URL, then try again.",
+                        parentOrigin: getBuilderBrowserOriginForEvent(event),
+                    });
                 }
-                // Store a short-lived pending row. If the DB is unavailable we
-                // surface a popup-renderable error page that signals the parent
-                // via BroadcastChannel, rather than letting the popup show raw
-                // JSON and the parent poll for 5 minutes.
+                const state = createBuilderConnectState();
+                // The standard OAuth client discovers Builder's protected-resource
+                // metadata, dynamically registers, and creates its S256 verifier.
+                // Persist that opaque protocol state encrypted and consume it once.
+                let oauthFlow;
+                let authorizationUrl;
                 try {
-                    if (relay) {
-                        await putSetting(builderRelayPendingKey(relay.payload.flowId), {
-                            ownerEmail,
-                            orgId: pendingOrgId,
-                            role: pendingRole,
-                            targetOrigin: relay.payload.targetOrigin,
-                            basePath: relay.payload.basePath,
-                            expiresAt: relay.payload.exp,
-                            tracking: connectTracking,
-                        });
-                    }
-                    else {
-                        await putSetting(`builder-pending-connect:${ownerEmail}`, {
-                            expiresAt: Date.now() + BUILDER_CONNECT_PENDING_TTL_MS,
-                            tracking: connectTracking,
-                        });
-                    }
+                    const started = await startBuilderOAuthAuthorization({
+                        ownerEmail,
+                        redirectUri: callbackUrl,
+                        state,
+                    });
+                    oauthFlow = started.pending;
+                    authorizationUrl = started.authorizationUrl;
+                    await putSetting(`builder-connect-pending:${state}`, {
+                        ownerEmail,
+                        orgId: null,
+                        role: null,
+                        encryptedOAuthFlow: encryptSecretValue(JSON.stringify(oauthFlow)),
+                        redirectUri: callbackUrl,
+                        expiresAt: Date.now() + BUILDER_CONNECT_PENDING_TTL_MS,
+                        tracking: connectTracking,
+                    });
+                    await purgeExpiredBuilderConnectPendingStates().catch(() => 0); // coercion-ok: connect already persisted the new pending row; purge of abandoned rows must not fail OAuth start
                 }
                 catch (err) {
                     await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
@@ -1836,18 +1908,9 @@ export function createCoreRoutesPlugin(options = {}) {
                     stage: "connect",
                     connect_token_owner_matches_context: !connectTokenOwner || connectTokenOwner === ownerEmail,
                 });
-                setBuilderConnectOwnerCookie(event, ownerEmail);
-                // The primary UI now opens the signed Builder /cli-auth URL directly
-                // from /builder/status. Keep this legacy trampoline working for older
-                // clients, but still send it to Builder immediately and include signed
-                // callback state so the callback does not depend on popup cookies.
-                const cliAuthUrl = buildBuilderCliAuthUrl(callbackOrigin, signBuilderCallbackState(ownerEmail), {
-                    previewOrigin,
-                    relayState: relay?.state,
-                    tracking: connectTracking,
-                });
                 setResponseStatus(event, 302);
-                setResponseHeader(event, "Location", cliAuthUrl);
+                setResponseHeader(event, "Cache-Control", "no-store");
+                setResponseHeader(event, "Location", authorizationUrl);
                 return "";
             }));
             getH3App(nitroApp).use(`${P}/builder/run`, defineEventHandler(async (event) => {
@@ -2017,6 +2080,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 // propagation even though the second hop carries secrets only in
                 // its authenticated POST body.
                 setResponseHeader(event, "Cache-Control", "no-store");
+                setResponseHeader(event, "Pragma", "no-cache");
                 setResponseHeader(event, "Referrer-Policy", "no-referrer");
                 const requestUrl = getFrameworkRouteRequestUrl(event);
                 const relayStateRaw = requestUrl.searchParams.get(BUILDER_RELAY_STATE_PARAM);
@@ -2085,301 +2149,104 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                     return createBuilderBrowserCallbackPage(`${relayParentOrigin}${relayPayload.basePath || "/"}`, { parentOrigin: relayParentOrigin });
                 }
-                // A real session or a template-approved anonymous owner is required;
-                // the pending-row check below (combined with the same-origin gate on
-                // /builder/connect) blocks CSRF and callback replay.
-                const ownerContext = await resolveBuilderOwnerContext(event, "callback");
-                const ownerEmail = ownerContext.email;
-                // Diagnostic: log the resolver's inputs for debugging "No active
-                // connect flow found" reports. Reveals session-vs-state owner
-                // mismatches and missing/forged _an_state without leaking the
-                // signed token itself.
-                try {
-                    const debugSearch = getFrameworkRouteRequestUrl(event).searchParams;
-                    const stateRaw = debugSearch.get(BUILDER_STATE_PARAM);
-                    const stateOwnerProbe = verifyBuilderCallbackStateAndGetOwner(stateRaw);
-                    const session = await getSession(event).catch(() => null);
-                    console.log(`[builder-callback] resolved-owner=${ownerEmail ?? "(none)"} session-email=${session?.email ?? "(none)"} state-owner=${stateOwnerProbe ?? "(none)"} state-present=${Boolean(stateRaw)} anon=${ownerContext.anonymous} host=${getHeader(event, "host") ?? "(none)"} sec-fetch-site=${getHeader(event, "sec-fetch-site") ?? "(none)"} origin=${getHeader(event, "origin") ?? "(none)"} referer=${getHeader(event, "referer") ?? "(none)"}`);
-                }
-                catch {
-                    // Diagnostic logging is best-effort; do not break the callback.
-                }
-                if (!ownerEmail) {
-                    setResponseStatus(event, 401);
-                    return { error: "Authentication required" };
-                }
-                clearBuilderConnectOwnerCookie(event);
-                let connectTracking = getBuilderConnectTrackingParams(requestUrl.searchParams);
-                // postMessage from the callback success/error pages must target the
-                // original preview opener, not the callback server. On the fallback
-                // path the callback is served from the env-configured gateway while
-                // the opener lives on the preview origin. Three sources of opener
-                // origin, in priority order:
-                //   1. `_an_opener` — written into the callback URL's query by
-                //      buildBuilderCliAuthUrl when cli-auth's allow-list forced
-                //      preview_url onto the gateway. Survives Builder's redirect
-                //      verbatim (Builder preserves redirect_url's query string).
-                //   2. `preview-url` — Builder echoes the top-level preview_url back
-                //      as a query param on the callback. Reflects the gateway on
-                //      the fallback path, but matches the opener on the happy path.
-                //   3. The event's own origin — last-resort fallback.
-                const openerOriginFromQuery = requestUrl.searchParams.get(BUILDER_OPENER_PARAM);
-                const callbackParentOrigin = resolveSafePreviewUrl(openerOriginFromQuery, event) ||
-                    resolveSafePreviewUrl(requestUrl.searchParams.get("preview-url"), event) ||
-                    getBuilderBrowserOriginForEvent(event);
-                const callbackStateOwner = verifyBuilderCallbackStateAndGetOwner(requestUrl.searchParams.get(BUILDER_STATE_PARAM));
-                const hasValidCallbackState = callbackStateOwner === ownerEmail;
-                // Verify either:
-                //   1. the signed callback state embedded in redirect_url by
-                //      /builder/status (primary flow), or
-                //   2. the server-side pending-connect row written by the legacy
-                //      /builder/connect trampoline.
-                //
-                // For the pending-row path, delete must succeed before we proceed;
-                // otherwise a DB blip
-                // leaves the row in place and the same callback URL can be
-                // replayed against the same session for up to 10 minutes (the
-                // TTL window). Treat a delete failure as a hard failure: the
-                // user retries, the next /builder/connect call rewrites the
-                // pending row.
-                let pendingValid = hasValidCallbackState;
-                let pendingError = null;
-                try {
-                    const pending = (await getSetting(`builder-pending-connect:${ownerEmail}`));
-                    if (pending?.tracking) {
-                        connectTracking = {
-                            signupSource: connectTracking.signupSource ?? pending.tracking.signupSource,
-                            agentNativeFlow: connectTracking.agentNativeFlow ??
-                                pending.tracking.agentNativeFlow,
-                            agentNativeConnectSource: connectTracking.agentNativeConnectSource ??
-                                pending.tracking.agentNativeConnectSource,
-                            agentNativeApp: connectTracking.agentNativeApp ??
-                                pending.tracking.agentNativeApp,
-                            agentNativeTemplate: connectTracking.agentNativeTemplate ??
-                                pending.tracking.agentNativeTemplate,
-                        };
-                    }
-                    if (pending &&
-                        typeof pending.expiresAt === "number" &&
-                        Date.now() < pending.expiresAt) {
-                        try {
-                            await deleteSetting(`builder-pending-connect:${ownerEmail}`);
-                            pendingValid = true;
-                        }
-                        catch (err) {
-                            if (!hasValidCallbackState) {
-                                pendingError =
-                                    "Could not consume pending-connect token (storage error). Please retry.";
-                                console.error("[builder] deleteSetting failed for pending-connect — refusing to proceed (replay risk):", err?.message ?? err);
-                            }
-                        }
-                    }
-                }
-                catch {
-                    // DB temporarily unavailable — treat as missing.
-                }
-                if (pendingError) {
-                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                        ...builderConnectTrackingProperties(connectTracking),
-                        reason: "pending_consume_storage_error",
-                        stage: "callback",
-                    });
-                    // Best-effort signal to the parent's poll loop, then render the
-                    // popup-friendly error page so the BroadcastChannel notify fires.
-                    await putSetting(`builder-connect-error:${ownerEmail}`, {
-                        message: pendingError,
-                        at: Date.now(),
-                    }).catch(() => { });
-                    setResponseStatus(event, 503);
-                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                    return createBuilderBrowserCallbackErrorPage(pendingError, {
-                        parentOrigin: callbackParentOrigin,
-                    });
-                }
-                if (!pendingValid) {
-                    // Diagnostic: log the exact reason pendingValid is false so we can
-                    // distinguish "state didn't validate" from "no pending row" in
-                    // production "No active connect flow found" reports.
-                    console.warn(`[builder-callback] pending-invalid owner=${ownerEmail} has-state-param=${Boolean(requestUrl.searchParams.get(BUILDER_STATE_PARAM))} state-validated=${hasValidCallbackState} pending-error=${pendingError ?? "(none)"}`);
-                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                        ...builderConnectTrackingProperties(connectTracking),
-                        reason: hasValidCallbackState
-                            ? "callback_state_unexpectedly_rejected"
-                            : "missing_pending_connect",
-                        stage: "callback",
-                        has_callback_state: Boolean(requestUrl.searchParams.get(BUILDER_STATE_PARAM)),
-                    });
-                    const msg = "No active connect flow found. Restart the Builder connect flow from Settings.";
-                    // Write an error signal so the polling loop in the parent tab
-                    // terminates quickly instead of waiting 5 minutes for the timeout.
-                    try {
+                const state = requestUrl.searchParams.get("state");
+                const parentOrigin = getBuilderBrowserOriginForEvent(event);
+                const fail = async (status, message, ownerEmail, reason, tracking = {}) => {
+                    if (ownerEmail) {
                         await putSetting(`builder-connect-error:${ownerEmail}`, {
-                            message: msg,
+                            message,
                             at: Date.now(),
+                        }).catch(() => { });
+                        await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                            ...builderConnectTrackingProperties(tracking),
+                            reason: reason ?? "callback_failed",
+                            stage: "callback",
                         });
                     }
-                    catch {
-                        // DB unavailable — parent will time out naturally.
-                    }
-                    setResponseStatus(event, 403);
+                    setResponseStatus(event, status);
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                    return createBuilderBrowserCallbackErrorPage(msg, {
-                        parentOrigin: callbackParentOrigin,
-                    });
-                }
-                const privateKey = requestUrl.searchParams.get("p-key");
-                const publicKey = requestUrl.searchParams.get("api-key");
-                if (!privateKey || !publicKey) {
-                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                        ...builderConnectTrackingProperties(connectTracking),
-                        reason: "missing_credentials",
-                        stage: "callback",
-                    });
-                    // Render the popup-friendly error page (and write a status row)
-                    // instead of bare JSON, so the parent tab's poll loop terminates
-                    // immediately via BroadcastChannel rather than hanging until the
-                    // 5-minute timeout.
-                    const msg = "Builder didn't return credentials. Restart the connect flow from settings.";
-                    await putSetting(`builder-connect-error:${ownerEmail}`, {
-                        message: msg,
-                        at: Date.now(),
-                    }).catch(() => { });
-                    setResponseStatus(event, 400);
-                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                    return createBuilderBrowserCallbackErrorPage(msg, {
-                        parentOrigin: callbackParentOrigin,
+                    return createBuilderBrowserCallbackErrorPage(message, {
+                        parentOrigin,
                     });
+                };
+                if (!state || !isSignedBuilderConnectState(state)) {
+                    return fail(403, "No active Builder connect flow found. Restart the connection from Settings.");
+                }
+                const pending = await readBuilderConnectPendingState(state);
+                if (!pending) {
+                    return fail(403, "No active Builder connect flow found. Restart the connection from Settings.");
+                }
+                const ownerEmail = typeof pending.ownerEmail === "string" ? pending.ownerEmail : null;
+                const tracking = pending.tracking && typeof pending.tracking === "object"
+                    ? pending.tracking
+                    : {};
+                const session = await getSession(event).catch(() => null); // coercion-ok: callback treats session read failure as unauthenticated
+                const expiresAt = typeof pending.expiresAt === "number" ? pending.expiresAt : 0;
+                const encryptedOAuthFlow = typeof pending.encryptedOAuthFlow === "string"
+                    ? pending.encryptedOAuthFlow
+                    : null;
+                const redirectUri = typeof pending.redirectUri === "string"
+                    ? pending.redirectUri
+                    : null;
+                const expectedRedirectUri = resolveBuilderConnectCallbackUrl(event);
+                if (!ownerEmail ||
+                    !isBuilderConnectCallbackOwner(ownerEmail, session?.email) ||
+                    Date.now() >= expiresAt ||
+                    !encryptedOAuthFlow ||
+                    !redirectUri ||
+                    !expectedRedirectUri ||
+                    redirectUri !== expectedRedirectUri ||
+                    !isBuilderConnectCallbackUrlAllowed(redirectUri, event)) {
+                    if (Date.now() >= expiresAt) {
+                        await deleteSetting(`builder-connect-pending:${state}`).catch(() => false); // coercion-ok: expired pending cleanup is best-effort; callback already failed verification
+                    }
+                    return fail(403, "Builder connect callback could not be verified. Restart the connection.", ownerEmail ?? undefined, "callback_verification_failed", tracking);
+                }
+                const consumed = await consumeBuilderConnectPendingState(state);
+                if (!consumed) {
+                    return fail(403, "No active Builder connect flow found. Restart the connection from Settings.", ownerEmail, "callback_verification_failed", tracking);
+                }
+                const denied = requestUrl.searchParams.get("error");
+                const code = requestUrl.searchParams.get("code");
+                const iss = requestUrl.searchParams.get("iss") ?? undefined;
+                if (denied || !code) {
+                    return fail(400, denied
+                        ? "Builder connection was cancelled."
+                        : "Builder did not return an authorization code.", ownerEmail, denied ? "authorization_denied" : "missing_code", tracking);
                 }
-                const userId = requestUrl.searchParams.get("user-id");
-                const orgName = requestUrl.searchParams.get("org-name");
-                const orgKind = requestUrl.searchParams.get("kind");
-                const subscription = requestUrl.searchParams.get("subscription");
-                const subscriptionLevel = requestUrl.searchParams.get("subscription-level");
-                const subscriptionName = requestUrl.searchParams.get("subscription-name");
-                const isEnterprise = parseBuilderCallbackBoolean(requestUrl.searchParams.get("is-enterprise"));
-                const isFreeAccount = parseBuilderCallbackBoolean(requestUrl.searchParams.get("is-free-account"));
-                // Store per-user in app_secrets so each user's Builder connection
-                // is independent. No more shared env vars that the last connector
-                // overwrites.
-                //
-                // Failure handling: a silent catch here (returning the success page
-                // anyway) was Midhun's bug on 2026-04-28 — popup said "yay", parent
-                // window polled `/builder/status` for 5 minutes seeing
-                // configured:false, never got a real error. Now we surface the
-                // failure two ways: (a) a settings row that the next /builder/status
-                // poll picks up, and (b) postMessage from the error page itself,
-                // wired into the popup HTML, so the parent stops polling immediately.
-                let writeError = null;
                 try {
-                    const { writeBuilderCredentials } = await import("./credential-provider.js");
-                    // Resolve the user's active org / role so the credentials land
-                    // at org scope when an owner/admin is connecting (everyone in
-                    // the org auto-resolves them on next chat call). Members and
-                    // users with no active org silently fall back to user scope.
-                    // Failure to read org context is non-fatal — we just keep the
-                    // legacy per-user behaviour for that connection.
-                    let orgId = null;
-                    let role = null;
-                    if (!ownerContext.anonymous) {
-                        try {
-                            const { getOrgContext } = await import("../org/context.js");
-                            const orgCtx = await getOrgContext(event);
-                            orgId = orgCtx.orgId ?? null;
-                            role = orgCtx.role ?? null;
-                        }
-                        catch {
-                            /* org module not present in this template — keep user scope */
-                        }
-                    }
-                    const target = await writeBuilderCredentials(ownerEmail, {
-                        privateKey,
-                        publicKey,
-                        userId,
-                        orgName,
-                        orgKind,
-                        subscription,
-                        subscriptionLevel,
-                        subscriptionName,
-                        isEnterprise,
-                        isFreeAccount,
-                    }, { orgId, role });
-                    console.log(`[builder-connect] wrote credentials email=${ownerEmail} requestOrgId=${orgId ?? "(none)"} role=${role ?? "(none)"} scope=${target.scope} scopeId=${target.scopeId}`);
-                }
-                catch (err) {
-                    writeError = err?.message ?? String(err);
-                    console.error("[builder] Failed to persist Builder credentials:", writeError);
-                }
-                if (writeError) {
-                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                        ...builderConnectTrackingProperties(connectTracking),
-                        reason: "credential_write_failed",
-                        stage: "callback",
-                    });
-                    // Best-effort signal to /builder/status. If putSetting also fails
-                    // (entire DB unreachable) the popup's postMessage still notifies
-                    // the parent. If both fail the parent times out at 5min as today.
-                    try {
-                        await putSetting(`builder-connect-error:${ownerEmail}`, {
-                            message: writeError,
-                            at: Date.now(),
-                        });
-                    }
-                    catch (settingsErr) {
-                        console.error("[builder] Couldn't even record connect-error to settings:", settingsErr?.message ?? settingsErr);
-                    }
-                    setResponseStatus(event, 500);
-                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                    return createBuilderBrowserCallbackErrorPage(writeError, {
-                        parentOrigin: callbackParentOrigin,
+                    const oauthFlow = JSON.parse(decryptSecretValue(encryptedOAuthFlow));
+                    await finishBuilderOAuthAuthorization({
+                        ownerEmail,
+                        code,
+                        iss,
+                        pending: oauthFlow,
                     });
                 }
-                // Clear any legacy disconnect flag and any prior connect-error row
-                // (so a successful retry doesn't surface the previous failure).
-                try {
-                    await deleteSetting("builder-disconnected");
-                }
                 catch {
-                    // DB not ready — proceed
+                    return fail(502, "Builder could not exchange the authorization code. Restart the connection.", ownerEmail, "code_exchange_failed", tracking);
                 }
                 try {
-                    await deleteSetting(`builder-connect-error:${ownerEmail}`);
+                    await Promise.all([
+                        deleteSetting("builder-disconnected").catch(() => false), // coercion-ok: best-effort cleanup after successful OAuth save
+                        deleteSetting(`builder-connect-error:${ownerEmail}`).catch(() => false),
+                    ]);
                 }
                 catch {
-                    // No prior error row — fine
+                    return fail(500, "Builder credentials could not be saved. Restart the connection.", ownerEmail, "credential_write_failed", tracking);
                 }
-                const previewUrl = resolveBuilderCallbackReturnUrl({
-                    event,
-                    openerOrigin: openerOriginFromQuery,
-                    previewUrl: requestUrl.searchParams.get("preview-url"),
-                });
                 await trackBuilderLifecycle(event, "builder connect succeeded", ownerEmail, {
-                    ...builderConnectTrackingProperties(connectTracking),
+                    ...builderConnectTrackingProperties(tracking),
                     stage: "callback",
-                    has_preview_url: Boolean(previewUrl),
-                    org_kind: orgKind || undefined,
-                    subscription: subscription || undefined,
-                    subscription_level: subscriptionLevel || undefined,
-                    subscription_name: subscriptionName || undefined,
-                    is_enterprise: isEnterprise ?? undefined,
-                    is_free_account: isFreeAccount ?? undefined,
+                    credential_scope: "user",
                 });
                 setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                // The parent (opener) is the original preview surface that started the
-                // connect flow, NOT the callback server's own origin — when the
-                // env-configured gateway is used as the callback fallback (because
-                // Builder rejects the preview host), the callback server and the
-                // opener live on different origins, and postMessage to the gateway
-                // origin would be dropped by the preview opener. callbackParentOrigin
-                // is the precomputed best-available opener origin (`_an_opener` →
-                // `preview-url` → event origin).
-                return createBuilderBrowserCallbackPage(previewUrl, {
-                    parentOrigin: callbackParentOrigin,
-                });
+                return createBuilderBrowserCallbackPage(`${parentOrigin}${getAppBasePath() || "/"}`, { parentOrigin });
             }));
-            // POST /_agent-native/builder/disconnect — revoke the user's per-user
-            // or org-scoped Builder credentials in app_secrets. Deploy-level env
-            // credentials are never mutated here; if env is configured it remains as
-            // the fallback after request-scoped credentials are removed.
+            // POST /_agent-native/builder/disconnect — remove this user's OAuth
+            // custody. Legacy BUILDER_* secrets are cleared at user scope when OAuth
+            // was present, so an admin disconnect cannot delete the org-wide keys.
+            // A legacy-only disconnect still uses the owner/admin org write gate.
             getH3App(nitroApp).use(`${P}/builder/disconnect`, defineEventHandler(async (event) => {
                 if (getMethod(event) !== "POST") {
                     setResponseStatus(event, 405);
@@ -2390,26 +2257,37 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseStatus(event, 401);
                     return { error: "unauthorized" };
                 }
-                const { deleteBuilderCredentials } = await import("./credential-provider.js");
-                // Mirror the connect-side scope decision so disconnect undoes
-                // exactly what connect wrote: owner/admin connections land at
-                // org scope and tear down at org scope; member or no-org
-                // connections stay user-scoped on both ends. Symmetric, so a
-                // single Disconnect press always reverses what the same user's
-                // Connect press did.
-                let orgId = null;
-                let role = null;
-                try {
-                    const { getOrgContext } = await import("../org/context.js");
-                    const orgCtx = await getOrgContext(event);
-                    orgId = orgCtx.orgId ?? null;
-                    role = orgCtx.role ?? null;
-                }
-                catch {
-                    /* org module not present — keep user scope */
-                }
                 try {
-                    await deleteBuilderCredentials(session.email, { orgId, role });
+                    const hadOAuth = await hasBuilderOAuthSession(session.email);
+                    const oauthResult = hadOAuth
+                        ? await deleteBuilderOAuthSession(session.email)
+                        : { localDeleted: false, remoteRevoked: false };
+                    const { deleteBuilderCredentials } = await import("./credential-provider.js");
+                    let orgId = null;
+                    let role = null;
+                    try {
+                        const { getOrgContext } = await import("../org/context.js");
+                        const orgCtx = await getOrgContext(event);
+                        orgId = orgCtx.orgId ?? null;
+                        role = orgCtx.role ?? null;
+                    }
+                    catch {
+                        // coercion-ok: org module is optional; disconnect still clears user-scoped custody.
+                    }
+                    await deleteBuilderCredentials(session.email, hadOAuth ? undefined : { orgId, role });
+                    await trackBuilderLifecycle(event, "builder disconnect succeeded", session.email, {
+                        oauth_present: hadOAuth,
+                        remote_revoked: hadOAuth
+                            ? oauthResult.remoteRevoked
+                            : undefined,
+                    });
+                    return {
+                        ok: true,
+                        remoteRevoked: hadOAuth ? oauthResult.remoteRevoked : undefined,
+                        warning: hadOAuth && !oauthResult.remoteRevoked
+                            ? "Local Builder access was removed, but remote revocation could not be confirmed."
+                            : undefined,
+                    };
                 }
                 catch (err) {
                     await trackBuilderLifecycle(event, "builder disconnect failed", session.email, {
@@ -2422,8 +2300,6 @@ export function createCoreRoutesPlugin(options = {}) {
                         cause: err instanceof Error ? err.message : String(err),
                     };
                 }
-                await trackBuilderLifecycle(event, "builder disconnect succeeded", session.email);
-                return { ok: true };
             }));
             // Proxy to Builder's agents-run API for background code changes.
             getH3App(nitroApp).use(`${P}/builder/agents-run`, defineEventHandler(async (event) => {