Pass authUserId to createOrUpdateUser

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rorhug

docs/pages/advanced.mdx

@@ -89,6 +89,12 @@ export const { auth, signIn, signOut, store, isAuthenticated } = {
         return args.existingUserId;
       }
 
+      if (args.authUserId) {
+        // During OAuth account linking, attach the new account to the
+        // currently authenticated user who started the flow.
+        return args.authUserId;
+      }
+
       // Implement your own account linking logic:
       const existingUser = await findUserByEmail(ctx, args.profile.email);
       if (existingUser) return existingUser._id;
@@ -102,6 +108,10 @@ export const { auth, signIn, signOut, store, isAuthenticated } = {
 };
 ```
 
+`args.existingUserId` is the user already linked to the account being signed in,
+if one exists. `args.authUserId` identifies the currently authenticated user so
+you can link the new OAuth account to them. This is useful for OAuth flows started while signed in.
+
 When you provide this callback, the library doesn't create or update users at
 all. It is up to you to implement all the necessary logic for all providers you
 use.
@@ -123,7 +133,7 @@ import { MutationCtx } from "./_generated/server";
 export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
   providers: [GitHub, Password],
   callbacks: {
-    // `args` are the same the as for `createOrUpdateUser` but include `userId`
+    // `args` are the same as for `createOrUpdateUser` but include `userId`
     async afterUserCreatedOrUpdated(ctx: MutationCtx, { userId }) {
       await ctx.db.insert("someTable", { userId, data: "some data" });
     },

src/server/implementation/users.ts

@@ -55,10 +55,15 @@ async function defaultCreateOrUpdateUser(
     args,
   });
   const existingUserId = existingAccount?.userId ?? null;
+  const authUserId =
+    existingSessionId !== null
+      ? (await ctx.db.get(existingSessionId))?.userId ?? null
+      : null;
   if (config.callbacks?.createOrUpdateUser !== undefined) {
     logWithLevel(LOG_LEVELS.DEBUG, "Using custom createOrUpdateUser callback");
     return await config.callbacks.createOrUpdateUser(ctx, {
       existingUserId,
+      authUserId,
       ...args,
     });
   }

src/server/types.ts

@@ -167,6 +167,11 @@ export type ConvexAuthConfig = {
          * this is the existing user ID linked to that account.
          */
         existingUserId: GenericId<"users"> | null;
+        /**
+         * If this OAuth flow was started while a user was already signed in,
+         * this is that authenticated user ID recovered from the saved session.
+         */
+        authUserId: GenericId<"users"> | null;
         /**
          * The provider type or "verification" if this callback is called
          * after an email or phone token verification.

test/convex/createOrUpdateUser.test.ts

@@ -0,0 +1,134 @@
+/// <reference types="vite/client" />
+import GitHub from "@auth/core/providers/github";
+import { convexTest } from "convex-test";
+import { decodeJwt } from "jose";
+import { Password } from "../../src/providers/Password";
+import { convexAuth } from "../../src/server";
+import { expect, test } from "vitest";
+import { api } from "./_generated/api";
+import schema from "./schema";
+import {
+  CONVEX_SITE_URL,
+  JWKS,
+  JWT_PRIVATE_KEY,
+  signInViaGitHub,
+} from "./test.helpers";
+
+const createOrUpdateUserAuth = convexAuth({
+  callbacks: {
+    async createOrUpdateUser(ctx, args) {
+      if (args.existingUserId) {
+        return args.existingUserId;
+      }
+
+      if (args.authUserId) {
+        await ctx.db.insert("messages", {
+          userId: args.authUserId,
+          body: JSON.stringify({
+            type: args.type,
+            authUserId: args.authUserId,
+            existingUserId: args.existingUserId,
+          }),
+        });
+        return args.authUserId;
+      }
+
+      return await ctx.db.insert("users", {
+        email: args.profile.email,
+        name:
+          typeof args.profile.name === "string" ? args.profile.name : undefined,
+      });
+    },
+  },
+  providers: [GitHub, Password],
+});
+
+test("createOrUpdateUser links a new OAuth account to the signed-in user via authUserId", async () => {
+  setupEnv();
+  const modules = import.meta.glob("./**/*.*s");
+  const overriddenModules = {
+    ...modules,
+    "./auth.ts": async () => createOrUpdateUserAuth,
+  };
+  const t = convexTest(schema, overriddenModules);
+
+  const { tokens } = await t.action(api.auth.signIn, {
+    provider: "password",
+    params: { email: "sarah@gmail.com", password: "44448888", flow: "signUp" },
+  });
+  expect(tokens).not.toBeNull();
+
+  const claims = decodeJwt(tokens!.token);
+  const asSarah = t.withIdentity({ subject: claims.sub });
+
+  const { tokens: oauthTokens } = await signInViaGitHub(asSarah, "github", {
+    email: "github-only@example.com",
+    name: "Sarah From GitHub",
+    id: "someGitHubId",
+  });
+  expect(oauthTokens).not.toBeNull();
+
+  await t.run(async (ctx) => {
+    const users = await ctx.db.query("users").collect();
+    expect(users).toHaveLength(1);
+
+    const accounts = await ctx.db.query("authAccounts").collect();
+    expect(accounts).toHaveLength(2);
+    expect(accounts.find((account) => account.provider === "password")).toMatchObject({
+      userId: users[0]._id,
+    });
+    expect(accounts.find((account) => account.provider === "github")).toMatchObject({
+      userId: users[0]._id,
+    });
+
+    const messages = await ctx.db.query("messages").collect();
+    expect(messages).toHaveLength(1);
+    expect(messages[0].userId).toEqual(users[0]._id);
+    expect(JSON.parse(messages[0].body)).toEqual({
+      type: "oauth",
+      authUserId: users[0]._id,
+      existingUserId: null,
+    });
+  });
+});
+
+test("createOrUpdateUser creates a new user for unauthenticated OAuth sign-in", async () => {
+  setupEnv();
+  const modules = import.meta.glob("./**/*.*s");
+  const overriddenModules = {
+    ...modules,
+    "./auth.ts": async () => createOrUpdateUserAuth,
+  };
+  const t = convexTest(schema, overriddenModules);
+
+  const { tokens: oauthTokens } = await signInViaGitHub(t, "github", {
+    email: "unauthenticated@example.com",
+    name: "Unauthenticated User",
+    id: "anotherGitHubId",
+  });
+  expect(oauthTokens).not.toBeNull();
+
+  await t.run(async (ctx) => {
+    const users = await ctx.db.query("users").collect();
+    expect(users).toHaveLength(1);
+
+    const accounts = await ctx.db.query("authAccounts").collect();
+    expect(accounts).toHaveLength(1);
+    expect(accounts.find((account) => account.provider === "github")).toMatchObject({
+      userId: users[0]._id,
+    });
+
+    const messages = await ctx.db.query("messages").collect();
+    expect(messages).toEqual([]);
+  });
+});
+
+function setupEnv() {
+  process.env.SITE_URL = "http://localhost:5173";
+  process.env.CONVEX_SITE_URL = CONVEX_SITE_URL;
+  process.env.JWT_PRIVATE_KEY = JWT_PRIVATE_KEY;
+  process.env.JWKS = JWKS;
+  process.env.AUTH_GITHUB_ID = "githubClientId";
+  process.env.AUTH_GITHUB_SECRET = "githubClientSecret";
+  process.env.AUTH_LOG_LEVEL = "ERROR";
+}