@smileid/usesmileid 12.0.0-beta01 → 12.0.1

package/src/core/models/global_privacy_control.ts

@@ -0,0 +1,45 @@
+/**
+ * Partner-declared Global Privacy Control posture for the consent screen
+ * (`global_privacy_control` on the wire).
+ *
+ * Native mobile platforms expose no OS-level equivalent of the web's GPC
+ * signal, so the SDK performs no runtime user-signal tracking: the partner
+ * declares the posture once at initialization
+ * (`b.config((c) => { c.globalPrivacyControl = ...; })`) and it governs
+ * every session.
+ *
+ * Const-object pattern (see `KameraEventType`-style types): enum ergonomics,
+ * string wire format.
+ */
+export const GlobalPrivacyControl = {
+  /**
+   * Default. Forces the opt-out consent layout universally: consent starts
+   * granted (pre-selected) for every session regardless of region — the
+   * user unticks to opt out. Regional detection is never consulted.
+   */
+  OptOut: "opt-out",
+
+  /**
+   * Legacy regional mechanics: consent starts granted outside the EU and
+   * starts ungranted (explicit opt-in required) when the device locale is
+   * an EU member state.
+   */
+  OptIn: "opt-in",
+} as const;
+export type GlobalPrivacyControl =
+  (typeof GlobalPrivacyControl)[keyof typeof GlobalPrivacyControl];
+
+/** Configuration key this setting is transported under. */
+export const GLOBAL_PRIVACY_CONTROL_WIRE_KEY = "global_privacy_control";
+
+/**
+ * Parses a wire value ("opt-out" / "opt-in"); anything else falls back to
+ * the `OptOut` baseline default.
+ */
+export function globalPrivacyControlFromWire(
+  value: string | null | undefined,
+): GlobalPrivacyControl {
+  return value === GlobalPrivacyControl.OptIn
+    ? GlobalPrivacyControl.OptIn
+    : GlobalPrivacyControl.OptOut;
+}

package/src/core/models/network_config.ts

