fix(nextjs,backend): Replace error with errors for jwt / token helpers return value

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;

.changeset/unlucky-frogs-tap.md

@@ -0,0 +1,41 @@
+---
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Replace return the value of the following jwt helpers to match the format of backend API client return values (for consistency).
+
+```diff
+import { signJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await signJwt(...);
++ const { data, errors: [error] = [] } = await signJwt(...);
+```
+
+```diff
+import { verifyJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await verifyJwt(...);
++ const { data, errors: [error] = [] } = await verifyJwt(...);
+```
+
+```diff
+import { hasValidSignature } from '@clerk/backend/jwt';
+
+- const { data, error } = await hasValidSignature(...);
++ const { data, errors: [error] = [] } = await hasValidSignature(...);
+```
+
+```diff
+import { decodeJwt } from '@clerk/backend/jwt';
+
+- const { data, error } = await decodeJwt(...);
++ const { data, errors: [error] = [] } = await decodeJwt(...);
+```
+
+```diff
+import { verifyToken } from '@clerk/backend';
+
+- const { data, error } = await verifyToken(...);
++ const { data, errors: [error] = [] } = await verifyToken(...);
+```

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -56,27 +56,27 @@ export default (QUnit: QUnit) => {
  });
 
  test('returns an error if null is given as jwt', assert => {
- const { error } = decodeJwt('null');
+ const { errors: [error] = [] } = decodeJwt('null');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if undefined is given as jwt', assert => {
- const { error } = decodeJwt('undefined');
+ const { errors: [error] = [] } = decodeJwt('undefined');
  assert.propContains(error, invalidTokenError);
  });
 
  test('returns an error if empty string is given as jwt', assert => {
- const { error } = decodeJwt('');
+ const { errors: [error] = [] } = decodeJwt('');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if invalid string is given as jwt', assert => {
- const { error } = decodeJwt('whatever');
+ const { errors: [error] = [] } = decodeJwt('whatever');
  assert.propContains(error, invalidTokenError);
  });
 
  test('throws an error if number is given as jwt', assert => {
- const { error } = decodeJwt('42');
+ const { errors: [error] = [] } = decodeJwt('42');
  assert.propContains(error, invalidTokenError);
  });
  });
@@ -127,7 +127,7 @@ export default (QUnit: QUnit) => {
  issuer: mockJwtPayload.iss,
  authorizedParties: ['', 'https://accounts.inspired.puma-74.lcl.dev'],
  };
- const { error } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
+ const { errors: [error] = [] } = await verifyJwt('invalid-jwt', inputVerifyJwtOptions);
  assert.propContains(error, invalidTokenError);
  });
  });

packages/backend/src/jwt/signJwt.ts

@@ -60,6 +60,6 @@ export async function signJwt(
  const encodedSignature = `${firstPart}.${base64url.stringify(new Uint8Array(signature), { pad: false })}`;
  return { data: encodedSignature };
  } catch (error) {
- return { error: new SignJWTError((error as Error)?.message) };
+ return { errors: [new SignJWTError((error as Error)?.message)] };
  }
 }

packages/backend/src/jwt/types.ts

@@ -1,9 +1,9 @@
 export type JwtReturnType<R, E extends Error> =
  | {
  data: R;
-error?: undefined;
+errors?: undefined;
  }
  | {
  data?: undefined;
-error: E;
+errors: [E];
  };

packages/backend/src/jwt/verifyJwt.ts

@@ -34,10 +34,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
  return { data: verified };
  } catch (error) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: (error as Error)?.message,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: (error as Error)?.message,
+ }),
+ ],
  };
  }
 }
@@ -46,10 +48,12 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
  const tokenParts = (token || '').toString().split('.');
  if (tokenParts.length !== 3) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalid,
- message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalid,
+ message: `Invalid JWT form. A JWT consists of three parts separated by dots.`,
+ }),
+ ],
  };
  }
 
@@ -105,9 +109,9 @@ export async function verifyJwt(
  const { audience, authorizedParties, clockSkewInMs, key } = options;
  const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- return { error };
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header, payload } = decoded;
@@ -128,26 +132,30 @@ export async function verifyJwt(
  assertActivationClaim(nbf, clockSkew);
  assertIssuedAtClaim(iat, clockSkew);
  } catch (err) {
- return { error: err as TokenVerificationError };
+ return { errors: [err as TokenVerificationError] };
  }
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.EnsureClerkJWT,
- reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying JWT signature. ${signatureError}`,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.EnsureClerkJWT,
+ reason: TokenVerificationErrorReason.TokenVerificationFailed,
+ message: `Error verifying JWT signature. ${signatureErrors[0]}`,
+ }),
+ ],
  };
  }
 
  if (!signatureValid) {
  return {
- error: new TokenVerificationError({
- reason: TokenVerificationErrorReason.TokenInvalidSignature,
- message: 'JWT signature is invalid.',
- }),
+ errors: [
+ new TokenVerificationError({
+ reason: TokenVerificationErrorReason.TokenInvalidSignature,
+ message: 'JWT signature is invalid.',
+ }),
+ ],
  };
  }
 

packages/backend/src/tokens/handshake.ts

@@ -6,9 +6,9 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 import type { VerifyTokenOptions } from './verify';
 
 async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Promise<{ handshake: string[] }> {
- const { data: decoded, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data: decoded, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { header, payload } = decoded;
@@ -19,11 +19,11 @@ async function verifyHandshakeJwt(token: string, { key }: VerifyJwtOptions): Pro
  assertHeaderType(typ);
  assertHeaderAlgorithm(alg);
 
- const { data: signatureValid, error: signatureError } = await hasValidSignature(decoded, key);
- if (signatureError) {
+ const { data: signatureValid, errors: signatureErrors } = await hasValidSignature(decoded, key);
+ if (signatureErrors) {
  throw new TokenVerificationError({
  reason: TokenVerificationErrorReason.TokenVerificationFailed,
- message: `Error verifying handshake token. ${signatureError}`,
+ message: `Error verifying handshake token. ${signatureErrors[0]}`,
  });
  }
 
@@ -46,9 +46,9 @@ export async function verifyHandshakeToken(
 ): Promise<{ handshake: string[] }> {
  const { secretKey, apiUrl, apiVersion, jwksCacheTtlInMs, jwtKey, skipJwksCache } = options;
 
- const { data, error } = decodeJwt(token);
- if (error) {
- throw error;
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
  }
 
  const { kid } = data.header;

packages/backend/src/tokens/request.ts

@@ -117,7 +117,7 @@ export async function authenticateRequest(
  return signedOut(authenticateContext, AuthErrorReason.SessionTokenMissing, '', headers);
  }
 
- const { data, error } = await verifyToken(sessionToken, authenticateContext);
+ const { data, errors: [error] = [] } = await verifyToken(sessionToken, authenticateContext);
  if (data) {
  return signedIn(authenticateContext, data, headers, sessionToken);
  }
@@ -140,7 +140,7 @@ ${error.getFullMessage()}`,
  );
 
  // Retry with a generous clock skew allowance (1 day)
