@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

package/README.md

@@ -1,5 +1,7 @@
 # Face+ZK SDK
 
+[![npm version](https://img.shields.io/badge/npm-0.3.5-blue)](https://www.npmjs.com/package/@jupitermetalabs/face-zk-sdk)
+
 A standalone React Native and Web SDK for face verification and Zero-Knowledge (ZK) proofs.
 
 ## Features
@@ -19,7 +21,6 @@ To keep documentation clean, each major module has its own dedicated documentati
 - `storage/`: Built-in storage adapters for persisting enrolled references and proofs.
 - `assets/`: ONNX models and WebView-based liveness/ZK scripts.
 - `example/`: A complete Expo app demonstrating how to integrate the SDK.
-- `example/`: A complete Expo app demonstrating how to integrate the SDK.
 
 ## Getting Started
 
@@ -179,5 +180,49 @@ Verify a live user against a saved reference.
 />
 ```
 
+---
+
+### 6. Gender & Age Estimation (Optional)
+
+Enable by passing the `ageGender` model in `initializeSdk`. Results are returned automatically alongside every verification and enrollment.
+
+**Enable the model:**
+```typescript
+await initializeSdk({
+  models: {
+    detection:   { module: require('./assets/models/det_500m.onnx') },
+    recognition: { module: require('./assets/models/w600k_mbf.onnx') },
+    antispoof:   { module: require('./assets/models/antispoof.onnx') },
+    ageGender:   { module: require('./assets/models/genderage.onnx') }, // add this
+  },
+});
+```
+
+**Read results from verification:**
+```typescript
+<FaceZkVerificationFlow
+  onComplete={(outcome) => {
+    // outcome.liveCapture is populated after a successful live capture
+    console.log(outcome.liveCapture?.gender); // "Male" | "Female" | "Unknown"
+    console.log(outcome.liveCapture?.age);    // e.g. 28
+  }}
+/>
+```
+
+**Read results from enrollment:**
+```typescript
+<ReferenceEnrollmentFlow
+  onComplete={(template) => {
+    // gender/age stored in template metadata under sdkResponse
+    console.log(template.metadata?.sdkResponse?.gender);
+    console.log(template.metadata?.sdkResponse?.age);
+  }}
+/>
+```
+
+If `ageGender` is not configured, `gender` will be `undefined` and `age` will be `undefined` — the rest of the SDK functions normally.
+
+---
+
 ## Contributing
 Please see the individual `README.md` files in each subdirectory for more technical details on the architecture.

package/assets/face-guidance/pose-guidance.js.txt

@@ -20,6 +20,7 @@ let isGuidanceActive = false;
 let stableStartTime = 0;
 let currentStream = null;
 let lastPose = null;
+let lastLandmarks = null;
 let guidanceStatus = { text: "", arrowLeft: false, arrowRight: false, isMatch: false };
 let isRenderLoopActive = false;
 
@@ -60,13 +61,14 @@ function onResults(results) {
 
     if (results.multiFaceLandmarks && results.multiFaceLandmarks.length > 0) {
         const landmarks = results.multiFaceLandmarks[0];
+        lastLandmarks = landmarks;
         const pose = calculatePose(landmarks);
         const gaze = calculateGaze(landmarks);
         const faceWidth = Math.hypot(
             landmarks[454].x - landmarks[234].x,
             landmarks[454].y - landmarks[234].y
         );
-        
+
         lastPose = { ...pose, gaze, faceWidth };
         
         // --- LIVENESS CHECK ---
@@ -327,7 +329,7 @@ function captureSuccess() {
     
     // Capture Image
     const dataUrl = canvasElement.toDataURL('image/jpeg', 0.9);
-    sendMessage('success', { image: dataUrl, pose: TARGET_POSE });
+    sendMessage('success', { image: dataUrl, pose: lastPose || TARGET_POSE, faceMeshLandmarks: lastLandmarks || undefined });
 }
 
 

package/assets/liveness/liveness.js.txt

@@ -80,6 +80,7 @@ let lastValidationTime = 0;
 
 let captureStableFrames = 0; // For near-field stability check
 let readyToCapture = false;
+let lastLandmarks = null;
 
 const SPOOF_THRESHOLD_FINAL = 0.65; // Per-sample fail threshold (only flag high-confidence spoofs)
 const SPOOF_EMA_FAIL_THRESHOLD = 0.60; // EMA-based final decision threshold
@@ -434,6 +435,7 @@ function onResults(results) {
   }
 
   const landmarks = results.multiFaceLandmarks[0];
+  lastLandmarks = landmarks;
 
   // Calculate face width for distance checks
   const faceWidth = Math.hypot(
@@ -788,6 +790,7 @@ function captureEvidence() {
         image: dataUrl,
         metadata: {
           spoofScore: spoofVerdict.averageScore,
+          faceMeshLandmarks: lastLandmarks || undefined,
         },
       }),
     );

package/dist/FaceZkSdk.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 – Main SDK Class
+ *
+ * `FaceZkSdk` is the single entry point for initializing the SDK.
+ * Call `FaceZkSdk.init(config)` once at app startup before using any SDK features.
+ *
+ * @example – models bundled in the app (user copies assets via `npx face-zk setup --bundle`)
+ * ```ts
+ * import { FaceZkSdk } from '@jupitermetalabs/face-zk-sdk';
+ *
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { module: require('./assets/face-zk/det_500m.onnx') },
+ *     recognition: { module: require('./assets/face-zk/w600k_mbf.onnx') },
+ *   },
+ * });
+ * ```
+ *
+ * @example – models downloaded from CDN on first use
+ * ```ts
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { url: 'https://cdn.example.com/face-zk/det_500m.onnx' },
+ *     recognition: { url: 'https://cdn.example.com/face-zk/w600k_mbf.onnx' },
+ *   },
+ * });
+ * ```
+ */
+import type { FaceZkConfig } from "./config/types";
+type SdkInitState = "uninitialized" | "initializing" | "ready" | "error";
+export declare class FaceZkSdk {
+    /**
+     * Initialize the SDK with model sources and optional feature flags.
+     * Must be called once before using any SDK features (enrollment, verification, ZK proofs).
+     *
+     * Safe to await at app startup (in App.tsx, before rendering the root navigator).
+     */
+    static init(config: FaceZkConfig): Promise<void>;
+    /**
+     * Returns the resolved SDK config.
+     * Throws if `init()` hasn't been called yet.
+     */
+    static getConfig(): FaceZkConfig;
+    /** Returns true if `init()` has completed successfully. */
+    static isInitialized(): boolean;
+    /** Returns the current init state: 'uninitialized' | 'initializing' | 'ready' | 'error' */
+    static getState(): SdkInitState;
+    /** Returns the error from the last failed `init()` call, if any. */
+    static getInitError(): Error | null;
+    /**
+     * Reset SDK state. Useful for tests or re-initialization flows.
+     */
+    static reset(): void;
+}
+export {};

package/dist/FaceZkSdk.js

@@ -0,0 +1,136 @@
+"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 – Main SDK Class
+ *
+ * `FaceZkSdk` is the single entry point for initializing the SDK.
+ * Call `FaceZkSdk.init(config)` once at app startup before using any SDK features.
+ *
+ * @example – models bundled in the app (user copies assets via `npx face-zk setup --bundle`)
+ * ```ts
+ * import { FaceZkSdk } from '@jupitermetalabs/face-zk-sdk';
+ *
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { module: require('./assets/face-zk/det_500m.onnx') },
+ *     recognition: { module: require('./assets/face-zk/w600k_mbf.onnx') },
+ *   },
+ * });
+ * ```
+ *
+ * @example – models downloaded from CDN on first use
+ * ```ts
+ * await FaceZkSdk.init({
+ *   models: {
+ *     detection:   { url: 'https://cdn.example.com/face-zk/det_500m.onnx' },
+ *     recognition: { url: 'https://cdn.example.com/face-zk/w600k_mbf.onnx' },
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FaceZkSdk = void 0;
+// Module-level state (singleton)
+let _state = "uninitialized";
+let _config = null;
+let _initError = null;
+class FaceZkSdk {
+    /**
+     * Initialize the SDK with model sources and optional feature flags.
+     * Must be called once before using any SDK features (enrollment, verification, ZK proofs).
+     *
+     * Safe to await at app startup (in App.tsx, before rendering the root navigator).
+     */
+    static async init(config) {
+        if (_state === "initializing") {
+            throw new Error("[FaceZkSdk] Already initializing. Avoid calling init() concurrently.");
+        }
+        if (_state === "ready") {
+            throw new Error("[FaceZkSdk] Already initialized. Call FaceZkSdk.reset() before re-initializing.");
+        }
+        _state = "initializing";
+        _initError = null;
+        try {
+            validateConfig(config);
+            _config = config;
+            _state = "ready";
+        }
+        catch (err) {
+            _state = "error";
+            _initError = err instanceof Error ? err : new Error(String(err));
+            throw _initError;
+        }
+    }
+    /**
+     * Returns the resolved SDK config.
+     * Throws if `init()` hasn't been called yet.
+     */
+    static getConfig() {
+        if (_state !== "ready" || !_config) {
+            throw new Error("[FaceZkSdk] Not initialized. Call FaceZkSdk.init(config) before using SDK features.");
+        }
+        return _config;
+    }
+    /** Returns true if `init()` has completed successfully. */
+    static isInitialized() {
+        return _state === "ready";
+    }
+    /** Returns the current init state: 'uninitialized' | 'initializing' | 'ready' | 'error' */
+    static getState() {
+        return _state;
+    }
+    /** Returns the error from the last failed `init()` call, if any. */
+    static getInitError() {
+        return _initError;
+    }
+    /**
+     * Reset SDK state. Useful for tests or re-initialization flows.
+     */
+    static reset() {
+        _state = "uninitialized";
+        _config = null;
+        _initError = null;
+    }
+}
+exports.FaceZkSdk = FaceZkSdk;
+// ============================================================================
+// Internal validation
+// ============================================================================
+function validateConfig(config) {
+    if (!config || typeof config !== "object") {
+        throw new Error("[FaceZkSdk] config must be an object.");
+    }
+    if (!config.models || typeof config.models !== "object") {
+        throw new Error("[FaceZkSdk] config.models is required.");
+    }
+    if (!config.models.detection) {
+        throw new Error("[FaceZkSdk] config.models.detection is required. " +
+            "Provide a { module }, { url }, or { localUri }.");
+    }
+    if (!config.models.recognition) {
+        throw new Error("[FaceZkSdk] config.models.recognition is required. " +
+            "Provide a { module }, { url }, or { localUri }.");
+    }
+    // Each provided ModelSource must have at least one resolvable field
+    const modelEntries = Object.entries(config.models);
+    for (const [key, source] of modelEntries) {
+        if (!source)
+            continue;
+        if (!source.module && !source.url && !source.localUri) {
+            throw new Error(`[FaceZkSdk] config.models.${key} must have at least one of: module, url, localUri.`);
+        }
+    }
+}

package/dist/assets/face-guidance/pose-guidance.js.txt

@@ -20,6 +20,7 @@ let isGuidanceActive = false;
 let stableStartTime = 0;
 let currentStream = null;
 let lastPose = null;
+let lastLandmarks = null;
 let guidanceStatus = { text: "", arrowLeft: false, arrowRight: false, isMatch: false };
 let isRenderLoopActive = false;
 
@@ -60,13 +61,14 @@ function onResults(results) {
 
     if (results.multiFaceLandmarks && results.multiFaceLandmarks.length > 0) {
         const landmarks = results.multiFaceLandmarks[0];
+        lastLandmarks = landmarks;
         const pose = calculatePose(landmarks);
         const gaze = calculateGaze(landmarks);
         const faceWidth = Math.hypot(
             landmarks[454].x - landmarks[234].x,
             landmarks[454].y - landmarks[234].y
         );
-        
+
         lastPose = { ...pose, gaze, faceWidth };
         
         // --- LIVENESS CHECK ---
@@ -327,7 +329,7 @@ function captureSuccess() {
     
     // Capture Image
     const dataUrl = canvasElement.toDataURL('image/jpeg', 0.9);
-    sendMessage('success', { image: dataUrl, pose: TARGET_POSE });
+    sendMessage('success', { image: dataUrl, pose: lastPose || TARGET_POSE, faceMeshLandmarks: lastLandmarks || undefined });
 }
 
 

package/dist/assets/liveness/liveness.js.txt

@@ -80,6 +80,7 @@ let lastValidationTime = 0;
 
 let captureStableFrames = 0; // For near-field stability check
 let readyToCapture = false;
+let lastLandmarks = null;
 
 const SPOOF_THRESHOLD_FINAL = 0.65; // Per-sample fail threshold (only flag high-confidence spoofs)
 const SPOOF_EMA_FAIL_THRESHOLD = 0.60; // EMA-based final decision threshold
@@ -434,6 +435,7 @@ function onResults(results) {
   }
 
   const landmarks = results.multiFaceLandmarks[0];
+  lastLandmarks = landmarks;
 
   // Calculate face width for distance checks
   const faceWidth = Math.hypot(
@@ -788,6 +790,7 @@ function captureEvidence() {
         image: dataUrl,
         metadata: {
           spoofScore: spoofVerdict.averageScore,
+          faceMeshLandmarks: lastLandmarks || undefined,
         },
       }),
     );