use-convex 1.2.0 → 2.0.0

package/README.md

@@ -75,7 +75,7 @@ Args accept the query's `FunctionArgs`, `'skip'`, or a `MaybeRefOrGetter` of eit
 
 - **`'skip'`** — gate on missing ids, feature flags, etc. Keeps the same payload key as empty args so SSR HTML survives.
 - **`authenticated: true`** — skip live subscribe until Convex confirms auth. SSR still snapshots when the JWT cookie is present. Prefer this over wrapping args yourself.
-- **`token`** — authenticated SSR for this call only. Never put JWTs in `runtimeConfig.public`. When `convex.auth.cookie` / HttpOnly auth is set, queries fall back to that cookie.
+- **`token`** — authenticated SSR for this call only. Never put JWTs in `runtimeConfig.public`. Otherwise queries use the session token (Convex Auth SSR mode, or a BYO `convex.auth.cookie`).
 
 Warm a subscription before a screen mounts:
 
@@ -88,13 +88,20 @@ prewarmQuery(api.tasks.list, {})
 Browser-only live map (no SSR). Each value is `data | undefined` (loading) | `Error`. Combine with `useConvexQuery` when you need an SSR snapshot for known queries.
 
 ```ts
-const results = useConvexQueries(() => ({
-  tasks: { query: api.tasks.list, args: {} },
-  files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
-}))
+const results = useConvexQueries(
+  () => ({
+    tasks: { query: api.tasks.list, args: {} },
+    files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
+    // Per-entry gate (overrides the options bag when set):
+    // admin: { query: api.admin.stats, args: {}, authenticated: true },
+  }),
+  { authenticated: true }, // wait for Convex auth before any subscribe
+)
 // results.value.tasks
 ```
 
+`'skip'` still wins for missing ids / feature flags. Prefer `{ authenticated: true }` over wrapping every private entry yourself.
+
 ### Pagination
 
 ```ts
@@ -126,6 +133,12 @@ const { run, pending, error } = useConvexAction(api.tasks.shout)
 const shouted = await run({ text: 'hello' }) // browser-only
 ```
 
