@zerocat-software/zerobrix-auth NPM

@zerocat-software/zerobrix-auth

A modern, secure, and easy-to-use authentication library for Next.js applications powered by ZeroBrix blockchain. Perfect for projects that need blockchain-based authentication with a beautiful frosted-glass modal UI and encrypted user management.

Why ZeroBrix Auth?

ZeroBrix Auth brings enterprise-grade blockchain authentication to your Next.js application with minimal setup. While ZeroBrix Blockchain is our proprietary solution for secure transactions, this authentication library is fully open-source, allowing developers to:

✅ Inspect and verify the security implementation
✅ Contribute improvements and features
✅ Trust through code transparency
✅ Customize the solution for specific needs

Features At a Glance

🎨 Beautiful Modal UI: Frosted glass design with smooth animations
🔐 Secure Authentication: QR code-based blockchain authentication
🔒 Encrypted Storage: Built-in encrypted JSON database
📱 Mobile Ready: Seamless ZeroWallet mobile app integration
🔄 Flexible Onboarding: Individual and company account support
⚡ Zero Config: No manual route setup needed
🎯 Simple Integration: Just wrap your components
🌐 TypeScript Ready: Full type support

Installation

# Using npm
npm install @zerocat-software/zerobrix-auth

# Using yarn
yarn add @zerocat-software/zerobrix-auth

# Using pnpm
pnpm add @zerocat-software/zerobrix-auth

Complete Setup Guide

1. Environment Variables

Create or update .env.local in your project root:

# Required: ZeroBrix API Configuration
ZEROBRIX_API_URL=https://brix.zerocat.one/api/v2
ZEROBRIX_API_KEY=your_api_key
AUTH_CONTRACT_ID=your_contract_id

# Required: Public Variables
NEXT_PUBLIC_SERVER_WALLET_ADDRESS=your_wallet_address
NEXT_PUBLIC_ZEROCOIN_TOKEN_ID=your_token_id

# Optional: Database Encryption
DB_ENCRYPTION_KEY=your_random_32_byte_hex_string

2. Create Auth API Route

Create app/api/auth/route.ts:

import { createAuthApiHandler } from '@zerocat-software/zerobrix-auth';

// Important for Next.js dynamic routes
export const dynamic = 'force-dynamic';

// Export the authentication handlers
export const { GET, POST } = createAuthApiHandler({
  // Optional: Add custom validation
  customValidation: async (walletAddress: string) => {
    return true; // Allow all wallets by default
  }
});

3. Add the Provider

In your app/layout.tsx:

import { AuthProvider } from '@zerocat-software/zerobrix-auth';

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <AuthProvider
          config={{
            // Required
            appName: "Your App Name",
            appDescription: "Login securely with ZeroWallet",
            
            // Optional: Theme
            theme: {
              primary: "blue",
              secondary: "teal"
            }
          }}
        >
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}

4. Protect Your Pages

Simply wrap any page that needs authentication:

'use client';

import { withAuth, useAuth } from '@zerocat-software/zerobrix-auth';

function ProtectedPage() {
  const { user, logout } = useAuth();
  
  return (
    <div>
      <h1>Protected Content</h1>
      <p>Welcome back!</p>
      
      {/* User will be either individual or company */}
      <div>
        {user?.company_name ? (
          <p>Company: {user.company_name}</p>
        ) : (
          <p>Name: {user.first_name} {user.last_name}</p>
        )}
      </div>
      
      <button onClick={logout}>Logout</button>
    </div>
  );
}

export default withAuth(ProtectedPage);

Understanding the Authentication Flow

How It Works

User visits a protected page
Auth modal automatically appears
User scans QR code with ZeroWallet
ZeroWallet processes the authentication transaction
Library verifies the transaction
If new user, shows onboarding form
User is authenticated and can access protected content

The Modal UI

The authentication modal includes:

Clean, modern frosted glass design
ZEROCAT branding (subtle corner logo)
Step-by-step guidance
Smooth transitions
QR code display
Loading states
Error handling

User Data Storage

All user data is stored in an encrypted JSON file:

Automatic encryption/decryption
Secure at rest
No database setup needed
Handles both user types:
- Individual (first name, last name)
- Company (company name)

Customization Options

Styling

<AuthProvider
  config={{
    // Theme colors
    theme: {
      primary: "indigo",    // Any Tailwind color
      secondary: "purple"   // Any Tailwind color
    },
    
    // Custom class names
    customStyles: {
      card: "backdrop-blur-xl bg-white/10",
      button: "hover:scale-105",
      input: "focus:ring-2"
    }
  }}
>

Onboarding Configuration

<AuthProvider
  config={{
    onboardingFields: {
      // Enable/disable company accounts
      allowCompany: true,
      
      // Field requirements
      requireName: false,
      requireEmail: false,
      
      // Available roles
      availableRoles: ["User", "Admin"]
    }
  }}
>

Custom Validation

export const { GET, POST } = createAuthApiHandler({
  customValidation: async (walletAddress: string) => {
    // Example: Check whitelist
    const whitelist = ['0x123...'];
    return whitelist.includes(walletAddress);
    
    // Or check domain
    const email = await getEmailForWallet(walletAddress);
    return email.endsWith('@yourcompany.com');
  }
});

Troubleshooting Guide

Modal Not Appearing

// Make sure to:
// 1. Add 'use client' directive
'use client';

// 2. Wrap the component
export default withAuth(YourComponent);

// 3. Use inside AuthProvider
function App() {
  return (
    <AuthProvider config={...}>
      <YourComponent />
    </AuthProvider>
  );
}

Styling Issues

// In tailwind.config.js
module.exports = {
  content: [
    // Essential: Include the library's components
    "./node_modules/@zerocat-software/zerobrix-auth/**/*.{js,ts,jsx,tsx}"
  ]
}

Database Issues

# Create data directory
mkdir data
chmod 755 data

# Check .env.local
DB_ENCRYPTION_KEY should be exactly 32 bytes when converted to hex

Security Best Practices

Always keep your API keys secure
Don't expose your DB_ENCRYPTION_KEY
Use custom validation for additional security
Implement role-based access control
Regularly update the library

Support

📧 Email Support
🌐 Website
💼 LinkedIn
📝 Blog

License

Licensed under the BSD-3-Clause License. See LICENSE for more information.

zerocat.art • LinkedIn • Blog

zerocat authentication wallet zerobrix react nextjs

clsx fs tailwind-merge

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago