@verifiedonchain-protocol/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-# VerifiedOnchain SDK (`vo-sdk`)
+# VerifiedOnchain SDK (`@verifiedonchain-protocol/sdk`)
 
 A lightweight, framework-agnostic React SDK for integrating the **Proof of Humanity** face verification, social connections, and wallet abstractions into your dApp.
 
@@ -7,7 +7,7 @@ This SDK captures biometric telemetry, performs local sequential liveness detect
 ## Installation
 
 ```bash
-npm install vo-sdk
+npm install @verifiedonchain-protocol/sdk
 ```
 
 *(Note: If you are using React 18, you might need to install peer dependencies like `framer-motion` for animations, `@solana/wallet-adapter-react` for Solana support, and `wagmi` + `viem` for EVM support if you haven't already).*
@@ -20,15 +20,15 @@ The SDK requires two things to function correctly:
 
 ### 1. Hosting the ML Models
 
-Download the standard Human.js models (or copy them from the SDK's `node_modules/vo-sdk/models` if available) and place them in your web root under `/models`. The required models typically include `blazeface.json`, `faceres.json`, etc.
+Download the standard Human.js models (or copy them from the SDK's `node_modules/@verifiedonchain-protocol/sdk/models` if available) and place them in your web root under `/models`. The required models typically include `blazeface.json`, `faceres.json`, etc.
 
 ### 2. Basic Usage
 
 The easiest way to integrate the SDK is using the `VerifiedOnchainFlow` component, which provides a complete turn-key UI for wallet connection, social linking, and biometric scanning.
 
 ```tsx
-import { VerifiedOnchainFlow } from 'vo-sdk';
-import 'vo-sdk/dist/index.css'; // Optional if you are compiling Tailwind yourself
+import { VerifiedOnchainFlow } from '@verifiedonchain-protocol/sdk';
+import '@verifiedonchain-protocol/sdk/dist/index.css'; // Optional if you are compiling Tailwind yourself
 
 export default function VerificationPage() {
   const handleSuccess = (data) => {
@@ -79,7 +79,7 @@ If you need complete control over the user experience, styling, or the order of
 A plug-and-play UI for wallet connections across both EVM and Solana ecosystems.
 
 ```tsx
-import { WalletSelection } from 'vo-sdk';
+import { WalletSelection } from '@verifiedonchain-protocol/sdk';
 
 <WalletSelection 
   requiredWallets={['phantom', 'metamask', 'backpack']}
@@ -93,7 +93,7 @@ import { WalletSelection } from 'vo-sdk';
 Handles OAuth flows and API integrations for social verification.
 
 ```tsx
-import { SocialConnection } from 'vo-sdk';
+import { SocialConnection } from '@verifiedonchain-protocol/sdk';
 
 <SocialConnection 
   requiredSocials={['x', 'farcaster']}
@@ -107,7 +107,7 @@ import { SocialConnection } from 'vo-sdk';
 The core biometric scanners. `ProofOfHumanity` provides a structured UI wrapper around the raw `FaceZK` scanner.
 
 ```tsx
-import { ProofOfHumanity } from 'vo-sdk';
+import { ProofOfHumanity } from '@verifiedonchain-protocol/sdk';
 
 <ProofOfHumanity 
   onNextStep={() => console.log("User clicked continue")}
@@ -122,8 +122,8 @@ import { ProofOfHumanity } from 'vo-sdk';
 
 If you are using the **Headless / Modular Approach**, you are responsible for submitting the biometric payload to the backend using the `VerifiedRelayerClient`.
 
-```tsx
-import { VerifiedRelayerClient } from 'vo-sdk';
+```typescript
+import { VerifiedRelayerClient } from '@verifiedonchain-protocol/sdk';
 
 // Initialize the client
 const client = new VerifiedRelayerClient({ 

package/dist/index.d.ts

@@ -259,6 +259,8 @@ declare function checkFaceOcclusionRaw(landmarks: NormalizedLandmark[], ctx: Can
 /** @deprecated Use tracker + checkFaceOcclusionRaw */
 declare function checkFaceOcclusion(landmarks: NormalizedLandmark[], ctx: CanvasRenderingContext2D, width: number, height: number): FaceOcclusionResult;
 
+declare const EMBEDDING_DIMENSIONS = 1024;
+declare const SIGNATURE_BITS = 256;
 /**
  * Generates deterministic random hyperplanes
  * These chop the high-dimensional space into 256 regions
@@ -560,4 +562,4 @@ interface SocialConnectionProps {
 }
 declare const SocialConnection: React.FC<SocialConnectionProps>;
 
-export { type AleoCircuitInputs, type AleoCircuitInputsComplete, type AleoEmbeddingChunks, type AleoSimHashInputs, BACKEND_PRIORITY, type BiometricSimHashPayload, CAPTURE_QUALITY, type CaptureQualityResult, type ChainType, type DataQuality, EmbeddingQuantizer, type FaceBox, type FaceOcclusionResult, FaceOcclusionTracker, FaceZKInner as FaceZK, type FlashColor, GlassesDetector, HUMAN_CONFIG, type LivenessData, LivenessEngine, type LivenessResult, MaskDetector, type NormalizedLandmark, type OcclusionCheckOptions, ProofOfHumanity, type RawFacialData, type RelayerConfig, type RelayerResponse, SocialConnection, VERIFICATION_CONSTANTS, type VerificationPayload, type VerificationResult, type VerifiedIdentityData, VerifiedOnchainFlow, type VerifiedOnchainFlowProps, VerifiedRelayerClient, type VisionModels, WalletSelection, averageEmbeddings, calculateHammingDistance, checkFaceOcclusion, checkFaceOcclusionRaw, computeSimHash, createCalibratedQuantizer, createLivenessData, evaluateCaptureQuality, extractRawFacialData, generateBiometricSimHash, generateHyperplanes, generateRandomSalt, getFaceBox, getFaceLuminance, getHyperplanes, getRegionLuminance, hammingDistance, normalizeEmbedding, processFacialDataForAleo, similarityFromDistance, useCameraStream, useVisionModels, validateDataQuality };
+export { type AleoCircuitInputs, type AleoCircuitInputsComplete, type AleoEmbeddingChunks, type AleoSimHashInputs, BACKEND_PRIORITY, type BiometricSimHashPayload, CAPTURE_QUALITY, type CaptureQualityResult, type ChainType, type DataQuality, EMBEDDING_DIMENSIONS, EmbeddingQuantizer, type FaceBox, type FaceOcclusionResult, FaceOcclusionTracker, FaceZKInner as FaceZK, type FlashColor, GlassesDetector, HUMAN_CONFIG, type LivenessData, LivenessEngine, type LivenessResult, MaskDetector, type NormalizedLandmark, type OcclusionCheckOptions, ProofOfHumanity, type RawFacialData, type RelayerConfig, type RelayerResponse, SIGNATURE_BITS, SocialConnection, VERIFICATION_CONSTANTS, type VerificationPayload, type VerificationResult, type VerifiedIdentityData, VerifiedOnchainFlow, type VerifiedOnchainFlowProps, VerifiedRelayerClient, type VisionModels, WalletSelection, averageEmbeddings, calculateHammingDistance, checkFaceOcclusion, checkFaceOcclusionRaw, computeSimHash, createCalibratedQuantizer, createLivenessData, evaluateCaptureQuality, extractRawFacialData, generateBiometricSimHash, generateHyperplanes, generateRandomSalt, getFaceBox, getFaceLuminance, getHyperplanes, getRegionLuminance, hammingDistance, normalizeEmbedding, processFacialDataForAleo, similarityFromDistance, useCameraStream, useVisionModels, validateDataQuality };

package/dist/index.js

@@ -1,5 +1,7 @@
 // src/core/biometrics/simHash.ts
 var SEED_PREFIX = "HumanityGen_SimHash_Hyperplane_";
+var EMBEDDING_DIMENSIONS = 1024;
+var SIGNATURE_BITS = 256;
 function generateHyperplanes(dimensions, count) {
   const hyperplanes = [];
   for (let i = 0; i < count; i++) {
@@ -34,12 +36,24 @@ function simpleHash(str) {
 }
 function computeSimHash(embedding, hyperplanes) {
   if (embedding.length === 0) return "";
-  const dims = Math.min(embedding.length, hyperplanes[0].length);
+  const hyperplaneDim = hyperplanes[0].length;
+  let workingEmbedding = embedding;
+  if (embedding.length !== hyperplaneDim) {
+    console.warn(
+      `\u26A0\uFE0F SimHash dimension mismatch: embedding has ${embedding.length} dims, hyperplanes expect ${hyperplaneDim}. ` + (embedding.length < hyperplaneDim ? `Zero-padding embedding with ${hyperplaneDim - embedding.length} extra dims.` : `Truncating embedding to ${hyperplaneDim} dims.`)
+    );
+    if (embedding.length < hyperplaneDim) {
+      workingEmbedding = [...embedding, ...new Array(hyperplaneDim - embedding.length).fill(0)];
+    } else {
+      workingEmbedding = embedding.slice(0, hyperplaneDim);
+    }
+  }
+  const dims = hyperplaneDim;
   let signatureBytes = new Uint8Array(hyperplanes.length / 8);
   for (let i = 0; i < hyperplanes.length; i++) {
     let dotProduct = 0;
     for (let j = 0; j < dims; j++) {
-      dotProduct += embedding[j] * hyperplanes[i][j];
+      dotProduct += workingEmbedding[j] * hyperplanes[i][j];
     }
     if (dotProduct > 0) {
       const byteIndex = Math.floor(i / 8);
@@ -72,7 +86,7 @@ function hammingDistance(hex1, hex2) {
   return distance;
 }
 var cachedHyperplanes = null;
-function getHyperplanes(dimensions = 1024, count = 256) {
+function getHyperplanes(dimensions = EMBEDDING_DIMENSIONS, count = SIGNATURE_BITS) {
   if (!cachedHyperplanes || cachedHyperplanes[0].length !== dimensions || cachedHyperplanes.length !== count) {
     console.time("Generating Hyperplanes");
     cachedHyperplanes = generateHyperplanes(dimensions, count);
@@ -110,7 +124,7 @@ function averageEmbeddings(embeddings) {
     return { index, distance: Math.sqrt(sumSq) };
   });
   distances.sort((a, b) => a.distance - b.distance);
-  const keepCount = Math.max(1, Math.floor(count * 0.7));
+  const keepCount = Math.max(1, Math.floor(count * 0.85));
   const bestIndices = new Set(distances.slice(0, keepCount).map((d) => d.index));
   const finalAvg = new Array(dim).fill(0);
   for (let i = 0; i < count; i++) {
@@ -123,7 +137,7 @@ function averageEmbeddings(embeddings) {
   for (let d = 0; d < dim; d++) {
     finalAvg[d] /= keepCount;
   }
-  console.log(`Averaged ${keepCount} clean embeddings (discarded ${count - keepCount} outliers)`);
+  console.log(`Averaged ${keepCount}/${count} clean embeddings (discarded ${count - keepCount} outliers)`);
   return finalAvg;
 }
 function safeNumber(value, fallback = 0) {
@@ -507,7 +521,7 @@ function generateBiometricSimHash(face, livenessData, averagedEmbedding) {
   const rawData = extractRawFacialData(face);
   const sourceEmbedding = averagedEmbedding && averagedEmbedding.length > 0 ? averagedEmbedding : rawData.faceEmbedding;
   const normalized = normalizeEmbedding(sourceEmbedding);
-  const hyperplanes = getHyperplanes(1024, 256);
+  const hyperplanes = getHyperplanes(normalized.length || EMBEDDING_DIMENSIONS);
   const simHashHex = computeSimHash(normalized, hyperplanes);
   const hasBlink = livenessData.blinkCount >= 1;
   const hasEmotionTransition = livenessData.emotionTransitions.length > 0;
@@ -1570,10 +1584,16 @@ var FaceZKInner = ({
     }
     return dot / (Math.sqrt(normA) * Math.sqrt(normB));
   };
-  const captureMultipleEmbeddings = async (video, sampleCount = 10, intervalMs = 200) => {
+  const captureMultipleEmbeddings = async (video, sampleCount = 10, intervalMs = 200, assertFaceClear) => {
     const embeddings = [];
     console.log(`\u{1F4F8} Starting multi-frame capture: ${sampleCount} samples, ${intervalMs}ms apart`);
     for (let i = 0; i < sampleCount; i++) {
+      if (assertFaceClear) {
+        const status = assertFaceClear();
+        if (!status.aligned) {
+          throw new Error(status.message || "Face obstruction detected during capture");
+        }
+      }
       try {
         const emb = await extractFaceEmbedding(video);
         embeddings.push(emb);
@@ -1815,8 +1835,22 @@ var FaceZKInner = ({
           setLiveFeedback(null);
           const yaw = getYawDegrees(latestMatrix.current);
           if (condition(yaw)) {
-            await new Promise((r) => setTimeout(r, 300));
-            if (latestMatrix.current && condition(getYawDegrees(latestMatrix.current))) {
+            const holdUntil = Date.now() + 300;
+            let holdBroken = false;
+            while (Date.now() < holdUntil) {
+              if (!latestMatrix.current || !condition(getYawDegrees(latestMatrix.current))) {
+                holdBroken = true;
+                break;
+              }
+              const holdStatus = checkFaceAlignment();
+              if (!holdStatus.aligned) {
+                setLiveFeedback({ message: holdStatus.message, isGood: false });
+                holdBroken = true;
+                break;
+              }
+              await new Promise((r) => setTimeout(r, 50));
+            }
+            if (!holdBroken && latestMatrix.current && condition(getYawDegrees(latestMatrix.current)) && checkFaceAlignment().aligned) {
               return true;
             }
           }
@@ -1846,8 +1880,31 @@ var FaceZKInner = ({
         setCurrentStep("capturing");
         const video = videoRef.current;
         let embedding;
+        const occlusionCanvas = document.createElement("canvas");
+        const checkFaceReadyAndOcclusion = (duringFlash = false) => {
+          const alignment2 = checkFaceAlignment();
+          if (!alignment2.aligned) return alignment2;
+          if (occlusionCanvas.width !== video.videoWidth) {
+            occlusionCanvas.width = video.videoWidth;
+            occlusionCanvas.height = video.videoHeight;
+          }
+          const ctx = occlusionCanvas.getContext("2d", { willReadFrequently: true });
+          if (!ctx) return { aligned: true, message: "Perfect! Hold still." };
+          ctx.drawImage(video, 0, 0, occlusionCanvas.width, occlusionCanvas.height);
+          const occlusion = checkFaceOcclusionRaw(
+            latestLandmarks.current,
+            ctx,
+            occlusionCanvas.width,
+            occlusionCanvas.height,
+            { yawDegrees: 0, duringLivenessFlash: duringFlash }
+          );
+          if (!occlusion.ok) {
+            return { aligned: false, message: occlusion.message ?? "Please remove obstructions from your face." };
+          }
+          return { aligned: true, message: "Perfect! Hold still." };
+        };
         try {
-          embedding = await captureMultipleEmbeddings(video, 10, 200);
+          embedding = await captureMultipleEmbeddings(video, 10, 200, () => checkFaceReadyAndOcclusion(false));
         } catch (e) {
           handleFailure(e.message || "Failed to capture face data");
           return;
@@ -1857,13 +1914,16 @@ var FaceZKInner = ({
           handleFailure("Face lost during final check");
           return;
         }
-        const alignment = checkFaceAlignment();
+        const alignment = checkFaceReadyAndOcclusion(false);
         if (!alignment.aligned) {
           handleFailure(`Alignment lost: ${alignment.message}`);
           return;
         }
         setCurrentStep("light-flash");
-        const livenessResult = await livenessEngine.runLivenessSequence(bbox);
+        const livenessResult = await livenessEngine.runLivenessSequence(
+          bbox,
+          () => checkFaceReadyAndOcclusion(true)
+        );
         if (!livenessResult.passed) {
           handleFailure(livenessResult.message || "Liveness check failed");
           return;
@@ -2963,6 +3023,7 @@ var VerifiedOnchainFlow_default = VerifiedOnchainFlow;
 export {
   BACKEND_PRIORITY,
   CAPTURE_QUALITY,
+  EMBEDDING_DIMENSIONS,
   EmbeddingQuantizer,
   FaceOcclusionTracker,
   FaceZK_default as FaceZK,
@@ -2971,6 +3032,7 @@ export {
   LivenessEngine,
   MaskDetector,
   ProofOfHumanity_default as ProofOfHumanity,
+  SIGNATURE_BITS,
   SocialConnection_default as SocialConnection,
   VERIFICATION_CONSTANTS,
   VerifiedOnchainFlow_default as VerifiedOnchainFlow,