@smileid/usesmileid 12.0.0-beta01

package/src/data/repository/use_smile_id_repository_impl.ts

@@ -0,0 +1,94 @@
+import type { JobRequest } from "../model/job_request";
+import type { JobSubmissionResponse } from "../model/job_submission_response";
+import type { SmileIDAPI } from "../api/smile_id_api";
+import type { RetryConfig } from "../../core/models/network_config";
+import type { UseSmileIDResult } from "../../core/models/result";
+import { failure, success } from "../../core/models/result";
+import { JobType } from "../../core/models/job_type";
+import { withRetry } from "../util/retry_util";
+import { InvalidFieldValueException } from "../../core/exception/job_validation_exceptions";
+import { UseSmileIDValidationException } from "../../core/exception/use_smile_id_validation_exception";
+import {
+  mapAxiosError,
+  type UseSmileIDNetworkException,
+} from "../../core/exception/use_smile_id_network_exception";
+
+/**
+ * Concrete repository.
+ *
+ * Exhaustive-switch dispatch over the `JobRequest` discriminated
+ * union — adding a new variant fails to compile here until the new
+ * dispatch case lands, so partner orchestrator code never silently
+ * skips a request type.
+ */
+export class UseSmileIDRepositoryImpl {
+  private readonly _api: SmileIDAPI;
+  private readonly _retry: RetryConfig;
+
+  constructor(api: SmileIDAPI, retry: RetryConfig) {
+    this._api = api;
+    this._retry = retry;
+  }
+
+  async submit(
+    request: JobRequest,
+  ): Promise<UseSmileIDResult<JobSubmissionResponse>> {
+    // BVN is not yet supported. Fail fast at the repository boundary
+    // with the canonical typed exception so partner `onResult` sees a
+    // structured error rather than a wire-level failure from the
+    // server.
+    if (request.jobType === JobType.bvn) {
+      return failure(
+        new InvalidFieldValueException({
+          fieldName: "jobType",
+          reason: "BVN submission is not yet supported",
+        }),
+      );
+    }
+    try {
+      const response = await withRetry(this._retry, () =>
+        this._dispatch(request),
+      );
+      return success(response);
+    } catch (error) {
+      // A validation failure (e.g. a liveness-count mismatch) is a
+      // pre-network constraint violation — surface the typed exception
+      // directly rather than collapsing it into the network hierarchy, so
+      // partners can catch it as the validation error it is.
+      if (error instanceof UseSmileIDValidationException) {
+        return failure(error);
+      }
+      return failure(this._mapError(error));
+    }
+  }
+
+  private _dispatch(
+    request: Exclude<JobRequest, { jobType: typeof JobType.bvn }>,
+  ): Promise<JobSubmissionResponse> {
+    switch (request.jobType) {
+      case JobType.smartSelfieEnrollment:
+        return this._api.smartSelfieEnrollment(request);
+      case JobType.smartSelfieAuthentication:
+        return this._api.smartSelfieAuthentication(request);
+      case JobType.enhancedKyc:
+        return this._api.enhancedKyc(request);
+      case JobType.biometricKyc:
+        return this._api.biometricKyc(request);
+      case JobType.documentVerification:
+        return this._api.documentVerification(request);
+      case JobType.enhancedDocumentVerification:
+        return this._api.enhancedDocumentVerification(request);
+    }
+  }
+
+  /**
+   * Translate any caught error into the typed
+   * [UseSmileIDNetworkException] hierarchy. Delegates to the canonical
+   * [mapAxiosError] so a single mapper implementation covers both the
+   * repository layer and any future call sites (interceptors,
+   * partner-supplied error wrappers).
+   */
+  private _mapError(error: unknown): UseSmileIDNetworkException {
+    return mapAxiosError(error);
+  }
+}

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

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+
+import { SigningCrypto, base64Encode, utf8Bytes } from "../signing_crypto";
+import { SmileIDCryptoManager } from "../smile_id_crypto_manager";
+
+/**
+ * Pins down the request-signing contract:
+ *   - A multipart request signs to a fixed known-answer vector so any
+ *     divergence from the canonical algorithm — the logical payload (JSON
+ *     fields parsed, file parts Base64'd, scalars as strings) key-sorted and
+ *     compact-stringified, then PBKDF2-HMAC-SHA256 keyed and Base64-encoded —
+ *     fails loud.
+ *   - Only `smileid-*` headers are signed, and the body is canonicalised so the
+ *     MAC is independent of header / part ordering.
+ */
+const TIMESTAMP = "1700000000000";
+const subject = new SmileIDCryptoManager("test-signing-secret");
+
+const KAT_HEADERS = {
+  "smileid-token": "test-token",
+  "smileid-request-timestamp": TIMESTAMP,
+  "content-type": "multipart/form-data",
+};
+
+/** Minimal stand-in for React Native's `FormData` (only `getParts` is read). */
+function formData(
+  parts: ReadonlyArray<{ fieldName: string; string?: string; uri?: string }>,
+) {
+  return { getParts: () => parts };
+}
+
+/**
+ * The known-answer-vector body: scalar string fields, a top-level boolean
+ * string, two JSON fields, and a file part — exercising every classification.
+ * The file is a `data:` URI so the canonicalizer's `fetch` reads its bytes
+ * (Base64 of "selfiebytes").
+ */
+function katBody() {
+  return formData([
+    { fieldName: "country", string: "NG" },
+    { fieldName: "id_type", string: "PASSPORT" },
+    { fieldName: "allow_new_enroll", string: "true" },
+    {
+      fieldName: "consent",
+      string: '{"granted":true,"personal_details":false}',
+    },
+    { fieldName: "partner_params", string: '{"job_id":"j1","user_id":"u1"}' },
+    {
+      fieldName: "selfie_image",
+      uri: "data:application/octet-stream;base64,c2VsZmllYnl0ZXM=",
+    },
+  ]);
+}
+
+describe("SmileIDCryptoManager", () => {
+  it("signs a multipart request to the known-answer vector", async () => {
+    const mac = await subject.sign(TIMESTAMP, KAT_HEADERS, katBody());
+    expect(mac).toBe("nW0HenQOrKH/qAwQBveK+TSXvg70oVWfD0aGGtfI1bk=");
+  });
+
+  it("multipart body MAC is independent of part order", async () => {
+    const headers = { "smileid-request-timestamp": TIMESTAMP };
+    const first = await subject.sign(
+      TIMESTAMP,
+      headers,
+      formData([
+        { fieldName: "country", string: "NG" },
+        { fieldName: "id_type", string: "PASSPORT" },
+      ]),
+    );
+    const second = await subject.sign(
+      TIMESTAMP,
+      headers,
+      formData([
+        { fieldName: "id_type", string: "PASSPORT" },
+        { fieldName: "country", string: "NG" },
+      ]),
+    );
+    expect(first).toBe(second);
+  });
+
+  it("non-smileid headers do not affect the MAC", async () => {
+    const body = () => formData([{ fieldName: "country", string: "NG" }]);
+    const withoutExtras = await subject.sign(
+      TIMESTAMP,
+      { "smileid-token": "test-token" },
+      body(),
+    );
+    const withExtras = await subject.sign(
+      TIMESTAMP,
+      {
+        "smileid-token": "test-token",
+        "x-extra": "ignored",
+        accept: "application/json",
+      },
+      body(),
+    );
+    expect(withoutExtras).toBe(withExtras);
+  });
+
+  it("internal marker headers do not affect the MAC", async () => {
+    const body = () => formData([{ fieldName: "country", string: "NG" }]);
+    const withoutMarkers = await subject.sign(
+      TIMESTAMP,
+      { "smileid-token": "test-token" },
+      body(),
+    );
+    const withMarkers = await subject.sign(
+      TIMESTAMP,
+      {
+        "smileid-token": "test-token",
+        "x-smileid-requires-attestation": "true",
+        "x-smileid-requires-mac": "true",
+      },
+      body(),
+    );
+    expect(withoutMarkers).toBe(withMarkers);
+  });
+
+  it("smileid-prefixed headers affect the MAC", async () => {
+    const body = () => formData([{ fieldName: "country", string: "NG" }]);
+    const withFirstToken = await subject.sign(
+      TIMESTAMP,
+      { "smileid-token": "token-one" },
+      body(),
+    );
+    const withSecondToken = await subject.sign(
+      TIMESTAMP,
+      { "smileid-token": "token-two" },
+      body(),
+    );
+    expect(withFirstToken).not.toBe(withSecondToken);
+  });
+
+  it("different signing secrets produce different MACs", async () => {
+    const withDefaultSecret = await subject.sign(
+      TIMESTAMP,
+      KAT_HEADERS,
+      katBody(),
+    );
+    const withOtherSecret = await new SmileIDCryptoManager("other-secret").sign(
+      TIMESTAMP,
+      KAT_HEADERS,
+      katBody(),
+    );
+    expect(withDefaultSecret).not.toBe(withOtherSecret);
+  });
+
+  it("hmacSha256 matches RFC 4231 Test Case 2", async () => {
+    const mac = await SigningCrypto.hmacSha256(
+      utf8Bytes("Jefe"),
+      utf8Bytes("what do ya want for nothing?"),
+    );
+    expect(base64Encode(mac)).toBe(
+      "W9zBRr9gdU5qBCQmCJV1x1oAPwidJzmDnexYuWTsOEM=",
+    );
+  });
+});

