chore(backend,nextjs): Improve token handling and optimize verification

.changeset/twenty-beds-serve.md

@@ -0,0 +1,8 @@
+---
+'@clerk/backend': minor
+'@clerk/nextjs': minor
+---
+
+- Optimize `auth()` calls to avoid unnecessary verification calls when the provided token type is not in the `acceptsToken` array.
+- Add handling for invalid token types when `acceptsToken` is an array in `authenticateRequyest()`: now returns a clear unauthenticated state (`tokenType: null`) if the token is not in the accepted list.
+

packages/backend/src/tokens/__tests__/request.test-d.ts

@@ -26,7 +26,7 @@ test('returns the correct `authenticateRequest()` return type for each accepted
   // Array of token types
   expectTypeOf(
     authenticateRequest(request, { acceptsToken: ['session_token', 'api_key', 'machine_token'] }),
-  ).toMatchTypeOf<Promise<RequestState<'session_token' | 'api_key' | 'machine_token'>>>();
+  ).toMatchTypeOf<Promise<RequestState<'session_token' | 'api_key' | 'machine_token' | null>>>();
 
   // Any token type
   expectTypeOf(authenticateRequest(request, { acceptsToken: 'any' })).toMatchTypeOf<Promise<RequestState<TokenType>>>();

packages/backend/src/tokens/__tests__/request.test.ts

@@ -16,7 +16,7 @@ import type { AuthReason } from '../authStatus';
 import { AuthErrorReason, AuthStatus } from '../authStatus';
 import { OrganizationMatcher } from '../organizationMatcher';
 import { authenticateRequest, RefreshTokenErrorReason } from '../request';
-import type { MachineTokenType } from '../tokenTypes';
+import { type MachineTokenType, TokenType } from '../tokenTypes';
 import type { AuthenticateRequestOptions } from '../types';
 
 const PK_TEST = 'pk_test_Y2xlcmsuaW5zcGlyZWQucHVtYS03NC5sY2wuZGV2JA';
@@ -1203,7 +1203,7 @@ describe('tokens.authenticateRequest(options)', () => {
     });
 
     // Test each token type with parameterized tests
-    const tokenTypes = ['api_key', 'oauth_token', 'machine_token'] as const;
+    const tokenTypes = [TokenType.ApiKey, TokenType.OAuthToken, TokenType.MachineToken];
 
     describe.each(tokenTypes)('%s Authentication', tokenType => {
       const mockToken = mockTokens[tokenType];
@@ -1240,6 +1240,7 @@ describe('tokens.authenticateRequest(options)', () => {
         });
         expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
           tokenType,
+          isAuthenticated: false,
         });
       });
     });
@@ -1289,6 +1290,7 @@ describe('tokens.authenticateRequest(options)', () => {
         });
         expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
           tokenType: 'api_key',
+          isAuthenticated: false,
         });
       });
 
@@ -1303,6 +1305,7 @@ describe('tokens.authenticateRequest(options)', () => {
         });
         expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
           tokenType: 'oauth_token',
+          isAuthenticated: false,
         });
       });
 
@@ -1317,6 +1320,7 @@ describe('tokens.authenticateRequest(options)', () => {
         });
         expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
           tokenType: 'machine_token',
+          isAuthenticated: false,
         });
       });
 
@@ -1331,6 +1335,7 @@ describe('tokens.authenticateRequest(options)', () => {
         });
         expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
           tokenType: 'machine_token',
+          isAuthenticated: false,
         });
       });
     });
@@ -1360,12 +1365,13 @@ describe('tokens.authenticateRequest(options)', () => {
         );
 
         expect(requestState).toBeMachineUnauthenticated({
-          tokenType: 'machine_token',
+          tokenType: null,
           reason: AuthErrorReason.TokenTypeMismatch,
           message: '',
         });
         expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
-          tokenType: 'machine_token',
+          tokenType: null,
+          isAuthenticated: false,
         });
       });
     });

packages/backend/src/tokens/authObjects.ts

