Merge pull request #562 from ForgeRock/qr-code

feat(davinci-client): add QRCode collector support

Author: ryanbas21

.changeset/fast-ways-rest.md

@@ -0,0 +1,5 @@
+---
+'@forgerock/davinci-client': minor
+---
+
+Add QR code collector support to davinci-client

.github/actions/setup/action.yml

@@ -31,7 +31,9 @@ runs:
         registry-url: 'https://registry.npmjs.org'
 
     - name: Update npm
-      run: npm install -g npm@latest
+      run: |
+        corepack enable
+        corepack install -g npm@latest
       shell: bash
 
     - name: Install dependencies

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
         with:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-      - run: npx nx-cloud fix-ci
+      - run: pnpm nx fix-ci
         if: always()
 
       - uses: codecov/codecov-action@v5

e2e/davinci-app/components/qr-code.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+import type { QrCodeCollector } from '@forgerock/davinci-client/types';
+
+export default function (formEl: HTMLFormElement, collector: QrCodeCollector) {
+  if (collector.error) {
+    const errorEl = document.createElement('p');
+    errorEl.innerText = `QR Code error: ${collector.error}`;
+    formEl.appendChild(errorEl);
+    return;
+  }
+
+  const container = document.createElement('div');
+
+  const img = document.createElement('img');
+  img.src = collector.output.src;
+  img.alt = 'QR Code';
+  img.setAttribute('data-testid', 'qr-code-image');
+  container.appendChild(img);
+
+  if (collector.output.label) {
+    const fallback = document.createElement('p');
+    fallback.innerText = `Manual code: ${collector.output.label}`;
+    fallback.setAttribute('data-testid', 'qr-code-fallback');
+    container.appendChild(fallback);
+  }
+
+  formEl.appendChild(container);
+}

e2e/davinci-app/main.ts

@@ -32,6 +32,7 @@ import multiValueComponent from './components/multi-value.js';
 import labelComponent from './components/label.js';
 import objectValueComponent from './components/object-value.js';
 import fidoComponent from './components/fido.js';
