feat(*): add OAuth device verification flow

.changeset/quiet-devices-verify.md

@@ -0,0 +1,13 @@
+---
+'@clerk/astro': minor
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/nextjs': minor
+'@clerk/nuxt': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+'@clerk/vue': minor
+---
+
+Add an authenticated OAuth device verification component and workflow hook for approving or denying OAuth Device Authorization Grant requests.

packages/astro/src/astro-components/index.ts

@@ -29,5 +29,6 @@ export { default as CreateOrganization } from './interactive/CreateOrganization.
 export { default as GoogleOneTap } from './interactive/GoogleOneTap.astro';
 export { default as Waitlist } from './interactive/Waitlist.astro';
 export { default as OAuthConsent } from './interactive/OAuthConsent.astro';
+export { default as OAuthDeviceVerification } from './interactive/OAuthDeviceVerification.astro';
 export { default as PricingTable } from './interactive/PricingTable.astro';
 export { default as APIKeys } from './interactive/APIKeys.astro';

packages/astro/src/astro-components/interactive/OAuthDeviceVerification.astro

@@ -0,0 +1,11 @@
+---
+import type { OAuthDeviceVerificationProps } from '@clerk/shared/types';
+type Props = OAuthDeviceVerificationProps;
+
+import InternalUIComponentRenderer from './InternalUIComponentRenderer.astro';
+---
+
+<InternalUIComponentRenderer
+  {...Astro.props}
+  component='oauth-device-verification'
+/>

packages/astro/src/internal/mount-clerk-astro-js-components.ts