- const { data: retryResult, error: retryError } = await verifyToken(sessionToken, {
+ const { data: retryResult, errors: [retryError] = [] } = await verifyToken(sessionToken, {
  ...authenticateContext,
  clockSkewInMs: 86_400_000,
  });
@@ -180,9 +180,9 @@ ${error.getFullMessage()}`,
  const { sessionTokenInHeader } = authenticateContext;
 
  try {
- const { data, error } = await verifyToken(sessionTokenInHeader!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(sessionTokenInHeader!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, sessionTokenInHeader!);
@@ -286,19 +286,19 @@ ${error.getFullMessage()}`,
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.ClientUATWithoutSessionToken, '');
  }
 
- const { data: decodeResult, error: decodedError } = decodeJwt(authenticateContext.sessionTokenInCookie!);
- if (decodedError) {
- return handleError(decodedError, 'cookie');
+ const { data: decodeResult, errors: decodedErrors } = decodeJwt(authenticateContext.sessionTokenInCookie!);
+ if (decodedErrors) {
+ return handleError(decodedErrors[0], 'cookie');
  }
 
  if (decodeResult.payload.iat < authenticateContext.clientUat) {
  return handleMaybeHandshakeStatus(authenticateContext, AuthErrorReason.SessionTokenOutdated, '');
  }
 
  try {
- const { data, error } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
- if (error) {
- throw error;
+ const { data, errors } = await verifyToken(authenticateContext.sessionTokenInCookie!, authenticateContext);
+ if (errors) {
+ throw errors[0];
  }
  // use `await` to force this try/catch handle the signedIn invocation
  return await signedIn(authenticateContext, data, undefined, authenticateContext.sessionTokenInCookie!);

packages/backend/src/tokens/verify.ts

@@ -14,9 +14,9 @@ export async function verifyToken(
  token: string,
  options: VerifyTokenOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
- const { data: decodedResult, error: decodedError } = decodeJwt(token);
- if (decodedError) {
- return { error: decodedError };
+ const { data: decodedResult, errors } = decodeJwt(token);
+ if (errors) {
+ return { errors };
  }
 
  const { header } = decodedResult;
@@ -32,16 +32,18 @@ export async function verifyToken(
  key = await loadClerkJWKFromRemote({ ...options, kid });
  } else {
  return {
- error: new TokenVerificationError({
- action: TokenVerificationErrorAction.SetClerkJWTKey,
- message: 'Failed to resolve JWK during verification.',
- reason: TokenVerificationErrorReason.JWKFailedToResolve,
- }),
+ errors: [
+ new TokenVerificationError({
+ action: TokenVerificationErrorAction.SetClerkJWTKey,
+ message: 'Failed to resolve JWK during verification.',
+ reason: TokenVerificationErrorReason.JWKFailedToResolve,
+ }),
+ ],
  };
  }
 
  return await verifyJwt(token, { ...options, key });
  } catch (error) {
- return { error: error as TokenVerificationError };
+ return { errors: [error as TokenVerificationError] };
  }
 }

packages/nextjs/src/server/createGetAuth.ts

@@ -46,9 +46,9 @@ export const createGetAuth = ({
  logger.debug('Options debug', options);
 
  if (authStatus === AuthStatus.SignedIn) {
- const { data: jwt, error } = decodeJwt(authToken as string);
- if (error) {
- throw error;
+ const { data: jwt, errors } = decodeJwt(authToken as string);
+ if (errors) {
+ throw errors[0];
  }
 
  logger.debug('JWT debug', jwt.raw.text);
@@ -68,10 +68,10 @@ export const getAuth = createGetAuth({
 export const parseJwt = (req: RequestLike) => {
  const cookieToken = getCookie(req, constants.Cookies.Session);
  const headerToken = getHeader(req, 'authorization')?.replace('Bearer ', '');
- const { data, error } = decodeJwt(cookieToken || headerToken || '');
+ const { data, errors } = decodeJwt(cookieToken || headerToken || '');
 
- if (error) {
- throw error;
+ if (errors) {
+ throw errors[0];
  }
 
  return data;