@wizpro/auth-sdk

SDK for integrating WizAuth authentication into WizPro applications.

Installation

npm install @wizpro/auth-sdk

Quick Start

import { WizAuthClient } from '@wizpro/auth-sdk';

const wizAuth = new WizAuthClient({
  appId: 'rooferwiz',
  appName: 'RooferWiz',
  appIcon: 'https://example.com/icon.png', // optional
});

Push Authentication

Push authentication sends a notification to the user's WizAuth mobile app. The user must select the correct 2-digit number displayed on your app to approve.

Basic Usage

async function authenticateUser(userId: string) {
  try {
    const result = await wizAuth.requestPushAuth({
      userId,
      onChallengeNumber: (challengeNumber) => {
        // Display this number to the user
        // They must match it in WizAuth to approve
        console.log(`Enter ${challengeNumber} in WizAuth to approve`);
      },
      onStatusUpdate: (status) => {
        console.log('Status:', status);
      },
    });

    switch (result.status) {
      case 'APPROVED':
        console.log('User approved! Biometric used:', result.biometricUsed);
        return true;

      case 'DENIED':
        console.log('User denied the request');
        return false;

      case 'EXPIRED':
        console.log('Request timed out');
        return false;

      case 'FRAUD_REPORTED':
        console.log('User reported this as fraudulent!');
        // Take security action
        return false;
    }
  } catch (error) {
    console.error('Push auth failed:', error);
    return false;
  }
}

React Example

import { useState } from 'react';
import { WizAuthClient } from '@wizpro/auth-sdk';

const wizAuth = new WizAuthClient({
  appId: 'rooferwiz',
  appName: 'RooferWiz',
});

function LoginWithPushAuth({ userId }: { userId: string }) {
  const [challengeNumber, setChallengeNumber] = useState<number | null>(null);
  const [status, setStatus] = useState<string>('idle');

  const handleLogin = async () => {
    setStatus('waiting');

    const result = await wizAuth.requestPushAuth({
      userId,
      onChallengeNumber: setChallengeNumber,
      onStatusUpdate: setStatus,
    });

    if (result.status === 'APPROVED') {
      // Redirect to dashboard
      window.location.href = '/dashboard';
    } else {
      setStatus('failed');
    }
  };

  return (
    <div>
      {status === 'idle' && (
        <button onClick={handleLogin}>Login with WizAuth</button>
      )}

      {status === 'waiting' && challengeNumber && (
        <div>
          <p>Open WizAuth and enter:</p>
          <h1>{challengeNumber}</h1>
          <p>Waiting for approval...</p>
        </div>
      )}

      {status === 'failed' && (
        <div>
          <p>Authentication failed</p>
          <button onClick={handleLogin}>Try Again</button>
        </div>
      )}
    </div>
  );
}

Request Types

You can specify different request types for different scenarios:

// Standard login
await wizAuth.requestPushAuth({
  userId,
  requestType: 'LOGIN',
});

// Sensitive action (e.g., deleting data)
await wizAuth.requestPushAuth({
  userId,
  requestType: 'SENSITIVE_ACTION',
  actionDescription: 'Delete all project data',
});

// Financial transaction
await wizAuth.requestPushAuth({
  userId,
  requestType: 'TRANSACTION',
  actionDescription: 'Transfer $500 to vendor',
});

// New device registration
await wizAuth.requestPushAuth({
  userId,
  requestType: 'NEW_DEVICE',
  actionDescription: 'Chrome on Windows 11',
});

Adding Context

Provide additional context for security:

await wizAuth.requestPushAuth({
  userId,
  requestType: 'LOGIN',
  ipAddress: req.ip,
  userAgent: req.headers['user-agent'],
  location: 'Austin, TX',
});

Manual Polling

If you prefer to handle polling yourself:

// Create request
const { requestToken, challengeNumber } = await wizAuth.createPushAuthRequest({
  userId,
  requestType: 'LOGIN',
});

// Display challenge number to user
showChallengeNumber(challengeNumber);

// Poll for status
const checkStatus = async () => {
  const { status } = await wizAuth.getPushAuthStatus(requestToken);

  if (status === 'PENDING') {
    // Still waiting, check again
    setTimeout(checkStatus, 2000);
  } else {
    // Terminal state reached
    handleResult(status);
  }
};

checkStatus();

Configuration

const wizAuth = new WizAuthClient({
  // Required
  appId: 'your-app-id',
  appName: 'Your App Name',

  // Optional
  appIcon: 'https://example.com/icon.png',
  apiUrl: 'https://wiz-auth-psi.vercel.app/api', // default
  timeout: 60000, // 60 seconds (default)
  pollInterval: 2000, // 2 seconds (default)
});

TypeScript

The SDK is written in TypeScript and includes full type definitions:

import type {
  WizAuthConfig,
  PushAuthResult,
  PushAuthStatus,
  PushAuthType,
} from '@wizpro/auth-sdk';

Security Best Practices

1. Always display the challenge number - Users should verify the number matches what they see in WizAuth
2. Use biometric verification - WizAuth supports biometric for added security
3. Provide context - Include IP address, user agent, and location when available
4. Handle fraud reports - If FRAUD_REPORTED, take immediate security action
5. Implement fallback - Have TOTP or backup codes as fallback authentication

Support

For issues or questions, contact [email protected]