@surtai/faceguard

Official SDK for FaceGuard — face verification for secure login.

Install

npm install @surtai/faceguard

Quick Start

Callback style

import { FaceGuard } from '@surtai/faceguard';

const fg = FaceGuard.init({
  token: 'PORTAL_TOKEN', // from your backend
  onSuccess: (result) => console.log('Approved', result.confidence),
  onFailed: (result) => console.log('Rejected', result.confidence),
  onCancel: () => console.log('Canceled'),
  onError: (error) => console.log('Error', error.message),
});

// cleanup
fg.destroy();

Async/await

const result = await FaceGuard.verify({ token: 'PORTAL_TOKEN' });

if (result.status === 'approved') {
  // grant access
} else if (result.status === 'rejected') {
  // deny access
}

Options

| Option | Type | Required | Default | Description | | ----------- | ----------------------- | -------- | ---------------------------- | ------------------------------------------ | | token | string | Yes | — | Portal JWT from your backend | | baseUrl | string | No | https://faceguard.surt.com | Override for non-prod environments | | mode | 'mobile' \| 'desktop' | No | Auto-detect | Force mobile (camera) or desktop (QR) flow | | container | HTMLElement | No | document.body | DOM element to mount the overlay into | | lang | string | No | Browser default | 'en', 'es', 'pt', or 'de' |

Callbacks (FaceGuard.init)

| Callback | Payload | Description | | ----------- | ------------------------ | --------------------------- | | onReady | — | FaceGuard iframe loaded | | onSuccess | { confidence: number } | Verification passed (0-100) | | onFailed | { confidence: number } | Verification failed (0-100) | | onCancel | — | User closed FaceGuard | | onError | { message: string } | Something went wrong |

Result (FaceGuard.verify)

interface FaceGuardVerifyResult {
  status: 'approved' | 'rejected' | 'canceled' | 'error';
  confidence?: number;
  error?: string;
}

How It Works

The SDK creates an iframe overlay pointing to the FaceGuard app. On mobile, it goes fullscreen with the camera flow. On desktop, it shows a phone-shaped modal with a QR code for phone handoff (or "Verify Here" for webcam).

All communication happens via postMessage. The SDK handles the event mapping and cleanup automatically.

Requirements

• HTTPS (camera requires secure context)
• A valid portal token from your backend

License

Apache 2.0