Spectre Snap

Identity-as-a-Service — Embeddable facial authentication for React applications.

Spectre Snap is a drop-in React component that provides a complete facial authentication experience powered by Spectre's liveness detection (Face Anti-Spoofing) and biometric identity matching pipeline.

Installation

npm install @thewhitenigs/spectre-snap

Quick Start

import { SpectreAuth } from '@thewhitenigs/spectre-snap';
import '@thewhitenigs/spectre-snap/style.css';

function LoginPage() {
  return (
    <SpectreAuth
      apiKey="spk_..."
      userId="[email protected]"
      onSuccess={(result) => {
        console.log('Verified!', result.sessionId);
        // redirect or update auth state
      }}
      onFailed={(reason) => {
        console.log('Failed:', reason);
      }}
    />
  );
}

Modal Variant

import { useState } from 'react';
import { SpectreAuthModal } from '@thewhitenigs/spectre-snap';
import '@thewhitenigs/spectre-snap/style.css';

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Verify Identity</button>
      <SpectreAuthModal
        open={open}
        onOpenChange={setOpen}
        apiKey="spk_..."
        userId="[email protected]"
        onSuccess={(result) => {
          console.log('Verified!', result.sessionId);
          setOpen(false);
        }}
      />
    </>
  );
}

Global Configuration (Provider)

import { SpectreAuthProvider, SpectreAuth } from '@thewhitenigs/spectre-snap';
import '@thewhitenigs/spectre-snap/style.css';

function App() {
  return (
    <SpectreAuthProvider
      apiKey="spk_..."
      baseUrl="https://your-backend.com"
      theme="dark"
    >
      {/* All SpectreAuth instances inherit the provider config */}
      <SpectreAuth
        userId="[email protected]"
        onSuccess={handleSuccess}
      />
    </SpectreAuthProvider>
  );
}

Props Reference

SpectreAuth

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | Provider value | API key from the Spectre dashboard. Required unless SpectreAuthProvider supplies it | | userId | string | "anonymous" | External user identifier | | mode | "register" \| "authenticate" \| "auto" | "auto" | Scan mode — auto detects from existing profile | | baseUrl | string | HF Spaces prod | Override backend API URL | | redirectUrl | string | — | URL to redirect after success | | redirectDelay | number | 5 | Seconds before redirect | | fas | boolean | true | Enable face anti-spoofing | | requirePose | boolean | true | Require head-pose ring scan | | showPreview | boolean | false | Show preview before submission | | theme | "dark" \| "light" \| "auto" | "dark" | UI theme | | locale | "id" \| "en" | "id" | Deprecated placeholder; scanner copy remains Indonesian in this release |

Callbacks

| Callback | Signature | Description | |----------|-----------|-------------| | onSuccess | (result: SpectreAuthResult) => void | Fired on successful authentication | | onFailed | (reason: SpectreFailureReason, result?: SpectreAuthResult) => void | Fired on failure | | onClose | () => void | Fired when user dismisses the scanner | | onReady | () => void | Fired when camera is active and scanner is ready | | onRedirect | () => void | Fired when the success countdown completes instead of assigning window.location.href |

SpectreAuthResult

interface SpectreAuthResult {
  verdict: "ok" | "spoof" | "warn";
  label: string;
  sessionId?: string;
  similarityScore?: number;
  inferenceTimeMs?: number;
  summary: { live: number; spoof: number };
  detail: Record<string, number> | null;
}

SpectreFailureReason

| Reason | Description | |--------|-------------| | liveness_failed | Face anti-spoofing detected a presentation attack | | face_not_detected | No face found in the frame | | face_mismatch | Face does not match the registered profile | | quality_insufficient | Image quality too low for reliable inference | | session_expired | Scan session expired | | user_cancelled | User closed the scanner | | camera_denied | Camera permission denied | | network_error | Network connectivity issue | | system_error | Unexpected backend error |

TypeScript

All types are exported and fully documented. Import them directly:

import type {
  SpectreAuthResult,
  SpectreFailureReason,
  SpectreAuthProps,
  SpectreErrorCode,
} from '@thewhitenigs/spectre-snap';

Requirements

• React ≥ 18
• Modern browser with camera access (WebRTC)
• Valid Spectre API key

License

ISC