chore(backend): Add getAuth() type helper tests

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();

.changeset/social-carrots-melt.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Resolve machine token property mixing in discriminated unions

packages/backend/src/index.ts

@@ -162,3 +162,4 @@ export type {
  * Auth objects
  */
 export type { AuthObject } from './tokens/authObjects';
+export type { SessionAuthObject, MachineAuthObject } from './tokens/types';

packages/backend/src/internal.ts

@@ -12,8 +12,6 @@ export type {
  OrganizationSyncOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- SessionAuthObject,
- MachineAuthObject,
  GetAuthFn,
 } from './tokens/types';
 

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

@@ -0,0 +1,107 @@
+import { assertType, test } from 'vitest';
+
+import type { AuthObject } from '../authObjects';
+import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';
+
+// Across our SDKs, we have a getAuth() function
+const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
+ return {} as any;
+};
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token by default
+ assertType<SessionAuthObject>(getAuth(request));
+
+ // Individual token types
+ assertType<SessionAuthObject>(getAuth(request, { acceptsToken: 'session_token' }));
+ assertType<MachineAuthObject<'api_key'>>(getAuth(request, { acceptsToken: 'api_key' }));
+ assertType<MachineAuthObject<'machine_token'>>(getAuth(request, { acceptsToken: 'machine_token' }));
+ assertType<MachineAuthObject<'oauth_token'>>(getAuth(request, { acceptsToken: 'oauth_token' }));
+
+ // Array of token types
+ assertType<SessionAuthObject | MachineAuthObject<'machine_token'>>(
+ getAuth(request, { acceptsToken: ['session_token', 'machine_token'] }),
+ );
+ assertType<MachineAuthObject<'machine_token' | 'oauth_token'>>(
+ getAuth(request, { acceptsToken: ['machine_token', 'oauth_token'] }),
+ );
+
+ // Any token type
+ assertType<AuthObject>(getAuth(request, { acceptsToken: 'any' }));
+});
+
+test('verifies correct properties exist for each token type', () => {
+ const request = new Request('https://example.com');
+
+ // Session token should have userId
+ const sessionAuth = getAuth(request, { acceptsToken: 'session_token' });
+ assertType<string | null>(sessionAuth.userId);
+
+ // All machine tokens should have id and subject
+ const apiKeyAuth = getAuth(request, { acceptsToken: 'api_key' });
+ const machineTokenAuth = getAuth(request, { acceptsToken: 'machine_token' });
+ const oauthTokenAuth = getAuth(request, { acceptsToken: 'oauth_token' });
+
+ assertType<string | null>(apiKeyAuth.id);
+ assertType<string | null>(machineTokenAuth.id);
+ assertType<string | null>(oauthTokenAuth.id);
+ assertType<string | null>(apiKeyAuth.subject);
+ assertType<string | null>(machineTokenAuth.subject);
+ assertType<string | null>(oauthTokenAuth.subject);
+
+ // Only api_key and machine_token should have name and claims
+ assertType<string | null>(apiKeyAuth.name);
+ assertType<Record<string, any> | null>(apiKeyAuth.claims);
+
+ assertType<string | null>(machineTokenAuth.name);
+ assertType<Record<string, any> | null>(machineTokenAuth.claims);
+
+ // oauth_token should NOT have name and claims
+ // @ts-expect-error oauth_token does not have name property
+ void oauthTokenAuth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void oauthTokenAuth.claims;
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ const request = new Request('https://example.com');
+
+ const auth = getAuth(request, { acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ // Should be SessionAuthObject - has userId
+ assertType<string | null>(auth.userId);
+ // Should NOT have machine token properties
+ // @ts-expect-error session_token does not have id property
+ void auth.id;
+ } else if (auth.tokenType === 'api_key') {
+ // Should be AuthenticatedMachineObject<'api_key'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error api_key does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'machine_token') {
+ // Should be AuthenticatedMachineObject<'machine_token'> - has id, name, claims
+ assertType<string | null>(auth.id);
+ assertType<string | null>(auth.name);
+ assertType<Record<string, any> | null>(auth.claims);
+ // Should NOT have session token properties
+ // @ts-expect-error machine_token does not have userId property
+ void auth.userId;
+ } else if (auth.tokenType === 'oauth_token') {
+ // Should be AuthenticatedMachineObject<'oauth_token'> - has id but NOT name/claims
+ assertType<string | null>(auth.id);
+ // Should NOT have name or claims
+ // @ts-expect-error oauth_token does not have name property
+ void auth.name;
+ // @ts-expect-error oauth_token does not have claims property
+ void auth.claims;
+ // Should NOT have session token properties
+ // @ts-expect-error oauth_token does not have userId property
+ void auth.userId;
+ }
+});

packages/backend/src/tokens/authObjects.ts

@@ -104,29 +104,43 @@ type MachineObjectExtendedProperties<TAuthenticated extends boolean> = {
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: string;
- subject: string;
- scopes: string[];
- getToken: () => Promise<string>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<true>[T];
+export type AuthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: string;
+ subject: string;
+ scopes: string[];
+ getToken: () => Promise<string>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<true>[T]
+ : never;
 
 /**
  * @internal
+ *
+ * Uses `T extends any` to create a distributive conditional type.
+ * This ensures that union types like `'api_key' | 'oauth_token'` are processed
+ * individually, creating proper discriminated unions where each token type
+ * gets its own distinct properties (e.g., oauth_token won't have claims).
  */
-export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = {
- id: null;
- subject: null;
- scopes: null;
- getToken: () => Promise<null>;
- has: CheckAuthorizationFromSessionClaims;
- debug: AuthObjectDebug;
- tokenType: T;
-} & MachineObjectExtendedProperties<false>[T];
+export type UnauthenticatedMachineObject<T extends MachineTokenType = MachineTokenType> = T extends any
+ ? {
+ id: null;
+ subject: null;
+ scopes: null;
+ getToken: () => Promise<null>;
+ has: CheckAuthorizationFromSessionClaims;
+ debug: AuthObjectDebug;
+ tokenType: T;
+ } & MachineObjectExtendedProperties<false>[T]
+ : never;
 
 /**
  * @interface
@@ -243,7 +257,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  const result = verificationResult as MachineToken;
@@ -253,7 +267,7 @@ export function authenticatedMachineObject<T extends MachineTokenType>(
  name: result.name,
  claims: result.claims,
  scopes: result.scopes,
- };
+ } as unknown as AuthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {
@@ -290,15 +304,15 @@ export function unauthenticatedMachineObject<T extends MachineTokenType>(
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.MachineToken: {
  return {
  ...baseObject,
  tokenType,
  name: null,
  claims: null,
- };
+ } as unknown as UnauthenticatedMachineObject<T>;
  }
  case TokenType.OAuthToken: {
  return {

packages/backend/src/tokens/types.ts

@@ -163,8 +163,8 @@ export type InferAuthObjectFromTokenArray<
 > = SessionTokenType extends T[number]
  ? T[number] extends SessionTokenType
  ? SessionType
- : SessionType | (MachineType & { tokenType: T[number] })
- : MachineType & { tokenType: T[number] };
+ : SessionType | (MachineType & { tokenType: Exclude<T[number], SessionTokenType> })
+ : MachineType & { tokenType: Exclude<T[number], SessionTokenType> };
 
 /**
  * Infers auth object type from a single token type.
@@ -174,12 +174,12 @@ export type InferAuthObjectFromToken<
  T extends TokenType,
  SessionType extends AuthObject,
  MachineType extends AuthObject,
-> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: Exclude<T, SessionTokenType> };
 
 export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
-export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
-tokenType: T;
-};
+export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> = T extends any
+? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
+ : never;
 
 type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
 
@@ -199,7 +199,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType[]>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example
@@ -208,7 +211,10 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
  <T extends TokenType>(
  req: RequestType,
  options: AuthOptions & { acceptsToken: T },
- ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+ ): MaybePromise<
+ InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>,
+ ReturnsPromise
+ >;
 
  /**
  * @example

packages/backend/vitest.config.mts

@@ -3,6 +3,10 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  plugins: [],
  test: {
+ typecheck: {
+ enabled: true,
+ include: ['**/*.test.ts'],
+ },
  coverage: {
  provider: 'v8',
  },

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

@@ -1,11 +1,10 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
 import type {
  AuthenticateRequestOptions,
  InferAuthObjectFromToken,
  InferAuthObjectFromTokenArray,
- MachineAuthObject,
  RedirectFun,
-SessionAuthObject,
+SessionTokenType,
 } from '@clerk/backend/internal';
 import { constants, createClerkRequest, createRedirect, TokenType } from '@clerk/backend/internal';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -56,15 +55,23 @@ export interface AuthFn<TRedirect = ReturnType<typeof redirect>> {
  */
  <T extends TokenType[]>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromTokenArray<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T[number]>>>;
+ ): Promise<
+ InferAuthObjectFromTokenArray<
+ T,
+ SessionAuthWithRedirect<TRedirect>,
+ MachineAuthObject<Exclude<T[number], SessionTokenType>>
+ >
+ >;
 
  /**
  * @example
  * const authObject = await auth({ acceptsToken: 'session_token' })
  */
  <T extends TokenType>(
  options: AuthOptions & { acceptsToken: T },
- ): Promise<InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<T>>>;
+ ): Promise<
+ InferAuthObjectFromToken<T, SessionAuthWithRedirect<TRedirect>, MachineAuthObject<Exclude<T, SessionTokenType>>>
+ >;
 
  /**
  * @example

packages/nextjs/src/server/protect.ts

@@ -73,6 +73,12 @@ export interface AuthProtect {
  options?: AuthProtectOptions & { token: T },
  ): Promise<InferAuthObjectFromTokenArray<T, SignedInAuthObject, AuthenticatedMachineObject>>;
 
+ /**
+ * @example
+ * auth.protect({ token: 'any' });
+ */
+ (options?: AuthProtectOptions & { token: 'any' }): Promise<SignedInAuthObject | AuthenticatedMachineObject>;
+
  /**
  * @example
  * auth.protect();