@smileid/usesmileid 12.0.1 → 12.1.0

package/src/metadata/use_smile_id_metadata_factory.ts

@@ -1,580 +0,0 @@
-import { Dimensions, Platform } from "react-native";
-import {
-  Attestation,
-  type DeviceIntegritySignals,
-  DeviceIntegrityProvider,
-  type HardwareAttestation,
-  PrivilegesProvider,
-} from "@smileid/usesmileid_bridge";
-import {
-  UseSmileIDMetadata,
-  type UseSmileIDMetadataFields,
-} from "./use_smile_id_metadata";
-import {
-  loadAsyncStorage,
-  loadExpoBattery,
-  loadExpoCellular,
-  loadExpoDevice,
-  loadExpoNetwork,
-} from "./optional_native_modules";
-import { type Geolocation, resolveGeolocation } from "./geolocation";
-import type { SdkConfig } from "../data/model/sdk_config";
-import { resolveDimensions } from "../data/model/sdk_config_capture";
-import { SdkConfigSource } from "../data/model/sdk_config_source";
-import { CameraDefaults } from "../camera/camera_defaults";
-
-/**
- * Metadata factory.
- *
- * **Lifecycle:**
- *   - **One factory per SDK session.** Construct once at flow start
- *     (the orchestrator owns it) — `sessionId` is generated here and
- *     reused across every submission within the flow.
- *   - **One `make()` per API request.** Static fields (device OS,
- *     model, system architecture, screen resolution, …) are resolved
- *     once at construction and cached. Dynamic fields (timezone,
- *     locale, device orientation) are re-resolved on every `make()`
- *     so a mid-flow rotation or locale change is captured.
- *
- * **What's resolved here today:**
- *   - Resolved synchronously from `react-native` core APIs at
- *     construction: `device_os`, `screen_resolution`,
- *     `device_orientation`, `timezone`, `locale`, `session_id`,
- *     `sdk_version`, `sdk`, `security_policy_version`.
- *   - Resolved synchronously from `expo-device` when present:
- *     `device_model`, `system_architecture`, `memory_info`.
- *   - Resolved asynchronously via fire-and-forget [warmup] from
- *     `expo-network` when present: `client_ip`, `network_connection`.
- *     The first [make] after construction may see empty defaults if
- *     warmup hasn't settled; every subsequent [make] sees the
- *     resolved values. Capture flows always take several seconds
- *     before the first submission so the race is benign in practice.
- *   - Partner-supplied via [MetadataFactoryOptions]: `app_name`,
- *     `host_application`.
- *   - Not measurable until a richer native bridge lands:
- *     `carrier_info` and `number_of_cameras` stay empty / zero (dropped
- *     from the wire), and `proximity_sensor` / `proxy` stay undefined
- *     (dropped from the wire) rather than reporting an inaccurate
- *     `false`. Partners who want these pass a custom
- *     `MetadataProvider` to the repository.
- */
-
-// Beta release version reported to the backend as `sdk_version`. Keep in sync
-// with the `version` field across the published package.json files.
-const SDK_VERSION = "12.0.1";
-// The security-policy axis is versioned independently of the SDK release tag,
-// so it stays at the base `12.0.0` (not the prerelease tag).
-const SECURITY_POLICY_VERSION = "12.0.0";
-const SDK_IDENTIFIER = "react-native-expo";
-const LAUNCH_COUNT_KEY = "com.usesmileid.metadata.sdk_launch_count";
-
-export interface MetadataProvider {
-  /**
-   * Build a metadata snapshot for a single submission.
-   *
-   * When `sdkConfig` is provided (the decoded `sdk_config` JWT claim),
-   * the snapshot includes:
-   *   - `sdk_config_source: "sdk_config"` — the backend gates its
-   *     dimension-consistency check on this value.
-   *   - `image_width` / `image_height` — the resolved selfie capture
-   *     dimensions (server override or SDK default of 480 × 640).
-   *
-   * When `sdkConfig` is absent, `sdk_config_source` is `"default"` and
-   * `image_width` / `image_height` reflect the SDK defaults.
-   */
-  make(sdkConfig?: SdkConfig): UseSmileIDMetadata;
-
-  /**
-   * Stable per-flow session identifier — used as the analytics
-   * events' `session_id` value and the storage session directory name.
-   */
-  readonly sessionId: string;
-}
-
-export type MetadataFactoryOptions = {
-  /**
-   * Override the partner's app name. Default is empty string — RN
-   * does not expose the host-app name without `expo-application` as
-   * a peer dep. Partners using `expo-application` typically pass
-   * `Application.applicationName` here.
-   */
-  readonly appName?: string;
-  /**
-   * Override the host-app version string (e.g. `'PartnerApp v1.2.3'`).
-   * Default empty.
-   */
-  readonly hostApplication?: string;
-};
-
-export class UseSmileIDMetadataFactory implements MetadataProvider {
-  // Cached static fields (resolved once at construction).
-  private readonly _sessionId: string;
-  private readonly _deviceOs: string;
-  private readonly _deviceModel: string;
-  private readonly _appName: string;
-  private readonly _hostApplication: string;
-  private readonly _systemArchitecture: string;
-  private readonly _memoryInfoMb: number;
-  // Build / device-context strings + carrier, resolved once at construction
-  // from expo-device / expo-cellular sync constants. Empty when the module is
-  // absent or the platform has no analog.
-  private readonly _buildBrand: string;
-  private readonly _buildDevice: string;
-  private readonly _buildFingerprint: string;
-  private readonly _buildProduct: string;
-  private readonly _carrierInfo: string;
-  // Resolved by the async warmup (expo-battery). Undefined until it settles —
-  // make() omits battery_status until then.
-  private _batteryStatus?: number;
-  // Persisted launch counter, resolved by the async warmup (async-storage).
-  // Undefined until it settles — make() omits sdk_launch_count until then.
-  private _sdkLaunchCount?: number;
-  // Last-known location, resolved by the async warmup (expo-location), only when a
-  // permission is already granted. Undefined until it settles / when denied.
-  private _geolocation?: Geolocation;
-  // Obfuscated device privileges JSON, resolved by the async warmup (native bridge).
-  // Undefined until it settles — make() omits the privileges field until then.
-  private _privileges?: string;
-  // Native device-integrity signals (fingerprint, package name, vpn, build hardware,
-  // install source, cert digests), resolved by the async warmup (native bridge).
-  // Undefined until it settles — make() omits the corresponding fields until then.
-  private _deviceIntegrity?: DeviceIntegritySignals;
-  // Mutated by [warmup] once the async expo-network calls settle.
-  // Mutable on purpose — the constructor cannot block on the
-  // async API, and reading stale `""` is preferable to forcing the
-  // orchestrator to await before mounting the camera.
-  private _clientIp = "";
-  private _networkConnection = "";
-  // Per-session device-integrity snapshot, set once the fire-and-forget
-  // hardware-attestation warm-up settles. Undefined until then — make()
-  // omits the attestation metadata fields.
-  private _hardwareAttestation?: HardwareAttestation;
-
-  constructor(options: MetadataFactoryOptions = {}) {
-    this._sessionId = generateSessionId();
-    this._deviceOs = resolveDeviceOs();
-    this._appName = options.appName ?? "";
-    this._hostApplication = options.hostApplication ?? "";
-
-    // `expo-device` is an optional peer dep — populate the richer
-    // fields when it's installed, fall back to empty / zero
-    // otherwise. The check happens ONCE at construction so the
-    // require-attempt is cached for the factory's lifetime; concrete
-    // scenario this prevents: a partner without `expo-device` would
-    // otherwise pay a fresh require-failure throw on every flow
-    // mount. The optional-modules helper caches `null` distinctly
-    // from `undefined` so re-attempts are skipped.
-    const device = loadExpoDevice();
-    if (device) {
-      const brand = device.brand?.trim() ?? "";
-      const model = device.modelName?.trim() ?? "";
-      // `<brand> <model>` shape (e.g. `"Apple iPhone 15"`) — the
-      // wire format the analytics pipeline expects.
-      this._deviceModel = [brand, model].filter(Boolean).join(" ");
-      this._systemArchitecture =
-        device.supportedCpuArchitectures?.[0]?.trim() ?? "";
-      // expo-device returns `totalMemory` in BYTES; the wire format
-      // expects MB.
-      this._memoryInfoMb =
-        typeof device.totalMemory === "number" && device.totalMemory > 0
-          ? Math.round(device.totalMemory / (1024 * 1024))
-          : 0;
-      this._buildBrand = device.brand?.trim() ?? "";
-      // Android `Build.DEVICE` vs iOS hardware identifier (e.g. iPhone16,2).
-      this._buildDevice =
-        (Platform.OS === "ios" ? device.modelId : device.designName)?.trim() ??
-        "";
-      this._buildFingerprint = device.osBuildFingerprint?.trim() ?? "";
-      this._buildProduct = device.productName?.trim() ?? "";
-    } else {
-      this._deviceModel = "";
-      this._systemArchitecture = "";
-      this._memoryInfoMb = 0;
-      this._buildBrand = "";
-      this._buildDevice = "";
-      this._buildFingerprint = "";
-      this._buildProduct = "";
-    }
-
-    // Carrier name from expo-cellular's sync constant (empty when absent).
-    this._carrierInfo = loadExpoCellular()?.carrier?.trim() ?? "";
-
-    // Fire-and-forget warmup of the async network fields. The
-    // promise is intentionally unawaited — capture flows take
-    // several seconds before the first `make()`, by which time
-    // `getNetworkStateAsync()` (typically ~10–50 ms on device) has
-    // long since settled. Any rejection is swallowed: partners
-    // without `expo-network` get empty defaults, never a thrown
-    // error.
-    void this._warmupAsync();
-
-    // Fire-and-forget hardware-attestation probe, bound to this
-    // session id. Unawaited for the same reason as the network warmup;
-    // make() omits the attestation fields until it settles.
-    void this._warmUpHardwareAttestation();
-  }
-
-  /**
-   * Stable per-flow session identifier. Used as the storage session
-   * directory name, the analytics events' `session_id` value, and the
-   * Sentry user-id for crash-report correlation (see
-   * `UseSmileIDCrashReporting.setUserId`).
-   */
-  get sessionId(): string {
-    return this._sessionId;
-  }
-
-  /**
-   * Resolve the async `expo-network` fields into the cache. Called
-   * from the constructor as fire-and-forget; partners can also
-   * `await` it explicitly when they want to guarantee populated
-   * network fields on the first submission.
-   */
-  async warmup(): Promise<void> {
-    return this._warmupAsync();
-  }
-
-  private async _warmupAsync(): Promise<void> {
-    const network = loadExpoNetwork();
-    if (!network) return;
-    // Run both calls concurrently — they're independent and the
-    // factory does not need either's result to handle the other.
-    const stateResult = network
-      .getNetworkStateAsync()
-      .then((state) => {
-        this._networkConnection = (state.type ?? "").toString();
-      })
-      .catch(() => {
-        /* leave the cached empty string */
-      });
-    const ipResult = network.getIpAddressAsync
-      ? network
-          .getIpAddressAsync()
-          .then((ip) => {
-            this._clientIp = ip ?? "";
-          })
-          .catch(() => {
-            /* leave the cached empty string */
-          })
-      : Promise.resolve();
-    await Promise.all([
-      stateResult,
-      ipResult,
-      this._warmUpBatteryStatus(),
-      this._warmUpLaunchCount(),
-      this._warmUpGeolocation(),
-      this._warmUpPrivileges(),
-      this._warmUpDeviceIntegrity(),
-    ]);
-  }
-
-  /**
-   * Resolve the last-known location (expo-location) into the cache — only when a permission
-   * is already granted (never prompts). Fail-open: leaves `_geolocation` unset otherwise.
-   */
-  private async _warmUpGeolocation(): Promise<void> {
-    const geolocation = await resolveGeolocation();
-    if (geolocation) this._geolocation = geolocation;
-  }
-
-  /**
-   * Resolve the obfuscated device privileges signal from the native bridge into the cache.
-   * Fail-open: `PrivilegesProvider` returns `"{}"` when the native module is unavailable.
-   */
-  private async _warmUpPrivileges(): Promise<void> {
-    const privileges = await PrivilegesProvider.privileges();
-    if (privileges.length > 0) this._privileges = privileges;
-  }
-
-  /**
-   * Resolve the native device-integrity signals (fingerprint, package name, vpn, build
-   * hardware, install source, cert digests) from the bridge into the cache. Fail-open:
-   * `DeviceIntegrityProvider` returns empty/undefined values when the native module is absent.
-   */
-  private async _warmUpDeviceIntegrity(): Promise<void> {
-    this._deviceIntegrity = await DeviceIntegrityProvider.signals();
-  }
-
-  /**
-   * Read, increment, and persist the SDK launch counter via async-storage.
-   * Fail-open: leaves `_sdkLaunchCount` unset when the package is absent.
-   */
-  private async _warmUpLaunchCount(): Promise<void> {
-    const store = loadAsyncStorage();
-    if (!store) return;
-    try {
-      const current = Number(await store.getItem(LAUNCH_COUNT_KEY)) || 0;
-      const next = current + 1;
-      await store.setItem(LAUNCH_COUNT_KEY, String(next));
-      this._sdkLaunchCount = next;
-    } catch {
-      /* leave _sdkLaunchCount unset */
-    }
-  }
-
-  /**
-   * Resolve the charging state (expo-battery) into the cache, mapped to the
-   * cross-platform plug status: `-1` unknown, `0` on battery, `1` plugged in.
-   * Fail-open: leaves `_batteryStatus` unset when the module is absent.
-   */
-  private async _warmUpBatteryStatus(): Promise<void> {
-    const battery = loadExpoBattery();
-    if (!battery) return;
-    try {
-      // expo-battery BatteryState: 0 unknown, 1 unplugged, 2 charging, 3 full.
-      const state = await battery.getBatteryStateAsync();
-      switch (state) {
-        case 1:
-          this._batteryStatus = 0;
-          break;
-        case 2:
-        case 3:
-          this._batteryStatus = 1;
-          break;
-        default:
-          this._batteryStatus = -1;
-      }
-    } catch {
-      /* leave _batteryStatus unset */
-    }
-  }
-
-  /**
-   * Resolve the per-session hardware-attestation snapshot. Called from the
-   * constructor as fire-and-forget. Android mints a Keystore-backed key
-   * (challenge `SHA-256(sessionId)`); iOS reports App Attest support.
-   */
-  private async _warmUpHardwareAttestation(): Promise<void> {
-    try {
-      this._hardwareAttestation = await Attestation.generateHardwareAttestation(
-        this._sessionId,
-      );
-    } catch {
-      // Fail-open: the native module may be absent (pure-JS test) or the
-      // probe may fail; leave the snapshot unset so make() omits the fields.
-    }
-  }
-
-  /** Build a metadata snapshot for a single submission. */
-  make(sdkConfig?: SdkConfig): UseSmileIDMetadata {
-    // Android carries the Keystore security level + cert chain; iOS carries
-    // the App Attest capability. The shared snapshot encodes both; pick the
-    // platform-appropriate fields so an iOS job never ships the Android
-    // Keystore field (which the server parses as a numeric security level).
-    // `exactOptionalPropertyTypes` — spread the optional fields in only when
-    // present rather than assigning `undefined`.
-    const hardware = this._hardwareAttestation;
-    const androidAttestation =
-      Platform.OS === "android" && hardware
-        ? {
-            hardwareAttestationSecurityLevel: hardware.securityLevel,
-            ...(hardware.certificateChain &&
-            hardware.certificateChain.length > 0
-              ? { attestationCertificateChain: hardware.certificateChain }
-              : {}),
-          }
-        : {};
-    const iosAttestation =
-      Platform.OS === "ios" && hardware
-        ? { supportsAppAttest: hardware.supportsAppAttest }
-        : {};
-
-    // Resolve sdk_config provenance and selfie dimensions for metadata.
-    // The backend gates its dimension-consistency check on sdk_config_source,
-    // so this value must match whether a claim was actually applied.
-    const selfieDims = resolveDimensions(sdkConfig?.selfie);
-    const sdkConfigSource =
-      sdkConfig !== undefined
-        ? SdkConfigSource.sdkConfig
-        : SdkConfigSource.defaultSource;
-    const imageWidth =
-      selfieDims?.width ?? CameraDefaults.selfieJpegTargetWidth;
-    const imageHeight =
-      selfieDims?.height ?? CameraDefaults.selfieJpegTargetHeight;
-    // Liveness frames use the same capture target as the selfie (480x640); the sdk_config
-    // liveness group overrides it when present.
-    const livenessDims = resolveDimensions(sdkConfig?.liveness);
-    const livenessImageWidth =
-      livenessDims?.width ?? CameraDefaults.selfieJpegTargetWidth;
-    const livenessImageHeight =
-      livenessDims?.height ?? CameraDefaults.selfieJpegTargetHeight;
-
-    const fields: UseSmileIDMetadataFields = {
-      sdkVersion: SDK_VERSION,
-      sdk: SDK_IDENTIFIER,
-      deviceOs: this._deviceOs,
-      deviceModel: this._deviceModel,
-      appName: this._appName,
-      sessionId: this._sessionId,
-      clientIp: this._clientIp,
-      networkConnection: this._networkConnection,
-      carrierInfo: this._carrierInfo,
-      // proxy / proximitySensor are not measurable without a native bridge;
-      // leaving them undefined keeps the keys off the wire rather than
-      // reporting an inaccurate false.
-      // Dynamic — re-resolved per submission so mid-flow changes
-      // (rotation, locale switch) are captured.
-      timezone: resolveTimezone(),
-      timezoneOffsetMinutes: resolveTimezoneOffsetMinutes(),
-      locale: resolveLocale(),
-      screenResolution: resolveScreenResolution(),
-      memoryInfoMb: this._memoryInfoMb,
-      deviceOrientation: resolveDeviceOrientation(),
-      systemArchitecture: this._systemArchitecture,
-      numberOfCameras: 0,
-      hostApplication: this._hostApplication,
-      securityPolicyVersion: SECURITY_POLICY_VERSION,
-      ...androidAttestation,
-      ...iosAttestation,
-      sdkConfigSource,
-      imageWidth,
-      imageHeight,
-      livenessImageWidth,
-      livenessImageHeight,
-      buildBrand: this._buildBrand,
-      buildDevice: this._buildDevice,
-      buildFingerprint: this._buildFingerprint,
-      buildProduct: this._buildProduct,
-      buildHardware: this._deviceIntegrity?.buildHardware ?? "",
-      buildSource: this._deviceIntegrity?.buildSource ?? "",
-      packageName: this._deviceIntegrity?.packageName ?? "",
-      fingerprint: this._deviceIntegrity?.fingerprint ?? "",
-      localTimeOfEnrolment: resolveLocalTimeOfEnrolment(),
-      wrapperName: "react_native_expo",
-      wrapperVersion: SDK_VERSION,
-      ...(this._deviceIntegrity?.vpn !== undefined
-        ? { vpn: this._deviceIntegrity.vpn }
-        : {}),
-      ...(this._deviceIntegrity?.certificateDigest !== undefined
-        ? { certificateDigest: this._deviceIntegrity.certificateDigest }
-        : {}),
-      ...(this._batteryStatus !== undefined
-        ? { batteryStatus: this._batteryStatus }
-        : {}),
-      ...(this._sdkLaunchCount !== undefined
-        ? { sdkLaunchCount: this._sdkLaunchCount }
-        : {}),
-      ...(this._geolocation !== undefined
-        ? { geolocation: this._geolocation }
-        : {}),
-      ...(this._privileges !== undefined
-        ? { privileges: this._privileges }
-        : {}),
-    };
-    return new UseSmileIDMetadata(fields);
-  }
-}
-
-// --- field resolvers --------------------------------------------------------
-
-function resolveDeviceOs(): string {
-  // `"iOS 17.4"` / `"Android 12"` — the shape the native EXIF tagger stamps.
-  const platform =
-    Platform.OS === "ios"
-      ? "iOS"
-      : Platform.OS === "android"
-        ? "Android"
-        : Platform.OS;
-  const version = resolveOsVersion();
-  return version ? `${platform} ${version}` : platform;
-}
-
-function resolveOsVersion(): string {
-  if (Platform.OS === "android") {
-    const release = (
-      Platform.constants as { Release?: string | number } | undefined
-    )?.Release;
-    if (release !== undefined && release !== null && `${release}` !== "") {
-      return `${release}`;
-    }
-  }
-  return typeof Platform.Version !== "undefined"
-    ? String(Platform.Version)
-    : "";
-}
-
-function resolveLocalTimeOfEnrolment(): string {
-  try {
-    return new Date().toISOString();
-  } catch {
-    return "";
-  }
-}
-
-function resolveTimezone(): string {
-  try {
-    return Intl.DateTimeFormat().resolvedOptions().timeZone ?? "";
-  } catch {
-    return "";
-  }
-}
-
-/**
- * Current device offset from UTC in minutes (negative west of UTC). `Date.getTimezoneOffset`
- * returns minutes *behind* UTC (positive west), so negate it to report the UTC offset.
- */
-function resolveTimezoneOffsetMinutes(): number {
-  return -new Date().getTimezoneOffset();
-}
-
-function resolveLocale(): string {
-  try {
-    return Intl.DateTimeFormat().resolvedOptions().locale ?? "";
-  } catch {
-    return "";
-  }
-}
-
-function resolveScreenResolution(): string {
-  try {
-    const { width, height, scale } = Dimensions.get("screen");
-    if (!width || !height) return "";
-    // Physical pixels (dp × scale), formatted as `<width> × <height>`
-    // with the U+00D7 multiplication sign.
-    const pixelWidth = Math.round(width * (scale || 1));
-    const pixelHeight = Math.round(height * (scale || 1));
-    return `${pixelWidth} × ${pixelHeight}`;
-  } catch {
-    return "";
-  }
-}
-
-function resolveDeviceOrientation(): string {
-  try {
-    const { width, height } = Dimensions.get("window");
-    if (!width || !height) return "";
-    return height >= width ? "Portrait" : "Landscape";
-  } catch {
-    return "";
-  }
-}
-
-/**
- * Generate a session-stable identifier. Prefers `crypto.randomUUID`
- * (Hermes 0.79+ / RN 0.76+) and falls back to a Math.random-based
- * UUID-like for older runtimes. The fallback is NOT
- * cryptographically random — that's acceptable here because the
- * session ID's purpose is correlation, not security.
- */
-export function generateSessionId(): string {
-  const cryptoApi = (globalThis as { crypto?: { randomUUID?: () => string } })
-    .crypto;
-  if (cryptoApi && typeof cryptoApi.randomUUID === "function") {
-    return cryptoApi.randomUUID();
-  }
-  // Fallback: standard UUID v4 generated from Math.random.
-  // Matches the canonical 8-4-4-4-12 layout.
-  const hex = (n: number) => n.toString(16);
-  const rand = () => Math.floor(Math.random() * 0x10000);
-  return [
-    hex(rand()) + hex(rand()),
-    hex(rand()),
-    // Set the version nibble to 4 (UUID v4)
-    "4" + hex(rand()).slice(-3),
-    // Set the variant bits to 10xx
-    hex((rand() & 0x3fff) | 0x8000),
-    hex(rand()) + hex(rand()) + hex(rand()),
-  ]
-    .map((s) => s.padStart(s.length === 4 ? 4 : s.length === 12 ? 12 : 4, "0"))
-    .join("-");
-}