FaceZKP - ZKP-AI Proof of Humanity


Face analysis library with liveness detection, biometric template extraction, and fuzzy hashing for privacy-preserving identity verification.

Features

$3

- Real-time Face Detection - MediaPipe-based face detection and mesh extraction
- Biometric Template Generation - Structured face descriptors and metadata
- Fuzzy Biometric Hashing - Locality-sensitive hashing for similarity matching
- Liveness Detection - Multi-frame analysis to prevent spoofing attacks
- Privacy-Preserving - No server-side biometric storage, client-side only

$3

- TypeScript Support - Full type definitions and IntelliSense
- Cross-Platform - Browser and Node.js compatibility
- Performance Optimized - WebGL/WASM backend support, 30+ FPS
- Memory Efficient - Automatic tensor cleanup and garbage collection
- Error Handling - Comprehensive error recovery and validation
- Event-Driven - Real-time progress and completion events

$3

- ✅ Zero Server Storage - All processing happens locally
- ✅ Fuzzy Tolerance - Handles lighting, angle, and expression variations
- ✅ Deterministic Hashing - Same face always produces similar hashes
- ✅ Configurable Security - Adjustable similarity thresholds
- ✅ GDPR Compliant - Privacy by design architecture

Installation

``bash
npm install facezk-core
`

Quick Start

$3

`typescript
import { FaceZK, HumanIntegration } from 'facezk-core';

// Initialize FaceZK
const facezk = new FaceZK({
backend: 'webgl',
debug: false,
minConfidence: 0.5,
minLivenessScore: 0.8,
});

await facezk.initialize();

// Start verification session
const session = facezk.startSession();

// Process video frame
const video = document.getElementById('video');
const result = await facezk.processFrame(video);

if (result?.verified) {
console.log('✅ Verification successful!');
console.log('Biometric ID:', result.biometricId);
console.log('Humanity Code:', result.humanityCode);
}
`

$3

`typescript
import { generateFuzzyHash, compareFuzzyHashes, defaultFuzzyConfig } from 'facezk-core';

// Generate fuzzy hash for storage
const template = await facezk.extractTemplate(faceResult);
const fuzzyHash = generateFuzzyHash(template, defaultFuzzyConfig);

// Store locally (never on server!)
localStorage.setItem('userBiometricHash', fuzzyHash.hash);

// Later verification
const newTemplate = await facezk.extractTemplate(newFaceResult);
const newHash = generateFuzzyHash(newTemplate, defaultFuzzyConfig);

const comparison = compareFuzzyHashes(fuzzyHash, newHash, defaultFuzzyConfig);

if (comparison.match) {
console.log(✅ Same person! Similarity: ${comparison.similarity * 100}%);
} else {
console.log(❌ Different person. Similarity: ${comparison.similarity * 100}%);
}
`

$3

`typescript
const config = {
// Performance
backend: 'webgl', // 'webgl', 'wasm', 'cpu'
async: true,

// Detection
minConfidence: 0.7,
maxDetected: 1,

// Liveness
minLivenessScore: 0.85,
livenessFrames: 10,

// Fuzzy Hashing
fuzzyConfig: {
hashBits: 256,
similarityThreshold: 0.85,
normalization: 'l2',
},

// Features
face: {
detector: { enabled: true, rotation: true },
mesh: { enabled: true },
iris: { enabled: true },
emotion: { enabled: true },
ageGender: { enabled: true },
antispoof: { enabled: true },
},
};

const facezk = new FaceZK(config);
`

API Reference

$3

#### FaceZK
Main library class for face verification.

`typescript
class FaceZK {
constructor(config?: Partial);

// Initialization
initialize(): Promise;

// Session management
startSession(sessionId?: string): VerificationSession;
resetSession(): void;

// Processing
processFrame(input: Input): Promise;

// Events
addEventListener(event: VerificationEvent, listener: VerificationEventListener): void;
removeEventListener(event: VerificationEvent, listener: VerificationEventListener): void;
}
`

#### HumanIntegration
Integration with Human library for face detection.

`typescript
class HumanIntegration {
constructor(config: HumanIntegrationConfig);

// Initialization
initialize(): Promise;
dispose(): void;

// Detection
detectFaces(input: Input): Promise;

// Utilities
convertToBiometricTemplate(faceResult: FaceResult): BiometricTemplate;
drawOverlay(ctx: CanvasRenderingContext2D, faceResult: FaceResult): void;
}
`

$3

#### generateFuzzyHash(template, config?)
Generate fuzzy-tolerant biometric hash.

`typescript
function generateFuzzyHash(
template: BiometricTemplate,
config?: FuzzyHashConfig
): FuzzyHashResult;
`

#### compareFuzzyHashes(hash1, hash2, config?)
Compare two fuzzy hashes for similarity.

`typescript
function compareFuzzyHashes(
hash1: FuzzyHashResult,
hash2: FuzzyHashResult,
config?: FuzzyHashConfig
): { similarity: number; match: boolean };
`

Demo

Try the interactive demo to see FaceZK in action:

`bash
npm run demo
`

Then visit: http://localhost:3030/demo/

Features:
- Real-time face detection and analysis
- Fuzzy hash generation and comparison
- Performance monitoring
- Debug information panel

Testing

`bash


Run all tests

npm test

Run tests with coverage

npm run test:ci

Watch mode for development

npm run test:watch
`

Performance

$3

- Detection Speed: 30+ FPS on modern devices
- Memory Usage: <100MB for typical usage
- Hash Generation: ~5-10ms per template
- Hash Comparison: ~1-2ms per comparison
- Accuracy: 95%+ for same person, <5% false positives

$3

- ✅ Chrome 88+
- ✅ Firefox 85+
- ✅ Safari 14+
- ✅ Edge 88+

Security

$3

- Local Processing - No biometric data leaves the device
- Fuzzy Hashing - Prevents reverse engineering of face data
- Deterministic - Same face produces consistent hashes
- Configurable - Adjustable security thresholds

$3

1. Always use HTTPS in production
2. Validate inputs before processing
3. Keep library updated to latest version
4. Use secure storage for biometric hashes
5. Test with diverse samples for your use case

Contributing

We welcome contributions! Please see our Contributing Guide for details.

$3

`bash


Clone repository

git clone https://github.com/VerifiedOnchain/facezk-lib.git
cd facezk-lib

Install dependencies

npm install

Build library

npm run build

Run tests

npm test

Start demo

npm run demo
``

License

MIT License - see LICENSE for details.

Support

- Documentation: https://facezk.com/docs
- Issues: GitHub Issues
- Security: security@facezk.com
- General: team@facezk.com

Acknowledgments

- Human Library - Face detection and analysis
- TensorFlow.js - Machine learning framework
- MediaPipe - Face mesh and landmarks

---

Made with ❤️ by the VerifiedOnchain Team