@agent-native/core 0.164.4 → 0.164.12

package/dist/server/auth.js

@@ -842,7 +842,7 @@ export function isExpectedAuthFailure(error) {
 // ---------------------------------------------------------------------------
 let _sessionInitPromise;
 let sessionMaxAge = DEFAULT_MAX_AGE;
-async function ensureSessionTable() {
+export async function ensureSessionTable() {
     if (!_sessionInitPromise) {
         _sessionInitPromise = (async () => {
             const client = getDbExec();
@@ -1115,6 +1115,7 @@ const _desktopExchanges = new Map();
 const DESKTOP_EXCHANGE_ERROR_PREFIX = "__error__::";
 const DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX = "__magic-link-challenge__::";
 const DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX = "__magic-link-exchange__::";
+export const DESKTOP_OAUTH_BROWSER_BINDING_COOKIE = "an_desktop_oauth_binding";
 const DESKTOP_AUTH_TOKEN_BODY_ORIGINS = new Set([
     "tauri://localhost",
     "http://tauri.localhost",
@@ -1138,6 +1139,12 @@ function normalizeDesktopFlowVerifier(value) {
 function desktopFlowVerifierHash(verifier) {
     return crypto.createHash("sha256").update(verifier).digest("base64url");
 }
+function matchesDesktopHash(actualHash, expectedHash) {
+    const actual = Buffer.from(actualHash);
+    const expected = Buffer.from(expectedHash);
+    return (actual.length === expected.length &&
+        crypto.timingSafeEqual(actual, expected));
+}
 function matchesDesktopFlowVerifier(verifier, expectedHash) {
     const actual = Buffer.from(desktopFlowVerifierHash(verifier));
     const expected = Buffer.from(expectedHash);
@@ -1145,31 +1152,63 @@ function matchesDesktopFlowVerifier(verifier, expectedHash) {
         crypto.timingSafeEqual(actual, expected));
 }
 function parseDesktopExchangeStoredEntry(packed) {
-    if (packed.startsWith(DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX)) {
-        const verifierHash = packed.slice(DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX.length);
-        return verifierHash ? { challenge: true, verifierHash } : null;
-    }
-    if (packed.startsWith(DESKTOP_EXCHANGE_ERROR_PREFIX)) {
-        const raw = packed.slice(DESKTOP_EXCHANGE_ERROR_PREFIX.length);
+    try {
+        if (packed.startsWith(DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX)) {
+            const raw = packed.slice(DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX.length);
+            const parts = raw.split("::");
+            if (parts.length > 2)
+                return null;
+            const [verifierHash, browserBindingHash] = parts;
+            if (!isValidDesktopFlowVerifierHash(verifierHash))
+                return null;
+            if (browserBindingHash !== undefined &&
+                !isValidDesktopFlowVerifierHash(browserBindingHash)) {
+                return null;
+            }
+            return {
+                challenge: true,
+                verifierHash,
+                ...(browserBindingHash ? { browserBindingHash } : {}),
+            };
+        }
+        if (packed.startsWith(DESKTOP_EXCHANGE_ERROR_PREFIX)) {
+            const raw = packed.slice(DESKTOP_EXCHANGE_ERROR_PREFIX.length);
+            const parsed = JSON.parse(Buffer.from(raw, "base64url").toString());
+            if (!parsed ||
+                typeof parsed !== "object" ||
+                typeof parsed.message !== "string") {
+                return null;
+            }
+            return { error: parsed };
+        }
+        const isMagicLinkExchange = packed.startsWith(DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX);
+        const encoded = isMagicLinkExchange
+            ? packed.slice(DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX.length)
+            : packed;
+        const verifierSeparator = isMagicLinkExchange ? encoded.indexOf("::") : -1;
+        const verifierHash = verifierSeparator >= 0 ? encoded.slice(0, verifierSeparator) : undefined;
+        if (verifierHash !== undefined &&
+            !isValidDesktopFlowVerifierHash(verifierHash)) {
+            return null;
+        }
+        const tokenAndEmail = verifierSeparator >= 0 ? encoded.slice(verifierSeparator + 2) : encoded;
+        const sepIdx = tokenAndEmail.indexOf("::");
+        if (sepIdx <= 0 || sepIdx === tokenAndEmail.length - 2)
+            return null;
+        const token = tokenAndEmail.slice(0, sepIdx);
+        const email = tokenAndEmail.slice(sepIdx + 2);
+        if (!token || !email)
+            return null;
         return {
-            error: JSON.parse(Buffer.from(raw, "base64url").toString()),
+            token,
+            email,
+            ...(verifierHash ? { verifierHash } : {}),
         };
     }
-    const isMagicLinkExchange = packed.startsWith(DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX);
-    const encoded = isMagicLinkExchange
-        ? packed.slice(DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX.length)
-        : packed;
-    const verifierSeparator = isMagicLinkExchange ? encoded.indexOf("::") : -1;
-    const verifierHash = verifierSeparator >= 0 ? encoded.slice(0, verifierSeparator) : undefined;
-    const tokenAndEmail = verifierSeparator >= 0 ? encoded.slice(verifierSeparator + 2) : encoded;
-    const sepIdx = tokenAndEmail.indexOf("::");
-    if (sepIdx === -1)
+    catch {
+        // coercion-ok: malformed desktop exchange payloads are rejected as absent.
         return null;
-    return {
-        token: tokenAndEmail.slice(0, sepIdx),
-        email: tokenAndEmail.slice(sepIdx + 2),
-        ...(verifierHash ? { verifierHash } : {}),
-    };
+    }
 }
 function isDesktopMagicLinkCallbackPath(value) {
     try {
@@ -1186,20 +1225,49 @@ function withDesktopMagicLinkFlow(callbackURL, flow) {
     url.searchParams.set("verifier", flow.verifier);
     return `${url.pathname}${url.search}${url.hash}`;
 }
-async function persistDesktopMagicLinkChallenge(flowId, verifierHash) {
-    await addSession(`dex:${flowId}`, `${DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX}${verifierHash}`);
+async function persistDesktopMagicLinkChallenge(flowId, verifierHash, browserBindingHash) {
+    await addSession(`dex:${flowId}`, `${DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX}${verifierHash}${browserBindingHash ? `::${browserBindingHash}` : ""}`);
+}
+function isValidDesktopFlowVerifierHash(value) {
+    return typeof value === "string" && /^[A-Za-z0-9_-]{43}$/.test(value);
+}
+/**
+ * Create or reuse the browser-local binding for a desktop Google OAuth flow.
+ * The raw value stays in an HttpOnly cookie; only its hash travels in signed
+ * OAuth state and the exchange challenge. This prevents a caller from
+ * initiating a flow and handing its authorization URL to another browser.
+ */
+export function prepareDesktopOAuthBrowserBinding(event) {
+    let binding = getCookie(event, DESKTOP_OAUTH_BROWSER_BINDING_COOKIE);
+    if (!binding || !/^[A-Za-z0-9_-]{43}$/.test(binding)) {
+        binding = crypto.randomBytes(32).toString("base64url");
+        setCookie(event, DESKTOP_OAUTH_BROWSER_BINDING_COOKIE, binding, {
+            ...crossSiteCookieAttrs(event),
+            httpOnly: true,
+            path: "/",
+            maxAge: Math.floor(DESKTOP_EXCHANGE_TTL_MS / 1_000),
+        });
+    }
+    return desktopFlowVerifierHash(binding);
+}
+/** Verify that a desktop OAuth callback is returning to its initiating browser. */
+export function matchesDesktopOAuthBrowserBinding(event, expectedHash) {
+    const binding = getCookie(event, DESKTOP_OAUTH_BROWSER_BINDING_COOKIE);
+    return Boolean(binding &&
+        isValidDesktopFlowVerifierHash(expectedHash) &&
+        matchesDesktopFlowVerifier(binding, expectedHash));
 }
 async function issueDesktopMagicLinkFlow() {
     const flowId = crypto.randomBytes(32).toString("base64url");
     const verifier = crypto.randomBytes(32).toString("base64url");
     const verifierHash = desktopFlowVerifierHash(verifier);
-    _desktopExchanges.set(flowId, {
-        challenge: true,
-        verifierHash,
-        expiresAt: Date.now() + DESKTOP_EXCHANGE_TTL_MS,
-    });
     try {
         await persistDesktopMagicLinkChallenge(flowId, verifierHash);
+        _desktopExchanges.set(flowId, {
+            challenge: true,
+            verifierHash,
+            expiresAt: Date.now() + DESKTOP_EXCHANGE_TTL_MS,
+        });
     }
     catch (error) {
         _desktopExchanges.delete(flowId);
@@ -1207,16 +1275,88 @@ async function issueDesktopMagicLinkFlow() {
     }
     return { flowId, verifier };
 }
-export function setDesktopExchange(flowId, token, email) {
-    _desktopExchanges.set(flowId, {
-        token,
-        email,
-        expiresAt: Date.now() + DESKTOP_EXCHANGE_TTL_MS,
-    });
-    // Persist to DB so the token survives cross-instance routing (e.g. when
-    // templates call this helper directly instead of going through the OAuth
-    // callback path).
-    void persistDesktopExchangeToDB(flowId, token, email);
+export async function setDesktopExchange(flowId, token, email, verifierHash) {
+    if (!isValidDesktopFlowVerifierHash(verifierHash)) {
+        throw new Error("Invalid desktop exchange challenge.");
+    }
+    // Persist before publishing anything to the in-memory cache. The DB is the
+    // durable source of truth for one-time tokens; publishing first would let a
+    // same-instance poll succeed while a delayed write recreated a token after
+    // it had already been consumed.
+    await persistDesktopExchangeToDB(flowId, token, email, verifierHash);
+    _desktopExchanges.delete(flowId);
+}
+/**
+ * Register the client-held verifier for a desktop OAuth flow before Google
+ * sees the request. Only the verifier hash is persisted; the initiating
+ * browser keeps the raw verifier and presents it when polling the exchange.
+ */
+export async function registerDesktopExchange(flowId, verifier, browserBindingHash) {
+    const normalizedFlowId = normalizeDesktopFlowId(flowId);
+    const normalizedVerifier = normalizeDesktopFlowVerifier(verifier);
+    if (!normalizedFlowId || !normalizedVerifier) {
+        throw new Error("Invalid desktop exchange challenge.");
+    }
+    if (browserBindingHash !== undefined &&
+        !isValidDesktopFlowVerifierHash(browserBindingHash)) {
+        throw new Error("Invalid desktop exchange browser binding.");
+    }
+    const verifierHash = desktopFlowVerifierHash(normalizedVerifier);
+    const current = _desktopExchanges.get(normalizedFlowId);
+    if (current && current.expiresAt >= Date.now()) {
+        if ("challenge" in current &&
+            matchesDesktopFlowVerifier(normalizedVerifier, current.verifierHash)) {
+            if (browserBindingHash !== undefined &&
+                (!current.browserBindingHash ||
+                    !matchesDesktopHash(current.browserBindingHash, browserBindingHash))) {
+                throw new Error("Desktop exchange flow is already in use.");
+            }
+            return current.verifierHash;
+        }
+        throw new Error("Desktop exchange flow is already in use.");
+    }
+    const stored = await readDesktopExchangeFromDB(normalizedFlowId);
+    if (stored.status === "unavailable") {
+        throw new Error("Desktop exchange storage is unavailable.");
+    }
+    if (stored.status === "malformed") {
+        throw new Error("Desktop exchange storage is invalid.");
+    }
+    if (stored.status === "entry") {
+        const storedEntry = stored.entry;
+        if ("challenge" in storedEntry &&
+            matchesDesktopFlowVerifier(normalizedVerifier, storedEntry.verifierHash)) {
+            if (browserBindingHash !== undefined &&
+                (!storedEntry.browserBindingHash ||
+                    !matchesDesktopHash(storedEntry.browserBindingHash, browserBindingHash))) {
+                throw new Error("Desktop exchange flow is already in use.");
+            }
+            _desktopExchanges.set(normalizedFlowId, {
+                challenge: true,
+                verifierHash: storedEntry.verifierHash,
+                ...(storedEntry.browserBindingHash
+                    ? { browserBindingHash: storedEntry.browserBindingHash }
+                    : {}),
+                expiresAt: Date.now() + DESKTOP_EXCHANGE_TTL_MS,
+            });
+            return storedEntry.verifierHash;
+        }
+        throw new Error("Desktop exchange flow is already in use.");
+    }
+    try {
+        await persistDesktopMagicLinkChallenge(normalizedFlowId, verifierHash, browserBindingHash);
+        _desktopExchanges.set(normalizedFlowId, {
+            challenge: true,
+            verifierHash,
+            ...(browserBindingHash ? { browserBindingHash } : {}),
+            expiresAt: Date.now() + DESKTOP_EXCHANGE_TTL_MS,
+        });
+    }
+    catch (error) {
+        _desktopExchanges.delete(normalizedFlowId);
+        throw error;
+    }
+    return verifierHash;
 }
 export function setDesktopExchangeError(flowId, error) {
     _desktopExchanges.set(flowId, {
@@ -1230,19 +1370,15 @@ export function setDesktopExchangeError(flowId, error) {
  * cross-instance routing (e.g. Cloudflare Workers). Stored under a synthetic
  * token key "dex:{flowId}"; the `email` column packs both the real session
  * token and the user email so they can be recovered in one query.
- * Non-fatal — if the DB isn't ready yet the in-memory Map still works for
- * same-instance requests.
+ * Fail closed when the durable exchange cannot be written. A token must not
+ * be published only in memory because the callback and poll can land on
+ * different instances.
  */
 async function persistDesktopExchangeToDB(flowId, token, email, verifierHash) {
-    try {
-        const packed = verifierHash
-            ? `${DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX}${verifierHash}::${token}::${email}`
-            : `${token}::${email}`;
-        await addSession(`dex:${flowId}`, packed);
-    }
-    catch {
-        // non-fatal — in-memory Map is the primary path
-    }
+    const packed = verifierHash
+        ? `${DESKTOP_MAGIC_LINK_EXCHANGE_PREFIX}${verifierHash}::${token}::${email}`
+        : `${token}::${email}`;
+    await addSession(`dex:${flowId}`, packed);
 }
 async function persistDesktopExchangeErrorToDB(flowId, error) {
     try {
@@ -1253,41 +1389,35 @@ async function persistDesktopExchangeErrorToDB(flowId, error) {
         // non-fatal — in-memory Map is the primary path
     }
 }
-/**
- * Retrieve and consume a desktop exchange entry from the DB fallback.
- * Returns null if not found or already consumed.
- */
-async function consumeDesktopExchangeFromDB(flowId) {
+/** Read the durable exchange without mutating it. */
+async function readDesktopExchangeFromDB(flowId) {
     try {
-        // Atomic DELETE...RETURNING prevents token replay: two concurrent polls
-        // cannot both retrieve the token because only one DELETE will match the row.
-        // SQLite ≥3.35 and PostgreSQL both support this syntax.
-        // The created_at predicate enforces the 5-minute TTL so stale DB entries
-        // (e.g. the desktop app never polled) are rejected rather than silently
-        // redeemed with the session table's default 30-day TTL.
         const client = getDbExec();
         const { rows } = await client.execute({
-            sql: `DELETE FROM sessions WHERE token = ? AND created_at > ? AND email NOT LIKE ? RETURNING email`,
-            args: [
-                `dex:${flowId}`,
-                Date.now() - DESKTOP_EXCHANGE_TTL_MS,
-                `${DESKTOP_MAGIC_LINK_CHALLENGE_PREFIX}%`,
-            ],
+            sql: `SELECT email FROM sessions WHERE token = ? AND created_at > ? LIMIT 1`,
+            args: [`dex:${flowId}`, Date.now() - DESKTOP_EXCHANGE_TTL_MS],
         });
-        forgetCachedSessionEmail(`dex:${flowId}`);
         if (rows.length === 0)
-            return null;
+            return { status: "missing" };
         const packed = (rows[0].email ?? rows[0][0]);
-        if (!packed)
-            return null;
-        return parseDesktopExchangeStoredEntry(packed);
+        if (packed === null)
+            return { status: "malformed", packed };
+        const entry = parseDesktopExchangeStoredEntry(packed);
+        return entry
+            ? { status: "entry", entry, packed }
+            : { status: "malformed", packed };
     }
     catch {
-        // coercion-ok: a DB fallback outage leaves the exchange pending so polling can retry without consuming a token.
-        return null;
+        return { status: "unavailable" };
     }
 }
-async function readDesktopMagicLinkChallengeFromDB(flowId) {
+/**
+ * Parse and atomically consume a desktop exchange entry from the DB fallback.
+ * The exact packed payload is part of the DELETE predicate so concurrent
+ * pollers cannot both redeem a row, and malformed payloads remain available
+ * for diagnosis instead of being deleted before parsing.
+ */
+async function consumeDesktopExchangeFromDB(flowId) {
     try {
         const client = getDbExec();
         const { rows } = await client.execute({
@@ -1295,17 +1425,27 @@ async function readDesktopMagicLinkChallengeFromDB(flowId) {
             args: [`dex:${flowId}`, Date.now() - DESKTOP_EXCHANGE_TTL_MS],
         });
         if (rows.length === 0)
-            return null;
+            return { status: "missing" };
         const packed = (rows[0].email ?? rows[0][0]);
-        if (!packed)
-            return null;
-        const entry = parseDesktopExchangeStoredEntry(packed);
-        return entry && "challenge" in entry
-            ? { verifierHash: entry.verifierHash }
-            : null;
+        const entry = packed ? parseDesktopExchangeStoredEntry(packed) : null;
+        if (!entry)
+            return { status: "malformed", packed };
+        // SQLite >=3.35 and PostgreSQL both support RETURNING. Matching the
+        // payload makes the read/claim pair safe against a concurrent replacement
+        // of the same flow id, while the single DELETE makes concurrent pollers
+        // one-time consumers.
+        const deleted = await client.execute({
+            sql: `DELETE FROM sessions WHERE token = ? AND created_at > ? AND email = ? RETURNING email`,
+            args: [`dex:${flowId}`, Date.now() - DESKTOP_EXCHANGE_TTL_MS, packed],
+        });
+        if (deleted.rows.length === 0)
+            return { status: "missing" };
+        forgetCachedSessionEmail(`dex:${flowId}`);
+        return { status: "entry", entry };
     }
     catch {
-        return null;
+        // coercion-ok: a DB fallback outage leaves the exchange pending so polling can retry without consuming a token.
+        return { status: "unavailable" };
     }
 }
 async function claimDesktopMagicLinkFlow(flowId, verifier, token, email) {
@@ -1317,14 +1457,15 @@ async function claimDesktopMagicLinkFlow(flowId, verifier, token, email) {
             !matchesDesktopFlowVerifier(verifier, entry.verifierHash)) {
             return false;
         }
-        _desktopExchanges.set(flowId, {
-            token,
-            email,
-            verifierHash,
-            expiresAt: Date.now() + DESKTOP_EXCHANGE_TTL_MS,
-        });
-        await persistDesktopExchangeToDB(flowId, token, email, verifierHash);
-        return true;
+        try {
+            await persistDesktopExchangeToDB(flowId, token, email, verifierHash);
+            _desktopExchanges.delete(flowId);
+            return true;
+        }
+        catch {
+            // coercion-ok: a failed persistence claim must not issue a native session token.
+            return false;
+        }
     }
     try {
         const client = getDbExec();
@@ -1440,6 +1581,7 @@ function applyCorsHeaders(event, publicCorsPaths = [], requestPath) {
             "X-Request-Source",
             "X-Agent-Native-CSRF",
             "X-User-Timezone",
+            "X-Agent-Native-Desktop-Verifier",
             EMBED_TARGET_HEADER,
         ].join(","));
     return { hasOrigin: true, allowed: true };
@@ -2911,10 +3053,11 @@ async function mountBetterAuthRoutes(app, options) {
             "https://www.googleapis.com/auth/userinfo.email",
             "https://www.googleapis.com/auth/userinfo.profile",
         ].join(" ");
-        app.use("/_agent-native/google/auth-url", defineEventHandler((event) => {
+        app.use("/_agent-native/google/auth-url", defineEventHandler(async (event) => {
             if (!areGenericGoogleOAuthRoutesEnabled(app))
                 return undefined;
-            if (getMethod(event) !== "GET") {
+            const method = getMethod(event);
+            if (method !== "GET" && method !== "POST") {
                 setResponseStatus(event, 405);
                 return { error: "Method not allowed" };
             }
@@ -2931,7 +3074,37 @@ async function mountBetterAuthRoutes(app, options) {
             const q = getQuery(event);
             const desktop = isElectronRequest(event) || q.desktop === "1" || q.desktop === "true";
             const mobile = q.mobile === "1" || q.mobile === "true";
-            const flowId = desktop ? q.flow_id || undefined : undefined;
+            const flowId = desktop && typeof q.flow_id === "string"
+                ? normalizeDesktopFlowId(q.flow_id)
+                : undefined;
+            if (method === "POST" && (!desktop || !flowId)) {
+                setResponseStatus(event, 400);
+                return { error: "Invalid desktop exchange challenge." };
+            }
+            const requestedVerifier = desktop
+                ? getHeader(event, "x-agent-native-desktop-verifier")
+                : undefined;
+            let desktopVerifierHash;
+            let desktopBrowserBindingHash;
+            if (desktop && (q.flow_id !== undefined || q.verifier !== undefined)) {
+                if (method !== "POST" ||
+                    !flowId ||
+                    !requestedVerifier ||
+                    q.verifier !== undefined ||
+                    q.redirect !== undefined) {
+                    setResponseStatus(event, 400);
+                    return { error: "Invalid desktop exchange challenge." };
+                }
+                try {
+                    desktopBrowserBindingHash =
+                        prepareDesktopOAuthBrowserBinding(event);
+                    desktopVerifierHash = await registerDesktopExchange(flowId, requestedVerifier, desktopBrowserBindingHash);
+                }
+                catch {
+                    setResponseStatus(event, 400);
+                    return { error: "Invalid desktop exchange challenge." };
+                }
+            }
             // Validate the caller's return param up front and only embed it
             // into the OAuth state when it normalises to a non-root path —
             // skip embedding "/" (the default fallback) so the state stays
@@ -2953,7 +3126,9 @@ async function mountBetterAuthRoutes(app, options) {
                 addAccount: false,
                 app: getOAuthStateAppId(),
                 returnUrl,
-                flowId,
+                flowId: flowId ?? undefined,
+                desktopVerifierHash,
+                desktopBrowserBindingHash,
                 signupAttribution,
                 signupAnonymousId,
             });
@@ -3009,7 +3184,7 @@ async function mountBetterAuthRoutes(app, options) {
             try {
                 const query = getQuery(event);
                 const code = query.code;
-                const { redirectUri, desktop, mobile, returnUrl, flowId, signupAttribution, signupAnonymousId, } = decodeOAuthState(query.state, getAppUrl(event, "/_agent-native/google/callback"));
+                const { redirectUri, desktop, mobile, returnUrl, flowId, desktopVerifierHash, desktopBrowserBindingHash, signupAttribution, signupAnonymousId, } = decodeOAuthState(query.state, getAppUrl(event, "/_agent-native/google/callback"));
                 callbackFlowId = flowId;
                 callbackDesktop = desktop ?? false;
                 callbackMobile = mobile ?? false;
@@ -3066,6 +3241,13 @@ async function mountBetterAuthRoutes(app, options) {
                     });
                     return oauthErrorPage(msg);
                 }
+                if (flowId) {
+                    if (!desktopVerifierHash ||
+                        !desktopBrowserBindingHash ||
+                        !matchesDesktopOAuthBrowserBinding(event, desktopBrowserBindingHash)) {
+                        throw new Error("Desktop OAuth browser binding is invalid.");
+                    }
+                }
                 const tokenRes = await fetch("https://oauth2.googleapis.com/token", {
                     method: "POST",
                     headers: {
@@ -3140,7 +3322,10 @@ async function mountBetterAuthRoutes(app, options) {
                     emailDomain: email.split("@")[1] || "",
                 });
                 if (flowId && sessionToken) {
-                    setDesktopExchange(flowId, sessionToken, email);
+                    if (!desktopVerifierHash) {
+                        throw new Error("Missing desktop exchange challenge.");
+                    }
+                    await setDesktopExchange(flowId, sessionToken, email, desktopVerifierHash);
                     logGoogleOAuthDebug(event, "callback-exchange-stored", {
                         flowId,
                         desktop,
@@ -3186,79 +3371,110 @@ async function mountBetterAuthRoutes(app, options) {
             setResponseStatus(event, 400);
             return { error: "Missing flow_id" };
         }
-        const verifier = normalizeDesktopFlowVerifier(getQuery(event).verifier);
-        let entry = _desktopExchanges.get(flowId);
-        if (!entry || entry.expiresAt < Date.now()) {
-            const challenge = await readDesktopMagicLinkChallengeFromDB(flowId);
-            if (challenge) {
-                if (!verifier ||
-                    !matchesDesktopFlowVerifier(verifier, challenge.verifierHash)) {
-                    setResponseStatus(event, 403);
-                    return { error: "Invalid desktop exchange verifier." };
-                }
-                return { pending: true, flow: oauthDebugFlowId(flowId) };
-            }
-            // In-memory miss — fall back to the DB-persisted entry. This handles
-            // cross-instance routing (Cloudflare Workers, multi-region) where the
-            // OAuth callback and the polling request may hit different isolates.
-            const fromDb = await consumeDesktopExchangeFromDB(flowId);
-            if (!fromDb) {
-                // Don't log on the pending path — clients poll every second for up
-                // to 5 minutes, so logging here floods telemetry. The auth-url,
-                // callback-start, callback-session-created, exchange-success, and
-                // exchange-error breadcrumbs already cover every meaningful state
-                // transition.
-                return { pending: true, flow: oauthDebugFlowId(flowId) };
+        if (query.verifier !== undefined) {
+            setResponseStatus(event, 400);
+            return {
+                error: "Desktop exchange verifier must use a request header.",
+            };
+        }
+        const verifier = normalizeDesktopFlowVerifier(getHeader(event, "x-agent-native-desktop-verifier"));
+        const cached = _desktopExchanges.get(flowId);
+        if (cached && cached.expiresAt < Date.now()) {
+            _desktopExchanges.delete(flowId);
+        }
+        const current = _desktopExchanges.get(flowId);
+        if (current && "challenge" in current) {
+            if (!verifier ||
+                !matchesDesktopFlowVerifier(verifier, current.verifierHash)) {
+                setResponseStatus(event, 403);
+                return { error: "Invalid desktop exchange verifier." };
             }
-            entry =
-                "error" in fromDb
-                    ? { error: fromDb.error, expiresAt: Date.now() + 1 }
-                    : "challenge" in fromDb
-                        ? {
-                            challenge: true,
-                            verifierHash: fromDb.verifierHash,
-                            expiresAt: Date.now() + 1,
-                        }
-                        : {
-                            token: fromDb.token,
-                            email: fromDb.email,
-                            ...(fromDb.verifierHash
-                                ? { verifierHash: fromDb.verifierHash }
-                                : {}),
-                            expiresAt: Date.now() + 1,
-                        };
-        }
-        if ("challenge" in entry) {
+            return { pending: true, flow: oauthDebugFlowId(flowId) };
+        }
+        if (current && "error" in current) {
+            _desktopExchanges.delete(flowId);
+            removeSession(`dex:${flowId}`).catch((err) => {
+                console.warn("[auth] desktop-exchange DB cleanup failed:", describeDbError(err));
+            });
+            logGoogleOAuthDebug(event, "exchange-error", {
+                flowId,
+                message: current.error.message,
+                code: current.error.code,
+            });
+            setResponseStatus(event, 400);
+            return { error: current.error.message, ...current.error };
+        }
+        // The DB is authoritative for token exchanges. Read and validate before
+        // the conditional delete so malformed rows remain available for
+        // diagnosis and two instances cannot both redeem the same payload.
+        const fromDb = await readDesktopExchangeFromDB(flowId);
+        if (fromDb.status === "missing" || fromDb.status === "unavailable") {
+            // Don't log on the pending path — clients poll every second for up
+            // to 5 minutes, so logging here floods telemetry. The auth-url,
+            // callback-start, callback-session-created, exchange-success, and
+            // exchange-error breadcrumbs already cover every meaningful state
+            // transition.
+            return { pending: true, flow: oauthDebugFlowId(flowId) };
+        }
+        if (fromDb.status === "malformed") {
+            setResponseStatus(event, 500);
+            return {
+                error: "Desktop exchange storage is invalid.",
+                code: "exchange_storage_invalid",
+            };
+        }
+        if ("challenge" in fromDb.entry) {
             if (!verifier ||
-                !matchesDesktopFlowVerifier(verifier, entry.verifierHash)) {
+                !matchesDesktopFlowVerifier(verifier, fromDb.entry.verifierHash)) {
                 setResponseStatus(event, 403);
                 return { error: "Invalid desktop exchange verifier." };
             }
             return { pending: true, flow: oauthDebugFlowId(flowId) };
         }
-        if ("token" in entry && entry.verifierHash) {
+        if ("token" in fromDb.entry &&
+            (!fromDb.entry.verifierHash ||
+                !verifier ||
+                !matchesDesktopFlowVerifier(verifier, fromDb.entry.verifierHash))) {
+            setResponseStatus(event, 403);
+            return { error: "Invalid desktop exchange verifier." };
+        }
+        const consumed = await consumeDesktopExchangeFromDB(flowId);
+        if (consumed.status === "missing" || consumed.status === "unavailable") {
+            return { pending: true, flow: oauthDebugFlowId(flowId) };
+        }
+        if (consumed.status === "malformed") {
+            setResponseStatus(event, 500);
+            return {
+                error: "Desktop exchange storage is invalid.",
+                code: "exchange_storage_invalid",
+            };
+        }
+        if ("challenge" in consumed.entry) {
             if (!verifier ||
-                !matchesDesktopFlowVerifier(verifier, entry.verifierHash)) {
+                !matchesDesktopFlowVerifier(verifier, consumed.entry.verifierHash)) {
                 setResponseStatus(event, 403);
                 return { error: "Invalid desktop exchange verifier." };
             }
+            return { pending: true, flow: oauthDebugFlowId(flowId) };
         }
-        _desktopExchanges.delete(flowId);
-        // Also wipe the DB-persisted entry so it cannot be replayed via the
-        // DB fallback path after in-memory consumption. Best-effort: a dropped
-        // Neon WebSocket rejects with a raw ErrorEvent, and a floating
-        // rejection here surfaces as an unhandled promise rejection.
-        removeSession(`dex:${flowId}`).catch((err) => {
-            console.warn("[auth] desktop-exchange DB cleanup failed:", describeDbError(err));
-        });
-        if ("error" in entry) {
+        if ("error" in consumed.entry) {
             logGoogleOAuthDebug(event, "exchange-error", {
                 flowId,
-                message: entry.error.message,
-                code: entry.error.code,
+                message: consumed.entry.error.message,
+                code: consumed.entry.error.code,
             });
             setResponseStatus(event, 400);
-            return { error: entry.error.message, ...entry.error };
+            return {
+                error: consumed.entry.error.message,
+                ...consumed.entry.error,
+            };
+        }
+        const entry = consumed.entry;
+        if (!verifier ||
+            !entry.verifierHash ||
+            !matchesDesktopFlowVerifier(verifier, entry.verifierHash)) {
+            setResponseStatus(event, 403);
+            return { error: "Invalid desktop exchange verifier." };
         }
         // Make the exchange itself establish the app session. Older clients
         // still make a follow-up /auth/session?_session=... request, but the