@@ -97,10 +97,10 @@ export type CacheConfig = {
 };
 
 /**
- * Retry strategy.
+ * Retry strategy. `none` is the default.
+ *   - `none`: one attempt, no retry — `maxAttempts` is forced to 1
  *   - `exponential`: `delay = min(initialDelay × multiplier^attempt, maxDelay)` plus `±jitter`
  *   - `fixed`: constant `fixedDelay` between attempts
- *   - `none`: no retry (`maxAttempts: 1`)
  */
 export enum RetryStrategy {
   exponential = "exponential",

package/src/core/models/result.ts

@@ -1,31 +1,32 @@
 /**
- * A result type for SDK operations that makes error handling explicit.
+ * The outcome of an SDK operation: success with a value, failure with an
+ * error, or cancellation when the user exits the flow. Surfaced to
+ * partners through `onResult`.
  *
  * Partners never need to unwrap a `UseSmileIDResult` directly — all
  * errors are automatically surfaced through the `onResult` callback.
  * The discriminated union lets partner code `switch (result.status)`
- * and exhaust both branches without try/catch ceremony.
+ * and exhaust the branches without try/catch ceremony.
  */
 export type UseSmileIDResult<T> =
   | { readonly status: "success"; readonly value: T }
   | { readonly status: "failure"; readonly error: unknown }
   | { readonly status: "cancelled" };
 
-/** Construct a successful result carrying `value`. */
+/** A successful outcome carrying the resulting value. */
 export function success<T>(value: T): UseSmileIDResult<T> {
   return { status: "success", value };
 }
 
-/** Construct a failed result carrying `error`. */
+/** A failed outcome carrying the causing error. */
 export function failure<T>(error: unknown): UseSmileIDResult<T> {
   return { status: "failure", error };
 }
 
 /**
- * Construct a cancelled result — the user deliberately exited the flow
- * (e.g. back-pressed out of the first screen) without completing or
- * failing. Distinct from `failure` so partners can tell a user
- * cancellation apart from an error.
+ * The user deliberately exited the flow without completing or failing it
+ * (e.g. back-pressed out of the first screen) — distinct from a failure
+ * so cancellation can be handled separately.
  */
 export function cancelled<T>(): UseSmileIDResult<T> {
   return { status: "cancelled" };

package/src/data/api/__tests__/smile_id_api.test.ts

@@ -109,7 +109,7 @@ const consent: ConsentInformation = Object.freeze({
 // builds this and it travels on every `JobRequest`; the API
 // serializes `request.metadata` as the `metadata` multipart part.
 const metadata = new UseSmileIDMetadata({
-  sdkVersion: "12.0.0",
+  sdkVersion: "12.0.1",
   sdk: "react-native-expo",
   deviceOs: "",
   deviceModel: "",

package/src/data/api/interceptors/__tests__/gzip_interceptor.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import axios, { AxiosHeaders, type InternalAxiosRequestConfig } from "axios";
+
+import { createGzipInterceptor } from "../gzip_interceptor";
+
+/**
+ * Pins `createGzipInterceptor`'s wire shape: it stamps `Accept-Encoding: gzip` on every request
+ * (never reading `config.data`), leaves the body unmodified (no compression, no Content-Type/
+ * Length), never sets `Content-Encoding`, and overwrites any existing `Accept-Encoding`.
+ */
+describe("createGzipInterceptor", () => {
+  function attachAndRun(
+    config: InternalAxiosRequestConfig,
+  ): Promise<InternalAxiosRequestConfig> {
+    const client = axios.create();
+    createGzipInterceptor().attach(client);
+    const handlers = (
+      client.interceptors.request as unknown as {
+        handlers: {
+          fulfilled?: (
+            cfg: InternalAxiosRequestConfig,
+          ) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>;
+        }[];
+      }
+    ).handlers;
+    const fulfilled = handlers[handlers.length - 1]?.fulfilled;
+    if (!fulfilled) throw new Error("gzip interceptor did not register");
+    return Promise.resolve(fulfilled(config));
+  }
+
+  it("stamps Accept-Encoding: gzip on a bodyless request", async () => {
+    const result = await attachAndRun({
+      headers: new AxiosHeaders(),
+    } as InternalAxiosRequestConfig);
+
+    expect(result.headers.get("Accept-Encoding")).toBe("gzip");
+    expect(result.data).toBeUndefined();
+  });
+
+  it("stamps the header without touching a JSON string body", async () => {
+    const result = await attachAndRun({
+      headers: new AxiosHeaders(),
+      data: '{"hello":"world"}',
+    } as InternalAxiosRequestConfig);
+
+    expect(result.headers.get("Accept-Encoding")).toBe("gzip");
+    // The body is not compressed or otherwise transformed.
+    expect(result.data).toBe('{"hello":"world"}');
+    expect(result.headers.get("Content-Type")).toBeUndefined();
+  });
+
+  it("stamps the header without touching a multipart FormData body", async () => {
+    // A minimal FormData-like stand-in; the interceptor never inspects
+    // `config.data`'s shape, so this is enough to prove pass-through.
+    const formData = { getParts: () => [] };
+    const result = await attachAndRun({
+      headers: new AxiosHeaders(),
+      data: formData,
+    } as unknown as InternalAxiosRequestConfig);
+
+    expect(result.headers.get("Accept-Encoding")).toBe("gzip");
+    expect(result.data).toBe(formData);
+    expect(result.headers.get("Content-Type")).toBeUndefined();
+    expect(result.headers.get("Content-Length")).toBeUndefined();
+  });
+
+  it("never stamps Content-Encoding — the request body itself is never compressed", async () => {
+    const result = await attachAndRun({
+      headers: new AxiosHeaders(),
+      data: '{"hello":"world"}',
+    } as InternalAxiosRequestConfig);
+
+    expect(result.headers.get("Content-Encoding")).toBeUndefined();
+  });
+
+  it("overwrites an Accept-Encoding value set by an earlier interceptor", async () => {
+    const result = await attachAndRun({
+      headers: new AxiosHeaders({ "Accept-Encoding": "identity" }),
+    } as InternalAxiosRequestConfig);
+
+    expect(result.headers.get("Accept-Encoding")).toBe("gzip");
+  });
+});

package/src/data/api/interceptors/__tests__/smile_integrity_interceptor.test.ts

@@ -20,6 +20,7 @@ import {
   ATTESTATION_OPT_IN_KEY,
 } from "../smile_integrity_interceptor";
 import { REQUEST_MAC_HEADER } from "../smile_request_mac_interceptor";
+import { SecurityPolicy } from "../../../security/security_policy";
 
 /**
  * Pins down the integrity interceptor's wire shape:
@@ -51,7 +52,10 @@ describe("SmileIntegrityInterceptor", () => {
 
   beforeEach(() => {
     client = axios.create();
-    interceptor = new SmileIntegrityInterceptor();
+    // undefined bit-code is fail-secure: the attestation check is active, matching the pre-policy default.
+    interceptor = new SmileIntegrityInterceptor({
+      securityPolicy: SecurityPolicy.fromBitCode(undefined),
+    });
     interceptor.attach(client);
     warmUpAttestation = vi.fn();
     requestAttestationToken = vi.fn();
@@ -153,4 +157,36 @@ describe("SmileIntegrityInterceptor", () => {
     expect(ex.message).toBe("hello world");
     expect(encodeURIComponent(ex.message)).toBe("hello%20world");
   });
+
+  it("passes through without a nonce when policy disables attestation", async () => {
+    // bit-code 1: only payload signing (bit 0) set; the attestation bit (3) is off, so the token
+    // must not be requested even though the MAC header is present.
+    const localClient = axios.create();
+    new SmileIntegrityInterceptor({
+      securityPolicy: SecurityPolicy.fromBitCode(1),
+    }).attach(localClient);
+    const config = makeConfig({
+      [ATTESTATION_OPT_IN_KEY]: true,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+    config.headers.set(REQUEST_MAC_HEADER, "mac-abc");
+
+    const handlers = (
+      localClient.interceptors.request as unknown as {
+        handlers: {
+          fulfilled?: (cfg: InternalAxiosRequestConfig) => unknown;
+        }[];
+      }
+    ).handlers;
+    let current = config;
+    for (let i = handlers.length - 1; i >= 0; i--) {
+      const handler = handlers[i]?.fulfilled;
+      if (typeof handler === "function") {
+        current = (await handler(current)) as InternalAxiosRequestConfig;
+      }
+    }
+
+    expect(current.headers.get(DEVICE_NONCE_HEADER)).toBeUndefined();
+    expect(requestAttestationToken).not.toHaveBeenCalled();
+  });
 });

package/src/data/api/interceptors/__tests__/smile_request_mac_interceptor.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it, beforeEach } from "vitest";
 import axios, { AxiosHeaders, type InternalAxiosRequestConfig } from "axios";
 
 import { SmileIDCryptoManager } from "../../../security/smile_id_crypto_manager";
+import { SecurityPolicy } from "../../../security/security_policy";
 import {
   SmileRequestMacInterceptor,
   REQUEST_MAC_HEADER,
@@ -26,7 +27,11 @@ describe("SmileRequestMacInterceptor", () => {
 
   beforeEach(() => {
     client = axios.create();
-    interceptor = new SmileRequestMacInterceptor({ cryptoManager });
+    // undefined bit-code is fail-secure: payload signing is active, matching the pre-policy default.
+    interceptor = new SmileRequestMacInterceptor({
+      cryptoManager,
+      securityPolicy: SecurityPolicy.fromBitCode(undefined),
+    });
     interceptor.attach(client);
   });
 
@@ -95,4 +100,57 @@ describe("SmileRequestMacInterceptor", () => {
     );
     expect(result.headers.get(REQUEST_MAC_HEADER)).toBeUndefined();
   });
+
+  /** Drive a one-interceptor client built with a specific policy. */
+  async function runWith(
+    policy: SecurityPolicy,
+    config: InternalAxiosRequestConfig,
+  ): Promise<InternalAxiosRequestConfig> {
+    const localClient = axios.create();
+    new SmileRequestMacInterceptor({
+      cryptoManager,
+      securityPolicy: policy,
+    }).attach(localClient);
+    const handlers = (
+      localClient.interceptors.request as unknown as {
+        handlers: {
+          fulfilled?: (cfg: InternalAxiosRequestConfig) => unknown;
+        }[];
+      }
+    ).handlers;
+    let current = config;
+    for (let i = handlers.length - 1; i >= 0; i--) {
+      const handler = handlers[i]?.fulfilled;
+      if (typeof handler === "function") {
+        current = (await handler(current)) as InternalAxiosRequestConfig;
+      }
+    }
+    return current;
+  }
+
+  it("leaves the request unsigned when the policy disables payload signing", async () => {
+    // bit-code 0: no bits set, so payload signing is off for this session.
+    const result = await runWith(
+      SecurityPolicy.fromBitCode(0),
+      makeConfig({
+        data: '{"hello":"world"}',
+        headers: new AxiosHeaders({ [REQUEST_TIMESTAMP_HEADER]: TIMESTAMP }),
+        [REQUEST_MAC_OPT_IN_KEY]: true,
+      } as Partial<InternalAxiosRequestConfig>),
+    );
+    expect(result.headers.get(REQUEST_MAC_HEADER)).toBeUndefined();
+  });
+
+  it("signs when the policy enables only payload signing", async () => {
+    // bit-code 1: bit 0 (payload signing) set; other behaviours off.
+    const result = await runWith(
+      SecurityPolicy.fromBitCode(1),
+      makeConfig({
+        data: '{"hello":"world"}',
+        headers: new AxiosHeaders({ [REQUEST_TIMESTAMP_HEADER]: TIMESTAMP }),
+        [REQUEST_MAC_OPT_IN_KEY]: true,
+      } as Partial<InternalAxiosRequestConfig>),
+    );
+    expect(result.headers.get(REQUEST_MAC_HEADER)).toBeDefined();
+  });
 });

package/src/data/api/interceptors/smile_auth_interceptor.ts

@@ -1,5 +1,5 @@
 import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
-import { Platform } from "react-native";
+import { sourceSdkIdentifier } from "@smileid/usesmileid_bridge";
 
 import type { PartnerConfig } from "../../../core/models/network_config";
 import { currentRequestTimestamp } from "../../security/request_timestamp";
@@ -26,22 +26,7 @@ import type { TokenHolder } from "../auth/token_holder";
  * by the next outgoing request.
  */
 
-const SDK_VERSION = "12.0.0-beta01";
-
-/**
- * Source-SDK identifier, suffixed with the runtime platform so the server can
- * attribute the request and resolve the matching per-SDK signing secret.
- */
-function sourceSdk(): string {
-  switch (Platform.OS) {
-    case "android":
-      return "react-native-expo (android)";
-    case "ios":
-      return "react-native-expo (iOS)";
-    default:
-      return "react-native-expo";
-  }
-}
+const SDK_VERSION = "12.0.1";
 
 export type SmileAuthInterceptorOptions = {
   readonly partnerConfig: PartnerConfig;
@@ -73,7 +58,7 @@ export class SmileAuthInterceptor {
     config: InternalAxiosRequestConfig,
   ): Promise<InternalAxiosRequestConfig> {
     config.headers.set("smileid-token", this._tokenHolder.current);
-    config.headers.set("smileid-source-sdk", sourceSdk());
+    config.headers.set("smileid-source-sdk", sourceSdkIdentifier());
     config.headers.set("smileid-source-sdk-version", SDK_VERSION);
     config.headers.set("smileid-partner-id", this._partnerConfig.partnerId);
     if (this._partnerConfig.callbackUrl) {

package/src/data/api/interceptors/smile_integrity_interceptor.ts

@@ -2,6 +2,7 @@ import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
 
 import { Attestation, AttestationException } from "@smileid/usesmileid_bridge";
 
+import type { SecurityPolicy } from "../../security/security_policy";
 import { REQUEST_MAC_HEADER } from "./smile_request_mac_interceptor";
 
 /**
@@ -31,6 +32,11 @@ import { REQUEST_MAC_HEADER } from "./smile_request_mac_interceptor";
  * Warm-up lives outside the interceptor. Call `Attestation.warmUp()`
  * once at flow mount so the per-request `requestToken` call doesn't
  * pay the multi-second warm-up cost on every submission.
+ *
+ * Attestation is additionally gated by the server-driven {@link SecurityPolicy}:
+ * when the session's policy disables the device-attestation check, an opted-in
+ * request ships without a device nonce. The policy is fail-secure, so a token
+ * that omits the claim attests as before.
  */
 
 export const DEVICE_NONCE_HEADER = "smileid-device-nonce";
@@ -38,7 +44,17 @@ export const DEVICE_NONCE_HEADER = "smileid-device-nonce";
 /** Axios config key that opts a request into attestation stamping. */
 export const ATTESTATION_OPT_IN_KEY = "_useSmileIDAttestation";
 
+export type SmileIntegrityInterceptorOptions = {
+  readonly securityPolicy: SecurityPolicy;
+};
+
 export class SmileIntegrityInterceptor {
+  private readonly _securityPolicy: SecurityPolicy;
+
+  constructor(options: SmileIntegrityInterceptorOptions) {
+    this._securityPolicy = options.securityPolicy;
+  }
+
   attach(client: AxiosInstance): { request: number } {
     const requestId = client.interceptors.request.use(async (config) => {
       return this._onRequest(config);
@@ -55,6 +71,10 @@ export class SmileIntegrityInterceptor {
       ] === true;
     if (!optedIn) return config;
 
+    // Server-driven policy can switch device attestation off for this session; when it is off,
+    // ship the opted-in request without requesting a token.
+    if (!this._securityPolicy.isPlayIntegrityCheckActive()) return config;
+
     const macHeader = config.headers.get(REQUEST_MAC_HEADER);
     if (typeof macHeader !== "string") return config;
 

package/src/data/api/interceptors/smile_request_mac_interceptor.ts

@@ -2,6 +2,7 @@ import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
 
 import { SmileIDCryptoError } from "../../security/smile_id_crypto_error";
 import type { SmileIDCryptoManager } from "../../security/smile_id_crypto_manager";
+import type { SecurityPolicy } from "../../security/security_policy";
 
 /**
  * Stamps the `smileid-request-mac` header on every outbound request whose axios
@@ -18,6 +19,11 @@ import type { SmileIDCryptoManager } from "../../security/smile_id_crypto_manage
  * rather than signed against an invented timestamp.
  *
  * Requests without the opt-in flag pass through unchanged.
+ *
+ * Signing is additionally gated by the server-driven {@link SecurityPolicy}: when the session's
+ * policy disables payload signing, an opted-in request still ships, just unsigned — the same wire
+ * shape as an opt-out request. The policy is fail-secure, so a token that omits the claim signs as
+ * before.
  */
 
 export const REQUEST_MAC_HEADER = "smileid-request-mac";
@@ -28,13 +34,16 @@ export const REQUEST_MAC_OPT_IN_KEY = "_useSmileIDRequestMac";
 
 export type SmileRequestMacInterceptorOptions = {
   readonly cryptoManager: SmileIDCryptoManager;
+  readonly securityPolicy: SecurityPolicy;
 };
 
 export class SmileRequestMacInterceptor {
   private readonly _cryptoManager: SmileIDCryptoManager;
+  private readonly _securityPolicy: SecurityPolicy;
 
   constructor(options: SmileRequestMacInterceptorOptions) {
     this._cryptoManager = options.cryptoManager;
+    this._securityPolicy = options.securityPolicy;
   }
 
   attach(client: AxiosInstance): { request: number } {
@@ -53,6 +62,10 @@ export class SmileRequestMacInterceptor {
       ] === true;
     if (!optedIn) return config;
 
+    // Server-driven policy can switch payload signing off for this session; when it is off, ship
+    // the opted-in request unsigned and let the server apply its policy.
+    if (!this._securityPolicy.isPayloadSigningActive()) return config;
+
     const timestamp = config.headers.get(REQUEST_TIMESTAMP_HEADER);
     if (typeof timestamp !== "string") return config;
 

package/src/data/compression/__tests__/payload_compressor.test.ts

@@ -0,0 +1,200 @@
+import { ImageType, type ImageTypeId } from "@smileid/usesmileid_bridge";
+import { describe, expect, it } from "vitest";
+
+import {
+  type CompressibleAsset,
+  CompressibleAssets,
+} from "../compressible_asset";
+import {
+  base64Len,
+  PayloadCompressionConfig as C,
+} from "../payload_compression_config";
+import { PayloadCompressor } from "../payload_compressor";
+
+const mib = C.bytesPerMB;
+
+/** Encoded size scales linearly with quality: `size(q) = base * q`. */
+class FakeAsset implements CompressibleAsset {
+  recompressCount = 0;
+  private q: number;
+  constructor(
+    readonly imageType: ImageTypeId,
+    private readonly base: number,
+    startQuality: number,
+  ) {
+    this.q = startQuality;
+  }
+  encodedSize(): number {
+    return Math.trunc(this.base * this.q);
+  }
+  quality(): number {
+    return this.q;
+  }
+  async recompress(quality: number): Promise<void> {
+    this.q = quality;
+    this.recompressCount += 1;
+  }
+}
+
+describe("PayloadCompressor", () => {
+  it("base64Len matches ceil(n / 3) * 4", () => {
+    expect(base64Len(0)).toBe(0);
+    expect(base64Len(1)).toBe(4);
+    expect(base64Len(3)).toBe(4);
+    expect(base64Len(4)).toBe(8);
+    expect(base64Len(6)).toBe(8);
+    expect(base64Len(3_000_000)).toBe(Math.ceil(3_000_000 / 3) * 4);
+  });
+
+  it("raw and projected sizes sum images plus metadata", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 300_000, 1.0),
+      liveness: [new FakeAsset(ImageType.Liveness, 100_000, 1.0)],
+    });
+    const metadata = 50_000;
+    expect(PayloadCompressor.rawBundleSize(assets, metadata)).toBe(
+      300_000 + 100_000 + 50_000,
+    );
+    expect(PayloadCompressor.projectedEncodedSize(assets, metadata)).toBe(
+      base64Len(300_000) +
+        base64Len(100_000) +
+        metadata +
+        C.structuralOverheadBytes,
+    );
+  });
+
+  it("plan order Rule B - selfie over 1MB compresses faces first then back then front", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 2 * mib, 0.95),
+      liveness: [new FakeAsset(ImageType.Liveness, mib, 0.8)],
+      documentFront: new FakeAsset(ImageType.DocumentFront, mib, 0.85),
+      documentBack: new FakeAsset(ImageType.DocumentBack, mib, 0.85),
+    });
+    const plan = PayloadCompressor.buildCompressionPlan(assets);
+    expect(plan.map(([a]) => a.imageType)).toEqual([
+      ImageType.Selfie,
+      ImageType.Liveness,
+      ImageType.DocumentBack,
+      ImageType.DocumentFront,
+    ]);
+    expect(plan[0][1]).toBe(C.faceMinQ);
+    expect(plan[3][1]).toBe(C.docMinQ);
+  });
+
+  it("plan order Rule A - documents over 4MB compresses back, front, then faces", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 500_000, 0.95),
+      documentFront: new FakeAsset(ImageType.DocumentFront, 3 * mib, 0.9),
+      documentBack: new FakeAsset(ImageType.DocumentBack, 3 * mib, 0.9),
+    });
+    const plan = PayloadCompressor.buildCompressionPlan(assets);
+    expect(plan.map(([a]) => a.imageType)).toEqual([
+      ImageType.DocumentBack,
+      ImageType.DocumentFront,
+      ImageType.Selfie,
+    ]);
+  });
+
+  it("plan order generic - small selfie and docs uses faces then docs", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 400_000, 0.95),
+      documentFront: new FakeAsset(ImageType.DocumentFront, 400_000, 0.85),
+    });
+    const plan = PayloadCompressor.buildCompressionPlan(assets);
+    expect(plan.map(([a]) => a.imageType)).toEqual([
+      ImageType.Selfie,
+      ImageType.DocumentFront,
+    ]);
+  });
+
+  it("already small bundle is left untouched", async () => {
+    const selfie = new FakeAsset(ImageType.Selfie, mib, 0.95);
+    await PayloadCompressor.prepareBundleForTransmission(
+      new CompressibleAssets({ selfie }),
+      50_000,
+    );
+    expect(selfie.recompressCount).toBe(0);
+  });
+
+  it("over-budget bundle compresses under target and never breaches floors", async () => {
+    const selfie = new FakeAsset(
+      ImageType.Selfie,
+      Math.trunc((22 * mib) / 10),
+      0.95,
+    );
+    const liveness = [
+      new FakeAsset(ImageType.Liveness, Math.trunc((12 * mib) / 10), 0.8),
+      new FakeAsset(ImageType.Liveness, Math.trunc((12 * mib) / 10), 0.8),
+    ];
+    const assets = new CompressibleAssets({ selfie, liveness });
+    const metadata = Math.trunc((2 * mib) / 10);
+    await PayloadCompressor.prepareBundleForTransmission(assets, metadata);
+
+    expect(
+      PayloadCompressor.rawBundleSize(assets, metadata),
+    ).toBeLessThanOrEqual(C.rawFallback);
+    expect(selfie.quality()).toBeGreaterThanOrEqual(C.faceMinQ);
+    for (const frame of liveness)
+      expect(frame.quality()).toBeGreaterThanOrEqual(C.faceMinQ);
+  });
+
+  it("document-heavy bundle compresses back first and never breaches the doc floor", async () => {
+    const front = new FakeAsset(
+      ImageType.DocumentFront,
+      Math.trunc((23 * mib) / 10),
+      0.9,
+    );
+    const back = new FakeAsset(
+      ImageType.DocumentBack,
+      Math.trunc((23 * mib) / 10),
+      0.9,
+    );
+    const selfie = new FakeAsset(ImageType.Selfie, 400_000, 0.95);
+    const assets = new CompressibleAssets({
+      selfie,
+      documentFront: front,
+      documentBack: back,
+    });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    expect(back.quality()).toBeLessThanOrEqual(front.quality());
+    expect(front.quality()).toBeGreaterThanOrEqual(C.docMinQ);
+    expect(back.quality()).toBeGreaterThanOrEqual(C.docMinQ);
+    expect(
+      PayloadCompressor.rawBundleSize(assets, 100_000),
+    ).toBeLessThanOrEqual(C.rawTarget);
+  });
+
+  it("hard guarantee drops past the per-type floor to fit the relaxed cap", async () => {
+    // floor .45 -> 12MB*.45 = 5.4MB raw, still over the relaxed 4.5MB ceiling. The guarantee pass
+    // must step quality below faceMinQ until the bundle fits both caps.
+    const selfie = new FakeAsset(ImageType.Selfie, 12 * mib, 0.95);
+    const assets = new CompressibleAssets({ selfie });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    expect(
+      PayloadCompressor.rawBundleSize(assets, 100_000),
+    ).toBeLessThanOrEqual(C.rawFallback);
+    expect(
+      PayloadCompressor.projectedEncodedSize(assets, 100_000),
+    ).toBeLessThanOrEqual(C.hardEncodedCap);
+    expect(selfie.quality()).toBeLessThan(C.faceMinQ);
+    expect(selfie.quality()).toBeGreaterThanOrEqual(C.absoluteMinQ);
+  });
+
+  it("extreme bundle unreachable by quality drives to the absolute floor without throwing", async () => {
+    // So large that even absoluteMinQ leaves it over the cap (real JPEGs shrink far more than this
+    // linear fake). The guarantee pass drives to the absolute floor and ships — never loops forever.
+    const selfie = new FakeAsset(ImageType.Selfie, 80 * mib, 0.95);
+    const assets = new CompressibleAssets({ selfie });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    expect(selfie.quality()).toBe(C.absoluteMinQ);
+  });
+
+  it("bundle in fallback band with light metadata is accepted", async () => {
+    const selfie = new FakeAsset(ImageType.Selfie, 9 * mib, 0.95);
+    const assets = new CompressibleAssets({ selfie });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    const raw = PayloadCompressor.rawBundleSize(assets, 100_000);
+    expect(raw).toBeGreaterThan(C.rawTarget);
+    expect(raw).toBeLessThanOrEqual(C.rawFallback);
+  });
+});