test(hono): add e2e proxy tests and CI integration

Add hono to the CI integration test matrix. Add e2e tests that verify
proxy-enabled auth flows work correctly, including a test that proves
handshake redirects use forwarded headers instead of localhost.

Author: nikosdouvlis

.github/workflows/ci.yml

@@ -305,6 +305,7 @@ jobs:
             "nuxt",
             "react-router",
             "custom",
+            "hono",
           ]
         test-project: ["chrome"]
         include:

integration/presets/envs.ts

@@ -136,6 +136,11 @@ const withWaitlistMode = withEmailCodes
   .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-waitlist-mode').sk)
   .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-waitlist-mode').pk);
 
+const withEmailCodesProxy = withEmailCodes
+  .clone()
+  .setId('withEmailCodesProxy')
+  .setEnvVariable('private', 'CLERK_PROXY_ENABLED', 'true');
+
 const withSignInOrUpFlow = withEmailCodes
   .clone()
   .setId('withSignInOrUpFlow')
@@ -222,6 +227,7 @@ export const envs = {
   withDynamicKeys,
   withEmailCodes,
   withEmailCodes_destroy_client,
+  withEmailCodesProxy,
   withEmailCodesQuickstart,
   withEmailLinks,
   withKeyless,

integration/presets/longRunningApps.ts

@@ -86,6 +86,7 @@ export const createLongRunningApps = () => {
      * Hono apps
      */
     { id: 'hono.vite.withEmailCodes', config: hono.vite, env: envs.withEmailCodes },
+    { id: 'hono.vite.withEmailCodesProxy', config: hono.vite, env: envs.withEmailCodesProxy },
   ] as const;
 
   const apps = configs.map(longRunningApplication);

integration/templates/hono-vite/src/server/main.ts

@@ -8,10 +8,13 @@ import ViteExpress from 'vite-express';
 
 const app = new Hono();
 
+const proxyEnabled = process.env.CLERK_PROXY_ENABLED === 'true';
+
 app.use(
   '*',
   clerkMiddleware({
     publishableKey: process.env.VITE_CLERK_PUBLISHABLE_KEY,
+    ...(proxyEnabled ? { frontendApiProxy: { enabled: true } } : {}),
   }),
 );
 

integration/tests/hono/proxy.test.ts

@@ -0,0 +1,97 @@
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../../presets';
+import type { FakeUser } from '../../testUtils';
+import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodesProxy] })(
+  'frontend API proxy tests for @hono',
+  ({ app }) => {
+    test.describe.configure({ mode: 'parallel' });
+
+    let fakeUser: FakeUser;
+
+    test.beforeAll(async () => {
+      const u = createTestUtils({ app });
+      fakeUser = u.services.users.createFakeUser();
+      await u.services.users.createBapiUser(fakeUser);
+    });
+
+    test.afterAll(async () => {
+      await fakeUser.deleteIfExists();
+      await app.teardown();
+    });
+
+    test.skip('proxies Frontend API requests to /__clerk path', async ({ page, context }) => {
+      // TODO: clerkFrontendApiProxy sends Clerk-Proxy-Url with localhost origin
+      // because it uses requestUrl directly. FAPI rejects this with 400.
+      // Needs the same forwarded-header awareness in proxy.ts.
+      const u = createTestUtils({ app, page, context });
+      const url = new URL('/api/__clerk/v1/client?_is_native=false', app.serverUrl);
+      const res = await u.page.request.get(url.toString());
+
+      expect(res.status()).toBe(200);
+      const body = await res.json();
+      expect(body).toHaveProperty('response');
+    });
+
+    test('protected routes still require auth when proxy is enabled', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+      await u.page.goToRelative('/');
+      await u.po.signIn.waitForMounted();
+
+      const url = new URL('/api/protected', app.serverUrl);
+      const res = await u.page.request.get(url.toString());
+      expect(res.status()).toBe(401);
+      expect(await res.text()).toBe('Unauthorized');
+    });
+
+    test('authenticated requests work with proxy enabled', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+      await u.page.goToRelative('/');
+
+      await u.po.signIn.waitForMounted();
+      await u.po.signIn.setIdentifier(fakeUser.email);
+      await u.po.signIn.continue();
+      await u.po.signIn.setPassword(fakeUser.password);
+      await u.po.signIn.continue();
+
+      await u.po.userButton.waitForMounted();
+
+      const url = new URL('/api/protected', app.serverUrl);
+      const res = await u.page.request.get(url.toString());
+      expect(res.status()).toBe(200);
+      expect(await res.text()).toBe('Protected API response');
+    });
+
+    test('handshake redirect uses forwarded headers for proxyUrl, not localhost', async () => {
+      // This test proves that the SDK must derive proxyUrl from x-forwarded-* headers.
+      // When a reverse proxy sits in front of the app, the raw request URL is localhost,
+      // but the handshake redirect must point to the public origin.
+      //
+      // We simulate a behind-proxy scenario by sending x-forwarded-proto and x-forwarded-host
+      // headers, with a __client_uat cookie (non-zero) but no session cookie, which forces
+      // a handshake. The handshake redirect Location should use the forwarded origin.
+      const url = new URL('/api/protected', app.serverUrl);
+      const res = await fetch(url.toString(), {
+        headers: {
+          'x-forwarded-proto': 'https',
+          'x-forwarded-host': 'myapp.example.com',
+          'sec-fetch-dest': 'document',
+          Accept: 'text/html',
+          Cookie: '__clerk_db_jwt=needstobeset; __client_uat=1',
+        },
+        redirect: 'manual',
+      });
+
+      // The server should respond with a 307 handshake redirect
+      expect(res.status).toBe(307);
+      const location = res.headers.get('location') ?? '';
+      // The redirect must point to the public origin (from forwarded headers),
+      // NOT to http://localhost:PORT. If the SDK uses requestUrl.origin instead
+      // of forwarded headers, this assertion will fail.
+      expect(location).toContain('https://myapp.example.com');
+      expect(location).not.toContain('localhost');
+    });
+  },
+);