@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

package/dist/core/verification-core.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 – Verification Core
+ *
+ * Headless verification functions for face matching with optional ZK proofs.
+ * This module orchestrates reference resolution, live capture, liveness checks,
+ * matching, and optional ZK proof generation.
+ */
+import type { ReferenceTemplate, ReferenceTemplateInput, ReferenceId, LivenessResult, VerificationOutcome, FaceZkRuntimeConfig, VerificationOptions } from "./types";
+import type { FaceEmbeddingProvider } from "./enrollment-core";
+export type { FaceEmbeddingProvider };
+/**
+ * Interface for liveness provider.
+ * This will be implemented by platform-specific adapters.
+ */
+export interface LivenessProvider {
+    /**
+     * Run liveness checks on a captured image/frame.
+     *
+     * @param imageUri URI of the image to check
+     * @returns Liveness result with pass/fail and optional checks
+     */
+    checkLiveness(imageUri: string): Promise<LivenessResult>;
+}
+/**
+ * Interface for reading image data (base64, file size, etc.).
+ * This keeps the core framework-agnostic - platform adapters provide implementation.
+ */
+export interface ImageDataProvider {
+    /**
+     * Read image as base64 string
+     * @param imageUri URI of the image
+     * @returns Base64-encoded image string
+     */
+    readAsBase64(imageUri: string): Promise<string>;
+    /**
+     * Get image file size in bytes
+     * @param imageUri URI of the image
+     * @returns Size in bytes
+     */
+    getFileSizeBytes(imageUri: string): Promise<number>;
+    /**
+     * Estimate an image quality score (0–1, higher = better).
+     * Implementation is platform-specific; a file-size heuristic is acceptable.
+     * @param imageUri URI of the image
+     * @returns Quality score between 0 and 1
+     */
+    analyzeQuality?(imageUri: string): Promise<number>;
+}
+/**
+ * Per-call options for {@link verifyOnly} and {@link verifyWithProof}.
+ * Extends {@link VerificationOptions} with optional provider overrides for this call.
+ */
+export interface VerifyCallOptions extends VerificationOptions {
+    /** Liveness provider for this call. */
+    livenessProvider?: LivenessProvider;
+    /** Image-data provider for this call (base64, size, quality). */
+    imageDataProvider?: ImageDataProvider;
+}
+/**
+ * Performs a face match verification without generating a Zero-Knowledge proof.
+ *
+ * This function orchestrates the standard verification pipeline:
+ * 1. Resolves the enrolled `ReferenceTemplate`.
+ * 2. Captures and extracts the live facial embedding via `FaceEmbeddingProvider`.
+ * 3. Evaluates anti-spoofing via the optional `LivenessProvider`.
+ * 4. Computes the raw L2² distance.
+ *
+ * **Security Warning:** This bypasses the cryptographic ZK verification. The `success` boolean returned here is based *only* on the liveness result (if enabled). Because the threshold API was removed in v3.0, the SDK does not natively fail the match here; your application logic must interpret the `FaceMatchResult` manually if you choose not to use `verifyWithProof`.
+ *
+ * @param {ReferenceTemplate | ReferenceTemplateInput | ReferenceId} reference - The enrolled identity to compare against.
+ * @param {string} liveImageUri - URI of the live capture frame.
+ * @param {FaceZkRuntimeConfig} sdkConfig - Global SDK Configuration.
+ * @param {FaceEmbeddingProvider} embeddingProvider - Platform adapter for extracting embeddings.
+ * @param {VerifyCallOptions} [options={}] - Per-call options: config overrides plus optional liveness and image-data providers.
+ * @returns {Promise<VerificationOutcome>} The completed outcome including the fractional match percentage.
+ *
+ * @example
+ * const outcome = await verifyOnly(refId, 'file:///live.jpg', config, embedProv);
+ * @example With providers
+ * const outcome = await verifyOnly(refId, uri, config, embedProv, { livenessProvider, liveness: { enabled: true } });
+ */
+export declare function verifyOnly(reference: ReferenceTemplate | ReferenceTemplateInput | ReferenceId, liveImageUri: string, sdkConfig: FaceZkRuntimeConfig, embeddingProvider: FaceEmbeddingProvider, options?: VerifyCallOptions): Promise<VerificationOutcome>;
+/**
+ * Performs a high-security face match verification backed by a Zero-Knowledge proof.
+ *
+ * This is the primary verification gateway. It executes the standard pipeline (via `verifyOnly`) and then funnels the resulting exact embeddings into the ZK WASM circuit.
+ *
+ * **Crypto/ZK Context:** The circuit mathematically guarantees that:
+ * 1. The distance between the live and reference embeddings is strictly less than the compiled threshold.
+ * 2. The computation was executed faithfully.
+ * If this condition is not met, the cryptographic verification fails, and `zkOutcome.success` is forced to `false` (assuming `zk.requiredForSuccess` is true).
+ *
+ * @param {ReferenceTemplate | ReferenceTemplateInput | ReferenceId} reference - The enrolled identity to verify.
+ * @param {string} liveImageUri - URI of the live capture frame.
+ * @param {FaceZkRuntimeConfig} sdkConfig - Global SDK configuration requiring `zk.enabled = true`.
+ * @param {FaceEmbeddingProvider} embeddingProvider - Platform adapter for extracting embeddings.
+ * @param {VerifyCallOptions} [options={}] - Per-call options: config overrides plus optional liveness and image-data providers.
+ * @returns {Promise<VerificationOutcome>} The completed outcome, containing the `ZkProofSummary` and cryptographic success state.
+ *
+ * @example
+ * const outcome = await verifyWithProof(refId, uri, config, embedProv);
+ * @example With liveness provider
+ * const outcome = await verifyWithProof(refId, uri, config, embedProv, { livenessProvider });
+ */
+export declare function verifyWithProof(reference: ReferenceTemplate | ReferenceTemplateInput | ReferenceId, liveImageUri: string, sdkConfig: FaceZkRuntimeConfig, embeddingProvider: FaceEmbeddingProvider, options?: VerifyCallOptions): Promise<VerificationOutcome>;

