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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }
 

.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 `authenticateRequest()`: 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';
@@ -236,7 +236,7 @@ expect.extend({
  toBeMachineUnauthenticated(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  reason: AuthReason;
  message: string;
  },
@@ -246,6 +246,7 @@ expect.extend({
  received.tokenType === expected.tokenType &&
  received.reason === expected.reason &&
  received.message === expected.message &&
+ !received.isAuthenticated &&
  !received.token;
 
  if (pass) {
@@ -264,15 +265,11 @@ expect.extend({
  toBeMachineUnauthenticatedToAuth(
  received,
  expected: {
- tokenType: MachineTokenType;
+ tokenType: MachineTokenType | null;
  },
  ) {
  const pass =
- received.tokenType === expected.tokenType &&
- !received.claims &&
- !received.subject &&
- !received.name &&
- !received.id;
+ received.tokenType === expected.tokenType && !received.isAuthenticated && !received.name && !received.id;
 
  if (pass) {
  return {
@@ -1203,7 +1200,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 +1237,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(requestState.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType,
+ isAuthenticated: false,
  });
  });
  });
@@ -1289,6 +1287,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'api_key',
+ isAuthenticated: false,
  });
  });
 
@@ -1303,6 +1302,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'oauth_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1317,6 +1317,7 @@ describe('tokens.authenticateRequest(options)', () => {
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
 
@@ -1328,9 +1329,11 @@ describe('tokens.authenticateRequest(options)', () => {
  tokenType: 'machine_token',
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
+ isAuthenticated: false,
  });
  expect(result.toAuth()).toBeMachineUnauthenticatedToAuth({
  tokenType: 'machine_token',
+ isAuthenticated: false,
  });
  });
  });
@@ -1360,12 +1363,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 withDebugHeaders({
+ 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,20 @@ function checkTokenTypeMismatch(
  return null;
 }
 
+function isTokenTypeInAcceptedArray(acceptsToken: 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);
+}
+
 export interface AuthenticateRequest {
  /**
  * @example
@@ -96,7 +110,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 +137,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);
 
@@ -655,7 +669,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  // Handle case where tokenType is any and the token is not a machine token
  if (!isMachineTokenByPrefix(tokenInHeader)) {
  return signedOut({
- tokenType: acceptsToken as MachineTokenType,
+ tokenType: acceptsToken as TokenType,
  authenticateContext,
  reason: AuthErrorReason.TokenTypeMismatch,
  message: '',
@@ -722,15 +736,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();
  }