feat(backend): Add support for JWTs in OAuth token type

.changeset/swift-sheep-notice.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Added support for JWTs in oauth token type

packages/backend/src/api/resources/IdPOAuthAccessToken.ts

@@ -1,5 +1,14 @@
+import type { JwtPayload } from '@clerk/types';
+
 import type { IdPOAuthAccessTokenJSON } from './JSON';
 
+type OAuthJwtPayload = JwtPayload & {
+  jti?: string;
+  client_id?: string;
+  scope?: string;
+  scp?: string[];
+};
+
 export class IdPOAuthAccessToken {
   constructor(
     readonly id: string,
@@ -30,4 +39,27 @@ export class IdPOAuthAccessToken {
       data.updated_at,
     );
   }
+
+  /**
+   * Creates an IdPOAuthAccessToken from a JWT payload.
+   * Maps standard JWT claims and OAuth-specific fields to token properties.
+   */
+  static fromJwtPayload(payload: JwtPayload, clockSkewInMs = 5000): IdPOAuthAccessToken {
+    const oauthPayload = payload as OAuthJwtPayload;
+
+    // Map JWT claims to IdPOAuthAccessToken fields
+    return new IdPOAuthAccessToken(
+      oauthPayload.jti ?? '',
+      oauthPayload.client_id ?? '',
+      'oauth_token',
+      payload.sub,
+      oauthPayload.scp ?? oauthPayload.scope?.split(' ') ?? [],
+      false,
+      null,
+      payload.exp * 1000 <= Date.now() - clockSkewInMs,
+      payload.exp,
+      payload.iat,
+      payload.iat,
+    );
+  }
 }

packages/backend/src/errors.ts

@@ -74,6 +74,7 @@ export const MachineTokenVerificationErrorCode = {
   TokenInvalid: 'token-invalid',
   InvalidSecretKey: 'secret-key-invalid',
   UnexpectedError: 'unexpected-error',
+  TokenVerificationFailed: 'token-verification-failed',
 } as const;
 
 export type MachineTokenVerificationErrorCode =
