fix(nextjs): Deprecate user, session, organization from auth() (#1960)

.changeset/three-rings-wash.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Deprecate `user`, `session`, and `organization` resources from the returned value of `auth()`.

packages/nextjs/src/server/getAuth.ts

@@ -1,4 +1,4 @@
-import type { Organization, Session, SignedInAuthObject, SignedOutAuthObject, User } from '@clerk/backend';
+import type { AuthObject, Organization, Session, SignedInAuthObject, SignedOutAuthObject, User } from '@clerk/backend';
 import {
   AuthStatus,
   constants,
@@ -8,6 +8,7 @@ import {
   signedInAuthObject,
   signedOutAuthObject,
 } from '@clerk/backend';
+import { deprecatedObjectProperty } from '@clerk/shared';
 import type { SecretKeyOrApiKey } from '@clerk/types';
 
 import { withLogger } from '../utils/debugLogger';
@@ -18,6 +19,21 @@ import { getAuthKeyFromRequest, getCookie, getHeader, injectSSRStateIntoObject }
 
 type GetAuthOpts = Partial<SecretKeyOrApiKey>;
 
+type AuthObjectWithDeprecatedResources<T extends AuthObject> = Omit<T, 'user' | 'organization' | 'session'> & {
+  /**
+   * @deprecated This will be removed in the next major version
+   */
+  user: T['user'];
+  /**
+   * @deprecated This will be removed in the next major version
+   */
+  organization: T['organization'];
+  /**
+   * @deprecated This will be removed in the next major version
+   */
+  session: T['session'];
+};
+
 export const createGetAuth = ({
   debugLoggerName,
   noAuthStatusMessage,
@@ -26,7 +42,10 @@ export const createGetAuth = ({
   debugLoggerName: string;
 }) =>
   withLogger(debugLoggerName, logger => {
-    return (req: RequestLike, opts?: GetAuthOpts): SignedInAuthObject | SignedOutAuthObject => {
+    return (
+      req: RequestLike,
+      opts?: GetAuthOpts,
+    ): AuthObjectWithDeprecatedResources<SignedInAuthObject | SignedOutAuthObject> => {
       const debug = getHeader(req, constants.Headers.EnableDebug) === 'true';
       if (debug) {
         logger.enable();
@@ -61,7 +80,22 @@ export const createGetAuth = ({
 
       const jwt = parseJwt(req);
       logger.debug('JWT debug', jwt.raw.text);
-      return signedInAuthObject(jwt.payload, { ...options, token: jwt.raw.text });
+
+      const signedIn = signedInAuthObject(jwt.payload, { ...options, token: jwt.raw.text });
+
+      if (signedIn.user) {
+        deprecatedObjectProperty(signedIn, 'user', 'Use `clerkClient.users.getUser` instead.');
+      }
+
+      if (signedIn.organization) {
+        deprecatedObjectProperty(signedIn, 'organization', 'Use `clerkClient.organizations.getOrganization` instead.');
+      }
+
+      if (signedIn.session) {
+        deprecatedObjectProperty(signedIn, 'session', 'Use `clerkClient.sessions.getSession` instead.');
+      }
+
+      return signedIn;
     };
   });