@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

package/dist/react-native/utils/modelInitialisationChecks.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelInitialisationChecks = modelInitialisationChecks;
+/**
+ * Face+ZK SDK – Model Initialisation Checks
+ *
+ * Pre-flight utility that inspects whether each configured model source is
+ * already available on device without downloading anything.
+ *
+ * Call this before mounting any SDK screen to decide whether a download step
+ * is needed. The result tells you exactly which models are present and which
+ * need to be fetched, so your app can show an appropriate UI (progress bar,
+ * "first-time setup" screen, etc.) before calling initializeSdk().
+ *
+ * Usage:
+ *   const result = await modelInitialisationChecks(modelConfig);
+ *   if (!result.ready) {
+ *     // download missing models, show progress, then proceed
+ *   }
+ */
+const FileSystem = __importStar(require("expo-file-system/legacy"));
+const resolveModelUri_1 = require("./resolveModelUri");
+// ── Implementation ─────────────────────────────────────────────────────────
+/**
+ * Returns whether a single ModelSource is already locally available.
+ * Does NOT download or resolve assets — read-only check.
+ */
+async function isSourceReady(source) {
+    if (source.localUri) {
+        const info = await FileSystem.getInfoAsync(source.localUri);
+        return info.exists;
+    }
+    if (source.module != null) {
+        // Metro-bundled assets are always present in the binary.
+        return true;
+    }
+    if (source.url) {
+        const info = await FileSystem.getInfoAsync((0, resolveModelUri_1.deriveStorePath)(source.url));
+        return info.exists;
+    }
+    // Source has no resolvable value — treat as not ready.
+    return false;
+}
+/**
+ * Check whether all configured model sources are already resolved locally.
+ *
+ * Does NOT download anything. Safe to call on every app launch — fast when
+ * all models are present (only stat calls, no network).
+ *
+ * @param models  The same FaceZkModelsConfig you intend to pass to initializeSdk().
+ * @returns       Readiness result with `ready` flag and `missing`/`present` arrays.
+ */
+async function modelInitialisationChecks(models) {
+    const entries = [
+        ["detection", models.detection],
+        ["recognition", models.recognition],
+        ["antispoof", models.antispoof],
+        ["wasm", models.wasm],
+        ["zkWorkerHtml", models.zkWorkerHtml],
+    ];
+    const missing = [];
+    const present = [];
+    for (const [key, source] of entries) {
+        if (source == null) {
+            // Optional model not configured — not required, skip.
+            continue;
+        }
+        if (await isSourceReady(source)) {
+            present.push(key);
+        }
+        else {
+            missing.push(key);
+        }
+    }
+    return {
+        ready: missing.length === 0,
+        missing,
+        present,
+    };
+}

package/dist/react-native/utils/resolveModelUri.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ModelSource } from "../../config/types";
+/** Directory where URL-downloaded models are stored persistently. */
+export declare const MODEL_STORE_DIR: string;
+/**
+ * Resolve a ModelSource to a local file URI.
+ *
+ * @param source         The model source to resolve.
+ * @param onProgress     Optional callback receiving download fraction (0–1).
+ *                       Only fires for `url` sources during active download;
+ *                       silent on cache hits.
+ * @param allowedDomains Optional hostname allowlist. When provided and non-empty,
+ *                       any `url` source whose hostname is not in this list is
+ *                       rejected before any network request is made.
+ *                       Pass `FaceZkConfig.allowedDomains` here in production.
+ * @throws if the source has none of: module, url, localUri
+ * @throws if the download fails (url path)
+ */
+export declare function resolveModelUri(source: ModelSource, onProgress?: (fraction: number) => void, allowedDomains?: string[]): Promise<string>;
+/**
+ * Derive the local store path for a given URL.
+ *
+ * Guards against path traversal in two passes:
+ *  1. URL-decode the last path segment so encoded separators like `%2F` or
+ *     `%2E%2E` are normalised before any checks run.
+ *  2. Re-extract the basename from the decoded string (a decoded `%2F`
+ *     becomes `/`, so a second `.split("/")` is needed).
+ *  3. Reject the reserved names `.` and `..` outright.
+ *  4. Allowlist `[A-Za-z0-9._-]` — the only characters that can appear in a
+ *     legitimate model filename.  Anything outside this set throws so the
+ *     caller can surface the problem rather than silently storing a bad file.
+ *
+ * @throws if the derived filename is empty, a traversal component, or contains
+ *         characters outside the safe allowlist.
+ */
+export declare function deriveStorePath(url: string): string;
+/**
+ * Clear all URL-downloaded model files from the persistent store.
+ * Useful for forcing a re-download after a model version update.
+ */
+export declare function clearModelCache(): Promise<void>;

