feat(anonymous): delete anonymous user endpoint (#6377)

Author: ping-maxwell

docs/content/docs/plugins/anonymous.mdx

@@ -76,7 +76,8 @@ const user = await authClient.signIn.anonymous()
 
 ### Link Account
 
-If a user is already signed in anonymously and tries to `signIn` or `signUp` with another method, their anonymous activities can be linked to the new account.
+If a user is already signed in anonymously and tries to `signIn` or `signUp` with another method,
+their anonymous activities can be linked to the new account.
 
 To do that you first need to provide `onLinkAccount` callback to the plugin.
 
@@ -101,6 +102,27 @@ const user = await authClient.signIn.email({
 })
 ```
 
+### Delete Anonymous User
+
+To delete an anonymous user, you can call the `/delete-anonymous-user` endpoint.
+
+<APIMethod
+  path="/delete-anonymous-user"
+  method="POST"
+  noResult
+>
+```ts
+type deleteAnonymousUser = {
+}
+```
+</APIMethod>
+
+<Callout type="info">
+**Notes:**
+- The anonymous user is deleted by default when the account is linked to a new authentication method.
+- Setting `disableDeleteAnonymousUser` to `true` will prevent the anonymous user from being able to call the `/delete-anonymous-user` endpoint.
+</Callout>
+
 ## Options
 
 ### `emailDomainName`
@@ -151,7 +173,10 @@ A callback function that is called when an anonymous user links their account to
 
 ### `disableDeleteAnonymousUser`
 
-By default, the anonymous user is deleted when the account is linked to a new authentication method. Set this option to `true` to disable this behavior.
+By default, when an anonymous user links their account to a new authentication method,
+the anonymous user record is automatically deleted.
+If you set this option to `true`, this automatic deletion will be disabled,
+and the `/delete-anonymous-user` endpoint will no longer be accessible to anonymous users.
 
 ### `generateName`
 

packages/better-auth/src/plugins/anonymous/error-codes.ts

@@ -6,4 +6,7 @@ export const ANONYMOUS_ERROR_CODES = defineErrorCodes({
 	COULD_NOT_CREATE_SESSION: "Could not create session",
 	ANONYMOUS_USERS_CANNOT_SIGN_IN_AGAIN_ANONYMOUSLY:
 		"Anonymous users cannot sign in again anonymously",
+	FAILED_TO_DELETE_ANONYMOUS_USER: "Failed to delete anonymous user",
+	USER_IS_NOT_ANONYMOUS: "User is not anonymous",
+	DELETE_ANONYMOUS_USER_DISABLED: "Deleting anonymous users is disabled",
 });

packages/better-auth/src/plugins/anonymous/index.ts

@@ -5,12 +5,24 @@ import {
 } from "@better-auth/core/api";
 import { generateId } from "@better-auth/core/utils";
 import * as z from "zod";
-import { APIError, getSessionFromCtx } from "../../api";
-import { parseSetCookieHeader, setSessionCookie } from "../../cookies";
+import {
+	APIError,
+	getSessionFromCtx,
+	sensitiveSessionMiddleware,
+} from "../../api";
+import {
+	deleteSessionCookie,
+	parseSetCookieHeader,
+	setSessionCookie,
+} from "../../cookies";
 import { mergeSchema } from "../../db/schema";
 import { ANONYMOUS_ERROR_CODES } from "./error-codes";
 import { schema } from "./schema";
-import type { AnonymousOptions } from "./types";
+import type {
+	AnonymousOptions,
+	AnonymousSession,
+	UserWithAnonymous,
+} from "./types";
 
 async function getAnonUserEmail(
 	options: AnonymousOptions | undefined,
@@ -74,7 +86,7 @@ export const anonymous = (options?: AnonymousOptions | undefined) => {
 					// prevents an anonymous user from signing in anonymously again while they
 					// are already authenticated.
 					const existingSession = await getSessionFromCtx<{
-						isAnonymous: boolean;
+						isAnonymous: boolean | null;
 					}>(ctx, { disableRefresh: true });
 					if (existingSession?.user.isAnonymous) {
 						throw new APIError("BAD_REQUEST", {
@@ -126,6 +138,93 @@ export const anonymous = (options?: AnonymousOptions | undefined) => {
 					});
 				},
 			),
+			deleteAnonymousUser: createAuthEndpoint(
+				"/delete-anonymous-user",
+				{
+					method: "POST",
+					use: [sensitiveSessionMiddleware],
+					metadata: {
+						openapi: {
+							description: "Delete an anonymous user",
+							responses: {
+								200: {
+									description: "Anonymous user deleted",
+									content: {
+										"application/json": {
+											schema: {
+												type: "object",
+												properties: {
+													success: {
+														type: "boolean",
+													},
+												},
+											},
+										},
+									},
+								},
+								"400": {
+									description: "Anonymous user deletion is disabled",
+									content: {
+										"application/json": {
+											schema: {
+												type: "object",
+												properties: {
+													message: {
+														type: "string",
+													},
+												},
+											},
+											required: ["message"],
+										},
+									},
+								},
+								"500": {
+									description: "Internal server error",
+									content: {
+										"application/json": {
+											schema: {
+												type: "object",
+												properties: {
+													message: {
+														type: "string",
+													},
+												},
+												required: ["message"],
+											},
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+				async (ctx) => {
+					const session = ctx.context.session as AnonymousSession;
+
+					if (options?.disableDeleteAnonymousUser) {
+						throw new APIError("BAD_REQUEST", {
+							message: ANONYMOUS_ERROR_CODES.DELETE_ANONYMOUS_USER_DISABLED,
+						});
+					}
+
+					if (!session.user.isAnonymous) {
+						throw new APIError("FORBIDDEN", {
+							message: ANONYMOUS_ERROR_CODES.USER_IS_NOT_ANONYMOUS,
+						});
+					}
+
+					try {
+						await ctx.context.internalAdapter.deleteUser(session.user.id);
+					} catch (error) {
+						ctx.context.logger.error("Failed to delete anonymous user", error);
+						throw new APIError("INTERNAL_SERVER_ERROR", {
+							message: ANONYMOUS_ERROR_CODES.FAILED_TO_DELETE_ANONYMOUS_USER,
+						});
+					}
+					deleteSessionCookie(ctx);
+					return ctx.json({ success: true });
+				},
+			),
 		},
 		hooks: {
 			after: [
@@ -165,12 +264,11 @@ export const anonymous = (options?: AnonymousOptions | undefined) => {
 						/**
 						 * Make sure the user had an anonymous session.
 						 */
-						const session = await getSessionFromCtx<{ isAnonymous: boolean }>(
-							ctx,
-							{
-								disableRefresh: true,
-							},
-						);
+						const session = await getSessionFromCtx<{
+							isAnonymous: boolean | null;
+						}>(ctx, {
+							disableRefresh: true,
+						});
 
 						if (!session || !session.user.isAnonymous) {
 							return;
@@ -186,13 +284,22 @@ export const anonymous = (options?: AnonymousOptions | undefined) => {
 						if (!newSession) {
 							return;
 						}
+
+						const user = {
+							...session.user,
+							// Type hack to ensure `isAnonymous` is correctly inferred as true.
+							// Without this, `isAnonymous` is inferred as `boolean | null` despite
+							// the conditional checks above suggesting otherwise.
+							isAnonymous: session.user.isAnonymous,
+						};
+
 						// At this point the user is linking their previous anonymous account with a
 						// new credential (email / social). Invoke the provided callback so that the
 						// integrator can perform any additional logic such as transferring data
 						// from the anonymous user to the new user.
 						if (options?.onLinkAccount) {
 							await options?.onLinkAccount?.({
-								anonymousUser: session,
+								anonymousUser: { session: session.session, user },
 								newUser: newSession,
 								ctx,
 							});

packages/better-auth/src/plugins/anonymous/types.ts

@@ -7,6 +7,10 @@ import type { EndpointContext } from "better-call";
 import type { InferOptionSchema, Session, User } from "../../types";
 import type { schema } from "./schema";
 
+export type AnonymousSession = { session: Session; user: User } & {
+	user: { isAnonymous: boolean | null };
+} & Record<string, any>;
+
 export interface UserWithAnonymous extends User {
 	isAnonymous: boolean;
 }
@@ -36,7 +40,7 @@ export interface AnonymousOptions {
 		  }) => Awaitable<void>)
 		| undefined;
 	/**
-	 * Disable deleting the anonymous user after linking
+	 * Disable deleting the anonymous user
 	 */
 	disableDeleteAnonymousUser?: boolean | undefined;
 	/**