@smileid/usesmileid 12.0.0-beta01

package/src/data/factory/__tests__/networking_factory_order.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
+
+import { JobType } from "../../../core/models/job_type";
+import type {
+  Interceptor,
+  NetworkConfig,
+} from "../../../core/models/network_config";
+import { LogLevel } from "../../../core/models/network_config";
+import { makeNetworkingFactory } from "../networking_factory";
+import { MissingPartnerConfigException } from "../../../core/exception";
+
+/**
+ * Locks down the canonical interceptor chain order built by
+ * `makeNetworkingFactory`:
+ *
+ *   `partner-custom → auth → logging → wire`
+ *
+ * axios applies request interceptors LIFO (last registered runs
+ * first on the request), so the factory registers in reverse:
+ * `logging → auth → partner-custom`. The behavioural assertion below
+ * fires a real request through a mock adapter and watches what each
+ * interceptor observes — it doesn't peek at axios internals.
+ *
+ * A regression that swaps the registration order would surface here
+ * in two ways:
+ *  - the partner-custom interceptor would see auth-stamped headers
+ *    (security regression — partner code can read the token);
+ *  - or the auth interceptor would never stamp the request because a
+ *    different interceptor short-circuited it first.
+ */
+describe("NetworkingFactory interceptor order", () => {
+  it("partner-custom interceptors observe pre-auth requests", async () => {
+    const partnerObserved: Array<Record<string, unknown>> = [];
+    let wireObserved: Record<string, unknown> | undefined;
+
+    const config = makeBaseConfig({
+      // Partner-custom interceptor: records the headers it sees on
+      // the request path. Because it's registered last (and axios
+      // runs request interceptors LIFO), it runs FIRST on the
+      // request path — before SmileAuthInterceptor stamps headers.
+      interceptors: [
+        {
+          attach(client: AxiosInstance) {
+            client.interceptors.request.use((requestConfig) => {
+              partnerObserved.push({
+                ...(requestConfig.headers as unknown as Record<
+                  string,
+                  unknown
+                >),
+              });
+              return requestConfig;
+            });
+          },
+        },
+      ],
+    });
+
+    const { client, api } = makeNetworkingFactory(config, () => "test-secret");
+
+    // Install a wire-level adapter LAST so we observe what the
+    // server would actually receive (post-auth, post-logging).
+    client.defaults.adapter = (requestConfig: InternalAxiosRequestConfig) => {
+      wireObserved = {
+        ...(requestConfig.headers as unknown as Record<string, unknown>),
+      };
+      return Promise.resolve({
+        status: 200,
+        statusText: "OK",
+        data: { jobId: "job-test-1" },
+        headers: {},
+        config: requestConfig,
+      });
+    };
+
+    // Use the API surface to trigger a request — sidestep the
+    // multipart machinery by hitting any GET-shaped endpoint via
+    // the underlying axios client directly. The fake adapter
+    // intercepts before any real network IO.
+    void api; // referenced to keep the API in scope; the wire goes through `client`
+    await client.get("/v3/test");
+
+    // Wire-level (after all interceptors): auth stamps SmileID-Token.
+    expect(wireObserved).toBeDefined();
+    const wireKeys = new Set(
+      Object.keys(wireObserved ?? {}).map((k) => k.toLowerCase()),
+    );
+    expect(wireKeys.has("smileid-token")).toBe(true);
+
+    // Partner-custom (registered last, runs first on the request):
+    // sees the request BEFORE auth stamps any token. Partner code
+    // therefore cannot read or strip the partner token, which is the
+    // security property the chain order encodes.
+    expect(partnerObserved.length).toBeGreaterThan(0);
+    const partnerKeys = new Set(
+      Object.keys(partnerObserved[0] ?? {}).map((k) => k.toLowerCase()),
+    );
+    expect(partnerKeys.has("smileid-token")).toBe(false);
+  });
+
+  it("logging interceptor sees the fully-stamped request (post-auth)", async () => {
+    // The logging interceptor is registered FIRST (so it runs LAST
+    // on the request path, just before the wire). The behavioural
+    // check: the line it prints contains an `smileid-token` entry
+    // (redaction-masked, but key still present). This is what
+    // partners see when they enable LogLevel.headers in production.
+    // Capture every argument passed to console.log without coercing
+    // — the logging interceptor passes the headers map as a second
+    // arg (an object). String coercion would turn it into
+    // "[object Object]" and lose the test signal.
+    const printedArgs: unknown[][] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      printedArgs.push(args);
+    };
+    try {
+      const config = makeBaseConfig({ logLevel: LogLevel.headers });
+      const { client } = makeNetworkingFactory(config, () => "test-secret");
+      client.defaults.adapter = (requestConfig: InternalAxiosRequestConfig) =>
+        Promise.resolve({
+          status: 200,
+          statusText: "OK",
+          data: {},
+          headers: {},
+          config: requestConfig,
+        });
+      await client.get("/v3/test");
+    } finally {
+      console.log = originalLog;
+    }
+
+    // Find the request-headers log call. Its shape is
+    // `[usesmileid]   headers:`, then the redacted-headers object.
+    const headersCall = printedArgs.find(
+      (args) =>
+        typeof args[0] === "string" &&
+        (args[0] as string).toLowerCase().includes("headers"),
+    );
+    expect(headersCall).toBeDefined();
+    const headersObject = headersCall![1] as Record<string, unknown>;
+    // Auth stamped the token; logging saw it, redaction masked the value.
+    const headersLower = new Map(
+      Object.entries(headersObject).map(([k, v]) => [k.toLowerCase(), v]),
+    );
+    expect(headersLower.has("smileid-token")).toBe(true);
+    expect(headersLower.get("smileid-token")).toBe("<redacted>");
+  });
+});
+
+describe("NetworkingFactory credential validation", () => {
+  it("throws MissingPartnerConfigException when partnerId is blank", () => {
+    const base = makeBaseConfig();
+    const bad: NetworkConfig = {
+      ...base,
+      config: {
+        ...base.config!,
+        partnerConfig: { ...base.config!.partnerConfig!, partnerId: "  " },
+      },
+    };
+    expect(() => makeNetworkingFactory(bad, () => "s")).toThrow(
+      MissingPartnerConfigException,
+    );
+  });
+
+  it("throws MissingPartnerConfigException when the auth token is blank", () => {
+    const base = makeBaseConfig();
+    const bad: NetworkConfig = {
+      ...base,
+      config: { ...base.config!, token: "" },
+    };
+    expect(() => makeNetworkingFactory(bad, () => "s")).toThrow(
+      MissingPartnerConfigException,
+    );
+  });
+});
+
+function makeBaseConfig({
+  interceptors,
+  logLevel = LogLevel.basic,
+}: {
+  readonly interceptors?: ReadonlyArray<Interceptor>;
+  readonly logLevel?: LogLevel;
+} = {}): NetworkConfig {
+  return {
+    config: {
+      jobType: JobType.smartSelfieEnrollment,
+      token: "test-token-value",
+      partnerConfig: {
+        partnerId: "test-partner",
+        callbackUrl: "https://example.test/cb",
+        useSandbox: true,
+      },
+      logging: {
+        enabled: true,
+        level: logLevel,
+        redactHeaders: [],
+      },
+    },
+    ...(interceptors ? { interceptors } : {}),
+  };
+}

