feat(nextjs): Improve auth().redirectToSignIn() and auth().protect() …

…redirect mechanism

* feat(nextjs): Make auth().redirectToSignIn() in middleware work without return

* feat(nextjs): Make auth().protect() respect returnBackUrl by using redirectToSignIn internally

.changeset/chilled-bikes-rule.md

@@ -0,0 +1,24 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+The `auth().redirectToSignIn()` helper no longer needs to be explicitly returned when called within the middleware. The following examples are now equivalent:
+
+```js
+// Before
+export default clerkMiddleware(auth => {
+  if (protectedRoute && !auth.user) {
+    return auth().redirectToSignIn()
+  }
+})
+
+// After
+export default clerkMiddleware(auth => {
+  if (protectedRoute && !auth.user) {
+    auth().redirectToSignIn()
+  }
+})
+```
+
+Calling `auth().protect()` from a page will now automatically redirect back to the same page by setting `redirect_url` to the request url before the redirect to the sign-in URL takes place.

integration/templates/next-app-router/package.json

@@ -12,7 +12,7 @@
     "@types/node": "^18.17.0",
     "@types/react": "18.2.14",
     "@types/react-dom": "18.2.6",
-    "next": "13.5.4",
+    "next": "13",
     "react": "18.2.0",
     "react-dom": "18.2.0",
     "typescript": "5.1.6"

packages/backend/src/constants.ts

