@smileid/usesmileid 12.0.0-beta01 → 12.0.0

package/src/data/security/request_canonicalizer.ts

@@ -1,4 +1,5 @@
 import { base64Encode, utf8Bytes } from "./signing_crypto";
+import { SmileIDCryptoError } from "./smile_id_crypto_error";
 
 /**
  * Reduces a request to the canonical bytes that get signed: the signed headers
@@ -86,8 +87,20 @@ async function canonicalBody(body: unknown): Promise<Uint8Array> {
 /** File parts (a `uri`) → Base64 of bytes; JSON fields → parsed; else string with bool coercion. */
 async function partValue(part: FormDataPart): Promise<unknown> {
   if (part.uri != null) {
-    const response = await fetch(part.uri);
-    return base64Encode(new Uint8Array(await response.arrayBuffer()));
+    // Reading a file part can reject — e.g. the captured-image `file://` URI is
+    // unreadable, or the RN runtime rejects a local-file `fetch` when the device
+    // is offline (behaviour differs between the Expo and bare-RN runtimes).
+    // Surface it as a SmileIDCryptoError so the signing interceptor's narrow
+    // catch fails open (ships the request unsigned) instead of letting the
+    // rejection escape and crash the submission flow.
+    try {
+      const response = await fetch(part.uri);
+      return base64Encode(new Uint8Array(await response.arrayBuffer()));
+    } catch (cause) {
+      throw new SmileIDCryptoError(
+        `Failed to read request part "${part.fieldName}" for signing: ${String(cause)}`,
+      );
+    }
   }
   const value = part.string ?? "";
   if (JSON_FIELDS.has(part.fieldName)) {

package/src/data/security/security_policy.ts

@@ -0,0 +1,70 @@
+/**
+ * Server-driven security policy decoded from the integer `policy` bit-code carried as a top-level
+ * claim on the SmileID JWT — a sibling of the `sdk_config` claim, not nested inside it (see
+ * `decodeSecurityPolicyBitCode` and `docs/Policy.md`).
+ *
+ * Each bit toggles one SDK security behaviour, so the backend can dial protection up or down per
+ * session without shipping a new SDK build. The bit-code contract — which bit means what — is
+ * documented in `docs/Policy.md`, not here, so the four SDKs share one source of truth.
+ *
+ * **Fail-secure:** an absent (`undefined`) bit-code enables every behaviour, so a token that omits
+ * the claim — or a malformed token that fails to decode — runs with full protection rather than
+ * silently dropping security. This matches the value `undefined` produces in
+ * {@link SecurityPolicy.fromBitCode}.
+ *
+ * **Internal by design:** this class is not exported from the package entrypoint (`src/index.ts`),
+ * so it never becomes part of the partner-facing API; it exists only so the SDK can gate its own
+ * request signing and device attestation.
+ */
+export class SecurityPolicy {
+  private static readonly _BIT_PAYLOAD_SIGNING = 0;
+  private static readonly _BIT_PAYLOAD_ENCRYPTION = 1;
+  private static readonly _BIT_ROOTED_DEVICE_CHECK = 2;
+  private static readonly _BIT_PLAY_INTEGRITY_CHECK = 3;
+
+  // Fail-secure default for an absent bit-code: every known behaviour active.
+  private static readonly _ALL_ACTIVE =
+    (1 << SecurityPolicy._BIT_PAYLOAD_SIGNING) |
+    (1 << SecurityPolicy._BIT_PAYLOAD_ENCRYPTION) |
+    (1 << SecurityPolicy._BIT_ROOTED_DEVICE_CHECK) |
+    (1 << SecurityPolicy._BIT_PLAY_INTEGRITY_CHECK);
+
+  private readonly _bitCode: number;
+
+  private constructor(bitCode: number) {
+    this._bitCode = bitCode;
+  }
+
+  /**
+   * Decode a `bitCode` into a typed policy. An `undefined` code is fail-secure — every behaviour
+   * is active. For a defined code, behaviour `b` is active when bit `b` is set, least-significant
+   * bit first.
+   */
+  static fromBitCode(bitCode: number | undefined): SecurityPolicy {
+    return new SecurityPolicy(bitCode ?? SecurityPolicy._ALL_ACTIVE);
+  }
+
+  /** True when the server enabled request-payload HMAC signing for this session. */
+  isPayloadSigningActive(): boolean {
+    return this._isSet(SecurityPolicy._BIT_PAYLOAD_SIGNING);
+  }
+
+  /** True when the server enabled request-payload encryption for this session. */
+  isPayloadEncryptionActive(): boolean {
+    return this._isSet(SecurityPolicy._BIT_PAYLOAD_ENCRYPTION);
+  }
+
+  /** True when the server enabled the rooted / jailbroken device check for this session. */
+  isRootedDeviceCheckActive(): boolean {
+    return this._isSet(SecurityPolicy._BIT_ROOTED_DEVICE_CHECK);
+  }
+
+  /** True when the server enabled device attestation for this session. */
+  isPlayIntegrityCheckActive(): boolean {
+    return this._isSet(SecurityPolicy._BIT_PLAY_INTEGRITY_CHECK);
+  }
+
+  private _isSet(bit: number): boolean {
+    return ((this._bitCode >> bit) & 1) === 1;
+  }
+}

package/src/data/util/__tests__/use_smile_id_token_decoder.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { decodeSmileIDToken } from "../use_smile_id_token_decoder";
+import {
+  decodeSmileIDToken,
+  decodeSecurityPolicyBitCode,
+} from "../use_smile_id_token_decoder";
 
 // ---------------------------------------------------------------------------
 // Helper — mint a structurally valid JWT with a caller-supplied payload.
@@ -14,6 +17,59 @@ function makeJwt(payload: Record<string, unknown>): string {
   return `eyJhbGciOiJub25lIn0.${payloadSegment}.stub-sig`;
 }
 
+// ---------------------------------------------------------------------------
+// Security policy bit-code extraction
+// ---------------------------------------------------------------------------
+describe("decodeSecurityPolicyBitCode", () => {
+  it("parses the top-level policy bit-code alongside sdk_config", () => {
+    const token = makeJwt({
+      policy: 9,
+      sdk_config: { selfie: { quality: 85 } },
+    });
+    expect(decodeSecurityPolicyBitCode(token)).toBe(9);
+  });
+
+  it("parses the top-level policy bit-code when sdk_config is absent", () => {
+    const token = makeJwt({ policy: 0 });
+    expect(decodeSecurityPolicyBitCode(token)).toBe(0);
+  });
+
+  it("returns undefined when the token omits policy", () => {
+    const token = makeJwt({ sdk_config: { selfie: { quality: 85 } } });
+    expect(decodeSecurityPolicyBitCode(token)).toBeUndefined();
+  });
+
+  it("returns undefined for a structurally invalid token", () => {
+    expect(decodeSecurityPolicyBitCode("not-a-jwt")).toBeUndefined();
+  });
+
+  it("returns undefined when policy is not a number", () => {
+    const token = makeJwt({ policy: "9" });
+    expect(decodeSecurityPolicyBitCode(token)).toBeUndefined();
+  });
+});
+
+describe("decodeSmileIDToken — partner_id claim (stamped onto the EXIF tag)", () => {
+  it("parses the canonical top-level partner_id claim", () => {
+    // The EXIF tagger keys on this, so it must be the server-canonical form (e.g. "002").
+    const token = makeJwt({
+      partner_id: "002",
+      sdk_config: { selfie: { width: 640 } },
+    });
+    expect(decodeSmileIDToken(token)?.partnerId).toBe("002");
+  });
+
+  it("leaves partnerId undefined when the claim is absent", () => {
+    const token = makeJwt({ sdk_config: { selfie: { quality: 85 } } });
+    expect(decodeSmileIDToken(token)?.partnerId).toBeUndefined();
+  });
+
+  it("leaves partnerId undefined when the claim is not a string", () => {
+    const token = makeJwt({ partner_id: 2 });
+    expect(decodeSmileIDToken(token)?.partnerId).toBeUndefined();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Structural failure paths → undefined
 // ---------------------------------------------------------------------------

package/src/data/util/retry_util.ts

@@ -13,12 +13,13 @@ import type { RetryConfig } from "../../core/models/network_config";
  */
 export async function withRetry<T>(
   config: RetryConfig,
-  block: () => Promise<T>,
+  block: (attempt: number) => Promise<T>,
 ): Promise<T> {
   let lastError: unknown;
   for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
     try {
-      return await block();
+      // `attempt` is the number of retries that preceded this try (0 first).
+      return await block(attempt);
     } catch (error) {
       lastError = error;
       if (!isRetryable(error) || attempt === config.maxAttempts - 1) {

package/src/data/util/use_smile_id_token_decoder.ts

@@ -20,6 +20,14 @@ declare function atob(data: string): string;
  */
 export type DecodedToken = {
   readonly sdkConfig?: SdkConfig;
+  /**
+   * Canonical `partner_id` from the top-level JWT claim (server-padded form,
+   * e.g. `"002"`), which can differ from the partner-supplied config string
+   * (`"2"`). The Smile EXIF tagger keys its HMAC/AES derivation on this so the
+   * stamped value matches the partner_id the backend validates against.
+   * `undefined` when the claim is absent.
+   */
+  readonly partnerId?: string;
 };
 
 /**
@@ -40,6 +48,73 @@ export type DecodedToken = {
  * This function never throws — all failure paths return a value.
  */
 export function decodeSmileIDToken(token: string): DecodedToken | undefined {
+  const payloadObject = parseJwtPayloadObject(token);
+  if (payloadObject === undefined) return undefined;
+
+  // Canonical partner_id — a TOP-LEVEL claim (server-padded form, e.g. "002"), a sibling of
+  // `sdk_config`. The EXIF tagger keys on this so the stamped value matches the backend. Spread
+  // in only when present so `exactOptionalPropertyTypes` isn't violated by an explicit undefined.
+  const rawPartnerId = payloadObject["partner_id"];
+  const partnerIdField =
+    typeof rawPartnerId === "string" ? { partnerId: rawPartnerId } : {};
+
+  const rawClaim = payloadObject["sdk_config"];
+
+  if (rawClaim === undefined || rawClaim === null) {
+    // No claim present — defaults apply throughout the flow.
+    return { ...partnerIdField };
+  }
+
+  if (typeof rawClaim !== "object" || Array.isArray(rawClaim)) {
+    // Claim exists but is not an object — treat as absent.
+    return { ...partnerIdField };
+  }
+
+  const parseResult = sdkConfigSchema.safeParse(rawClaim);
+  if (!parseResult.success) {
+    // Zod rejected the claim shape — degrade to defaults.
+    if (!(parseResult.error instanceof ZodError)) {
+      // Unreachable in practice (safeParse always gives ZodError on
+      // failure), but degrade gracefully to preserve the never-throws
+      // contract rather than surfacing an unexpected error type.
+      return { ...partnerIdField };
+    }
+    return { ...partnerIdField };
+  }
+
+  return { sdkConfig: parseResult.data, ...partnerIdField };
+}
+
+/**
+ * Extract the server-driven security policy bit-code from the token's **top-level** `policy` claim
+ * (a sibling of `sdk_config`, not nested inside it — mirroring the backend and the v11
+ * `/v1/auth_smile` response).
+ *
+ * Internal-only: deliberately NOT re-exported from the package entrypoint (`src/index.ts`), so the
+ * policy never widens the partner-facing API. It rides here — alongside the decoder — rather than
+ * on the exported {@link DecodedToken} for the same reason. See `SecurityPolicy` and
+ * `docs/Policy.md`.
+ *
+ * Returns `undefined` when the token is unparseable or carries no numeric top-level `policy`. The
+ * caller treats `undefined` as fail-secure (every behaviour active), so this never throws.
+ */
+export function decodeSecurityPolicyBitCode(token: string): number | undefined {
+  const payloadObject = parseJwtPayloadObject(token);
+  if (payloadObject === undefined) return undefined;
+
+  const policy = payloadObject["policy"];
+  return typeof policy === "number" ? policy : undefined;
+}
+
+/**
+ * Parse the JWT payload (middle segment) into a JSON object, or `undefined` when the token is
+ * structurally invalid (not exactly three `.`-delimited segments, non-base64url payload, or a
+ * non-object JSON payload). Shared by {@link decodeSmileIDToken} and
+ * {@link decodeSecurityPolicyBitCode} so both read the payload the same way.
+ */
+function parseJwtPayloadObject(
+  token: string,
+): Record<string, unknown> | undefined {
   const segments = token.split(".");
   if (segments.length !== 3) return undefined;
 
@@ -74,34 +149,7 @@ export function decodeSmileIDToken(token: string): DecodedToken | undefined {
     return undefined;
   }
 
-  // Valid structural token from here on — failures below degrade to an
-  // empty DecodedToken (sdkConfig unset) rather than returning undefined.
-  const payloadObject = payload as Record<string, unknown>;
-  const rawClaim = payloadObject["sdk_config"];
-
-  if (rawClaim === undefined || rawClaim === null) {
-    // No claim present — defaults apply throughout the flow.
-    return {};
-  }
-
-  if (typeof rawClaim !== "object" || Array.isArray(rawClaim)) {
-    // Claim exists but is not an object — treat as absent.
-    return {};
-  }
-
-  const parseResult = sdkConfigSchema.safeParse(rawClaim);
-  if (!parseResult.success) {
-    // Zod rejected the claim shape — degrade to defaults.
-    if (!(parseResult.error instanceof ZodError)) {
-      // Unreachable in practice (safeParse always gives ZodError on
-      // failure), but degrade gracefully to preserve the never-throws
-      // contract rather than surfacing an unexpected error type.
-      return {};
-    }
-    return {};
-  }
-
-  return { sdkConfig: parseResult.data };
+  return payload as Record<string, unknown>;
 }
 
 /**

package/src/l10n/strings_en.ts

@@ -160,6 +160,7 @@ export const enStrings = {
   si_ess_look_left: "Turn your head to the left",
   si_ess_look_right: "Turn your head to the right",
   si_ess_look_up: "Turn your head slightly upwards",
+  si_ess_look_at_camera: "Look at the camera",
   si_ess_capture_initial_instruction:
     "Centre your face in the frame and turn your head in the direction of the arrow.",
   si_ess_hold_still: "Hold still…",
@@ -168,4 +169,4 @@ export const enStrings = {
 export type SiKey = keyof typeof enStrings;
 
 /** Total canonical key count — pinned in tests to catch a missed addition/deletion at PR time. */
-export const CANONICAL_KEY_COUNT = 118 as const;
+export const CANONICAL_KEY_COUNT = 119 as const;

package/src/l10n/use_smile_id_localizations.ts

@@ -676,6 +676,9 @@ export class UseSmileIDLocalizations {
   get siEssLookUp(): string {
     return this._s("si_ess_look_up", enStrings.si_ess_look_up);
   }
+  get siEssLookAtCamera(): string {
+    return this._s("si_ess_look_at_camera", enStrings.si_ess_look_at_camera);
+  }
   get siEssCaptureInitialInstruction(): string {
     return this._s(
       "si_ess_capture_initial_instruction",

package/src/metadata/__tests__/device_orientation_collector.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+
+import { DeviceOrientationCollector } from "../device_orientation_collector";
+
+/**
+ * Regression guard: with no accelerometer samples, `device_movement_detected` must be absent
+ * (`null`) and `device_positions` empty — never a sentinel. Mirrored across all four SDKs.
+ */
+describe("DeviceOrientationCollector", () => {
+  it("omits movement (null) and positions when no samples were collected", () => {
+    const collector = new DeviceOrientationCollector();
+    expect(collector.deviceMovementDetected).toBeNull();
+    expect(collector.devicePositions).toHaveLength(0);
+  });
+});

package/src/metadata/__tests__/metadata_configuration_mappers.test.ts

@@ -0,0 +1,215 @@
+import {
+  AnalyzerFactoryKey,
+  faceConfigSchema,
+} from "@smileid/usesmileid_bridge";
+import { describe, expect, it } from "vitest";
+
+import { DocumentCaptureMode } from "../../core/models/document_capture_mode";
+import { CaptureType } from "../../core/models/ml_config";
+import type { FlowConfiguration } from "../../presentation/flow/config/flow_configuration";
+import { ScreensBuilder } from "../../presentation/flow/dsl/builder/screens_builder";
+import {
+  ModelProvider,
+  MODEL_DESCRIPTOR_UNKNOWN,
+} from "../model_configuration";
+import {
+  flowConfigurationToBuilderConfiguration,
+  flowConfigurationToModelConfiguration,
+  flowConfigurationToSelfieLivenessTelemetry,
+} from "../metadata_configuration_mappers";
+
+function flow(
+  buildScreens: (screens: ScreensBuilder) => void,
+  ml?: FlowConfiguration["ml"],
+): FlowConfiguration {
+  const screensBuilder = new ScreensBuilder();
+  buildScreens(screensBuilder);
+  return {
+    screens: screensBuilder.build(),
+    ...(ml ? { ml } : {}),
+    onResult: () => {},
+  };
+}
+
+describe("flowConfigurationToBuilderConfiguration", () => {
+  it("reflects the consent screen", () => {
+    const config = flowConfigurationToBuilderConfiguration(
+      flow((screens) => {
+        screens.consent((consent) => {
+          consent.partnerIcon = "icon";
+          consent.showAttribution = false;
+        });
+      }),
+    );
+    expect(config.consentScreenUsed).toBe(true);
+    expect(config.consentIconProvided).toBe(true);
+    // A React Native consent icon is a ReactNode with no measurable pixel size.
+    expect(config.consentIconDimensions).toBeNull();
+    expect(config.consentAttributionShown).toBe(false);
+  });
+
+  it("reports consent absent when there is no consent screen", () => {
+    const config = flowConfigurationToBuilderConfiguration(
+      flow((screens) => screens.instructions()),
+    );
+    expect(config.consentScreenUsed).toBe(false);
+    expect(config.consentIconProvided).toBe(false);
+  });
+
+  it("maps selfie capture flags", () => {
+    const config = flowConfigurationToBuilderConfiguration(
+      flow((screens) => {
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.selfie;
+          capture.selfie((selfie) => {
+            selfie.allowAgentMode = true;
+            selfie.enableEnhancedLiveness = true;
+          });
+        });
+        screens.preview();
+      }),
+    );
+    expect(config.allowAgentMode).toBe(true);
+    expect(config.enhancedLivenessEnabled).toBe(true);
+    expect(config.selfiePreviewEnabled).toBe(true);
+    expect(config.documentPreviewEnabled).toBe(false);
+  });
+
+  it("maps document capture flags and capture mode", () => {
+    const config = flowConfigurationToBuilderConfiguration(
+      flow((screens) => {
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.document;
+          capture.document((document) => {
+            document.captureMode = DocumentCaptureMode.ManualCapture;
+            document.allowGalleryUpload = true;
+            document.captureBothSides = false;
+            document.allowSkipBack = true;
+          });
+        });
+        screens.preview();
+      }),
+    );
+    expect(config.autoCaptureEnabled).toBe("manual");
+    expect(config.allowGalleryUpload).toBe(true);
+    expect(config.captureBothSides).toBe(false);
+    expect(config.allowSkipBack).toBe(true);
+    expect(config.documentPreviewEnabled).toBe(true);
+    expect(config.selfiePreviewEnabled).toBe(false);
+  });
+
+  it("maps each document capture mode to the wire enum", () => {
+    const modeFor = (captureMode: DocumentCaptureMode): string =>
+      flowConfigurationToBuilderConfiguration(
+        flow((screens) => {
+          screens.capture((capture) => {
+            capture.captureType = CaptureType.document;
+            capture.document((document) => {
+              document.captureMode = captureMode;
+            });
+          });
+        }),
+      ).autoCaptureEnabled;
+
+    expect(modeFor(DocumentCaptureMode.AutoCapture)).toBe("auto_capture_only");
+    expect(modeFor(DocumentCaptureMode.ManualCapture)).toBe("manual");
+    expect(modeFor(DocumentCaptureMode.AutoCaptureWithManualFallback())).toBe(
+      "autocapture_default",
+    );
+  });
+
+  it("reports submission skipped without a processing screen", () => {
+    const selfieOnly = (screens: ScreensBuilder) =>
+      screens.capture((capture) => {
+        capture.captureType = CaptureType.selfie;
+      });
+    expect(
+      flowConfigurationToBuilderConfiguration(flow(selfieOnly))
+        .submissionSkipped,
+    ).toBe(true);
+    expect(
+      flowConfigurationToBuilderConfiguration(
+        flow((screens) => {
+          selfieOnly(screens);
+          screens.processing();
+        }),
+      ).submissionSkipped,
+    ).toBe(false);
+  });
+});
+
+describe("flowConfigurationToModelConfiguration", () => {
+  it("maps the face backend key with the noop document fallback", () => {
+    const config = flow(
+      (screens) =>
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.selfie;
+        }),
+      {
+        analyzers: {
+          selfieConfig: faceConfigSchema.parse({
+            analyzerFactoryKey: AnalyzerFactoryKey.MLKitFace,
+          }),
+        },
+      },
+    );
+    const model = flowConfigurationToModelConfiguration(config);
+    expect(model.faceModel.provider).toBe(ModelProvider.Google);
+    expect(model.faceModel.name).toBe("play-services-mlkit-face-detection");
+    expect(model.documentModel.provider).toBe(ModelProvider.Smile);
+  });
+
+  it("falls back to unknown for an ML-free flow", () => {
+    const model = flowConfigurationToModelConfiguration(
+      flow((screens) =>
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.selfie;
+        }),
+      ),
+    );
+    expect(model.faceModel).toEqual(MODEL_DESCRIPTOR_UNKNOWN);
+    expect(model.documentModel.provider).toBe(ModelProvider.Smile);
+  });
+});
+
+describe("flowConfigurationToSelfieLivenessTelemetry", () => {
+  it("reports smile for a standard selfie flow", () => {
+    const telemetry = flowConfigurationToSelfieLivenessTelemetry(
+      flow((screens) =>
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.selfie;
+          capture.selfie(() => {});
+        }),
+      ),
+    );
+    expect(telemetry.activeLivenessType).toBe("smile");
+    expect(telemetry.activeLivenessVersion).toBe("2.0.0");
+    expect(telemetry.selfieImageOrigin).toBe("front_camera");
+  });
+
+  it("reports head_pose when enhanced liveness is on", () => {
+    const telemetry = flowConfigurationToSelfieLivenessTelemetry(
+      flow((screens) =>
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.selfie;
+          capture.selfie((selfie) => {
+            selfie.enableEnhancedLiveness = true;
+          });
+        }),
+      ),
+    );
+    expect(telemetry.activeLivenessType).toBe("head_pose");
+  });
+
+  it("is all-null for a document-only flow", () => {
+    const telemetry = flowConfigurationToSelfieLivenessTelemetry(
+      flow((screens) =>
+        screens.capture((capture) => {
+          capture.captureType = CaptureType.document;
+        }),
+      ),
+    );
+    expect(telemetry.activeLivenessType).toBeNull();
+    expect(telemetry.selfieImageOrigin).toBeNull();
+  });
+});