package/dist/core/verification-core.js

@@ -0,0 +1,442 @@
+"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.verifyOnly = verifyOnly;
+exports.verifyWithProof = verifyWithProof;
+const types_1 = require("./types");
+const matching_1 = require("./matching");
+const idGenerator_1 = require("./idGenerator");
+/**
+ * Resolve a reference to a ReferenceTemplate.
+ * Accepts:
+ * - ReferenceTemplate (pass-through)
+ * - ReferenceTemplateInput (convert to ReferenceTemplate)
+ * - ReferenceId (load from storage)
+ */
+async function resolveReference(reference, sdkConfig) {
+    // If it's already a ReferenceTemplate, return as-is
+    if (typeof reference === "object" &&
+        "referenceId" in reference &&
+        "embedding" in reference &&
+        "pose" in reference) {
+        // Check if it has all required fields of ReferenceTemplate
+        if (typeof reference.referenceId === "string" &&
+            Array.isArray(reference.embedding) &&
+            reference.pose &&
+            typeof reference.pose === "object") {
+            return reference;
+        }
+    }
+    // If it's a string (ReferenceId), load from storage
+    if (typeof reference === "string") {
+        const referenceId = reference;
+        if (!sdkConfig.storage) {
+            const error = {
+                code: "NO_REFERENCE",
+                message: "Reference ID provided but no storage adapter configured",
+                details: { referenceId },
+            };
+            throw error;
+        }
+        sdkConfig.onLog?.({
+            level: "debug",
+            message: "Loading reference from storage",
+            context: { referenceId },
+        });
+        const template = await sdkConfig.storage.loadReference(referenceId);
+        if (!template) {
+            const error = {
+                code: "NO_REFERENCE",
+                message: `Reference not found: ${referenceId}`,
+                details: { referenceId },
+            };
+            throw error;
+        }
+        return template;
+    }
+    // Otherwise, it's a ReferenceTemplateInput - convert to ReferenceTemplate
+    const input = reference;
+    // Generate referenceId if not provided
+    const referenceId = input.referenceId ||
+        generateSecureId("ref");
+    return {
+        referenceId,
+        embedding: input.embedding,
+        pose: input.pose,
+        metadata: input.metadata,
+    };
+}
+/**
+ * Compute live capture result from an image URI.
+ * Extracts embedding, pose, and optional image metadata.
+ */
+async function computeLiveCapture(liveImageUri, embeddingProvider, sdkConfig, options, imageDataProvider) {
+    sdkConfig.onLog?.({
+        level: "debug",
+        message: "Computing live capture",
+        context: { liveImageUri },
+    });
+    const result = await embeddingProvider.processImageForEmbedding(liveImageUri);
+    if (result.status !== "ok") {
+        const errorCode = result.status === "no_face"
+            ? "NO_FACE"
+            : result.status === "multiple_faces"
+                ? "MULTIPLE_FACES"
+                : "SYSTEM_ERROR";
+        const error = {
+            code: errorCode,
+            message: result.message || `Face processing failed: ${result.status}`,
+            details: { stage: "live_capture", status: result.status },
+        };
+        throw error;
+    }
+    if (!result.embedding) {
+        const error = {
+            code: "SYSTEM_ERROR",
+            message: "Face processing succeeded but missing embedding",
+            details: { stage: "live_capture" },
+        };
+        throw error;
+    }
+    // Build image info
+    const imageInfo = {
+        imageUri: liveImageUri,
+    };
+    // Optionally compute base64, sizeKb, qualityScore if requested
+    if (options?.includeImageData && imageDataProvider) {
+        const { base64, sizeKb, qualityScore } = options.includeImageData;
+        if (base64 || sizeKb) {
+            try {
+                // Use platform-specific image data provider (keeps core framework-agnostic)
+                const imageBase64 = await imageDataProvider.readAsBase64(liveImageUri);
+                if (base64) {
+                    imageInfo.imageBase64 = imageBase64;
+                }
+                if (sizeKb) {
+                    // Calculate size from base64 length
+                    // Base64 is ~33% larger than binary, so we divide by 1.33 and convert to KB
+                    const binarySize = (imageBase64.length * 3) / 4;
+                    imageInfo.sizeKb = Math.round((binarySize / 1024) * 100) / 100;
+                }
+            }
+            catch (error) {
+                sdkConfig.onLog?.({
+                    level: "warn",
+                    message: "Failed to read image data",
+                    context: { error: String(error) },
+                });
+            }
+        }
+        if (qualityScore && imageDataProvider?.analyzeQuality) {
+            imageInfo.qualityScore = await imageDataProvider.analyzeQuality(liveImageUri);
+        }
+    }
+    else if (options?.includeImageData && !imageDataProvider) {
+        sdkConfig.onLog?.({
+            level: "warn",
+            message: "includeImageData requested but no ImageDataProvider provided, skipping image data",
+        });
+    }
+    return {
+        embedding: result.embedding,
+        pose: result.pose,
+        image: imageInfo,
+        gender: result.gender,
+        age: result.age,
+    };
+}
+/**
+ * Merge verification options with SDK config.
+ */
+function mergeConfig(sdkConfig, options) {
+    const merged = { ...sdkConfig };
+    // Merge liveness config
+    if (options.liveness && sdkConfig.liveness) {
+        merged.liveness = { ...sdkConfig.liveness, ...options.liveness };
+    }
+    else if (sdkConfig.liveness) {
+        merged.liveness = sdkConfig.liveness;
+    }
+    // Merge ZK config
+    if (options.zk && sdkConfig.zk) {
+        merged.zk = { ...sdkConfig.zk, ...options.zk };
+    }
+    else if (sdkConfig.zk) {
+        merged.zk = sdkConfig.zk;
+    }
+    return merged;
+}
+/**
+ * Performs a face match verification without generating a Zero-Knowledge proof.
+ *
+ * This function orchestrates the standard verification pipeline:
+ * 1. Resolves the enrolled `ReferenceTemplate`.
+ * 2. Captures and extracts the live facial embedding via `FaceEmbeddingProvider`.
+ * 3. Evaluates anti-spoofing via the optional `LivenessProvider`.
+ * 4. Computes the raw L2² distance.
+ *
+ * **Security Warning:** This bypasses the cryptographic ZK verification. The `success` boolean returned here is based *only* on the liveness result (if enabled). Because the threshold API was removed in v3.0, the SDK does not natively fail the match here; your application logic must interpret the `FaceMatchResult` manually if you choose not to use `verifyWithProof`.
+ *
+ * @param {ReferenceTemplate | ReferenceTemplateInput | ReferenceId} reference - The enrolled identity to compare against.
+ * @param {string} liveImageUri - URI of the live capture frame.
+ * @param {FaceZkRuntimeConfig} sdkConfig - Global SDK Configuration.
+ * @param {FaceEmbeddingProvider} embeddingProvider - Platform adapter for extracting embeddings.
+ * @param {VerifyCallOptions} [options={}] - Per-call options: config overrides plus optional liveness and image-data providers.
+ * @returns {Promise<VerificationOutcome>} The completed outcome including the fractional match percentage.
+ *
+ * @example
+ * const outcome = await verifyOnly(refId, 'file:///live.jpg', config, embedProv);
+ * @example With providers
+ * const outcome = await verifyOnly(refId, uri, config, embedProv, { livenessProvider, liveness: { enabled: true } });
+ */
+async function verifyOnly(reference, liveImageUri, sdkConfig, embeddingProvider, options = {}) {
+    const { livenessProvider, imageDataProvider, ...configOptions } = options;
+    const config = mergeConfig(sdkConfig, configOptions);
+    config.onLog?.({
+        level: "info",
+        message: "Starting verification (match only)",
+        context: { liveImageUri },
+    });
+    try {
+        // Step 1: Resolve reference
+        const resolvedReference = await resolveReference(reference, config);
+        // Step 2: Compute live capture
+        const liveCapture = await computeLiveCapture(liveImageUri, embeddingProvider, config, options, imageDataProvider);
+        // Step 3: Run liveness (if enabled)
+        let livenessResult;
+        if (config.liveness?.enabled && livenessProvider) {
+            config.onLog?.({
+                level: "debug",
+                message: "Running liveness checks",
+            });
+            livenessResult = await livenessProvider.checkLiveness(liveImageUri);
+            if (!livenessResult.passed) {
+                config.onLog?.({
+                    level: "warn",
+                    message: "Liveness check failed",
+                    context: { livenessResult },
+                });
+                return {
+                    success: false,
+                    score: 0,
+                    liveness: livenessResult,
+                    reference: resolvedReference,
+                    live: liveCapture,
+                    error: {
+                        code: "LIVENESS_FAILED",
+                        message: "Liveness check did not pass",
+                        details: { stage: "liveness", livenessResult },
+                    },
+                };
+            }
+        }
+        // Step 4: Compute match result
+        config.onLog?.({
+            level: "debug",
+            message: "Computing face match",
+        });
+        const matchResult = (0, matching_1.computeFaceMatchResult)(resolvedReference.embedding, liveCapture.embedding);
+        config.onLog?.({
+            level: "info",
+            message: "Match computation complete",
+            context: {
+                distance: matchResult.distance,
+                matchPercentage: matchResult.matchPercentage,
+            },
+        });
+        // Step 5: Build outcome
+        // Pass/fail is determined by the ZK engine; here we only gate on liveness.
+        const success = livenessResult?.passed ?? true;
+        return {
+            success,
+            score: matchResult.matchPercentage,
+            match: matchResult,
+            liveness: livenessResult,
+            reference: resolvedReference,
+            live: liveCapture,
+        };
+    }
+    catch (error) {
+        // If it's already an SdkError, wrap it in outcome
+        if ((0, types_1.isSdkError)(error)) {
+            return {
+                success: false,
+                score: 0,
+                error,
+            };
+        }
+        // Wrap unexpected errors
+        const sdkError = {
+            code: "SYSTEM_ERROR",
+            message: error instanceof Error ? error.message : "Unknown error",
+            details: { stage: "verification", originalError: String(error) },
+        };
+        return {
+            success: false,
+            score: 0,
+            error: sdkError,
+        };
+    }
+}
+/**
+ * Performs a high-security face match verification backed by a Zero-Knowledge proof.
+ *
+ * This is the primary verification gateway. It executes the standard pipeline (via `verifyOnly`) and then funnels the resulting exact embeddings into the ZK WASM circuit.
+ *
+ * **Crypto/ZK Context:** The circuit mathematically guarantees that:
+ * 1. The distance between the live and reference embeddings is strictly less than the compiled threshold.
+ * 2. The computation was executed faithfully.
+ * If this condition is not met, the cryptographic verification fails, and `zkOutcome.success` is forced to `false` (assuming `zk.requiredForSuccess` is true).
+ *
+ * @param {ReferenceTemplate | ReferenceTemplateInput | ReferenceId} reference - The enrolled identity to verify.
+ * @param {string} liveImageUri - URI of the live capture frame.
+ * @param {FaceZkRuntimeConfig} sdkConfig - Global SDK configuration requiring `zk.enabled = true`.
+ * @param {FaceEmbeddingProvider} embeddingProvider - Platform adapter for extracting embeddings.
+ * @param {VerifyCallOptions} [options={}] - Per-call options: config overrides plus optional liveness and image-data providers.
+ * @returns {Promise<VerificationOutcome>} The completed outcome, containing the `ZkProofSummary` and cryptographic success state.
+ *
+ * @example
+ * const outcome = await verifyWithProof(refId, uri, config, embedProv);
+ * @example With liveness provider
+ * const outcome = await verifyWithProof(refId, uri, config, embedProv, { livenessProvider });
+ */
+async function verifyWithProof(reference, liveImageUri, sdkConfig, embeddingProvider, options = {}) {
+    const { livenessProvider, imageDataProvider, ...configOptions } = options;
+    const config = mergeConfig(sdkConfig, configOptions);
+    // If ZK is not enabled, fall back to verify-only (match without proof)
+    if (!config.zk?.enabled) {
+        config.onLog?.({
+            level: "warn",
+            message: "ZK proof requested but ZK is not enabled in config, falling back to verify-only",
+            context: { stage: "zk_validation" },
+        });
+        return verifyOnly(reference, liveImageUri, sdkConfig, embeddingProvider, options);
+    }
+    // config.zk is guaranteed defined here — the early return above exits if !config.zk?.enabled
+    const zkConfig = config.zk;
+    config.onLog?.({
+        level: "info",
+        message: "Starting verification with ZK proof",
+        context: { liveImageUri },
+    });
+    // First, run normal verification
+    const outcome = await verifyOnly(reference, liveImageUri, sdkConfig, embeddingProvider, options);
+    // If verification failed before matching, return early
+    if (!outcome.match || !outcome.reference || !outcome.live) {
+        config.onLog?.({
+            level: "warn",
+            message: "Verification failed before ZK proof generation",
+            context: { error: outcome.error },
+        });
+        return outcome;
+    }
+    try {
+        // Generate ZK proof
+        config.onLog?.({
+            level: "debug",
+            message: "Generating ZK proof",
+        });
+        const id = (0, idGenerator_1.generateReferenceId)();
+        // Parse the last 8 characters of the ID to use as a 32-bit nonce
+        const nonce = parseInt(id.slice(-8), 16);
+        const startTime = Date.now();
+        const { proof, publicInputs } = await config.zk.engine.generateProof(outcome.reference.embedding, outcome.live.embedding, nonce);
+        config.onLog?.({
+            level: "debug",
+            message: "Verifying ZK proof",
+        });
+        const verified = await config.zk.engine.verifyProof(proof, publicInputs);
+        config.onLog?.({
+            level: "debug",
+            message: "Computing proof hash",
+        });
+        const hash = await config.zk.engine.getProofHash(proof);
+        const zkProof = {
+            proof,
+            publicInputs,
+            hash,
+            verified,
+            timestamp: Date.now(),
+            sizeBytes: new TextEncoder().encode(proof).length,
+        };
+        config.onLog?.({
+            level: "info",
+            message: "ZK proof generated and verified",
+            context: {
+                verified,
+                hash,
+                durationMs: Date.now() - startTime,
+            },
+        });
+        // Build new outcome with ZK results — no mutation of the original object (C-12)
+        const zkOutcome = zkConfig.requiredForSuccess && !verified
+            ? {
+                ...outcome,
+                zkProof,
+                success: false,
+                error: {
+                    code: "ZK_ERROR",
+                    message: "ZK proof verification failed",
+                    details: { stage: "zk_verification", zkProof },
+                },
+            }
+            : { ...outcome, zkProof };
+        // Optionally persist proof via storage adapter
+        if (config.storage?.saveProof && verified) {
+            config.onLog?.({
+                level: "debug",
+                message: "Persisting ZK proof",
+            });
+            await config.storage.saveProof({
+                referenceId: outcome.reference.referenceId,
+                zkProof,
+            });
+        }
+        return zkOutcome;
+    }
+    catch (error) {
+        const zkError = {
+            code: "ZK_ERROR",
+            message: error instanceof Error ? error.message : "ZK proof failed",
+            details: {
+                stage: "zk_generation",
+                originalError: String(error),
+            },
+        };
+        config.onLog?.({
+            level: "error",
+            message: "ZK proof generation failed",
+            context: { ...zkError.details, code: zkError.code },
+        });
+        // If ZK is required for success, mark as failure
+        if (zkConfig.requiredForSuccess) {
+            return {
+                ...outcome,
+                success: false,
+                error: zkError,
+            };
+        }
+        // Otherwise, return outcome with error but original success state
+        return {
+            ...outcome,
+            error: zkError,
+        };
+    }
+}
+function generateSecureId(prefix) {
+    return (0, idGenerator_1.generateReferenceId)().replace(/^ref_/, `${prefix}_`);
+}

package/dist/core/zk-core.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 – ZK Proof Core
+ *
+ * Functions for generating and managing zero-knowledge proofs.
+ * This module provides standalone ZK proof generation for advanced use cases
+ * where the caller already has embeddings and just needs the proof.
+ */
+import type { FloatVector, ZkProofSummary, ZkProofOptions, FaceZkRuntimeConfig } from "./types";
+/**
+ * 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);
+ * }
+ */
+export declare function generateZkProofOnly(referenceEmbedding: FloatVector, liveEmbedding: FloatVector, sdkConfig: FaceZkRuntimeConfig, options: ZkProofOptions): Promise<ZkProofSummary>;
+/**
+ * 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}`);
+ */
+export declare function generateAndPersistZkProof(referenceId: string, referenceEmbedding: FloatVector, liveEmbedding: FloatVector, sdkConfig: FaceZkRuntimeConfig, options: ZkProofOptions): Promise<{
+    summary: ZkProofSummary;
+    proofId?: string;
+}>;