package/dist/react-native/utils/resolveModelUri.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_STORE_DIR = void 0;
+exports.resolveModelUri = resolveModelUri;
+exports.deriveStorePath = deriveStorePath;
+exports.clearModelCache = clearModelCache;
+/**
+ * Face+ZK SDK – Model URI Resolution
+ *
+ * Resolves a `ModelSource` to a local file URI that can be passed to
+ * FileSystem.readAsStringAsync() or similar APIs.
+ *
+ * Resolution order:
+ *   1. localUri  – returned as-is (already resolved)
+ *   2. module    – resolved via expo-asset (Metro-bundled)
+ *   3. url       – downloaded to documentDirectory on first use, path returned
+ *
+ * Models are stored in documentDirectory (not cacheDirectory) so they
+ * survive cache clears and never need re-downloading.
+ */
+const expo_asset_1 = require("expo-asset");
+const FileSystem = __importStar(require("expo-file-system/legacy"));
+/** Directory where URL-downloaded models are stored persistently. */
+exports.MODEL_STORE_DIR = `${FileSystem.documentDirectory}face-zk-models/`;
+/**
+ * Resolve a ModelSource to a local file URI.
+ *
+ * @param source         The model source to resolve.
+ * @param onProgress     Optional callback receiving download fraction (0–1).
+ *                       Only fires for `url` sources during active download;
+ *                       silent on cache hits.
+ * @param allowedDomains Optional hostname allowlist. When provided and non-empty,
+ *                       any `url` source whose hostname is not in this list is
+ *                       rejected before any network request is made.
+ *                       Pass `FaceZkConfig.allowedDomains` here in production.
+ * @throws if the source has none of: module, url, localUri
+ * @throws if the download fails (url path)
+ */
+async function resolveModelUri(source, onProgress, allowedDomains) {
+    // ── 1. Already a local URI ──────────────────────────────────────────────
+    if (source.localUri) {
+        return source.localUri;
+    }
+    // ── 2. Metro-bundled module ─────────────────────────────────────────────
+    if (source.module != null) {
+        const asset = expo_asset_1.Asset.fromModule(source.module);
+        await asset.downloadAsync();
+        const uri = asset.localUri ?? asset.uri;
+        if (!uri) {
+            throw new Error("[FaceZkSdk] Failed to resolve bundled asset URI.");
+        }
+        return uri;
+    }
+    // ── 3. Remote URL – download and store persistently ─────────────────────
+    if (source.url) {
+        return downloadAndStore(source.url, onProgress, allowedDomains);
+    }
+    throw new Error("[FaceZkSdk] ModelSource must have at least one of: module, url, localUri.");
+}
+/**
+ * Derive the local store path for a given URL.
+ *
+ * Guards against path traversal in two passes:
+ *  1. URL-decode the last path segment so encoded separators like `%2F` or
+ *     `%2E%2E` are normalised before any checks run.
+ *  2. Re-extract the basename from the decoded string (a decoded `%2F`
+ *     becomes `/`, so a second `.split("/")` is needed).
+ *  3. Reject the reserved names `.` and `..` outright.
+ *  4. Allowlist `[A-Za-z0-9._-]` — the only characters that can appear in a
+ *     legitimate model filename.  Anything outside this set throws so the
+ *     caller can surface the problem rather than silently storing a bad file.
+ *
+ * @throws if the derived filename is empty, a traversal component, or contains
+ *         characters outside the safe allowlist.
+ */
+function deriveStorePath(url) {
+    // Step 1 – take the last slash-delimited segment and drop any query string
+    const raw = url.split("/").pop()?.split("?")[0] ?? "";
+    // Step 2 – URL-decode so encoded traversal sequences are normalised
+    let decoded;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        decoded = raw;
+    }
+    // Step 3 – re-extract basename in case decoding introduced new separators
+    const basename = decoded.replace(/\\/g, "/").split("/").pop() ?? "";
+    // Step 4 – reject empty names and dot-traversal components
+    if (!basename || basename === "." || basename === "..") {
+        throw new Error(`[FaceZkSdk] Unsafe or empty model filename derived from URL: "${url}"`);
+    }
+    // Step 5 – allowlist: only alphanumeric, dot, hyphen, underscore
+    if (!/^[A-Za-z0-9._-]+$/.test(basename)) {
+        throw new Error(`[FaceZkSdk] Model filename contains unsafe characters: "${basename}"`);
+    }
+    return `${exports.MODEL_STORE_DIR}${basename}`;
+}
+/**
+ * Download a remote model URL to documentDirectory.
+ * Skips download if the file already exists (store hit).
+ *
+ * Security layers (in order):
+ *  1. HTTPS-only — rejects http://, file://, data: etc.
+ *  2. Domain allowlist — rejects hostnames not in allowedDomains (if provided).
+ *  3. Path containment — asserts the derived local path stays inside MODEL_STORE_DIR.
+ */
+async function downloadAndStore(url, onProgress, allowedDomains) {
+    // ── Layer 1: HTTPS-only ────────────────────────────────────────────────
+    if (!url.startsWith("https://")) {
+        throw new Error(`[FaceZkSdk] Only HTTPS model URLs are permitted. Received: "${url.split("?")[0]}"`);
+    }
+    // ── Layer 2: Domain allowlist ──────────────────────────────────────────
+    if (allowedDomains && allowedDomains.length > 0) {
+        const hostnameMatch = url.match(/^https:\/\/([^/?#]+)/);
+        const hostname = hostnameMatch ? hostnameMatch[1] : null;
+        if (!hostname || !allowedDomains.includes(hostname)) {
+            throw new Error(`[FaceZkSdk] Model download blocked: hostname "${hostname ?? "unknown"}" is not in allowedDomains. ` +
+                `Allowed: [${allowedDomains.join(", ")}]`);
+        }
+    }
+    const localPath = deriveStorePath(url);
+    // ── Layer 3: Path containment ──────────────────────────────────────────
+    if (!localPath.startsWith(exports.MODEL_STORE_DIR)) {
+        throw new Error(`[FaceZkSdk] Security: derived path escapes model store. This is a bug — please report it.`);
+    }
+    // Ensure store directory exists
+    const dirInfo = await FileSystem.getInfoAsync(exports.MODEL_STORE_DIR);
+    if (!dirInfo.exists) {
+        await FileSystem.makeDirectoryAsync(exports.MODEL_STORE_DIR, {
+            intermediates: true,
+        });
+    }
+    // Return stored file if already present
+    const fileInfo = await FileSystem.getInfoAsync(localPath);
+    if (fileInfo.exists) {
+        return localPath;
+    }
+    // Download with optional progress reporting
+    const downloadResumable = FileSystem.createDownloadResumable(url, localPath, {}, onProgress
+        ? (progress) => {
+            if (progress.totalBytesExpectedToWrite > 0) {
+                onProgress(progress.totalBytesWritten / progress.totalBytesExpectedToWrite);
+            }
+        }
+        : undefined);
+    const result = await downloadResumable.downloadAsync();
+    if (!result || result.status < 200 || result.status >= 300) {
+        await FileSystem.deleteAsync(localPath, { idempotent: true });
+        throw new Error(`[FaceZkSdk] Failed to download model from ${url} (HTTP ${result?.status ?? "unknown"}).`);
+    }
+    return localPath;
+}
+/**
+ * Clear all URL-downloaded model files from the persistent store.
+ * Useful for forcing a re-download after a model version update.
+ */
+async function clearModelCache() {
+    const info = await FileSystem.getInfoAsync(exports.MODEL_STORE_DIR);
+    if (info.exists) {
+        await FileSystem.deleteAsync(exports.MODEL_STORE_DIR, { idempotent: true });
+    }
+}

package/dist/react-native/utils/resolveRuntimeAsset.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { FaceZkRuntimeAssetsConfig } from '../../config/types';
+/**
+ * Resolve a runtime asset key to its file contents as a string.
+ *
+ * @param key            Key from `FaceZkRuntimeAssetsConfig` (e.g. `'ortJs'`, `'livenessHtml'`).
+ * @param encoding       `'utf8'` for text assets (HTML, JS); `'base64'` for binary assets (WASM, data).
+ * @param allowedDomains Optional hostname allowlist forwarded to `resolveModelUri` for URL sources.
+ * @returns              File contents as a string in the requested encoding.
+ */
+export declare function resolveRuntimeAsset(key: keyof FaceZkRuntimeAssetsConfig, encoding: 'utf8' | 'base64', allowedDomains?: string[]): Promise<string>;

package/dist/react-native/utils/resolveRuntimeAsset.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRuntimeAsset = resolveRuntimeAsset;
+/**
+ * resolveRuntimeAsset
+ *
+ * Resolves a single runtime asset (HTML page, JS bundle, WASM binary, etc.)
+ * to its string contents (utf8 or base64).
+ *
+ * Resolution order:
+ *   1. If the SDK is initialised and `config.runtimeAssets[key]` is set,
+ *      use that `ModelSource` (supports module / url / localUri).
+ *   2. Otherwise fall back to the SDK's bundled copy via `BUNDLED_RUNTIME_ASSETS`.
+ *
+ * This mirrors the pattern already used by `useWasmLoader` for ZK assets and
+ * `FaceRecognition` for ONNX models, but generalised to all runtime assets.
+ */
+const FileSystem = __importStar(require("expo-file-system/legacy"));
+const FaceZkSdk_1 = require("../../FaceZkSdk");
+const bundledRuntimeAssets_1 = require("../bundledRuntimeAssets");
+const resolveModelUri_1 = require("./resolveModelUri");
+/**
+ * Resolve a runtime asset key to its file contents as a string.
+ *
+ * @param key            Key from `FaceZkRuntimeAssetsConfig` (e.g. `'ortJs'`, `'livenessHtml'`).
+ * @param encoding       `'utf8'` for text assets (HTML, JS); `'base64'` for binary assets (WASM, data).
+ * @param allowedDomains Optional hostname allowlist forwarded to `resolveModelUri` for URL sources.
+ * @returns              File contents as a string in the requested encoding.
+ */
+async function resolveRuntimeAsset(key, encoding, allowedDomains) {
+    // Pick the configured source if the SDK is initialised and the key is overridden;
+    // otherwise fall back to the SDK-bundled copy.
+    let source = bundledRuntimeAssets_1.BUNDLED_RUNTIME_ASSETS[key];
+    if (FaceZkSdk_1.FaceZkSdk.isInitialized()) {
+        const configured = FaceZkSdk_1.FaceZkSdk.getConfig().runtimeAssets?.[key];
+        if (configured) {
+            source = configured;
+        }
+    }
+    const localUri = await (0, resolveModelUri_1.resolveModelUri)(source, undefined, allowedDomains);
+    return FileSystem.readAsStringAsync(localUri, {
+        encoding: encoding === 'base64'
+            ? FileSystem.EncodingType.Base64
+            : FileSystem.EncodingType.UTF8,
+    });
+}

package/dist/react-native/utils/resolveUiConfig.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Face+ZK SDK – UI Config Resolver
+ *
+ * Merges user-supplied UiConfig with SDK defaults so flow components
+ * always have a complete, resolved theme and string set.
+ */
+import type { UiConfig, FaceZkTheme, FaceZkStrings } from "../../core/types";
+export declare const DEFAULT_THEME: FaceZkTheme;
+export declare const DEFAULT_STRINGS: Required<FaceZkStrings>;
+export interface ResolvedTheme extends FaceZkTheme {
+    colors: Required<FaceZkTheme["colors"]>;
+    borderRadius: number;
+}
+export interface ResolvedUiConfig {
+    theme: ResolvedTheme;
+    strings: Required<FaceZkStrings>;
+    renderLoading?: UiConfig["renderLoading"];
+    renderSuccess?: UiConfig["renderSuccess"];
+    renderError?: UiConfig["renderError"];
+    renderOverlay?: UiConfig["renderOverlay"];
+}
+export declare function resolveUiConfig(uiConfig?: UiConfig): ResolvedUiConfig;
+/**
+ * Replace `{score}` placeholder in a string template.
+ */
+export declare function interpolate(template: string, vars: Record<string, string | number>): string;

package/dist/react-native/utils/resolveUiConfig.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STRINGS = exports.DEFAULT_THEME = void 0;
+exports.resolveUiConfig = resolveUiConfig;
+exports.interpolate = interpolate;
+// ============================================================================
+// Defaults
+// ============================================================================
+exports.DEFAULT_THEME = {
+    colors: {
+        primary: "#4CAF50",
+        background: "#000000",
+        surface: "rgba(255,255,255,0.1)",
+        text: "#ffffff",
+        textMuted: "#aaaaaa",
+        error: "#F44336",
+    },
+    borderRadius: 8,
+};
+exports.DEFAULT_STRINGS = {
+    loadingInitializing: "Initializing...",
+    loadingModels: "Loading face recognition models...",
+    loadingCapturing: "Capturing image...",
+    loadingProcessing: "Processing reference image...",
+    loadingEmbedding: "Processing face...",
+    loadingMatching: "Matching face...",
+    loadingZkProof: "Generating cryptographic proof...",
+    verificationSuccessTitle: "Verified!",
+    verificationSuccessSubtitle: "Match: {score}%",
+    enrollmentSuccessTitle: "Reference Enrolled",
+    enrollmentSuccessSubtitle: "Your reference has been successfully enrolled.",
+    verificationErrorTitle: "Verification Failed",
+    enrollmentErrorTitle: "Enrollment Failed",
+    cancelButton: "Cancel",
+    retryButton: "Try Again",
+};
+// ============================================================================
+// Resolver
+// ============================================================================
+function resolveUiConfig(uiConfig = {}) {
+    const userColors = uiConfig.theme?.colors ?? {};
+    const userTheme = uiConfig.theme ?? {};
+    return {
+        theme: {
+            colors: {
+                ...exports.DEFAULT_THEME.colors,
+                ...userColors,
+            },
+            borderRadius: userTheme.borderRadius ?? exports.DEFAULT_THEME.borderRadius,
+        },
+        strings: {
+            ...exports.DEFAULT_STRINGS,
+            ...(uiConfig.strings ?? {}),
+        },
+        renderLoading: uiConfig.renderLoading,
+        renderSuccess: uiConfig.renderSuccess,
+        renderError: uiConfig.renderError,
+        renderOverlay: uiConfig.renderOverlay,
+    };
+}
+/**
+ * Replace `{score}` placeholder in a string template.
+ */
+function interpolate(template, vars) {
+    return template.replace(/\{(\w+)\}/g, (_, key) => key in vars ? String(vars[key]) : `{${key}}`);
+}