@robelest/convex-auth 0.0.4-preview.30 → 0.0.4-preview.31

package/dist/server/types.d.ts

@@ -195,155 +195,15 @@ type ConvexAuthConfig = {
     maxFailedAttemptsPerHour?: number;
   };
   /**
-   * Lifecycle callbacks for customizing sign-in behavior.
+   * Lifecycle callbacks. Two functions, both discriminated by `event.kind`:
    *
-   * Use `redirect` to control post-OAuth redirect URLs, and
-   * `createOrUpdateUser` or `afterUserCreatedOrUpdated` to
-   * customize account linking and user document creation.
+   * - {@link AuthCallbacks.before before} — intercept + customize specific
+   *   operations. Returning `undefined` falls back to the default.
+   * - {@link AuthCallbacks.after after} — observe lifecycle events. Events
+   *   fired from mutation context are transactional; events fired from action
+   *   context run after the orchestration mutation commits.
    */
-  callbacks?: {
-    /**
-     * Control which URLs are allowed as a destination after OAuth sign-in
-     * and for magic links:
-     *
-     * ```ts
-     * import { createAuth } from "@robelest/convex-auth/component";
-     * import { components } from "./_generated/api";
-     *
-     * const auth = createAuth(components.auth, {
-     *   providers: [google],
-     *   callbacks: {
-     *     async redirect({ redirectTo }) {
-     *       // Check that redirectTo is valid
-     *       // and return the relative or absolute URL
-     *       // to redirect to.
-     *     },
-     *   },
-     * });
-     * ```
-     *
-     * Convex Auth performs redirect only during OAuth sign-in. By default,
-     * it redirects back to the URL specified via the `SITE_URL` environment
-     * variable. Similarly magic links link to `SITE_URL`. Additional frontend
-     * origins can be listed in `SECONDARY_URL` for flows like passkeys.
-     *
-     * You can customize that behavior by providing a `redirectTo` param
-     * to the `signIn` function:
-     *
-     * ```ts
-     * signIn("google", { redirectTo: "/dashboard" })
-     * ```
-     *
-     * You can even redirect to a different site.
-     *
-     * This callback, if specified, is then called with the provided
-     * `redirectTo` param. Otherwise, only query params, relative paths
-     * and URLs starting with `SITE_URL` are allowed.
-     */
-    redirect?: (params: {
-      /**
-       * The param value passed to the `signIn` function.
-       */
-      redirectTo: string;
-    }) => Promise<string>;
-    /**
-     * Completely control account linking via this callback.
-     *
-     * This callback is called during the sign-in process,
-     * before account creation and token generation.
-     * If specified, this callback is responsible for creating
-     * or updating the user document.
-     *
-     * For "credentials" providers, the callback is only called
-     * when `createAccount` is called.
-     */
-    createOrUpdateUser?: (ctx: GenericMutationCtx<AnyDataModel>, args: {
-      /**
-       * If this is a sign-in to an existing account,
-       * this is the existing user ID linked to that account.
-       */
-      existingUserId: GenericId<"User"> | null;
-      /**
-       * The provider type or "verification" if this callback is called
-       * after an email or phone token verification.
-       */
-      type: "oauth" | "credentials" | "email" | "phone" | "verification";
-      /**
-       * The provider used for the sign-in, or the provider
-       * tied to the account which is having the email or phone verified.
-       */
-      provider: AuthProviderMaterializedConfig;
-      /**
-       * - The profile returned by the OAuth provider's `profile` method.
-       * - The profile passed to `createAccount` from a ConvexCredentials
-       * config.
-       * - The email address to which an email will be sent.
-       * - The phone number to which a text will be sent.
-       */
-      profile: Record<string, unknown> & {
-        email?: string;
-        phone?: string;
-        emailVerified?: boolean;
-        phoneVerified?: boolean;
-      };
-      /**
-       * The `shouldLink` argument passed to `createAccount`.
-       */
-      shouldLink?: boolean;
-    }) => Promise<GenericId<"User">>;
-    /**
-     * Perform additional writes after a user is created.
-     *
-     * This callback is called during the sign-in process,
-     * after the user is created or updated,
-     * before account creation and token generation.
-     *
-     * **This callback is only called if `createOrUpdateUser`
-     * is not specified.** If `createOrUpdateUser` is specified,
-     * you can perform any additional writes in that callback.
-     *
-     * For "credentials" providers, the callback is only called
-     * when `createAccount` is called.
-     */
-    afterUserCreatedOrUpdated?: (ctx: GenericMutationCtx<AnyDataModel>, args: {
-      /**
-       * The ID of the user that is being signed in.
-       */
-      userId: GenericId<"User">;
-      /**
-       * If this is a sign-in to an existing account,
-       * this is the existing user ID linked to that account.
-       */
-      existingUserId: GenericId<"User"> | null;
-      /**
-       * The provider type or "verification" if this callback is called
-       * after an email or phone token verification.
-       */
-      type: "oauth" | "credentials" | "email" | "phone" | "verification";
-      /**
-       * The provider used for the sign-in, or the provider
-       * tied to the account which is having the email or phone verified.
-       */
-      provider: AuthProviderMaterializedConfig;
-      /**
-       * - The profile returned by the OAuth provider's `profile` method.
-       * - The profile passed to `createAccount` from a ConvexCredentials
-       * config.
-       * - The email address to which an email will be sent.
-       * - The phone number to which a text will be sent.
-       */
-      profile: Record<string, unknown> & {
-        email?: string;
-        phone?: string;
-        emailVerified?: boolean;
-        phoneVerified?: boolean;
-      };
-      /**
-       * The `shouldLink` argument passed to `createAccount`.
-       */
-      shouldLink?: boolean;
-    }) => Promise<void>;
-  };
+  callbacks?: AuthCallbacks;
   /**
    * Application-defined role and grant model used by membership access checks.
    */
