feat(nextjs): Clock skew error message

.changeset/green-mails-cover.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Improve error messaging when clock skew is detected.

packages/backend/src/tokens/errors.ts

@@ -31,6 +31,7 @@ export enum TokenVerificationErrorAction {
   EnsureClerkJWT = 'Make sure that this is a valid Clerk generate JWT.',
   SetClerkJWTKey = 'Set the CLERK_JWT_KEY environment variable.',
   SetClerkSecretKeyOrAPIKey = 'Set the CLERK_SECRET_KEY or CLERK_API_KEY environment variable.',
+  EnsureClockSync = 'Make sure your system clock is in sync (e.g. turn off and on automatic time synchronization).',
 }
 
 export class TokenVerificationError extends Error {

packages/backend/src/tokens/jwt/verifyJwt.ts

@@ -210,6 +210,7 @@ export async function verifyJwt(
     const early = notBeforeDate.getTime() > currentDate.getTime() + clockSkew;
     if (early) {
       throw new TokenVerificationError({
+        action: TokenVerificationErrorAction.EnsureClockSync,
         reason: TokenVerificationErrorReason.TokenNotActiveYet,
         message: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`,
       });

packages/nextjs/src/server/authMiddleware.ts

@@ -1,4 +1,4 @@
-import type { AuthObject } from '@clerk/backend';
+import type { AuthObject, RequestState } from '@clerk/backend';
 import { buildRequestUrl, constants } from '@clerk/backend';
 import type Link from 'next/link';
 import type { NextFetchEvent, NextMiddleware, NextRequest } from 'next/server';
@@ -9,7 +9,12 @@ import { withLogger } from '../utils/debugLogger';
 import { authenticateRequest, handleInterstitialState, handleUnknownState } from './authenticateRequest';
 import { SECRET_KEY } from './clerkClient';
 import { DEV_BROWSER_JWT_MARKER, setDevBrowserJWTInURL } from './devBrowser';
-import { infiniteRedirectLoopDetected, informAboutProtectedRouteInfo, receivedRequestForIgnoredRoute } from './errors';
+import {
+  clockSkewDetected,
+  infiniteRedirectLoopDetected,
+  informAboutProtectedRouteInfo,
+  receivedRequestForIgnoredRoute,
+} from './errors';
 import { redirectToSignIn } from './redirect';
 import type { NextMiddlewareResult, WithAuthOptions } from './types';
 import { isDevAccountPortalOrigin } from './url';
@@ -187,8 +192,11 @@ const authMiddleware: AuthMiddleware = (...args: unknown[]) => {
       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);
+      return assertInfiniteRedirectionLoop(req, res, options, requestState);
     }
 
     const auth = Object.assign(requestState.toAuth(), {
@@ -334,20 +342,41 @@ 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 (!isDevelopmentFromApiKey(opts.secretKey || SECRET_KEY)) {
+    return;
+  }
+
+  if (requestState.reason === 'token-not-active-yet') {
+    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 (!isDevelopmentFromApiKey(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 === 'token-expired') {
+      throw new Error(clockSkewDetected(requestState.message));
+    }
+
+    // Not clock skew, return general error
     throw new Error(infiniteRedirectLoopDetected());
   }
 

packages/nextjs/src/server/errors.ts

@@ -34,20 +34,24 @@ export const getAuthAuthHeaderMissing = () =>
 export const authAuthHeaderMissing = () =>
   "Clerk: auth() was called but it looks like you aren't using `authMiddleware` in your middleware file. Please use `authMiddleware` and make sure your middleware matcher is configured correctly and it matches this route or page. See https://clerk.com/docs/quickstarts/get-started-with-nextjs";
 
+export const clockSkewDetected = (verifyMessage: string) =>
+  `Clerk: Clock skew detected. This usually means that your system clock is inaccurate. Clerk will continuously try to issue new tokens, as the existing ones will be treated as "expired" due to clock skew.
+
+To resolve this issue, make sure your system's clock is set to the correct time (e.g. turn off and on automatic time synchronization).
+
+---
+
+${verifyMessage}`;
+
 export const infiniteRedirectLoopDetected = () =>
   `Clerk: Infinite redirect loop detected. That usually means that we were not able to determine the auth state for this request. A list of common causes and solutions follows.
 
 Reason 1:
-Your server's system clock is inaccurate. Clerk will continuously try to issue new tokens, as the existing ones will be treated as "expired" due to clock skew.
-How to resolve:
--> Make sure your system's clock is set to the correct time (e.g. turn off and on automatic time synchronization).
-
-Reason 2:
 Your Clerk instance keys are incorrect, or you recently changed keys (Publishable Key, Secret Key).
 How to resolve:
 -> Make sure you're using the correct keys from the Clerk Dashboard. If you changed keys recently, make sure to clear your browser application data and cookies.
 
-Reason 3:
+Reason 2:
 A bug that may have already been fixed in the latest version of Clerk NextJS package.
 How to resolve:
 -> Make sure you are using the latest version of '@clerk/nextjs' and 'next'.