@smileid/usesmileid 12.0.0-beta01

package/src/data/smile_id_urls.ts

@@ -0,0 +1,13 @@
+/**
+ * Base URLs for the Smile ID API, selected by sandbox vs production.
+ *
+ * Sandbox and production currently both resolve to the dev API; the split is
+ * kept so the production host can diverge without touching call sites.
+ */
+export const SmileIDUrls = {
+  sandbox: "https://devapi.smileidentity.com/",
+  production: "https://api.smileidentity.com/",
+  forConfig(useSandbox: boolean): string {
+    return useSandbox ? this.sandbox : this.production;
+  },
+} as const;

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

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { AxiosError, AxiosHeaders } from "axios";
+import { computeDelayMs, isRetryable, withRetry } from "../retry_util";
+import {
+  RetryStrategy,
+  type RetryConfig,
+} from "../../../core/models/network_config";
+
+const exponentialConfig: RetryConfig = Object.freeze({
+  maxAttempts: 3,
+  strategy: RetryStrategy.exponential,
+  initialDelay: 0.1,
+  multiplier: 2,
+  maxDelay: 10,
+  jitter: 0,
+  fixedDelay: 1,
+});
+
+const fixedConfig: RetryConfig = Object.freeze({
+  ...exponentialConfig,
+  strategy: RetryStrategy.fixed,
+});
+
+const noneConfig: RetryConfig = Object.freeze({
+  ...exponentialConfig,
+  strategy: RetryStrategy.none,
+  maxAttempts: 1,
+});
+
+function makeAxiosError(status?: number): AxiosError {
+  const err = new AxiosError(
+    "boom",
+    status ? `${status}` : undefined,
+    undefined,
+    undefined,
+    status
+      ? {
+          status,
+          statusText: "X",
+          data: undefined,
+          headers: {},
+          config: { headers: new AxiosHeaders() },
+        }
+      : undefined,
+  );
+  return err;
+}
+
+describe("isRetryable", () => {
+  it("retries no-response axios errors (timeout / DNS / connection reset)", () => {
+    expect(isRetryable(makeAxiosError())).toBe(true);
+  });
+
+  it.each([500, 502, 503, 504, 408, 429])("retries HTTP %d", (status) => {
+    expect(isRetryable(makeAxiosError(status))).toBe(true);
+  });
+
+  it.each([400, 401, 403, 404, 422])(
+    "does NOT retry HTTP %d (application error)",
+    (status) => {
+      // Concrete scenario: a 401 must fall through immediately so the
+      // auth interceptor can invalidate its cached token. If we kept
+      // retrying, the auth chain would burn `maxAttempts` calls
+      // sending the same expired token before the partner sees the
+      // failure. Pin the contract.
+      expect(isRetryable(makeAxiosError(status))).toBe(false);
+    },
+  );
+
+  it("does NOT retry non-axios errors (programming bugs)", () => {
+    expect(isRetryable(new Error("typo"))).toBe(false);
+    expect(isRetryable("not an error")).toBe(false);
+    expect(isRetryable(null)).toBe(false);
+  });
+});
+
+describe("computeDelayMs", () => {
+  it('strategy="none" → 0', () => {
+    expect(computeDelayMs(noneConfig, 0)).toBe(0);
+    expect(computeDelayMs(noneConfig, 5)).toBe(0);
+  });
+
+  it('strategy="fixed" → constant fixedDelayMs', () => {
+    expect(computeDelayMs(fixedConfig, 0)).toBe(1_000);
+    expect(computeDelayMs(fixedConfig, 1)).toBe(1_000);
+    expect(computeDelayMs(fixedConfig, 5)).toBe(1_000);
+  });
+
+  it('strategy="exponential" with jitter=0 → deterministic backoff', () => {
+    // Concrete scenario: a regression that doubles `multiplier`
+    // accidentally would lengthen retry timing dramatically. Pin
+    // the formula at jitter=0 (deterministic) so timing changes
+    // surface in CI.
+    expect(computeDelayMs(exponentialConfig, 0)).toBe(100); // 100 * 2^0
+    expect(computeDelayMs(exponentialConfig, 1)).toBe(200); // 100 * 2^1
+    expect(computeDelayMs(exponentialConfig, 2)).toBe(400);
+    expect(computeDelayMs(exponentialConfig, 3)).toBe(800);
+  });
+
+  it("caps at maxDelayMs", () => {
+    expect(computeDelayMs(exponentialConfig, 10)).toBe(10_000); // would be 102_400 uncapped
+  });
+});
+
+describe("withRetry", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns immediately on first success", async () => {
+    const block = vi.fn().mockResolvedValue("ok");
+    await expect(withRetry(exponentialConfig, block)).resolves.toBe("ok");
+    expect(block).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries network-class failures up to maxAttempts", async () => {
+    const block = vi
+      .fn()
+      .mockRejectedValueOnce(makeAxiosError(503))
+      .mockRejectedValueOnce(makeAxiosError(503))
+      .mockResolvedValueOnce("ok");
+    const promise = withRetry(exponentialConfig, block);
+    // Attach a no-op catch BEFORE advancing timers so vitest doesn't
+    // flag the in-flight rejection as unhandled while the retry loop
+    // is mid-cycle. The actual assertion below still sees the final
+    // resolution / rejection.
+    promise.catch(() => {});
+    await vi.runAllTimersAsync();
+    await expect(promise).resolves.toBe("ok");
+    expect(block).toHaveBeenCalledTimes(3);
+  });
+
+  it("throws application errors immediately (no retry)", async () => {
+    // Concrete scenario: 401 / 403 must not consume retry budget.
+    // The auth interceptor needs to see the 401 and clear its cache
+    // before the next "real" call comes in.
+    const block = vi.fn().mockRejectedValue(makeAxiosError(401));
+    await expect(withRetry(exponentialConfig, block)).rejects.toMatchObject({
+      response: { status: 401 },
+    });
+    expect(block).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws after exhausting maxAttempts on persistent failure", async () => {
+    const block = vi.fn().mockRejectedValue(makeAxiosError(503));
+    const promise = withRetry(exponentialConfig, block);
+    promise.catch(() => {}); // see comment in prior test
+    await vi.runAllTimersAsync();
+    await expect(promise).rejects.toMatchObject({
+      response: { status: 503 },
+    });
+    expect(block).toHaveBeenCalledTimes(3); // maxAttempts
+  });
+});

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

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import { decodeSmileIDToken } from "../use_smile_id_token_decoder";
+
+// ---------------------------------------------------------------------------
+// Helper — mint a structurally valid JWT with a caller-supplied payload.
+// The header and signature fields are arbitrary tokens; only the
+// base64url-encoded middle segment is decoded.
+// ---------------------------------------------------------------------------
+function makeJwt(payload: Record<string, unknown>): string {
+  const json = JSON.stringify(payload);
+  // Node.js Buffer.from + base64url covers the full UTF-8 range and is
+  // available in the Hermes-compatible vitest Node environment.
+  const payloadSegment = Buffer.from(json).toString("base64url");
+  return `eyJhbGciOiJub25lIn0.${payloadSegment}.stub-sig`;
+}
+
+// ---------------------------------------------------------------------------
+// Structural failure paths → undefined
+// ---------------------------------------------------------------------------
+describe("decodeSmileIDToken — structural failures return undefined", () => {
+  it("returns undefined for an empty string", () => {
+    expect(decodeSmileIDToken("")).toBeUndefined();
+  });
+
+  it("returns undefined for a single-segment string", () => {
+    expect(decodeSmileIDToken("notajwt")).toBeUndefined();
+  });
+
+  it("returns undefined for two segments", () => {
+    expect(decodeSmileIDToken("a.b")).toBeUndefined();
+  });
+
+  it("returns undefined for four segments", () => {
+    expect(decodeSmileIDToken("a.b.c.d")).toBeUndefined();
+  });
+
+  it("returns undefined for non-base64 payload", () => {
+    // The second segment cannot be decoded by atob — structurally invalid.
+    expect(
+      decodeSmileIDToken("header.!!!invalid-base64!!!.sig"),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when the payload decodes to non-JSON", () => {
+    const nonJson = Buffer.from("not-json").toString("base64url");
+    expect(decodeSmileIDToken(`header.${nonJson}.sig`)).toBeUndefined();
+  });
+
+  it("returns undefined when the payload is a JSON array (RFC 7519 §3 violation)", () => {
+    const arrayPayload = Buffer.from(JSON.stringify([1, 2, 3])).toString(
+      "base64url",
+    );
+    expect(decodeSmileIDToken(`header.${arrayPayload}.sig`)).toBeUndefined();
+  });
+
+  it("returns undefined when the payload is a JSON null", () => {
+    const nullPayload = Buffer.from("null").toString("base64url");
+    expect(decodeSmileIDToken(`header.${nullPayload}.sig`)).toBeUndefined();
+  });
+
+  it("returns undefined when the payload is a JSON string", () => {
+    const strPayload = Buffer.from('"just-a-string"').toString("base64url");
+    expect(decodeSmileIDToken(`header.${strPayload}.sig`)).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Valid token, absent or non-object claim → defined DecodedToken with
+// sdkConfig unset.
+// ---------------------------------------------------------------------------
+describe("decodeSmileIDToken — valid token with no usable sdk_config", () => {
+  it("returns an empty DecodedToken when sdk_config is absent", () => {
+    const token = makeJwt({ sub: "partner-1", iat: 1_700_000_000 });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig).toBeUndefined();
+  });
+
+  it("returns an empty DecodedToken when sdk_config is null", () => {
+    const token = makeJwt({ sdk_config: null });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig).toBeUndefined();
+  });
+
+  it("returns an empty DecodedToken when sdk_config is a number", () => {
+    const token = makeJwt({ sdk_config: 42 });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig).toBeUndefined();
+  });
+
+  it("returns an empty DecodedToken when sdk_config is a string", () => {
+    const token = makeJwt({ sdk_config: "some-string" });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig).toBeUndefined();
+  });
+
+  it("returns an empty DecodedToken when sdk_config is an array", () => {
+    const token = makeJwt({ sdk_config: [{ width: 640 }] });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig).toBeUndefined();
+  });
+
+  it("returns an empty DecodedToken when sdk_config fails Zod parsing (float width)", () => {
+    // Non-integer floats are rejected by .int() in sdkConfigCaptureSchema.
+    const token = makeJwt({ sdk_config: { selfie: { width: 640.5 } } });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Valid token with a parseable sdk_config — full round-trip
+// ---------------------------------------------------------------------------
+describe("decodeSmileIDToken — parses a valid sdk_config claim", () => {
+  it("parses the canonical backend fixture (selfie, liveness, document, livenessImageCount)", () => {
+    // Matches the lambda authentication test fixture exactly.
+    const token = makeJwt({
+      sdk_config: {
+        selfie: { width: 640, height: 480, quality: 90 },
+        liveness: { width: 640, height: 480, quality: 80 },
+        document: { quality: 70 },
+        livenessImageCount: 7,
+      },
+    });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.sdkConfig?.selfie?.width).toBe(640);
+    expect(result?.sdkConfig?.selfie?.height).toBe(480);
+    expect(result?.sdkConfig?.selfie?.quality).toBe(90);
+    expect(result?.sdkConfig?.liveness?.quality).toBe(80);
+    expect(result?.sdkConfig?.document?.quality).toBe(70);
+    expect(result?.sdkConfig?.livenessImageCount).toBe(7);
+  });
+
+  it("parses a minimal claim (only livenessImageCount)", () => {
+    const token = makeJwt({ sdk_config: { livenessImageCount: 5 } });
+    const result = decodeSmileIDToken(token);
+    expect(result?.sdkConfig?.livenessImageCount).toBe(5);
+    expect(result?.sdkConfig?.selfie).toBeUndefined();
+  });
+
+  it("parses a claim with only quality settings (no dimensions)", () => {
+    const token = makeJwt({
+      sdk_config: { selfie: { quality: 85 }, liveness: { quality: 70 } },
+    });
+    const result = decodeSmileIDToken(token);
+    expect(result?.sdkConfig?.selfie?.quality).toBe(85);
+    expect(result?.sdkConfig?.selfie?.width).toBeUndefined();
+    expect(result?.sdkConfig?.liveness?.quality).toBe(70);
+  });
+
+  it("strips extra unknown fields at the top level of sdk_config (Zod strip)", () => {
+    const token = makeJwt({ sdk_config: { unknownTopLevel: "ignored" } });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    // sdkConfig is defined (valid empty object), not undefined
+    expect(result?.sdkConfig).toBeDefined();
+    expect(
+      (result?.sdkConfig as Record<string, unknown>)?.["unknownTopLevel"],
+    ).toBeUndefined();
+  });
+
+  it("handles a token with other standard JWT claims alongside sdk_config", () => {
+    const token = makeJwt({
+      sub: "partner-123",
+      iat: 1_700_000_000,
+      exp: 1_700_086_400,
+      sdk_config: { liveness: { quality: 60 } },
+    });
+    const result = decodeSmileIDToken(token);
+    expect(result?.sdkConfig?.liveness?.quality).toBe(60);
+  });
+
+  it("never throws — returns a value for any input string", () => {
+    // Smoke-test: a large variety of malformed inputs must never throw.
+    const inputs = [
+      "",
+      "a",
+      "a.b",
+      "a.b.c.d",
+      "a.!!!.c",
+      makeJwt({}),
+      makeJwt({ sdk_config: {} }),
+      makeJwt({ sdk_config: { selfie: { quality: 90 } } }),
+    ];
+    for (const input of inputs) {
+      expect(() => decodeSmileIDToken(input)).not.toThrow();
+    }
+  });
+});

package/src/data/util/retry_util.ts

@@ -0,0 +1,72 @@
+import { isAxiosError } from "axios";
+import type { RetryConfig } from "../../core/models/network_config";
+
+/**
+ * Retry helper. Retries `block` until success or `maxAttempts`
+ * exhausted, with delays driven by the configured strategy. Only
+ * network-class failures are retried — application errors (4xx other
+ * than 408 / 429) bubble out immediately.
+ *
+ * Concrete scenario: a 401 (token expired) bubbles through here so
+ * the auth interceptor can invalidate its cache. A 503 (server busy)
+ * is retried up to `maxAttempts` times with exponential backoff.
+ */
+export async function withRetry<T>(
+  config: RetryConfig,
+  block: () => Promise<T>,
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
+    try {
+      return await block();
+    } catch (error) {
+      lastError = error;
+      if (!isRetryable(error) || attempt === config.maxAttempts - 1) {
+        throw error;
+      }
+      const delayMs = computeDelayMs(config, attempt);
+      await sleep(delayMs);
+    }
+  }
+  // Unreachable — the loop either returns or throws — but TS needs
+  // an explicit terminal statement here.
+  throw lastError;
+}
+
+/**
+ * Network-class failure check. Returns `true` for axios errors that
+ * indicate transient transport problems (timeout, 5xx, 408, 429) and
+ * `false` for application errors the caller must handle (400, 401,
+ * 403, …) or for non-axios errors (programming bugs).
+ */
+export function isRetryable(error: unknown): boolean {
+  if (!isAxiosError(error)) return false;
+  // No response yet → transport failure (timeout, DNS, connection
+  // reset). Retry.
+  if (!error.response) return true;
+  const code = error.response.status;
+  return code >= 500 || code === 408 || code === 429;
+}
+
+/**
+ * Compute the delay (in milliseconds) before the next retry attempt.
+ * `attempt` is 0-indexed (0 = first retry, after the initial call
+ * failed). Config delays are in seconds; the return value is converted
+ * to ms so it can drive `setTimeout` directly.
+ */
+export function computeDelayMs(config: RetryConfig, attempt: number): number {
+  if (config.strategy === "none") return 0;
+  if (config.strategy === "fixed") return config.fixedDelay * 1000;
+
+  const maxDelayMs = config.maxDelay * 1000;
+  const baseMs =
+    config.initialDelay * 1000 * Math.pow(config.multiplier, attempt);
+  const cappedMs = Math.min(baseMs, maxDelayMs);
+  const jitterFactor = (Math.random() * 2 - 1) * config.jitter;
+  const withJitterMs = cappedMs * (1 + jitterFactor);
+  return Math.max(0, Math.min(maxDelayMs, Math.round(withJitterMs)));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/data/util/use_smile_id_token_decoder.ts

@@ -0,0 +1,138 @@
+import { ZodError } from "zod";
+
+import { type SdkConfig, sdkConfigSchema } from "../model/sdk_config";
+
+// `atob` is a global available in React Native's Hermes runtime and in
+// modern browsers. The `lib: ["ES2022"]` tsconfig omits DOM types, so the
+// declaration must be explicit. The function exists at runtime; the
+// declaration is a type-only hint.
+declare function atob(data: string): string;
+
+/**
+ * Result of decoding a Smile ID JWT auth token.
+ *
+ * A non-`undefined` `DecodedToken` means the token was structurally
+ * valid (three base64url segments, decodable JSON object payload).
+ * `sdkConfig` may still be `undefined` within a valid token when the
+ * `sdk_config` claim was absent, had an unexpected type, or failed
+ * schema validation — all those cases degrade gracefully to `undefined`
+ * rather than rejecting the token.
+ */
+export type DecodedToken = {
+  readonly sdkConfig?: SdkConfig;
+};
+
+/**
+ * Decode a Smile ID JWT auth token and extract the `sdk_config` claim.
+ *
+ * The JWT signature is intentionally NOT verified — the server validates
+ * authenticity; the SDK only reads capture settings from the payload.
+ *
+ * Return semantics:
+ *   - Structurally invalid token (not exactly three `.`-delimited
+ *     segments, non-base64url payload, non-object JSON) → `undefined`.
+ *   - Valid token with no `sdk_config` claim, a non-object claim, or a
+ *     claim that fails Zod parsing → non-`undefined` `DecodedToken`
+ *     with `sdkConfig` unset.
+ *   - Valid token with a parseable `sdk_config` → non-`undefined`
+ *     `DecodedToken` with `sdkConfig` set.
+ *
+ * This function never throws — all failure paths return a value.
+ */
+export function decodeSmileIDToken(token: string): DecodedToken | undefined {
+  const segments = token.split(".");
+  if (segments.length !== 3) return undefined;
+
+  // Decode the payload (middle segment). JWTs omit base64 padding; add
+  // it back before decoding. Replace the URL-safe alphabet (-_) with the
+  // standard alphabet (+/) that `atob` / `Buffer.from` expects.
+  const payloadSegment = segments[1];
+  if (!payloadSegment) return undefined;
+
+  let payloadJson: string;
+  try {
+    payloadJson = decodeBase64Url(payloadSegment);
+  } catch {
+    // Non-base64 data in the payload segment — structurally invalid token.
+    return undefined;
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(payloadJson);
+  } catch {
+    // Non-JSON payload — structurally invalid token.
+    return undefined;
+  }
+
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    Array.isArray(payload)
+  ) {
+    // JWT payload must be a JSON object per RFC 7519 §3.
+    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 };
+}
+
+/**
+ * Decode a base64url string (no padding) to a UTF-8 string.
+ *
+ * JWTs use base64url encoding (RFC 4648 §5) which replaces `+` with
+ * `-` and `/` with `_`, and omits `=` padding. This helper restores the
+ * standard alphabet and adds padding before decoding.
+ *
+ * Throws `DOMException` / `TypeError` when the input is not valid
+ * base64; callers wrap it in a try/catch.
+ */
+function decodeBase64Url(input: string): string {
+  // Restore standard base64 alphabet.
+  const standard = input.replace(/-/g, "+").replace(/_/g, "/");
+  // Add `=` padding to reach a multiple of 4.
+  const remainder = standard.length % 4;
+  const padded =
+    remainder === 0 ? standard : standard + "=".repeat(4 - remainder);
+
+  // `atob` is available in React Native's Hermes runtime and in all
+  // modern browsers. It decodes to a binary string; decode UTF-8 via
+  // `decodeURIComponent` + percent-encoding to handle non-ASCII claims.
+  const binaryString = atob(padded);
+  return decodeURIComponent(
+    binaryString
+      .split("")
+      .map(
+        (char: string) =>
+          "%" + char.charCodeAt(0).toString(16).padStart(2, "0"),
+      )
+      .join(""),
+  );
+}