@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

package/dist/core/matching.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 – Matching Core
+ *
+ * Pure matching functions for face embeddings.
+ * All functions are synchronous and have no side effects for easy testing.
+ *
+ * Based on: src/utils/mathUtils.ts
+ */
+import type { FloatVector, FaceMatchResult } from "./types";
+/**
+ * Calculates the L2 squared distance between two vectors.
+ * More efficient for mobile devices as it skips square root operations and bounds checking.
+ *
+ * **Crypto/ZK Context:** The raw distance computed here provides UI feedback, but the actual cryptographic proof relies on the unaltered feature vectors.
+ *
+ * @param {FloatVector} a - First facial embedding vector.
+ * @param {FloatVector} b - Second facial embedding vector.
+ * @returns {number} The L2² distance. Lower is better. 0 = identical vectors.
+ * @throws {Error} Throws if vectors are empty or mismatched in length.
+ *
+ * @example
+ * const dist = l2SquaredDistance(liveEmbedding, refEmbedding);
+ * console.log(`Distance: ${dist}`);
+ */
+export declare function l2SquaredDistance(a: FloatVector, b: FloatVector): number;
+/**
+ * Converts L2² distance to a human-readable percentage match score.
+ *
+ * Precondition: `l2Squared` is the scalar output of `l2SquaredDistance` applied to
+ * two normalized embeddings, which places it in [0, 4].
+ *
+ * @param {number} l2Squared - The L2 squared distance (scalar).
+ * @returns {number} Match percentage (0-100). Higher is better.
+ *
+ * @example
+ * const percentage = l2SquaredToPercentage(1.2);
+ * console.log(`Match: ${percentage}%`); // Extrapolates onto a 0-100 curve
+ */
+export declare function l2SquaredToPercentage(l2Squared: number): number;
+/**
+ * Computes a face match result from two embeddings for informational use.
+ *
+ * **Important:** This function no longer returns a boolean pass/fail flag.
+ * Pass/fail is determined by the ZK engine (which explicitly owns the threshold), not by this function.
+ *
+ * @param {FloatVector} referenceEmbedding - Reference face embedding.
+ * @param {FloatVector} liveEmbedding - Live face embedding.
+ * @returns {FaceMatchResult} Match result containing raw distance and percentage.
+ *
+ * @example
+ * const result = computeFaceMatchResult(refEmbed, liveEmbed);
+ * console.log(`Match confidence: ${result.matchPercentage}%`);
+ */
+export declare function computeFaceMatchResult(referenceEmbedding: FloatVector, liveEmbedding: FloatVector): FaceMatchResult;

package/dist/core/matching.js