+import qrCodeComponent from './components/qr-code.js';
 
 const loggerFn = {
   error: () => {
@@ -223,6 +224,8 @@ const urlParams = new URLSearchParams(window.location.search);
           formEl, // You can ignore this; it's just for rendering
           collector, // This is the plain object of the collector
         );
+      } else if (collector.type === 'QrCodeCollector') {
+        qrCodeComponent(formEl, collector);
       } else if (collector.type === 'TextCollector') {
         textComponent(
           formEl, // You can ignore this; it's just for rendering

e2e/davinci-app/server-configs.ts

@@ -57,7 +57,6 @@ export const serverConfigs: Record<string, DaVinciConfig> = {
   },
   /**
    * Phone Number Input With Email and Password
-   *
    */
   '20dd0ed0-bb9b-4c8f-9a60-9ebeb4b348e0': {
     clientId: '20dd0ed0-bb9b-4c8f-9a60-9ebeb4b348e0',
@@ -68,4 +67,14 @@ export const serverConfigs: Record<string, DaVinciConfig> = {
         'https://auth.pingone.ca/02fb4743-189a-4bc7-9d6c-a919edfe6447/as/.well-known/openid-configuration',
     },
   },
+  /** QR Code policy id : aa3c00c3ec25a9721be078f7bf44678d **/
+  'c12743f9-08e8-4420-a624-71bbb08e9fe1': {
+    clientId: 'c12743f9-08e8-4420-a624-71bbb08e9fe1',
+    redirectUri: window.location.origin + '/',
+    scope: 'openid profile email',
+    serverConfig: {
+      wellknown:
+        'https://auth.pingone.ca/02fb4743-189a-4bc7-9d6c-a919edfe6447/as/.well-known/openid-configuration',
+    },
+  },
 };

e2e/davinci-suites/src/qr-code.test.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+import { expect, test } from '@playwright/test';
+import { asyncEvents } from './utils/async-events.js';
+import { password, username } from './utils/demo-user.js';
+
+const qrCodeUrl =
+  '/?clientId=c12743f9-08e8-4420-a624-71bbb08e9fe1&acr_values=9da1b93991bcd577947da228ad4c741f';
+
+test('QR code renders after navigating through device registration flow', async ({ page }) => {
+  const { navigate } = asyncEvents(page);
+
+  await navigate(qrCodeUrl);
+
+  // Step 1: Login
+  await page.getByRole('button', { name: 'USER_LOGIN' }).click();
+  await page.waitForEvent('requestfinished');
+
+  await page.getByLabel('Username').fill(username);
+  await page.getByLabel('Password').fill(password);
+  await page.getByRole('button', { name: 'Sign On' }).click();
+  await page.waitForEvent('requestfinished');
+
+  // Step 2: Select device registration
+  await page.getByRole('button', { name: 'DEVICE_REGISTRATION' }).click();
+  await page.waitForEvent('requestfinished');
+
+  // Step 3: Choose "Mobile App" from the device selection screen
+  await expect(page.getByText('MFA Device Selection - Registration')).toBeVisible();
+  await page.getByRole('button', { name: 'Mobile App' }).click();
+  await page.waitForEvent('requestfinished');
+
+  // Step 4: QR code should now be visible
+  const qrImage = page.locator('[data-testid="qr-code-image"]');
+  await expect(qrImage).toBeVisible({ timeout: 10000 });
+
+  // Verify the image has a base64-encoded src
+  const src = await qrImage.getAttribute('src');
+  expect(src).toBeTruthy();
+  expect(src).toContain('data:image/png;base64,');
+
+  // Verify fallback text is displayed if present
+  const fallback = page.locator('[data-testid="qr-code-fallback"]');
+  const fallbackVisible = await fallback.isVisible();
+  if (fallbackVisible) {
+    const fallbackText = await fallback.textContent();
+    expect(fallbackText).toBeTruthy();
+  }
+});

packages/davinci-client/src/lib/collector.types.ts

@@ -482,7 +482,7 @@ export type SubmitCollector = ActionCollectorNoUrl<'SubmitCollector'>;
 /**
  * @interface NoValueCollector - Represents a collector that collects no value; text only for display.
  */
-export type NoValueCollectorTypes = 'ReadOnlyCollector' | 'NoValueCollector';
+export type NoValueCollectorTypes = 'ReadOnlyCollector' | 'NoValueCollector' | 'QrCodeCollector';
 
 export interface NoValueCollectorBase<T extends NoValueCollectorTypes> {
   category: 'NoValueCollector';
@@ -497,6 +497,20 @@ export interface NoValueCollectorBase<T extends NoValueCollectorTypes> {
   };
 }
 
+export interface QrCodeCollectorBase {
+  category: 'NoValueCollector';
+  error: string | null;
+  type: 'QrCodeCollector';
+  id: string;
+  name: string;
+  output: {
+    key: string;
+    label: string;
+    type: string;
+    src: string;
+  };
+}
+
 /**
  * Type to help infer the collector based on the collector type
  * Used specifically in the returnNoValueCollector wrapper function.
@@ -507,16 +521,21 @@ export interface NoValueCollectorBase<T extends NoValueCollectorTypes> {
 export type InferNoValueCollectorType<T extends NoValueCollectorTypes> =
   T extends 'ReadOnlyCollector'
     ? NoValueCollectorBase<'ReadOnlyCollector'>
-    : NoValueCollectorBase<'NoValueCollector'>;
+    : T extends 'QrCodeCollector'
+      ? QrCodeCollectorBase
+      : NoValueCollectorBase<'NoValueCollector'>;
 
 export type NoValueCollectors =
   | NoValueCollectorBase<'NoValueCollector'>
-  | NoValueCollectorBase<'ReadOnlyCollector'>;
+  | NoValueCollectorBase<'ReadOnlyCollector'>
+  | QrCodeCollectorBase;
 
 export type NoValueCollector<T extends NoValueCollectorTypes> = NoValueCollectorBase<T>;
 
 export type ReadOnlyCollector = NoValueCollectorBase<'ReadOnlyCollector'>;
 
+export type QrCodeCollector = QrCodeCollectorBase;
+
 export type UnknownCollector = {
   category: 'UnknownCollector';
   error: string | null;

packages/davinci-client/src/lib/collector.utils.test.ts

@@ -22,6 +22,7 @@ import {
   returnObjectValueCollector,
   returnSingleValueAutoCollector,
   returnObjectValueAutoCollector,
+  returnQrCodeCollector,
 } from './collector.utils.js';
 import type {
   DaVinciField,
@@ -31,6 +32,7 @@ import type {
   FidoRegistrationField,
   PhoneNumberField,
   ProtectField,
+  QrCodeField,
   ReadOnlyField,
   RedirectField,
   StandardField,
@@ -809,6 +811,77 @@ describe('No Value Collectors', () => {
   });
 });
 
+describe('returnQrCodeCollector', () => {
+  it('should return a valid QrCodeCollector with src and label from fallbackText', () => {
+    const mockField: QrCodeField = {
+      type: 'QR_CODE',
+      key: 'qr-code-field',
+      content: 'data:image/png;base64,abc123',
+      fallbackText: '04ZKS2KCIWKXT8FHRX',
+    };
+    const result = returnQrCodeCollector(mockField, 2);
+    expect(result).toEqual({
+      category: 'NoValueCollector',
+      error: null,
+      type: 'QrCodeCollector',
+      id: 'qr-code-field-2',
+      name: 'qr-code-field-2',
+      output: {
+        key: 'qr-code-field-2',
+        label: '04ZKS2KCIWKXT8FHRX',
+        type: 'QR_CODE',
+        src: 'data:image/png;base64,abc123',
+      },
+    });
+  });
+
+  it('should handle missing fallbackText gracefully', () => {
+    const mockField: QrCodeField = {
+      type: 'QR_CODE',
+      key: 'qr-code-field',
+      content: 'data:image/png;base64,abc123',
+    };
+    const result = returnQrCodeCollector(mockField, 0);
+    expect(result).toEqual({
+      category: 'NoValueCollector',
+      error: null,
+      type: 'QrCodeCollector',
+      id: 'qr-code-field-0',
+      name: 'qr-code-field-0',
+      output: {
+        key: 'qr-code-field-0',
+        label: '',
+        type: 'QR_CODE',
+        src: 'data:image/png;base64,abc123',
+      },
+    });
+  });
+
+  it('should set error when content is missing', () => {
+    const mockField = { type: 'QR_CODE', key: 'qr-code-field' } as unknown as QrCodeField;
+    const result = returnQrCodeCollector(mockField, 0);
+    expect(result.error).toContain('Content is not found');
+    expect(result.output.src).toBe('');
+  });
+
+  it('should fall back to type for id/name when key is missing', () => {
+    const mockField = {
+      type: 'QR_CODE',
+      content: 'data:image/png;base64,abc123',
+    } as unknown as QrCodeField;
+    const result = returnQrCodeCollector(mockField, 0);
+    expect(result.error).toBeNull();
+    expect(result.id).toBe('QR_CODE-0');
+    expect(result.name).toBe('QR_CODE-0');
+  });
+
+  it('should only report content error when both key and content are missing', () => {
+    const mockField = { type: 'QR_CODE' } as unknown as QrCodeField;
+    const result = returnQrCodeCollector(mockField, 0);
+    expect(result.error).toContain('Content is not found');
+  });
+});
+
 describe('returnSingleValueAutoCollector', () => {
   it('should create a valid ProtectCollector', () => {
     const mockField: ProtectField = {

packages/davinci-client/src/lib/collector.utils.ts

@@ -29,6 +29,7 @@ import type {
   AutoCollectors,
   SingleValueAutoCollectorTypes,
   ObjectValueAutoCollectorTypes,
+  QrCodeCollectorBase,
 } from './collector.types.js';
 import type {
   DeviceAuthenticationField,
@@ -38,6 +39,7 @@ import type {
   MultiSelectField,
   PhoneNumberField,
   ProtectField,
+  QrCodeField,
   ReadOnlyField,
   RedirectField,
   SingleSelectField,
@@ -678,7 +680,7 @@ export function returnObjectValueCollector(
  * @returns {NoValueCollector} The constructed NoValueCollector object.
  */
 export function returnNoValueCollector<
-  Field extends ReadOnlyField,
+  Field extends ReadOnlyField | QrCodeField,
   CollectorType extends NoValueCollectorTypes = 'NoValueCollector',
 >(field: Field, idx: number, collectorType: CollectorType) {
   let error = '';
@@ -713,6 +715,25 @@ export function returnReadOnlyCollector(field: ReadOnlyField, idx: number) {
   return returnNoValueCollector(field, idx, 'ReadOnlyCollector');
 }
 
+/**
+ * @function returnQrCodeCollector - Creates a QrCodeCollector object for displaying QR code images.
+ * @param {QrCodeField} field - The field object containing key, content, type, and optional fallbackText.
+ * @param {number} idx - The index to be used in the id of the QrCodeCollector.
+ * @returns {QrCodeCollectorBase} The constructed QrCodeCollector object.
+ */
+export function returnQrCodeCollector(field: QrCodeField, idx: number): QrCodeCollectorBase {
+  const base = returnNoValueCollector(field, idx, 'QrCodeCollector');
+
+  return {
+    ...base,
+    output: {
+      ...base.output,
+      label: field.fallbackText || '',
+      src: field.content || '',
+    },
+  };
+}
+
 /**
  * @function returnValidator - Creates a validator function based on the provided collector
  * @param {ValidatedTextCollector | ObjectValueCollectors | MultiValueCollectors | AutoCollectors} collector - The collector to which the value will be validated