chore(backend,nextjs): [WIP] auth helper improvements and integration tests

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
     "pk": "",
     "sk": ""
+  },
+  "with-api-keys": {
+    "pk": "",
+    "sk": ""
   }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
   .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
   .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+  .clone()
+  .setId('withAPIKeys')
+  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
   base,
   withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
   withBillingStaging,
   withBilling,
   withWhatsappPhoneCode,
+  withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
       config: next.appRouter,
       env: envs.withSessionTasks,
     },
+    { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
     { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
     { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
     { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/templates/next-app-router/src/app/api/machine/route.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from 'next/server';
+import { auth } from '@clerk/nextjs/server';
+
+export async function GET() {
+  const { userId } = await auth({ acceptsToken: 'api_key' });
+
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  return NextResponse.json({ userId });
+}
+
+export async function POST() {
+  const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+  if (!authObject.isAuthenticated) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  return NextResponse.json({ userId: authObject.userId });
+}

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
   return backendCreateClerkClient({
     apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
   delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+  apiKey: APIKey;
+  secret: string;
+  revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
   createFakeUser: (options?: FakeUserOptions) => FakeUser;
   createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
   deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
   createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
   getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+  createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
         delete: () => clerkClient.organizations.deleteOrganization(organization.id),
       } satisfies FakeOrganization;
     },
+    createFakeAPIKey: async (userId: string) => {
+      const THIRTY_MINUTES = 30 * 60;
+
+      const apiKey = await clerkClient.apiKeys.create({
+        subject: userId,
+        name: faker.company.buzzPhrase(),
+        secondsUntilExpiration: THIRTY_MINUTES,
+      });
+
+      const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+      return {
+        apiKey,
+        secret,
+        revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+      } satisfies FakeAPIKey;
+    },
   };
 
   return self;

integration/tests/api-keys/auth.test.ts

@@ -0,0 +1,86 @@
+import { type User } from '@clerk/backend';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withAPIKeys] })('auth() with API keys @xnextjs', ({ app }) => {
+  test.describe.configure({ mode: 'parallel' });
+
+  let fakeUser: FakeUser;
+  let fakeBapiUser: User;
+  let fakeAPIKey: FakeAPIKey;
+  const u = createTestUtils({ app });
+
+  test.beforeAll(async () => {
+    fakeUser = u.services.users.createFakeUser();
+    fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+    fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+  });
+
+  test.afterAll(async () => {
+    await fakeAPIKey.revoke();
+    await fakeUser.deleteIfExists();
+    await app.teardown();
+  });
+
+  test('should validate API key', async () => {
+    const url = new URL('/api/machine', app.serverUrl);
+
+    // No API key provided
+    const noKeyRes = await fetch(url);
+    expect(noKeyRes.status).toBe(401);
+
+    // Invalid API key
+    const invalidKeyRes = await fetch(url, {
+      headers: {
+        Authorization: 'Bearer invalid_key',
+      },
+    });
+    expect(invalidKeyRes.status).toBe(401);
+
+    // Valid API key
+    const validKeyRes = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${fakeAPIKey.secret}`,
+      },
+    });
+    const apiKeyData = await validKeyRes.json();
+    expect(validKeyRes.status).toBe(200);
+    expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+  });
+
+  test('should handle multiple token types', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    const url = new URL('/api/machine', app.serverUrl);
+
+    // Sign in to get a session token
+    await u.po.signIn.goTo();
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+    await u.po.expect.toBeSignedIn();
+
+    // GET endpoint (only accepts api_key)
+    const getRes = await u.page.request.get(url.toString());
+    expect(getRes.status()).toBe(401);
+
+    // POST endpoint (accepts both api_key and session_token)
+    // Test with session token
+    const postWithSessionRes = await u.page.request.post(url.toString());
+    const sessionData = await postWithSessionRes.json();
+    expect(postWithSessionRes.status()).toBe(200);
+    expect(sessionData.userId).toBe(fakeBapiUser.id);
+
+    // Test with API key
+    const postWithApiKeyRes = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${fakeAPIKey.secret}`,
+      },
+    });
+    const apiKeyData = await postWithApiKeyRes.json();
+    expect(postWithApiKeyRes.status).toBe(200);
+    expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+  });
+});