@@ -82,17 +83,29 @@ export type MachineTokenVerificationErrorCode =
 export class MachineTokenVerificationError extends Error {
   code: MachineTokenVerificationErrorCode;
   long_message?: string;
-  status: number;
+  status?: number;
+  action?: TokenVerificationErrorAction;
 
-  constructor({ message, code, status }: { message: string; code: MachineTokenVerificationErrorCode; status: number }) {
+  constructor({
+    message,
+    code,
+    status,
+    action,
+  }: {
+    message: string;
+    code: MachineTokenVerificationErrorCode;
+    status?: number;
+    action?: TokenVerificationErrorAction;
+  }) {
     super(message);
     Object.setPrototypeOf(this, MachineTokenVerificationError.prototype);
 
     this.code = code;
     this.status = status;
+    this.action = action;
   }
 
   public getFullMessage() {
-    return `${this.message} (code=${this.code}, status=${this.status})`;
+    return `${this.message} (code=${this.code}, status=${this.status || 'n/a'})`;
   }
 }

packages/backend/src/fixtures/index.ts

@@ -33,6 +33,37 @@ export const mockJwtPayload = {
   sub: 'user_2GIpXOEpVyJw51rkZn9Kmnc6Sxr',
 };
 
+export const mockOAuthAccessTokenJwtPayload = {
+  ...mockJwtPayload,
+  iss: 'https://clerk.oauth.example.test',
+  sub: 'user_2vYVtestTESTtestTESTtestTESTtest',
+  client_id: 'client_2VTWUzvGC5UhdJCNx6xG1D98edc',
+  scope: 'read:foo write:bar',
+  jti: 'oat_2VTWUzvGC5UhdJCNx6xG1D98edc',
+  exp: mockJwtPayload.iat + 300,
+  iat: mockJwtPayload.iat,
+  nbf: mockJwtPayload.iat - 10,
+};
+
+type CreateJwt = (opts?: { header?: any; payload?: any; signature?: string }) => string;
+export const createJwt: CreateJwt = ({ header, payload, signature = mockJwtSignature } = {}) => {
+  const encoder = new TextEncoder();
+
+  const stringifiedHeader = JSON.stringify({ ...mockJwtHeader, ...header });
+  const stringifiedPayload = JSON.stringify({ ...mockJwtPayload, ...payload });
+
+  return [
+    base64url.stringify(encoder.encode(stringifiedHeader), { pad: false }),
+    base64url.stringify(encoder.encode(stringifiedPayload), { pad: false }),
+    signature,
+  ].join('.');
+};
+
+export const mockOAuthAccessTokenJwt = createJwt({
+  header: { typ: 'at+jwt' },
+  payload: mockOAuthAccessTokenJwtPayload,
+});
+
 export const mockRsaJwkKid = 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD';
 
 export const mockRsaJwk = {
@@ -151,20 +182,6 @@ export const signedJwt =
 export const pkTest = 'pk_test_Y2xlcmsuaW5zcGlyZWQucHVtYS03NC5sY2wuZGV2JA';
 export const pkLive = 'pk_live_Y2xlcmsuaW5zcGlyZWQucHVtYS03NC5sY2wuZGV2JA';
 
-type CreateJwt = (opts?: { header?: any; payload?: any; signature?: string }) => string;
-export const createJwt: CreateJwt = ({ header, payload, signature = mockJwtSignature } = {}) => {
-  const encoder = new TextEncoder();
-
-  const stringifiedHeader = JSON.stringify({ ...mockJwtHeader, ...header });
-  const stringifiedPayload = JSON.stringify({ ...mockJwtPayload, ...payload });
-
-  return [
-    base64url.stringify(encoder.encode(stringifiedHeader), { pad: false }),
-    base64url.stringify(encoder.encode(stringifiedPayload), { pad: false }),
-    signature,
-  ].join('.');
-};
-
 export function createCookieHeader(cookies: Record<string, string>): string {
   return Object.keys(cookies)
     .reduce((result: string[], cookieName: string) => {

packages/backend/src/jwt/assertions.ts

@@ -47,16 +47,17 @@ export const assertAudienceClaim = (aud?: unknown, audience?: unknown) => {
   }
 };
 
-export const assertHeaderType = (typ?: unknown) => {
+export const assertHeaderType = (typ?: unknown, allowedTypes: string | string[] = 'JWT') => {
   if (typeof typ === 'undefined') {
     return;
   }
 
-  if (typ !== 'JWT') {
+  const allowed = Array.isArray(allowedTypes) ? allowedTypes : [allowedTypes];
+  if (!allowed.includes(typ as string)) {
     throw new TokenVerificationError({
       action: TokenVerificationErrorAction.EnsureClerkJWT,
       reason: TokenVerificationErrorReason.TokenInvalid,
-      message: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`,
+      message: `Invalid JWT type ${JSON.stringify(typ)}. Expected "${allowed.join(', ')}".`,
     });
   }
 };

packages/backend/src/jwt/verifyJwt.ts

@@ -119,13 +119,18 @@ export type VerifyJwtOptions = {
    * @internal
    */
   key: JsonWebKey | string;
+  /**
+   * A string or list of allowed [header types](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.9).
+   * @default 'JWT'
+   */
+  headerType?: string | string[];
 };
 
 export async function verifyJwt(
   token: string,
   options: VerifyJwtOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
-  const { audience, authorizedParties, clockSkewInMs, key } = options;
+  const { audience, authorizedParties, clockSkewInMs, key, headerType } = options;
   const clockSkew = clockSkewInMs || DEFAULT_CLOCK_SKEW_IN_MS;
 
   const { data: decoded, errors } = decodeJwt(token);
@@ -138,7 +143,7 @@ export async function verifyJwt(
     // Header verifications
     const { typ, alg } = header;
 
-    assertHeaderType(typ);
+    assertHeaderType(typ, headerType);
     assertHeaderAlgorithm(alg);
 
     // Payload verifications

packages/backend/src/tokens/__tests__/machine.test.ts

@@ -1,10 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
+import { createJwt, mockOAuthAccessTokenJwtPayload } from '../../fixtures';
 import {
   API_KEY_PREFIX,
   getMachineTokenType,
+  isJwtFormat,
   isMachineTokenByPrefix,
   isMachineTokenType,
+  isOAuthJwt,
   isTokenTypeAccepted,
   M2M_TOKEN_PREFIX,
   OAUTH_TOKEN_PREFIX,
@@ -91,3 +94,46 @@ describe('isMachineTokenType', () => {
     expect(isMachineTokenType('session_token')).toBe(false);
   });
 });
+
+describe('isJwtFormat', () => {
+  it('returns true for valid JWT format', () => {
+    expect(isJwtFormat('header.payload.signature')).toBe(true);
+    expect(isJwtFormat('a.b.c')).toBe(true);
+  });
+
+  it('returns false for invalid JWT format', () => {
+    expect(isJwtFormat('invalid')).toBe(false);
+    expect(isJwtFormat('invalid.jwt')).toBe(false);
+    expect(isJwtFormat('invalid.jwt.token.extra')).toBe(false);
+  });
+});
+
+describe('isOAuthJwt', () => {
+  it('returns true for JWT with typ "at+jwt"', () => {
+    const token = createJwt({
+      header: { typ: 'at+jwt', kid: 'ins_whatever' },
+      payload: mockOAuthAccessTokenJwtPayload,
+    });
+    expect(isOAuthJwt(token)).toBe(true);
+  });
+
+  it('returns true for JWT with typ "application/at+jwt"', () => {
+    const token = createJwt({
+      header: { typ: 'application/at+jwt', kid: 'ins_whatever' },
+      payload: mockOAuthAccessTokenJwtPayload,
+    });
+    expect(isOAuthJwt(token)).toBe(true);
+  });
+
+  it('returns false for JWT with other typ', () => {
+    const token = createJwt({
+      header: { typ: 'JWT', kid: 'ins_whatever' },
+      payload: mockOAuthAccessTokenJwtPayload,
+    });
+    expect(isOAuthJwt(token)).toBe(false);
+  });
+
+  it('returns false for non-JWT token', () => {
+    expect(isOAuthJwt('not.a.jwt')).toBe(false);
+  });
+});