@@ -0,0 +1,101 @@
+"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.l2SquaredDistance = l2SquaredDistance;
+exports.l2SquaredToPercentage = l2SquaredToPercentage;
+exports.computeFaceMatchResult = computeFaceMatchResult;
+/**
+ * Calculates the L2 squared distance between two vectors.
+ * More efficient for mobile devices as it skips square root operations and bounds checking.
+ *
+ * **Crypto/ZK Context:** The raw distance computed here provides UI feedback, but the actual cryptographic proof relies on the unaltered feature vectors.
+ *
+ * @param {FloatVector} a - First facial embedding vector.
+ * @param {FloatVector} b - Second facial embedding vector.
+ * @returns {number} The L2² distance. Lower is better. 0 = identical vectors.
+ * @throws {Error} Throws if vectors are empty or mismatched in length.
+ *
+ * @example
+ * const dist = l2SquaredDistance(liveEmbedding, refEmbedding);
+ * console.log(`Distance: ${dist}`);
+ */
+function l2SquaredDistance(a, b) {
+    if (a.length === 0 || b.length === 0) {
+        throw new Error("l2SquaredDistance: embeddings cannot be empty");
+    }
+    if (a.length !== b.length) {
+        throw new Error(`l2SquaredDistance: embedding length mismatch (${a.length} vs ${b.length})`);
+    }
+    let sumSquared = 0;
+    const len = a.length;
+    // Unrolled loop for better performance (process 4 at a time)
+    let i = 0;
+    for (; i < len - 3; i += 4) {
+        const d0 = a[i] - b[i];
+        const d1 = a[i + 1] - b[i + 1];
+        const d2 = a[i + 2] - b[i + 2];
+        const d3 = a[i + 3] - b[i + 3];
+        sumSquared += d0 * d0 + d1 * d1 + d2 * d2 + d3 * d3;
+    }
+    // Handle remaining elements
+    for (; i < len; i++) {
+        const diff = a[i] - b[i];
+        sumSquared += diff * diff;
+    }
+    return sumSquared;
+}
+/**
+ * Converts L2² distance to a human-readable percentage match score.
+ *
+ * Precondition: `l2Squared` is the scalar output of `l2SquaredDistance` applied to
+ * two normalized embeddings, which places it in [0, 4].
+ *
+ * @param {number} l2Squared - The L2 squared distance (scalar).
+ * @returns {number} Match percentage (0-100). Higher is better.
+ *
+ * @example
+ * const percentage = l2SquaredToPercentage(1.2);
+ * console.log(`Match: ${percentage}%`); // Extrapolates onto a 0-100 curve
+ */
+function l2SquaredToPercentage(l2Squared) {
+    // For normalized vectors L2² ∈ [0, 4]; 0 = identical, 4 = maximally different.
+    // ((2 - d) / 2) × 100 maps that range linearly to 100%…0%.
+    const matchPercentage = ((2.0 - l2Squared) / 2.0) * 100;
+    return Math.max(0, Math.min(100, matchPercentage)); // Clamp to 0-100
+}
+/**
+ * Computes a face match result from two embeddings for informational use.
+ *
+ * **Important:** This function no longer returns a boolean pass/fail flag.
+ * Pass/fail is determined by the ZK engine (which explicitly owns the threshold), not by this function.
+ *
+ * @param {FloatVector} referenceEmbedding - Reference face embedding.
+ * @param {FloatVector} liveEmbedding - Live face embedding.
+ * @returns {FaceMatchResult} Match result containing raw distance and percentage.
+ *
+ * @example
+ * const result = computeFaceMatchResult(refEmbed, liveEmbed);
+ * console.log(`Match confidence: ${result.matchPercentage}%`);
+ */
+function computeFaceMatchResult(referenceEmbedding, liveEmbedding) {
+    const distance = l2SquaredDistance(referenceEmbedding, liveEmbedding);
+    const matchPercentage = l2SquaredToPercentage(distance);
+    return {
+        distance,
+        matchPercentage,
+    };
+}

package/dist/core/types.d.ts

