@yavqo/secureid

Yavqo SecureID — Enterprise client-side age & identity verification SDK. Drop-in biometric facial scanning, document OCR, and compliance-ready verification flows for modern web platforms.

Features

• One-Line Setup: Just pass your clientId — configuration, audit logging, and verification rules are loaded automatically from your Developer Console.
• Double Verification Workflow: Selfie facial alignment check + document OCR text extraction with cross-matching.
• Biometric Scanner Simulation: Real-time face-mesh alignment drawn on a dynamic canvas over the camera feed.
• Client-Side Privacy: All processing runs in the user's browser. No images or PII are sent to Yavqo servers.
• React & Vanilla JS: Exported as ESM/CommonJS class and native React hooks/components.
• Automatic Audit Logging: Every verification attempt is logged to your Supabase dashboard.

Installation

npm install @yavqo/secureid

Quick Start: Vanilla JS

import { SecureID } from '@yavqo/secureid';
import '@yavqo/secureid/css';

const verify = new SecureID({
  clientId: 'your-client-id',  // from your Developer Console
  onSuccess: (result) => {
    console.log('Verified!', result.age, result.dob);
  },
  onFailure: (result) => {
    console.error('Failed:', result.error);
  }
});

// Show the verification modal wherever you need it
document.getElementById('verify-button').addEventListener('click', () => {
  verify.open();
});

Quick Start: React / Next.js

1. Declarative Component Wrapper

import { useSecureID } from '@yavqo/secureid/react';
import '@yavqo/secureid/css';

function VerifyButton() {
  const { open } = useSecureID({
    clientId: 'your-client-id',
    onSuccess: (res) => console.log('Verified!', res.age),
    onFailure: (res) => console.error('Failed:', res.error),
  });

  return <button onClick={open}>Verify Age</button>;
}

2. Declarative Modal Component

import { SecureIDModal } from '@yavqo/secureid/react';
import '@yavqo/secureid/css';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Verify Identity</button>
      <SecureIDModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onSuccess={(result) => {
          console.log("Approved!", result.age);
          setIsOpen(false);
        }}
        options={{ supabaseClientId: 'your-client-id' }}
      />
    </div>
  );
}

API Reference

AgeVerifierOptions

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | targetAge | number | 18 | Minimum age required to pass verification. | | mode | 'face' \| 'document' \| 'both' | 'both' | 'face': selfie only. 'document': ID only. 'both': double validation. | | sandbox | boolean | true | When true, runs client-side biometric and OCR text simulations. | | theme | 'light' \| 'dark' | 'dark' | Visual theme of the overlay modal panels. | | accentColor | string | '#10b981' | Theme accent color used for buttons, laser lines, and glowing ticks. | | endpointUrl | string | undefined | POST API endpoint to submit base64 image data to when sandbox: false. | | verifyHandler | Function | undefined | Async function to handle backend calculations manually. Overrides endpointUrl. | | onSuccess | (res: VerificationResult) => void | undefined | Callback fired on approval. | | onFailure | (res: VerificationResult) => void | undefined | Callback fired on rejection or error. | | onClose | () => void | undefined | Callback fired when the overlay is closed. |

VerificationResult

interface VerificationResult {
  success: boolean;
  mode: 'face' | 'document' | 'both';
  age?: number;
  dob?: string;
  documentDetails?: {
    type: string;
    name?: string;
    expiryDate?: string;
    documentNumber?: string;
  };
  confidence: number; // percentage (0 - 100)
  images: {
    face?: string; // base64 JPEG data URL
    document?: string; // base64 JPEG data URL
  };
  error?: string; // present on failed checks
}

Real Backend Integration

In production environments, switch sandbox: false and configure a secure verification endpoint or handler:

Using endpointUrl (HTTP POST)

The SDK will automatically post a payload containing base64 images to your server:

const verifier = new AgeVerifier({
  sandbox: false,
  endpointUrl: 'https://api.yourdomain.com/verify-identity',
  // ...
});

Request Payload sent by SDK:

{
  "faceImage": "data:image/jpeg;base64,...",
  "documentImage": "data:image/jpeg;base64,...",
  "mode": "both"
}

Your backend should process these images (using APIs like Google Cloud Vision or Amazon Rekognition) and respond with a JSON body matching the VerificationResult structure.

Supabase Integration

Yavqo SecureID supports logging session attempts automatically to your database and loading configuration rules dynamically. All tables are prefixed with secureid_.

1. Database Table Setup

Execute the SQL statements inside supabase_schema.sql in your Supabase SQL Editor. This initializes:

• secureid_attempts: Storage for session outputs (Passed/Failed status, metadata, and optional base64 captured images).
• secureid_configurations: Central rules registry to dynamic control of client verification options.

2. Client Initialization

Configure the SDK with your database details:

import { SecureID } from '@yavqo/secureid';

const secureID = new SecureID({
  targetAge: 18,
  supabaseEnabled: true,
  supabaseUrl: 'https://ikjugnimawkoatkbvpgk.supabase.co',
  supabaseKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImlranVnbmltYXdrb2F0a2J2cGdrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODAwNzI3OTAsImV4cCI6MjA5NTY0ODc5MH0.xr9B_khj2zKIEoUsTisL66SGgn8Yo2K0YH5YDw0QmQw',
  
  // Optional: Fetch targetAge and mode remotely from secureid_configurations
  supabaseClientId: 'yavqo-enterprise-partner'
});

Browser Compatibility

• Camera access: Supported in all modern mobile and desktop browsers (Chrome, Safari, Firefox, Edge). Requires an HTTPS context locally/in staging (localhost is exempted).
• Dialog styling: Uses native HTML dialog components supporting Esc keys and backdrop captures. Includes polyfills to handle light-dismiss on Safari browsers.