@smileid/usesmileid 12.0.0-beta01 → 12.0.1

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

@@ -0,0 +1,18 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("react-native", () => ({
+  Platform: { OS: "android", Version: 31, constants: { Release: "12" } },
+  Dimensions: {
+    get: () => ({ width: 1080, height: 2400, scale: 3 }),
+  },
+}));
+
+import { UseSmileIDMetadataFactory } from "../use_smile_id_metadata_factory";
+
+describe("device_os on Android", () => {
+  it("reports the release version, not the API level", () => {
+    const factory = new UseSmileIDMetadataFactory();
+
+    expect(factory.make().toFields().deviceOs).toBe("Android 12");
+  });
+});

package/src/metadata/__tests__/metadata_golden_fixture.json

@@ -0,0 +1,13 @@
+{
+  "_comment": "Shared cross-SDK golden parity vectors. These metadata keys must serialise to the EXACT same wire value on Android, iOS, Flutter, and React Native for the standard fully-populated golden snapshot. Each SDK's metadata-payload golden test asserts its payload contains every entry below verbatim. Maintained manually — keep the four copies (android/ios/flutter/react-native-expo test dirs) in sync.",
+  "expected": {
+    "sdk_version": "12.0.1",
+    "proxy": "true",
+    "proximity_sensor": "true",
+    "sdk_config_source": "sdk_config",
+    "battery_status": "0",
+    "sdk_launch_count": "5",
+    "vpn": "false",
+    "privileges": "{\"1\":\"100010\",\"8\":\"100100\"}"
+  }
+}

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

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  UseSmileIDMetadata,
+  type UseSmileIDMetadataFields,
+} from "../use_smile_id_metadata";
+import goldenFixture from "./metadata_golden_fixture.json";
+
+/**
+ * Golden check that a fully-populated `UseSmileIDMetadata` emits the device-context payload with the
+ * right value shapes, and that a default snapshot emits only the always-present keys.
+ *
+ * Capture-telemetry / document-origin / config-object keys ride as flow-manager `extraEntries`
+ * (verified in `document_flow_navigation.test.ts`); this suite covers the field-based device-context
+ * keys, using the same inputs/expected values as the sibling Android / iOS / Flutter golden suites.
+ */
+describe("metadata payload (golden, device-context fields)", () => {
+  function fullyPopulated(): UseSmileIDMetadataFields {
+    return {
+      sdkVersion: "12.0.1",
+      sdk: "react-native-expo",
+      deviceOs: "Android 14",
+      deviceModel: "Google Pixel 8",
+      appName: "TestApp",
+      sessionId: "session-123",
+      clientIp: "192.168.1.5",
+      networkConnection: "wifi",
+      carrierInfo: "MTN",
+      proxy: true,
+      timezone: "Africa/Lagos",
+      locale: "en_NG",
+      screenResolution: "1080x2400",
+      memoryInfoMb: 7777,
+      deviceOrientation: "portrait",
+      systemArchitecture: "arm64-v8a",
+      numberOfCameras: 3,
+      hostApplication: "TestApp v1.2",
+      proximitySensor: true,
+      securityPolicyVersion: "12.0.0",
+      sdkConfigSource: "sdk_config",
+      imageWidth: 480,
+      imageHeight: 640,
+      livenessImageWidth: 320,
+      livenessImageHeight: 240,
+      timezoneOffsetMinutes: 60,
+      buildBrand: "Google",
+      buildDevice: "husky",
+      buildFingerprint: "google/husky:14",
+      buildProduct: "husky",
+      buildHardware: "husky",
+      buildSource: "com.android.vending",
+      packageName: "com.partner.app",
+      fingerprint: "android-id-123",
+      localTimeOfEnrolment: "2026-06-24T10:00:00.000+03:00",
+      batteryStatus: 0,
+      vpn: false,
+      certificateDigest: ["AA:BB", "CC:DD"],
+      wrapperName: "react_native_expo",
+      wrapperVersion: "12.0.1",
+      sdkLaunchCount: 5,
+      geolocation: {
+        latitude: 1.5,
+        longitude: -2.5,
+        accuracy: "precise",
+        source: "gps",
+      },
+      privileges: '{"1":"100010","8":"100100"}',
+    };
+  }
+
+  function entriesOf(fields: UseSmileIDMetadataFields): Map<string, string> {
+    return new Map(
+      new UseSmileIDMetadata(fields).toEntries().map((e) => [e.name, e.value]),
+    );
+  }
+
+  // Field-based device-context keys the fully-populated payload must emit.
+  const expectedKeys = [
+    "sdk_version",
+    "sdk",
+    "device_os",
+    "device_model",
+    "app_name",
+    "session_id",
+    "proxy",
+    "proximity_sensor",
+    "sdk_config_source",
+    "client_ip",
+    "network_connection",
+    "carrier_info",
+    "timezone",
+    "locale",
+    "screen_resolution",
+    "device_orientation",
+    "system_architecture",
+    "host_application",
+    "security_policy_version",
+    "selfie_image_dimensions",
+    "liveness_image_dimensions",
+    "timezone_offset",
+    "memory_info",
+    "number_of_cameras",
+    "build_brand",
+    "build_device",
+    "build_fingerprint",
+    "build_product",
+    "build_hardware",
+    "build_source",
+    "package_name",
+    "fingerprint",
+    "local_time_of_enrolment",
+    "battery_status",
+    "vpn",
+    "certificate_digest",
+    "wrapper_name",
+    "wrapper_version",
+    "sdk_launch_count",
+    "geolocation",
+    "privileges",
+  ];
+
+  it("emits every expected device-context key", () => {
+    const map = entriesOf(fullyPopulated());
+    for (const key of expectedKeys) {
+      expect(map.has(key), `missing key: ${key}`).toBe(true);
+    }
+  });
+
+  it("emits scalar + meaningful-falsey + JSON-shaped values correctly", () => {
+    const map = entriesOf(fullyPopulated());
+    expect(map.get("sdk_version")).toBe("12.0.1");
+    expect(map.get("proxy")).toBe("true");
+    expect(map.get("battery_status")).toBe("0"); // 0 is meaningful
+    expect(map.get("sdk_config_source")).toBe("sdk_config");
+    expect(map.get("wrapper_name")).toBe("react_native_expo");
+    expect(map.get("privileges")).toBe('{"1":"100010","8":"100100"}'); // verbatim
+    expect(map.get("vpn")).toBe("false"); // false is meaningful
+    expect(map.get("fingerprint")).toBe("android-id-123");
+    expect(map.get("package_name")).toBe("com.partner.app");
+    expect(JSON.parse(map.get("certificate_digest")!)).toEqual([
+      "AA:BB",
+      "CC:DD",
+    ]);
+    expect(JSON.parse(map.get("geolocation")!).accuracy).toBe("precise");
+  });
+
+  it("matches the cross-SDK parity fixture values", () => {
+    const map = entriesOf(fullyPopulated());
+    for (const [key, value] of Object.entries(goldenFixture.expected)) {
+      expect(map.get(key), `cross-SDK parity mismatch for ${key}`).toBe(value);
+    }
+  });
+
+  it("default snapshot emits only the always-present keys", () => {
+    const minimal: UseSmileIDMetadataFields = {
+      sdkVersion: "12.0.1",
+      sdk: "react-native-expo",
+      deviceOs: "Android 14",
+      deviceModel: "",
+      appName: "App",
+      sessionId: "s",
+      clientIp: "",
+      networkConnection: "",
+      carrierInfo: "",
+      timezone: "",
+      locale: "",
+      screenResolution: "",
+      memoryInfoMb: 0,
+      deviceOrientation: "",
+      systemArchitecture: "",
+      numberOfCameras: 0,
+      hostApplication: "",
+      securityPolicyVersion: "",
+      sdkConfigSource: "default",
+      imageWidth: 0,
+      imageHeight: 0,
+      livenessImageWidth: 0,
+      livenessImageHeight: 0,
+    };
+    const keys = new Set(entriesOf(minimal).keys());
+    // device_model is "" here so it omits; the rest of the required identity keys + source.
+    expect(keys.has("sdk_version")).toBe(true);
+    expect(keys.has("sdk_config_source")).toBe(true);
+    // Never-measured booleans → omitted rather than an inaccurate false.
+    expect(keys.has("proxy")).toBe(false);
+    expect(keys.has("proximity_sensor")).toBe(false);
+    // Optionals absent → omitted.
+    expect(keys.has("build_brand")).toBe(false);
+    expect(keys.has("geolocation")).toBe(false);
+    expect(keys.has("privileges")).toBe(false);
+    expect(keys.has("battery_status")).toBe(false);
+  });
+});

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

