FaceVault Node.js SDK

Node.js/TypeScript client for the FaceVault identity verification API — privacy-first KYC with liveness detection, face matching, and document verification.

Features

• TypeScript-first — full type definitions, interfaces for all models
• Zero runtime dependencies — uses native fetch (Node 18+) and node:crypto
• ESM + CJS — dual-format package, works everywhere
• Webhook verification — HMAC-SHA256 signature validation with timing-safe comparison
• Secure by default — HTTPS enforced, API keys validated, secrets redacted from inspect

Installation

npm install facevault

Quick start

import { FaceVaultClient } from "facevault";

const client = new FaceVaultClient({ apiKey: "fv_live_your_api_key" });

// Create a verification session
const session = await client.createSession("user-123");
console.log(session.webappUrl); // Send this URL to your user

// With proof of address required
const session2 = await client.createSession("user-123", { requirePoa: true });

// Check session status
const status = await client.getSession(session.sessionId);
console.log(status.status);        // "in_progress", "passed", "failed", "review"
console.log(status.trustScore);     // 0-100 trust score
console.log(status.trustDecision);  // "accept", "review", "reject"

Webhook verification

import { verifySignature, parseEvent } from "facevault";

const body = request.body; // raw string or Buffer
const signature = request.headers["x-signature"];

if (verifySignature(body, signature, "whsec_your_secret")) {
  const event = parseEvent(body);
  console.log(event.event); // "verification.completed"
  console.log(event.sessionId);
  console.log(event.faceMatchPassed);
  console.log(event.trustScore);     // 0-100
  console.log(event.trustDecision);  // "accept", "review", "reject"
  console.log(event.sanctionsHit);   // true/false
}

Error handling

import {
  FaceVaultClient,
  AuthError,
  NotFoundError,
  RateLimitError,
} from "facevault";

const client = new FaceVaultClient({ apiKey: "fv_live_your_api_key" });

try {
  const status = await client.getSession("nonexistent");
} catch (err) {
  if (err instanceof AuthError) {
    console.log("Invalid API key");
  } else if (err instanceof NotFoundError) {
    console.log("Session not found");
  } else if (err instanceof RateLimitError) {
    console.log("Too many requests — back off");
  }
}

Security

The SDK enforces security best practices out of the box:

• HTTPS only — http:// URLs are rejected at init to prevent credentials leaking over plaintext
• Key validation — empty or whitespace-only API keys throw TypeError immediately
• Secret redaction — custom inspect and toJSON() mask the API key, safe for logging
• True private fields — ES2022 # private fields make the API key inaccessible at runtime
• Timing-safe comparison — webhook signature verification uses crypto.timingSafeEqual

What's new in 1.0.0

• requirePoa option on createSession() — per-session proof of address override
• trustScore and trustDecision on SessionStatus — unified 0-100 trust score
• requirePoa, poa, antiSpoofing, credential on SessionStatus
• trustScore, trustDecision, sanctionsHit, poa on WebhookEvent
• challengeNonce on Session — capture integrity nonce

Documentation

• Getting started guide
• API reference
• Blog: Announcing the Node.js SDK

License

MIT