@smileid/usesmileid 12.0.1 → 12.0.2

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

@@ -0,0 +1,203 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import Module from "node:module";
+
+import { SigningCrypto, base64Encode, utf8Bytes } from "../signing_crypto";
+import { SmileIDCryptoError } from "../smile_id_crypto_error";
+
+/**
+ * Provider resolution for request signing. Node supplies a global
+ * `crypto.subtle`, so the on-device path — the lazy
+ * `require("react-native-quick-crypto")` — is only reachable with the
+ * global removed and the CommonJS loader intercepted. `resolveSubtle`
+ * caches the first provider it finds, so these tests are ordered:
+ * the not-found case runs before anything is cached.
+ */
+
+type SubtleStub = {
+  importKey: ReturnType<typeof vi.fn>;
+  deriveBits: ReturnType<typeof vi.fn>;
+  sign: ReturnType<typeof vi.fn>;
+};
+
+type Loader = (id: string, parent: unknown, isMain: boolean) => unknown;
+const loaderHost = Module as unknown as { _load: Loader };
+const originalLoad: Loader = loaderHost._load;
+
+const QUICK_CRYPTO = "react-native-quick-crypto";
+
+let quickCryptoExports: unknown | null = null;
+let cryptoDescriptor: PropertyDescriptor | undefined;
+
+function makeSubtle(): SubtleStub {
+  return {
+    importKey: vi.fn(async () => ({ handle: "key" })),
+    deriveBits: vi.fn(async () => new Uint8Array(32).fill(7).buffer),
+    sign: vi.fn(async () => new Uint8Array(32).fill(9).buffer),
+  };
+}
+
+beforeAll(() => {
+  // Hermes exposes no global `crypto.subtle`; reproduce that here so the
+  // native-provider branch is the one under test.
+  cryptoDescriptor = Object.getOwnPropertyDescriptor(globalThis, "crypto");
+  Object.defineProperty(globalThis, "crypto", {
+    value: undefined,
+    configurable: true,
+    writable: true,
+  });
+  vi.spyOn(loaderHost, "_load").mockImplementation((id, parent, isMain) => {
+    if (id === QUICK_CRYPTO) {
+      if (quickCryptoExports === null) {
+        const error = new Error(
+          `Cannot find module '${QUICK_CRYPTO}'`,
+        ) as Error & {
+          code: string;
+        };
+        error.code = "MODULE_NOT_FOUND";
+        throw error;
+      }
+      return quickCryptoExports;
+    }
+    return originalLoad.call(Module, id, parent, isMain);
+  });
+});
+
+afterAll(() => {
+  vi.restoreAllMocks();
+  if (cryptoDescriptor) {
+    Object.defineProperty(globalThis, "crypto", cryptoDescriptor);
+  } else {
+    delete (globalThis as { crypto?: unknown }).crypto;
+  }
+});
+
+describe("SigningCrypto — encoding helpers", () => {
+  it("UTF-8 encodes multi-byte text", () => {
+    expect(Array.from(utf8Bytes("é"))).toEqual([0xc3, 0xa9]);
+  });
+
+  it("base64-encodes with the standard alphabet and padding", () => {
+    expect(base64Encode(utf8Bytes("any carnal pleasure"))).toBe(
+      "YW55IGNhcm5hbCBwbGVhc3VyZQ==",
+    );
+    expect(base64Encode(utf8Bytes("any carnal pleasur"))).toBe(
+      "YW55IGNhcm5hbCBwbGVhc3Vy",
+    );
+    expect(base64Encode(utf8Bytes("any carnal pleasu"))).toBe(
+      "YW55IGNhcm5hbCBwbGVhc3U=",
+    );
+    expect(base64Encode(new Uint8Array(0))).toBe("");
+  });
+});
+
+// Ordered: the not-found case must run before a provider is cached.
+describe("SigningCrypto — no provider available", () => {
+  it("fails key derivation with actionable install guidance", async () => {
+    quickCryptoExports = null;
+
+    await expect(
+      SigningCrypto.deriveKey("secret", new Uint8Array([1, 2, 3])),
+    ).rejects.toBeInstanceOf(SmileIDCryptoError);
+    await expect(
+      SigningCrypto.deriveKey("secret", new Uint8Array([1, 2, 3])),
+    ).rejects.toThrow(/react-native-quick-crypto/);
+  });
+
+  it("fails MAC computation the same way", async () => {
+    quickCryptoExports = null;
+
+    await expect(
+      SigningCrypto.hmacSha256(new Uint8Array(32), new Uint8Array([1])),
+    ).rejects.toThrow(/No Web Crypto provider available/);
+  });
+});
+
+describe("SigningCrypto — native provider", () => {
+  const subtle = makeSubtle();
+
+  beforeAll(() => {
+    // Deepest of the four export shapes the package is read across.
+    quickCryptoExports = { default: { webcrypto: { subtle } } };
+  });
+
+  it("derives a 32-byte key through the native subtle", async () => {
+    const salt = new Uint8Array([9, 8, 7]);
+    const key = await SigningCrypto.deriveKey("secret", salt);
+
+    expect(key).toHaveLength(32);
+    expect(subtle.importKey).toHaveBeenCalledWith(
+      "raw",
+      expect.anything(),
+      "PBKDF2",
+      false,
+      ["deriveBits"],
+    );
+    const deriveArgs = subtle.deriveBits.mock.calls[0] as [
+      { name: string; iterations: number; hash: string; salt: ArrayBuffer },
+      unknown,
+      number,
+    ];
+    expect(deriveArgs[0].name).toBe("PBKDF2");
+    expect(deriveArgs[0].iterations).toBe(200000);
+    expect(deriveArgs[2]).toBe(256);
+    // The salt crosses as its exact bytes, not the whole backing buffer.
+    expect(Array.from(new Uint8Array(deriveArgs[0].salt))).toEqual([9, 8, 7]);
+  });
+
+  it("computes an HMAC through the native subtle", async () => {
+    const mac = await SigningCrypto.hmacSha256(
+      new Uint8Array(32).fill(1),
+      utf8Bytes("payload"),
+    );
+
+    expect(mac).toHaveLength(32);
+    expect(subtle.sign).toHaveBeenCalledWith(
+      "HMAC",
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
+  it("passes only the view's own bytes when the input is a subarray", async () => {
+    const backing = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]);
+    subtle.sign.mockClear();
+    await SigningCrypto.hmacSha256(new Uint8Array(32), backing.subarray(2, 5));
+
+    const dataBuffer = subtle.sign.mock.calls[0]?.[2] as ArrayBuffer;
+    expect(Array.from(new Uint8Array(dataBuffer))).toEqual([2, 3, 4]);
+  });
+
+  it("wraps a derivation failure in SmileIDCryptoError", async () => {
+    subtle.deriveBits.mockRejectedValueOnce(new Error("openssl exploded"));
+
+    await expect(
+      SigningCrypto.deriveKey("secret", new Uint8Array([1])),
+    ).rejects.toThrow(/Key derivation failed: .*openssl exploded/);
+  });
+
+  it("rethrows an already-typed crypto error from deriveKey unchanged", async () => {
+    const typed = new SmileIDCryptoError("key material rejected");
+    subtle.importKey.mockRejectedValueOnce(typed);
+
+    await expect(
+      SigningCrypto.deriveKey("secret", new Uint8Array([1])),
+    ).rejects.toBe(typed);
+  });
+
+  it("wraps a MAC failure in SmileIDCryptoError", async () => {
+    subtle.sign.mockRejectedValueOnce(new Error("bad key handle"));
+
+    await expect(
+      SigningCrypto.hmacSha256(new Uint8Array(32), new Uint8Array([1])),
+    ).rejects.toThrow(/MAC computation failed: .*bad key handle/);
+  });
+
+  it("rethrows an already-typed crypto error from hmacSha256 unchanged", async () => {
+    const typed = new SmileIDCryptoError("hmac key rejected");
+    subtle.importKey.mockRejectedValueOnce(typed);
+
+    await expect(
+      SigningCrypto.hmacSha256(new Uint8Array(32), new Uint8Array([1])),
+    ).rejects.toBe(typed);
+  });
+});

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

@@ -3,6 +3,10 @@ import {
   decodeSmileIDToken,
   decodeSecurityPolicyBitCode,
 } from "../use_smile_id_token_decoder";
+import {
+  isTokenConsentComplete,
+  bindsRequiredUserDetails,
+} from "../../model/token_payload";
 
 // ---------------------------------------------------------------------------
 // Helper — mint a structurally valid JWT with a caller-supplied payload.
@@ -243,9 +247,184 @@ describe("decodeSmileIDToken — parses a valid sdk_config claim", () => {
       makeJwt({}),
       makeJwt({ sdk_config: {} }),
       makeJwt({ sdk_config: { selfie: { quality: 90 } } }),
+      makeJwt({ payload: "not-an-object" }),
+      makeJwt({ payload: { consent: { granted: "yes" } } }),
     ];
     for (const input of inputs) {
       expect(() => decodeSmileIDToken(input)).not.toThrow();
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Token-bound user details & consent — the top-level `payload` claim
+// (a sibling of `sdk_config`). Values are opaque vault references; only
+// key presence is meaningful. Consent subfields are plaintext.
+// ---------------------------------------------------------------------------
+describe("decodeSmileIDToken — payload claim (token-bound user details & consent)", () => {
+  it("parses a full payload claim into all four presence flags plus complete consent", () => {
+    const token = makeJwt({
+      payload: {
+        given_names: "pii_abc",
+        last_name: "pii_def",
+        email: "pii_ghi",
+        phone_number: "pii_jkl",
+        consent: {
+          granted: true,
+          granted_at: "2026-01-01T09:00:00.000Z",
+          notice_language: "EN",
+          notice_privacy_policy_url: "https://partner.test/privacy",
+        },
+      },
+    });
+    const tokenPayload = decodeSmileIDToken(token)?.tokenPayload;
+    expect(tokenPayload?.hasGivenNames).toBe(true);
+    expect(tokenPayload?.hasLastName).toBe(true);
+    expect(tokenPayload?.hasEmail).toBe(true);
+    expect(tokenPayload?.hasPhoneNumber).toBe(true);
+    expect(isTokenConsentComplete(tokenPayload?.consent)).toBe(true);
+  });
+
+  it("parses a subset claim — exact flags plus a partial (incomplete) consent", () => {
+    const token = makeJwt({
+      payload: {
+        email: "pii_ghi",
+        consent: {
+          granted: true,
+          granted_at: "2026-01-01T09:00:00.000Z",
+        },
+      },
+    });
+    const tokenPayload = decodeSmileIDToken(token)?.tokenPayload;
+    expect(tokenPayload?.hasGivenNames).toBe(false);
+    expect(tokenPayload?.hasLastName).toBe(false);
+    expect(tokenPayload?.hasEmail).toBe(true);
+    expect(tokenPayload?.hasPhoneNumber).toBe(false);
+    expect(tokenPayload?.consent).toEqual({
+      granted: true,
+      grantedAt: "2026-01-01T09:00:00.000Z",
+    });
+    expect(isTokenConsentComplete(tokenPayload?.consent)).toBe(false);
+  });
+
+  it("leaves tokenPayload undefined when the payload claim is absent", () => {
+    const token = makeJwt({ sub: "partner-1", iat: 1_700_000_000 });
+    const result = decodeSmileIDToken(token);
+    expect(result).toBeDefined();
+    expect(result?.tokenPayload).toBeUndefined();
+  });
+
+  it("leaves tokenPayload undefined when the payload claim is not an object", () => {
+    for (const claim of ["a-string", ["an", "array"], 42, null]) {
+      const result = decodeSmileIDToken(makeJwt({ payload: claim }));
+      expect(result).toBeDefined();
+      expect(result?.tokenPayload).toBeUndefined();
+    }
+  });
+
+  it("tolerates malformed consent and unknown keys inside the claim", () => {
+    const stringConsent = decodeSmileIDToken(
+      makeJwt({ payload: { consent: "granted", last_name: "pii_x" } }),
+    )?.tokenPayload;
+    expect(stringConsent?.consent).toBeUndefined();
+    expect(stringConsent?.hasLastName).toBe(true);
+
+    const arrayConsent = decodeSmileIDToken(
+      makeJwt({ payload: { consent: [true] } }),
+    )?.tokenPayload;
+    expect(arrayConsent?.consent).toBeUndefined();
+
+    const emptyConsent = decodeSmileIDToken(
+      makeJwt({ payload: { consent: {} } }),
+    )?.tokenPayload;
+    expect(emptyConsent?.consent).toBeUndefined();
+
+    const untrustedGranted = decodeSmileIDToken(
+      makeJwt({
+        payload: {
+          consent: { granted: "yes", notice_language: "EN" },
+          unknown_key: "ignored",
+        },
+      }),
+    )?.tokenPayload;
+    expect(untrustedGranted?.consent?.granted).toBeUndefined();
+    expect(untrustedGranted?.consent?.noticeLanguage).toBe("EN");
+    expect(isTokenConsentComplete(untrustedGranted?.consent)).toBe(false);
+
+    const deniedGranted = decodeSmileIDToken(
+      makeJwt({ payload: { consent: { granted: false } } }),
+    )?.tokenPayload;
+    expect(deniedGranted?.consent).toBeUndefined();
+  });
+
+  it("regression: a legacy token (sdk_config only) still parses sdkConfig with tokenPayload unset", () => {
+    const token = makeJwt({
+      partner_id: "002",
+      sdk_config: { selfie: { width: 640, height: 480, quality: 90 } },
+    });
+    const result = decodeSmileIDToken(token);
+    expect(result?.sdkConfig?.selfie?.width).toBe(640);
+    expect(result?.partnerId).toBe("002");
+    expect(result?.tokenPayload).toBeUndefined();
+  });
+
+  it("parses payload and sdk_config claims side by side", () => {
+    const token = makeJwt({
+      sdk_config: { livenessImageCount: 5 },
+      payload: { given_names: "pii_abc" },
+    });
+    const result = decodeSmileIDToken(token);
+    expect(result?.sdkConfig?.livenessImageCount).toBe(5);
+    expect(result?.tokenPayload?.hasGivenNames).toBe(true);
+  });
+
+  it("decodes a minted token that binds names and email but not phone_number", () => {
+    // Same deployment, partial binding: given_names, last_name and email
+    // only. The contact requirement is satisfied by the bound email alone.
+    const mintedToken =
+      "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV8wMWtibWd6bXczZXloOW5jdjlqcG1kNDlqZiIsInR5cCI6IkpXVCJ9." +
+      "eyJhcGlfdXJsIjoiaHR0cHM6Ly92My10b2tlbi1jb25zZW50LXBheWxvYWQuYXBpLnNtaWxlaWQuY28vdjMiLCJrZXlfaWQiOiIyY2NjOWMyMy01Y2U3LTRkMGUtYWRkYy1lN2I1NGQ4YjkxZGQiLCJwYXlsb2FkIjp7ImNvbnNlbnQiOnsiZ3JhbnRlZCI6dHJ1ZSwiZ3JhbnRlZF9hdCI6IjIwMjYtMDEtMDFUMDk6MDA6MDAuMDAwWiIsIm5vdGljZV9sYW5ndWFnZSI6IkVOIiwibm90aWNlX3ByaXZhY3lfcG9saWN5X3VybCI6Imh0dHBzOi8vanVtYS5wcml2YWN5LXBvbGljeS5jb20ifSwiZW1haWwiOiJwaWlfMDFrcDNzOXQ3OGZleDkxcWg0NnlwODdyanEiLCJnaXZlbl9uYW1lcyI6InBpaV8wMWt6cm0xNzB0ZjY5cnE5NTM4cnpnZXR5eiIsImxhc3RfbmFtZSI6InBpaV8wMWtwM3M5dDdyZThocjZkZXI5cTNucHo3YyJ9LCJwYXJ0bmVyX2lkIjoiMTQ4MyIsInBvbGljeSI6MTUsImF1ZCI6InNtaWxlaWQtYXBpIiwiZXhwIjoxNzg2NDU5ODcxLCJpYXQiOjE3ODY0NTg5NzEsImlzcyI6InNtaWxlaWQtYXV0aCJ9." +
+      "s5BFthU2B1aKxYDYyyWYDmRpLoHibH34r2Lk4OS-wZQC8pmYROjWBiORx6n2_0srmxz_SA2eZo_FHyAr-ew_Zg";
+
+    const tokenPayload = decodeSmileIDToken(mintedToken)?.tokenPayload;
+
+    expect(tokenPayload?.hasGivenNames).toBe(true);
+    expect(tokenPayload?.hasLastName).toBe(true);
+    expect(tokenPayload?.hasEmail).toBe(true);
+    expect(tokenPayload?.hasPhoneNumber).toBe(false);
+    expect(bindsRequiredUserDetails(tokenPayload)).toBe(true);
+    expect(isTokenConsentComplete(tokenPayload?.consent)).toBe(true);
+  });
+
+  it("decodes the payload claim from a token minted by the v3 token endpoint", () => {
+    // Captured from the /v3/token deployment: ES256-signed, extra top-level
+    // claims (api_url, key_id, aud, iss), every user-detail field bound as an
+    // opaque pii_ reference, a complete consent object, and in-claim identity
+    // fields (country, id_type, id_number, callback_url) the SDK deliberately
+    // ignores. The token expired minutes after minting and carries no raw
+    // PII — the decoder never checks exp (the server enforces token
+    // validity).
+    const mintedToken =
+      "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV8wMWtibWd6bXczZXloOW5jdjlqcG1kNDlqZiIsInR5cCI6IkpXVCJ9." +
+      "eyJhcGlfdXJsIjoiaHR0cHM6Ly92My10b2tlbi1jb25zZW50LXBheWxvYWQuYXBpLnNtaWxlaWQuY28vdjMiLCJrZXlfaWQiOiIyY2NjOWMyMy01Y2U3LTRkMGUtYWRkYy1lN2I1NGQ4YjkxZGQiLCJwYXlsb2FkIjp7ImNvbnNlbnQiOnsiZ3JhbnRlZCI6dHJ1ZSwiZ3JhbnRlZF9hdCI6IjIwMjYtMDEtMDFUMDk6MDA6MDAuMDAwWiIsIm5vdGljZV9sYW5ndWFnZSI6IkVOIiwibm90aWNlX3ByaXZhY3lfcG9saWN5X3VybCI6Imh0dHBzOi8vanVtYS5wcml2YWN5LXBvbGljeS5jb20ifSwiY291bnRyeSI6Ik5HIiwiaWRfdHlwZSI6Ik5JTl9WMiIsImVtYWlsIjoicGlpXzAxa3Azczl0NzhmZXg5MXFoNDZ5cDg3cmpxIiwiZ2l2ZW5fbmFtZXMiOiJwaWlfMDFrenJtMTcwdGY2OXJxOTUzOHJ6Z2V0eXoiLCJpZF9udW1iZXIiOiJwaWlfMDFra2dhYTliNWZ2Z2EyMnllZXM1ZjRyNnQiLCJsYXN0X25hbWUiOiJwaWlfMDFrcDNzOXQ3cmU4aHI2ZGVyOXEzbnB6N2MiLCJwaG9uZV9udW1iZXIiOiJwaWlfMDFrenJtdHdkeGZlenJ0dGRmOXQzc3Rzem4iLCJjYWxsYmFja191cmwiOiJjYWxsYmFja18wMWt6cm10d2VmZTV5YWgzbmR2NW03MDc3ZyJ9LCJwYXJ0bmVyX2lkIjoiMTQ4MyIsInBvbGljeSI6MTUsImF1ZCI6InNtaWxlaWQtYXBpIiwiZXhwIjoxNzg2NDYwNzEyLCJpYXQiOjE3ODY0NTk4MTIsImlzcyI6InNtaWxlaWQtYXV0aCJ9." +
+      "cuZgo64eEt5vNvND_RvCVpJyTv4rqax9ebkLV4i4uI4raz6fBhazxspbaoErYC0wxwRmn5EhPAdAdDnNKI6tEQ";
+
+    const result = decodeSmileIDToken(mintedToken);
+
+    expect(result?.partnerId).toBe("1483");
+    expect(result?.tokenPayload).toEqual({
+      hasGivenNames: true,
+      hasLastName: true,
+      hasEmail: true,
+      hasPhoneNumber: true,
+      consent: {
+        granted: true,
+        grantedAt: "2026-01-01T09:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://juma.privacy-policy.com",
+      },
+    });
+    expect(bindsRequiredUserDetails(result?.tokenPayload)).toBe(true);
+    expect(isTokenConsentComplete(result?.tokenPayload?.consent)).toBe(true);
+  });
+});

package/src/data/util/use_smile_id_token_decoder.ts

@@ -1,6 +1,7 @@
 import { ZodError } from "zod";
 
 import { type SdkConfig, sdkConfigSchema } from "../model/sdk_config";
+import { type TokenPayload, parseTokenPayload } from "../model/token_payload";
 
 // `atob` is a global available in React Native's Hermes runtime and in
 // modern browsers. The `lib: ["ES2022"]` tsconfig omits DOM types, so the
@@ -28,20 +29,31 @@ export type DecodedToken = {
    * `undefined` when the claim is absent.
    */
   readonly partnerId?: string;
+  /**
+   * Token-bound user-detail presence flags and consent subfields from the
+   * top-level `payload` claim (a sibling of `sdk_config`). `undefined` when
+   * the claim is absent or not an object — legacy tokens keep today's strict
+   * validation. Same graceful degradation as `sdk_config`: a malformed claim
+   * never rejects the token.
+   */
+  readonly tokenPayload?: TokenPayload;
 };
 
 /**
- * Decode a Smile ID JWT auth token and extract the `sdk_config` claim.
+ * Decode a Smile ID JWT auth token and extract the `sdk_config` and
+ * `payload` claims.
  *
  * The JWT signature is intentionally NOT verified — the server validates
- * authenticity; the SDK only reads capture settings from the payload.
+ * authenticity; the SDK only reads capture settings and token-bound
+ * user-detail/consent presence 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.
+ *     with `sdkConfig` unset. The `payload` claim degrades the same
+ *     way into `tokenPayload`.
  *   - Valid token with a parseable `sdk_config` → non-`undefined`
  *     `DecodedToken` with `sdkConfig` set.
  *
@@ -58,16 +70,21 @@ export function decodeSmileIDToken(token: string): DecodedToken | undefined {
   const partnerIdField =
     typeof rawPartnerId === "string" ? { partnerId: rawPartnerId } : {};
 
+  // Token-bound user details & consent — a TOP-LEVEL `payload` claim, another
+  // sibling of `sdk_config`. Absent/malformed degrades to unset, never rejects.
+  const tokenPayload = parseTokenPayload(payloadObject["payload"]);
+  const tokenPayloadField = tokenPayload !== undefined ? { tokenPayload } : {};
+
   const rawClaim = payloadObject["sdk_config"];
 
   if (rawClaim === undefined || rawClaim === null) {
     // No claim present — defaults apply throughout the flow.
-    return { ...partnerIdField };
+    return { ...partnerIdField, ...tokenPayloadField };
   }
 
   if (typeof rawClaim !== "object" || Array.isArray(rawClaim)) {
     // Claim exists but is not an object — treat as absent.
-    return { ...partnerIdField };
+    return { ...partnerIdField, ...tokenPayloadField };
   }
 
   const parseResult = sdkConfigSchema.safeParse(rawClaim);
@@ -77,12 +94,16 @@ export function decodeSmileIDToken(token: string): DecodedToken | undefined {
       // 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 { ...partnerIdField };
+      return { ...partnerIdField, ...tokenPayloadField };
     }
-    return { ...partnerIdField };
+    return { ...partnerIdField, ...tokenPayloadField };
   }
 
-  return { sdkConfig: parseResult.data, ...partnerIdField };
+  return {
+    sdkConfig: parseResult.data,
+    ...partnerIdField,
+    ...tokenPayloadField,
+  };
 }
 
 /**

package/src/l10n/__tests__/use_smile_id_localizations.test.ts

@@ -1,7 +1,11 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { UseSmileIDLocalizations } from "../use_smile_id_localizations";
 import { CANONICAL_KEY_COUNT, enStrings } from "../strings_en";
 
+// Unicode FIRST STRONG ISOLATE / POP DIRECTIONAL ISOLATE.
+const FSI = "\u2068";
+const PDI = "\u2069";
+
 describe("strings_en — canonical key set", () => {
   it("matches the documented canonical key count", () => {
     // Concrete scenario: we silently drop a key during a refactor —
@@ -55,7 +59,7 @@ describe("UseSmileIDLocalizations", () => {
   it("renders {name} placeholders via _t — siConsentTitle parameterized", () => {
     const loc = new UseSmileIDLocalizations();
     expect(loc.siConsentTitle("Acme")).toBe(
-      "Acme would like to verify your identity using Smile ID.",
+      `${FSI}Acme${PDI} would like to verify your identity using Smile ID.`,
     );
   });
 
@@ -68,7 +72,9 @@ describe("UseSmileIDLocalizations", () => {
     const loc = new UseSmileIDLocalizations({
       si_consent_title: "{partnerName} hi {partnerName}",
     });
-    expect(loc.siConsentTitle("Acme")).toBe("Acme hi Acme");
+    expect(loc.siConsentTitle("Acme")).toBe(
+      `${FSI}Acme${PDI} hi ${FSI}Acme${PDI}`,
+    );
   });
 
   it("uses partner override for parameterized partner-link key", () => {
@@ -79,13 +85,15 @@ describe("UseSmileIDLocalizations", () => {
       si_consent_learn_more_privacy_partner_link: "Politique {partnerName}",
     });
     expect(loc.siConsentLearnMorePrivacyPartnerLink("Acme")).toBe(
-      "Politique Acme",
+      `Politique ${FSI}Acme${PDI}`,
     );
   });
 
   it("renders the document flip title with the {id_type} token", () => {
     const loc = new UseSmileIDLocalizations();
-    expect(loc.siDocumentFlipTitle("Green Book")).toBe("Flip your Green Book");
+    expect(loc.siDocumentFlipTitle("Green Book")).toBe(
+      `Flip your ${FSI}Green Book${PDI}`,
+    );
     expect(loc.siDocumentCaptureBack).toBe("Capture Back of ID");
     expect(loc.siDocumentSkipBack).toBe("Skip");
     expect(loc.siDocumentGuidelineGood).toBe("Good");
@@ -125,3 +133,112 @@ describe("UseSmileIDLocalizations", () => {
     });
   });
 });
+
+describe("UseSmileIDLocalizations — bidi isolation of interpolated values", () => {
+  it("isolates a substituted value so it cannot reorder the sentence", () => {
+    const loc = new UseSmileIDLocalizations();
+    const rendered = loc.siConsentTitle("شركة");
+
+    expect(rendered).toContain(`${FSI}شركة${PDI}`);
+    expect(rendered.indexOf(FSI)).toBeLessThan(rendered.indexOf(PDI));
+  });
+
+  it("isolates every occurrence of a repeated placeholder", () => {
+    const loc = new UseSmileIDLocalizations({
+      si_consent_title: "{partnerName} — {partnerName}",
+    });
+    const rendered = loc.siConsentTitle("Acme");
+
+    expect(rendered.split(FSI)).toHaveLength(3);
+    expect(rendered.split(PDI)).toHaveLength(3);
+  });
+
+  it("leaves an empty value unwrapped rather than emitting a bare isolate pair", () => {
+    const loc = new UseSmileIDLocalizations({
+      si_consent_title: "[{partnerName}]",
+    });
+    expect(loc.siConsentTitle("")).toBe("[]");
+  });
+});
+
+describe("UseSmileIDLocalizations — active-locale identity", () => {
+  it("changes when the resolved locale changes", () => {
+    const original = UseSmileIDLocalizations.localeResolver;
+    try {
+      UseSmileIDLocalizations.localeResolver = () => "en";
+      const before = UseSmileIDLocalizations.activeLocaleKey;
+      UseSmileIDLocalizations.localeResolver = () => "fr";
+      expect(UseSmileIDLocalizations.activeLocaleKey).not.toBe(before);
+    } finally {
+      UseSmileIDLocalizations.localeResolver = original;
+    }
+  });
+
+  it("changes when a locale is registered after the first read", () => {
+    UseSmileIDLocalizations.clearRegistry();
+    const before = UseSmileIDLocalizations.activeLocaleKey;
+    UseSmileIDLocalizations.register("fr", { si_consent_allow: "Autoriser" });
+    expect(UseSmileIDLocalizations.activeLocaleKey).not.toBe(before);
+    UseSmileIDLocalizations.clearRegistry();
+  });
+});
+
+describe("UseSmileIDLocalizations — dev-build fallback warnings", () => {
+  const globalWithDev = globalThis as { __DEV__?: boolean };
+
+  function withDevBuild(body: (warn: ReturnType<typeof vi.fn>) => void): void {
+    const hadDev = "__DEV__" in globalWithDev;
+    const previousDev = globalWithDev.__DEV__;
+    const warn = vi.fn();
+    const originalWarn = console.warn;
+    globalWithDev.__DEV__ = true;
+    console.warn = warn;
+    try {
+      body(warn);
+    } finally {
+      console.warn = originalWarn;
+      if (hadDev) globalWithDev.__DEV__ = previousDev;
+      else delete globalWithDev.__DEV__;
+    }
+  }
+
+  it("warns when the device locale has no registered translations", () => {
+    withDevBuild((warn) => {
+      UseSmileIDLocalizations.clearRegistry();
+      const original = UseSmileIDLocalizations.localeResolver;
+      UseSmileIDLocalizations.localeResolver = () => "zu-ZA";
+      try {
+        UseSmileIDLocalizations.forActiveLocale();
+      } finally {
+        UseSmileIDLocalizations.localeResolver = original;
+      }
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(String(warn.mock.calls[0]?.[0])).toContain("zu-ZA");
+    });
+  });
+
+  it("warns once when a supplied translation is missing keys", () => {
+    withDevBuild((warn) => {
+      const loc = new UseSmileIDLocalizations({
+        si_consent_allow: "Autoriser",
+      });
+      expect(loc.siConsentAllow).toBe("Autoriser");
+      expect(warn).not.toHaveBeenCalled();
+
+      loc.siConsentDeny;
+      loc.siLabelContinue;
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(String(warn.mock.calls[0]?.[0])).toContain("si_consent_deny");
+    });
+  });
+
+  it("stays silent for the English-only default instance", () => {
+    withDevBuild((warn) => {
+      const loc = new UseSmileIDLocalizations();
+      expect(loc.siLabelContinue).toBe("Continue");
+      expect(warn).not.toHaveBeenCalled();
+    });
+  });
+});