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-facevault-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.1

• Webhook signature verification now HMACs the raw request body instead of re-serializing the parsed JSON. The old approach couldn't reproduce the server's exact signed bytes for payloads containing non-ASCII characters (names, addresses) or whole-number floats, so valid webhooks could be silently rejected. Verification is now byte-exact — pass the body exactly as received.
• README + examples now document the webhook header as X-FaceVault-Signature (the API has always sent this; v1.0.0 docs incorrectly showed X-Signature).
• Reusable identity credentials (/credentials/*) are noted in the Roadmap section — these are planned for the v2 SDK line alongside FacePass / FaceKey, not v1.x.

Documentation

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

Roadmap

The FaceVault platform also offers reusable identity credentials ("verify once, prove forever" — credential challenge / verify / renew / status). These endpoints aren't wrapped by this SDK yet; they're planned for a future release. Until then, call them directly via the REST API.

Contributing

Pull requests welcome! See CONTRIBUTING.md for repo layout, local dev commands, and PR rules.

Reporting a vulnerability

To report a vulnerability, email [email protected] — do not open a public issue. See SECURITY.md for scope and response times.

Changelog

See CHANGELOG.md for a full history of changes.

License

MIT © Kaditham Holdings Pte Ltd