feat(express,fastify,tanstack-react-start,react-router): Support machine auth tokens in getAuth() (#6067)

Author: wobsoriano

.changeset/free-times-refuse.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Re-organize internal types for the recently added "machine authentication" feature. 

.changeset/large-adults-juggle.md

@@ -0,0 +1,30 @@
+---
+'@clerk/tanstack-react-start': minor
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed by using the `acceptsToken` option in the `getAuth()` function. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { getAuth } from '@clerk/tanstack-react-start/server'
+import { getWebRequest } from '@tanstack/react-start/server'
+
+const authStateFn = createServerFn({ method: 'GET' }).handler(async () => {
+    const request = getWebRequest()
+    const auth = await getAuth(request, { acceptsToken: 'any' })
+
+    if (authObject.tokenType === 'session_token') {
+        console.log('this is session token from a user')
+    } else {
+        console.log('this is some other type of machine token')
+        console.log('more specifically, a ' + authObject.tokenType)
+    }
+
+    return {}
+})
+
+```

.changeset/sour-onions-wear.md

@@ -0,0 +1,27 @@
+---
+'@clerk/express': minor
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed by using the `acceptsToken` option in the `getAuth()` function. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+import express from 'express';
+import { getAuth } from '@clerk/express';
+
+const app = express();
+
+app.get('/path', (req, res) => {
+  const authObject = getAuth(req, { acceptsToken: 'any' });
+
+  if (authObject.tokenType === 'session_token') {
+    console.log('this is session token from a user')
+  } else {
+    console.log('this is some other type of machine token')
+    console.log('more specifically, a ' + authObject.tokenType)
+  }
+});
+```

.changeset/two-trains-pull.md

@@ -0,0 +1,27 @@
+---
+'@clerk/react-router': minor
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed by using the `acceptsToken` option in the `getAuth()` function. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+import { getAuth } from '@clerk/react-router/ssr.server'
+import type { Route } from './+types/profile'
+
+export async function loader(args: Route.LoaderArgs) {
+  const authObject = await getAuth(args, { acceptsToken: 'any' })
+
+  if (authObject.tokenType === 'session_token') {
+    console.log('this is session token from a user')
+  } else {
+    console.log('this is some other type of machine token')
+    console.log('more specifically, a ' + authObject.tokenType)
+  }
+
+  return {}
+}
+```

.changeset/yummy-socks-join.md

@@ -0,0 +1,27 @@
+---
+'@clerk/fastify': minor
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed by using the `acceptsToken` option in the `getAuth()` function. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+import Fastify from 'fastify'
+import { getAuth } from '@clerk/fastify'
+
+const fastify = Fastify()
+
+fastify.get('/path', (request, reply) => {
+  const authObject = getAuth(req, { acceptsToken: 'any' });
+
+  if (authObject.tokenType === 'session_token') {
+    console.log('this is session token from a user')
+  } else {
+    console.log('this is some other type of machine token')
+    console.log('more specifically, a ' + authObject.tokenType)
+  }
+});
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -150,7 +150,10 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "backend/client.mdx",
   "backend/email-address.mdx",
   "backend/external-account.mdx",
+  "backend/get-auth-fn.mdx",
   "backend/identification-link.mdx",
+  "backend/infer-auth-object-from-token-array.mdx",
+  "backend/infer-auth-object-from-token.mdx",
   "backend/invitation-status.mdx",
   "backend/invitation.mdx",
   "backend/organization-invitation-status.mdx",

packages/backend/src/__tests__/exports.test.ts

@@ -47,6 +47,7 @@ describe('subpath /internal exports', () => {
         "createRedirect",
         "debugRequestState",
         "decorateObjectWithResources",
+        "getAuthObjectForAcceptedToken",
         "getAuthObjectFromJwt",
         "getMachineTokenType",
         "isMachineToken",

packages/backend/src/internal.ts

@@ -7,7 +7,15 @@ export { createAuthenticateRequest } from './tokens/factory';
 
 export { debugRequestState } from './tokens/request';
 
-export type { AuthenticateRequestOptions, OrganizationSyncOptions } from './tokens/types';
+export type {
+  AuthenticateRequestOptions,
+  OrganizationSyncOptions,
+  InferAuthObjectFromToken,
+  InferAuthObjectFromTokenArray,
+  SessionAuthObject,
+  MachineAuthObject,
+  GetAuthFn,
+} from './tokens/types';
 
 export { TokenType } from './tokens/tokenTypes';
 export type { SessionTokenType, MachineTokenType } from './tokens/tokenTypes';
@@ -26,6 +34,7 @@ export {
   authenticatedMachineObject,
   unauthenticatedMachineObject,
   getAuthObjectFromJwt,
+  getAuthObjectForAcceptedToken,
 } from './tokens/authObjects';
 
 export { AuthStatus } from './tokens/authStatus';

packages/backend/src/tokens/authObjects.ts

@@ -13,10 +13,11 @@ import type {
 
 import type { APIKey, CreateBackendApiOptions, MachineToken } from '../api';
 import { createBackendApiClient } from '../api';
+import { isTokenTypeAccepted } from '../internal';
 import type { AuthenticateContext } from './authenticateContext';
 import type { MachineTokenType, SessionTokenType } from './tokenTypes';
 import { TokenType } from './tokenTypes';
-import type { MachineAuthType } from './types';
+import type { AuthenticateRequestOptions, MachineAuthType } from './types';
 
 /**
  * @inline
@@ -361,3 +362,63 @@ export const getAuthObjectFromJwt = (
 
   return authObject;
 };
+
+/**
+ * @internal
+ * Filters and coerces an AuthObject based on the accepted token type(s).
+ *
+ * This function is used after authentication to ensure that the returned auth object
+ * matches the expected token type(s) specified by `acceptsToken`. If the token type
+ * of the provided `authObject` does not match any of the types in `acceptsToken`,
+ * it returns an unauthenticated or signed-out version of the object, depending on the token type.
+ *
+ * - If `acceptsToken` is `'any'`, the original auth object is returned.
+ * - If `acceptsToken` is a single token type or an array of token types, the function checks if
+ *   `authObject.tokenType` matches any of them.
+ * - If the token type does not match and is a session token, a signed-out object is returned.
+ * - If the token type does not match and is a machine token, an unauthenticated machine object is returned.
+ * - If the token type matches, the original auth object is returned.
+ *
+ * @param {Object} params
+ * @param {AuthObject} params.authObject - The authenticated object to filter.
+ * @param {AuthenticateRequestOptions['acceptsToken']} [params.acceptsToken=TokenType.SessionToken] - The accepted token type(s). Can be a string, array of strings, or 'any'.
+ * @returns {AuthObject} The filtered or coerced auth object.
+ *
+ * @example
+ * // Accept only 'api_key' tokens
+ * const authObject = { tokenType: 'session_token', userId: 'user_123' };
+ * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: 'api_key' });
+ * // result will be a signed-out object (since tokenType is 'session_token' and does not match)
+ *
+ * @example
+ * // Accept 'api_key' or 'machine_token'
+ * const authObject = { tokenType: 'machine_token', id: 'mt_123' };
+ * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: ['api_key', 'machine_token'] });
+ * // result will be the original authObject (since tokenType matches one in the array)
+ *
+ * @example
+ * // Accept any token type
+ * const authObject = { tokenType: 'api_key', id: 'ak_123' };
+ * const result = getAuthObjectForAcceptedToken({ authObject, acceptsToken: 'any' });
+ * // result will be the original authObject
+ */
+export function getAuthObjectForAcceptedToken({
+  authObject,
+  acceptsToken = TokenType.SessionToken,
+}: {
+  authObject: AuthObject;
+  acceptsToken: AuthenticateRequestOptions['acceptsToken'];
+}): AuthObject {
+  if (acceptsToken === 'any') {
+    return authObject;
+  }
+
+  if (!isTokenTypeAccepted(authObject.tokenType, acceptsToken)) {
+    if (authObject.tokenType === TokenType.SessionToken) {
+      return signedOutAuthObject(authObject.debug);
+    }
+    return unauthenticatedMachineObject(authObject.tokenType, authObject.debug);
+  }
+
+  return authObject;
+}

packages/backend/src/tokens/types.ts

@@ -1,7 +1,15 @@
 import type { MatchFunction } from '@clerk/shared/pathToRegexp';
+import type { PendingSessionOptions } from '@clerk/types';
 
 import type { ApiClient, APIKey, IdPOAuthAccessToken, MachineToken } from '../api';
-import type { TokenType } from './tokenTypes';
+import type {
+  AuthenticatedMachineObject,
+  AuthObject,
+  SignedInAuthObject,
+  SignedOutAuthObject,
+  UnauthenticatedMachineObject,
+} from './authObjects';
+import type { SessionTokenType, TokenType } from './tokenTypes';
 import type { VerifyTokenOptions } from './verify';
 
 /**
@@ -141,3 +149,76 @@ export type OrganizationSyncTargetMatchers = {
 export type OrganizationSyncTarget =
   | { type: 'personalAccount' }
   | { type: 'organization'; organizationId?: string; organizationSlug?: string };
+
+/**
+ * Infers auth object type from an array of token types.
+ * - Session token only -> SessionType
+ * - Mixed tokens -> SessionType | MachineType
+ * - Machine tokens only -> MachineType
+ */
+export type InferAuthObjectFromTokenArray<
+  T extends readonly TokenType[],
+  SessionType extends AuthObject,
+  MachineType extends AuthObject,
+> = SessionTokenType extends T[number]
+  ? T[number] extends SessionTokenType
+    ? SessionType
+    : SessionType | (MachineType & { tokenType: T[number] })
+  : MachineType & { tokenType: T[number] };
+
+/**
+ * Infers auth object type from a single token type.
+ * Returns SessionType for session tokens, or MachineType for machine tokens.
+ */
+export type InferAuthObjectFromToken<
+  T extends TokenType,
+  SessionType extends AuthObject,
+  MachineType extends AuthObject,
+> = T extends SessionTokenType ? SessionType : MachineType & { tokenType: T };
+
+export type SessionAuthObject = SignedInAuthObject | SignedOutAuthObject;
+export type MachineAuthObject<T extends TokenType> = (AuthenticatedMachineObject | UnauthenticatedMachineObject) & {
+  tokenType: T;
+};
+
+type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;
+
+/**
+ * Shared generic overload type for getAuth() helpers across SDKs.
+ *
+ * - Parameterized by the request type (RequestType).
+ * - Handles different accepted token types and their corresponding return types.
+ */
+export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
+  /**
+   * @example
+   * const auth = await getAuth(req, { acceptsToken: ['session_token', 'api_key'] })
+   */
+  <T extends TokenType[]>(
+    req: RequestType,
+    options: AuthOptions & { acceptsToken: T },
+  ): MaybePromise<InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<T[number]>>, ReturnsPromise>;
+
+  /**
+   * @example
+   * const auth = await getAuth(req, { acceptsToken: 'session_token' })
+   */
+  <T extends TokenType>(
+    req: RequestType,
+    options: AuthOptions & { acceptsToken: T },
+  ): MaybePromise<InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<T>>, ReturnsPromise>;
+
+  /**
+   * @example
+   * const auth = await getAuth(req, { acceptsToken: 'any' })
+   */
+  (req: RequestType, options: AuthOptions & { acceptsToken: 'any' }): MaybePromise<AuthObject, ReturnsPromise>;
+
+  /**
+   * @example
+   * const auth = await getAuth(req)
+   */
+  (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
+}

packages/express/src/__tests__/getAuth.test.ts

@@ -2,16 +2,46 @@ import { getAuth } from '../getAuth';
 import { mockRequest, mockRequestWithAuth } from './helpers';
 
 describe('getAuth', () => {
-  it('throws error if clerkMiddleware is not executed before getAuth', async () => {
+  it('throws error if clerkMiddleware is not executed before getAuth', () => {
     expect(() => getAuth(mockRequest())).toThrow(/The "clerkMiddleware" should be registered before using "getAuth"/);
   });
 
-  it('returns auth from request for signed-out request', async () => {
-    expect(getAuth(mockRequestWithAuth())).toHaveProperty('userId', null);
+  it('returns auth from request for signed-out request', () => {
+    const req = mockRequestWithAuth({ userId: null, tokenType: 'session_token' });
+    const auth = getAuth(req);
+    expect(auth.userId).toBeNull();
+    expect(auth.tokenType).toBe('session_token');
   });
 
-  it('returns auth from request', async () => {
-    const req = mockRequestWithAuth({ userId: 'user_12345' });
-    expect(getAuth(req)).toHaveProperty('userId', 'user_12345');
+  it('returns auth from request', () => {
+    const req = mockRequestWithAuth({ userId: 'user_12345', tokenType: 'session_token' });
+    const auth = getAuth(req);
+    expect(auth.userId).toBe('user_12345');
+    expect(auth.tokenType).toBe('session_token');
+  });
+
+  it('returns the actual auth object when its tokenType matches acceptsToken', () => {
+    const req = mockRequestWithAuth({ tokenType: 'api_key', id: 'ak_1234', subject: 'api_key_1234' });
+    const result = getAuth(req, { acceptsToken: 'api_key' });
+    expect(result.tokenType).toBe('api_key');
+    expect(result.id).toBe('ak_1234');
+    expect(result.subject).toBe('api_key_1234');
+  });
+
+  it('returns the actual auth object if its tokenType is included in the acceptsToken array', () => {
+    const req = mockRequestWithAuth({ tokenType: 'machine_token', id: 'mt_1234' });
+    const result = getAuth(req, { acceptsToken: ['machine_token', 'api_key'] });
+    expect(result.tokenType).toBe('machine_token');
+    expect(result.id).toBe('mt_1234');
+    expect(result.subject).toBeUndefined();
+  });
+
+  it('returns an unauthenticated auth object when the tokenType does not match acceptsToken', () => {
+    const req = mockRequestWithAuth({ tokenType: 'session_token', userId: 'user_12345' });
+    const result = getAuth(req, { acceptsToken: 'api_key' });
+    expect(result.tokenType).toBe('session_token'); // reflects the actual token found
+    // Properties specific to authenticated objects should be null or undefined
+    // @ts-expect-error - userId is not a property of the unauthenticated object
+    expect(result.userId).toBeNull();
   });
 });