@@ -428,37 +428,40 @@ export const getAuthObjectFromJwt = (
  * Returns an auth object matching the requested token type(s).
  *
  * If the parsed token type does not match any in acceptsToken, returns:
- *   - an unauthenticated machine object for the first machine token type in acceptsToken (if present), or
+ *   - an invalid token auth object if the token is not in the accepted array
+ *   - an unauthenticated machine object for machine tokens, or
  *   - a signed-out session object otherwise.
  *
  * This ensures the returned object always matches the developer's intent.
  */
-export function getAuthObjectForAcceptedToken({
+export const getAuthObjectForAcceptedToken = ({
   authObject,
   acceptsToken = TokenType.SessionToken,
 }: {
   authObject: AuthObject;
   acceptsToken: AuthenticateRequestOptions['acceptsToken'];
-}): AuthObject {
+}): AuthObject => {
+  // 1. any token: return as-is
   if (acceptsToken === 'any') {
     return authObject;
   }
 
+  // 2. array of tokens: must match one of the accepted types
   if (Array.isArray(acceptsToken)) {
     if (!isTokenTypeAccepted(authObject.tokenType, acceptsToken)) {
-      // If the token is not in the accepted array, return invalid token auth object
       return invalidTokenAuthObject();
     }
     return authObject;
   }
 
-  // Single value: Intent based
+  // 3. single token: must match exactly, else return appropriate unauthenticated object
   if (!isTokenTypeAccepted(authObject.tokenType, acceptsToken)) {
     if (isMachineTokenType(acceptsToken)) {
       return unauthenticatedMachineObject(acceptsToken, authObject.debug);
     }
     return signedOutAuthObject(authObject.debug);
   }
 
+  // 4. default: return as-is
   return authObject;
-}
+};

packages/backend/src/tokens/authStatus.ts

@@ -5,12 +5,14 @@ import type { TokenVerificationErrorReason } from '../errors';
 import type { AuthenticateContext } from './authenticateContext';
 import type {
   AuthenticatedMachineObject,
+  InvalidTokenAuthObject,
   SignedInAuthObject,
   SignedOutAuthObject,
   UnauthenticatedMachineObject,
 } from './authObjects';
 import {
   authenticatedMachineObject,
+  invalidTokenAuthObject,
   signedInAuthObject,
   signedOutAuthObject,
   unauthenticatedMachineObject,
@@ -27,13 +29,15 @@ export const AuthStatus = {
 
 export type AuthStatus = (typeof AuthStatus)[keyof typeof AuthStatus];
 
-type ToAuth<T extends TokenType, Authenticated extends boolean> = T extends SessionTokenType
-  ? Authenticated extends true
-    ? (opts?: PendingSessionOptions) => SignedInAuthObject
-    : () => SignedOutAuthObject
-  : Authenticated extends true
-    ? () => AuthenticatedMachineObject<Exclude<T, SessionTokenType>>
-    : () => UnauthenticatedMachineObject<Exclude<T, SessionTokenType>>;
+type ToAuth<T extends TokenType | null, Authenticated extends boolean> = T extends null
+  ? () => InvalidTokenAuthObject
+  : T extends SessionTokenType
+    ? Authenticated extends true
+      ? (opts?: PendingSessionOptions) => SignedInAuthObject
+      : () => SignedOutAuthObject
+    : Authenticated extends true
+      ? () => AuthenticatedMachineObject<Exclude<T, SessionTokenType | null>>
+      : () => UnauthenticatedMachineObject<Exclude<T, SessionTokenType | null>>;
 
 export type AuthenticatedState<T extends TokenType = SessionTokenType> = {
   status: typeof AuthStatus.SignedIn;
@@ -58,7 +62,7 @@ export type AuthenticatedState<T extends TokenType = SessionTokenType> = {
   toAuth: ToAuth<T, true>;
 };
 
-export type UnauthenticatedState<T extends TokenType = SessionTokenType> = {
+export type UnauthenticatedState<T extends TokenType | null = SessionTokenType> = {
   status: typeof AuthStatus.SignedOut;
   reason: AuthReason;
   message: string;
@@ -120,8 +124,8 @@ export type AuthErrorReason = (typeof AuthErrorReason)[keyof typeof AuthErrorRea
 
 export type AuthReason = AuthErrorReason | TokenVerificationErrorReason;
 
-export type RequestState<T extends TokenType = SessionTokenType> =
-  | AuthenticatedState<T>
+export type RequestState<T extends TokenType | null = SessionTokenType> =
+  | AuthenticatedState<T extends null ? never : T>
   | UnauthenticatedState<T>
   | (T extends SessionTokenType ? HandshakeState : never);
 
@@ -240,6 +244,29 @@ export function handshake(
   });
 }
 
+export function signedOutInvalidToken(): UnauthenticatedState<null> {
+  const authObject = invalidTokenAuthObject();
+  return {
+    status: AuthStatus.SignedOut,
+    reason: AuthErrorReason.TokenTypeMismatch,
+    message: '',
+    proxyUrl: '',
+    publishableKey: '',
+    isSatellite: false,
+    domain: '',
+    signInUrl: '',
+    signUpUrl: '',
+    afterSignInUrl: '',
+    afterSignUpUrl: '',
+    isSignedIn: false,
+    isAuthenticated: false,
+    tokenType: null,
+    toAuth: () => authObject,
+    headers: new Headers(),
+    token: null,
+  };
+}
+
 const withDebugHeaders = <T extends { headers: Headers; message?: string; reason?: AuthReason; status?: AuthStatus }>(
   requestState: T,
 ): T => {

packages/backend/src/tokens/request.ts

@@ -10,7 +10,7 @@ import type { AuthenticateContext } from './authenticateContext';
 import { createAuthenticateContext } from './authenticateContext';
 import type { SignedInAuthObject } from './authObjects';
 import type { HandshakeState, RequestState, SignedInState, SignedOutState, UnauthenticatedState } from './authStatus';
-import { AuthErrorReason, handshake, signedIn, signedOut } from './authStatus';
+import { AuthErrorReason, handshake, signedIn, signedOut, signedOutInvalidToken } from './authStatus';
 import { createClerkRequest } from './clerkRequest';
 import { getCookieName, getCookieValue } from './cookie';
 import { HandshakeService } from './handshake';
@@ -88,6 +88,23 @@ function checkTokenTypeMismatch(
   return null;
 }
 
+function isTokenTypeInAcceptedArray(
+  acceptsToken: ReadonlyArray<TokenType>,
+  authenticateContext: AuthenticateContext,
+): boolean {
+  let parsedTokenType: TokenType | null = null;
+  const { tokenInHeader } = authenticateContext;
+  if (tokenInHeader) {
+    if (isMachineTokenByPrefix(tokenInHeader)) {
+      parsedTokenType = getMachineTokenType(tokenInHeader);
+    } else {
+      parsedTokenType = TokenType.SessionToken;
+    }
+  }
+  const typeToCheck = parsedTokenType ?? TokenType.SessionToken;
+  return isTokenTypeAccepted(typeToCheck, acceptsToken as TokenType[]);
+}
+
 export interface AuthenticateRequest {
   /**
    * @example
@@ -96,7 +113,7 @@ export interface AuthenticateRequest {
   <T extends readonly TokenType[]>(
     request: Request,
     options: AuthenticateRequestOptions & { acceptsToken: T },
-  ): Promise<RequestState<T[number]>>;
+  ): Promise<RequestState<T[number] | null>>;
 
   /**
    * @example
@@ -123,7 +140,7 @@ export interface AuthenticateRequest {
 export const authenticateRequest: AuthenticateRequest = (async (
   request: Request,
   options: AuthenticateRequestOptions,
-): Promise<RequestState<TokenType>> => {
+): Promise<RequestState<TokenType> | UnauthenticatedState<null>> => {
   const authenticateContext = await createAuthenticateContext(createClerkRequest(request), options);
   assertValidSecretKey(authenticateContext.secretKey);
 
@@ -652,16 +669,6 @@ export const authenticateRequest: AuthenticateRequest = (async (
       return handleSessionTokenError(new Error('Missing token in header'), 'header');
     }
 
-    // Handle case where tokenType is any and the token is not a machine token
-    if (!isMachineTokenByPrefix(tokenInHeader)) {
-      return signedOut({
-        tokenType: acceptsToken as MachineTokenType,
-        authenticateContext,
-        reason: AuthErrorReason.TokenTypeMismatch,
-        message: '',
-      });
-    }
-
     const parsedTokenType = getMachineTokenType(tokenInHeader);
     const mismatchState = checkTokenTypeMismatch(parsedTokenType, acceptsToken, authenticateContext);
     if (mismatchState) {
@@ -722,15 +729,21 @@ export const authenticateRequest: AuthenticateRequest = (async (
     });
   }
 
+  // If acceptsToken is an array, early check if the token is in the accepted array
+  // to avoid unnecessary verification calls
+  if (Array.isArray(acceptsToken)) {
+    if (!isTokenTypeInAcceptedArray(acceptsToken, authenticateContext)) {
+      return signedOutInvalidToken();
+    }
+  }
+
   if (authenticateContext.tokenInHeader) {
     if (acceptsToken === 'any') {
       return authenticateAnyRequestWithTokenInHeader();
     }
-
     if (acceptsToken === TokenType.SessionToken) {
       return authenticateRequestWithTokenInHeader();
     }
-
     return authenticateMachineRequestWithTokenInHeader();
   }
 

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

@@ -477,15 +477,15 @@ describe('clerkMiddleware(params)', () => {
       const req = mockRequest({
         url: '/api/protected',
         headers: new Headers({
-          [constants.Headers.Authorization]: 'Bearer api_key_xxxxxxxxxxxxxxxxxx',
+          [constants.Headers.Authorization]: 'Bearer ak_123',
         }),
       });
 
       authenticateRequestMock.mockResolvedValueOnce({
         publishableKey,
         status: AuthStatus.SignedIn,
         headers: new Headers(),
-        toAuth: () => ({ tokenType: TokenType.ApiKey, id: 'api_key_xxxxxxxxxxxxxxxxxx' }),
+        toAuth: () => ({ tokenType: TokenType.ApiKey, id: 'ak_123', isAuthenticated: true }),
       });
 
       const resp = await clerkMiddleware(async auth => {
@@ -525,7 +525,7 @@ describe('clerkMiddleware(params)', () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({
-          [constants.Headers.Authorization]: 'Bearer api_key_xxxxxxxxxxxxxxxxxx',
+          [constants.Headers.Authorization]: 'Bearer ak_123',
         }),
       });
 
@@ -552,7 +552,7 @@ describe('clerkMiddleware(params)', () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({
-          [constants.Headers.Authorization]: 'Bearer oauth_token_xxxxxxxxxxxxxxxxxx',
+          [constants.Headers.Authorization]: 'Bearer oat_123',
         }),
       });
 
@@ -658,7 +658,7 @@ describe('clerkMiddleware(params)', () => {
       const req = mockRequest({
         url: '/api/protected',
         headers: new Headers({
-          [constants.Headers.Authorization]: 'Bearer m2m_xxxxxxxxxxxxxxxxxx',
+          [constants.Headers.Authorization]: 'Bearer m2m_123',
         }),
       });
 
@@ -681,15 +681,15 @@ describe('clerkMiddleware(params)', () => {
       const req = mockRequest({
         url: '/api/protected',
         headers: new Headers({
-          [constants.Headers.Authorization]: 'Bearer api_key_xxx',
+          [constants.Headers.Authorization]: 'Bearer ak_123',
         }),
       });
 
       authenticateRequestMock.mockResolvedValueOnce({
         publishableKey,
         status: AuthStatus.SignedIn,
         headers: new Headers(),
-        toAuth: () => ({ tokenType: TokenType.ApiKey, id: 'api_key_xxxxxxxxxxxxxxxxxx' }),
+        toAuth: () => ({ tokenType: TokenType.ApiKey, id: 'ak_123', isAuthenticated: true }),
       });
 
       const resp = await clerkMiddleware(async auth => {
@@ -705,7 +705,7 @@ describe('clerkMiddleware(params)', () => {
       const req = mockRequest({
         url: '/api/protected',
         headers: new Headers({
-          [constants.Headers.Authorization]: 'Bearer api_key_xxx',
+          [constants.Headers.Authorization]: 'Bearer ak_123',
         }),
       });