use-convex 1.2.0 → 2.0.0

package/dist/runtime/composables/useConvexQuery.js

@@ -1,3 +1,4 @@
+import { sessionKeyFromToken } from "../utils/authStorage.js";
 import { convexToJson, jsonToConvex } from "convex/values";
 import { useAsyncData, useRuntimeConfig } from "nuxt/app";
 import {
@@ -47,7 +48,11 @@ export async function useConvexQuery(query, args = {}, options = {}) {
         () => toValue(args),
         // Re-run HttpClient snapshot when the SSR JWT cookie / token changes
         // (e.g. after sign-in with live:false, or Refresh).
-        () => options.token ?? ctx.ssrToken.value,
+        // Session identity (JWT iss + sub), not the raw token: Convex Auth
+        // rotates the access token every minute without changing session,
+        // but switching accounts must re-run the snapshot (`live: false`
+        // and BYO cookies included).
+        () => sessionKeyFromToken(options.token ?? ctx.ssrToken.value),
         // Re-run when auth confirms *and* a JWT is available for HttpClient
         // (readable cookie / SSR). Avoids anonymous client refetches with HttpOnly.
         () => requireAuth && ctx.auth.isAuthenticated.value && !!(options.token ?? ctx.ssrToken.value)

package/dist/runtime/plugin.auth.client.d.ts

@@ -1,8 +1,13 @@
 /**
- * First-party Convex Auth wiring (opt-in via `convex.auth.provider: 'convex-auth'`).
+ * First-party Convex Auth v2 wiring (`convex.auth.provider: 'convex-auth'`).
  *
- * Must stay synchronous through `useConvexAuth` / `inject` — awaiting first
- * drops Vue setup context and caused the "plugin did not start" 500.
+ * Builds an `AuthClient` from `@convex-dev/auth/browser` in SSR mode (refresh
+ * token in an httpOnly cookie, sign-ins through the Nitro auth proxy) or SPA
+ * mode (tokens in browser storage, sign-ins straight to the deployment),
+ * then hands its token to `useConvexAuth` and watches `isAuthenticated` so a
+ * session revoked server-side signs the client out.
+ *
+ * Setup stays synchronous so `useConvexAuth` keeps the Nuxt app context.
  */
 declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/plugin.auth.client.js

@@ -1,41 +1,226 @@
+import { AuthClient, InMemoryStorage, defaultStorage } from "@convex-dev/auth/browser";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
 import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+import { readonly, shallowRef, watch } from "vue";
 import { useConvexAuth } from "./composables/useConvexAuth.js";
 import {
-  consumeOAuthCodeFromUrl,
-  getAuthToken,
-  hasPendingOAuthCallback,
-  hydrateAuthFromStorage,
-  useAuthProviderState
-} from "./composables/useAuth.js";
-import { tryUseConvexContext } from "./utils/context.js";
+  OAUTH_CODE_PARAM,
+  OAUTH_ERROR_PARAM,
+  convexOAuth
+} from "./auth/oauth.js";
+import { postAuth, retryingTokenFetcher } from "./auth/sessionRoutes.js";
+import { getConvexAuthClientOptions } from "./utils/authClientOptions.js";
+import { useConvexAuthTokenState } from "./utils/authCookie.js";
+import {
+  isConvexAuth,
+  resolveAuthApiNames,
+  resolveAuthMode,
+  resolveAuthRoutes
+} from "./utils/authStorage.js";
+import {
+  tryUseConvexContext
+} from "./utils/context.js";
+function sessionStorageOrUndefined() {
+  try {
+    return typeof window !== "undefined" ? window.sessionStorage : void 0;
+  } catch {
+    return void 0;
+  }
+}
 export default defineNuxtPlugin({
   name: "convex-nuxt-auth",
   dependsOn: ["convex-nuxt-client"],
-  setup() {
+  setup(nuxtApp) {
     const config = useRuntimeConfig();
     const convexConfig = config.public.convex;
-    if (!convexConfig?.url) {
+    const auth = convexConfig?.auth;
+    if (!convexConfig?.url || !isConvexAuth(auth)) {
       return;
     }
-    if (!tryUseConvexContext()) {
+    const ctx = tryUseConvexContext();
+    const convex = ctx?.client;
+    if (!ctx || !convex) {
       return;
     }
-    const pendingOAuth = hasPendingOAuthCallback();
-    if (!pendingOAuth) {
-      hydrateAuthFromStorage();
-    }
-    const { isLoading, hasSession } = useAuthProviderState();
-    useConvexAuth({
-      fetchToken: ({ forceRefreshToken }) => getAuthToken({ forceRefreshToken }),
-      isLoading,
-      isAuthenticated: hasSession
+    const mode = resolveAuthMode(auth);
+    const apiNames = resolveAuthApiNames(auth);
+    const baseURL = config.app?.baseURL ?? "/";
+    const routes = resolveAuthRoutes(auth);
+    const route = (path) => baseURL.replace(/\/+$/, "") + path;
+    const options = getConvexAuthClientOptions();
+    const tokenState = useConvexAuthTokenState();
+    const storage = options.storage ?? (auth?.storage === "inMemory" ? new InMemoryStorage() : defaultStorage());
+    const storageNamespace = auth?.storageNamespace ?? ctx.url;
+    const replaceUrl = options.replaceUrl ?? ((url) => {
+      window.history.replaceState(window.history.state, "", url);
+      const router = nuxtApp.$router;
+      void router?.isReady().then(() => {
+        const current = router.currentRoute.value;
+        if (!(OAUTH_CODE_PARAM in current.query) && !(OAUTH_ERROR_PARAM in current.query)) {
+          return;
+        }
+        const query = { ...current.query };
+        delete query[OAUTH_CODE_PARAM];
+        delete query[OAUTH_ERROR_PARAM];
+        void router.replace({ path: current.path, query, hash: current.hash });
+      });
     });
-    if (pendingOAuth) {
-      void consumeOAuthCodeFromUrl().then((ok) => {
-        if (!ok) {
-          hydrateAuthFromStorage();
+    const flowStorage = !options.storage && auth?.storage === "inMemory" ? sessionStorageOrUndefined() : void 0;
+    const signIns = options.ambientSignIns ?? [
+      convexOAuth(flowStorage ? { flowStorage, namespace: storageNamespace } : {})
+    ];
+    const convexMutationApi = {
+      mutation: (fn, args) => convex.mutation(fn, args)
+    };
+    let authClient;
+    let signInApi;
+    if (mode === "ssr") {
+      const proxy = new ConvexHttpClient(`${route(routes.signIn)}?path=`, {
+        skipConvexDeploymentUrlCheck: true
+      });
+      const withAuth = () => {
+        const token = authClient.getAccessToken();
+        if (token !== null) {
+          proxy.setAuth(token);
+        } else {
+          proxy.clearAuth();
+        }
+        return proxy;
+      };
+      signInApi = {
+        mutation: (fn, args) => withAuth().mutation(fn, args),
+        action: (fn, args) => withAuth().action(fn, args)
+      };
+      authClient = new AuthClient({
+        mode: "ssr",
+        authApi: {
+          refreshSession: async () => (await postAuth(route(routes.refresh))).tokens,
+          signOut: async () => {
+            await postAuth(route(routes.signOut));
+          }
+        },
+        storage,
+        storageNamespace,
+        // The server refreshed on our behalf, so this is the freshest token.
+        initialAccessToken: tokenState.value,
+        verbose: auth?.verbose,
+        ambientSignIns: {
+          signIns,
+          signInApi,
+          convex: convexMutationApi,
+          replaceUrl
         }
       });
+    } else {
+      const http = new ConvexHttpClient(ctx.url);
+      const refreshSession = makeFunctionReference(apiNames.refreshSession);
+      const signOutRef = makeFunctionReference(apiNames.signOut);
+      signInApi = {
+        mutation: (fn, args) => convex.mutation(fn, args),
+        action: (fn, args) => convex.action(fn, args)
+      };
+      authClient = new AuthClient({
+        mode: "spa",
+        authApi: {
+          refreshSession: (refreshToken) => http.mutation(refreshSession, { refreshToken }),
+          signOut: async (refreshToken) => {
+            await http.mutation(signOutRef, { refreshToken });
+          }
+        },
+        storage,
+        storageNamespace,
+        verbose: auth?.verbose,
+        ambientSignIns: {
+          signIns,
+          signInApi,
+          convex: convexMutationApi,
+          replaceUrl
+        }
+      });
+    }
+    const state = shallowRef(authClient.getSnapshot());
+    authClient.subscribe(() => {
+      state.value = authClient.getSnapshot();
+    });
+    const syncTokenState = () => {
+      if (!state.value.isLoading) {
+        tokenState.value = state.value.token;
+      }
+    };
+    if (nuxtApp.isHydrating) {
+      nuxtApp.hooks.hookOnce("app:suspense:resolve", () => {
+        syncTokenState();
+        watch(state, syncTokenState);
+      });
+    } else {
+      watch(state, syncTokenState, { immediate: true });
     }
+    const ambientCache = /* @__PURE__ */ new Map();
+    const ambientValue = (id, key) => {
+      const cacheKey = `${id}:${key}`;
+      let cached = ambientCache.get(cacheKey);
+      if (!cached) {
+        const reader = authClient.ambientSignInValues(id);
+        const value = shallowRef(reader.get(key));
+        reader.subscribe(key, () => {
+          value.value = reader.get(key);
+        });
+        cached = readonly(value);
+        ambientCache.set(cacheKey, cached);
+      }
+      return cached;
+    };
+    const binding = {
+      mode,
+      state,
+      signInApi,
+      setSession: (session) => authClient.setSession(session),
+      signOut: () => authClient.signOut(),
+      ambientValue
+    };
+    ctx.convexAuth = binding;
+    const convexAuth = useConvexAuth({
+      // A refresh that fails (outage, proxy error) is retried with backoff
+      // rather than thrown into ConvexClient or treated as signed out.
+      fetchToken: retryingTokenFetcher((args) => authClient.fetchAccessToken(args), {
+        hasSession: () => authClient.getAccessToken() !== null,
+        onRetry: (error, delayMs) => {
+          if (import.meta.dev || auth?.verbose) {
+            console.warn(`[use-convex] Session refresh failed; retrying in ${delayMs}ms.`, error);
+          }
+        }
+      }),
+      isLoading: () => state.value.isLoading,
+      isAuthenticated: () => state.value.isAuthenticated
+    });
+    const isAuthenticatedRef = makeFunctionReference(
+      apiNames.isAuthenticated
+    );
+    let stopWatching = null;
+    watch(
+      () => convexAuth.isAuthenticated.value,
+      (authenticated) => {
+        stopWatching?.();
+        stopWatching = null;
+        if (!authenticated) {
+          return;
+        }
+        const unsubscribe = convex.onUpdate(
+          isAuthenticatedRef,
+          {},
+          (hasLiveSession) => {
+            if (hasLiveSession === false) {
+              void authClient.signOut();
+            }
+          },
+          () => {
+          }
+        );
+        stopWatching = () => unsubscribe();
+      },
+      { immediate: true }
+    );
+    void authClient.init();
   }
 });

package/dist/runtime/plugin.server.js

@@ -1,5 +1,6 @@
-import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
-import { useSsrTokenRef } from "./utils/authCookie.js";
+import { defineNuxtPlugin, useRequestEvent, useRuntimeConfig } from "nuxt/app";
+import { useConvexAuthTokenState, useSsrTokenRef } from "./utils/authCookie.js";
+import { isSsrConvexAuth } from "./utils/authStorage.js";
 import { createHttpClient } from "./utils/http.js";
 import { convexNuxtKey, createAuthContext } from "./utils/context.js";
 import { warnMissingConvexUrl } from "./utils/errors.js";
@@ -15,6 +16,11 @@ export default defineNuxtPlugin({
       }
       return;
     }
+    if (isSsrConvexAuth(convexConfig?.auth)) {
+      const event = useRequestEvent();
+      const token = event?.context?.convexAuthToken;
+      useConvexAuthTokenState().value = token ?? null;
+    }
     const ssrToken = useSsrTokenRef();
     const auth = createAuthContext();
     if (ssrToken.value) {

package/dist/runtime/server/auth.d.ts

@@ -1,7 +1,12 @@
 import type { H3Event } from 'h3';
 /**
- * Read the Convex JWT from the configured auth cookie on this request.
- * Returns `undefined` when the cookie is missing or auth cookies are disabled.
+ * Read the Convex JWT for this request.
+ *
+ * - Convex Auth (SSR mode): the access token the session middleware
+ *   refreshed for this request, else the access-token cookie while valid.
+ * - BYO providers: the configured `convex.auth.cookie`.
+ *
+ * Returns `undefined` when there is no session or auth cookies are disabled.
  */
 export declare function getConvexToken(event: H3Event): string | undefined;
 /**

package/dist/runtime/server/auth.js

@@ -1,16 +1,27 @@
 import { createError, getCookie } from "h3";
-import { resolveAuthCookieName } from "../utils/authStorage.js";
+import { isJwtExpiring, isSsrConvexAuth, resolveAuthCookieName } from "../utils/authStorage.js";
 import { resolveFetchToken } from "../utils/fetchToken.js";
 import { readConvexConfig } from "./convexConfig.js";
 export function getConvexToken(event) {
-  const cookieName = resolveAuthCookieName(readConvexConfig(event)?.auth);
+  const auth = readConvexConfig(event)?.auth;
+  if (isSsrConvexAuth(auth)) {
+    const fromMiddleware = event.context.convexAuthToken;
+    if (fromMiddleware !== void 0) {
+      return fromMiddleware ?? void 0;
+    }
+  }
+  const cookieName = resolveAuthCookieName(auth);
   if (!cookieName) {
     return void 0;
   }
-  return resolveFetchToken({
+  const token = resolveFetchToken({
     cookieName,
     cookieValue: getCookie(event, cookieName)
   });
+  if (token && isSsrConvexAuth(auth) && isJwtExpiring(token, 0)) {
+    return void 0;
+  }
+  return token;
 }
 export function requireConvexAuth(event) {
   const token = getConvexToken(event);

package/dist/runtime/server/convexAuth/refresh.d.ts

@@ -0,0 +1,3 @@
+/** Convex Auth v2 `refreshHandler` from `@convex-dev/auth/ssr`. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/convexAuth/refresh.js

@@ -0,0 +1,5 @@
+import { defineEventHandler } from "h3";
+import { runWebHandler, useConvexAuthServer } from "./setup.js";
+export default defineEventHandler(
+  (event) => runWebHandler(event, useConvexAuthServer(event).refreshHandler)
+);

package/dist/runtime/server/convexAuth/session.middleware.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve the Convex Auth access token for this request (SSR mode).
+ *
+ * Access tokens live ~60s, so most page loads find an expired one: refresh
+ * from the httpOnly refresh cookie, rotate both cookies on the response, and
+ * leave the fresh token on `event.context.convexAuthToken` for SSR queries,
+ * `getConvexToken`, and the Nitro `fetch*` helpers.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/convexAuth/session.middleware.js

@@ -0,0 +1,37 @@
+import { defineEventHandler, getCookie, getRequestURL } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import {
+  CONVEX_AUTH_JWT_COOKIE,
+  CONVEX_AUTH_REFRESH_COOKIE,
+  DEFAULT_AUTH_ROUTE_PREFIX,
+  isJwtExpiring
+} from "../../utils/authStorage.js";
+import { createServerAuthSession } from "./setup.js";
+export default defineEventHandler(async (event) => {
+  const context = event.context;
+  if (context.convexAuthToken !== void 0) {
+    return;
+  }
+  const pathname = getRequestURL(event).pathname;
+  const config = useRuntimeConfig(event);
+  const baseURL = (config.app?.baseURL ?? "/").replace(/\/+$/, "");
+  const auth = config.public?.convex?.auth;
+  const prefix = baseURL + (auth?.routePrefix ?? DEFAULT_AUTH_ROUTE_PREFIX).replace(/\/+$/, "");
+  if (pathname.startsWith(prefix + "/") || // Build assets and dev tooling never need a session. Other paths with a
+  // dot (`/users/jane.doe`, `/api/report.json`) are pages and endpoints
+  // that may. Files in `public/` are served by Nitro before middleware.
+  pathname.startsWith(`${baseURL}/_nuxt/`) || pathname.startsWith(`${baseURL}/__nuxt_devtools__`) || pathname.startsWith(`${baseURL}/__convex_devtools`) || pathname === `${baseURL}/favicon.ico`) {
+    return;
+  }
+  const jwt = getCookie(event, CONVEX_AUTH_JWT_COOKIE) || null;
+  const refresh = getCookie(event, CONVEX_AUTH_REFRESH_COOKIE) || null;
+  if (refresh === null) {
+    context.convexAuthToken = jwt !== null && !isJwtExpiring(jwt, 0) ? jwt : null;
+    return;
+  }
+  try {
+    context.convexAuthToken = await createServerAuthSession(event).getToken();
+  } catch {
+    context.convexAuthToken = jwt !== null && !isJwtExpiring(jwt, 0) ? jwt : null;
+  }
+});

package/dist/runtime/server/convexAuth/setup.d.ts

@@ -0,0 +1,21 @@
+import { ServerAuthSession, setupConvexAuthServer, type AuthCookieOptions, type CookieStore } from '@convex-dev/auth/ssr';
+import type { H3Event } from 'h3';
+import { type ConvexAuthServerRuntimeConfig } from '../../utils/authStorage.js';
+export type { ConvexAuthServerRuntimeConfig };
+export declare function resolveCookieOptions(event: H3Event, server: ConvexAuthServerRuntimeConfig): AuthCookieOptions;
+type Handlers = ReturnType<typeof setupConvexAuthServer>;
+/**
+ * `setupConvexAuthServer` built from runtime config, cached per
+ * deployment + cookie attributes (`secure` differs on localhost).
+ */
+export declare function useConvexAuthServer(event: H3Event): Handlers;
+/** Run a WHATWG handler from `@convex-dev/auth/ssr` on an H3 event. */
+export declare function runWebHandler(event: H3Event, handler: (request: Request) => Promise<Response>): Promise<void>;
+/** `CookieStore` over H3 request/response cookies. */
+export declare function h3CookieStore(event: H3Event): CookieStore;
+/**
+ * A `ServerAuthSession` for this request: reads the access/refresh cookies,
+ * refreshes when the access token is missing or near expiry, and writes the
+ * rotated cookies onto the response.
+ */
+export declare function createServerAuthSession(event: H3Event): ServerAuthSession;

package/dist/runtime/server/convexAuth/setup.js

@@ -0,0 +1,90 @@
+import {
+  ServerAuthSession,
+  setupConvexAuthServer
+} from "@convex-dev/auth/ssr";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  createError,
+  deleteCookie,
+  getCookie,
+  getRequestHeader,
+  sendWebResponse,
+  setCookie,
+  toWebRequest
+} from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { MISSING_URL_HINT } from "../../utils/errors.js";
+import {
+  resolveAuthApiNames
+} from "../../utils/authStorage.js";
+function resolveConfig(event) {
+  const config = useRuntimeConfig(event);
+  const pub = config.public?.convex;
+  const convexUrl = pub?.url ?? process.env.NUXT_PUBLIC_CONVEX_URL;
+  if (!convexUrl) {
+    throw createError({ statusCode: 500, message: MISSING_URL_HINT });
+  }
+  return {
+    convexUrl,
+    auth: pub?.auth,
+    server: config.convexAuth ?? {}
+  };
+}
+function isLocalHost(event) {
+  const host = getRequestHeader(event, "host") ?? "";
+  return host.startsWith("localhost") || host.startsWith("127.0.0.1") || host.startsWith("[::1]");
+}
+export function resolveCookieOptions(event, server) {
+  return {
+    secure: server.cookie?.secure ?? !isLocalHost(event),
+    ...server.cookie?.domain ? { domain: server.cookie.domain } : {},
+    ...server.cookie?.path ? { path: server.cookie.path } : {}
+  };
+}
+const cache = /* @__PURE__ */ new Map();
+export function useConvexAuthServer(event) {
+  const { convexUrl, auth, server } = resolveConfig(event);
+  const cookieOptions = resolveCookieOptions(event, server);
+  const api = resolveAuthApiNames(auth);
+  const key = JSON.stringify([convexUrl, api, server, cookieOptions]);
+  let handlers = cache.get(key);
+  if (!handlers) {
+    handlers = setupConvexAuthServer({
+      convexUrl,
+      refreshSession: makeFunctionReference(api.refreshSession),
+      signOut: makeFunctionReference(api.signOut),
+      signIn: (server.signIn ?? []).map((name) => makeFunctionReference(name)),
+      cookieOptions,
+      ...server.allowedOrigins?.length ? { allowedOrigins: server.allowedOrigins } : {}
+    });
+    cache.set(key, handlers);
+  }
+  return handlers;
+}
+export async function runWebHandler(event, handler) {
+  const response = await handler(toWebRequest(event));
+  return sendWebResponse(event, response);
+}
+export function h3CookieStore(event) {
+  return {
+    get: (name) => getCookie(event, name) || void 0,
+    set: (name, value, options) => {
+      setCookie(event, name, value, options);
+    },
+    delete: (name, options) => {
+      deleteCookie(event, name, options);
+    }
+  };
+}
+export function createServerAuthSession(event) {
+  const { convexUrl, auth, server } = resolveConfig(event);
+  const api = resolveAuthApiNames(auth);
+  const http = new ConvexHttpClient(convexUrl);
+  const refreshSession = makeFunctionReference(api.refreshSession);
+  return new ServerAuthSession({
+    refreshSession: (refreshToken) => http.mutation(refreshSession, { refreshToken }),
+    cookies: h3CookieStore(event),
+    cookieOptions: resolveCookieOptions(event, server)
+  });
+}

package/dist/runtime/server/convexAuth/signin.d.ts

@@ -0,0 +1,3 @@
+/** Convex Auth v2 `convexProxyHandler` from `@convex-dev/auth/ssr`. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/convexAuth/signin.js

@@ -0,0 +1,5 @@
+import { defineEventHandler } from "h3";
+import { runWebHandler, useConvexAuthServer } from "./setup.js";
+export default defineEventHandler(
+  (event) => runWebHandler(event, useConvexAuthServer(event).convexProxyHandler)
+);

package/dist/runtime/server/convexAuth/signout.d.ts

@@ -0,0 +1,3 @@
+/** Convex Auth v2 `signOutHandler` from `@convex-dev/auth/ssr`. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/convexAuth/signout.js

@@ -0,0 +1,5 @@
+import { defineEventHandler } from "h3";
+import { runWebHandler, useConvexAuthServer } from "./setup.js";
+export default defineEventHandler(
+  (event) => runWebHandler(event, useConvexAuthServer(event).signOutHandler)
+);

package/dist/runtime/server/convexConfig.d.ts

@@ -1,12 +1,8 @@
 import type { H3Event } from 'h3';
+import type { ConvexAuthConfig } from '../utils/authStorage.js';
 export interface ConvexPublicConfig {
     url?: string;
-    auth?: {
-        provider?: string;
-        cookie?: string;
-        httpOnly?: boolean;
-        presentCookie?: string;
-    };
+    auth?: ConvexAuthConfig;
 }
 /** Read `runtimeConfig.public.convex`, or `undefined` outside a Nitro request. */
 export declare function readConvexConfig(event?: H3Event): ConvexPublicConfig | undefined;

package/dist/runtime/server/fetch.d.ts

@@ -8,9 +8,17 @@ export interface ConvexFetchOptions {
     url?: string;
     /**
      * JWT for this call. Prefer per-request tokens — never put JWTs in public config.
-     * When omitted and `event` is passed, falls back to `convex.auth.cookie` if set.
+     * When omitted and `event` is passed, falls back to the request's session
+     * (Convex Auth SSR mode) or `convex.auth.cookie` (BYO).
+     * Ignored when {@link adminToken} is set (admin auth clears user JWT).
      */
     token?: string;
+    /**
+     * Deploy / admin key for privileged server tooling (Next.js `fetchQuery`
+     * parity). Calls `ConvexHttpClient.setAdminAuth`. Never put this in public
+     * runtime config — pass per request from a server secret.
+     */
+    adminToken?: string;
     /**
      * Nitro/H3 event. Used to resolve runtimeConfig and the optional auth cookie.
      */

package/dist/runtime/server/fetch.js

@@ -1,6 +1,5 @@
-import { getCookie } from "h3";
 import { createHttpClient } from "../utils/http.js";
-import { resolveAuthCookieName } from "../utils/authStorage.js";
+import { getConvexToken } from "./auth.js";
 import { resolveFetchToken } from "../utils/fetchToken.js";
 import { missingConvexUrlError } from "../utils/errors.js";
 import { readConvexConfig } from "./convexConfig.js";
@@ -22,19 +21,17 @@ export function resolveToken(options) {
   if (options.token !== void 0) {
     return resolveFetchToken({ token: options.token });
   }
-  const cookieName = resolveAuthCookieName(readConvexConfig(options.event)?.auth);
-  if (!cookieName || !options.event) {
+  if (!options.event) {
     return void 0;
   }
-  return resolveFetchToken({
-    cookieName,
-    cookieValue: getCookie(options.event, cookieName)
-  });
+  return getConvexToken(options.event);
 }
 function setupClient(options = {}) {
+  const token = options.adminToken ? void 0 : resolveToken(options);
   return createHttpClient(resolveUrl(options), {
-    token: resolveToken(options),
-    skipConvexDeploymentUrlCheck: options.skipConvexDeploymentUrlCheck
+    ...token ? { token } : {},
+    ...options.adminToken ? { adminToken: options.adminToken } : {},
+    ...options.skipConvexDeploymentUrlCheck !== void 0 ? { skipConvexDeploymentUrlCheck: options.skipConvexDeploymentUrlCheck } : {}
   });
 }
 export async function fetchQuery(query, args, options) {