@@ -0,0 +1,379 @@
+/**
+ * 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 Type Definitions (Local-Only)
+ *
+ * This file defines the TypeScript data models for the local-only Face+ZK SDK.
+ * It is the source of truth for the SDK's API surface.
+ *
+ * Based on: docs/sdk-plan/face-zk-sdk-types-and-entrypoints.md
+ */
+/** Face embedding vector (e.g., 512-dimensional) */
+export type FloatVector = number[];
+/** Head pose estimate (angles in degrees) */
+export type Pose = {
+    yaw: number;
+    pitch: number;
+    roll: number;
+};
+/** Supported liveness check types */
+export type LivenessCheckId = "motion" | "blink" | "pose_variation" | "depth_or_3d" | "spoof_texture" | "other";
+/** Opaque identifier for a reference template */
+export type ReferenceId = string;
+/**
+ * Reference template created during enrollment.
+ * Contains the face embedding and pose from the reference image.
+ */
+export interface ReferenceTemplate {
+    /** SDK-generated opaque ID; caller may also store their own mapping (userId → referenceId). */
+    referenceId: ReferenceId;
+    /** Face embedding derived from the reference image. */
+    embedding: FloatVector;
+    /** Head pose estimate at enrollment time. Required. */
+    pose: Pose;
+    /**
+     * Caller-defined metadata, stored in memory or via the storage adapter.
+     * Must NOT include raw PII or image bytes by default.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * When the caller wants to provide their own reference (e.g., embeddings computed elsewhere),
+ * they can supply this shape instead of letting the SDK compute from an image URI.
+ */
+export interface ReferenceTemplateInput {
+    referenceId?: ReferenceId;
+    embedding: FloatVector;
+    pose: Pose;
+    metadata?: Record<string, unknown>;
+}
+/** Metadata about a captured live image */
+export interface LiveImageInfo {
+    /** URI of the final chosen live frame (e.g., camera capture). */
+    imageUri?: string;
+    /**
+     * Optional base64-encoded image string for callers that need it.
+     * SDK should not persist this unless a storage adapter is explicitly configured to do so.
+     */
+    imageBase64?: string;
+    /** Approximate size in kilobytes (if base64 is available). */
+    sizeKb?: number;
+    /** Optional quality score (0–1, higher = better). */
+    qualityScore?: number;
+}
+/** Result of live capture including embedding and pose */
+export interface LiveCaptureResult {
+    /** Embedding computed from the final live frame. */
+    embedding: FloatVector;
+    /** Pose estimate at capture time. */
+    pose?: Pose;
+    /** Image metadata for the captured frame. */
+    image?: LiveImageInfo;
+    /** Detected gender if model is configured */
+    gender?: "Male" | "Female" | "Unknown";
+    /** Estimated age if model is configured */
+    age?: number;
+    /**
+     * Raw MediaPipe FaceMesh landmarks at capture time (468 points + iris if refineLandmarks=true).
+     * Each point is normalized to [0,1] relative to the video frame.
+     * Useful for research and model improvement — not required for SDK operation.
+     */
+    faceMeshLandmarks?: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+}
+/** Result of a single liveness check */
+export interface LivenessCheckResult {
+    id: LivenessCheckId;
+    passed: boolean;
+    score?: number;
+    reason?: string;
+}
+/** Overall liveness result */
+export interface LivenessResult {
+    /** Overall outcome across all checks. */
+    passed: boolean;
+    /** Optional aggregate score. */
+    score?: number;
+    /** Per-check details. */
+    checks?: LivenessCheckResult[];
+}
+/** Face matching result comparing reference and live embeddings */
+export interface FaceMatchResult {
+    /** Raw L2-squared distance between reference and live embeddings. */
+    distance: number;
+    /** Derived match percentage (0–100, higher = better match). */
+    matchPercentage: number;
+}
+/** Zero-knowledge proof summary */
+export interface ZkProofSummary {
+    /** Full proof string as returned by the ZK engine. */
+    proof: string;
+    /** Public inputs passed to the verifier. */
+    publicInputs: string[];
+    /** Hash of the proof, suitable for commitments or indexing. */
+    hash: string;
+    /** Result of local verification. */
+    verified: boolean;
+    /** Optional metadata. */
+    timestamp?: number;
+    sizeBytes?: number;
+}
+/** SDK error codes */
+export type SdkErrorCode = "NO_FACE" | "MULTIPLE_FACES" | "LOW_MATCH" | "SYSTEM_ERROR" | "ZK_ERROR" | "NO_REFERENCE" | "LIVENESS_FAILED" | "CANCELLED";
+/** Structured error information */
+export interface SdkError {
+    code: SdkErrorCode;
+    message: string;
+    /**
+     * Rich structured details for debugging:
+     * - internal stage name (e.g., "embedding", "match", "zk_proof")
+     * - raw distances/scores
+     * - underlying exception message (sanitized)
+     */
+    details?: Record<string, unknown>;
+}
+/** Type guard to check if an unknown value is an SdkError */
+export declare function isSdkError(error: unknown): error is SdkError;
+/** Complete verification outcome */
+export interface VerificationOutcome {
+    /** Overall result: true only if all enabled checks (match, liveness, ZK if required) pass. */
+    success: boolean;
+    /**
+     * Primary score for UX surfaces.
+     * Contract: matchPercentage in the range 0–100 (higher is better).
+     */
+    score: number;
+    /** Detailed face match metrics. */
+    match?: FaceMatchResult;
+    /** Liveness/anti-spoof result (if enabled). */
+    liveness?: LivenessResult;
+    /** Reference and live capture details (embeddings + pose, no reference image bytes). */
+    reference?: Pick<ReferenceTemplate, "referenceId" | "embedding" | "pose" | "metadata">;
+    live?: LiveCaptureResult;
+    /** Optional ZK proof summary (when proof is generated). */
+    zkProof?: ZkProofSummary;
+    /** Present when the flow ends in a failure state or partial success. */
+    error?: SdkError;
+}
+/** Liveness configuration */
+export interface LivenessConfig {
+    /** Enable or disable liveness/anti-spoof checks in this flow. */
+    enabled: boolean;
+}
+/** Zero-knowledge proof engine interface */
+export interface ZkProofEngine {
+    generateProof(referenceEmbedding: FloatVector, liveEmbedding: FloatVector, nonce: number): Promise<{
+        proof: string;
+        publicInputs: string[];
+    }>;
+    verifyProof(proof: string, publicInputs: string[]): Promise<boolean>;
+    getProofHash(proof: string): Promise<string>;
+}
+/** ZK configuration */
+export interface ZkConfig {
+    /** Whether ZK is allowed in this environment (SDK-level capability). */
+    enabled: boolean;
+    /**
+     * If true, verification is only considered a full SUCCESS when a ZK proof
+     * is successfully generated and verified.
+     */
+    requiredForSuccess?: boolean;
+    /** Concrete engine implementation (e.g., RN WebView/Plonky3 bridge). */
+    engine: ZkProofEngine;
+}
+/** Reference storage record */
+export interface ReferenceStorageRecord {
+    template: ReferenceTemplate;
+}
+/** Proof storage record */
+export interface ProofStorageRecord {
+    referenceId: ReferenceId;
+    liveEmbeddingHash?: string;
+    zkProof: ZkProofSummary;
+}
+/** Storage adapter interface for persisting references and proofs */
+export interface StorageAdapter {
+    saveReference(template: ReferenceTemplate): Promise<ReferenceId>;
+    loadReference(referenceId: ReferenceId): Promise<ReferenceTemplate | null>;
+    deleteReference(referenceId: ReferenceId): Promise<void>;
+    saveProof?(record: ProofStorageRecord): Promise<string>;
+    loadProof?(proofId: string): Promise<ProofStorageRecord | null>;
+}
+/**
+ * Logging/telemetry remains local; callers decide what to do with it.
+ */
+export interface SdkLogger {
+    onLog?(event: {
+        level: "debug" | "info" | "warn" | "error";
+        message: string;
+        context?: Record<string, any>;
+    }): void;
+}
+/** Global runtime configuration — controls liveness, ZK, storage, and logging for all SDK operations. */
+export interface FaceZkRuntimeConfig extends SdkLogger {
+    liveness?: LivenessConfig;
+    zk?: ZkConfig;
+    storage?: StorageAdapter;
+}
+/**
+ * Per-call override; shallow-partial of FaceZkRuntimeConfig.
+ */
+export interface VerificationOptions {
+    liveness?: Partial<LivenessConfig>;
+    zk?: Partial<Pick<ZkConfig, "requiredForSuccess">>;
+    /**
+     * Optional: include additional image data in LiveCaptureResult.
+     * Only computed when explicitly requested (base64 is expensive).
+     */
+    includeImageData?: {
+        base64?: boolean;
+        sizeKb?: boolean;
+        /** Optional image quality score (0–1, higher = better). */
+        qualityScore?: number;
+    };
+}
+/** Options for enrollment (reference creation) */
+export interface EnrollmentOptions {
+    /** Optional metadata for the reference template (e.g., userId, tag). */
+    metadata?: Record<string, unknown>;
+    /** If true, SDK will save via storage adapter and return the persisted template. */
+    persist?: boolean;
+}
+/** Options for ZK-only proof generation */
+export interface ZkProofOptions {
+    nonce?: number;
+}
+/** Verification flow stages for UI state management */
+export type VerificationStage = "IDLE" | "REFERENCE_LOADING" | "LIVENESS" | "CAPTURING" | "EMBEDDING" | "MATCHING" | "ZK_PROOF" | "DONE";
+/**
+ * Color theme for SDK UI components.
+ * All colors are CSS/React Native color strings (hex, rgb, rgba, named).
+ */
+export interface FaceZkTheme {
+    colors: {
+        /** Primary accent color — buttons, spinners, success icons. Default: #4CAF50 */
+        primary: string;
+        /** Screen / modal background. Default: #000000 */
+        background: string;
+        /** Overlay and surface background (e.g., cancel button). Default: rgba(255,255,255,0.1) */
+        surface: string;
+        /** Primary text color. Default: #ffffff */
+        text: string;
+        /** Secondary / muted text color. Default: #aaaaaa */
+        textMuted: string;
+        /** Error state color — error icons, error titles. Default: #F44336 */
+        error: string;
+    };
+    /** Border radius for buttons and cards. Default: 8 */
+    borderRadius?: number;
+}
+/**
+ * Copy overrides for all user-facing strings in SDK flows.
+ * Any string left undefined falls back to the SDK default.
+ */
+export interface FaceZkStrings {
+    loadingInitializing?: string;
+    loadingModels?: string;
+    loadingCapturing?: string;
+    loadingProcessing?: string;
+    loadingEmbedding?: string;
+    loadingMatching?: string;
+    loadingZkProof?: string;
+    verificationSuccessTitle?: string;
+    verificationSuccessSubtitle?: string;
+    enrollmentSuccessTitle?: string;
+    enrollmentSuccessSubtitle?: string;
+    verificationErrorTitle?: string;
+    enrollmentErrorTitle?: string;
+    cancelButton?: string;
+    retryButton?: string;
+}
+/**
+ * UI configuration for customizing SDK React Native flow components.
+ *
+ * Three layers of customization:
+ *
+ * 1. `theme`   — change colors and border radius (brand colors, dark/light mode)
+ * 2. `strings` — override any piece of copy (localization, custom messaging)
+ * 3. render props — completely replace a state's UI with your own React component
+ *
+ * @example — brand colors only
+ * ```tsx
+ * <FaceZkVerificationFlow
+ *   uiConfig={{
+ *     theme: { colors: { primary: '#6200EE', background: '#1a1a2e' } },
+ *   }}
+ * />
+ * ```
+ *
+ * @example — copy overrides (localization)
+ * ```tsx
+ * <FaceZkVerificationFlow
+ *   uiConfig={{
+ *     strings: {
+ *       loadingModels: 'Cargando modelos...',
+ *       verificationSuccessTitle: '¡Verificado!',
+ *       cancelButton: 'Cancelar',
+ *     },
+ *   }}
+ * />
+ * ```
+ *
+ * @example — fully custom success screen
+ * ```tsx
+ * <FaceZkVerificationFlow
+ *   uiConfig={{
+ *     renderSuccess: (outcome) => (
+ *       <MyBrandedSuccessScreen score={outcome.score} zkHash={outcome.zkProof?.hash} />
+ *     ),
+ *   }}
+ * />
+ * ```
+ */
+export interface UiConfig {
+    /** Brand color overrides. Only specify what you want to change. */
+    theme?: Partial<FaceZkTheme> & {
+        colors?: Partial<FaceZkTheme["colors"]>;
+    };
+    /** Copy/string overrides. Only specify what you want to change. */
+    strings?: Partial<FaceZkStrings>;
+    /**
+     * Fully replace the loading / processing state UI.
+     * Receives the current stage label and resolved message string.
+     */
+    renderLoading?: (stage: VerificationStage | string, message: string) => React.ReactNode;
+    /**
+     * Fully replace the verification success state UI.
+     * Receives the completed VerificationOutcome.
+     */
+    renderSuccess?: (outcome: VerificationOutcome) => React.ReactNode;
+    /**
+     * Fully replace the error state UI.
+     * Receives the SdkError and retry/cancel callbacks.
+     */
+    renderError?: (error: SdkError, actions: {
+        onRetry: () => void;
+        onCancel: () => void;
+    }) => React.ReactNode;
+    /**
+     * Custom overlay rendered on top of the camera/liveness view.
+     * Receives live WebView state (pose, instructions, etc).
+     */
+    renderOverlay?: (state: any) => React.ReactNode;
+}

package/dist/core/types.js

@@ -0,0 +1,37 @@
+"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.isSdkError = isSdkError;
+const SDK_ERROR_CODES = new Set([
+    "NO_FACE",
+    "MULTIPLE_FACES",
+    "LOW_MATCH",
+    "SYSTEM_ERROR",
+    "ZK_ERROR",
+    "NO_REFERENCE",
+    "LIVENESS_FAILED",
+    "CANCELLED",
+]);
+/** Type guard to check if an unknown value is an SdkError */
+function isSdkError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        "message" in error &&
+        typeof error.message === "string" &&
+        SDK_ERROR_CODES.has(error.code));
+}