@agent-native/core 0.69.0 → 0.70.1

package/corpus/core/src/server/attribution.ts

@@ -0,0 +1,211 @@
+/**
+ * First-touch referral attribution — server side.
+ *
+ * The browser captures an anonymous visitor's *first* landing context (referral
+ * source, UTM params, referring host, landing path) and persists it across the
+ * signup boundary in a first-party cookie named `an_ft` (see
+ * `client/analytics.ts`). On signup, the auth hook reads that cookie off the
+ * request and enriches the canonical server-side `signup` event so we can
+ * measure where new users came from and how apps spread (virality).
+ *
+ * This module is intentionally pure and dependency-free so it is trivially
+ * unit-testable and can never throw into the signup path. The single hard rule:
+ * parsing untrusted cookie input must NEVER throw — every accessor is defensive.
+ */
+
+/**
+ * The decoded first-touch attribution object. Mirrors the compact JSON the
+ * client writes into the `an_ft` cookie / `an_attribution` localStorage key.
+ * Every field is optional — the client omits empty fields to keep the cookie
+ * small, and a malformed/absent cookie yields `null`.
+ */
+export interface FirstTouchAttribution {
+  /** Referral source bucket, e.g. "clip_share", "plan_share". */
+  ref?: string;
+  /** Referrer's stable user id (the clip/plan owner who shared the link). */
+  via?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  /** `window.location.pathname` of the first page the visitor landed on. */
+  landing_path?: string;
+  /** Host of `document.referrer` (scrubbed; host only, never a full URL). */
+  landing_referrer?: string;
+  /** ISO timestamp of when the visitor first landed. */
+  landed_at?: string;
+}
+
+/** Cookie name written by the client (non-HttpOnly; non-sensitive). */
+export const FIRST_TOUCH_COOKIE_NAME = "an_ft";
+
+const STRING_FIELDS: Array<keyof FirstTouchAttribution> = [
+  "ref",
+  "via",
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+  "landing_path",
+  "landing_referrer",
+  "landed_at",
+];
+
+/**
+ * Parse a raw `Cookie:` header into a flat name→value map. Tolerates missing
+ * input, extra whitespace, `=` inside values, and malformed pairs. Never throws.
+ */
+export function parseCookieHeader(
+  cookieHeader: string | null | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!cookieHeader || typeof cookieHeader !== "string") return out;
+  for (const part of cookieHeader.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const name = part.slice(0, eq).trim();
+    if (!name) continue;
+    const rawValue = part.slice(eq + 1).trim();
+    // First write wins so a duplicate cookie name can't clobber the first.
+    if (name in out) continue;
+    out[name] = rawValue;
+  }
+  return out;
+}
+
+/**
+ * Decode a single cookie value into a `FirstTouchAttribution`. The value is the
+ * URL-encoded compact JSON written by the client. Returns `null` for empty,
+ * malformed, or non-object input. Only known string fields are copied through,
+ * each clamped to a sane max length as a defense against an oversized cookie.
+ */
+export function decodeFirstTouchValue(
+  value: string | null | undefined,
+): FirstTouchAttribution | null {
+  if (!value || typeof value !== "string") return null;
+  let decoded = value;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    // Not valid percent-encoding — fall back to the raw value and let the JSON
+    // parse below decide whether it's usable.
+    decoded = value;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+  const source = parsed as Record<string, unknown>;
+  const result: FirstTouchAttribution = {};
+  let any = false;
+  for (const field of STRING_FIELDS) {
+    const raw = source[field];
+    if (typeof raw === "string" && raw.length > 0) {
+      result[field] = raw.slice(0, 120);
+      any = true;
+    }
+  }
+  return any ? result : null;
+}
+
+/**
+ * Read the `an_ft` first-touch attribution out of a raw `Cookie:` header.
+ * Returns `null` when the cookie is absent or unparseable. Never throws.
+ */
+export function readFirstTouchAttribution(
+  cookieHeader: string | null | undefined,
+): FirstTouchAttribution | null {
+  try {
+    const cookies = parseCookieHeader(cookieHeader);
+    return decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]);
+  } catch {
+    return null;
+  }
+}
+
+function isExternalReferrerHost(host: string | undefined): boolean {
+  const trimmed = host?.trim();
+  return !!trimmed && trimmed.length > 0;
+}
+
+/**
+ * Derive the `referral_source` bucket from first-touch attribution per the
+ * contract:
+ *   1. explicit `ref` wins;
+ *   2. landing path under `/share/` => "clip_share";
+ *   3. landing path that looks like a public plan page
+ *      (contains `/p/`, `/plan/`, or `/share-plan/`) => "plan_share";
+ *   4. a non-empty external referring host => "external";
+ *   5. otherwise => "direct".
+ */
+export function deriveReferralSource(ft: FirstTouchAttribution | null): string {
+  if (ft?.ref && ft.ref.trim()) return ft.ref.trim();
+  const path = ft?.landing_path ?? "";
+  if (path.startsWith("/share/")) return "clip_share";
+  if (
+    path.includes("/p/") ||
+    path.includes("/plan/") ||
+    path.includes("/share-plan/")
+  ) {
+    return "plan_share";
+  }
+  if (isExternalReferrerHost(ft?.landing_referrer)) return "external";
+  return "direct";
+}
+
+/**
+ * Compute the snake_case signup-event properties from first-touch attribution.
+ * Returns a clean object with `undefined` values omitted, ready to merge into
+ * the `signup` track call. Always sets `referral_source` (defaults to "direct").
+ *
+ * Pure and total — given any (or no) input it returns a well-formed object and
+ * never throws.
+ */
+export function deriveSignupAttribution(
+  ft: FirstTouchAttribution | null,
+): Record<string, string> {
+  const out: Record<string, string> = {
+    referral_source: deriveReferralSource(ft),
+  };
+  if (!ft) return out;
+
+  const setIf = (key: string, value: string | undefined) => {
+    const trimmed = value?.trim();
+    if (trimmed) out[key] = trimmed;
+  };
+
+  setIf("referrer_user", ft.via);
+  setIf("referral_medium", ft.utm_medium);
+  setIf("referral_campaign", ft.utm_campaign);
+  setIf("utm_source", ft.utm_source);
+  setIf("utm_medium", ft.utm_medium);
+  setIf("utm_campaign", ft.utm_campaign);
+  setIf("utm_content", ft.utm_content);
+  setIf("utm_term", ft.utm_term);
+  setIf("first_touch_path", ft.landing_path);
+  setIf("landing_referrer", ft.landing_referrer);
+
+  return out;
+}
+
+/**
+ * Convenience: read the cookie header and derive signup attribution in one
+ * call. Never throws; falls back to `{ referral_source: "direct" }` on any
+ * error.
+ */
+export function signupAttributionFromCookieHeader(
+  cookieHeader: string | null | undefined,
+): Record<string, string> {
+  try {
+    return deriveSignupAttribution(readFirstTouchAttribution(cookieHeader));
+  } catch {
+    return { referral_source: "direct" };
+  }
+}