package/src/data/factory/__tests__/signed_job_submission_headers.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import type { InternalAxiosRequestConfig } from "axios";
+
+import { JobType } from "../../../core/models/job_type";
+import type { NetworkConfig } from "../../../core/models/network_config";
+import { LogLevel } from "../../../core/models/network_config";
+import { makeNetworkingFactory } from "../networking_factory";
+import { UseSmileIDMetadata } from "../../../metadata/use_smile_id_metadata";
+
+/**
+ * Wire-level proof that the signed-job opt-in flags survive axios
+ * config merging and reach the interceptors: a real submission through
+ * the real client must leave with `smileid-request-mac` and
+ * `smileid-device-nonce` stamped. The API-layer tests mock the client,
+ * so they cannot catch a mismatch between where `_postMultipart`
+ * places the flags and where the interceptors read them.
+ */
+
+function makeBaseConfig(): NetworkConfig {
+  return {
+    config: {
+      jobType: JobType.enhancedKyc,
+      token: "test-token-value",
+      partnerConfig: {
+        partnerId: "test-partner",
+        callbackUrl: "https://example.test/cb",
+        useSandbox: true,
+      },
+      logging: {
+        enabled: false,
+        level: LogLevel.basic,
+        redactHeaders: [],
+      },
+    },
+  };
+}
+
+const metadata = new UseSmileIDMetadata({
+  sdkVersion: "12.0.0",
+  sdk: "react-native-expo",
+  deviceOs: "",
+  deviceModel: "",
+  appName: "",
+  sessionId: "test-session-id",
+  clientIp: "",
+  networkConnection: "",
+  carrierInfo: "",
+  proxy: false,
+  timezone: "",
+  locale: "",
+  screenResolution: "",
+  memoryInfoMb: 0,
+  deviceOrientation: "",
+  systemArchitecture: "",
+  numberOfCameras: 0,
+  hostApplication: "",
+  proximitySensor: false,
+  securityPolicyVersion: "12.0.0",
+});
+
+describe("signed job submission headers (wire-level)", () => {
+  it("a job submission leaves with smileid-request-mac and smileid-device-nonce", async () => {
+    let wireHeaders: Record<string, unknown> | undefined;
+
+    const { client, api } = makeNetworkingFactory(
+      makeBaseConfig(),
+      () => "test-secret",
+    );
+    client.defaults.adapter = (requestConfig: InternalAxiosRequestConfig) => {
+      wireHeaders = {
+        ...(requestConfig.headers as unknown as Record<string, unknown>),
+      };
+      return Promise.resolve({
+        status: 200,
+        statusText: "OK",
+        data: {
+          job_id: "job-1",
+          user_id: "user-1",
+          status: "accepted",
+          message: "ok",
+        },
+        headers: {},
+        config: requestConfig,
+      });
+    };
+
+    await api.enhancedKyc({
+      jobType: JobType.enhancedKyc,
+      params: { idType: "NATIONAL_ID", idNumber: "32232403", country: "KE" },
+      userDetails: { givenNames: "John", lastName: "Doe" },
+      consent: {
+        granted: true,
+        grantedAt: "2026-04-30T00:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://example.test/p",
+      },
+      metadata,
+    });
+
+    expect(wireHeaders).toBeDefined();
+    const keys = new Set(
+      Object.keys(wireHeaders ?? {}).map((k) => k.toLowerCase()),
+    );
+    expect(keys.has("smileid-request-timestamp")).toBe(true);
+    expect(keys.has("smileid-request-mac")).toBe(true);
+    // Attestation fails open without the native module, so the nonce
+    // carries an ERR_ envelope here — presence is the contract.
+    expect(keys.has("smileid-device-nonce")).toBe(true);
+  });
+});

