@finalboss/idv-sdk

Official SDK for FinalBoss IDV++ API - Enterprise Identity Verification with Post-Quantum Cryptographic Governance.

Features

• 🔐 Identity Verification - Document, biometric, and liveness verification
• 🔗 Hash-Chain Governance - Tamper-evident audit trail with cryptographic receipts
• 🛡️ Post-Quantum Security - ML-DSA-65 (NIST FIPS 204) signatures
• ⚡ Epoch-Based Revocation - O(1) instant mass invalidation
• 📋 Consent Management - GDPR/CCPA compliant consent tracking
• 🎯 Liveness Detection - 60-second time-bound biometric proofs
• 📊 Full TypeScript Support - Complete type definitions

Installation

npm install @finalboss/idv-sdk

Quick Start

import { IDVClient } from '@finalboss/idv-sdk';

const client = new IDVClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  // Optional: custom base URL
  // baseUrl: 'https://your-instance.example.com'
});

// Create and process a verification
const verification = await client.createVerification({
  user_id: 'user-123',
  verification_type: 'identity',
  metadata: { document_type: 'passport', country: 'USA' }
});

const result = await client.processVerification(verification.verification_id);
console.log(`Verification ${result.passed ? '✅ PASSED' : '❌ FAILED'}`);
console.log(`Confidence: ${(result.confidence_score * 100).toFixed(1)}%`);

API Reference

Verifications

// Create a verification
const verification = await client.createVerification({
  user_id: 'user-123',
  verification_type: 'identity', // 'document' | 'biometric' | 'liveness' | 'age' | 'identity'
  metadata: { /* custom data */ }
});

// Process through ML pipeline
const result = await client.processVerification(verification.verification_id);

// Get verification details
const details = await client.getVerification(verification.verification_id);

// List all verifications
const { verifications, total } = await client.listVerifications({
  status: 'verified',
  limit: 100
});

Governance Receipts

// Get receipt chain for a verification
const chain = await client.getGovernanceReceipts(verificationId);
console.log(`Chain integrity: ${chain.chain_integrity}`);

// Verify entire receipt chain
const verification = await client.verifyGovernanceChain();
console.log(`Total receipts: ${verification.total_receipts}`);
console.log(`Failures: ${verification.failures.length}`);

// Export for independent verification
const export = await client.exportGovernanceReceipts();

Post-Quantum Cryptography (ML-DSA-65)

// Get PQC public key
const pqcKey = await client.getPQCPublicKey();
console.log(`Algorithm: ${pqcKey.algorithm}`);
console.log(`Key size: ${pqcKey.public_key_bytes} bytes`);

// Create PQC receipt
const receipt = await client.createPQCReceipt({
  event_type: 'verification_completed',
  verification_id: verificationId,
  decision_logic: { confidence: 0.95 }
});
console.log(`Signature: ${receipt.signature_bytes} bytes`);

// Verify PQC chain
const pqcVerification = await client.verifyPQCChain();
console.log(`Chain integrity: ${pqcVerification.chain_integrity}`);

// Export with public key for offline verification
const pqcExport = await client.exportPQCReceipts();

Consent Management (GDPR/CCPA)

// Create consent
const consent = await client.createConsent({
  subject_id: 'user-123',
  partner_id: 'partner-acme',
  purpose: 'identity_verification',
  scope: {
    data_types: ['name', 'photo', 'date_of_birth'],
    retention_days: 90
  }
});

// Verify consent
const { valid, consent } = await client.verifyConsent({
  subject_id: 'user-123',
  partner_id: 'partner-acme',
  purpose: 'identity_verification'
});

// Revoke consent
await client.revokeConsent(consentId, { reason: 'user_request' });

// List all consents for a subject
const { consents } = await client.listConsentsForSubject('user-123');

Liveness Detection

// Create challenge
const challenge = await client.createLivenessChallenge({
  subject_id: 'user-123',
  challenge_type: 'blink' // 'blink' | 'smile' | 'turn_head' | 'speak_phrase' | 'nod'
});

console.log(`Challenge: ${challenge.instructions}`);
console.log(`Expires: ${challenge.expires_at}`);

// Submit response (within 60 seconds)
const result = await client.submitLivenessResponse(challenge.challenge_id, {
  response_data: base64EncodedVideoFrame,
  device_info: {
    user_agent: navigator.userAgent,
    platform: navigator.platform
  }
});

console.log(`Result: ${result.result}`);
console.log(`Confidence: ${result.confidence_score}`);

Epoch-Based Revocation

// Get current epoch
const epoch = await client.getEpochStatus();
console.log(`Current epoch: ${epoch.epoch_id}`);

// FLIP EPOCH - Instantly invalidate ALL prior verifications
const flip = await client.flipEpoch({ reason: 'security_incident' });
console.log(`New epoch: ${flip.new_epoch}`);
console.log(flip.message); // "All verifications issued before epoch X are now INVALID"

// Revoke single verification
const revocation = await client.revokeVerification(verificationId, {
  reason: 'fraud_detected'
});

// Check if verification is still valid
const validity = await client.checkVerificationValidity(verificationId);
console.log(`Valid: ${validity.valid}`);

Policy Management

// Get current policy
const policy = await client.getPolicy();

// Set policy
const newPolicy = await client.setPolicy({
  policy_data: {
    verification_threshold: 0.85,
    consent_required: true,
    liveness_required: true,
    retention_days: 365,
    pqc_receipts_enabled: true
  },
  version: '2.0.0'
});

// Get policy history
const { policies } = await client.getPolicyHistory();

Health & Discovery

// Check API health
const health = await client.health();
console.log(`Version: ${health.version}`);
console.log(`PQC enabled: ${health.pqc.enabled}`);

// Get JWKS for JWT verification
const jwks = await client.getJWKS();

Error Handling

import {
  IDVClient,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  IDVError
} from '@finalboss/idv-sdk';

try {
  await client.createVerification({ /* ... */ });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed - check credentials');
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.details);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited - retry after ${error.details?.retry_after}s`);
  } else if (error instanceof IDVError) {
    console.error(`API error ${error.status}: ${error.message}`);
  }
}

Configuration

const client = new IDVClient({
  // Required
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',

  // Optional
  baseUrl: 'https://your-instance.example.com',
  timeout: 30000, // Request timeout in ms

  // Custom fetch (useful for testing/mocking)
  fetch: customFetchImplementation,

  // Retry configuration
  retry: {
    maxRetries: 3,
    baseDelay: 1000,
    maxDelay: 10000
  }
});

TypeScript Support

Full TypeScript support with complete type definitions:

import type {
  Verification,
  VerificationResult,
  PQCReceipt,
  Consent,
  LivenessChallenge,
  EpochStatus
} from '@finalboss/idv-sdk';

License

MIT

Support

• Documentation: https://finalbosstech.com/docs
• Issues: https://github.com/805-ai/finalboss-idv-sdk/issues
• Email: [email protected]