@@ -361,6 +221,170 @@ type ConvexAuthConfig = {
    */
   telemetry?: AuthTelemetryConfig;
 };
+/** The provider context that triggered a `link` / `userCreated` / `userUpdated` event. */
+type AuthCallbackContext = "oauth" | "credentials" | "email" | "phone" | "verification";
+/** Profile shape passed to `link` / `userCreated` / `userUpdated` callbacks. */
+type AuthCallbackProfile = Record<string, unknown> & {
+  email?: string;
+  phone?: string;
+  emailVerified?: boolean;
+  phoneVerified?: boolean;
+};
+/**
+ * Discriminated union of intercept events. Each variant runs *before* the
+ * default behavior for that operation. Returning a value replaces the
+ * default; returning `undefined` keeps it.
+ */
+type BeforeEvent = {
+  kind: "redirect"; /** The `redirectTo` param passed to `signIn(provider, { redirectTo })`. */
+  redirectTo: string;
+} | {
+  kind: "link"; /** Existing user ID if this account is already linked, else `null`. */
+  existingUserId: GenericId<"User"> | null; /** Where the link request originated. */
+  type: AuthCallbackContext; /** The provider whose account is being linked. */
+  provider: AuthProviderMaterializedConfig; /** Profile data harvested from the provider. */
+  profile: AuthCallbackProfile; /** The `shouldLink` argument passed to `createAccount`. */
+  shouldLink?: boolean;
+};
+/**
+ * Convex context type passed to `before` callbacks.
+ *
+ * `redirect` events arrive in action context; `link` events arrive
+ * in mutation context. Use `if ("db" in ctx)` to narrow when you need
+ * mutation-only methods.
+ */
+type BeforeCtx = GenericMutationCtx<any> | GenericActionCtx<any>;
+/**
+ * Return value contract for a `before` callback:
+ *
+ * - For `kind: "redirect"` — return a `string` (final URL) or `undefined`
+ *   to fall back to the default URL resolver.
+ * - For `kind: "link"` — return a `GenericId<"User">` or `undefined`
+ *   to fall back to the default user create/link logic.
+ */
+type BeforeResult = string | GenericId<"User"> | undefined;
+/**
+ * Discriminated union of post-operation lifecycle events. Events fired from
+ * mutation context run inside the same Convex transaction, so throwing rolls
+ * the operation back. Events fired from action context run after their
+ * orchestration mutation commits and cannot roll that mutation back.
+ */
+type AuthEvent = {
+  kind: "userCreated";
+  userId: GenericId<"User">;
+  type: AuthCallbackContext;
+  provider: AuthProviderMaterializedConfig;
+  profile: AuthCallbackProfile;
+} | {
+  kind: "userUpdated";
+  userId: GenericId<"User">;
+  existingUserId: GenericId<"User">;
+  type: AuthCallbackContext;
+  provider: AuthProviderMaterializedConfig;
+  profile: AuthCallbackProfile;
+} | {
+  kind: "signedIn";
+  userId: GenericId<"User">;
+  sessionId: GenericId<"Session">;
+  provider: string;
+  flow?: string;
+} | {
+  kind: "signedOut";
+  userId: GenericId<"User">;
+  sessionId: GenericId<"Session">;
+} | {
+  kind: "passwordChanged";
+  userId: GenericId<"User">;
+  flow: "reset" | "change";
+} | {
+  kind: "passkeyAdded";
+  userId: GenericId<"User">;
+  passkeyId: GenericId<"Passkey">;
+  credentialId: string;
+} | {
+  kind: "passkeyRemoved";
+  userId: GenericId<"User">;
+  passkeyId: GenericId<"Passkey">;
+} | {
+  kind: "totpEnrolled";
+  userId: GenericId<"User">;
+  totpId: GenericId<"TotpFactor">;
+} | {
+  kind: "totpRemoved";
+  userId: GenericId<"User">;
+  totpId: GenericId<"TotpFactor">;
+} | {
+  kind: "emailVerified";
+  userId: GenericId<"User">;
+  email: string;
+} | {
+  kind: "phoneVerified";
+  userId: GenericId<"User">;
+  phone: string;
+} | {
+  kind: "accountLinked";
+  userId: GenericId<"User">;
+  provider: string;
+  providerAccountId: string;
+} | {
+  kind: "accountUnlinked";
+  userId: GenericId<"User">;
+  accountId: GenericId<"Account">;
+  provider: string;
+} | {
+  kind: "sessionsInvalidated";
+  userId: GenericId<"User">;
+  sessionIds: GenericId<"Session">[];
+};
+/**
+ * Convex context type passed to `after` callbacks.
+ *
+ * Different events fire from different runtime contexts (some from
+ * mutations, some from actions). The union type exposes only methods both
+ * share — `runQuery`, `runMutation`, `scheduler`, `auth`. To use ctx-specific
+ * features (`db`, `runAction`), narrow with `if ("db" in ctx)`.
+ */
+type AfterCtx = GenericMutationCtx<any> | GenericActionCtx<any>;
+/**
+ * Lifecycle callback set. Two callbacks, both discriminated by `event.kind`.
+ *
+ * @example
+ * ```ts
+ * createAuth(components.auth, {
+ *   providers: [google()],
+ *   callbacks: {
+ *     async before(ctx, event) {
+ *       if (event.kind === "redirect") return safeRedirect(event.redirectTo);
+ *       // returning undefined falls back to default for other kinds
+ *     },
+ *     async after(ctx, event) {
+ *       if (event.kind === "userCreated") {
+ *         await ctx.scheduler.runAfter(0, internal.workflows.onboard, {
+ *           userId: event.userId,
+ *         });
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface AuthCallbacks {
+  /**
+   * Intercept and customize specific operations before they commit.
+   * Returning a value replaces the default; returning `undefined` keeps it.
+   *
+   * Match on `event.kind` to narrow the event shape. See {@link BeforeResult}
+   * for what to return per kind.
+   */
+  before?: (ctx: BeforeCtx, event: BeforeEvent) => Promise<BeforeResult>;
+  /**
+   * Observe lifecycle events. The `ctx` type is a union of mutation and
+   * action ctx — see {@link AfterCtx}. Most events fire from mutation
+   * context (atomic with the operation, throwing rolls back); a few fire
+   * from action context after the orchestration mutation commits.
+   */
+  after?: (ctx: AfterCtx, event: AuthEvent) => Promise<void>;
+}
 /**
  * Union of all supported auth provider config types.
  *
@@ -558,6 +582,7 @@ interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /**
    * The values passed to the `signIn` function.
    */
