From 890e0841f71d8dbbf6491bb02404d911008d3cc3 Mon Sep 17 00:00:00 2001
From: Taesu <bytaesu@gmail.com>
Date: Sat, 17 Oct 2026 05:51:22 +0900
Subject: [PATCH] docs(apple): correct first-authorization email guidance

---
 docs/content/docs/authentication/apple.mdx       |  2 +-
 packages/core/src/social-providers/apple.test.ts | 11 +++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/content/docs/authentication/apple.mdx b/docs/content/docs/authentication/apple.mdx
index 74d4b6ff03..82704dcd2d 100644
--- a/docs/content/docs/authentication/apple.mdx
+++ b/docs/content/docs/authentication/apple.mdx
@@ -126,7 +126,7 @@ description: Apple provider setup and usage.
     For multiple static audiences (for example a Service ID plus a native bundle ID), prefer `clientId: string[]` or `audience: string[]` instead of setting only `appBundleIdentifier`. When the audience must depend on the request (for example reading an `x-platform` header), use a custom [`verifyIdToken`](/docs/concepts/oauth#verifyidtoken) callback — it receives the request context as its third argument.
 
     <Callout type="warn">
-      Apple emits the `email` claim only on the first authorization; every subsequent sign-in omits it, and Apple provides no user-info endpoint to fetch it later. See [Handling Providers Without Email](/docs/concepts/oauth#handling-providers-without-email) for persistence guidance and the `mapProfileToUser` fallback.
+      Apple returns the `user` object, including the user’s name, only on the first authorization. Save that information when it is provided. The email address is included in subsequent identity tokens, although managed Apple Accounts may have an empty email. See [Apple’s authorization response documentation](https://developer.apple.com/documentation/signinwithapplejs/configuring-your-webpage-for-sign-in-with-apple).
     </Callout>
   </Step>
 </Steps>
diff --git a/packages/core/src/social-providers/apple.test.ts b/packages/core/src/social-providers/apple.test.ts
index 24f3965493..09a17f770a 100644
--- a/packages/core/src/social-providers/apple.test.ts
+++ b/packages/core/src/social-providers/apple.test.ts
@@ -180,15 +180,18 @@ it.each([
 	["true", true],
 	["false", false],
 ] as const)(
-	"accepts email_verified=%s without native-only claims",
+	"accepts email_verified=%s without optional claims",
 	async (emailVerified, expected) => {
 		const profile = {
 			sub: "apple-user-123",
-			name: "",
 			email_verified: emailVerified,
 		};
-		assertType<AppleProfile>(profile);
-		assertType<AppleProfile>({ ...profile, is_private_email: "true" });
+		assertType<AppleProfile>({ ...profile, name: "" });
+		assertType<AppleProfile>({
+			...profile,
+			name: "",
+			is_private_email: "true",
+		});
 		const provider = apple({ clientId: "service.example.app" });
 
 		const result = await provider.getUserInfo({