@smileid/usesmileid 12.0.0 → 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/__tests__/config_builder.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import * as ScreenOrientation from "expo-screen-orientation";
+import { GlobalPrivacyControl } from "../../../../../core/models/global_privacy_control";
+import { UseSmileIDConfigBuilder } from "../config_builder";
+
+describe("UseSmileIDConfigBuilder", () => {
+  it("snapshots the documented defaults", () => {
+    expect(new UseSmileIDConfigBuilder().build()).toEqual({
+      enableCrashReporting: true,
+      enableDebugMode: false,
+      allowOfflineMode: false,
+      globalPrivacyControl: GlobalPrivacyControl.OptOut,
+      exitOrientations: ScreenOrientation.OrientationLock.PORTRAIT_UP,
+    });
+  });
+
+  it("carries an overridden exit orientation lock into the snapshot", () => {
+    const builder = new UseSmileIDConfigBuilder();
+    builder.exitOrientations = ScreenOrientation.OrientationLock.DEFAULT;
+
+    expect(builder.build().exitOrientations).toBe(
+      ScreenOrientation.OrientationLock.DEFAULT,
+    );
+  });
+});

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

@@ -1,4 +1,6 @@
+import * as ScreenOrientation from "expo-screen-orientation";
 import type { ConfigOptions } from "../../../../core/models/config";
+import { GlobalPrivacyControl } from "../../../../core/models/global_privacy_control";
 
 /**
  * `b.config((c) => { c.enableCrashReporting = false; ... })`
@@ -26,11 +28,30 @@ export class UseSmileIDConfigBuilder {
    */
   allowOfflineMode = false;
 
+  /**
+   * Consent posture for every session (`global_privacy_control`). Defaults
+   * to `GlobalPrivacyControl.OptOut` — the opt-out consent layout is
+   * enforced universally and regional detection is ignored. Set
+   * `GlobalPrivacyControl.OptIn` to keep the legacy regional mechanics
+   * (opt-in inside the EU, opt-out elsewhere).
+   */
+  globalPrivacyControl: GlobalPrivacyControl = GlobalPrivacyControl.OptOut;
+
+  /**
+   * Orientation lock applied when a capture screen leaves the screen.
+   * Defaults to portrait-up; set `ScreenOrientation.OrientationLock.DEFAULT`
+   * if your app supports more than one orientation.
+   */
+  exitOrientations: ScreenOrientation.OrientationLock =
+    ScreenOrientation.OrientationLock.PORTRAIT_UP;
+
   build(): ConfigOptions {
     return Object.freeze({
       enableCrashReporting: this.enableCrashReporting,
       enableDebugMode: this.enableDebugMode,
       allowOfflineMode: this.allowOfflineMode,
+      globalPrivacyControl: this.globalPrivacyControl,
+      exitOrientations: this.exitOrientations,
     });
   }
 }

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
@@ -89,8 +87,9 @@ export class InstructionsConfigBuilder {
 
 export class SelfieCaptureConfigBuilder {
   /**
-   * When true, lets an assisting agent flip to the rear camera to capture
-   * the subject. Defaults to false.
+   * When true, the whole selfie session captures on the rear camera so an
+   * assisting agent can point it at the subject. Cannot be combined with
+   * {@link enableEnhancedLiveness}.
    */
   allowAgentMode = false;
   /**
@@ -180,10 +179,6 @@ export class PreviewConfigBuilder {
    * true.
    */
   showAttribution = true;
-  /** Provides a custom continue button in place of the default. */
-  continueButton?: ButtonSlot;
-  /** Provides a custom cancel button in place of the default. */
-  cancelButton?: ButtonSlot;
 }
 
 export class ProcessingConfigBuilder {

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).
@@ -693,9 +710,14 @@ export class FlowNavigationManager {
     void this._submit();
   }
 
-  /** Reset to `notAttempted` and re-fire submission (processing screen's onRetry). */
+  /**
+   * Reset to `notAttempted` and re-fire submission (processing screen's
+   * onRetry). Ignored while a submission is in flight — resetting then would
+   * defeat `beginSubmissionIfNeeded()`'s single-flight guard.
+   */
   retrySubmission(): void {
     if (this._disposed) return;
+    if (this._jobSubmissionState.kind === "loading") return;
     this._setSubmissionState({ kind: "notAttempted" });
     this.beginSubmissionIfNeeded();
   }
@@ -770,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
@@ -801,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(),
@@ -817,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(),
@@ -840,8 +870,8 @@ export class FlowNavigationManager {
           selfieImage: selfie.selfiePath,
           livenessImages: selfie.livenessPaths,
           params,
-          userDetails,
-          consent,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
           expectedLivenessImageCount: this._expectedLivenessImageCount(),
         };
@@ -857,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: {
@@ -877,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: {
@@ -898,8 +933,8 @@ export class FlowNavigationManager {
         return {
           jobType: JobType.enhancedKyc,
           params,
-          userDetails,
-          consent,
+          ...(userDetails !== undefined ? { userDetails } : {}),
+          ...consentField,
           metadata,
         };
       }
@@ -919,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();
     }
   }
 
@@ -945,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;
   }
 
   /**
@@ -974,58 +1022,25 @@ export class FlowNavigationManager {
     return frontDocumentPath;
   }
 
-  private _buildDocumentRequest(
-    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(
+  /** Capture-artifact fields shared by both document request variants. */
+  private _documentRequestFields(
     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(),
     };
   }