integration/tests/api-keys/protect.test.ts

@@ -0,0 +1,117 @@
+import type { User } from '@clerk/backend';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('auth.protect() with API keys @nextjs', () => {
+  test.describe.configure({ mode: 'parallel' });
+  let app: Application;
+  let fakeUser: FakeUser;
+  let fakeBapiUser: User;
+  let fakeAPIKey: FakeAPIKey;
+
+  test.beforeAll(async () => {
+    app = await appConfigs.next.appRouter
+      .clone()
+      .addFile(
+        'src/app/api/machine/route.ts',
+        () => `
+        import { NextResponse } from 'next/server';
+        import { auth } from '@clerk/nextjs/server';
+
+        export async function GET() {
+          const { userId } = await auth.protect({ token: 'api_key' });
+          return NextResponse.json({ userId });
+        }
+
+        export async function POST() {
+          const { userId } = await auth.protect({ token: ['api_key', 'session_token'] });
+          return NextResponse.json({ userId });
+        }
+        `,
+      )
+      .commit();
+
+    await app.setup();
+    await app.withEnv(appConfigs.envs.withAPIKeys);
+    await app.dev();
+
+    const u = createTestUtils({ app });
+    fakeUser = u.services.users.createFakeUser();
+    fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+    fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+  });
+
+  test.afterAll(async () => {
+    await fakeAPIKey.revoke();
+    await fakeUser.deleteIfExists();
+    await app.teardown();
+  });
+
+  test('should validate API key', async () => {
+    const url = new URL('/api/machine', app.serverUrl);
+
+    // No API key provided
+    const noKeyRes = await fetch(url);
+    if (noKeyRes.status !== 401) {
+      console.log('Unexpected status for "noKeyRes". Status:', noKeyRes.status, noKeyRes.statusText);
+      const body = await noKeyRes.text();
+      console.log(`error body ${body} error body`);
+    }
+    expect(noKeyRes.status).toBe(401);
+
+    // Invalid API key
+    const invalidKeyRes = await fetch(url, {
+      headers: {
+        Authorization: 'Bearer invalid_key',
+      },
+    });
+    expect(invalidKeyRes.status).toBe(401);
+
+    // Valid API key
+    const validKeyRes = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${fakeAPIKey.secret}`,
+      },
+    });
+    const apiKeyData = await validKeyRes.json();
+    expect(validKeyRes.status).toBe(200);
+    expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+  });
+
+  test('should handle multiple token types', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    const url = new URL('/api/machine', app.serverUrl);
+
+    // Sign in to get a session token
+    await u.po.signIn.goTo();
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+    await u.po.expect.toBeSignedIn();
+
+    // GET endpoint (only accepts api_key)
+    const getRes = await u.page.request.get(url.toString());
+    expect(getRes.status()).toBe(401);
+
+    // POST endpoint (accepts both api_key and session_token)
+    // Test with session token
+    const postWithSessionRes = await u.page.request.post(url.toString());
+    const sessionData = await postWithSessionRes.json();
+    expect(postWithSessionRes.status()).toBe(200);
+    expect(sessionData.userId).toBe(fakeBapiUser.id);
+
+    // Test with API key
+    const postWithApiKeyRes = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${fakeAPIKey.secret}`,
+      },
+    });
+    const apiKeyData = await postWithApiKeyRes.json();
+    expect(postWithApiKeyRes.status).toBe(200);
+    expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+  });
+});

package.json

@@ -48,6 +48,7 @@
     "test:integration:tanstack-react-router": "E2E_APP_ID=tanstack.react-router pnpm test:integration:base --grep @tanstack-react-router",
     "test:integration:tanstack-react-start": "E2E_APP_ID=tanstack.react-start pnpm test:integration:base --grep @tanstack-react-start",
     "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
+    "test:integration:xnextjs": "E2E_APP_ID=next.appRouter.* pnpm test:integration:base --grep @xnextjs",
     "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
     "turbo:clean": "turbo daemon clean",
     "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",