package/corpus/core/src/server/auth.ts

@@ -1796,6 +1796,12 @@ function createAuthGuardFn(): (
     // route tree, no per-user data.
     if (p === "/__manifest") return;
     if (p === "/_agent-native/speculation-rules.json") return;
+    // Liveness probe: always public so uptime monitors and the keep-warm cron
+    // can reach the DB-warmup route without a session. It exposes no per-user
+    // data (just ok/db/ms) and runs a trivial `SELECT 1`. Without this bypass
+    // the gate below 401s anonymous /_agent-native/* requests before any DB
+    // query, so the database would never get warmed.
+    if (p === "/_agent-native/health") return;
     if (isPublicPath(normalizedUrl, publicPaths)) return;
     if (shouldBypassAuthForBuilderConnect(event, p)) return;
     if (isPublicWorkspacePageRequest(event, p, config)) {

package/corpus/core/src/server/better-auth-instance.ts

@@ -23,6 +23,7 @@ import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { autoJoinDomainMatchingOrgs } from "../org/auto-join-domain.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { flushTracking, identify, track } from "../tracking/index.js";
+import { signupAttributionFromCookieHeader } from "./attribution.js";
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
@@ -72,23 +73,41 @@ export async function trackSignupEvent({
   authUserId,
   email,
   name,
+  attribution,
 }: {
   authProvider: string;
   authUserId?: string;
   email: string;
   name?: string | null;
+  /**
+   * First-touch referral attribution derived from the visitor's `an_ft`
+   * cookie (see `server/attribution.ts`). Snake_case keys such as
+   * `referral_source`, `referrer_user`, and the UTM passthrough are merged
+   * into the `signup` event so we can measure where new users came from.
+   * `undefined` values are dropped; a missing object is a clean no-op.
+   */
+  attribution?: Record<string, string | undefined>;
 }): Promise<void> {
   identify(email, {
     email,
     name: name ?? undefined,
     authUserId,
   });
+  const cleanAttribution: Record<string, string> = {};
+  if (attribution) {
+    for (const [key, value] of Object.entries(attribution)) {
+      if (typeof value === "string" && value.length > 0) {
+        cleanAttribution[key] = value;
+      }
+    }
+  }
   track(
     "signup",
     {
       ...resolveSignupTrackingProperties(),
       auth_provider: authProvider,
       ...(authUserId ? { auth_user_id: authUserId } : {}),
+      ...cleanAttribution,
     },
     { userId: email },
   );
@@ -929,22 +948,47 @@ async function createBetterAuthInstance(
     databaseHooks: {
       user: {
         create: {
-          after: async (user: {
-            id?: string;
-            email?: string;
-            name?: string | null;
-          }) => {
+          after: async (
+            user: {
+              id?: string;
+              email?: string;
+              name?: string | null;
+            },
+            // Better Auth (1.6.x) passes the endpoint context as the 2nd arg.
+            // It carries the originating request's headers (and on OAuth
+            // signups the callback request's headers), which is where the
+            // browser's `an_ft` first-touch cookie rides in.
+            context?: {
+              headers?: Headers | null;
+              request?: { headers?: Headers | null } | null;
+            } | null,
+          ) => {
             // When a newly-created user's email has pending org invitations
             // (common when someone is invited *before* they've signed up),
             // auto-accept them so the user lands in the org on their very
             // first page load instead of a blank-slate workspace.
             const email = user?.email;
             if (!email) return;
+            // Derive first-touch referral attribution from the request's
+            // cookie header. Never let attribution parsing throw or block
+            // signup — on any error fall back to `direct`.
+            let attribution: Record<string, string> | undefined;
+            try {
+              const cookieHeader =
+                context?.headers?.get("cookie") ??
+                context?.request?.headers?.get("cookie") ??
+                null;
+              attribution = signupAttributionFromCookieHeader(cookieHeader);
+            } catch (err) {
+              console.error("[auth] failed to derive signup attribution", err);
+              attribution = undefined;
+            }
             await trackSignupEvent({
               authProvider: "better-auth",
               authUserId: user.id,
               email,
               name: user.name,
+              attribution,
             });
             try {
               await acceptPendingInvitationsForEmail(email);

package/corpus/core/src/server/builder-browser.ts

@@ -1,7 +1,10 @@
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import type { H3Event } from "h3";
 import { getHeader } from "h3";
-import { getAuthSecret } from "./better-auth-instance.js";
+import {
+  getAuthSecret,
+  resolveSignupTrackingIdentity,
+} from "./better-auth-instance.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
 
 const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
@@ -43,6 +46,8 @@ export const BUILDER_SIGNUP_SOURCE_PARAM = "signupSource";
 export const BUILDER_AGENT_NATIVE_FLOW_PARAM = "agentNativeFlow";
 export const BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM =
   "agentNativeConnectSource";
+export const BUILDER_AGENT_NATIVE_APP_PARAM = "agentNativeApp";
+export const BUILDER_AGENT_NATIVE_TEMPLATE_PARAM = "agentNativeTemplate";
 
 const BUILDER_STATE_TTL_MS = 10 * 60 * 1000;
 const BUILDER_SIGNUP_SOURCE = "agent-native";
@@ -51,6 +56,8 @@ export interface BuilderConnectTrackingParams {
   signupSource?: string;
   agentNativeFlow?: string;
   agentNativeConnectSource?: string;
+  agentNativeApp?: string;
+  agentNativeTemplate?: string;
 }
 
 function cleanTrackingParam(value: unknown): string | undefined {
@@ -72,6 +79,12 @@ export function getBuilderConnectTrackingParams(
     agentNativeConnectSource: cleanTrackingParam(
       params.get(BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM),
     ),
+    agentNativeApp: cleanTrackingParam(
+      params.get(BUILDER_AGENT_NATIVE_APP_PARAM),
+    ),
+    agentNativeTemplate: cleanTrackingParam(
+      params.get(BUILDER_AGENT_NATIVE_TEMPLATE_PARAM),
+    ),
   };
 }
 
@@ -86,6 +99,12 @@ export function builderConnectTrackingProperties(
   if (tracking.agentNativeConnectSource) {
     properties.agent_native_connect_source = tracking.agentNativeConnectSource;
   }
+  if (tracking.agentNativeApp) {
+    properties.agent_native_app = tracking.agentNativeApp;
+  }
+  if (tracking.agentNativeTemplate) {
+    properties.agent_native_template = tracking.agentNativeTemplate;
+  }
   return properties;
 }
 
@@ -101,6 +120,10 @@ function applyBuilderConnectTrackingParams(
   if (flow) params.set(BUILDER_AGENT_NATIVE_FLOW_PARAM, flow);
   const source = cleanTrackingParam(tracking.agentNativeConnectSource);
   if (source) params.set(BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM, source);
+  const app = cleanTrackingParam(tracking.agentNativeApp);
+  if (app) params.set(BUILDER_AGENT_NATIVE_APP_PARAM, app);
+  const template = cleanTrackingParam(tracking.agentNativeTemplate);
+  if (template) params.set(BUILDER_AGENT_NATIVE_TEMPLATE_PARAM, template);
 }
 
 export interface BuilderBrowserStatus {
@@ -524,8 +547,11 @@ export function buildBuilderCliAuthUrl(
   ) {
     callbackUrl.searchParams.set(BUILDER_OPENER_PARAM, requestedPreviewOrigin);
   }
+  const identity = resolveSignupTrackingIdentity();
   const tracking = {
     signupSource: BUILDER_SIGNUP_SOURCE,
+    agentNativeApp: identity.app,
+    agentNativeTemplate: identity.template,
     ...options.tracking,
   };
   applyBuilderConnectTrackingParams(callbackUrl.searchParams, tracking);

package/corpus/core/src/server/core-routes-plugin.ts

@@ -32,6 +32,7 @@ import {
   MCP_EMBED_CORS_ALLOW_HEADERS,
   shouldAllowMcpEmbedCredentials,
 } from "../shared/mcp-embed-headers.js";
+import { captureError } from "./capture-error.js";
 import { handleMcpConnect } from "../mcp/connect-route.js";
 import {
   handleMcpOAuth,
@@ -145,6 +146,7 @@ import { isEnvVarWriteAllowed } from "./env-var-writes.js";
 import { llmConnectionTrackingProperties } from "../shared/llm-connection.js";
 import { mountBrowserSessionRoutes } from "../browser-sessions/routes.js";
 import { mountDbAdminRoutes } from "../db-admin/routes.js";
+import { getDbExec } from "../db/client.js";
 import {
   DEFAULT_SSR_CACHE_HEADERS,
   EMPTY_SPECULATION_RULES,
@@ -158,6 +160,40 @@ import {
 export const FRAMEWORK_ROUTE_PREFIX = "/_agent-native";
 export const FRAMEWORK_EVENTS_ROUTE = `${FRAMEWORK_ROUTE_PREFIX}/events`;
 export const LEGACY_FRAMEWORK_EVENTS_ROUTE = `${FRAMEWORK_ROUTE_PREFIX}/poll-events`;
+
+/** Result of the `/_agent-native/health` liveness + DB-warmup probe. */
+export interface DbHealthProbeResult {
+  /** The serverless function is live and served the request. */
+  ok: true;
+  /** A trivial `SELECT 1` reached the database (false = no DB or unreachable). */
+  db: boolean;
+  /** Round-trip time of the probe in milliseconds. */
+  ms: number;
+}
+
+/**
+ * Run a trivial `SELECT 1` to confirm the database is reachable and, as a side
+ * effect, keep a scale-to-zero serverless database (e.g. Neon) warm. Touching
+ * the DB on a schedule prevents the multi-second cold-start that otherwise
+ * stalls the next real user request.
+ *
+ * Always resolves: an app with no database (or a momentarily unreachable one)
+ * is still live, so the probe reports `db: false` rather than throwing. The
+ * `exec` parameter is injectable purely for tests.
+ */
+export async function runDbHealthProbe(
+  exec: () => { execute: (sql: string) => Promise<unknown> } = getDbExec,
+): Promise<DbHealthProbeResult> {
+  const startedAt = Date.now();
+  let db = false;
+  try {
+    await exec().execute("SELECT 1");
+    db = true;
+  } catch {
+    // Live even when the DB is unreachable or the app has no database.
+  }
+  return { ok: true, db, ms: Date.now() - startedAt };
+}
 const DEFAULT_BUILDER_WAITLIST_FORM_ID = "DYTHuM0jlV";
 const DEFAULT_BUILDER_WAITLIST_FORMS_ORIGIN = "https://forms.agent-native.com";
 const BUILDER_WAITLIST_FORM_SOURCE = "connect_builder_card";
@@ -550,6 +586,8 @@ export interface CoreRoutesPluginOptions {
   disableSSE?: boolean;
   /** Disable the /_agent-native/ping health check. */
   disablePing?: boolean;
+  /** Disable the /_agent-native/health DB liveness + warmup probe. */
+  disableHealth?: boolean;
   /** Disable the /_agent-native/application-state routes. */
   disableAppState?: boolean;
   /** Disable the /_agent-native/open deep-link route. */
@@ -594,6 +632,7 @@ export interface CoreRoutesPluginOptions {
  *   GET    /_agent-native/poll                          — polling endpoint for change detection
  *   GET    /_agent-native/events (or custom)            — SSE endpoint for real-time sync
  *   GET    /_agent-native/ping                          — health check
+ *   GET    /_agent-native/health                        — DB liveness probe + scale-to-zero warmup
  *   GET    /_agent-native/env-status                    — env key configuration status (when envKeys provided)
  *   POST   /_agent-native/env-vars                      — save env vars to .env (when envKeys provided)
  *   GET    /_agent-native/application-state/:key        — read application state
@@ -925,6 +964,20 @@ export function createCoreRoutesPlugin(
         );
       }
 
+      // Health + DB warmup — liveness probe that touches the database so
+      // uptime monitors and the keep-warm cron prevent a scale-to-zero
+      // serverless DB (e.g. Neon) from cold-starting on the next real
+      // request. Public, side-effect free, and never cached.
+      if (!options.disableHealth) {
+        getH3App(nitroApp).use(
+          `${P}/health`,
+          defineEventHandler(async (event) => {
+            setResponseHeader(event, "cache-control", "no-store");
+            return runDbHealthProbe();
+          }),
+        );
+      }
+
       getH3App(nitroApp).use(
         `${P}/speculation-rules.json`,
         defineEventHandler((event) => {
@@ -1691,6 +1744,12 @@ export function createCoreRoutesPlugin(
                 agentNativeConnectSource:
                   connectTracking.agentNativeConnectSource ??
                   pending.tracking.agentNativeConnectSource,
+                agentNativeApp:
+                  connectTracking.agentNativeApp ??
+                  pending.tracking.agentNativeApp,
+                agentNativeTemplate:
+                  connectTracking.agentNativeTemplate ??
+                  pending.tracking.agentNativeTemplate,
               };
             }
             if (
@@ -3103,6 +3162,83 @@ export function createCoreRoutesPlugin(
           `${P}/embed/start`,
           createEmbedStartRouteHandler({ getExistingSession: getSession }),
         );
+
+        // POST /_agent-native/mcp/embed-error — telemetry sink for MCP App
+        // embed shells. The shell runs in a sandboxed, opaque-origin iframe
+        // (Codex, Cursor, ChatGPT, Claude) with no session cookie or CSRF
+        // token, so this endpoint is intentionally unauthenticated and
+        // CORS-open to the SAME sandbox origins as /embed/start. It forwards a
+        // small, bounded diagnostic payload to Sentry via captureError so we
+        // can see *why* an inline embed failed (handshake timeout, transplant
+        // fetch status/CORS, auth, CSP) per host. Best-effort: always 204,
+        // never throws, body capped, no client-trusted identity.
+        getH3App(nitroApp).use(
+          `${P}/mcp/embed-error`,
+          defineEventHandler(async (event: H3Event) => {
+            const origin = getHeader(event, "origin");
+            if (origin && isMcpEmbedCorsOrigin(origin)) {
+              setResponseHeader(event, "Access-Control-Allow-Origin", origin);
+              setResponseHeader(event, "Vary", "Origin");
+              setResponseHeader(
+                event,
+                "Access-Control-Allow-Methods",
+                "POST,OPTIONS",
+              );
+              setResponseHeader(
+                event,
+                "Access-Control-Allow-Headers",
+                MCP_EMBED_CORS_ALLOW_HEADERS,
+              );
+            }
+            const method = getMethod(event);
+            if (method === "OPTIONS") {
+              setResponseStatus(event, 204);
+              return "";
+            }
+            if (method !== "POST") {
+              setResponseStatus(event, 405);
+              return { error: "Method not allowed" };
+            }
+            const body = await readBody(event).catch(() => undefined);
+            const rec =
+              body && typeof body === "object" && !Array.isArray(body)
+                ? (body as Record<string, unknown>)
+                : {};
+            const str = (value: unknown, max: number): string | undefined =>
+              typeof value === "string" && value
+                ? value.slice(0, max)
+                : undefined;
+            const message = str(rec.message, 500) ?? "MCP embed failed";
+            try {
+              captureError(new Error(message), {
+                route: `${P}/mcp/embed-error`,
+                method: "POST",
+                userAgent:
+                  str(rec.userAgent, 300) ?? getHeader(event, "user-agent"),
+                tags: {
+                  source: "mcp-embed-shell",
+                  embed_stage: str(rec.stage, 60),
+                  embed_render_mode: str(rec.renderMode, 40),
+                  embed_host: str(rec.host, 160),
+                  embed_bridge: str(rec.bridge, 40),
+                },
+                extra: {
+                  embedUrl: str(rec.url, 600),
+                  httpStatus:
+                    typeof rec.status === "number"
+                      ? rec.status
+                      : str(rec.status, 40),
+                  detail: str(rec.detail, 1200),
+                  origin,
+                },
+              });
+            } catch {
+              // Observability must never throw back into the request path.
+            }
+            setResponseStatus(event, 204);
+            return "";
+          }),
+        );
       }
 
       if (!options.disableAppState) {

package/corpus/core/src/server/google-oauth.ts

@@ -841,14 +841,27 @@ export function oauthCallbackResponse(
   // same-origin; Builder desktop workspace returns may point back to the
   // local loopback gateway and carry the short-lived `_session` bridge so
   // the local app can promote the newly created hosted OAuth session.
-  setResponseStatus(event, 302);
-  setResponseHeader(
-    event,
-    "Location",
-    appendSessionToOAuthReturnUrl(opts.returnUrl, opts.sessionToken),
+  const location = appendSessionToOAuthReturnUrl(
+    opts.returnUrl,
+    opts.sessionToken,
   );
+  setResponseStatus(event, 302);
+  setResponseHeader(event, "Location", location);
   setResponseHeader(event, "Referrer-Policy", "no-referrer");
-  return "";
+  // Return a real 302 so the browser lands on the clean return URL instead of
+  // lingering on the provider callback URL with its `code`/`state` query
+  // params. But h3 hands a non-2xx web `Response` straight back WITHOUT merging
+  // the `Set-Cookie` staged earlier in the callback (the framework session
+  // cookie), so mirror those staged cookies onto the redirect Response —
+  // otherwise the sign-in succeeds but the browser arrives back logged out.
+  const headers = new Headers({
+    Location: location,
+    "Referrer-Policy": "no-referrer",
+  });
+  for (const cookie of event.res?.headers?.getSetCookie?.() ?? []) {
+    headers.append("set-cookie", cookie);
+  }
+  return new Response(null, { status: 302, headers });
 }
 
 /** HTML error page for OAuth failures. The message is HTML-escaped — most