feat(backend): Update authenticateRequest handler to support multi-domain handshake

Author: brkalow

packages/backend/src/tokens/authStatus.ts

@@ -29,7 +29,7 @@ export type SignedInState = {
   isInterstitial: false;
   isUnknown: false;
   toAuth: () => SignedInAuthObject;
-  headers: Headers | null;
+  headers: Headers;
 };
 
 export type SignedOutState = {
@@ -48,7 +48,7 @@ export type SignedOutState = {
   isInterstitial: false;
   isUnknown: false;
   toAuth: () => SignedOutAuthObject;
-  headers: Headers | null;
+  headers: Headers;
 };
 
 export type InterstitialState = Omit<SignedOutState, 'isInterstitial' | 'status' | 'toAuth'> & {
@@ -136,7 +136,7 @@ export type AuthStatusOptionsType = LoadResourcesOptions &
 export async function signedIn<T extends AuthStatusOptionsType>(
   options: T,
   sessionClaims: JwtPayload,
-  headers: Headers | null = null,
+  headers: Headers = new Headers(),
 ): Promise<SignedInState> {
   const {
     publishableKey = '',
@@ -212,7 +212,7 @@ export function signedOut<T extends AuthStatusOptionsType>(
   options: T,
   reason: AuthReason,
   message = '',
-  headers: Headers | null = null,
+  headers: Headers = new Headers(),
 ): SignedOutState {
   const {
     publishableKey = '',

packages/backend/src/tokens/request.ts

@@ -3,7 +3,8 @@ import { parsePublishableKey } from '@clerk/shared/keys';
 import { constants } from '../constants';
 import { assertValidSecretKey } from '../util/assertValidSecretKey';
 import { buildRequest, stripAuthorizationHeader } from '../util/IsomorphicRequest';
-import { isDevelopmentFromSecretKey } from '../util/shared';
+import { addClerkPrefix, isDevelopmentFromSecretKey, isDevOrStagingUrl } from '../util/shared';
+import { buildRequestUrl } from '../utils';
 import type { AuthStatusOptionsType, RequestState } from './authStatus';
 import { AuthErrorReason, handshake, interstitial, signedIn, signedOut, unknownState } from './authStatus';
 import type { TokenCarrier } from './errors';
@@ -81,14 +82,21 @@ export async function authenticateRequest(options: AuthenticateRequestOptions):
       publishableKey,
       devBrowserToken,
       redirectUrl,
+      domain,
+      proxyUrl,
     }: {
       publishableKey: string;
       devBrowserToken: string;
       redirectUrl: string;
+      domain?: string;
+      proxyUrl?: string;
     }): string {
       const pk = parsePublishableKey(publishableKey);
+      const pkFapi = pk?.frontendApi || '';
+      // determine proper FAPI url, taking into account multi-domain setups
+      const frontendApi = proxyUrl || (!isDevOrStagingUrl(pkFapi) ? addClerkPrefix(domain) : '') || pkFapi;
 
-      const url = new URL(`https://${pk?.frontendApi}/v1/client/handshake`);
+      const url = new URL(`https://${frontendApi}/v1/client/handshake`);
       url.searchParams.append('redirect_url', redirectUrl);
 
       if (pk?.instanceType === 'development' && devBrowserToken) {
@@ -135,6 +143,14 @@ export async function authenticateRequest(options: AuthenticateRequestOptions):
         }
       });
 
+      if (parsePublishableKey(options.publishableKey)?.instanceType === 'development') {
+        const newUrl = new URL(options.request.url);
+        newUrl.searchParams.delete('__clerk_handshake');
+        newUrl.searchParams.delete('__clerk_help');
+
+        headers.append('Location', newUrl.toString());
+      }
+
       if (sessionToken === '') {
         return signedOut(ruleOptions, AuthErrorReason.SessionTokenMissing, '', headers);
       }
@@ -150,6 +166,24 @@ export async function authenticateRequest(options: AuthenticateRequestOptions):
     }
 
     // ================ This is to start the handshake if necessary ===================
+    if (ruleOptions.isSatellite && !new URL(options.request.url).searchParams.has('__clerk_synced')) {
+      const redirectUrl = buildRequestUrl(options.request);
+      const headers = new Headers();
+      headers.set(
+        'Location',
+        buildRedirectToHandshake({
+          publishableKey: ruleOptions.publishableKey!,
+          devBrowserToken: ruleOptions.devBrowserToken!,
+          redirectUrl: redirectUrl.toString(),
+          proxyUrl: ruleOptions.proxyUrl,
+          domain: ruleOptions.domain,
+        }),
+      );
+
+      // TODO: Add status code for redirection
+      return handshake(ruleOptions, AuthErrorReason.SatelliteCookieNeedsSyncing, '', headers);
+    }
+
     if (!hasActiveClient && !hasSessionToken) {
       return signedOut(ruleOptions, AuthErrorReason.CookieAndUATMissing);
     }

packages/clerk-js/src/core/devBrowserHandler.ts

@@ -14,7 +14,7 @@ export interface DevBrowserHandler {
 
   setup(): Promise<void>;
 
-  getDevBrowserJWT(): string | null;
+  getDevBrowserJWT(): string | undefined;
 
   setDevBrowserJWT(jwt: string): void;
 
@@ -39,11 +39,10 @@ export function createDevBrowserHandler({
   let usesUrlBasedSessionSyncing = true;
 
   function getDevBrowserJWT() {
-    return localStorage.getItem(key);
+    return cookieHandler.getDevBrowserCookie();
   }
 
   function setDevBrowserJWT(jwt: string) {
-    localStorage.setItem(key, jwt);
     // Append dev browser JWT to cookies, because server-side redirects (e.g. middleware) has no access to local storage
     cookieHandler.setDevBrowserCookie(jwt);
   }
@@ -116,7 +115,7 @@ export function createDevBrowserHandler({
     }
 
     // 2. If no JWT is found in the first step, check if a JWT is already available in the local cache
-    if (getDevBrowserJWT() !== null) {
+    if (getDevBrowserJWT()) {
       return;
     }
 

packages/nextjs/src/server/authMiddleware.ts

@@ -1,5 +1,5 @@
-import type { AuthObject, RequestState } from '@clerk/backend';
-import { buildRequestUrl, constants, TokenVerificationErrorReason } from '@clerk/backend';
+import type { AuthenticateRequestOptions, AuthObject } from '@clerk/backend';
+import { AuthStatus, buildRequestUrl, constants } from '@clerk/backend';
 import { DEV_BROWSER_JWT_MARKER, setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
 import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
 import { eventMethodCalled } from '@clerk/shared/telemetry';
@@ -10,15 +10,10 @@ import { NextResponse } from 'next/server';
 
 import { isRedirect, mergeResponses, paths, setHeader, stringifyHeaders } from '../utils';
 import { withLogger } from '../utils/debugLogger';
-import { authenticateRequest, handleInterstitialState, handleUnknownState } from './authenticateRequest';
+import { authenticateRequest } from './authenticateRequest';
 import { clerkClient } from './clerkClient';
 import { SECRET_KEY } from './constants';
-import {
-  clockSkewDetected,
-  infiniteRedirectLoopDetected,
-  informAboutProtectedRouteInfo,
-  receivedRequestForIgnoredRoute,
-} from './errors';
+import { informAboutProtectedRouteInfo, receivedRequestForIgnoredRoute } from './errors';
 import { redirectToSignIn } from './redirect';
 import type { NextMiddlewareResult, WithAuthOptions } from './types';
 import { isDevAccountPortalOrigin } from './url';
@@ -39,8 +34,6 @@ type RouteMatcherWithNextTypedRoutes = Autocomplete<
   WithPathPatternWildcard<ExcludeRootPath<NextTypedRoute>> | NextTypedRoute
 >;
 
-const INFINITE_REDIRECTION_LOOP_COOKIE = '__clerk_redirection_loop';
-
 /**
  * The default ideal matcher that excludes the _next directory (internals) and all static files,
  * but it will match the root route (/) and any routes that start with /api or /trpc.
@@ -191,22 +184,50 @@ const authMiddleware: AuthMiddleware = (...args: unknown[]) => {
       return setHeader(beforeAuthRes, constants.Headers.AuthReason, 'redirect');
     }
 
-    const requestState = await authenticateRequest(req, options);
-    if (requestState.isUnknown) {
-      logger.debug('authenticateRequest state is unknown', requestState);
-      return handleUnknownState(requestState);
-    } else if (requestState.isInterstitial && isApiRoute(req)) {
-      logger.debug('authenticateRequest state is interstitial in an API route', requestState);
-      return handleUnknownState(requestState);
-    } else if (requestState.isInterstitial) {
-      logger.debug('authenticateRequest state is interstitial', requestState);
+    const devBrowserToken =
+      req.nextUrl.searchParams.get('__clerk_db_jwt') || req.cookies.get('__clerk_db_jwt')?.value || '';
+    const handshakeToken =
+      req.nextUrl.searchParams.get('__clerk_handshake') || req.cookies.get('__clerk_handshake')?.value || '';
+
+    // TODO: fix type discrepancy between WithAuthOptions and AuthenticateRequestOptions
+    const requestState = await authenticateRequest(req, {
+      ...options,
+      devBrowserToken,
+      handshakeToken,
+    } as AuthenticateRequestOptions);
+    const requestStateHeaders = requestState.headers;
+
+    const locationHeader = requestStateHeaders?.get('location');
 
-      assertClockSkew(requestState, options);
+    // triggering a handshake redirect
+    if (locationHeader) {
+      return new Response(null, { status: 307, headers: requestStateHeaders });
+    }
 
-      const res = handleInterstitialState(requestState, options);
-      return assertInfiniteRedirectionLoop(req, res, options, requestState);
+    if (
+      requestState.status === AuthStatus.Handshake ||
+      requestState.status === AuthStatus.Unknown ||
+      requestState.status === AuthStatus.Interstitial
+    ) {
+      console.log(requestState);
+      throw new Error('Unexpected handshake or unknown state without redirect');
     }
 
+    // if (requestState.isUnknown) {
+    //   logger.debug('authenticateRequest state is unknown', requestState);
+    //   return handleUnknownState(requestState);
+    // } else if (requestState.isInterstitial && isApiRoute(req)) {
+    //   logger.debug('authenticateRequest state is interstitial in an API route', requestState);
+    //   return handleUnknownState(requestState);
+    // } else if (requestState.isInterstitial) {
+    //   logger.debug('authenticateRequest state is interstitial', requestState);
+
+    //   assertClockSkew(requestState, options);
+
+    //   const res = handleInterstitialState(requestState, options);
+    //   return assertInfiniteRedirectionLoop(req, res, options, requestState);
+    // }
+
     const auth = Object.assign(requestState.toAuth(), {
       isPublicRoute: isPublicRoute(req),
       isApiRoute: isApiRoute(req),
@@ -227,7 +248,15 @@ const authMiddleware: AuthMiddleware = (...args: unknown[]) => {
       logger.debug(`Added ${constants.Headers.EnableDebug} on request`);
     }
 
-    return decorateRequest(req, finalRes, requestState);
+    const result = decorateRequest(req, finalRes, requestState) || NextResponse.next();
+
+    if (requestStateHeaders) {
+      requestStateHeaders.forEach((value, key) => {
+        result.headers.append(key, value);
+      });
+    }
+
+    return result;
   });
 };
 
@@ -352,55 +381,6 @@ const isRequestMethodIndicatingApiRoute = (req: NextRequest): boolean => {
   return !['get', 'head', 'options'].includes(requestMethod);
 };
 
-/**
- * In development, attempt to detect clock skew based on the requestState. This check should run when requestState.isInterstitial is true. If detected, we throw an error.
- */
-const assertClockSkew = (requestState: RequestState, opts: AuthMiddlewareParams): void => {
-  if (!isDevelopmentFromSecretKey(opts.secretKey || SECRET_KEY)) {
-    return;
-  }
-
-  if (requestState.reason === TokenVerificationErrorReason.TokenNotActiveYet) {
-    throw new Error(clockSkewDetected(requestState.message));
-  }
-};
-
-// When in development, we want to prevent infinite interstitial redirection loops.
-// We incrementally set a `__clerk_redirection_loop` cookie, and when it loops 6 times, we throw an error.
-// We also utilize the `referer` header to skip the prefetch requests.
-const assertInfiniteRedirectionLoop = (
-  req: NextRequest,
-  res: NextResponse,
-  opts: AuthMiddlewareParams,
-  requestState: RequestState,
-): NextResponse => {
-  if (!isDevelopmentFromSecretKey(opts.secretKey || SECRET_KEY)) {
-    return res;
-  }
-
-  const infiniteRedirectsCounter = Number(req.cookies.get(INFINITE_REDIRECTION_LOOP_COOKIE)?.value) || 0;
-  if (infiniteRedirectsCounter === 6) {
-    // Infinite redirect detected, is it clock skew?
-    // We check for token-expired here because it can be a valid, recoverable scenario, but in a redirect loop a token-expired error likely indicates clock skew.
-    if (requestState.reason === TokenVerificationErrorReason.TokenExpired) {
-      throw new Error(clockSkewDetected(requestState.message));
-    }
-
-    // Not clock skew, return general error
-    throw new Error(infiniteRedirectLoopDetected());
-  }
-
-  // Skip the prefetch requests (when hovering a Next Link element)
-  if (req.headers.get('referer') === req.url) {
-    res.cookies.set({
-      name: INFINITE_REDIRECTION_LOOP_COOKIE,
-      value: `${infiniteRedirectsCounter + 1}`,
-      maxAge: 3,
-    });
-  }
-  return res;
-};
-
 const withNormalizedClerkUrl = (req: NextRequest): WithClerkUrl<NextRequest> => {
   const clerkUrl = req.nextUrl.clone();
 

packages/nextjs/src/server/authenticateRequest.ts

@@ -1,14 +1,14 @@
+import type { AuthenticateRequestOptions } from '@clerk/backend';
 import { constants, debugRequestState } from '@clerk/backend';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 
 import type { RequestState } from './clerkClient';
 import { clerkClient } from './clerkClient';
 import { CLERK_JS_URL, CLERK_JS_VERSION, PUBLISHABLE_KEY, SECRET_KEY } from './constants';
-import type { WithAuthOptions } from './types';
 import { apiEndpointUnauthorizedNextResponse, handleMultiDomainAndProxy } from './utils';
 
-export const authenticateRequest = async (req: NextRequest, opts: WithAuthOptions) => {
+export const authenticateRequest = async (req: NextRequest, opts: AuthenticateRequestOptions) => {
   const { isSatellite, domain, signInUrl, proxyUrl } = handleMultiDomainAndProxy(req, opts);
   return await clerkClient.authenticateRequest({
     ...opts,
@@ -34,7 +34,7 @@ export const handleUnknownState = (requestState: RequestState) => {
   return response;
 };
 
-export const handleInterstitialState = (requestState: RequestState, opts: WithAuthOptions) => {
+export const handleInterstitialState = (requestState: RequestState, opts: AuthenticateRequestOptions) => {
   const response = new NextResponse(
     clerkClient.localInterstitial({
       publishableKey: opts.publishableKey || PUBLISHABLE_KEY,

packages/nextjs/src/server/utils.ts

@@ -1,4 +1,4 @@
-import type { RequestState } from '@clerk/backend';
+import type { AuthenticateRequestOptions, RequestState } from '@clerk/backend';
 import { buildRequestUrl, constants } from '@clerk/backend';
 import { handleValueOrFn } from '@clerk/shared/handleValueOrFn';
 import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
@@ -9,7 +9,7 @@ import { NextResponse } from 'next/server';
 import { constants as nextConstants } from '../constants';
 import { DOMAIN, IS_SATELLITE, PROXY_URL, SECRET_KEY, SIGN_IN_URL } from './constants';
 import { missingDomainAndProxy, missingSignInUrlInDev } from './errors';
-import type { NextMiddlewareResult, RequestLike, WithAuthOptions } from './types';
+import type { NextMiddlewareResult, RequestLike } from './types';
 
 type AuthKey = 'AuthStatus' | 'AuthMessage' | 'AuthReason';
 
@@ -221,7 +221,7 @@ export const isCrossOrigin = (from: string | URL, to: string | URL) => {
   return fromUrl.origin !== toUrl.origin;
 };
 
-export const handleMultiDomainAndProxy = (req: NextRequest, opts: WithAuthOptions) => {
+export const handleMultiDomainAndProxy = (req: NextRequest, opts: AuthenticateRequestOptions) => {
   const requestURL = buildRequestUrl(req);
   const relativeOrAbsoluteProxyUrl = handleValueOrFn(opts?.proxyUrl, requestURL, PROXY_URL);
   let proxyUrl;

packages/shared/src/devBrowser.ts

@@ -1,4 +1,4 @@
-export const DEV_BROWSER_SSO_JWT_PARAMETER = '__dev_session';
+export const DEV_BROWSER_SSO_JWT_PARAMETER = '__clerk_db_jwt';
 export const DEV_BROWSER_JWT_MARKER = '__clerk_db_jwt';
 export const DEV_BROWSER_SSO_JWT_KEY = 'clerk-db-jwt';