+
   params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "Account">) => Promise<void>;
   /** Raw user options before merging with defaults. */
   options: EmailUserConfig<DataModel>;
@@ -624,6 +649,7 @@ interface PhoneConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /**
    * The values passed to the `signIn` function.
    */
+
   params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "Account">) => Promise<void>;
   options: PhoneUserConfig<DataModel>;
 }
@@ -790,6 +816,18 @@ type AuthInvalidateSessionsArgs = {
   userId: GenericId<"User">;
   except?: GenericId<"Session">[];
 };
+/** Arguments for `auth.account.unlink()`. */
+type AuthUnlinkAccountArgs = {
+  accountId: GenericId<"Account">;
+};
+/** Arguments for `auth.passkey.delete()`. */
+type AuthDeletePasskeyArgs = {
+  passkeyId: GenericId<"Passkey">;
+};
+/** Arguments for `auth.totp.delete()`. */
+type AuthDeleteTotpArgs = {
+  totpId: GenericId<"TotpFactor">;
+};
 /** Arguments for `auth.provider.signIn()`. */
 type AuthProviderSignInArgs = {
   accountId?: GenericId<"Account">;
@@ -837,7 +875,11 @@ type AuthMemberRequireArgs = AuthMemberInspectArgs & {
  * ```
  */
 type AuthServerHelpers = {
-  /** Account management: create, retrieve, and update provider-linked accounts. */account: {
+  /**
+   * Account management: create, retrieve, update, and unlink
+   * provider-linked accounts.
+   */
+  account: {
     create: (ctx: GenericActionCtx<GenericDataModel>, args: AuthCreateAccountArgs) => Promise<{
       account: GenericDoc<GenericDataModel, "Account">;
       user: GenericDoc<GenericDataModel, "User">;
@@ -849,6 +891,36 @@ type AuthServerHelpers = {
     update: (ctx: GenericActionCtx<GenericDataModel>, args: AuthUpdateAccountArgs) => Promise<{
       accountId: GenericId<"Account">;
     }>;
+    /**
+     * Unlink (delete) a provider-linked account by ID and fire the
+     * `accountUnlinked` lifecycle event with the captured `provider`.
+     */
+    unlink: (ctx: GenericActionCtx<GenericDataModel>, args: AuthUnlinkAccountArgs) => Promise<{
+      accountId: GenericId<"Account">;
+      userId: GenericId<"User">;
+      provider: string;
+    }>;
+  }; /** Passkey credential management exposed to provider authorize callbacks. */
+  passkey: {
+    /**
+     * Delete a passkey credential by ID and fire the `passkeyRemoved`
+     * lifecycle event with the owning `userId`.
+     */
+    delete: (ctx: GenericActionCtx<GenericDataModel>, args: AuthDeletePasskeyArgs) => Promise<{
+      passkeyId: GenericId<"Passkey">;
+      userId: GenericId<"User">;
+    }>;
+  }; /** TOTP factor management exposed to provider authorize callbacks. */
+  totp: {
+    /**
+     * Delete a TOTP factor by ID and fire the `totpRemoved` lifecycle
+     * event. If this was the user's last verified factor, the
+     * `User.hasTotp` flag is cleared as part of the same mutation.
+     */
+    delete: (ctx: GenericActionCtx<GenericDataModel>, args: AuthDeleteTotpArgs) => Promise<{
+      totpId: GenericId<"TotpFactor">;
+      userId: GenericId<"User">;
+    }>;
   };
   session: {
     current: (ctx: {
@@ -1029,12 +1101,12 @@ type UserWhere = {
 /** Sortable fields for `auth.user.list()`. */
 type UserOrderBy = "_creationTime" | "name" | "email" | "phone";
 /**
- * Context injected into `auth.http.action()` and `auth.http.route()` handlers.
+ * Context injected into `auth.request.action()` and `auth.request.route()` handlers.
  *
  * The handler's `ctx` receives these fields after Bearer token verification:
  *
  * ```ts
- * auth.http.route(http, {
+ * auth.request.route(http, {
  *   path: "/api/data",
  *   method: "GET",
  *   handler: async (ctx, request) => {
@@ -1134,6 +1206,7 @@ type AuthComponentApi = {
     keyPatch: FunctionReference<"mutation", "internal">;
     keyDelete: FunctionReference<"mutation", "internal">;
     passkeyInsert: FunctionReference<"mutation", "internal">;
+    passkeyGetById: FunctionReference<"query", "internal">;
     passkeyGetByCredentialId: FunctionReference<"query", "internal">;
     passkeyListByUserId: FunctionReference<"query", "internal">;
     passkeyUpdateCounter: FunctionReference<"mutation", "internal">;
@@ -1213,5 +1286,5 @@ type SessionTokenIdentityClaims = {
 };
 type KeyDoc = Infer<typeof vApiKeyDoc>;
 //#endregion
-export { AuthAuthorizationConfig, AuthGrant, AuthProviderConfig, AuthRoleId, ConvexAuthConfig, ConvexAuthMaterializedConfig, ConvexCredentialsConfig, CorsConfig, DeviceProviderConfig, Doc, EmailConfig, EmailUserConfig, GenericActionCtxWithAuthConfig, GenericDoc, GroupConnectionDeprovisionMode, GroupConnectionPolicy, GroupConnectionPolicyPatch, HasDeviceProvider, HasPasskeyProvider, HasSSO, HasTotpProvider, HttpKeyContext, KeyDoc, KeyScope, OAuthMaterializedConfig, OAuthProfile, OAuthTokens, OIDCClaimMapping, PasskeyProviderConfig, PhoneConfig, PhoneUserConfig, SSOProviderConfig, ScopeChecker, SessionTokenIdentityClaims, TotpProviderConfig, UserOrderBy, UserWhere };
+export { AfterCtx, AuthAuthorizationConfig, AuthCallbackContext, AuthCallbackProfile, AuthCallbacks, AuthEvent, AuthGrant, AuthProviderConfig, AuthRoleId, BeforeCtx, BeforeEvent, BeforeResult, ConvexAuthConfig, ConvexAuthMaterializedConfig, ConvexCredentialsConfig, CorsConfig, DeviceProviderConfig, Doc, EmailConfig, EmailUserConfig, GenericActionCtxWithAuthConfig, GenericDoc, GroupConnectionPolicy, GroupConnectionPolicyPatch, HasDeviceProvider, HasPasskeyProvider, HasSSO, HasTotpProvider, HttpKeyContext, KeyDoc, KeyScope, OAuthMaterializedConfig, OAuthProfile, OAuthTokens, OIDCClaimMapping, PasskeyProviderConfig, PhoneConfig, PhoneUserConfig, SSOProviderConfig, ScopeChecker, SessionTokenIdentityClaims, TotpProviderConfig, UserOrderBy, UserWhere };
 //# sourceMappingURL=types.d.ts.map

package/dist/server/url.js

@@ -28,5 +28,5 @@ function isLocalHost(host) {
 }
 
 //#endregion
-export { isLocalHost, siteUrlsFromEnv };
+export { isLocalHost, normalizeUrl, siteUrlsFromEnv };
 //# sourceMappingURL=url.js.map

package/dist/server/users.js

@@ -39,6 +39,52 @@ async function upsertUserAndAccount(ctx, sessionId, account, args, config, opts)
 		accountId: await createOrUpdateAccount(ctx, userId, account, args, config)
 	};
 }
+async function resolveUserIdByLinking(ctx, args, profile, shouldLinkViaEmail, shouldLinkViaPhone, existingUserIdOverride, config) {
+	const [emailLookup, phoneLookup] = await Promise.all([typeof profile.email === "string" && shouldLinkViaEmail ? uniqueUserWithVerifiedEmail(ctx, profile.email, config) : Promise.resolve(null), typeof profile.phone === "string" && shouldLinkViaPhone ? uniqueUserWithVerifiedPhone(ctx, profile.phone, config) : Promise.resolve(null)]);
+	const emailUserId = emailLookup?._id ?? null;
+	const phoneUserId = phoneLookup?._id ?? null;
+	if (emailUserId !== null && phoneUserId !== null) {
+		log(LOG_LEVELS.DEBUG, `Found both email and phone verified users, not linking: email: ${emailUserId}, phone: ${phoneUserId}`);
+		return existingUserIdOverride;
+	}
+	if (emailUserId !== null) {
+		log(LOG_LEVELS.DEBUG, `Found existing email verified user, linking: ${emailUserId}`);
+		return emailUserId;
+	}
+	if (phoneUserId !== null) {
+		log(LOG_LEVELS.DEBUG, `Found existing phone verified user, linking: ${phoneUserId}`);
+		return phoneUserId;
+	}
+	log(LOG_LEVELS.DEBUG, "No existing verified users found, creating new user");
+	return existingUserIdOverride;
+}
+async function checkAllowLink(args, config, userId) {
+	if (config.sso?.hooks?.allowLink === void 0 || args.provider.type !== "oauth" && args.provider.type !== "sso") return true;
+	return await config.sso.hooks.allowLink({
+		protocol: args.provider.type === "oauth" && typeof args.accountExtend?.identity?.protocol === "string" ? args.accountExtend.identity.protocol : "oidc",
+		connectionId: typeof args.accountExtend?.identity?.connectionId === "string" ? args.accountExtend.identity.connectionId : void 0,
+		profile: args.profile,
+		userId
+	}) !== false;
+}
+async function updateExistingUser(db, userId, userData, source, provisioningUser) {
+	const currentUser = await db.users.getById(userId);
+	const mode = effectiveUserUpdateMode(source, provisioningUser);
+	const patchData = buildUserPatchData({
+		currentUser: currentUser ?? {},
+		nextUser: userData,
+		mode
+	});
+	if (Object.keys(patchData).length === 0) return;
+	try {
+		await db.users.patch(userId, patchData);
+	} catch (error) {
+		throw new ConvexError({
+			code: "USER_UPDATE_FAILED",
+			message: `Could not update user document with ID \`${userId}\`, either the user has been deleted but their account has not, or the profile data doesn't match the \`users\` table schema: ${error instanceof Error ? error.message : String(error)}`
+		});
+	}
+}
 async function defaultCreateOrUpdateUser(ctx, existingSessionId, existingAccount, args, config, existingUserIdOverride, provisioningUser, source) {
 	log(LOG_LEVELS.DEBUG, "defaultCreateOrUpdateUser args:", {
 		existingAccountId: existingAccount?._id,
@@ -47,12 +93,18 @@ async function defaultCreateOrUpdateUser(ctx, existingSessionId, existingAccount
 	});
 	const existingUserId = existingAccount?.userId ?? null;
 	const db = authDb(ctx, config);
-	if (config.callbacks?.createOrUpdateUser !== void 0) {
-		log(LOG_LEVELS.DEBUG, "Using custom createOrUpdateUser callback");
-		return await config.callbacks.createOrUpdateUser(ctx, {
+	const before = config.callbacks?.before;
+	if (before !== void 0) {
+		log(LOG_LEVELS.DEBUG, "Calling `before({ kind: \"link\" })` callback");
+		const customUserId = await before(ctx, {
+			kind: "link",
 			existingUserId,
-			...args
+			type: args.type,
+			provider: args.provider,
+			profile: args.profile,
+			shouldLink: args.shouldLinkViaEmail || args.shouldLinkViaPhone
 		});
+		if (customUserId !== void 0) return customUserId;
 	}
 	const { provider, profile: { id: _profileId, emailVerified: profileEmailVerified, phoneVerified: profilePhoneVerified, ...profile } } = args;
 	const emailVerified = profileEmailVerified ?? (provider.type === "oauth" && provider.accountLinking !== "none");
@@ -61,30 +113,8 @@ async function defaultCreateOrUpdateUser(ctx, existingSessionId, existingAccount
 	const shouldLinkViaPhone = args.shouldLinkViaPhone || phoneVerified || provider.type === "phone";
 	let userId = existingUserId ?? existingUserIdOverride;
 	if (existingUserId === null) {
-		const [emailLookup, phoneLookup] = await Promise.all([typeof profile.email === "string" && shouldLinkViaEmail ? uniqueUserWithVerifiedEmail(ctx, profile.email, config) : Promise.resolve(null), typeof profile.phone === "string" && shouldLinkViaPhone ? uniqueUserWithVerifiedPhone(ctx, profile.phone, config) : Promise.resolve(null)]);
-		const existingUserWithVerifiedEmailId = emailLookup?._id ?? null;
-		const existingUserWithVerifiedPhoneId = phoneLookup?._id ?? null;
-		if (existingUserWithVerifiedEmailId !== null && existingUserWithVerifiedPhoneId !== null) {
-			log(LOG_LEVELS.DEBUG, `Found existing email and phone verified users, so not linking: email: ${existingUserWithVerifiedEmailId}, phone: ${existingUserWithVerifiedPhoneId}`);
-			userId = null;
-		} else if (existingUserWithVerifiedEmailId !== null) {
-			log(LOG_LEVELS.DEBUG, `Found existing email verified user, linking: ${existingUserWithVerifiedEmailId}`);
-			userId = existingUserWithVerifiedEmailId;
-		} else if (existingUserWithVerifiedPhoneId !== null) {
-			log(LOG_LEVELS.DEBUG, `Found existing phone verified user, linking: ${existingUserWithVerifiedPhoneId}`);
-			userId = existingUserWithVerifiedPhoneId;
-		} else {
-			log(LOG_LEVELS.DEBUG, "No existing verified users found, creating new user");
-			userId = null;
-		}
-		if (userId !== null && config.sso?.hooks?.allowLink !== void 0 && (args.provider.type === "oauth" || args.provider.type === "sso")) {
-			if (await config.sso.hooks.allowLink({
-				protocol: args.provider.type === "oauth" && typeof args.accountExtend?.identity?.protocol === "string" ? args.accountExtend.identity.protocol : "oidc",
-				connectionId: typeof args.accountExtend?.identity?.connectionId === "string" ? args.accountExtend.identity.connectionId : void 0,
-				profile: args.profile,
-				userId
-			}) === false) userId = null;
-		}
+		userId = await resolveUserIdByLinking(ctx, args, profile, shouldLinkViaEmail, shouldLinkViaPhone, existingUserIdOverride, config);
+		if (userId !== null && !await checkAllowLink(args, config, userId)) userId = null;
 	}
 	const userData = {
 		...emailVerified ? { emailVerificationTime: Date.now() } : null,
@@ -92,40 +122,43 @@ async function defaultCreateOrUpdateUser(ctx, existingSessionId, existingAccount
 		...profile
 	};
 	const existingOrLinkedUserId = userId;
-	if (userId !== null) {
-		const currentUserId = userId;
-		const currentUser = await db.users.getById(currentUserId);
-		const mode = effectiveUserUpdateMode(source, provisioningUser);
-		const patchData = buildUserPatchData({
-			currentUser: currentUser ?? {},
-			nextUser: userData,
-			mode
-		});
-		if (Object.keys(patchData).length === 0) return userId;
-		try {
-			await db.users.patch(currentUserId, patchData);
-		} catch (error) {
-			throw new ConvexError({
-				code: "USER_UPDATE_FAILED",
-				message: `Could not update user document with ID \`${currentUserId}\`, either the user has been deleted but their account has not, or the profile data doesn't match the \`users\` table schema: ${error instanceof Error ? error.message : String(error)}`
-			});
-		}
-	} else {
+	if (userId !== null) await updateExistingUser(db, userId, userData, source, provisioningUser);
+	else {
 		if (source === "login" && provisioningUser?.createOnSignIn === false) throw new ConvexError({
 			code: "NOT_AUTHORIZED",
 			message: "This SSO connection does not allow creating users on sign-in."
 		});
 		userId = await db.users.insert(userData);
 	}
-	const afterUserCreatedOrUpdated = config.callbacks?.afterUserCreatedOrUpdated;
-	if (afterUserCreatedOrUpdated !== void 0) {
-		log(LOG_LEVELS.DEBUG, "Calling custom afterUserCreatedOrUpdated callback");
-		await afterUserCreatedOrUpdated(ctx, {
+	const after = config.callbacks?.after;
+	if (after !== void 0) {
+		log(LOG_LEVELS.DEBUG, "Calling `after` callback for user lifecycle event");
+		if (existingOrLinkedUserId === null) await after(ctx, {
+			kind: "userCreated",
+			userId,
+			type: args.type,
+			provider: args.provider,
+			profile: args.profile
+		});
+		else await after(ctx, {
+			kind: "userUpdated",
 			userId,
 			existingUserId: existingOrLinkedUserId,
-			...args
+			type: args.type,
+			provider: args.provider,
+			profile: args.profile
+		});
+		if (emailVerified && typeof args.profile.email === "string") await after(ctx, {
+			kind: "emailVerified",
+			userId,
+			email: args.profile.email
+		});
+		if (phoneVerified && typeof args.profile.phone === "string") await after(ctx, {
+			kind: "phoneVerified",
+			userId,
+			phone: args.profile.phone
 		});
-	} else log(LOG_LEVELS.DEBUG, "No custom afterUserCreatedOrUpdated callback, skipping");
+	}
 	return userId;
 }
 async function uniqueUserWithVerifiedEmail(ctx, email, config) {
@@ -137,6 +170,7 @@ async function uniqueUserWithVerifiedPhone(ctx, phone, config) {
 async function createOrUpdateAccount(ctx, userId, account, args, config) {
 	const db = authDb(ctx, config);
 	const mergedExtend = "existingAccount" in account ? mergeExtend(account.existingAccount.extend, args.accountExtend) : args.accountExtend;
+	const isNewAccount = !("existingAccount" in account);
 	const accountId = "existingAccount" in account ? account.existingAccount._id : await db.accounts.create({
 		userId,
 		provider: args.provider.id,
@@ -144,6 +178,12 @@ async function createOrUpdateAccount(ctx, userId, account, args, config) {
 		secret: account.secret,
 		extend: mergedExtend
 	});
+	if (isNewAccount) await config.callbacks?.after?.(ctx, {
+		kind: "accountLinked",
+		userId,
+		provider: args.provider.id,
+		providerAccountId: account.providerAccountId
+	});
 	if ("existingAccount" in account && account.existingAccount.userId !== userId) await db.accounts.patch(accountId, { userId });
 	const accountPatchData = {};
 	if (mergedExtend) accountPatchData.extend = mergedExtend;