package/src/data/security/request_canonicalizer.ts

@@ -0,0 +1,148 @@
+import { base64Encode, utf8Bytes } from "./signing_crypto";
+
+/**
+ * Reduces a request to the canonical bytes that get signed: the signed headers
+ * as sorted-key JSON, followed by the canonicalised body. Canonicalisation
+ * reconstructs the logical request payload the server validates against, so the
+ * client and server sign the same bytes.
+ *
+ * The body reconstruction mirrors the server's form parser + payload processor:
+ *   - JSON fields (`partner_params`, `metadata`, `failure_reason`, `consent`,
+ *     `user_details`) are parsed into objects.
+ *   - File parts contribute the Base64 of their bytes; repeated names (e.g.
+ *     `liveness_images`) collapse into a list.
+ *   - Every other field contributes its string value; a top-level `"true"` /
+ *     `"false"` becomes a boolean.
+ * The result is key-sorted recursively and emitted as compact JSON, then
+ * `latitude`/`longitude` and the `device_movement_detected` metadata value are
+ * coerced from string to number to match the server.
+ */
+
+const SIGNED_HEADER_PREFIX = "smileid-";
+const REQUEST_MAC_HEADER = "smileid-request-mac";
+const DEVICE_NONCE_HEADER = "smileid-device-nonce";
+const JSON_FIELDS = new Set([
+  "partner_params",
+  "metadata",
+  "failure_reason",
+  "consent",
+  "user_details",
+]);
+
+const LATITUDE_LONGITUDE =
+  /"(latitude|longitude)":"(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)"/g;
+const DEVICE_MOVEMENT =
+  /("name":"device_movement_detected",.*?"value":)"(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)"/g;
+
+/** The subset of React Native's `FormData` part shape the canonicalizer reads. */
+type FormDataPart = {
+  readonly fieldName: string;
+  readonly string?: string;
+  readonly uri?: string;
+};
+type FormDataLike = { getParts(): readonly FormDataPart[] };
+
+function isFormDataLike(body: unknown): body is FormDataLike {
+  return (
+    typeof body === "object" &&
+    body !== null &&
+    typeof (body as { getParts?: unknown }).getParts === "function"
+  );
+}
+
+export const RequestCanonicalizer = {
+  async canonicalize(
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<Uint8Array> {
+    return concat(canonicalHeaders(headers), await canonicalBody(body));
+  },
+};
+
+function canonicalHeaders(headers: Record<string, string>): Uint8Array {
+  const signed: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    const name = key.toLowerCase();
+    if (
+      name.startsWith(SIGNED_HEADER_PREFIX) &&
+      name !== REQUEST_MAC_HEADER &&
+      name !== DEVICE_NONCE_HEADER
+    ) {
+      signed[name] = value;
+    }
+  }
+  return utf8Bytes(canonicalJson(signed));
+}
+
+async function canonicalBody(body: unknown): Promise<Uint8Array> {
+  if (!isFormDataLike(body)) return utf8Bytes("{}");
+  const payload: Record<string, unknown> = {};
+  for (const part of body.getParts()) {
+    merge(payload, part.fieldName, await partValue(part));
+  }
+  return utf8Bytes(coerceNumbers(canonicalJson(payload)));
+}
+
+/** File parts (a `uri`) → Base64 of bytes; JSON fields → parsed; else string with bool coercion. */
+async function partValue(part: FormDataPart): Promise<unknown> {
+  if (part.uri != null) {
+    const response = await fetch(part.uri);
+    return base64Encode(new Uint8Array(await response.arrayBuffer()));
+  }
+  const value = part.string ?? "";
+  if (JSON_FIELDS.has(part.fieldName)) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return value;
+}
+
+function merge(
+  payload: Record<string, unknown>,
+  name: string,
+  value: unknown,
+): void {
+  if (!(name in payload)) {
+    payload[name] = value;
+    return;
+  }
+  const existing = payload[name];
+  payload[name] = Array.isArray(existing)
+    ? [...existing, value]
+    : [existing, value];
+}
+
+/** Compact JSON with recursively sorted object keys (no whitespace). */
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (typeof value === "object" && value !== null) {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = sortValue((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function coerceNumbers(json: string): string {
+  return json
+    .replace(LATITUDE_LONGITUDE, '"$1":$2')
+    .replace(DEVICE_MOVEMENT, "$1$2");
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}

package/src/data/security/request_timestamp.ts

@@ -0,0 +1,12 @@
+/**
+ * The request timestamp used for request signing: epoch milliseconds rendered
+ * as a string.
+ *
+ * Stamped as the `smileid-request-timestamp` header and reused as the
+ * request-MAC salt, so producing it in one place keeps the clock read and the
+ * wire format consistent between the header and the signature. The server
+ * validates the value against its accepted clock-skew window.
+ */
+export function currentRequestTimestamp(): string {
+  return Date.now().toString();
+}

package/src/data/security/signing_crypto.ts

@@ -0,0 +1,219 @@
+import { SmileIDCryptoError } from "./smile_id_crypto_error";
+
+// Ambient declaration for the text-encoding global. `tsconfig.base.json` ships
+// `lib: ["ES2022"]` (no DOM types) so `TextEncoder` isn't in scope by default.
+// React Native exposes it (Hermes built-in since 0.71); Node provides it too.
+declare class TextEncoder {
+  encode(input: string): Uint8Array;
+}
+
+// CommonJS `require`, provided by the Metro / Node runtime. Declared so the
+// workspace `tsc` build doesn't need `@types/node` for the single lazy require
+// of the native crypto provider below. Matches the attestation bridge module.
+declare function require(moduleName: string): unknown;
+
+const KEY_LENGTH_BYTES = 32;
+const ITERATIONS = 200000;
+
+/** UTF-8 encodes a string to bytes. */
+export function utf8Bytes(input: string): Uint8Array {
+  return new TextEncoder().encode(input);
+}
+
+const BASE64_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** Standard-alphabet Base64 of [bytes] (no line wrap). */
+export function base64Encode(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] as number;
+    const b1 = i + 1 < bytes.length ? (bytes[i + 1] as number) : 0;
+    const b2 = i + 2 < bytes.length ? (bytes[i + 2] as number) : 0;
+    out += BASE64_ALPHABET[b0 >> 2];
+    out += BASE64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)];
+    out +=
+      i + 1 < bytes.length
+        ? BASE64_ALPHABET[((b1 & 0x0f) << 2) | (b2 >> 6)]
+        : "=";
+    out += i + 2 < bytes.length ? BASE64_ALPHABET[b2 & 0x3f] : "=";
+  }
+  return out;
+}
+
+/**
+ * Minimal structural type for the Web Crypto `SubtleCrypto` surface this module
+ * uses. Declared locally because the workspace tsconfig omits the DOM lib.
+ */
+interface SubtleLike {
+  importKey(
+    format: "raw",
+    keyData: ArrayBuffer,
+    algorithm: { name: "HMAC"; hash: "SHA-256" } | "PBKDF2",
+    extractable: boolean,
+    keyUsages: readonly ("sign" | "deriveBits")[],
+  ): Promise<unknown>;
+  sign(
+    algorithm: "HMAC",
+    key: unknown,
+    data: ArrayBuffer,
+  ): Promise<ArrayBuffer>;
+  deriveBits(
+    algorithm: {
+      name: "PBKDF2";
+      salt: ArrayBuffer;
+      iterations: number;
+      hash: "SHA-256";
+    },
+    key: unknown,
+    length: number,
+  ): Promise<ArrayBuffer>;
+}
+
+// Cached only once a provider is found. A not-found result is never cached, so a
+// provider that appears later (e.g. a partner that polyfills `globalThis.crypto`
+// or calls `react-native-quick-crypto`'s `install()` after the first signing
+// attempt) is picked up on the next call instead of being stuck throwing.
+let cachedSubtle: SubtleLike | undefined;
+
+/**
+ * Resolve the Web Crypto provider for request signing:
+ *
+ *   1. An existing global `crypto.subtle` — Node (vitest) provides it, and a
+ *      runtime that already polyfills Web Crypto (e.g. a partner app that calls
+ *      `react-native-quick-crypto`'s `install()`) exposes it here.
+ *   2. `react-native-quick-crypto` — the native (OpenSSL) provider bundled on
+ *      device. Hermes ships no `crypto.subtle`, so this is the on-device path;
+ *      PBKDF2/HMAC then run in compiled native code (~ms) rather than the JS
+ *      engine. Its `subtle` is read across the export shapes the package exposes
+ *      (`subtle`, `webcrypto.subtle`, and the same under `default`).
+ *
+ * Preferring the global first means tests transparently use Node's crypto and
+ * the lazy `require` is only reached on device (where Hermes has no global
+ * subtle and Metro has bundled the native module) — no runtime sniffing needed.
+ *
+ * Returns `null` (uncached) when neither resolves; callers throw
+ * {@link SmileIDCryptoError}. There is intentionally **no pure-JS PBKDF2/HMAC
+ * fallback**: a pure-JS 200_000-iteration PBKDF2 takes 40–80 s on device and,
+ * being silent, presents as "slow network".
+ */
+function resolveSubtle(): SubtleLike | null {
+  if (cachedSubtle) return cachedSubtle;
+
+  const globalSubtle = (globalThis as { crypto?: { subtle?: SubtleLike } })
+    .crypto?.subtle;
+  if (globalSubtle) {
+    cachedSubtle = globalSubtle;
+    return cachedSubtle;
+  }
+
+  try {
+    const moduleExports = require("react-native-quick-crypto") as {
+      subtle?: SubtleLike;
+      webcrypto?: { subtle?: SubtleLike };
+      default?: { subtle?: SubtleLike; webcrypto?: { subtle?: SubtleLike } };
+    };
+    const nativeSubtle =
+      moduleExports.subtle ??
+      moduleExports.webcrypto?.subtle ??
+      moduleExports.default?.subtle ??
+      moduleExports.default?.webcrypto?.subtle;
+    if (nativeSubtle) {
+      cachedSubtle = nativeSubtle;
+      return cachedSubtle;
+    }
+  } catch {
+    // Module not installed / not linked.
+  }
+
+  // Not found — intentionally uncached so a later polyfill / install() resolves.
+  return null;
+}
+
+function requireSubtle(): SubtleLike {
+  const subtle = resolveSubtle();
+  if (!subtle) {
+    throw new SmileIDCryptoError(
+      "No Web Crypto provider available for request signing. Install the " +
+        "`react-native-quick-crypto` peer dependency (with its peers " +
+        "`react-native-nitro-modules` and `react-native-quick-base64`), or " +
+        "expose a global `crypto.subtle`.",
+    );
+  }
+  return subtle;
+}
+
+/**
+ * The exact bytes of [bytes] as a standalone `ArrayBuffer`. Reading `.buffer`
+ * directly is wrong when the view covers only part of a larger buffer (a
+ * `subarray` / `slice`), which would feed the surrounding bytes into PBKDF2/HMAC.
+ */
+function exactBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}
+
+/**
+ * Low-level signing primitives: PBKDF2 key derivation and HMAC-SHA256. Stateless
+ * and deterministic, so the server reproduces the same key and MAC from the same
+ * inputs. Backed by the native Web Crypto provider resolved above.
+ */
+export const SigningCrypto = {
+  /**
+   * Derives a 32-byte key from [secret] and [salt] with PBKDF2-HMAC-SHA256.
+   *
+   * @throws {SmileIDCryptoError} if no provider is available or derivation fails.
+   */
+  async deriveKey(secret: string, salt: Uint8Array): Promise<Uint8Array> {
+    const subtle = requireSubtle();
+    try {
+      const keyMaterial = await subtle.importKey(
+        "raw",
+        exactBuffer(utf8Bytes(secret)),
+        "PBKDF2",
+        false,
+        ["deriveBits"],
+      );
+      const bits = await subtle.deriveBits(
+        {
+          name: "PBKDF2",
+          salt: exactBuffer(salt),
+          iterations: ITERATIONS,
+          hash: "SHA-256",
+        },
+        keyMaterial,
+        KEY_LENGTH_BYTES * 8,
+      );
+      return new Uint8Array(bits);
+    } catch (cause) {
+      if (cause instanceof SmileIDCryptoError) throw cause;
+      throw new SmileIDCryptoError(`Key derivation failed: ${String(cause)}`);
+    }
+  },
+
+  /**
+   * Computes HMAC-SHA256 of [data] under [key].
+   *
+   * @throws {SmileIDCryptoError} if no provider is available or the MAC cannot
+   *   be computed.
+   */
+  async hmacSha256(key: Uint8Array, data: Uint8Array): Promise<Uint8Array> {
+    const subtle = requireSubtle();
+    try {
+      const cryptoKey = await subtle.importKey(
+        "raw",
+        exactBuffer(key),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"],
+      );
+      const digest = await subtle.sign("HMAC", cryptoKey, exactBuffer(data));
+      return new Uint8Array(digest);
+    } catch (cause) {
+      if (cause instanceof SmileIDCryptoError) throw cause;
+      throw new SmileIDCryptoError(`MAC computation failed: ${String(cause)}`);
+    }
+  },
+};

