feat(nuxt): Introduce machine auth

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}

.changeset/cool-guests-trade.md

@@ -0,0 +1,24 @@
+---
+'@clerk/nuxt': 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 `event.context.auth()` context. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+export default eventHandler((event) => {
+ const auth = event.locals.auth({ 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 {}
+})
+```

packages/nuxt/src/module.ts

@@ -110,13 +110,11 @@ export default defineNuxtModule<ModuleOptions>({
  {
  filename: 'types/clerk.d.ts',
  getContents: () => `import type { SessionAuthObject } from '@clerk/backend';
- declare module 'h3' {
- type AuthObjectHandler = SessionAuthObject & {
- (): SessionAuthObject;
- }
+ import type { AuthFn } from '@clerk/nuxt/server';
 
+ declare module 'h3' {
  interface H3EventContext {
- auth: AuthObjectHandler;
+ auth: SessionAuthObject & AuthFn;
  }
  }
  `,

packages/nuxt/src/runtime/server/__tests__/auth.test-d.ts

@@ -0,0 +1,56 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import { expectTypeOf, test } from 'vitest';
+
+import type { AuthFn } from '../types';
+
+test('infers the correct AuthObject type for each accepted token type', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ // Session token by default
+ expectTypeOf(event.locals.auth()).toMatchTypeOf<SessionAuthObject>();
+
+ // Individual token types
+ expectTypeOf(event.locals.auth({ acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'machine_token' })).toMatchTypeOf<
+ MachineAuthObject<'machine_token'>
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+
+ // Array of token types
+ expectTypeOf(event.locals.auth({ acceptsToken: ['session_token', 'machine_token'] })).toMatchTypeOf<
+ SessionAuthObject | MachineAuthObject<'machine_token'> | InvalidTokenAuthObject
+ >();
+ expectTypeOf(event.locals.auth({ acceptsToken: ['machine_token', 'oauth_token'] })).toMatchTypeOf<
+ MachineAuthObject<'machine_token' | 'oauth_token'> | InvalidTokenAuthObject
+ >();
+
+ // Any token type
+ expectTypeOf(event.locals.auth({ acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
+});
+
+test('verifies discriminated union works correctly with acceptsToken: any', () => {
+ // Mock event object
+ const event = {
+ locals: {
+ auth: (() => {}) as AuthFn,
+ },
+ };
+
+ const auth = event.locals.auth({ acceptsToken: 'any' });
+
+ if (auth.tokenType === 'session_token') {
+ expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
+ } else if (auth.tokenType === 'api_key') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
+ } else if (auth.tokenType === 'machine_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'machine_token'>>();
+ } else if (auth.tokenType === 'oauth_token') {
+ expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
+ }
+});

packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts

@@ -3,9 +3,31 @@ import { vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
 
-const AUTH_RESPONSE = {
+const SESSION_AUTH_RESPONSE = {
  userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
  sessionId: 'sess_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ tokenType: 'session_token',
+ isAuthenticated: true,
+ sessionStatus: 'active',
+ sessionClaims: {},
+ actor: null,
+ factorVerificationAge: null,
+ orgId: null,
+ orgRole: null,
+ orgSlug: null,
+ orgPermissions: null,
+};
+
+const MACHINE_AUTH_RESPONSE = {
+ id: 'ak_123456789',
+ subject: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ scopes: ['read:users', 'write:users'],
+ tokenType: 'api_key',
+ isAuthenticated: true,
+ name: 'Test API Key',
+ claims: { custom: 'claim' },
+ userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
+ orgId: null,
 };
 
 const MOCK_OPTIONS = {
@@ -22,7 +44,7 @@ vi.mock('#imports', () => {
 });
 
 const authenticateRequestMock = vi.fn().mockResolvedValue({
- toAuth: () => AUTH_RESPONSE,
+ toAuth: () => SESSION_AUTH_RESPONSE,
  headers: new Headers(),
 });
 
@@ -47,7 +69,7 @@ describe('clerkMiddleware(params)', () => {
  const response = await handler(new Request(new URL('/', 'http://localhost')));
 
  expect(response.status).toBe(200);
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('renders route as normally when used with options param', async () => {
@@ -62,7 +84,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler', async () => {
@@ -81,7 +103,7 @@ describe('clerkMiddleware(params)', () => {
 
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
  });
 
  test('executes handler and renders route when used with a custom handler and options', async () => {
@@ -101,6 +123,108 @@ describe('clerkMiddleware(params)', () => {
  expect(response.status).toBe(200);
  expect(response.headers.get('a-custom-header')).toBe('1');
  expect(authenticateRequestMock).toHaveBeenCalledWith(expect.any(Request), expect.objectContaining(MOCK_OPTIONS));
- expect(await response.json()).toEqual(AUTH_RESPONSE);
+ expect(await response.json()).toEqual(SESSION_AUTH_RESPONSE);
+ });
+
+ describe('machine authentication', () => {
+ test('returns machine auth object when acceptsToken is machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'api_key' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns machine auth object when acceptsToken array includes machine token type', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'api_key'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns any auth object when acceptsToken is any', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'any' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual(MACHINE_AUTH_RESPONSE);
+ });
+
+ test('returns unauthenticated machine object when token type does not match acceptsToken', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: 'machine_token' })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe('machine_token');
+ expect(result.isAuthenticated).toBe(false);
+ expect(result.id).toBe(null);
+ });
+
+ test('returns invalid token object when token type is not in acceptsToken array', async () => {
+ authenticateRequestMock.mockResolvedValueOnce({
+ toAuth: () => MACHINE_AUTH_RESPONSE,
+ headers: new Headers(),
+ });
+
+ const app = createApp();
+ const handler = toWebHandler(app);
+ app.use(clerkMiddleware());
+ app.use(
+ '/',
+ eventHandler(event => event.context.auth({ acceptsToken: ['session_token', 'machine_token'] })),
+ );
+ const response = await handler(new Request(new URL('/', 'http://localhost')));
+
+ expect(response.status).toBe(200);
+ const result = await response.json();
+ expect(result.tokenType).toBe(null);
+ expect(result.isAuthenticated).toBe(false);
+ });
  });
 });

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -1,11 +1,12 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
-import { AuthStatus, constants } from '@clerk/backend/internal';
+import { AuthStatus, constants, getAuthObjectForAcceptedToken, TokenType } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
 import { clerkClient } from './clerkClient';
+import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
 function parseHandlerAndOptions(args: unknown[]) {
@@ -81,7 +82,10 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  return eventHandler(async event => {
  const clerkRequest = toWebRequest(event);
 
- const requestState = await clerkClient(event).authenticateRequest(clerkRequest, options);
+ const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
+ ...options,
+ acceptsToken: 'any',
+ });
 
  const locationHeader = requestState.headers.get(constants.Headers.Location);
  if (locationHeader) {
@@ -105,13 +109,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  }
 
  const authObject = requestState.toAuth();
- const authHandler = () => authObject;
+ const authHandler: AuthFn = ((options?: AuthOptions) => {
+ const acceptsToken = options?.acceptsToken ?? TokenType.SessionToken;
+ return getAuthObjectForAcceptedToken({ authObject, acceptsToken });
+ }) as AuthFn;
 
- const auth = new Proxy(Object.assign(authHandler, authObject), {
- get(target, prop: string, receiver) {
+ const auth = new Proxy(authHandler, {
+ get(target, prop, receiver) {
  deprecated('event.context.auth', 'Use `event.context.auth()` as a function instead.');
-
- return Reflect.get(target, prop, receiver);
+ // If the property exists on the function, return it
+ if (prop in target) return Reflect.get(target, prop, receiver);
+ // Otherwise, get it from the authObject
+ return authObject?.[prop as keyof typeof authObject];
  },
  });
 

packages/nuxt/src/runtime/server/getAuth.ts

@@ -1,9 +1,15 @@
-import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { SessionAuthObject } from '@clerk/backend';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { H3Event } from 'h3';
 
 import { moduleRegistrationRequired } from './errors';
 
-export function getAuth(event: H3Event): SignedInAuthObject | SignedOutAuthObject {
+/**
+ * @deprecated Use `event.context.auth()` instead.
+ */
+export function getAuth(event: H3Event): SessionAuthObject {
+ deprecated('getAuth', 'Use `event.context.auth()` instead.');
+
  const authObject = event.context.auth();
 
  if (!authObject) {

packages/nuxt/src/runtime/server/index.ts

@@ -3,3 +3,4 @@ export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
 export { createRouteMatcher } from './routeMatcher';
 export { getAuth } from './getAuth';
+export type { AuthFn } from './types';

packages/nuxt/src/runtime/server/types.ts

@@ -0,0 +1,45 @@
+import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ InferAuthObjectFromToken,
+ InferAuthObjectFromTokenArray,
+ SessionTokenType,
+ TokenType,
+} from '@clerk/backend/internal';
+
+export type AuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
+
+/**
+ * @internal This type is used to define the `auth` function in the event context.
+ */
+export interface AuthFn {
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: ['session_token', 'api_key'] })
+ */
+ <T extends TokenType[]>(
+ options: AuthOptions & { acceptsToken: T },
+ ):
+ | InferAuthObjectFromTokenArray<T, SessionAuthObject, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
+ | InvalidTokenAuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'session_token' })
+ */
+ <T extends TokenType>(
+ options: AuthOptions & { acceptsToken: T },
+ ): InferAuthObjectFromToken<T, SessionAuthObject, MachineAuthObject<Exclude<T, SessionTokenType>>>;
+
+ /**
+ * @example
+ * const auth = event.context.auth({ acceptsToken: 'any' })
+ */
+ (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;
+
+ /**
+ * @example
+ * const auth = event.context.auth()
+ */
+ (): SessionAuthObject;
+}