Skip to content

js-widget-documentation.md

Latest commit

 

History

History
174 lines (144 loc) · 6.42 KB

js-widget-documentation.md

File metadata and controls

174 lines (144 loc) · 6.42 KB
icon comment-question
layout
cover title description tableOfContents outline pagination
visible size
true
full
visible
true
visible
visible
true
visible
true
visible
true

Walver.io JavaScript Widget

The Walver.io Authentication Widget provides an easy way to integrate blockchain wallet-based authentication into your web application. This widget handles the entire authentication flow, including wallet connection, message signing, and signature verification through our infrastructure.

Installation

Add the Walver.io Authentication Widget script to your HTML page:

<script src="https://walver.io/static/js/walver-auth.js"></script>

Initialization

Initialize the widget with your configuration options:

// Optional: Set the base URL (useful for development environments)
window.walverBaseUrl = 'https://walver.io'; // Default value if not specified

// Initialize the authentication widget
WalverAuth.init({
    buttonText: 'Login with Walver.io', // Optional: Custom button text
    buttonClass: 'walver-auth-button', // Optional: Custom button class
    width: '360px', // Optional: Width of the iframe
    height: '480px', // Optional: Height of the iframe
    serviceName: 'Your Application Name', // Recommended: Your service name
    container: '#my-auth-container', // Required: Container element or selector
    onSuccess: function(data) {
        // Handle successful authentication
        console.log('Authentication successful:', data);
        // data contains: walletAddress, signature, message, chain, nonce, verifiedDomain
    },
    onError: function(error) {
        // Handle authentication error
        console.error('Authentication error:', error);
    },
    onCancel: function() {
        // Handle authentication cancellation
        console.log('Authentication cancelled');
    }
});

Configuration Options

Option Type Required Default Description
container String | Element Yes - The container element or selector where the widget will be rendered
serviceName String Recommended "Walver.io" Your application's name (appears in the signing message)
buttonText String No "Login with Walver.io" Custom text for the authentication button
buttonClass String No "walver-auth-button" Custom CSS class for the button
width String No "360px" Width of the authentication iframe
height String No "480px" Height of the authentication iframe
onSuccess Function No - Callback function called after successful authentication
onError Function No - Callback function called when an error occurs
onCancel Function No - Callback function called when the user cancels authentication

Authentication Response

When authentication is successful, the onSuccess callback will receive an object with the following properties:

{
    walletAddress: "The user's blockchain wallet address",
    signature: "The signature proving wallet ownership",
    message: "The message that was signed",
    chain: "The blockchain used (e.g., 'solana', 'ethereum')",
    nonce: "The nonce used for the authentication",
    verifiedDomain: "The domain that the user authenticated from"
}

Security Features

The Walver.io Authentication Widget implements several security measures:

  • Server-side Signature Verification: All signatures are verified on the server, never in the browser.
  • Service-specific Messages: Each message includes your service name to prevent phishing.
  • Domain Binding: Authentication is bound to your domain to prevent cross-site abuse.
  • Time-limited Signatures: Messages expire after 5 minutes for security.
  • Nonce Protection: Each authentication attempt uses a unique nonce that can only be used once.
  • Origin Validation: Messages are only accepted from authorized origins.
  • Content Security Policy: Strict CSP headers protect against XSS attacks.
  • IP Monitoring: Rate limiting and suspicious activity detection are implemented.

Example Integration

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Walver.io Authentication Example</title>
</head>
<body>
    <h1>Login with Wallet</h1>
    <div id="auth-container"></div>
    
    <script src="https://walver.io/static/js/walver-auth.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            WalverAuth.init({
                container: '#auth-container',
                serviceName: 'My Example App',
                onSuccess: function(data) {
                    console.log('Authenticated!', data);
                    // Here you would typically:
                    // 1. Verify the authentication with your backend
                    // 2. Create a session for the user
                    // 3. Redirect to a logged-in page
                },
                onError: function(error) {
                    console.error('Authentication error:', error);
                    alert('Authentication failed: ' + error);
                }
            });
        });
    </script>
</body>
</html>

Advanced Usage

Custom Button Styling

You can customize the appearance of the authentication button by providing a custom CSS class:

WalverAuth.init({
    container: '#auth-container',
    buttonClass: 'my-custom-button-class',
    // other options...
});

Server-side Verification

For complete security, you should verify the authentication data on your server:

  1. Send the authentication data (wallet address, signature, message, chain, nonce) to your server
  2. Your server should verify the signature using Walver.io's verification API or your own verification logic
  3. Only after server-side verification should you create a session for the user

Troubleshooting

Widget Not Appearing

  • Make sure the container element exists in the DOM before initializing the widget
  • Check browser console for any JavaScript errors

Authentication Failures

  • Ensure the user has a compatible wallet installed and configured
  • Check that the user is connected to the correct blockchain network
  • Verify that your application is properly configured with Walver.io