@@ -10,6 +10,7 @@ const Attributes = {
   AuthStatus: '__clerkAuthStatus',
   AuthReason: '__clerkAuthReason',
   AuthMessage: '__clerkAuthMessage',
+  ClerkUrl: '__clerkUrl',
 } as const;
 
 const Cookies = {
@@ -29,6 +30,7 @@ const Headers = {
   AuthStatus: 'x-clerk-auth-status',
   AuthReason: 'x-clerk-auth-reason',
   AuthMessage: 'x-clerk-auth-message',
+  ClerkUrl: 'x-clerk-clerk-url',
   EnableDebug: 'x-clerk-debug',
   ClerkRedirectTo: 'x-clerk-redirect-to',
   CloudFrontForwardedProto: 'cloudfront-forwarded-proto',

packages/backend/src/createRedirect.ts

@@ -1,6 +1,6 @@
 import { errorThrower, parsePublishableKey } from './util/shared';
 
-const buildUrl = (_baseUrl: string | URL, _targetUrl: string | URL, _returnBackUrl?: string | URL) => {
+const buildUrl = (_baseUrl: string | URL, _targetUrl: string | URL, _returnBackUrl?: string | URL | null) => {
   if (_baseUrl === '') {
     return legacyBuildUrl(_targetUrl.toString(), _returnBackUrl?.toString());
   }
@@ -58,7 +58,7 @@ const buildAccountsBaseUrl = (frontendApi?: string) => {
 };
 
 type RedirectAdapter<RedirectReturn> = (url: string) => RedirectReturn;
-type RedirectToParams = { returnBackUrl?: string | URL };
+type RedirectToParams = { returnBackUrl?: string | URL | null };
 export type RedirectFun<ReturnType> = (params?: RedirectToParams) => ReturnType;
 
 /**

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -18,6 +18,7 @@ exports[`constants from environment variables 1`] = `
     "AuthToken": "x-clerk-auth-token",
     "Authorization": "authorization",
     "ClerkRedirectTo": "x-clerk-redirect-to",
+    "ClerkUrl": "x-clerk-clerk-url",
     "CloudFrontForwardedProto": "cloudfront-forwarded-proto",
     "ContentType": "content-type",
     "EnableDebug": "x-clerk-debug",

packages/nextjs/src/app-router/server/auth.ts

@@ -8,6 +8,7 @@ import { createGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
+import { getAuthKeyFromRequest } from '../../server/utils';
 import { buildRequestLike } from './utils';
 
 type Auth = AuthObject & { protect: AuthProtect; redirectToSignIn: RedirectFun<ReturnType<typeof redirect>> };
@@ -19,16 +20,23 @@ export const auth = (): Auth => {
     noAuthStatusMessage: authAuthHeaderMissing(),
   })(request);
 
-  const protect = createProtect({ request, authObject, notFound, redirect });
-  const redirectToSignIn = createRedirect({
-    redirectAdapter: redirect,
-    baseUrl: createClerkRequest(request).clerkUrl.toString(),
-    // TODO: Support runtime-value configuration of these options
-    // via setting and reading headers from clerkMiddleware
-    publishableKey: PUBLISHABLE_KEY,
-    signInUrl: SIGN_IN_URL,
-    signUpUrl: SIGN_UP_URL,
-  }).redirectToSignIn;
+  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');
+
+  const redirectToSignIn: RedirectFun<never> = (opts = {}) => {
+    return createRedirect({
+      redirectAdapter: redirect,
+      baseUrl: createClerkRequest(request).clerkUrl.toString(),
+      // TODO: Support runtime-value configuration of these options
+      // via setting and reading headers from clerkMiddleware
+      publishableKey: PUBLISHABLE_KEY,
+      signInUrl: SIGN_IN_URL,
+      signUpUrl: SIGN_UP_URL,
+    }).redirectToSignIn({
+      returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+    });
+  };
+
+  const protect = createProtect({ request, authObject, redirectToSignIn, notFound, redirect });
 
   return Object.assign(authObject, { protect, redirectToSignIn });
 };

packages/nextjs/src/server/authMiddleware.ts

@@ -215,7 +215,7 @@ const authMiddleware: AuthMiddleware = (...args: unknown[]) => {
       logger.debug(`Added ${constants.Headers.EnableDebug} on request`);
     }
 
-    const result = decorateRequest(nextRequest, finalRes, requestState) || NextResponse.next();
+    const result = decorateRequest(clerkRequest, finalRes, requestState) || NextResponse.next();
 
     if (requestState.headers) {
       requestState.headers.forEach((value, key) => {

packages/nextjs/src/server/clerkMiddleware.test.ts

@@ -1,4 +1,4 @@
-// There is no need to execute the complete authenticateRequest to test authMiddleware
+// There is no need to execute the complete authenticateRequest to test clerkMiddleware
 // This mock SHOULD exist before the import of authenticateRequest
 import { AuthStatus, constants } from '@clerk/backend/internal';
 import { describe, expect } from '@jest/globals';
@@ -36,7 +36,7 @@ afterAll(() => {
   global.console.warn = consoleWarn;
 });
 
-// Removing this mock will cause the authMiddleware tests to fail due to missing publishable key
+// Removing this mock will cause the clerkMiddleware tests to fail due to missing publishable key
 // This mock SHOULD exist before the imports
 jest.mock('./constants', () => {
   return {
@@ -179,7 +179,7 @@ describe('authenticateRequest & handshake', () => {
   });
 });
 
-describe('authMiddleware(params)', () => {
+describe('clerkMiddleware(params)', () => {
   it('renders route as normally when used without params', async () => {
     const signInResp = await clerkMiddleware()(mockRequest({ url: '/sign-in' }), {} as NextFetchEvent);
     expect(signInResp?.status).toEqual(200);
@@ -215,48 +215,75 @@ describe('authMiddleware(params)', () => {
   });
 
   describe('auth().redirectToSignIn()', () => {
-    it('redirects to sign-in url when redirectToSignIn is calle and the request is a page request', async () => {
+    it('redirects to sign-in url when redirectToSignIn is called and the request is a page request', async () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
         appendDevBrowserCookie: true,
       });
 
-      authenticateRequestMock.mockResolvedValueOnce({
-        status: AuthStatus.SignedOut,
-        headers: new Headers(),
-        toAuth: () => ({ userId: null }),
+      const resp = await clerkMiddleware(auth => {
+        auth().redirectToSignIn();
+      })(req, {} as NextFetchEvent);
+
+      expect(resp?.status).toEqual(307);
+      expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
+      expect(clerkClient.authenticateRequest).toBeCalled();
+    });
+
+    it('redirects to sign-in url when redirectToSignIn is called with the correct returnBackUrl', async () => {
+      const req = mockRequest({
+        url: '/protected',
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
+        appendDevBrowserCookie: true,
       });
 
       const resp = await clerkMiddleware(auth => {
-        return auth().redirectToSignIn();
+        auth().redirectToSignIn();
       })(req, {} as NextFetchEvent);
 
       expect(resp?.status).toEqual(307);
       expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
       expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
       expect(clerkClient.authenticateRequest).toBeCalled();
     });
 
-    it('redirects to sign-in url when redirectToSignIn is calle and the request is not a page request', async () => {
+    it('redirects to sign-in url with redirect_url set to the  provided returnBackUrl param', async () => {
       const req = mockRequest({
         url: '/protected',
-        headers: new Headers(),
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
         appendDevBrowserCookie: true,
       });
 
-      authenticateRequestMock.mockResolvedValueOnce({
-        status: AuthStatus.SignedOut,
-        headers: new Headers(),
-        toAuth: () => ({ userId: null }),
+      const resp = await clerkMiddleware(auth => {
+        auth().redirectToSignIn({ returnBackUrl: 'https://www.clerk.com/hello' });
+      })(req, {} as NextFetchEvent);
+
+      expect(resp?.status).toEqual(307);
+      expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toEqual(
+        'https://www.clerk.com/hello',
+      );
+      expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
+      expect(clerkClient.authenticateRequest).toBeCalled();
+    });
+
+    it('redirects to sign-in url without a redirect_url when returnBackUrl is null', async () => {
+      const req = mockRequest({
+        url: '/protected',
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
+        appendDevBrowserCookie: true,
       });
 
       const resp = await clerkMiddleware(auth => {
-        return auth().redirectToSignIn();
+        auth().redirectToSignIn({ returnBackUrl: null });
       })(req, {} as NextFetchEvent);
 
       expect(resp?.status).toEqual(307);
       expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
       expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
       expect(clerkClient.authenticateRequest).toBeCalled();
     });
@@ -406,6 +433,88 @@ describe('authMiddleware(params)', () => {
       expect(clerkClient.authenticateRequest).toBeCalled();
     });
   });
+
+  describe('auth().redirectToSignIn()', () => {
+    it('redirects to sign-in url even if called without a return statement', async () => {
+      const req = mockRequest({
+        url: '/protected',
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
+        appendDevBrowserCookie: true,
+      });
+
+      authenticateRequestMock.mockResolvedValueOnce({
+        status: AuthStatus.SignedOut,
+        headers: new Headers(),
+        toAuth: () => ({ userId: null }),
+      });
+
+      const resp = await clerkMiddleware(auth => {
+        auth().protect();
+      })(req, {} as NextFetchEvent);
+
+      expect(resp?.status).toEqual(307);
+      expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
+      expect(clerkClient.authenticateRequest).toBeCalled();
+    });
+
+    it('redirects to unauthenticatedUrl when protect is called with the unauthenticatedUrl param, the user is signed out, and is a page request', async () => {
+      const req = mockRequest({
+        url: '/protected',
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
+        appendDevBrowserCookie: true,
+      });
+
+      authenticateRequestMock.mockResolvedValueOnce({
+        status: AuthStatus.SignedOut,
+        headers: new Headers(),
+        toAuth: () => ({ userId: null }),
+      });
+
+      const resp = await clerkMiddleware(auth => {
+        auth().protect({
+          unauthenticatedUrl: 'https://www.clerk.com/unauthenticatedUrl',
+          unauthorizedUrl: 'https://www.clerk.com/unauthorizedUrl',
+        });
+      })(req, {} as NextFetchEvent);
+
+      expect(resp?.status).toEqual(307);
+      expect(resp?.headers.get('location')).toContain('https://www.clerk.com/unauthenticatedUrl');
+      expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
+      expect(resp?.headers.get(constants.Headers.ClerkRedirectTo)).toEqual('true');
+      expect(clerkClient.authenticateRequest).toBeCalled();
+    });
+
+    it('redirects to unauthorizedUrl when protect is called with the unauthorizedUrl param, the user is signed in but does not have permissions, and is a page request', async () => {
+      const req = mockRequest({
+        url: '/protected',
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
+        appendDevBrowserCookie: true,
+      });
+
+      authenticateRequestMock.mockResolvedValueOnce({
+        status: AuthStatus.SignedOut,
+        headers: new Headers(),
+        toAuth: () => ({ userId: 'userId', has: () => false }),
+      });
+
+      const resp = await clerkMiddleware(auth => {
+        auth().protect(
+          { permission: 'random-permission' },
+          {
+            unauthenticatedUrl: 'https://www.clerk.com/unauthenticatedUrl',
+            unauthorizedUrl: 'https://www.clerk.com/unauthorizedUrl',
+          },
+        );
+      })(req, {} as NextFetchEvent);
+
+      expect(resp?.status).toEqual(307);
+      expect(resp?.headers.get('location')).toContain('https://www.clerk.com/unauthorizedUrl');
+      expect(resp?.headers.get('x-clerk-auth-reason')).toEqual('redirect');
+      expect(resp?.headers.get(constants.Headers.ClerkRedirectTo)).toEqual('true');
+      expect(clerkClient.authenticateRequest).toBeCalled();
+    });
+  });
 });
 
 describe('Dev Browser JWT when redirecting to cross origin for page requests', function () {