@smileid/usesmileid 12.0.1 → 12.0.2

package/src/presentation/flow/dsl/__tests__/use_smile_id_builder_component.test.tsx

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+
+// `vi.mock` is hoisted above the imports, so anything its factory closes over
+// must be created with `vi.hoisted` or it is still in the TDZ when the factory
+// runs.
+const { invalidProps, successProps } = vi.hoisted(() => ({
+  invalidProps: { current: undefined as Record<string, unknown> | undefined },
+  successProps: { current: undefined as Record<string, unknown> | undefined },
+}));
+
+// Stand in for the two flow renderers so these tests exercise the
+// build-and-dispatch decision the component owns, not the screen runtime
+// (which has its own suites).
+vi.mock("../../use_smile_id_flow", () => ({
+  FlowInvalidDispatcher: (props: Record<string, unknown>) => {
+    invalidProps.current = props;
+    return null;
+  },
+  FlowSuccessRenderer: (props: Record<string, unknown>) => {
+    successProps.current = props;
+    return null;
+  },
+}));
+
+import { UseSmileIDBuilder } from "../use_smile_id_builder";
+import type { UseSmileIDFlowBuilder } from "../use_smile_id_flow_builder";
+
+/**
+ * `<UseSmileIDBuilder>` runs the partner's closure exactly once per mount,
+ * builds the flow, and routes the outcome: a valid configuration renders the
+ * flow, an invalid one hands the partner's `onResult` and debug-mode flag to
+ * the invalid dispatcher. Re-running the closure on every render would
+ * restart a partner's flow mid-capture.
+ */
+
+function render(element: React.ReactElement) {
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(element);
+  });
+  return tree;
+}
+
+function validFlow(builder: UseSmileIDFlowBuilder): void {
+  builder.screens((screens) => {
+    screens.instructions();
+  });
+}
+
+describe("UseSmileIDBuilder", () => {
+  beforeEach(() => {
+    invalidProps.current = undefined;
+    successProps.current = undefined;
+  });
+
+  it("renders the flow when the configuration builds", () => {
+    render(<UseSmileIDBuilder builder={validFlow} />);
+
+    expect(invalidProps.current).toBeUndefined();
+    expect(successProps.current).toBeDefined();
+    const configuration = successProps.current?.configuration as {
+      screens: { steps: readonly unknown[] };
+    };
+    expect(configuration.screens.steps).toHaveLength(1);
+  });
+
+  it("routes an invalid configuration to the dispatcher with the partner callback", () => {
+    const onResult = vi.fn();
+    render(
+      <UseSmileIDBuilder
+        builder={(builder) => {
+          builder.onResult = onResult;
+        }}
+      />,
+    );
+
+    expect(successProps.current).toBeUndefined();
+    expect(invalidProps.current?.onResult).toBe(onResult);
+    expect(invalidProps.current?.enableDebugMode).toBe(false);
+    const result = invalidProps.current?.result as { kind: string };
+    expect(result.kind).toBe("invalid");
+  });
+
+  it("forwards the partner's debug-mode opt-in to the dispatcher", () => {
+    render(
+      <UseSmileIDBuilder
+        builder={(builder) => {
+          builder.config((config) => {
+            config.enableDebugMode = true;
+          });
+        }}
+      />,
+    );
+
+    expect(invalidProps.current?.enableDebugMode).toBe(true);
+  });
+
+  it("reports debug mode as off when the config block is never opened", () => {
+    render(<UseSmileIDBuilder builder={() => {}} />);
+
+    expect(invalidProps.current?.enableDebugMode).toBe(false);
+  });
+
+  it("runs the builder closure once per mount, not per render", () => {
+    const builder = vi.fn(validFlow);
+    const tree = render(<UseSmileIDBuilder builder={builder} />);
+
+    act(() => {
+      tree.update(<UseSmileIDBuilder builder={builder} />);
+    });
+    act(() => {
+      tree.update(<UseSmileIDBuilder builder={vi.fn(validFlow)} />);
+    });
+
+    expect(builder).toHaveBeenCalledTimes(1);
+    expect(successProps.current).toBeDefined();
+  });
+});