@@ -21,6 +21,7 @@ const mountAllClerkAstroJSComponents = () => {
     waitlist: 'mountWaitlist',
     'pricing-table': 'mountPricingTable',
     'api-keys': 'mountAPIKeys',
+    'oauth-device-verification': '__internal_mountOAuthDeviceVerification',
   } as const satisfies Record<InternalUIComponentId, keyof Clerk>;
 
   Object.entries(mountFns).forEach(([category, mountFn]) => {

packages/astro/src/react/__tests__/uiComponents.test.tsx

@@ -0,0 +1,48 @@
+import { render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { $clerk, $csrState } from '../../stores/internal';
+import { OAuthDeviceVerification } from '../uiComponents';
+
+describe('<OAuthDeviceVerification />', () => {
+  afterEach(() => {
+    $clerk.set(null);
+    $csrState.set({
+      isLoaded: false,
+      client: undefined,
+      user: undefined,
+      session: undefined,
+      organization: undefined,
+    });
+  });
+
+  it('updates the mounted component when its appearance changes', () => {
+    const mount = vi.fn();
+    const unmount = vi.fn();
+    const updateProps = vi.fn();
+    $clerk.set({
+      __internal_mountOAuthDeviceVerification: mount,
+      __internal_unmountOAuthDeviceVerification: unmount,
+      __internal_updateProps: updateProps,
+    } as any);
+    $csrState.set({
+      isLoaded: true,
+      client: undefined,
+      user: undefined,
+      session: undefined,
+      organization: undefined,
+    });
+    const firstAppearance = {};
+    const secondAppearance = {};
+    const { rerender } = render(<OAuthDeviceVerification appearance={firstAppearance} />);
+
+    rerender(<OAuthDeviceVerification appearance={secondAppearance} />);
+
+    expect(mount).toHaveBeenCalledOnce();
+    expect(updateProps).toHaveBeenCalledOnce();
+    expect(updateProps).toHaveBeenCalledWith({
+      node: expect.any(HTMLDivElement),
+      props: { appearance: secondAppearance },
+    });
+  });
+});

packages/astro/src/react/uiComponents.tsx

@@ -1,6 +1,7 @@
 import type {
   GoogleOneTapProps,
   OAuthConsentProps,
+  OAuthDeviceVerificationProps,
   OrganizationListProps,
   OrganizationProfileProps,
   OrganizationSwitcherProps,
@@ -207,3 +208,14 @@ export const OAuthConsent = withClerk(({ clerk, ...props }: WithClerkProp<OAuthC
     />
   );
 }, 'OAuthConsent');
+
+export const OAuthDeviceVerification = withClerk(({ clerk, ...props }: WithClerkProp<OAuthDeviceVerificationProps>) => {
+  return (
+    <Portal
+      mount={clerk?.__internal_mountOAuthDeviceVerification}
+      unmount={clerk?.__internal_unmountOAuthDeviceVerification}
+      updateProps={(clerk as any)?.__internal_updateProps}
+      props={props}
+    />
+  );
+}, 'OAuthDeviceVerification');

packages/astro/src/types.ts

@@ -119,4 +119,5 @@ export type InternalUIComponentId =
   | 'google-one-tap'
   | 'waitlist'
   | 'pricing-table'
-  | 'api-keys';
+  | 'api-keys'
+  | 'oauth-device-verification';

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

@@ -99,6 +99,7 @@ import type {
   LoadedClerk,
   NavigateOptions,
   OAuthApplicationNamespace,
+  OAuthDeviceVerificationProps,
   OAuthTransport,
   OrganizationListProps,
   OrganizationProfileProps,
@@ -1545,6 +1546,36 @@ export class Clerk implements ClerkInterface {
     return this.unmountOAuthConsent(node);
   };
 
+  public __internal_mountOAuthDeviceVerification = (node: HTMLDivElement, props?: OAuthDeviceVerificationProps) => {
+    if (noUserExists(this)) {
+      if (this.#instanceType === 'development') {
+        throw new ClerkRuntimeError(warnings.cannotRenderOAuthDeviceVerificationComponentWhenUserDoesNotExist, {
+          code: CANNOT_RENDER_USER_MISSING_ERROR_CODE,
+        });
+      }
+      return;
+    }
+
+    this.assertComponentsReady(this.#clerkUI);
+    const component = 'OAuthDeviceVerification';
+    void this.#clerkUI
+      .then(ui => ui.ensureMounted({ preloadHint: component }))
+      .then(controls =>
+        controls.mountComponent({
+          name: component,
+          appearanceKey: 'oauthDeviceVerification',
+          node,
+          props,
+        }),
+      );
+
+    this.telemetry?.record(eventPrebuiltComponentMounted(component, props));
+  };
+
+  public __internal_unmountOAuthDeviceVerification = (node: HTMLDivElement) => {
+    void this.#clerkUI?.then(ui => ui.ensureMounted()).then(controls => controls.unmountComponent({ node }));
+  };
+
   /**
    * Mount an API keys component at the target element.
    * @param targetNode Target to mount the APIKeys component.

packages/clerk-js/src/core/modules/oauthApplication/__tests__/OAuthApplication.test.ts

@@ -1,5 +1,10 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
-import type { InstanceType, OAuthConsentInfoJSON } from '@clerk/shared/types';
+import type {
+  InstanceType,
+  OAuthConsentInfoJSON,
+  OAuthDeviceVerificationInfoJSON,
+  OAuthDeviceVerificationResultJSON,
+} from '@clerk/shared/types';
 import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { mockFetch } from '@/test/core-fixtures';
@@ -20,6 +25,34 @@ const consentPayload: OAuthConsentInfoJSON = {
   scopes: [{ scope: 'openid', description: 'OpenID', requires_consent: true }],
 };
 
+const deviceVerificationPayload: OAuthDeviceVerificationInfoJSON = {
+  oauth_application_name: 'TV App',
+  oauth_application_logo_url: null,
+  client_id: 'client_device',
+  scopes: [{ scope: 'profile', description: 'Your profile', requires_consent: true }],
+  status: 'pending',
+  expires_at: 1_800_000_000_000,
+};
+
+const deviceVerificationResultPayload: OAuthDeviceVerificationResultJSON = {
+  object: 'oauth_device_verification',
+  status: 'approved',
+};
+
+function setFapiClerk() {
+  BaseResource.clerk = {
+    getFapiClient: () =>
+      createFapiClient({
+        frontendApi: 'clerk.example.com',
+        getSessionId: () => undefined,
+        instanceType: 'development' as InstanceType,
+      }),
+    __internal_setCountry: vi.fn(),
+    handleUnauthenticated: vi.fn(),
+    __internal_handleUnauthenticatedDevBrowser: vi.fn(),
+  } as any;
+}
+
 describe('OAuthApplication', () => {
   let oauthApp: OAuthApplication;
 
@@ -222,4 +255,150 @@ describe('OAuthApplication', () => {
       expect(result).toContain('__clerk_db_jwt=devjwt');
     });
   });
+
+  describe('lookupDeviceVerification', () => {
+    it.each([
+      ['direct', deviceVerificationPayload],
+      ['enveloped', { response: deviceVerificationPayload }],
+    ])('maps a %s FAPI response', async (_shape, response) => {
+      const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue(response as any);
+      BaseResource.clerk = {} as any;
+
+      await expect(oauthApp.lookupDeviceVerification({ userCode: 'bcdf ghjk' })).resolves.toEqual({
+        oauthApplicationName: 'TV App',
+        oauthApplicationLogoUrl: null,
+        clientId: 'client_device',
+        scopes: [{ scope: 'profile', description: 'Your profile', requiresConsent: true }],
+        status: 'pending',
+        expiresAt: 1_800_000_000_000,
+      });
+      expect(fetchSpy).toHaveBeenCalledWith(
+        {
+          method: 'POST',
+          path: '/me/oauth/device/lookup',
+          body: { userCode: 'bcdf ghjk' },
+        },
+        { skipUpdateClient: true },
+      );
+    });
+
+    it('defaults missing scopes to an empty array', async () => {
+      vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+        response: { ...deviceVerificationPayload, scopes: undefined },
+      } as any);
+      BaseResource.clerk = {} as any;
+
+      await expect(oauthApp.lookupDeviceVerification({ userCode: 'BCDF-GHJK' })).resolves.toMatchObject({ scopes: [] });
+    });
+
+    it.each(['pending', 'approved', 'denied', 'consumed'] as const)('preserves the %s lookup status', async status => {
+      vi.spyOn(BaseResource, '_fetch').mockResolvedValue({
+        response: { ...deviceVerificationPayload, status },
+      } as any);
+      BaseResource.clerk = {} as any;
+
+      await expect(oauthApp.lookupDeviceVerification({ userCode: 'BCDF-GHJK' })).resolves.toMatchObject({ status });
+    });
+
+    it('sends one credentialed form request with a snake-case user code field', async () => {
+      mockFetch(true, 200, deviceVerificationPayload);
+      setFapiClerk();
+
+      await oauthApp.lookupDeviceVerification({ userCode: 'BCDF-GHJK' });
+
+      expect(global.fetch).toHaveBeenCalledOnce();
+      const [url, init] = (global.fetch as Mock).mock.calls[0];
+      expect(url.toString()).toContain('/v1/me/oauth/device/lookup');
+      expect(init).toMatchObject({ credentials: 'include', method: 'POST', body: 'user_code=BCDF-GHJK' });
+    });
+
+    it('throws a network error when _fetch returns null', async () => {
+      vi.spyOn(BaseResource, '_fetch').mockResolvedValue(null);
+      BaseResource.clerk = {} as any;
+
+      await expect(oauthApp.lookupDeviceVerification({ userCode: 'BCDF-GHJK' })).rejects.toMatchObject({
+        code: 'network_error',
+      });
+    });
+
+    it('propagates FAPI errors without retrying', async () => {
+      const error = new ClerkAPIResponseError('Unknown device code', {
+        data: [{ code: 'resource_not_found', message: 'Unknown device code' }],
+        status: 404,
+      });
+      const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockRejectedValue(error);
+      BaseResource.clerk = {} as any;
+
+      await expect(oauthApp.lookupDeviceVerification({ userCode: 'BCDF-GHJK' })).rejects.toBe(error);
+      expect(fetchSpy).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('submitDeviceVerification', () => {
+    it.each([
+      ['direct', deviceVerificationResultPayload],
+      ['enveloped', { response: deviceVerificationResultPayload }],
+    ])('posts a decision and maps a %s FAPI response', async (_shape, response) => {
+      const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue(response as any);
+      BaseResource.clerk = {} as any;
+
+      await expect(
+        oauthApp.submitDeviceVerification({
+          userCode: 'BCDF-GHJK',
+          approved: true,
+          organizationId: 'org_123',
+        }),
+      ).resolves.toEqual(deviceVerificationResultPayload);
+      expect(fetchSpy).toHaveBeenCalledWith(
+        {
+          method: 'POST',
+          path: '/me/oauth/device',
+          body: { userCode: 'BCDF-GHJK', approved: true, organizationId: 'org_123' },
+        },
+        { skipUpdateClient: true },
+      );
+    });
+
+    it('omits organizationId through the FAPI form encoder when undefined', async () => {
+      const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockResolvedValue(deviceVerificationResultPayload as any);
+      BaseResource.clerk = {} as any;
+
+      await oauthApp.submitDeviceVerification({ userCode: 'BCDF-GHJK', approved: false });
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: { userCode: 'BCDF-GHJK', approved: false, organizationId: undefined },
+        }),
+        { skipUpdateClient: true },
+      );
+    });
+
+    it('sends a snake-case decision form and omits an undefined organization', async () => {
+      mockFetch(true, 200, deviceVerificationResultPayload);
+      setFapiClerk();
+
+      await oauthApp.submitDeviceVerification({ userCode: 'BCDF-GHJK', approved: false });
+
+      expect(global.fetch).toHaveBeenCalledOnce();
+      const [url, init] = (global.fetch as Mock).mock.calls[0];
+      expect(url.toString()).toContain('/v1/me/oauth/device');
+      expect(init).toMatchObject({
+        credentials: 'include',
+        method: 'POST',
+        body: 'user_code=BCDF-GHJK&approved=false',
+      });
+    });
+
+    it('propagates decision errors without retrying', async () => {
+      const error = new ClerkAPIResponseError('No longer pending', {
+        data: [{ code: 'bad_request', message: 'No longer pending' }],
+        status: 400,
+      });
+      const fetchSpy = vi.spyOn(BaseResource, '_fetch').mockRejectedValue(error);
+      BaseResource.clerk = {} as any;
+
+      await expect(oauthApp.submitDeviceVerification({ userCode: 'BCDF-GHJK', approved: true })).rejects.toBe(error);
+      expect(fetchSpy).toHaveBeenCalledOnce();
+    });
+  });
 });