package/src/data/factory/networking_factory.ts

@@ -0,0 +1,188 @@
+import type { AxiosInstance } from "axios";
+import type { NetworkConfig } from "../../core/models/network_config";
+import {
+  SmileIDAPI,
+  buildAxiosClient,
+  SmileAuthInterceptor,
+  attachLoggingInterceptor,
+} from "../api/smile_id_api";
+import { createGzipInterceptor } from "../api/interceptors/gzip_interceptor";
+import { SmileRequestMacInterceptor } from "../api/interceptors/smile_request_mac_interceptor";
+import { SmileIntegrityInterceptor } from "../api/interceptors/smile_integrity_interceptor";
+import { TokenRefreshInterceptor } from "../api/interceptors/token_refresh_interceptor";
+import { TokenHolder } from "../api/auth/token_holder";
+import { SmileIDCryptoManager } from "../security/smile_id_crypto_manager";
+import { Attestation, SigningSecretProvider } from "@smileid/usesmileid_bridge";
+import { MissingPartnerConfigException } from "../../core/exception";
+import { UseSmileIDMetadataFactory } from "../../metadata/use_smile_id_metadata_factory";
+import type { MetadataProvider } from "../../metadata/use_smile_id_metadata_factory";
+
+/**
+ * Wire an axios instance + the SDK's interceptor chain and return a
+ * `SmileIDAPI`.
+ *
+ * Canonical request-path order (outermost → wire):
+ *   `partner-custom → token-refresh → auth → request-mac → integrity →
+ *    logging → gzip → wire`
+ *
+ * - **Partner-custom interceptors** sit outermost so partners can
+ *   inject debugging tools (Charles, Sentry breadcrumbs) before any
+ *   SDK headers attach.
+ * - **TokenRefreshInterceptor** sits next so its retry — which re-issues
+ *   via `client.request(config)` — re-runs the rest of the SDK chain
+ *   with the refreshed token (auth re-stamps from the same `TokenHolder`
+ *   the refresh wrote into, mac/integrity re-stamp on opt-in endpoints).
+ *   It only attaches a response interceptor — the 401 → refresh → retry
+ *   pathway lives on the error branch.
+ * - **Auth** runs before the MAC interceptor so the `smileid-*` headers it
+ *   stamps (token, partner id, `smileid-request-timestamp`) are present to be
+ *   signed; it also sits after partner-custom interceptors so they cannot strip
+ *   the token. Reads the current token from the shared `TokenHolder`.
+ * - **Request MAC** stamps `smileid-request-mac` (the canonicalised-request
+ *   HMAC from `SmileIDCryptoManager`) for endpoints that opt in via
+ *   `_useSmileIDRequestMac: true`. It runs before the integrity interceptor so
+ *   the integrity token can bind to the freshly-computed MAC value.
+ * - **Integrity** stamps `smileid-device-nonce` with the
+ *   `Attestation.requestToken(macHeader)` envelope for endpoints that
+ *   opt in via `_useSmileIDAttestation: true`. Reads the MAC header the
+ *   previous interceptor set.
+ * - **Logging** sits second-to-last so the line it prints reflects
+ *   the request after auth has stamped headers but before gzip
+ *   transforms the body. Sensitive headers are redacted via the
+ *   [`ALWAYS_REDACT`](../api/interceptors/logging_interceptor.ts)
+ *   set. On the response path the order naturally inverts.
+ * - **Gzip** sits closest to the wire — it stamps `Accept-Encoding:
+ *   gzip` on every request so axios auto-decompresses responses.
+ *
+ * axios applies **request interceptors LIFO** (last registered runs
+ * first) and **response interceptors FIFO** (first registered runs
+ * first). The registration order below is therefore the *reverse* of
+ * the request-path order so the LIFO unwind lands on the canonical
+ * order described above.
+ */
+export function makeNetworkingFactory(
+  config: NetworkConfig,
+  // The request-signing secret source; defaults to the native bridge and exists
+  // so tests can supply a known secret without the native module.
+  signingSecret: () => string = () => SigningSecretProvider.signingSecret(),
+): {
+  readonly api: SmileIDAPI;
+  readonly client: AxiosInstance;
+  readonly metadata: MetadataProvider;
+} {
+  // Reject blank credentials with a typed exception at client
+  // construction so an unauthenticated request never reaches the wire.
+  const partnerConfig = config.config?.partnerConfig;
+  if (!partnerConfig || partnerConfig.partnerId.trim() === "") {
+    throw MissingPartnerConfigException.missingPartnerId();
+  }
+  if (!config.config?.token || config.config.token.trim() === "") {
+    throw MissingPartnerConfigException.missingAuthToken();
+  }
+
+  const client = buildAxiosClient(config);
+  // Wire a single per-flow metadata provider — every submission
+  // endpoint requires a `metadata` part. The factory reads
+  // `expo-device` lazily when present and falls back to empty values
+  // otherwise, so this is safe to construct unconditionally. The
+  // provider is returned to the caller so the request-construction
+  // site (the flow navigation manager) can stamp a fresh snapshot
+  // onto each `JobRequest` via `metadata.make()`.
+  const metadata = new UseSmileIDMetadataFactory();
+  const api = new SmileIDAPI(client, partnerConfig);
+
+  // Warm up the Play Integrity / App Attest token provider off the
+  // submission path so the integrity interceptor's per-request
+  // `requestToken` doesn't pay the multi-second first-call cost (and
+  // doesn't fail `NOT_INITIALIZED`). Fire-and-forget + fail-open: on
+  // failure the interceptor stamps an `ERR_` nonce and the server decides
+  // policy.
+  void Attestation.warmUp().catch(() => {
+    /* fail-open — handled per-request by SmileIntegrityInterceptor */
+  });
+
+  // Shared mutable holder for the partner-supplied auth token.
+  // SmileAuthInterceptor reads from it on every request;
+  // TokenRefreshInterceptor writes a refreshed value on a 401 so the
+  // next outgoing request automatically picks up the new token.
+  const tokenHolder = new TokenHolder(config.config?.token ?? "");
+
+  // 1. Gzip is registered FIRST so it runs LAST on the request path
+  //    (innermost / closest to the wire). It stamps `Accept-Encoding:
+  //    gzip` so the server can compress responses (axios
+  //    transparently decompresses).
+  const gzip = createGzipInterceptor();
+  gzip.attach(client);
+
+  // 2. Logging is registered SECOND so it runs SECOND-TO-LAST on the
+  //    request path — the printed body and headers reflect the
+  //    request after auth has stamped headers but before gzip
+  //    transforms the wire bytes. Lives at `config.config.logging`
+  //    under the `network → config → logging` nesting.
+  const logging = config.config?.logging;
+  if (logging) {
+    attachLoggingInterceptor(client, logging);
+  }
+
+  // 3. Integrity is registered THIRD so it runs after MAC stamping on the
+  //    request path — it reads the `smileid-request-mac` header the MAC
+  //    interceptor sets and binds the per-request token to it. Per-request
+  //    opt-in via `config._useSmileIDAttestation`; pass-through otherwise.
+  const integrityInterceptor = new SmileIntegrityInterceptor();
+  integrityInterceptor.attach(client);
+
+  // 4. Request MAC runs after auth (so the `smileid-*` headers + timestamp it
+  //    signs are present) and before integrity (which binds to the MAC). The
+  //    signing key is PBKDF2-derived from the native Arkana secret. Per-request
+  //    opt-in via `config._useSmileIDRequestMac`; pass-through otherwise.
+  const cryptoManager = new SmileIDCryptoManager(signingSecret());
+  const requestMacInterceptor = new SmileRequestMacInterceptor({
+    cryptoManager,
+  });
+  requestMacInterceptor.attach(client);
+
+  // 5. Auth is registered LAST of these three so it runs FIRST on the request
+  //    path — after partner-custom interceptors (which therefore cannot strip
+  //    the token), before logging. It stamps the token + partner id +
+  //    `smileid-request-timestamp` before the MAC interceptor signs them, and
+  //    reads from the shared `TokenHolder` so a refreshed value is picked up on
+  //    the next outbound request.
+  const authInterceptor = new SmileAuthInterceptor({
+    partnerConfig,
+    tokenHolder,
+  });
+  authInterceptor.attach(client);
+
+  // 6. TokenRefreshInterceptor only attaches a response interceptor —
+  //    its 401 → refresh → retry pathway lives on the error branch.
+  //    Registered after the SDK request-side interceptors so its
+  //    response error handler sees the 401 BEFORE bubbling up to
+  //    partner-custom handlers downstream; the retry re-issues via
+  //    `client.request(config)` and re-runs all request interceptors
+  //    above (auth re-reads the now-refreshed `TokenHolder`).
+  const tokenRefreshInterceptor = new TokenRefreshInterceptor({
+    tokenHolder,
+    onTokenExpired: config.config?.onTokenExpired,
+  });
+  tokenRefreshInterceptor.attach(client);
+
+  // 7. Partner-custom interceptors are registered LAST so they run
+  //    FIRST on the request path (outermost) — ideal for Charles,
+  //    Sentry breadcrumbs, etc. that should observe the request
+  //    before any SDK headers attach.
+  if (config.interceptors) {
+    for (const interceptor of config.interceptors) {
+      // Partner contracts: `interceptor` may be `(client) => void` or
+      // an object with `attach(client)`. We support both shapes.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const handler = interceptor as any;
+      if (typeof handler === "function") {
+        handler(client);
+      } else if (typeof handler?.attach === "function") {
+        handler.attach(client);
+      }
+    }
+  }
+
+  return { api, client, metadata };
+}