package/src/data/security/smile_id_crypto_error.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown by {@link SmileIDCryptoManager} and its supporting crypto
+ * routines.
+ *
+ * Typed so call sites can catch a key-derivation / MAC-computation failure
+ * (environment problem) intentionally rather than catching everything.
+ */
+export class SmileIDCryptoError extends Error {
+  constructor(message = "SmileID request signing failed") {
+    super(message);
+    this.name = "SmileIDCryptoError";
+  }
+}

package/src/data/security/smile_id_crypto_manager.ts

@@ -0,0 +1,46 @@
+import { RequestCanonicalizer } from "./request_canonicalizer";
+import { base64Encode, SigningCrypto, utf8Bytes } from "./signing_crypto";
+
+/**
+ * Signs outbound requests so the Smile ID server can prove the bytes it
+ * receives were produced by a genuine SDK install.
+ *
+ * The request is reduced to a canonical payload ({@link RequestCanonicalizer}),
+ * the signing key is PBKDF2-derived from the Arkana secret salted with the
+ * payload length and request timestamp, and the payload is HMAC-SHA256'd
+ * ({@link SigningCrypto}). The Base64 result is the `smileid-request-mac` value.
+ *
+ * Constructed by the networking factory with the Arkana signing secret
+ * (obtained from the bridge) and injected into `SmileRequestMacInterceptor`.
+ * Construct directly only in tests, passing a known secret.
+ */
+export class SmileIDCryptoManager {
+  private readonly _signingSecret: string;
+
+  constructor(signingSecret: string) {
+    this._signingSecret = signingSecret;
+  }
+
+  /**
+   * Signs a request's `smileid-*` headers and body.
+   *
+   * @param timestamp the value of the `smileid-request-timestamp` header,
+   *   reused here so the salt matches the header the server reads.
+   * @param headers the full request headers; only those prefixed `smileid-`
+   *   (case-insensitive) are signed.
+   * @param body the request body, canonicalised before signing.
+   * @returns the Base64-encoded HMAC.
+   * @throws {SmileIDCryptoError} if key derivation or MAC computation fails.
+   */
+  async sign(
+    timestamp: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<string> {
+    const payload = await RequestCanonicalizer.canonicalize(headers, body);
+    const salt = utf8Bytes(`${payload.length}${timestamp}`);
+    const key = await SigningCrypto.deriveKey(this._signingSecret, salt);
+    const mac = await SigningCrypto.hmacSha256(key, payload);
+    return base64Encode(mac);
+  }
+}