@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

package/dist/core/zk-core.js

@@ -0,0 +1,244 @@
+"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.generateZkProofOnly = generateZkProofOnly;
+exports.generateAndPersistZkProof = generateAndPersistZkProof;
+/**
+ * Generate a zero-knowledge proof from embeddings without running the full verification pipeline.
+ *
+ * This function focuses strictly on the cryptographic generation mechanism using the provided ZK engine.
+ * It is designed for advanced integrations where the caller computes embeddings manually or handles their own camera lifecycles.
+ *
+ * **ZK Context:** Plonky3 WASM circuits enforce that the Euclidean distance between `referenceEmbedding` and `liveEmbedding` does not exceed the globally compiled threshold. If it does, proof generation fails cryptographically, returning a structured `ZK_ERROR`.
+ *
+ * @param {FloatVector} referenceEmbedding - Trusted reference face embedding.
+ * @param {FloatVector} liveEmbedding - Face embedding derived from the current live capture.
+ * @param {FaceZkRuntimeConfig} sdkConfig - Global SDK configuration requiring `zk.enabled = true` and an injected `zk.engine`.
+ * @param {ZkProofOptions} options - Options containing optional `nonce`. If missing, cryptographically secure nonce is auto-generated.
+ * @returns {Promise<ZkProofSummary>} Cryptographic proof, inputs, and the verified hash.
+ * @throws {SdkError} Throws `ZK_ERROR` if the embeddings do not meet the circuit threshold, if vectors mismatch, or if ZK is not enabled.
+ *
+ * @example
+ * try {
+ *   const summary = await generateZkProofOnly(refEmbed, liveEmbed, config, {});
+ *   console.log(`Proof generated. Hash: ${summary.hash}`);
+ * } catch (error) {
+ *   console.error("Proof failed (threshold not met):", error);
+ * }
+ */
+async function generateZkProofOnly(referenceEmbedding, liveEmbedding, sdkConfig, options) {
+    const { nonce } = options;
+    // Validate ZK is enabled
+    if (!sdkConfig.zk?.enabled) {
+        const error = {
+            code: "ZK_ERROR",
+            message: "ZK proof generation requested but ZK is not enabled in config",
+            details: { stage: "zk_validation" },
+        };
+        sdkConfig.onLog?.({
+            level: "error",
+            message: error.message,
+            context: error,
+        });
+        throw error;
+    }
+    // Validate embeddings
+    if (!referenceEmbedding || referenceEmbedding.length === 0) {
+        const error = {
+            code: "ZK_ERROR",
+            message: "Invalid reference embedding (empty or undefined)",
+            details: { stage: "zk_validation" },
+        };
+        sdkConfig.onLog?.({
+            level: "error",
+            message: error.message,
+            context: error,
+        });
+        throw error;
+    }
+    if (!liveEmbedding || liveEmbedding.length === 0) {
+        const error = {
+            code: "ZK_ERROR",
+            message: "Invalid live embedding (empty or undefined)",
+            details: { stage: "zk_validation" },
+        };
+        sdkConfig.onLog?.({
+            level: "error",
+            message: error.message,
+            context: error,
+        });
+        throw error;
+    }
+    if (referenceEmbedding.length !== liveEmbedding.length) {
+        const error = {
+            code: "ZK_ERROR",
+            message: `Embedding dimension mismatch: reference=${referenceEmbedding.length}, live=${liveEmbedding.length}`,
+            details: {
+                stage: "zk_validation",
+                referenceDim: referenceEmbedding.length,
+                liveDim: liveEmbedding.length,
+            },
+        };
+        sdkConfig.onLog?.({
+            level: "error",
+            message: error.message,
+            context: error,
+        });
+        throw error;
+    }
+    sdkConfig.onLog?.({
+        level: "info",
+        message: "Starting ZK proof generation",
+        context: {
+            embeddingDim: referenceEmbedding.length,
+            nonce,
+        },
+    });
+    try {
+        const startTime = Date.now();
+        // Step 1: Generate nonce if not provided (cryptographically secure)
+        const actualNonce = nonce ?? Math.floor(Math.random() * 0xFFFFFFFF);
+        sdkConfig.onLog?.({
+            level: "debug",
+            message: "Generating ZK proof via engine",
+            context: { nonce: actualNonce },
+        });
+        // Step 2: Generate proof
+        const { proof, publicInputs } = await sdkConfig.zk.engine.generateProof(referenceEmbedding, liveEmbedding, actualNonce);
+        const proofGenDuration = Date.now() - startTime;
+        sdkConfig.onLog?.({
+            level: "debug",
+            message: "Proof generated, now verifying",
+            context: {
+                proofSize: proof.length,
+                publicInputsCount: publicInputs.length,
+                durationMs: proofGenDuration,
+            },
+        });
+        // Step 3: Verify proof
+        const verifyStartTime = Date.now();
+        const verified = await sdkConfig.zk.engine.verifyProof(proof, publicInputs);
+        const verifyDuration = Date.now() - verifyStartTime;
+        sdkConfig.onLog?.({
+            level: "debug",
+            message: "Proof verification complete",
+            context: { verified, durationMs: verifyDuration },
+        });
+        // Step 4: Compute hash
+        const hashStartTime = Date.now();
+        const hash = await sdkConfig.zk.engine.getProofHash(proof);
+        const hashDuration = Date.now() - hashStartTime;
+        sdkConfig.onLog?.({
+            level: "debug",
+            message: "Proof hash computed",
+            context: { hash, durationMs: hashDuration },
+        });
+        // Step 5: Build summary
+        const summary = {
+            proof,
+            publicInputs,
+            hash,
+            verified,
+            timestamp: Date.now(),
+            sizeBytes: new TextEncoder().encode(proof).length,
+        };
+        const totalDuration = Date.now() - startTime;
+        sdkConfig.onLog?.({
+            level: "info",
+            message: "ZK proof generation complete",
+            context: {
+                verified,
+                hash,
+                sizeBytes: summary.sizeBytes,
+                totalDurationMs: totalDuration,
+                breakdown: {
+                    generation: proofGenDuration,
+                    verification: verifyDuration,
+                    hashing: hashDuration,
+                },
+            },
+        });
+        return summary;
+    }
+    catch (error) {
+        const zkError = {
+            code: "ZK_ERROR",
+            message: error instanceof Error
+                ? error.message
+                : "ZK proof generation failed with unknown error",
+            details: {
+                stage: "zk_generation",
+                originalError: String(error),
+                embeddingDim: referenceEmbedding.length,
+            },
+        };
+        sdkConfig.onLog?.({
+            level: "error",
+            message: "ZK proof generation failed",
+            context: zkError,
+        });
+        throw zkError;
+    }
+}
+/**
+ * Helper function to generate a ZK proof and persist it securely using the active `StorageAdapter`.
+ *
+ * **Crypto Context:** The proof is persisted only if local verification against the generated public inputs passes. Unverified proofs will not be persisted to prevent storage poisoning.
+ *
+ * @param {string} referenceId - The opaque ID linking this proof to the enrolled reference.
+ * @param {FloatVector} referenceEmbedding - Trusted reference face embedding.
+ * @param {FloatVector} liveEmbedding - Live face embedding.
+ * @param {FaceZkRuntimeConfig} sdkConfig - SDK configuration including the configured `storage` adapter.
+ * @param {ZkProofOptions} options - Options containing optional `nonce`.
+ * @returns {Promise<{ summary: ZkProofSummary; proofId?: string }>} The generated ZK summary, and the storage handle if successfully persisted.
+ *
+ * @example
+ * const { summary, proofId } = await generateAndPersistZkProof(
+ *   'user-1234', refEmbed, liveEmbed, config, {}
+ * );
+ * console.log(`Proof stored under handle: ${proofId}`);
+ */
+async function generateAndPersistZkProof(referenceId, referenceEmbedding, liveEmbedding, sdkConfig, options) {
+    // Generate proof
+    const summary = await generateZkProofOnly(referenceEmbedding, liveEmbedding, sdkConfig, options);
+    // Persist if storage adapter is available
+    let proofId;
+    if (sdkConfig.storage?.saveProof && summary.verified) {
+        sdkConfig.onLog?.({
+            level: "debug",
+            message: "Persisting ZK proof",
+            context: { referenceId, hash: summary.hash },
+        });
+        proofId = await sdkConfig.storage.saveProof({
+            referenceId,
+            zkProof: summary,
+        });
+        sdkConfig.onLog?.({
+            level: "info",
+            message: "ZK proof persisted",
+            context: { referenceId, proofId, hash: summary.hash },
+        });
+    }
+    else if (sdkConfig.storage?.saveProof && !summary.verified) {
+        sdkConfig.onLog?.({
+            level: "warn",
+            message: "Skipping persistence of unverified ZK proof",
+            context: { referenceId, verified: summary.verified },
+        });
+    }
+    return { summary, proofId };
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 – Core Exports
+ *
+ * Main entry point for the Face+ZK SDK core functionality.
+ * This provides headless (non-UI) APIs for face verification and ZK proofs.
+ *
+ * For React Native UI components, import from '@jupitermetalabs/face-zk-sdk/react-native'
+ */
+export { FaceZkSdk } from "./FaceZkSdk";
+export type { FaceZkConfig, FaceZkModelsConfig, FaceZkFeaturesConfig, FaceZkSetupConfig, ModelSource, } from "./config/types";
+export type { FloatVector, Pose, LivenessCheckId, ReferenceId, ReferenceTemplate, ReferenceTemplateInput, LiveImageInfo, LiveCaptureResult, LivenessCheckResult, LivenessResult, FaceMatchResult, ZkProofSummary, SdkErrorCode, SdkError, VerificationOutcome, LivenessConfig, ZkProofEngine, ZkConfig, StorageAdapter, ReferenceStorageRecord, ProofStorageRecord, SdkLogger, FaceZkRuntimeConfig, VerificationOptions, EnrollmentOptions, ZkProofOptions, VerificationStage, UiConfig, FaceZkTheme, FaceZkStrings, } from "./core/types";
+export { l2SquaredDistance, l2SquaredToPercentage, computeFaceMatchResult, } from "./core/matching";
+export { createReferenceFromImage, type FaceEmbeddingProvider, } from "./core/enrollment-core";
+export { verifyOnly, verifyWithProof, type VerifyCallOptions, type LivenessProvider, } from "./core/verification-core";
+export { generateZkProofOnly, generateAndPersistZkProof, } from "./core/zk-core";

package/dist/index.js

@@ -0,0 +1,51 @@
+"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.
+ *
+ * Face+ZK SDK – Core Exports
+ *
+ * Main entry point for the Face+ZK SDK core functionality.
+ * This provides headless (non-UI) APIs for face verification and ZK proofs.
+ *
+ * For React Native UI components, import from '@jupitermetalabs/face-zk-sdk/react-native'
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAndPersistZkProof = exports.generateZkProofOnly = exports.verifyWithProof = exports.verifyOnly = exports.createReferenceFromImage = exports.computeFaceMatchResult = exports.l2SquaredToPercentage = exports.l2SquaredDistance = exports.FaceZkSdk = void 0;
+// ============================================================================
+// SDK Initialization
+// ============================================================================
+var FaceZkSdk_1 = require("./FaceZkSdk");
+Object.defineProperty(exports, "FaceZkSdk", { enumerable: true, get: function () { return FaceZkSdk_1.FaceZkSdk; } });
+// ============================================================================
+// Matching Functions
+// ============================================================================
+var matching_1 = require("./core/matching");
+Object.defineProperty(exports, "l2SquaredDistance", { enumerable: true, get: function () { return matching_1.l2SquaredDistance; } });
+Object.defineProperty(exports, "l2SquaredToPercentage", { enumerable: true, get: function () { return matching_1.l2SquaredToPercentage; } });
+Object.defineProperty(exports, "computeFaceMatchResult", { enumerable: true, get: function () { return matching_1.computeFaceMatchResult; } });
+// ============================================================================
+// Core Entrypoints
+// ============================================================================
+// Enrollment
+var enrollment_core_1 = require("./core/enrollment-core");
+Object.defineProperty(exports, "createReferenceFromImage", { enumerable: true, get: function () { return enrollment_core_1.createReferenceFromImage; } });
+// Verification
+var verification_core_1 = require("./core/verification-core");
+Object.defineProperty(exports, "verifyOnly", { enumerable: true, get: function () { return verification_core_1.verifyOnly; } });
+Object.defineProperty(exports, "verifyWithProof", { enumerable: true, get: function () { return verification_core_1.verifyWithProof; } });
+// ZK Proofs
+var zk_core_1 = require("./core/zk-core");
+Object.defineProperty(exports, "generateZkProofOnly", { enumerable: true, get: function () { return zk_core_1.generateZkProofOnly; } });
+Object.defineProperty(exports, "generateAndPersistZkProof", { enumerable: true, get: function () { return zk_core_1.generateAndPersistZkProof; } });

package/dist/react-native/adapters/faceEmbeddingProvider.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 Embedding Provider Adapter for React Native
+ *
+ * Wraps the existing faceRecognitionService to implement the FaceEmbeddingProvider interface.
+ * This adapter bridges the SDK core logic to the platform-specific implementation.
+ */
+import type { FaceEmbeddingProvider } from "../../core/enrollment-core";
+/**
+ * Create a face embedding provider that wraps faceRecognitionService.
+ *
+ * This adapter:
+ * - Implements the FaceEmbeddingProvider interface
+ * - Delegates to faceRecognitionService.processImageForEmbedding()
+ * - Guarantees embedding + pose are returned on success
+ *
+ * @returns FaceEmbeddingProvider implementation
+ */
+export declare function createFaceEmbeddingProvider(): FaceEmbeddingProvider;
+/**
+ * Singleton instance for convenience.
+ * Use this if you don't need custom configuration.
+ */
+export declare const defaultFaceEmbeddingProvider: FaceEmbeddingProvider;

package/dist/react-native/adapters/faceEmbeddingProvider.js

@@ -0,0 +1,45 @@
+"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.defaultFaceEmbeddingProvider = void 0;
+exports.createFaceEmbeddingProvider = createFaceEmbeddingProvider;
+const FaceRecognition_1 = require("../services/FaceRecognition");
+/**
+ * Create a face embedding provider that wraps faceRecognitionService.
+ *
+ * This adapter:
+ * - Implements the FaceEmbeddingProvider interface
+ * - Delegates to faceRecognitionService.processImageForEmbedding()
+ * - Guarantees embedding + pose are returned on success
+ *
+ * @returns FaceEmbeddingProvider implementation
+ */
+function createFaceEmbeddingProvider() {
+    return {
+        async processImageForEmbedding(imageUri) {
+            // Delegate to existing service
+            const result = await FaceRecognition_1.faceRecognitionService.processImageForEmbedding(imageUri);
+            // Return result as-is (it already matches the expected format)
+            return result;
+        },
+    };
+}
+/**
+ * Singleton instance for convenience.
+ * Use this if you don't need custom configuration.
+ */
+exports.defaultFaceEmbeddingProvider = createFaceEmbeddingProvider();

package/dist/react-native/adapters/imageDataProvider.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+/**
+ * Image Data Provider Adapter for React Native
+ *
+ * Provides platform-specific image data reading capabilities (base64, file size).
+ * This keeps the SDK core framework-agnostic while providing necessary functionality.
+ */
+import type { ImageDataProvider } from "../../core/verification-core";
+/**
+ * Create an image data provider using Expo FileSystem.
+ *
+ * This adapter implements base64 reading and file size retrieval
+ * for React Native / Expo environments.
+ *
+ * @returns ImageDataProvider implementation for React Native
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultImageDataProvider } from './sdk/react-native/adapters/imageDataProvider';
+ *
+ * const imageDataProvider = createDefaultImageDataProvider();
+ *
+ * // Use in verification
+ * const outcome = await verifyOnly(
+ *   reference,
+ *   liveImageUri,
+ *   sdkConfig,
+ *   embeddingProvider,
+ *   livenessProvider,
+ *   imageDataProvider, // <-- enables base64/sizeKb
+ *   { includeImageData: { base64: true, sizeKb: true } },
+ * );
+ * ```
+ */
+export declare function createDefaultImageDataProvider(): ImageDataProvider;
+/**
+ * Default singleton instance for convenience.
+ */
+export declare const defaultImageDataProvider: ImageDataProvider;

package/dist/react-native/adapters/imageDataProvider.js

@@ -0,0 +1,134 @@
+"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.defaultImageDataProvider = void 0;
+exports.createDefaultImageDataProvider = createDefaultImageDataProvider;
+const FileSystem = __importStar(require("expo-file-system/legacy"));
+/**
+ * Create an image data provider using Expo FileSystem.
+ *
+ * This adapter implements base64 reading and file size retrieval
+ * for React Native / Expo environments.
+ *
+ * @returns ImageDataProvider implementation for React Native
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultImageDataProvider } from './sdk/react-native/adapters/imageDataProvider';
+ *
+ * const imageDataProvider = createDefaultImageDataProvider();
+ *
+ * // Use in verification
+ * const outcome = await verifyOnly(
+ *   reference,
+ *   liveImageUri,
+ *   sdkConfig,
+ *   embeddingProvider,
+ *   livenessProvider,
+ *   imageDataProvider, // <-- enables base64/sizeKb
+ *   { includeImageData: { base64: true, sizeKb: true } },
+ * );
+ * ```
+ */
+function createDefaultImageDataProvider() {
+    return {
+        async readAsBase64(imageUri) {
+            try {
+                const base64 = await FileSystem.readAsStringAsync(imageUri, {
+                    encoding: FileSystem.EncodingType.Base64,
+                });
+                return base64;
+            }
+            catch (error) {
+                throw new Error(`Failed to read image as base64: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        async getFileSizeBytes(imageUri) {
+            try {
+                const fileInfo = await FileSystem.getInfoAsync(imageUri);
+                if (!fileInfo.exists) {
+                    throw new Error(`File does not exist: ${imageUri}`);
+                }
+                // getInfoAsync returns { exists, uri, size?, ... }
+                if ("size" in fileInfo && typeof fileInfo.size === "number") {
+                    return fileInfo.size;
+                }
+                throw new Error(`File size not available for: ${imageUri}`);
+            }
+            catch (error) {
+                throw new Error(`Failed to get file size: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        async analyzeQuality(imageUri) {
+            // Quality is estimated from file size — a practical proxy for face image
+            // fidelity without requiring additional image-processing dependencies.
+            // Thresholds are calibrated for compressed JPEG face captures:
+            //   < 5 KB  → heavily compressed / thumbnail → score near 0
+            //   ≥ 200 KB → high-detail capture            → score near 1
+            const MIN_BYTES = 5_000;
+            const MAX_BYTES = 200_000;
+            try {
+                const fileInfo = await FileSystem.getInfoAsync(imageUri);
+                if (!fileInfo.exists || !("size" in fileInfo) || typeof fileInfo.size !== "number") {
+                    return 0;
+                }
+                const clamped = Math.max(MIN_BYTES, Math.min(MAX_BYTES, fileInfo.size));
+                return Math.round(((clamped - MIN_BYTES) / (MAX_BYTES - MIN_BYTES)) * 100) / 100;
+            }
+            catch {
+                return 0;
+            }
+        },
+    };
+}
+/**
+ * Default singleton instance for convenience.
+ */
+exports.defaultImageDataProvider = createDefaultImageDataProvider();