package/src/data/model/__tests__/sdk_config.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import {
+  numSamplesOverride,
+  sdkConfigSchema,
+  type SdkConfig,
+} from "../sdk_config";
+
+describe("numSamplesOverride", () => {
+  it("converts livenessImageCount to numSamples via +1", () => {
+    // 7 liveness images → numSamples = 8 (1 selfie + 7 liveness).
+    expect(numSamplesOverride({ livenessImageCount: 7 })).toBe(8);
+  });
+
+  it("handles the minimum valid count (1 → 2)", () => {
+    expect(numSamplesOverride({ livenessImageCount: 1 })).toBe(2);
+  });
+
+  it("returns undefined when livenessImageCount is 0 (treated as absent)", () => {
+    expect(numSamplesOverride({ livenessImageCount: 0 })).toBeUndefined();
+  });
+
+  it("returns undefined when livenessImageCount is negative", () => {
+    expect(numSamplesOverride({ livenessImageCount: -3 })).toBeUndefined();
+  });
+
+  it("returns undefined when livenessImageCount is absent", () => {
+    expect(numSamplesOverride({})).toBeUndefined();
+  });
+
+  it("returns undefined when config is undefined", () => {
+    expect(numSamplesOverride(undefined)).toBeUndefined();
+  });
+});
+
+describe("sdkConfigSchema — Zod parsing", () => {
+  it("accepts an empty object (all fields optional)", () => {
+    const result = sdkConfigSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("parses the canonical backend fixture — selfie, liveness, document, livenessImageCount", () => {
+    // Matches the lambda authentication test fixture exactly.
+    const raw = {
+      selfie: { width: 640, height: 480, quality: 90 },
+      liveness: { width: 640, height: 480, quality: 80 },
+      document: { quality: 70 },
+      livenessImageCount: 7,
+    };
+    const result = sdkConfigSchema.safeParse(raw);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const config: SdkConfig = result.data;
+      expect(config.selfie?.width).toBe(640);
+      expect(config.selfie?.height).toBe(480);
+      expect(config.selfie?.quality).toBe(90);
+      expect(config.liveness?.quality).toBe(80);
+      expect(config.document?.quality).toBe(70);
+      expect(config.livenessImageCount).toBe(7);
+    }
+  });
+
+  it("parses a partial claim that only specifies liveness quality", () => {
+    const result = sdkConfigSchema.safeParse({ liveness: { quality: 60 } });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.liveness?.quality).toBe(60);
+      expect(result.data.selfie).toBeUndefined();
+      expect(result.data.document).toBeUndefined();
+      expect(result.data.livenessImageCount).toBeUndefined();
+    }
+  });
+
+  it("fails when livenessImageCount is a float", () => {
+    const result = sdkConfigSchema.safeParse({ livenessImageCount: 6.5 });
+    expect(result.success).toBe(false);
+  });
+
+  it("parses livenessImageCount: 6 and numSamplesOverride returns 7", () => {
+    const result = sdkConfigSchema.safeParse({ livenessImageCount: 6 });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(numSamplesOverride(result.data)).toBe(7);
+    }
+  });
+});