package/src/metadata/__tests__/metadata_configuration_objects.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  type BuilderConfiguration,
+  builderConfigurationToJson,
+} from "../builder_configuration";
+import {
+  type ModelConfiguration,
+  ModelProvider,
+  modelConfigurationToJson,
+} from "../model_configuration";
+
+const builderConfiguration: BuilderConfiguration = {
+  consentScreenUsed: true,
+  consentIconProvided: true,
+  consentIconDimensions: { width: 120, height: 80 },
+  consentAttributionShown: true,
+  instructionsScreenUsed: true,
+  selfiePreviewEnabled: true,
+  documentPreviewEnabled: false,
+  submissionSkipped: false,
+  allowAgentMode: true,
+  enhancedLivenessEnabled: false,
+  autoCaptureEnabled: "autocapture_default",
+  allowGalleryUpload: true,
+  captureBothSides: true,
+  allowSkipBack: false,
+};
+
+const modelConfiguration: ModelConfiguration = {
+  faceModel: {
+    provider: ModelProvider.Google,
+    name: "play-services-mlkit-face-detection",
+    version: "17.1.0",
+    bundled: false,
+  },
+  documentModel: {
+    provider: ModelProvider.Smile,
+    name: "noop_document_detector",
+    version: "12.0.0",
+    bundled: true,
+  },
+};
+
+describe("builder_configuration_object", () => {
+  it("serialises the full schema with snake_case keys", () => {
+    const json = builderConfigurationToJson(builderConfiguration);
+    expect(json.consent_screen_used).toBe(true);
+    expect(json.consent_icon_provided).toBe(true);
+    expect(json.consent_icon_dimensions).toEqual({ width: 120, height: 80 });
+    expect(json.auto_capture_enabled).toBe("autocapture_default");
+    expect(json.allow_gallery_upload).toBe(true);
+  });
+
+  it("emits consent_icon_dimensions as null when absent", () => {
+    const json = builderConfigurationToJson({
+      ...builderConfiguration,
+      consentIconProvided: false,
+      consentIconDimensions: null,
+    });
+    expect(json.consent_icon_dimensions).toBeNull();
+    // round-trips through JSON.stringify as an explicit null, not an omitted key
+    const reparsed = JSON.parse(JSON.stringify(json)) as Record<
+      string,
+      unknown
+    >;
+    expect("consent_icon_dimensions" in reparsed).toBe(true);
+    expect(reparsed.consent_icon_dimensions).toBeNull();
+  });
+});
+
+describe("model_configuration_object", () => {
+  it("serialises both model descriptors", () => {
+    const json = modelConfigurationToJson(modelConfiguration);
+    const face = json.face_model as Record<string, unknown>;
+    expect(face.provider).toBe("google");
+    expect(face.name).toBe("play-services-mlkit-face-detection");
+    expect(face.version).toBe("17.1.0");
+    expect(face.bundled).toBe(false);
+
+    const document = json.document_model as Record<string, unknown>;
+    expect(document.provider).toBe("smile");
+    expect(document.bundled).toBe(true);
+  });
+});