Mona Attest Frontend SDK

🚀 Secure Client-Side User Attestation for Modern Web Applications

The Mona Attest Frontend SDK provides seamless client-side user attestation and biometric verification for React and Next.js applications. Built for payment platforms, fintech apps, and any application requiring secure user verification.

✨ Key Features

• 🔐 WebAuthn Integration - Passwordless authentication with biometrics
• 📱 Cross-Platform Support - Works on web, mobile, and desktop
• ⚡ One-Line Integration - Simple API for complex attestation flows
• 🎨 Customizable UI - Branded authentication interfaces
• 🔄 Automatic Key Management - Handles all cryptographic operations
• 🎯 Payment Optimized - Built specifically for financial applications
• ⚛️ React Components - Pre-built UI components for React apps

📦 Installation

npm install @usemona/attest-frontend-sdk

🎯 Quick Start

Basic Usage (Recommended)

import { AttestFrontendSDK } from '@usemona/attest-frontend-sdk';

// Initialize the SDK
const attestFrontendSDK = new AttestFrontendSDK({
  customUrls: {
    apiUrl: 'https://your-api.com'
  },
    branding: {
      primaryColor: '#FE7048',
      backgroundColor: '#ffffff'
    }
  });

// One-line authenticated API call
const response = await attestFrontendSDK.fetchWithAttestation(
  'https://api.example.com/secure-endpoint',
  {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 1000, recipient: '[email protected]' })
  },
  {
    onSigningComplete: () => console.log('✅ User authenticated!'),
    onRequestStart: () => console.log('🚀 Processing request...')
  }
);

React Component Usage

import { AttestSigning } from '@usemona/attest-frontend-sdk';

function PaymentForm() {
  const handleAttestation = async (result) => {
    if (result.success) {
      console.log('Payment authorized:', result);
    }
  };

  return (
    <AttestSigning
      requestData={{
        amount: 1000,
        recipient: '[email protected]'
      }}
      onComplete={handleAttestation}
      branding={{
        primaryColor: '#FE7048',
        borderRadius: '12px'
      }}
    />
  );
}

🔧 Configuration Options

SDK Configuration

const config = {
  // API Configuration
  customUrls: {
    apiUrl: 'https://your-attesttool-backend.com',
    enrollmentUrl: 'https://your-attesttool-backend.com/api/enrollment',
    discoveryUrl: 'https://your-attesttool-backend.com/api/user-discovery'
  },
  
  // UI Customization
  branding: {
    primaryColor: '#FE7048',        // Main brand color
    backgroundColor: '#ffffff',      // Background color
    textColor: '#1f2937',           // Text color
    buttonColor: '#FE7048',         // Button color
    borderRadius: '12px',           // Border radius
    fontFamily: 'Inter, sans-serif' // Font family
  },
  
  // Behavior Settings
  allowAnonymous: true,             // Allow anonymous users
  requireBiometrics: false,         // Force biometric verification
  timeout: 30000                    // Request timeout in ms
};

📚 API Reference

AttestFrontendSDK Methods

fetchWithAttestation(url, options, callbacks)

Performs an authenticated HTTP request with automatic user attestation.

Parameters:

• url (string): The API endpoint URL
• options (RequestInit): Standard fetch options (method, headers, body, etc.)
• callbacks (object): Optional callbacks for UI feedback
  • onSigningComplete: Called when user authentication succeeds
  • onRequestStart: Called when the API request begins
  • onError: Called if attestation fails

Returns: Promise - Standard fetch Response object

createAttestation(requestData)

Creates a user attestation for the given request data.

Parameters:

• requestData (object): The data to be attested

Returns: Promise

📝 Important: After creating an attestation token, send it to your backend where it should be verified using the mona-attest-backend package. The frontend SDK only creates attestations - verification must happen server-side for security.

whoIsThisUser(options)

Discovers and returns information about the current user.

Parameters:

• options (object): Discovery options

Returns: Promise

🎨 React Components

<AttestSigning>

Pre-built React component for user attestation flows.

Props:

• requestData (object): Data to be attested
• onComplete (function): Callback when attestation completes
• onError (function): Callback for error handling
• branding (object): UI customization options
• allowAnonymous (boolean): Allow anonymous attestation

🏗️ Architecture

The frontend SDK handles:

1. User Discovery - Automatic detection of existing users
2. Key Management - WebAuthn key generation and storage
3. Biometric Authentication - Fingerprint, face, or device authentication
4. Cryptographic Signing - Secure request signing
5. UI Management - Modal overlays and user feedback
6. Error Handling - Graceful fallbacks and error reporting

🔄 Integration with Backend

This frontend SDK creates attestation tokens that must be verified on your backend for security. Here's the complete flow:

Step 1: Frontend - Create Attestation (Client-Side)

import { AttestFrontendSDK } from '@usemona/attest-frontend-sdk';

const attestFrontendSDK = new AttestFrontendSDK();

// Create attestation token
const attestationToken = await attestFrontendSDK.createAttestation({
  body: { amount: 1000, recipient: '[email protected]' },
  uri: '/api/payments',
  method: 'POST'
});

// Send to your backend
fetch('/api/payments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Attestation-Token': attestationToken  // Include the token
  },
  body: JSON.stringify({ amount: 1000, recipient: '[email protected]' })
});

Step 2: Backend - Verify Attestation (Server-Side)

Install the backend SDK in your server project:

npm install @usemona/attest-backend-sdk  # For Node.js backend

// Your backend server (Express.js example)
import { AttestBackendSDK } from '@usemona/attest-backend-sdk';

const attestBackendSDK = new AttestBackendSDK();

app.post('/api/payments', async (req, res) => {
  try {
    const attestationToken = req.headers['x-attestation-token'];
    
    // Verify the attestation token
    const verification = await attestBackendSDK.verifyAttestation(attestationToken, {
      body: req.body,
      headers: req.headers,
      method: req.method,
      url: req.url
    });
    
    if (verification.verified) {
      // ✅ Attestation valid - process the payment
      console.log('Authenticated user:', verification.user);
      const result = await processPayment(req.body);
      res.json({ success: true, paymentId: result.id });
    } else {
      // ❌ Invalid attestation - reject request
      res.status(403).json({ error: 'Invalid attestation' });
    }
  } catch (error) {
    res.status(500).json({ error: 'Verification failed' });
  }
});

🔒 Security Note: Never skip server-side verification. The frontend SDK is only for creating attestations - all verification must happen on your secure backend using mona-attest-backend.

🌟 Use Cases

• 💳 Payment Authentication - Secure payment authorization
• 🏦 Banking Applications - Account access and transactions
• 📱 Mobile Wallets - Secure wallet operations
• 🔐 Identity Verification - Know Your Customer (KYC) flows
• 📊 Sensitive Data Access - Protect critical business operations

🤝 Support

• Documentation: Full API Documentation
• Issues: GitHub Issues
• Discord: Join our community
• Email: [email protected]

📄 License

MIT License - see LICENSE file for details.

🚀 Getting Started

Ready to add secure attestation to your app? Check out our Quick Start Guide.

Made with ❤️ by the Mona Team