@smileid/usesmileid 12.0.0-beta01 → 12.0.0

package/src/data/dsl/builder/cache_config_builder.ts

@@ -7,8 +7,10 @@ import type { CacheConfig } from "../../../core/models/network_config";
  * verification flows without aggressive trimming.
  */
 export class CacheConfigBuilder {
+  /** Whether HTTP response caching is on. */
   enabled = true;
-  /** Bytes — default 50 MB. */
+
+  /** Maximum on-disk cache size, in bytes. Default 50 MB. */
   maxSize = 50 * 1024 * 1024;
 
   /**

package/src/data/dsl/builder/config_builder.ts

@@ -18,13 +18,25 @@ import {
  * identity.
  */
 export class PartnerConfigBuilder {
+  /** Your Smile ID partner id. Required. */
   partnerId = "";
+
+  /**
+   * Optional webhook URL Smile ID calls with the job result. It is also
+   * sent as a per-request identity header.
+   */
   callbackUrl = "";
+
+  /**
+   * When true, routes requests to the sandbox environment instead of
+   * production. Defaults to false.
+   */
   useSandbox = false;
+
   /**
-   * Optional partner-supplied key/value metadata. Forwarded onto the
-   * `partner_params` JSON multipart form part on Enhanced / Biometric
-   * KYC submissions when set.
+   * Optional free-form key/value pairs echoed back on the job result for
+   * your own correlation. Forwarded onto the `partner_params` JSON
+   * multipart form part on Enhanced / Biometric KYC submissions when set.
    */
   partnerParams?: Record<string, string>;
 
@@ -49,8 +61,16 @@ export class PartnerConfigBuilder {
  * redaction list with their own proxy-injected headers.
  */
 export class LoggingConfigBuilder {
+  /** Whether HTTP request/response logging is on. */
   enabled = true;
+
+  /** Logging verbosity: none, basic, headers, or full body. */
   level: LogLevel = LogLevel.basic;
+
+  /**
+   * Header names whose values are masked in logs (for example
+   * authorization headers).
+   */
   redactHeaders: readonly string[] = [];
 
   build(): NetworkLoggingConfig {
@@ -75,35 +95,46 @@ export class LoggingConfigBuilder {
  * omit blocks they don't need.
  */
 export class ConfigBuilder {
+  /**
+   * The verification job this flow submits (for example smart-selfie
+   * enrollment, biometric KYC, or document verification). Required.
+   */
   jobType?: JobType;
 
   /**
-   * Short-lived v3 auth token issued by `/v3/token`. The partner
-   * application is responsible for exchanging its API key for a token
-   * before invoking the SDK and supplying the result here. Stamped as
-   * the `smileid-token` HTTP header on every authenticated request.
+   * The short-lived authentication token for this session. Your backend
+   * obtains it from Smile ID's `/v3/token` endpoint using your API key;
+   * the SDK never exchanges credentials itself. Stamped as the
+   * `smileid-token` HTTP header on every authenticated request.
    */
   token = "";
 
   /**
-   * Optional async refresh callback invoked when the server responds
-   * with `401 Unauthorized`. The callback receives the token the SDK
-   * was using and returns a fresh token; the SDK then retries the
-   * original request once with the new value. Concurrent 401s collapse
-   * to a single callback invocation via the SDK's shared `TokenHolder`.
-   * If the callback throws or the retry also returns 401, the original
-   * 401 response is surfaced unchanged.
+   * Optional async callback invoked when the server rejects the token
+   * with a 401. Return a fresh token and the SDK retries the request
+   * once with it. The callback receives the token the SDK was using.
+   * Concurrent 401s collapse to a single callback invocation via the
+   * SDK's shared `TokenHolder`. If the callback throws or the retry also
+   * returns 401, the original 401 response is surfaced unchanged.
    */
   onTokenExpired?: (previousToken: string) => Promise<string>;
 
   private _partnerConfig?: PartnerConfigBuilder;
   private _logging?: LoggingConfigBuilder;
 
+  /**
+   * Configures partner identity and per-job environment settings —
+   * partner id, callback URL, sandbox mode, and partner params.
+   */
   partnerConfig(block: (p: PartnerConfigBuilder) => void): void {
     if (!this._partnerConfig) this._partnerConfig = new PartnerConfigBuilder();
     block(this._partnerConfig);
   }
 
+  /**
+   * Configures HTTP request/response logging: on/off, verbosity, and
+   * redacted headers.
+   */
   logging(block: (l: LoggingConfigBuilder) => void): void {
     if (!this._logging) this._logging = new LoggingConfigBuilder();
     block(this._logging);

package/src/data/dsl/builder/interceptor_config_builder.ts

@@ -28,24 +28,26 @@ import {
 export class InterceptorConfigBuilder {
   private _interceptors: Interceptor[] = [];
 
+  /** Appends a custom interceptor to the chain. */
   add(interceptor: Interceptor): void {
     this._interceptors.push(interceptor);
   }
 
   /**
-   * Returns an interceptor that stamps `Accept-Encoding: gzip` on
-   * every outbound request. Hint-only — the SDK does not pull in a
-   * JS gzip dependency to compress request bodies. See
-   * [createGzipInterceptor] for the rationale.
+   * Adds the gzip interceptor, which requests compressed responses by
+   * stamping `Accept-Encoding: gzip` on every outbound request.
+   * Hint-only — the SDK does not pull in a JS gzip dependency to
+   * compress request bodies. See [createGzipInterceptor] for the
+   * rationale.
    */
   gzip(): Interceptor {
     return createGzipInterceptor();
   }
 
   /**
-   * Returns a logging interceptor configured by `configure`. The
-   * partner block mutates a `LoggingInterceptorBuilder` carrying
-   * `level` and `redactHeaders`.
+   * Adds the logging interceptor with the given verbosity. The partner
+   * block mutates a `LoggingInterceptorBuilder` carrying `level` and
+   * `redactHeaders`.
    */
   logging(
     configure?: (builder: LoggingInterceptorBuilder) => void,

package/src/data/dsl/builder/retry_config_builder.ts

@@ -13,13 +13,34 @@ export { RetryStrategy };
  * `strategy = RetryStrategy.fixed`.
  */
 export class RetryConfigBuilder {
+  /** Maximum number of attempts per request, including the first. */
   maxAttempts = 3;
+
+  /** Backoff strategy between attempts: exponential, fixed, or none. */
   strategy: RetryStrategy = RetryStrategy.exponential;
+
+  /** Delay before the first retry, in seconds (exponential strategy). */
   initialDelay = 1;
+
+  /**
+   * Factor by which the delay grows after each attempt (exponential
+   * strategy).
+   */
   multiplier = 2;
+
+  /**
+   * Upper bound on the delay between attempts, in seconds (exponential
+   * strategy).
+   */
   maxDelay = 32;
-  /** ±20% randomized jitter on the computed delay, in [0, 1]. */
+
+  /**
+   * Random fraction between 0 and 1 added to each delay to avoid
+   * synchronized retry storms.
+   */
   jitter = 0.2;
+
+  /** Constant delay between attempts, in seconds (fixed strategy). */
   fixedDelay = 1;
 
   build(): RetryConfig {

package/src/data/dsl/builder/timeout_config_builder.ts

@@ -8,9 +8,16 @@ import type { TimeoutConfig } from "../../../core/models/network_config";
  * the end-to-end ceiling for the whole request including retries.
  */
 export class TimeoutConfigBuilder {
+  /** Maximum time to establish a connection, in seconds. */
   connect = 60;
+
+  /** Maximum time to wait for response data, in seconds. */
   read = 60;
+
+  /** Maximum time to send request data, in seconds. */
   write = 60;
+
+  /** Maximum total time for the entire request, in seconds. */
   call = 120;
 
   build(): TimeoutConfig {

package/src/data/dsl/use_smile_id_network_builder.ts

@@ -29,26 +29,43 @@ export class UseSmileIDNetworkBuilder {
   private _retry?: RetryConfigBuilder;
   private _interceptors?: InterceptorConfigBuilder;
 
+  /**
+   * Configures the job type, authentication token, token-refresh
+   * callback, and partner identity for this flow.
+   */
   config(block: (c: ConfigBuilder) => void): void {
     if (!this._config) this._config = new ConfigBuilder();
     block(this._config);
   }
 
+  /**
+   * Configures per-phase HTTP timeouts — connect, read, write, and
+   * overall call — in seconds.
+   */
   timeouts(block: (t: TimeoutConfigBuilder) => void): void {
     if (!this._timeouts) this._timeouts = new TimeoutConfigBuilder();
     block(this._timeouts);
   }
 
+  /** Configures the HTTP response cache (on/off and maximum size). */
   cache(block: (c: CacheConfigBuilder) => void): void {
     if (!this._cache) this._cache = new CacheConfigBuilder();
     block(this._cache);
   }
 
+  /**
+   * Configures automatic retry of failed requests: strategy, attempt
+   * count, and backoff.
+   */
   retry(block: (r: RetryConfigBuilder) => void): void {
     if (!this._retry) this._retry = new RetryConfigBuilder();
     block(this._retry);
   }
 
+  /**
+   * Registers additional request/response interceptors, appended to the
+   * SDK's interceptor chain.
+   */
   interceptors(block: (i: InterceptorConfigBuilder) => void): void {
     if (!this._interceptors)
       this._interceptors = new InterceptorConfigBuilder();

package/src/data/factory/networking_factory.ts

@@ -12,6 +12,8 @@ import { SmileIntegrityInterceptor } from "../api/interceptors/smile_integrity_i
 import { TokenRefreshInterceptor } from "../api/interceptors/token_refresh_interceptor";
 import { TokenHolder } from "../api/auth/token_holder";
 import { SmileIDCryptoManager } from "../security/smile_id_crypto_manager";
+import { SecurityPolicy } from "../security/security_policy";
+import { decodeSecurityPolicyBitCode } from "../util/use_smile_id_token_decoder";
 import { Attestation, SigningSecretProvider } from "@smileid/usesmileid_bridge";
 import { MissingPartnerConfigException } from "../../core/exception";
 import { UseSmileIDMetadataFactory } from "../../metadata/use_smile_id_metadata_factory";
@@ -107,6 +109,14 @@ export function makeNetworkingFactory(
   // next outgoing request automatically picks up the new token.
   const tokenHolder = new TokenHolder(config.config?.token ?? "");
 
+  // Server-driven security policy for this flow, decoded from the top-level `policy` claim on the
+  // JWT (a sibling of `sdk_config`). Decoding is fail-secure: a malformed token, an absent claim, or an absent
+  // bit-code all resolve to "every behaviour active", so a token without the claim keeps the
+  // pre-policy behaviour rather than dropping security.
+  const securityPolicy = SecurityPolicy.fromBitCode(
+    decodeSecurityPolicyBitCode(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
@@ -128,7 +138,9 @@ export function makeNetworkingFactory(
   //    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();
+  const integrityInterceptor = new SmileIntegrityInterceptor({
+    securityPolicy,
+  });
   integrityInterceptor.attach(client);
 
   // 4. Request MAC runs after auth (so the `smileid-*` headers + timestamp it
@@ -138,6 +150,7 @@ export function makeNetworkingFactory(
   const cryptoManager = new SmileIDCryptoManager(signingSecret());
   const requestMacInterceptor = new SmileRequestMacInterceptor({
     cryptoManager,
+    securityPolicy,
   });
   requestMacInterceptor.attach(client);
 

package/src/data/repository/__tests__/network_retries.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it, vi } from "vitest";
+import { AxiosError, AxiosHeaders } from "axios";
+
+import { UseSmileIDRepositoryImpl } from "../use_smile_id_repository_impl";
+import {
+  RetryStrategy,
+  type RetryConfig,
+} from "../../dsl/builder/retry_config_builder";
+import { JobType } from "../../../core/models/job_type";
+import { UseSmileIDMetadata } from "../../../metadata/use_smile_id_metadata";
+import type { EnhancedKycRequest } from "../../model/job_request";
+import type { JobSubmissionResponse } from "../../model/job_submission_response";
+import type { ConsentInformation } from "../../../core/models/params";
+
+// This file intentionally does NOT mock axios: it exercises the real retry
+// classifier (`isRetryable` → `axios.isAxiosError`) so a genuine retry happens
+// and `network_retries` can be observed on the stamped metadata.
+
+const FIXED_RETRY: RetryConfig = Object.freeze({
+  maxAttempts: 2,
+  strategy: RetryStrategy.fixed,
+  initialDelay: 0,
+  multiplier: 1,
+  maxDelay: 0,
+  jitter: 0,
+  fixedDelay: 0,
+});
+
+const CONSENT: ConsentInformation = Object.freeze({
+  granted: true,
+  grantedAt: "2026-04-30T00:00:00.000Z",
+  noticeLanguage: "EN",
+  noticePrivacyPolicyUrl: "https://example.test/p",
+});
+
+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",
+});
+
+function makeAxiosError(status: number): AxiosError {
+  return new AxiosError("boom", `${status}`, undefined, undefined, {
+    status,
+    statusText: "X",
+    data: undefined,
+    headers: {},
+    config: { headers: new AxiosHeaders() },
+  });
+}
+
+function networkRetriesOf(metadata: UseSmileIDMetadata): string | undefined {
+  return metadata.toEntries().find((e) => e.name === "network_retries")?.value;
+}
+
+describe("UseSmileIDRepositoryImpl — network_retries", () => {
+  it("stamps network_retries on the retried attempt and omits it on the first", async () => {
+    const response: JobSubmissionResponse = {
+      jobId: "job-1",
+      userId: "user-1",
+      status: "approved",
+      message: "ok",
+    };
+    const seenRetries: (string | undefined)[] = [];
+    const enhancedKyc = vi
+      .fn()
+      .mockImplementation((request: EnhancedKycRequest) => {
+        seenRetries.push(networkRetriesOf(request.metadata));
+        // Fail the first attempt with a retryable 500, succeed on the retry.
+        if (enhancedKyc.mock.calls.length === 1) {
+          return Promise.reject(makeAxiosError(500));
+        }
+        return Promise.resolve(response);
+      });
+    const stubApi = {
+      enhancedKyc,
+      biometricKyc: vi.fn(),
+      smartSelfieEnrollment: vi.fn(),
+      smartSelfieAuthentication: vi.fn(),
+      documentVerification: vi.fn(),
+      enhancedDocumentVerification: vi.fn(),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any;
+    const repository = new UseSmileIDRepositoryImpl(stubApi, FIXED_RETRY);
+    const request: EnhancedKycRequest = {
+      jobType: JobType.enhancedKyc,
+      params: { idType: "NIN", idNumber: "1", country: "NG" },
+      userDetails: { givenNames: "A", lastName: "B", email: "a@b.test" },
+      consent: CONSENT,
+      metadata: METADATA,
+    };
+
+    const result = await repository.submit(request);
+
+    expect(result.status).toBe("success");
+    expect(enhancedKyc).toHaveBeenCalledTimes(2);
+    // First attempt: no retries yet. Retry attempt: one retry preceded it.
+    expect(seenRetries).toEqual([undefined, "1"]);
+  });
+});

package/src/data/repository/use_smile_id_repository_impl.ts

@@ -12,6 +12,29 @@ import {
   mapAxiosError,
   type UseSmileIDNetworkException,
 } from "../../core/exception/use_smile_id_network_exception";
+import {
+  PayloadCompressionRunner,
+  type PayloadCompressionSizes,
+} from "../compression/payload_compression_runner";
+import type { MetadataEntry } from "../../metadata/use_smile_id_metadata";
+
+/** Builds the per-image original/final compressed size wire entries, omitting absent/zero sizes. */
+function compressionSizeEntries(
+  sizes: PayloadCompressionSizes,
+): MetadataEntry[] {
+  const entries: MetadataEntry[] = [];
+  const push = (name: string, value: number | undefined) => {
+    if (value !== undefined && value > 0)
+      entries.push({ name, value: String(value) });
+  };
+  push("selfie_original_size", sizes.selfieOriginalMb);
+  push("selfie_final_compressed_size", sizes.selfieFinalMb);
+  push("document_front_original_size", sizes.frontOriginalMb);
+  push("document_front_final_compressed_size", sizes.frontFinalMb);
+  push("document_back_original_size", sizes.backOriginalMb);
+  push("document_back_final_compressed_size", sizes.backFinalMb);
+  return entries;
+}
 
 /**
  * Concrete repository.
@@ -45,9 +68,28 @@ export class UseSmileIDRepositoryImpl {
         }),
       );
     }
+
+    // Pre-flight payload compression — best effort: shrink the captured JPEGs under the Lambda
+    // cap before transmission (runs once, outside the retry loop), but never block submission, so
+    // any compression failure ships the captured images as-is and lets the server validate. The
+    // per-image original + final compressed sizes are stamped onto the metadata for telemetry.
+    let submitted = request;
     try {
-      const response = await withRetry(this._retry, () =>
-        this._dispatch(request),
+      const sizes = await this._compressPayload(request);
+      const sizeEntries = sizes ? compressionSizeEntries(sizes) : [];
+      if (sizeEntries.length > 0) {
+        submitted = {
+          ...request,
+          metadata: request.metadata.withAdditionalEntries(sizeEntries),
+        };
+      }
+    } catch {
+      // Best-effort: compression is an optimization; submit the captured images as-is on failure.
+    }
+
+    try {
+      const response = await withRetry(this._retry, (attempt) =>
+        this._dispatch(submitted, attempt),
       );
       return success(response);
     } catch (error) {
@@ -62,22 +104,67 @@ export class UseSmileIDRepositoryImpl {
     }
   }
 
+  /**
+   * Pre-flight payload compression entry — extracts the captured image URIs for the job type and
+   * compresses the bundle under the transmission cap (metadata is measured, never modified).
+   * No-op for job types that carry no captured images (Enhanced KYC / BVN).
+   */
+  private async _compressPayload(
+    request: JobRequest,
+  ): Promise<PayloadCompressionSizes | undefined> {
+    const metadataBytes = JSON.stringify(request.metadata.toEntries()).length;
+    switch (request.jobType) {
+      case JobType.smartSelfieEnrollment:
+      case JobType.smartSelfieAuthentication:
+      case JobType.biometricKyc:
+        return PayloadCompressionRunner.compress({
+          selfieImage: request.selfieImage,
+          livenessImages: request.livenessImages,
+          metadataBytes,
+        });
+      case JobType.documentVerification:
+      case JobType.enhancedDocumentVerification:
+        return PayloadCompressionRunner.compress({
+          selfieImage: request.selfieImage,
+          livenessImages: request.livenessImages,
+          frontDocument: request.frontDocument,
+          backDocument: request.backDocument,
+          metadataBytes,
+        });
+      default:
+        return undefined;
+    }
+  }
+
   private _dispatch(
     request: Exclude<JobRequest, { jobType: typeof JobType.bvn }>,
+    attempt: number,
   ): Promise<JobSubmissionResponse> {
-    switch (request.jobType) {
+    // Stamp how many network retries preceded this attempt onto the metadata
+    // (re-evaluated per attempt inside the retry loop). Appended as a flow-state
+    // entry so the already-appended document / config entries are preserved.
+    const stamped: typeof request =
+      attempt > 0
+        ? {
+            ...request,
+            metadata: request.metadata.withAdditionalEntries([
+              { name: "network_retries", value: String(attempt) },
+            ]),
+          }
+        : request;
+    switch (stamped.jobType) {
       case JobType.smartSelfieEnrollment:
-        return this._api.smartSelfieEnrollment(request);
+        return this._api.smartSelfieEnrollment(stamped);
       case JobType.smartSelfieAuthentication:
-        return this._api.smartSelfieAuthentication(request);
+        return this._api.smartSelfieAuthentication(stamped);
       case JobType.enhancedKyc:
-        return this._api.enhancedKyc(request);
+        return this._api.enhancedKyc(stamped);
       case JobType.biometricKyc:
-        return this._api.biometricKyc(request);
+        return this._api.biometricKyc(stamped);
       case JobType.documentVerification:
-        return this._api.documentVerification(request);
+        return this._api.documentVerification(stamped);
       case JobType.enhancedDocumentVerification:
-        return this._api.enhancedDocumentVerification(request);
+        return this._api.enhancedDocumentVerification(stamped);
     }
   }
 

package/src/data/security/__tests__/security_policy.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+
+import { SecurityPolicy } from "../security_policy";
+
+/**
+ * Pins down the server-driven security policy bit-code mapping (the contract lives in
+ * `docs/Policy.md`):
+ *   - `undefined` is fail-secure (every behaviour active).
+ *   - bit 0 -> payload signing, bit 1 -> payload encryption, bit 2 -> rooted-device check,
+ *     bit 3 -> device attestation (least-significant bit first).
+ *   - Unrelated bits never cross-activate a behaviour.
+ */
+describe("SecurityPolicy", () => {
+  it("undefined bit-code is fail-secure and enables every behaviour", () => {
+    const policy = SecurityPolicy.fromBitCode(undefined);
+
+    expect(policy.isPayloadSigningActive()).toBe(true);
+    expect(policy.isPayloadEncryptionActive()).toBe(true);
+    expect(policy.isRootedDeviceCheckActive()).toBe(true);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(true);
+  });
+
+  it("zero bit-code disables every behaviour", () => {
+    const policy = SecurityPolicy.fromBitCode(0);
+
+    expect(policy.isPayloadSigningActive()).toBe(false);
+    expect(policy.isPayloadEncryptionActive()).toBe(false);
+    expect(policy.isRootedDeviceCheckActive()).toBe(false);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(false);
+  });
+
+  it("bit 0 maps to payload signing only", () => {
+    const policy = SecurityPolicy.fromBitCode(0b0001);
+
+    expect(policy.isPayloadSigningActive()).toBe(true);
+    expect(policy.isPayloadEncryptionActive()).toBe(false);
+    expect(policy.isRootedDeviceCheckActive()).toBe(false);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(false);
+  });
+
+  it("bit 1 maps to payload encryption only", () => {
+    const policy = SecurityPolicy.fromBitCode(0b0010);
+
+    expect(policy.isPayloadSigningActive()).toBe(false);
+    expect(policy.isPayloadEncryptionActive()).toBe(true);
+    expect(policy.isRootedDeviceCheckActive()).toBe(false);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(false);
+  });
+
+  it("bit 2 maps to rooted-device check only", () => {
+    const policy = SecurityPolicy.fromBitCode(0b0100);
+
+    expect(policy.isPayloadSigningActive()).toBe(false);
+    expect(policy.isPayloadEncryptionActive()).toBe(false);
+    expect(policy.isRootedDeviceCheckActive()).toBe(true);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(false);
+  });
+
+  it("bit 3 maps to play integrity check only", () => {
+    const policy = SecurityPolicy.fromBitCode(0b1000);
+
+    expect(policy.isPayloadSigningActive()).toBe(false);
+    expect(policy.isPayloadEncryptionActive()).toBe(false);
+    expect(policy.isRootedDeviceCheckActive()).toBe(false);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(true);
+  });
+
+  it("combined bit-code activates exactly the set behaviours", () => {
+    // 0b1001 = payload signing (bit 0) + device attestation (bit 3).
+    const policy = SecurityPolicy.fromBitCode(0b1001);
+
+    expect(policy.isPayloadSigningActive()).toBe(true);
+    expect(policy.isPayloadEncryptionActive()).toBe(false);
+    expect(policy.isRootedDeviceCheckActive()).toBe(false);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(true);
+  });
+
+  it("all four bits set activates every behaviour", () => {
+    const policy = SecurityPolicy.fromBitCode(0b1111);
+
+    expect(policy.isPayloadSigningActive()).toBe(true);
+    expect(policy.isPayloadEncryptionActive()).toBe(true);
+    expect(policy.isRootedDeviceCheckActive()).toBe(true);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(true);
+  });
+
+  it("higher unmapped bits do not affect the known behaviours", () => {
+    // bit 4 (0b10000) is beyond the defined mapping; the four known behaviours stay off.
+    const policy = SecurityPolicy.fromBitCode(0b10000);
+
+    expect(policy.isPayloadSigningActive()).toBe(false);
+    expect(policy.isPayloadEncryptionActive()).toBe(false);
+    expect(policy.isRootedDeviceCheckActive()).toBe(false);
+    expect(policy.isPlayIntegrityCheckActive()).toBe(false);
+  });
+});

package/src/data/security/__tests__/smile_id_crypto_manager.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import { SigningCrypto, base64Encode, utf8Bytes } from "../signing_crypto";
 import { SmileIDCryptoManager } from "../smile_id_crypto_manager";
+import { SmileIDCryptoError } from "../smile_id_crypto_error";
 
 /**
  * Pins down the request-signing contract:
@@ -58,6 +59,23 @@ describe("SmileIDCryptoManager", () => {
     expect(mac).toBe("nW0HenQOrKH/qAwQBveK+TSXvg70oVWfD0aGGtfI1bk=");
   });
 
+  it("wraps an unreadable file part as SmileIDCryptoError (signing fails open, never crashes)", async () => {
+    // A `file://` URI the runtime's `fetch` rejects — the same rejection a
+    // captured-image local read produces when the device is offline (Expo vs
+    // bare-RN runtimes differ here). The canonicalizer must surface it as a
+    // SmileIDCryptoError so the request-MAC interceptor's narrow catch fails
+    // open instead of letting the rejection escape and crash the submission.
+    await expect(
+      subject.sign(
+        TIMESTAMP,
+        KAT_HEADERS,
+        formData([
+          { fieldName: "selfie_image", uri: "file:///nonexistent/selfie.jpg" },
+        ]),
+      ),
+    ).rejects.toBeInstanceOf(SmileIDCryptoError);
+  });
+
   it("multipart body MAC is independent of part order", async () => {
     const headers = { "smileid-request-timestamp": TIMESTAMP };
     const first = await subject.sign(