+`useConvexAction` calls `ConvexClient.action`. Actions from one client run in parallel with each other and with mutations. If a later call depends on an earlier one, await the earlier call before starting the next.
+
+A failed action stays failed: Convex leaves retry to the caller, because the action may already have performed a side effect. `run` throws and sets `error`. Retry from your code when repeating the action is safe.
+
+Use `useConvexAction` (and `fetchAction`) for work the user is waiting on. For durable work, write the user's intent in a mutation and schedule an `internalAction` from that mutation.
+
 For paginated lists:
 
 ```ts
@@ -183,30 +196,64 @@ That runs `generateUploadUrl` → `PUT` to the signed URL → `syncMetadata({ ke
 
 ## Auth
 
-### Convex Auth
+### Convex Auth (v2)
+
+First-party support for [Convex Auth v2](https://docs.convex.dev/auth/convex-auth/) (`@convex-dev/auth@^2`), built on its framework-agnostic `AuthClient` (`@convex-dev/auth/browser`) and SSR handlers (`@convex-dev/auth/ssr`). Requires `convex@^1.48`.
 
-Opt in with `provider: 'convex-auth'`. The module hydrates tokens, finishes OAuth `?code=` callbacks, and wires `setAuth`. Forms only call `signIn` / `signOut`.
+```bash
+npm i @convex-dev/auth
+```
 
 ```ts
 convex: {
   url: process.env.NUXT_PUBLIC_CONVEX_URL,
   auth: {
     provider: 'convex-auth',
-    // cookie defaults to 'convex_jwt'
+    // Every Convex function that can issue a session. The SSR auth proxy refuses the rest.
+    signIn: ['auth:signInWithUsernamePassword', 'auth:signUpWithUsernamePassword'],
+    // mode: 'ssr',                       // default; or 'spa'
+    // api: { refreshSession, signOut, isAuthenticated }, // default 'auth:<name>'
+    // routePrefix: '/api/convex/auth',
+    // cookieOptions: { secure, domain, path },
+    // allowedOrigins: ['https://app.example.com'],
+    // storage: 'localStorage',           // or 'inMemory'
+    // storageNamespace: 'myapp',         // default = deployment URL
+    // verbose: false,
   },
 }
 ```
 
+**Session models**
+
+| `mode`          | Refresh token                      | Sign-in calls                       | SSR                                                 |
+| --------------- | ---------------------------------- | ----------------------------------- | --------------------------------------------------- |
+| `ssr` (default) | httpOnly cookie, set by Nitro      | `POST <prefix>/signin` (auth proxy) | Authenticated; access token refreshed by middleware |
+| `spa`           | `localStorage` (or custom storage) | Straight to Convex                  | Signed out until the client restores                |
+
+In SSR mode the module mounts `<prefix>/signin`, `<prefix>/refresh` and `<prefix>/signout` (Convex Auth's `setupConvexAuthServer` handlers, with their CSRF origin check) and a Nitro middleware. Access tokens live 60 seconds, so the middleware refreshes an expiring token from the refresh cookie before SSR queries run, rotates both cookies, and hands the fresh token to the client payload. `signIn`, `allowedOrigins` and `cookieOptions` are server-only (`runtimeConfig.convexAuth`).
+
+**Sign in.** Each v2 method exports its own typed functions. `useConvexSignIn` runs any of them through the right transport and adopts the session it returns:
+
 ```vue
 <script setup lang="ts">
-const { signIn, signOut } = useAuth()
+import { api } from '~~/convex/_generated/api'
+
+const { run: signIn, pending } = useConvexSignIn(api.auth.signInWithUsernamePassword)
+const { signOut, showAuthedUi } = useAuth()
+
+async function submit() {
+  const result = await signIn({ username, password })
+  if (result.status === 'error') {
+    // result.userError.error: 'INVALID_CREDENTIALS' | 'RATE_LIMITED' | … | 'OTHER_ERROR'
+  }
+}
 </script>
 
 <template>
   <AuthLoading>Resolving…</AuthLoading>
   <AuthRefreshing>Refreshing session…</AuthRefreshing>
   <Authenticated>
-    <!-- signed-in shell -->
+    <button @click="signOut()">Sign out</button>
   </Authenticated>
   <Unauthenticated>
     <!-- sign-in form -->
@@ -214,32 +261,56 @@ const { signIn, signOut } = useAuth()
 </template>
 ```
 
-Prefer `<Authenticated>` (or `showAuthedUi`) so SSR HTML does not flash the sign-in form. Gate private queries with `{ authenticated: true }`. `<AuthRefreshing>` shows only while an authenticated session is refreshing a rejected token (same as React).
+Pass `{ kind: 'action' }` when a sign-in function is an action (function kinds are type-only).
+
+**OAuth** (GitHub, Google, Apple). Starting a flow navigates to the provider. The callback (`?convexAuthCode=`) is finished on whichever page it lands, and the params are stripped from the URL and from `vue-router`:
 
 ```ts
-await signIn('password', { email, password, flow: 'signIn' })
-await signIn('github') // OAuth redirect; the plugin finishes on ?code=
-await signOut()
+const { signIn } = useOAuthSignIn({
+  providerName: 'github',
+  startSignIn: api.auth.startSignInWithGithub,
+  completeSignIn: api.auth.completeSignInWithGithub, // list it in `signIn` for SSR mode
+})
+await signIn() // or signIn({ redirectTo: '/after-login' })
+
+const { flowError } = useOAuth() // ACCESS_DENIED | EXPIRED | INVALID_FLOW | OTHER_ERROR
 ```
 
-You still own the Convex backend:
+`useAuth()` returns `isLoading`, `isAuthenticated`, `isRefreshing`, `hasSsrSession`, `showAuthedUi`, `token`, `setSession(bundle)` and `signOut()`. While signed in, the client subscribes to your `isAuthenticated` query, so a session revoked on the server signs the browser out right away.
 
-- `convex/auth.ts` — `convexAuth({ providers })` exporting `auth`, `signIn`, `signOut`
-- `convex/schema.ts` — spread `authTables`
-- `convex/http.ts` — `auth.addHttpRoutes(http)` (required for OAuth / magic links)
-- `convex/auth.config.ts` — JWT issuer (`CONVEX_SITE_URL`)
-- Env: `JWT_PRIVATE_KEY` + `JWKS` (`npx @convex-dev/auth`), plus `SITE_URL` for OAuth
+Prefer `<Authenticated>` (or `showAuthedUi`) so SSR HTML does not flash the sign-in form. Gate private queries with `{ authenticated: true }`.
 
-By default the JWT is a readable cookie (`convex_jwt`) and the refresh token lives in `localStorage`. For production Convex Auth apps, prefer HttpOnly dual cookies:
+For a custom `TokenStorage`, extra ambient sign-ins, or a custom `replaceUrl`, call `configureConvexAuth` from a client plugin that runs first:
 
 ```ts
-auth: {
-  provider: 'convex-auth',
-  httpOnly: true, // JWT + refresh via Nitro `/api/convex/auth/session`
-}
+// plugins/convex-auth-options.client.ts
+export default defineNuxtPlugin({
+  name: 'convex-auth-options',
+  enforce: 'pre',
+  setup() {
+    configureConvexAuth({
+      storage: { getItem, setItem, removeItem }, // may be async
+      // ambientSignIns: [convexOAuth()],       // [] disables OAuth callback handling
+    })
+  },
+})
 ```
 
-A readable `convex_auth_present` marker drives `hasSsrSession` / `showAuthedUi` (UI shell only — **not** authorization). Always gate private live queries with `{ authenticated: true }` (or equivalent). Tokens are HttpOnly cookies; the session API returns the JWT only via same-origin `POST { getToken: true }` for `ConvexClient.setAuth`. That mitigates cookie theft, **not** XSS (any XSS that can call your origin can still obtain a token once the client needs it in memory).
+You own the Convex backend (see the [v2 docs](https://docs.convex.dev/auth/convex-auth/) and `playground/convex`):
+
+- `convex/convex.config.ts`: `app.use(auth)` plus each method's components (e.g. `authPassword`, `authUsername`)
+- `convex/auth.config.ts`: `providers: [convexAuthProvider()]`
+- `convex/auth.ts`: `setupConvexAuth({ component: components.auth })` exporting `signOut`, `refreshSession`, `isAuthenticated`, plus each method's sign-in functions
+- Your own `users` table and a `createUser` callback. No `authTables`, `JWT_PRIVATE_KEY` or `JWKS`.
+
+#### Migrating from v1 (`use-convex` 0.x)
+
+- Backend: follow Convex's [v1 → v2 guide](https://docs.convex.dev/auth/convex-auth/migrating/from-convex-auth-v1).
+- `signIn(provider, params)` is gone. Use `useConvexSignIn(api.auth.<fn>)` or `useOAuthSignIn(refs)`.
+- `useAuth()` no longer returns `signIn`, `pending` or `error`. Sign-in results come back as `{ status, userError }`.
+- Options removed: `httpOnly`, `presentCookie`, `shouldHandleCode` (and `configureConvexAuth({ replaceURL, shouldHandleCode, storageNamespace })`). SSR mode is the default and keeps the refresh token in an httpOnly cookie. `replaceURL` is now `replaceUrl`.
+- `cookie` applies only to bring-your-own providers. Convex Auth uses `__convexAuthJWT` / `__convexAuthRefreshToken`.
+- `/api/convex/auth/session` is replaced by `<prefix>/signin|refresh|signout`. List every session-issuing function in `convex.auth.signIn`.
 
 ### SSR query budget
 
@@ -290,7 +361,7 @@ auth: {
 
 ## Server routes
 
-Nitro helpers are auto-imported in `server/`. Pass the H3 `event` so they resolve the deployment URL and, when a cookie is configured, the JWT:
+Nitro helpers are auto-imported in `server/`. Pass the H3 `event` so they resolve the deployment URL and the session JWT (Convex Auth SSR mode or a BYO cookie):
 
 ```ts
 // server/api/tasks.get.ts
@@ -318,7 +389,9 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
-`fetchAction` uses the same options. Each helper builds a fresh `ConvexHttpClient`. Override with `{ token }` when you already have a JWT. `getConvexToken(event)` reads the cookie without throwing.
+`fetchAction` uses the same options. Each helper builds a fresh `ConvexHttpClient`. Override with `{ token }` when you already have a JWT. Pass `{ adminToken }` (deploy key / admin key) for privileged server tooling — same as Next.js `fetchQuery` (user `token` is ignored when `adminToken` is set). `getConvexToken(event)` reads the cookie without throwing.
+
+`fetchAction` throws on failure. Convex leaves retry to the caller, because the action may already have performed a side effect. Retry in the route when repeating the action is safe. Use `fetchAction` for work the request is waiting on. For durable work, write the intent in a mutation and schedule an `internalAction` from that mutation. Browser actions run in parallel with each other and with mutations; see [Mutations and actions](#mutations-and-actions).
 
 ## Config
 
@@ -328,10 +401,17 @@ convex: {
   server: true, // SSR snapshots; override per query with { server }
   client: { unsavedChangesWarning: false }, // forwarded to new ConvexClient()
   auth: {
-    provider: 'convex-auth',
-    cookie: 'convex_jwt',
-    httpOnly: false,
-    presentCookie: 'convex_auth_present',
+    provider: 'convex-auth', // omit for BYO providers
+    mode: 'ssr', // or 'spa'
+    signIn: ['auth:signInWithUsernamePassword'], // SSR auth proxy allowlist (server-only)
+    // api: { refreshSession: 'auth:refreshSession', signOut: 'auth:signOut', isAuthenticated: 'auth:isAuthenticated' },
+    // routePrefix: '/api/convex/auth',
+    // cookieOptions: { secure: true, domain: undefined, path: '/' },
+    // allowedOrigins: [],
+    // storage: 'localStorage', // or 'inMemory'
+    // storageNamespace: 'myapp',
+    // verbose: false,
+    // cookie: 'convex_jwt', // BYO providers only
   },
 }
 ```
@@ -360,21 +440,20 @@ pnpm install
 
 # Terminal 1 — Convex backend (writes CONVEX_URL to playground/.env.local)
 pnpm run dev:backend
-# first time: npx @convex-dev/auth   # JWT_PRIVATE_KEY + JWKS
 
 # Terminal 2 — Nuxt
 pnpm run dev
 ```
 
-| Route     | What it shows                                         |
-| --------- | ----------------------------------------------------- |
-| `/`       | Shell session: features + composable call-shape demos |
-| `/live`   | SSR snapshot + live overlay (sign up, CRUD todos)     |
-| `/server` | Nitro `fetchQuery` / `fetchMutation` / `fetchAction`  |
-| `/files`  | `useConvexFileUpload` (upload, list, preview, delete) |
-| `/extras` | `live: false`, pagination, action, connection state   |
+| Route     | What it shows                                                         |
+| --------- | --------------------------------------------------------------------- |
+| `/`       | Shell session: features + composable call-shape demos                 |
+| `/live`   | SSR snapshot + live overlay (username + password sign up, CRUD todos) |
+| `/server` | Nitro `fetchQuery` / `fetchMutation` / `fetchAction`                  |
+| `/files`  | `useConvexFileUpload` (upload, list, preview, delete)                 |
+| `/extras` | `live: false`, pagination, action, connection state                   |
 
-On `/server`: `GET /api/health` is public; `GET`/`POST /api/tasks` use the cookie JWT; `POST /api/shout` is a public `fetchAction` demo.
+On `/server`: `GET /api/health` is public; `GET`/`POST /api/tasks` and `POST /api/shout` use the session JWT (refreshed by the Convex Auth middleware). `POST /api/shout` is an authenticated `fetchAction` demo.
 
 ## Releasing
 

package/dist/module.d.mts

@@ -1,64 +1,106 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import * as convex_browser from 'convex/browser';
-export { AuthTokens, SignInResult, UseAuthReturn } from '../dist/runtime/composables/useAuth.js';
+export { ConvexAuthSession, ConvexSignInResult, OAuthCompleteResult, OAuthFlowError, OAuthProviderRefs, OAuthSignInOptions, OAuthStartResult, UseAuthReturn } from '../dist/runtime/composables/useAuth.js';
 export { ConvexQueryArgs, UseConvexQueryOptions, UseConvexQueryReturn } from '../dist/runtime/composables/useConvexQuery.js';
 export { AuthTokenFetcher, UseConvexAuthReturn, UseConvexAuthSetupOptions } from '../dist/runtime/composables/useConvexAuth.js';
 export { OptimisticUpdate, UseConvexMutationOptions } from '../dist/runtime/composables/useConvexMutation.js';
 export { ConvexFileUploadExtraArgs, ConvexFileUploadMeta, UseConvexFileUploadOptions } from '../dist/runtime/composables/useConvexFileUpload.js';
 export { ConvexR2UploadApi, ConvexR2UploadProgress } from '../dist/runtime/composables/useConvexR2Upload.js';
 export { PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, PaginationStatus, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js';
-export { ConvexQueriesRequest, ConvexQueriesResult, ConvexQueryRequestEntry } from '../dist/runtime/composables/useConvexQueries.js';
+export { ConvexQueriesRequest, ConvexQueriesResult, ConvexQueryRequestEntry, UseConvexQueriesOptions } from '../dist/runtime/composables/useConvexQueries.js';
 export { ConvexFetchOptions } from '../dist/runtime/server/fetch.js';
 export { ConvexRef } from '../dist/runtime/utils/functionReference.js';
 export { ConvexAuthContext, ConvexNuxtContext } from '../dist/runtime/utils/context.js';
 export { ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js';
 export { ConvexGate } from '../dist/runtime/composables/useConvexGate.js';
+export { ConvexAmbientSignIn, ConvexAuthClientOptions, ConvexAuthStorageMode, ConvexAuthTokenStorage, configureConvexAuth } from '../dist/runtime/utils/authClientOptions.js';
+export { ConvexAuthServerRuntimeConfig } from '../dist/runtime/utils/authStorage.js';
 
 interface ModuleAuthOptions {
     /**
-     * Opt-in first-party Convex Auth (`@convex-dev/auth`) client.
+     * Opt-in first-party Convex Auth v2 (`@convex-dev/auth@^2`).
      *
-     * When set to `'convex-auth'`, the module registers a client plugin that
-     * hydrates tokens, handles OAuth `?code=` callbacks, and wires
-     * `useConvexAuth({ fetchToken })`. It also auto-imports `useAuth`,
-     * `signIn`, and `signOut` so apps only need forms.
+     * Registers a client plugin built on `AuthClient` from
+     * `@convex-dev/auth/browser` (session restore, refresh, cross-tab sync,
+     * OAuth callbacks, server-side revocation), auto-imports `useAuth`,
+     * `useConvexSignIn`, `useOAuth`, `useOAuthSignIn` and `signOut`, and in
+     * SSR mode mounts the auth routes from `@convex-dev/auth/ssr` in Nitro.
      *
      * Omit for bring-your-own providers (Clerk, Auth0, custom) — wire
      * `useConvexAuth({ fetchToken })` yourself.
      */
     provider?: 'convex-auth';
     /**
-     * Cookie name whose value is a JWT used for authenticated SSR queries.
-     * When set, the server plugin reads this cookie into `ctx.ssrToken` and
-     * `useConvexQuery` falls back to it when `options.token` is omitted.
-     * `useAuth` / `useConvexAuth` expose the presence of this cookie as
-     * `hasSsrSession`.
-     * Nitro `fetch*` helpers also read this cookie when `{ event }` is passed.
+     * Convex Auth session model.
      *
-     * Defaults to `'convex_jwt'` when `provider === 'convex-auth'` and
-     * `httpOnly` is off. With `httpOnly: true`, defaults to `__convexAuthJWT`.
-     * Otherwise off — BYO apps must opt in and write the JWT after sign-in.
+     * - `'ssr'` (default): the refresh token lives in an httpOnly cookie set by
+     *   Nitro; sign-ins go through the auth proxy route; SSR renders
+     *   authenticated. Requires {@link signIn}.
+     * - `'spa'`: tokens live in browser storage and sign-ins go straight to
+     *   Convex. SSR renders signed out.
+     *
+     * @default 'ssr'
      */
-    cookie?: string;
+    mode?: 'ssr' | 'spa';
     /**
-     * Store JWT + refresh tokens in HttpOnly cookies via Nitro
-     * (`/api/convex/auth/session`). Cookies are not readable via
-     * `document.cookie`. Prefer `true` in production.
-     *
-     * Note: ConvexClient still needs the JWT in memory for the WebSocket;
-     * the session route returns it only via same-origin POST `{ getToken: true }`.
-     * HttpOnly mitigates cookie theft, not XSS session theft. The readable
-     * presence cookie drives `hasSsrSession` / `showAuthedUi` (UI only — gate
-     * private queries with `{ authenticated: true }`).
+     * Names of the session functions exported from your Convex auth file
+     * (the result of `setupConvexAuth`).
      *
-     * @default false
+     * @default { refreshSession: 'auth:refreshSession', signOut: 'auth:signOut', isAuthenticated: 'auth:isAuthenticated' }
+     */
+    api?: {
+        refreshSession?: string;
+        signOut?: string;
+        isAuthenticated?: string;
+    };
+    /**
+     * SSR mode: every Convex function that can issue a session (sign-in,
+     * sign-up, OAuth `completeSignIn*`, …), e.g.
+     * `['auth:signInWithUsernamePassword', 'auth:signUpWithUsernamePassword']`.
+     * The auth proxy refuses anything not listed. Stored in private runtime
+     * config (`runtimeConfig.convexAuth.signIn`).
+     */
+    signIn?: string[];
+    /**
+     * SSR mode: path prefix for the Nitro auth routes
+     * (`<prefix>/signin`, `<prefix>/refresh`, `<prefix>/signout`).
+     * @default '/api/convex/auth'
+     */
+    routePrefix?: string;
+    /**
+     * SSR mode: origins trusted by the auth routes' CSRF check besides the
+     * request's own Host (e.g. behind a proxy that rewrites Host).
      */
-    httpOnly?: boolean;
+    allowedOrigins?: string[];
     /**
-     * Readable presence cookie when `httpOnly` is enabled.
-     * @default 'convex_auth_present'
+     * SSR mode: auth cookie attributes. `httpOnly`, `sameSite` and lifetimes
+     * are fixed by Convex Auth. `secure` defaults to true except on localhost.
      */
-    presentCookie?: string;
+    cookieOptions?: {
+        secure?: boolean;
+        domain?: string;
+        path?: string;
+    };
+    /**
+     * Namespace for token storage keys. Non-alphanumeric characters are
+     * ignored. Defaults to the deployment URL.
+     */
+    storageNamespace?: string;
+    /**
+     * Client token storage. `'localStorage'` (default) or `'inMemory'`.
+     * For a custom TokenStorage, call `configureConvexAuth({ storage })` from a
+     * client plugin with `enforce: 'pre'`.
+     * @default 'localStorage'
+     */
+    storage?: 'localStorage' | 'inMemory';
+    /** Log Convex Auth refresh / lifecycle steps to the console. */
+    verbose?: boolean;
+    /**
+     * BYO providers only: cookie whose value is a JWT used for authenticated
+     * SSR queries and Nitro `fetch*` helpers. The app writes it after sign-in.
+     * Ignored with `provider: 'convex-auth'`.
+     */
+    cookie?: string;
 }
 interface ModuleOptions {
     /**

package/dist/module.mjs

@@ -1,8 +1,9 @@
 import { defineNuxtModule, createResolver, addPlugin, addComponent, addServerScanDir, addServerHandler, addImports, addServerImports, addTypeTemplate } from '@nuxt/kit';
 import { defu } from 'defu';
-import { resolveAuthCookieName } from '../dist/runtime/utils/authStorage.js';
+import { isConvexAuth, resolveAuthMode, resolveAuthRoutes } from '../dist/runtime/utils/authStorage.js';
 import { suggestedCloudUrlFromMismatch } from '../dist/runtime/utils/convexDashboard.js';
 import { warnStaleLocalConvexUrl } from '../dist/runtime/utils/errors.js';
+export { configureConvexAuth } from '../dist/runtime/utils/authClientOptions.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -18,10 +19,35 @@ const module$1 = defineNuxtModule({
   },
   setup(options, nuxt) {
     const existing = nuxt.options.runtimeConfig.public.convex;
-    const auth = options.auth ? {
-      ...options.auth,
-      cookie: resolveAuthCookieName(options.auth) ?? options.auth.cookie
-    } : options.auth;
+    const {
+      signIn: authSignIn,
+      allowedOrigins: authAllowedOrigins,
+      cookieOptions: authCookieOptions,
+      ...publicAuth
+    } = options.auth ?? {};
+    const auth = options.auth ? publicAuth : void 0;
+    if (auth && isConvexAuth(auth)) {
+      for (const legacy of ["httpOnly", "presentCookie", "shouldHandleCode"]) {
+        if (legacy in auth) {
+          console.warn(
+            `[use-convex] convex.auth.${legacy} was removed with Convex Auth v2 support. See the README migration notes.`
+          );
+        }
+      }
+      if (resolveAuthMode(auth) === "ssr" && !authSignIn?.length) {
+        console.warn(
+          "[use-convex] convex.auth.signIn is empty: the SSR auth proxy will refuse every sign-in. List your session-issuing functions, e.g. ['auth:signInWithUsernamePassword']."
+        );
+      }
+    }
+    nuxt.options.runtimeConfig.convexAuth = defu(
+      nuxt.options.runtimeConfig.convexAuth ?? {},
+      {
+        signIn: authSignIn ?? [],
+        allowedOrigins: authAllowedOrigins ?? [],
+        cookie: authCookieOptions ?? {}
+      }
+    );
     nuxt.options.runtimeConfig.public.convex = defu(existing ?? {}, {
       url: options.url,
       server: options.server,
@@ -49,7 +75,8 @@ const module$1 = defineNuxtModule({
     }
     const resolver = createResolver(import.meta.url);
     const runtimeDir = resolver.resolve("./runtime");
-    const useConvexAuthProvider = auth?.provider === "convex-auth";
+    const useConvexAuthProvider = isConvexAuth(auth);
+    const useSsrConvexAuth = useConvexAuthProvider && resolveAuthMode(auth) === "ssr";
     nuxt.options.build.transpile.push(runtimeDir);
     nuxt.hooks.hook("nitro:config", (nitroConfig) => {
       nitroConfig.externals ||= {};
@@ -90,10 +117,24 @@ const module$1 = defineNuxtModule({
       });
     }
     addServerScanDir(resolver.resolve("./runtime/server"));
-    addServerHandler({
-      route: "/api/convex/auth/session",
-      handler: resolver.resolve("./runtime/server/api/convex/auth/session")
-    });
+    if (useSsrConvexAuth) {
+      const routes = resolveAuthRoutes(auth);
+      for (const [route, file] of [
+        [routes.signIn, "signin"],
+        [routes.refresh, "refresh"],
+        [routes.signOut, "signout"]
+      ]) {
+        addServerHandler({
+          route,
+          method: "post",
+          handler: resolver.resolve(`./runtime/server/convexAuth/${file}`)
+        });
+      }
+      addServerHandler({
+        middleware: true,
+        handler: resolver.resolve("./runtime/server/convexAuth/session.middleware")
+      });
+    }
     if (nuxt.options.dev) {
       addServerHandler({
         route: "/__convex_devtools",
@@ -179,12 +220,28 @@ const module$1 = defineNuxtModule({
           from: resolver.resolve("./runtime/composables/useAuth")
         },
         {
-          name: "signIn",
+          name: "useConvexSignIn",
           from: resolver.resolve("./runtime/composables/useAuth")
         },
+        {
+          name: "useOAuth",
+          from: resolver.resolve("./runtime/composables/useAuth")
+        },
+        {
+          name: "useOAuthSignIn",
+          from: resolver.resolve("./runtime/composables/useAuth")
+        },
+        {
+          name: "convexOAuth",
+          from: resolver.resolve("./runtime/auth/oauth")
+        },
         {
           name: "signOut",
           from: resolver.resolve("./runtime/composables/useAuth")
+        },
+        {
+          name: "configureConvexAuth",
+          from: resolver.resolve("./runtime/utils/authClientOptions")
         }
       ] : []
     ]);
@@ -224,6 +281,7 @@ const module$1 = defineNuxtModule({
       });
     }
     const contextTypes = resolver.resolve("./runtime/utils/context");
+    const authTypes = resolver.resolve("./runtime/utils/authStorage");
     addTypeTemplate({
       filename: "types/convex-nuxt.d.ts",
       getContents: () => `// Generated by use-convex
@@ -235,14 +293,12 @@ declare module '@nuxt/schema' {
       url?: string
       server?: boolean
       client?: import('convex/browser').ConvexClientOptions
-      auth?: {
-        provider?: 'convex-auth'
-        cookie?: string
-        httpOnly?: boolean
-        presentCookie?: string
-      }
+      auth?: import('${authTypes}').ConvexAuthConfig
     }
   }
+  interface RuntimeConfig {
+    convexAuth: import('${authTypes}').ConvexAuthServerRuntimeConfig
+  }
 }
 
 declare module 'nuxt/app' {

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

@@ -0,0 +1,96 @@
+/**
+ * OAuth ambient sign-in for Convex Auth v2.
+ *
+ * Port of `@convex-dev/auth`'s framework-agnostic OAuth client, which the
+ * package only ships behind its React entry point. Same wire contract:
+ * `startSignIn({ redirectTo })` → `{ redirect, state }`; the state is kept in
+ * the sign-in's storage, and the callback's `convexAuthCode` is redeemed with
+ * `completeSignIn({ code, state })` through the sign-in API (the auth proxy
+ * under SSR).
+ */
+import type { AuthClientConfig } from '@convex-dev/auth/browser';
+import { type FunctionReference } from 'convex/server';
+type AmbientSignIns = NonNullable<AuthClientConfig['ambientSignIns']>;
+export type AmbientSignInClient = AmbientSignIns['signIns'][number];
+export type AmbientSignInContext = Parameters<AmbientSignInClient['setup']>[0];
+/** Callback params written by the Convex Auth OAuth component. */
+export declare const OAUTH_CODE_PARAM = "convexAuthCode";
+export declare const OAUTH_ERROR_PARAM = "convexAuthError";
+export declare const OAUTH_SETUP_ID = "oauth";
+export declare const OAUTH_ACTIONS_KEY = "actions";
+export declare const OAUTH_FLOW_ERROR_KEY = "flowError";
+/** A provider's `startSignIn*` / `completeSignIn*` mutations plus its name. */
+export type OAuthProviderRefs = {
+    /** Label only, e.g. `'github'`. */
+    providerName: string;
+    startSignIn: FunctionReference<'mutation', 'public', {
+        redirectTo: string;
+    }, {
+        redirect: string;
+        state: string;
+    }>;
+    completeSignIn: FunctionReference<'mutation', 'public', {
+        code: string;
+        state: string;
+    }, any>;
+};
+/**
+ * Why a flow failed after the identity provider sent the user back.
+ * Switch on `error` and supply your own copy.
+ */
+export type OAuthFlowError = {
+    error: 'ACCESS_DENIED';
+} | {
+    error: 'EXPIRED';
+} | {
+    error: 'INVALID_FLOW';
+} | {
+    error: 'OTHER_ERROR';
+    cause: unknown;
+};
+export type OAuthStartResult = {
+    status: 'redirect';
+    redirect: URL;
+} | {
+    status: 'error';
+    userError: {
+        error: 'OTHER_ERROR';
+        cause: unknown;
+    };
+};
+export type OAuthCompleteResult = {
+    status: 'complete';
+} | {
+    status: 'error';
+    userError: OAuthFlowError;
+};
+export type OAuthSignInOptions = {
+    /** Where the provider sends the user back. Defaults to the current URL. */
+    redirectTo?: string;
+    /** Finish a flow started elsewhere instead of starting one. */
+    code?: string;
+};
+export type OAuthActions = {
+    signIn: (refs: OAuthProviderRefs, options?: OAuthSignInOptions) => Promise<OAuthStartResult | OAuthCompleteResult>;
+};
+/**
+ * The OAuth ambient sign-in. Registered by default; pass it explicitly via
+ * `configureConvexAuth({ ambientSignIns: [convexOAuth(), …] })` when adding
+ * others.
+ */
+export type ConvexOAuthOptions = {
+    /**
+     * Where to keep the pending flow across the provider redirect, when the
+     * session token storage does not survive navigation (e.g. in-memory
+     * tokens). Defaults to the client's token storage.
+     */
+    flowStorage?: {
+        getItem: (key: string) => string | null | undefined | Promise<string | null | undefined>;
+        setItem: (key: string, value: string) => void | Promise<void>;
+        removeItem: (key: string) => void | Promise<void>;
+    };
+    /** Key namespace for `flowStorage`, typically the deployment URL. */
+    namespace?: string;
+};
+export declare function convexOAuth(options?: ConvexOAuthOptions): AmbientSignInClient;
+export {};