@@ -18,11 +18,12 @@ import { UseSmileIDMetadataFactory } from "../use_smile_id_metadata_factory";
 import type { SdkConfig } from "../../data/model/sdk_config";
 import { SdkConfigSource } from "../../data/model/sdk_config_source";
 
-// Minimum baseline — every conditional field empty / zero. The
-// only fields that survive `toEntries()` from this fixture are the
-// truly-always-present ones (SDK constants, sessionId, booleans, sdk_config_source).
+// Minimum baseline — every conditional field empty / zero and the measured
+// booleans (proxy, proximitySensor) left undefined. The only fields that
+// survive `toEntries()` from this fixture are the truly-always-present ones
+// (SDK constants, sessionId, sdk_config_source).
 const baseFields: UseSmileIDMetadataFields = Object.freeze({
-  sdkVersion: "12.0.0",
+  sdkVersion: "12.0.1",
   sdk: "react-native-expo",
   deviceOs: "",
   deviceModel: "",
@@ -31,7 +32,6 @@ const baseFields: UseSmileIDMetadataFields = Object.freeze({
   clientIp: "",
   networkConnection: "",
   carrierInfo: "",
-  proxy: false,
   timezone: "",
   locale: "",
   screenResolution: "",
@@ -40,21 +40,23 @@ const baseFields: UseSmileIDMetadataFields = Object.freeze({
   systemArchitecture: "",
   numberOfCameras: 0,
   hostApplication: "",
-  proximitySensor: false,
   securityPolicyVersion: "12.0.0",
   // sdk_config provenance — always-present (non-empty by construction).
   sdkConfigSource: SdkConfigSource.defaultSource,
   // Dimensions — zero in baseline fixture → omitted from entries.
   imageWidth: 0,
   imageHeight: 0,
+  livenessImageWidth: 0,
+  livenessImageHeight: 0,
 });
 
 describe("UseSmileIDMetadata.toEntries — standardized multipart wire format", () => {
   it("always emits the always-present fields, including device_os / device_model / app_name even when empty", () => {
     // `device_os`, `device_model`, and `app_name` are part of the
     // always-present field set: they are emitted unconditionally (even
-    // when empty), alongside the SDK constants, the session UUID, and
-    // the booleans. `sdk_config_source` is also always-present.
+    // when empty), alongside the SDK constants and the session UUID.
+    // `sdk_config_source` is also always-present. The measured booleans
+    // (proxy, proximity_sensor) are undefined in the baseline → omitted.
     const meta = new UseSmileIDMetadata(baseFields);
     const names = meta.toEntries().map((e) => e.name);
     expect(names).toEqual([
@@ -64,8 +66,6 @@ describe("UseSmileIDMetadata.toEntries — standardized multipart wire format",
       "device_model",
       "app_name",
       "session_id",
-      "proxy",
-      "proximity_sensor",
       "security_policy_version",
       "sdk_config_source",
     ]);
@@ -88,8 +88,6 @@ describe("UseSmileIDMetadata.toEntries — standardized multipart wire format",
       "device_model",
       "app_name",
       "session_id",
-      "proxy",
-      "proximity_sensor",
       "security_policy_version",
       "sdk_config_source",
     ]);
@@ -122,7 +120,7 @@ describe("UseSmileIDMetadata.toEntries — standardized multipart wire format",
     expect(names).not.toContain("number_of_cameras");
   });
 
-  it("emits non-empty conditionals between the booleans and the trailer", () => {
+  it("emits non-empty conditionals between the identity block and the trailer", () => {
     const meta = new UseSmileIDMetadata({
       ...baseFields,
       // Populate the upper-conditional triple so the canonical
@@ -143,8 +141,6 @@ describe("UseSmileIDMetadata.toEntries — standardized multipart wire format",
       "device_model",
       "app_name",
       "session_id",
-      "proxy",
-      "proximity_sensor",
       "timezone",
       "locale",
       "memory_info",
@@ -267,10 +263,10 @@ describe("UseSmileIDMetadataFactory", () => {
     expect(names).toContain("app_name");
     // sdk_config_source is always-present (non-empty string by construction).
     expect(names).toContain("sdk_config_source");
-    // image_width / image_height are emitted when > 0.
+    // Selfie + liveness dimensions are emitted as "WxH" when both sides > 0.
     // Factory defaults to 480 × 640 so they appear without an sdkConfig override.
-    expect(names).toContain("image_width");
-    expect(names).toContain("image_height");
+    expect(names).toContain("selfie_image_dimensions");
+    expect(names).toContain("liveness_image_dimensions");
   });
 });
 
@@ -372,7 +368,7 @@ describe("UseSmileIDMetadata.toEntries — sdk_config provenance", () => {
     expect(valueByName(meta).sdk_config_source).toBe("sdk_config");
   });
 
-  it("emits image_width and image_height when > 0", () => {
+  it("emits selfie_image_dimensions as WxH when both sides > 0", () => {
     const values = valueByName(
       new UseSmileIDMetadata({
         ...baseFields,
@@ -381,18 +377,16 @@ describe("UseSmileIDMetadata.toEntries — sdk_config provenance", () => {
         imageHeight: 480,
       }),
     );
-    expect(values["image_width"]).toBe("640");
-    expect(values["image_height"]).toBe("480");
+    expect(values["selfie_image_dimensions"]).toBe("640x480");
   });
 
-  it("omits image_width and image_height when zero (fallback to SDK defaults not set)", () => {
-    // baseFields has imageWidth: 0 / imageHeight: 0 — these must be absent
+  it("omits selfie_image_dimensions when a side is zero (fallback to SDK defaults not set)", () => {
+    // baseFields has imageWidth: 0 / imageHeight: 0 — the "WxH" key must be absent
     // from the wire payload so the server doesn't see an explicit zero.
     const names = new UseSmileIDMetadata(baseFields)
       .toEntries()
       .map((e) => e.name);
-    expect(names).not.toContain("image_width");
-    expect(names).not.toContain("image_height");
+    expect(names).not.toContain("selfie_image_dimensions");
   });
 });
 

package/src/metadata/builder_configuration.ts

@@ -0,0 +1,69 @@
+/**
+ * Snapshot of the partner's structural SDK configuration, derived from the
+ * flow they assembled through the Builder DSL and appended to a job request as
+ * the `builder_configuration_object` entry. Lets the server correlate fraud
+ * signals with how the SDK was set up.
+ *
+ * Build instances with `flowConfigurationToBuilderConfiguration`.
+ */
+
+/**
+ * Intrinsic pixel dimensions of the partner-supplied consent icon. On React
+ * Native the consent icon is a `ReactNode` with no measurable pixel size at
+ * configuration time, so this is currently always reported as `null`.
+ */
+export type ConsentIconDimensions = {
+  readonly width: number;
+  readonly height: number;
+};
+
+export type BuilderConfiguration = {
+  readonly consentScreenUsed: boolean;
+  readonly consentIconProvided: boolean;
+  readonly consentIconDimensions: ConsentIconDimensions | null;
+  readonly consentAttributionShown: boolean;
+  readonly instructionsScreenUsed: boolean;
+  readonly selfiePreviewEnabled: boolean;
+  readonly documentPreviewEnabled: boolean;
+  readonly submissionSkipped: boolean;
+  readonly allowAgentMode: boolean;
+  readonly enhancedLivenessEnabled: boolean;
+  readonly autoCaptureEnabled: string;
+  readonly allowGalleryUpload: boolean;
+  readonly captureBothSides: boolean;
+  readonly allowSkipBack: boolean;
+  /**
+   * Partner-declared GPC posture ("opt-out" / "opt-in") — the consent
+   * layout every session ran under.
+   */
+  readonly globalPrivacyControl: string;
+};
+
+/**
+ * Serialises a [BuilderConfiguration] to its snake_case wire object, emitting
+ * `consent_icon_dimensions` as explicit `null` when no dimensions are available.
+ */
+export function builderConfigurationToJson(
+  configuration: BuilderConfiguration,
+): Record<string, unknown> {
+  const dimensions = configuration.consentIconDimensions;
+  return {
+    consent_screen_used: configuration.consentScreenUsed,
+    consent_icon_provided: configuration.consentIconProvided,
+    consent_icon_dimensions: dimensions
+      ? { width: dimensions.width, height: dimensions.height }
+      : null,
+    consent_attribution_shown: configuration.consentAttributionShown,
+    instructions_screen_used: configuration.instructionsScreenUsed,
+    selfie_preview_enabled: configuration.selfiePreviewEnabled,
+    document_preview_enabled: configuration.documentPreviewEnabled,
+    submission_skipped: configuration.submissionSkipped,
+    allow_agent_mode: configuration.allowAgentMode,
+    enhanced_liveness_enabled: configuration.enhancedLivenessEnabled,
+    auto_capture_enabled: configuration.autoCaptureEnabled,
+    allow_gallery_upload: configuration.allowGalleryUpload,
+    capture_both_sides: configuration.captureBothSides,
+    allow_skip_back: configuration.allowSkipBack,
+    global_privacy_control: configuration.globalPrivacyControl,
+  };
+}

package/src/metadata/captured_image_properties.ts

@@ -0,0 +1,10 @@
+/**
+ * Fixed image properties for the captured artifacts, emitted as `*_image_color_depth` and
+ * `*_image_pixel_config`.
+ *
+ * These describe the submitted artifact — a baseline JPEG (3-channel RGB, no alpha) — not the
+ * 32-bit RGBA bitmap it decodes to in memory. Per-image byte sizes (`*_original_size` /
+ * `*_final_compressed_size`) are measured in the repository around the compression pass.
+ */
+export const CAPTURE_IMAGE_COLOR_DEPTH = 24;
+export const CAPTURE_IMAGE_PIXEL_CONFIG = "RGB_888";

package/src/metadata/device_orientation_collector.ts

@@ -0,0 +1,75 @@
+import {
+  loadExpoSensors,
+  type AccelerometerSubscription,
+} from "./optional_native_modules";
+
+/**
+ * Samples the accelerometer during capture for two metadata signals:
+ * - `device_positions`: `"epochMs,x,y,z"` samples throttled to ~15 Hz, capped at
+ *   {@link MAX_DURATION_MS} to bound payload size.
+ * - `device_movement_detected`: the span (max − min) of movement magnitude
+ *   (`|‖accel‖ − gravity|`, in g) across the session, or `null` when no samples ran.
+ *
+ * The `expo-sensors` subscription lives only between {@link start} and {@link stop}
+ * (tied to the capture screen lifecycle). When `expo-sensors` isn't installed the
+ * collector silently no-ops and the keys are omitted.
+ */
+const SAMPLE_INTERVAL_MS = Math.floor(1000 / 15);
+const MAX_DURATION_MS = 90 * 1000;
+// expo-sensors reports acceleration in g; gravity is ~1 g (v11 parity value).
+const GRAVITY = 0.981;
+
+export class DeviceOrientationCollector {
+  private subscription: AccelerometerSubscription | null = null;
+  private positions: string[] = [];
+  private movements: number[] = [];
+  private startedAt = 0;
+  private lastSampleMs = 0;
+
+  /** Begins accelerometer sampling for a fresh capture session. No-op if running or unavailable. */
+  start(): void {
+    if (this.subscription) return;
+    const sensors = loadExpoSensors();
+    if (!sensors) return;
+    this.positions = [];
+    this.movements = [];
+    this.startedAt = Date.now();
+    this.lastSampleMs = 0;
+    sensors.Accelerometer.setUpdateInterval(SAMPLE_INTERVAL_MS);
+    this.subscription = sensors.Accelerometer.addListener((data) =>
+      this.onSample(data),
+    );
+  }
+
+  /** Stops sampling but preserves the collected data for the getters below. */
+  stop(): void {
+    this.subscription?.remove();
+    this.subscription = null;
+  }
+
+  private onSample(data: { x: number; y: number; z: number }): void {
+    const now = Date.now();
+    if (now - this.startedAt > MAX_DURATION_MS) {
+      this.stop();
+      return;
+    }
+    if (now - this.lastSampleMs < SAMPLE_INTERVAL_MS) return;
+    this.lastSampleMs = now;
+    this.positions.push(`${now},${data.x},${data.y},${data.z}`);
+    const magnitude = Math.sqrt(
+      data.x * data.x + data.y * data.y + data.z * data.z,
+    );
+    this.movements.push(Math.abs(magnitude - GRAVITY));
+  }
+
+  /** Collected `"epochMs,x,y,z"` samples (empty when no capture ran). */
+  get devicePositions(): readonly string[] {
+    return this.positions;
+  }
+
+  /** Span of movement magnitude across the session; `null` when no samples were collected. */
+  get deviceMovementDetected(): number | null {
+    if (this.movements.length === 0) return null;
+    return Math.max(...this.movements) - Math.min(...this.movements);
+  }
+}

package/src/metadata/geolocation.ts

@@ -0,0 +1,46 @@
+import { loadExpoLocation } from "./optional_native_modules";
+
+/**
+ * Coarse last-known location, emitted as the `geolocation` metadata (JSON-object string).
+ *
+ * `accuracy` is `precise` (<20 m), `approximate` (<100 m), or `unknown`; `source` is `gps`.
+ */
+export interface Geolocation {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy: string;
+  readonly source: string;
+}
+
+function classifyAccuracy(meters: number | null): string {
+  if (meters === null || meters <= 0) return "unknown";
+  if (meters < 20) return "precise";
+  if (meters < 100) return "approximate";
+  return "unknown";
+}
+
+/**
+ * Resolves the last-known location for the `geolocation` metadata — only when a location
+ * permission is **already** granted. The SDK never requests it (uses
+ * `getForegroundPermissionsAsync`, not `requestForegroundPermissionsAsync`), so this never
+ * prompts. Returns `null` when permission is absent, no cached fix exists, or `expo-location`
+ * isn't installed.
+ */
+export async function resolveGeolocation(): Promise<Geolocation | null> {
+  const location = loadExpoLocation();
+  if (!location) return null;
+  try {
+    const permission = await location.getForegroundPermissionsAsync();
+    if (!permission.granted) return null;
+    const position = await location.getLastKnownPositionAsync();
+    if (!position) return null;
+    return {
+      latitude: position.coords.latitude,
+      longitude: position.coords.longitude,
+      accuracy: classifyAccuracy(position.coords.accuracy),
+      source: "gps",
+    };
+  } catch {
+    return null;
+  }
+}