package/src/presentation/flow/dsl/builder/screens_builder.ts

@@ -29,15 +29,13 @@ export type ButtonSlot = (props: {
 
 // --- Per-screen builders ---------------------------------------------------
 
+// Required fields stay optional on the type because partners assign them by mutating this builder; the flow validator rejects a missing one.
 export class ConsentConfigBuilder {
-  /** Your company name, shown in the consent copy. */
+  /** Required. Your company name, shown in the consent copy. */
   partnerName = "";
-  /**
-   * Optional partner logo shown on the consent screen, rendered next to
-   * the Smile ID icon at the top.
-   */
+  /** Required. Your logo, shown on the consent screen next to the Smile ID icon. */
   partnerIcon?: ReactNode;
-  /** URL of your privacy policy, linked from the consent screen. */
+  /** Required. URL of your privacy policy, linked from the consent screen. */
   partnerPrivacyPolicyUrl?: string;
   /**
    * Whether to show the "Powered by Smile ID" attribution. Defaults to

package/src/presentation/flow/dsl/use_smile_id_flow_builder.ts

@@ -33,6 +33,8 @@ import {
 } from "../validation/flow_validator";
 import { ValidationState } from "../validation/validation_state";
 import type { FlowBuildResult } from "./flow_build_result";
+import { decodeSmileIDToken } from "../../../data/util/use_smile_id_token_decoder";
+import type { TokenPayload } from "../../../data/model/token_payload";
 
 /**
  * Top-level DSL builder.
@@ -326,6 +328,13 @@ export class UseSmileIDFlowBuilder {
     const screens = this._screens?.build();
     const network = this._network?.build();
     const mlConfig = this._ml?.build();
+    const config = this._config?.build();
+
+    // Decode the JWT `payload` claim (pure, synchronous) so validation
+    // can relax the userDetails/consent requirements the token already
+    // covers. Skip rules mirror FlowNavigationManager's decode: offline
+    // mode and a missing/blank token keep the strict legacy rules.
+    const tokenPayload = decodeTokenPayload(config?.allowOfflineMode, network);
 
     const issues = runFlowValidation({
       steps: screens?.steps ?? [],
@@ -338,6 +347,7 @@ export class UseSmileIDFlowBuilder {
       enhancedDocumentVerificationParams:
         this.enhancedDocumentVerificationParams,
       userDetails: this.userDetails,
+      tokenPayload,
     });
     const state = ValidationState.invalid(issues);
     const blocking = firstErrorIssue(state);
@@ -386,7 +396,7 @@ export class UseSmileIDFlowBuilder {
         : {}),
       ...(this.userDetails ? { userDetails: this.userDetails } : {}),
       ...(this.userId ? { userId: this.userId } : {}),
-      ...(this._config ? { config: this._config.build() } : {}),
+      ...(config ? { config } : {}),
       ...(this._theme ? { theme: this._theme.build() } : {}),
       ...(network ? { network } : {}),
       ...(mlConfig ? { ml: mlConfig } : {}),
@@ -402,6 +412,22 @@ export class UseSmileIDFlowBuilder {
   }
 }
 
+/**
+ * Decode the `payload` claim from the partner JWT for build-time
+ * validation. `undefined` for offline mode, no/blank token, or an
+ * unparseable token — every validation rule then stays exactly as
+ * strict as before token support existed.
+ */
+function decodeTokenPayload(
+  allowOfflineMode: boolean | undefined,
+  network: NetworkConfig | undefined,
+): TokenPayload | undefined {
+  if (allowOfflineMode) return undefined;
+  const token = network?.config?.token;
+  if (!token || token.length === 0) return undefined;
+  return decodeSmileIDToken(token)?.tokenPayload;
+}
+
 /**
  * Frozen snapshot produced by `UseSmileIDFlowBuilder.build()`.
  *

package/src/presentation/flow/flow_navigation_manager.ts

@@ -1,18 +1,9 @@
 import type { ScreenSpec } from "./dsl/builder/screens_builder";
 import type { FlowConfigurationSnapshot } from "./dsl/use_smile_id_flow_builder";
 import type { JobSubmissionState } from "./job_submission_state";
-import type {
-  DocumentVerificationRequest,
-  EnhancedDocumentVerificationRequest,
-  JobRequest,
-} from "../../data/model/job_request";
+import type { JobRequest } from "../../data/model/job_request";
 import type { UseSmileIDRepository } from "../../data/repository/use_smile_id_repository";
-import type {
-  ConsentInformation,
-  DocumentVerificationParams,
-  EnhancedDocumentVerificationParams,
-  UserDetails,
-} from "../../core/models/params";
+import type { ConsentInformation, UserDetails } from "../../core/models/params";
 import { JobType } from "../../core/models/job_type";
 import { CaptureType } from "../../core/models/ml_config";
 import {
@@ -20,17 +11,17 @@ import {
   type DocumentType,
 } from "../../core/models/document_type";
 import type { JobSubmissionResponse } from "../../data/model/job_submission_response";
-import { MissingRequiredFieldException } from "../../core/exception/job_validation_exceptions";
+import {
+  MissingJobTypeException,
+  MissingRequiredFieldException,
+} from "../../core/exception/job_validation_exceptions";
 import {
   UseSmileIDAnalyticsEventTypes,
   UseSmileIDAnalyticsParamKeys,
   UseSmileIDAnalyticsScreenNames,
   type UseSmileIDAnalyticsEventType,
 } from "./analytics/use_smile_id_analytics_event";
-import type {
-  MetadataEntry,
-  UseSmileIDMetadata,
-} from "../../metadata/use_smile_id_metadata";
+import type { MetadataEntry } from "../../metadata/use_smile_id_metadata";
 import {
   UseSmileIDMetadataFactory,
   type MetadataProvider,
@@ -52,6 +43,16 @@ import {
   decodeSmileIDToken,
   type DecodedToken,
 } from "../../data/util/use_smile_id_token_decoder";
+import {
+  isTokenConsentComplete,
+  bindsRequiredUserDetails,
+  type TokenPayload,
+} from "../../data/model/token_payload";
+import {
+  isUserDetailsPayloadEmpty,
+  userDetailsPayloadFrom,
+} from "../../data/model/user_details_payload";
+import type { UserDetailsPayload } from "../../data/model/user_details_payload";
 import {
   DocumentSide,
   EnhancedSmartSelfieConfig,
@@ -166,6 +167,15 @@ export class FlowNavigationManager {
   /** Canonical `partner_id` decoded from the JWT (raw); resolved via the [partnerId] getter. */
   private readonly _resolvedPartnerId: string | undefined;
 
+  /**
+   * Token-bound user-detail/consent bindings decoded from the JWT
+   * `payload` claim, resolved once at construction alongside
+   * `resolvedSdkConfig`. `undefined` for offline mode / no token /
+   * legacy token — assembly then requires and sends everything exactly
+   * as before token support existed.
+   */
+  private readonly _resolvedTokenPayload: TokenPayload | undefined;
+
   /**
    * Partner identifier the capture screen stamps into the Smile EXIF tag — the tag's HMAC/AES
    * keys derive from it and the backend validates the tag against the request's partner_id.
@@ -188,7 +198,6 @@ export class FlowNavigationManager {
 
   constructor(options: FlowNavigationManagerOptions) {
     this._configuration = options.configuration;
-    this._steps = options.configuration.screens.steps;
     this._onExit = options.onExit;
     this._repository = options.repository;
     // Fall back to a fresh factory so capture-only harnesses still build
@@ -202,6 +211,14 @@ export class FlowNavigationManager {
     );
     this.resolvedSdkConfig = decodedToken?.sdkConfig;
     this._resolvedPartnerId = decodedToken?.partnerId;
+    this._resolvedTokenPayload = decodedToken?.tokenPayload;
+    // Token consent always wins: a complete binding drops the consent
+    // screen from the flow — the server injects the token's record, so
+    // nothing is collected here.
+    const steps = options.configuration.screens.steps;
+    this._steps = isTokenConsentComplete(decodedToken?.tokenPayload?.consent)
+      ? steps.filter((s) => s.kind !== "consent")
+      : steps;
     // Seed the path with the first screen so currentScreen/renderer have a
     // deterministic start. Empty path → host renders the "no screens"
     // sentinel (validation rejects empty screens at build time anyway).
@@ -775,10 +792,18 @@ export class FlowNavigationManager {
   private _assembleJob(): JobRequest {
     const config = this._configuration;
     const jobType = config.network?.config?.jobType ?? JobType.unknown;
-    const consent =
-      this._captured.consentInformation ??
-      config.consentInformation ??
-      DEFAULT_CONSENT;
+    // Token consent always wins: the `consent` part is omitted — the
+    // server injects the token's record — and any local preset or
+    // capture is ignored. Without a token binding, a local source
+    // (captured on the consent screen, else the builder preset) is
+    // sent in full, and the legacy DEFAULT_CONSENT placeholder covers
+    // the no-source case.
+    const consent = isTokenConsentComplete(this._resolvedTokenPayload?.consent)
+      ? undefined
+      : (this._captured.consentInformation ??
+        config.consentInformation ??
+        DEFAULT_CONSENT);
+    const consentField = consent !== undefined ? { consent } : {};
     // Build the per-submission metadata snapshot so it travels on the
     // request (API layer serializes `request.metadata` directly).
     // Dynamic fields (orientation, locale, timezone) re-resolve per
@@ -806,8 +831,8 @@ export class FlowNavigationManager {
           jobType: JobType.smartSelfieEnrollment,
           selfieImage: selfie.selfiePath,
           livenessImages: selfie.livenessPaths,
-          userDetails,
-          consent,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
           enhanced: false,
           expectedLivenessImageCount: this._expectedLivenessImageCount(),
@@ -822,9 +847,9 @@ export class FlowNavigationManager {
           jobType: JobType.smartSelfieAuthentication,
           selfieImage: selfie.selfiePath,
           livenessImages: selfie.livenessPaths,
-          userDetails,
+          ...(userDetails !== undefined ? { userDetails } : {}),
           userId,
-          consent,
+          ...consentField,
           metadata,
           enhanced: false,
           expectedLivenessImageCount: this._expectedLivenessImageCount(),
@@ -845,8 +870,8 @@ export class FlowNavigationManager {
           selfieImage: selfie.selfiePath,
           livenessImages: selfie.livenessPaths,
           params,
-          userDetails,
-          consent,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
           expectedLivenessImageCount: this._expectedLivenessImageCount(),
         };
@@ -862,14 +887,17 @@ export class FlowNavigationManager {
           });
         }
         const userDetails = this._requireUserDetails(config);
-        return this._buildDocumentRequest(
-          selfie,
-          front,
-          params,
-          userDetails,
-          consent,
+        return {
+          jobType: JobType.documentVerification,
+          ...this._documentRequestFields(selfie, front),
+          country: params.country,
+          // Optional — omit when unset so the server classifies the document.
+          ...(params.idType ? { idType: params.idType } : {}),
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
-        );
+          expectedLivenessImageCount: this._expectedLivenessImageCount(),
+        };
       }
 
       case JobType.enhancedDocumentVerification: {
@@ -882,14 +910,16 @@ export class FlowNavigationManager {
           });
         }
         const userDetails = this._requireUserDetails(config);
-        return this._buildEnhancedDocumentRequest(
-          selfie,
-          front,
-          params,
-          userDetails,
-          consent,
+        return {
+          jobType: JobType.enhancedDocumentVerification,
+          ...this._documentRequestFields(selfie, front),
+          country: params.country,
+          idType: params.idType,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
-        );
+          expectedLivenessImageCount: this._expectedLivenessImageCount(),
+        };
       }
 
       case JobType.enhancedKyc: {
@@ -903,8 +933,8 @@ export class FlowNavigationManager {
         return {
           jobType: JobType.enhancedKyc,
           params,
-          userDetails,
-          consent,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
         };
       }
@@ -924,18 +954,15 @@ export class FlowNavigationManager {
         return {
           jobType: JobType.bvn,
           params,
-          userDetails,
-          consent,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
         };
       }
 
       case JobType.unknown:
       default:
-        throw new Error(
-          "Job type not configured — call `b.network((n) => n.config((c) => { c.jobType = JobType.<...>; }))` " +
-            "before mounting <UseSmileIDBuilder>.",
-        );
+        throw new MissingJobTypeException();
     }
   }
 
@@ -950,12 +977,28 @@ export class FlowNavigationManager {
     return { selfiePath, livenessPaths };
   }
 
-  private _requireUserDetails(config: FlowConfigurationSnapshot): UserDetails {
+  /**
+   * Resolve `b.userDetails` for the wire. May legitimately return
+   * `undefined` when the token binds every required field
+   * (`given_names`, `last_name`, and a contact field) — the
+   * `user_details` part is then omitted and the server injects the
+   * token's values. Otherwise throws exactly as before token support.
+   */
+  private _requireUserDetails(
+    config: FlowConfigurationSnapshot,
+  ): UserDetailsPayload | undefined {
     const userDetails = config.userDetails;
     if (!userDetails) {
+      if (bindsRequiredUserDetails(this._resolvedTokenPayload)) {
+        return undefined;
+      }
       throw new MissingRequiredFieldException({ fieldName: "userDetails" });
     }
-    return userDetails;
+    const payload = userDetailsPayloadFrom(
+      userDetails,
+      this._resolvedTokenPayload,
+    );
+    return isUserDetailsPayloadEmpty(payload) ? undefined : payload;
   }
 
   /**
@@ -979,58 +1022,25 @@ export class FlowNavigationManager {
     return frontDocumentPath;
   }
 
-  private _buildDocumentRequest(
+  /** Capture-artifact fields shared by both document request variants. */
+  private _documentRequestFields(
     selfie: {
       readonly selfiePath: string;
       readonly livenessPaths: readonly string[];
     },
     frontDocument: string,
-    params: DocumentVerificationParams,
-    userDetails: UserDetails,
-    consent: ConsentInformation,
-    metadata: UseSmileIDMetadata,
-  ): DocumentVerificationRequest {
-    const { backDocumentPath } = this._captured;
-    return {
-      jobType: JobType.documentVerification,
-      selfieImage: selfie.selfiePath,
-      livenessImages: selfie.livenessPaths,
-      frontDocument,
-      ...(backDocumentPath ? { backDocument: backDocumentPath } : {}),
-      country: params.country,
-      // Optional — omit when unset so the server classifies the document.
-      ...(params.idType ? { idType: params.idType } : {}),
-      userDetails,
-      consent,
-      metadata,
-      expectedLivenessImageCount: this._expectedLivenessImageCount(),
-    };
-  }
-
-  private _buildEnhancedDocumentRequest(
-    selfie: {
-      readonly selfiePath: string;
-      readonly livenessPaths: readonly string[];
-    },
-    frontDocument: string,
-    params: EnhancedDocumentVerificationParams,
-    userDetails: UserDetails,
-    consent: ConsentInformation,
-    metadata: UseSmileIDMetadata,
-  ): EnhancedDocumentVerificationRequest {
+  ): {
+    readonly selfieImage: string;
+    readonly livenessImages: readonly string[];
+    readonly frontDocument: string;
+    readonly backDocument?: string;
+  } {
     const { backDocumentPath } = this._captured;
     return {
-      jobType: JobType.enhancedDocumentVerification,
       selfieImage: selfie.selfiePath,
       livenessImages: selfie.livenessPaths,
       frontDocument,
       ...(backDocumentPath ? { backDocument: backDocumentPath } : {}),
-      country: params.country,
-      idType: params.idType,
-      userDetails,
-      consent,
-      metadata,
-      expectedLivenessImageCount: this._expectedLivenessImageCount(),
     };
   }
 

package/src/presentation/flow/graph/__tests__/screen_renderer.test.tsx

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+
+// `vi.mock` is hoisted above the imports, so anything its factory closes over
+// must be created with `vi.hoisted` or it is still in the TDZ when the factory
+// runs.
+const { dispatched } = vi.hoisted(() => ({
+  dispatched: {
+    current: undefined as
+      | { screen: string; configuration: unknown }
+      | undefined,
+  },
+}));
+
+function stub(screen: string) {
+  return ({ configuration }: { configuration: unknown }) => {
+    dispatched.current = { screen, configuration };
+    return null;
+  };
+}
+
+// Stand in for every orchestrated screen: this suite asserts the switch routes
+// each step kind (and its config) to the right screen — each screen has its own
+// suite for what it then does with that config.
+vi.mock("../../screen/orchestrated_capture_screen", () => ({
+  OrchestratedCaptureScreen: stub("capture"),
+}));
+vi.mock("../../screen/orchestrated_consent_screen", () => ({
+  OrchestratedConsentScreen: stub("consent"),
+}));
+vi.mock("../../screen/orchestrated_instructions_screen", () => ({
+  OrchestratedInstructionsScreen: stub("instructions"),
+}));
+vi.mock("../../screen/orchestrated_preview_screen", () => ({
+  OrchestratedPreviewScreen: stub("preview"),
+}));
+vi.mock("../../screen/orchestrated_processing_screen", () => ({
+  OrchestratedProcessingScreen: stub("processing"),
+}));
+
+import { ScreenRenderer } from "../screen_renderer";
+import {
+  CaptureType,
+  ScreensBuilder,
+  type ScreenSpec,
+} from "../../dsl/builder/screens_builder";
+
+const steps: readonly ScreenSpec[] = (() => {
+  const screensBuilder = new ScreensBuilder();
+  screensBuilder.consent();
+  screensBuilder.instructions();
+  screensBuilder.capture((capture) => {
+    capture.captureType = CaptureType.selfie;
+  });
+  screensBuilder.preview();
+  screensBuilder.processing();
+  return screensBuilder.build().steps;
+})();
+
+function stepOfKind(kind: ScreenSpec["kind"]): ScreenSpec {
+  const step = steps.find((candidate) => candidate.kind === kind);
+  if (!step) throw new Error(`no ${kind} step built`);
+  return step;
+}
+
+function render(step: ScreenSpec) {
+  act(() => {
+    createRenderer(<ScreenRenderer step={step} />);
+  });
+  const current = dispatched.current;
+  if (!current) throw new Error("ScreenRenderer dispatched nothing");
+  return current;
+}
+
+beforeEach(() => {
+  dispatched.current = undefined;
+});
+
+describe("ScreenRenderer", () => {
+  it.each([
+    ["consent"],
+    ["instructions"],
+    ["capture"],
+    ["preview"],
+    ["processing"],
+  ] as const)("routes a %s step to its orchestrated screen", (kind) => {
+    const step = stepOfKind(kind);
+    const result = render(step);
+
+    expect(result.screen).toBe(kind);
+    expect(result.configuration).toBe(step.config);
+  });
+
+  it("hands each step its own config object, not a shared one", () => {
+    const capture = render(stepOfKind("capture")).configuration;
+    const preview = render(stepOfKind("preview")).configuration;
+
+    expect(capture).not.toBe(preview);
+    expect(capture).toBe(stepOfKind("capture").config);
+  });
+});