⚡ Lightning Auth & Payment

The complete Lightning Network authentication and payment solution for modern web applications

Build Lightning Network-powered applications with ease. From simple single-page shops to complex eCommerce platforms, Lightning Auth & Payment provides everything you need for Lightning Network integration.

🚀 Quick Start

For AI Agents (Cursor, etc.)

Use our AI Setup Guide - copy and paste a single prompt to automatically configure everything.

📚 Examples Available

Check out our comprehensive examples in the /examples folder:

• 🚀 Next.js Full Example - Complete Lightning integration
• 🔐 Auth Only Example - Authentication without payments
• 💳 Payment Only Example - Payments without authentication
• ⚛️ React Example - React with Lightning integration
• 🚀 Express.js Example - Node.js API with Lightning

⚡ Zero-Config Setup (30 seconds!)

1. Install the library:

npm install lightning-auth-and-payment

2. Configure Next.js plugin in next.config.js:

import { withLightning } from 'lightning-auth-and-payment/nextjs';

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your existing config
};

// Zero-config: Auto-detects everything!
export default withLightning()(nextConfig);

3. Start development:

npm run dev:lightning

That's it! The plugin automatically:

• 🔍 Detects your project configuration
• 🔧 Generates all API routes
• 📝 Creates environment files
• 🗄️ Sets up database schema
• 🔒 Configures HTTPS development
• 🚀 Adds development scripts

🎯 Custom Configuration (Optional)

export default withLightning({
  database: 'prisma',     // Auto-detected
  btcpay: true,           // Auto-detected
  development: true,      // Auto-detected
  // ... other options
})(nextConfig);

✨ What You Get Automatically

🔧 Auto-Generated API Routes

• /api/auth/lnurl - Generate Lightning authentication URL
• /api/auth/callback - Handle authentication callback
• /api/auth/status - Check authentication status
• /api/auth/logout - User logout
• /api/user - Get current user information
• /api/payment/create-invoice - Create Lightning invoice
• /api/payment/status - Check payment status
• /api/webhooks/btcpay - BTCPay Server webhooks

🗄️ Auto-Generated Database Schema

• User management and sessions
• LNURL challenges and logins
• Payment and invoice tracking
• Order and order item management
• Complete Prisma schema with migrations

🚀 Zero-Config Development Features

• Smart Detection: Auto-detects Prisma, BTCPay, database setup
• Environment Setup: Auto-creates .env.local with secure defaults
• Database Setup: Auto-generates Prisma schema and runs migrations
• HTTPS Development: Auto-configures SSL certificates for Lightning wallets
• Development Scripts: Auto-adds dev:lightning and other helpful scripts
• Hot Reloading: Automatic route regeneration on changes
• TypeScript Support: Full type safety and IntelliSense
• Mobile Wallet Compatibility: Works with Alby, Zeus, and other Lightning wallets

💳 BTCPay Server Setup (Required for Payments)

To use the payment features, you need a BTCPay Server instance with Lightning Network support. The easiest way to set this up is using the SamRock Protocol with AQUA Wallet:

Recommended Setup: SamRock Protocol + AQUA Wallet

1. Install BTCPay Server with the SamRock plugin
2. Install AQUA Wallet on your mobile device
3. Connect using SamRock Protocol:
   • Install the SamRock plugin in BTCPay Server
   • Click "SamRock Protocol" in the BTCPay dashboard
   • Select payment methods: Bitcoin, Liquid, Lightning
   • Scan the QR code with AQUA Wallet
   • Your wallet securely provides the necessary public keys
   • No private keys are ever exposed to the server

This setup eliminates the need to:

• Run a Lightning node
• Manage private keys on the server
• Configure complex XPUB settings
• Handle Liquid blinding keys manually

Learn more: SamRock Protocol Documentation

Alternative: Manual BTCPay Server Setup

If you prefer manual setup:

1. Set up BTCPay Server with Lightning support
2. Configure your Lightning node (LND, CLN, or Eclair)
3. Create a store and get your API credentials
4. Add the credentials to your environment variables

🎯 What the Plugin Provides

• ✅ Automatic API route generation - No manual route creation needed
• ✅ Database adapter integration - Works with Prisma out of the box
• ✅ BTCPay Server integration - Complete payment processing
• ✅ Authentication flow - LNURL-auth with session management
• ✅ Development server - HTTPS with SSL certificates
• ✅ TypeScript support - Full type safety and IntelliSense

🎯 Core Features

✅ Lightning Authentication

• LNURL-auth protocol - Industry standard Lightning authentication
• QR Code generation - Works with any Lightning wallet
• Session management - Secure JWT-based sessions
• Wallet compatibility - Alby, Phoenix, Breez, Zeus, and more

✅ Lightning Payments

• BTCPay Server integration - Real Lightning invoices
• Automatic polling - Payment status detection
• QR Code payments - Mobile wallet support
• Success handling - User-friendly payment confirmation

✅ Development Experience

• Local HTTPS server - SSL certificates for wallet compatibility
• TypeScript support - Full type safety
• React components - Ready-to-use UI components
• Hot reload - Fast development iteration

🛠️ Development Server

The library includes a built-in development server for local HTTPS development with Lightning authentication support.

⚡ Quick Start with Binary

# Install the library
npm install lightning-auth-and-payment

# Add to package.json scripts
npm pkg set scripts.dev:lightning="lightning-dev-server"
npm pkg set scripts.dev:https="lightning-dev-server"

# Start the development server
npm run dev:lightning

🎯 What You Get

• 🔒 Automatic SSL certificates - Uses mkcert for trusted local certificates
• 🔄 Hot reload support - Works with Next.js development server
• 📱 Mobile wallet compatibility - HTTPS required for Lightning wallets
• 🌐 CORS handling - Pre-configured for Lightning wallet requests
• ⚡ Lightning-ready - Optimized for Lightning Network development
• 🎨 Beautiful UI - Professional Lightning Network theming
• 📊 Real-time logging - Detailed development feedback

Advanced Configuration

import { LightningDevServer } from 'lightning-auth-and-payment/dev';

const devServer = new LightningDevServer({
  nextPort: 3000,        // Next.js development server port
  httpsPort: 3443,       // HTTPS proxy port
  certsDir: 'certs',     // SSL certificates directory
  projectRoot: process.cwd(),
  verbose: true,          // Enable detailed logging
});

await devServer.start();

Package.json Integration

{
  "scripts": {
    "dev": "next dev",
    "dev:lightning": "lightning-dev-server",
    "dev:https": "lightning-dev-server"
  }
}

📦 What's Included

🔐 Authentication

import { LightningAuth, useAuth } from 'lightning-auth-and-payment';

// Server-side authentication
const auth = new LightningAuth({
  sessionSecret: process.env.SESSION_SECRET!,
  lnurlStore: new MemoryLnurlStore(),
});

// Client-side authentication
const { isAuthenticated, login, logout, user } = useAuth();

💳 Payments

import { BTCPayPaymentModal, createBTCPayService } from 'lightning-auth-and-payment';

// Payment modal component
<BTCPayPaymentModal
  isOpen={showPayment}
  onClose={() => setShowPayment(false)}
  amount={1000}
  description="Purchase item"
  onPaymentSuccess={() => console.log('Payment successful!')}
  autoCloseDelay={3000}
  successMessage="Payment confirmed!"
/>

// BTCPay service
const btcpayService = createBTCPayService();
const invoice = await btcpayService.createInvoice({
  amount: 1000,
  currency: 'SATS',
  description: 'Purchase item',
});

🎨 UI Components

import { 
  AuthHeader, 
  BTCPayPaymentModal, 
  Button, 
  Card 
} from 'lightning-auth-and-payment';

// Pre-built components with Lightning Network styling
<AuthHeader />
<Button onClick={handlePayment}>Buy Now</Button>
<Card>Your content here</Card>

🛠️ Environment Setup

Create .env.local:

# Session Configuration
SESSION_SECRET=your-super-secret-session-key-here-make-it-long-and-random
SESSION_COOKIE_DOMAIN=localhost

# BTCPay Server Configuration (required for payments)
BTCPAY_HOST=https://your-btcpay-server.com
BTCPAY_STORE_ID=your-store-id
BTCPAY_API_KEY=your-api-key
BTCPAY_WEBHOOK_SECRET=your-webhook-secret

# Application Configuration
NEXT_PUBLIC_APP_URL=https://localhost:3443
NODE_ENV=development

🏗️ API Routes

🎯 Automatic Route Generation with Next.js Plugin

The library's Next.js plugin automatically generates all API routes for you:

// next.config.js
import { withLightning } from 'lightning-auth-and-payment/nextjs';

export default withLightning({
  // your existing config
});

✨ What Gets Generated Automatically

• /api/auth/lnurl - LNURL generation for Lightning wallets
• /api/auth/callback - Authentication callback handling
• /api/auth/status - Authentication status checking
• /api/auth/logout - User logout functionality
• /api/user - User data retrieval
• /api/payment/create-invoice - BTCPay Server invoice creation
• /api/payment/status - Payment status checking
• /api/webhooks/btcpay - BTCPay Server webhook handling

🎯 Benefits of Automatic Generation

• ✅ Zero boilerplate - No manual route creation needed
• ✅ Database integration - Works with Prisma out of the box
• ✅ BTCPay Server ready - Complete payment processing
• ✅ CORS handling - Pre-configured for Lightning wallets
• ✅ Error handling - Built-in status codes and error responses
• ✅ TypeScript support - Full type safety and IntelliSense
• ✅ Hot reload - Routes update automatically during development

🔧 Manual Route Creation (Advanced)

If you prefer manual control, you can still create routes manually:

// /api/auth/lnurl/route.ts - LNURL generation
import { NextRequest, NextResponse } from 'next/server';
import { handleLnurlRequest, getAuthCorsHeaders } from 'lightning-auth-and-payment';
import { lnurlStore } from '@/lib/lnurl-store';

export async function GET(request: NextRequest) {
  const result = await handleLnurlRequest(lnurlStore, request);
  const response = NextResponse.json(result);
  
  // Apply CORS headers
  const corsHeaders = getAuthCorsHeaders();
  Object.entries(corsHeaders).forEach(([key, value]) => {
    response.headers.set(key, value);
  });
  
  return response;
}

💳 Payment Routes

// Payment routes use BTCPay utilities
import { 
  handleBTCPayInvoiceCreation, 
  handleBTCPayInvoiceStatus,
  handleBTCPayWebhook 
} from 'lightning-auth-and-payment';

🔧 Development Server

Start the Lightning development server with HTTPS support:

npm run dev:lightning

This provides:

• ✅ HTTPS with trusted SSL certificates
• ✅ Wallet-compatible LNURL endpoints
• ✅ Hot reload and debugging
• ✅ Automatic certificate management

📱 Wallet Compatibility

Desktop Wallets

• Alby - Browser extension (recommended for development)
• Phoenix - Desktop Lightning wallet
• Breez - Mobile/desktop Lightning wallet

Mobile Wallets

• Phoenix - iOS/Android Lightning wallet
• Breez - Mobile Lightning wallet
• Zeus - Advanced Lightning wallet
• Wallet of Satoshi - Simple Lightning wallet

🎨 UI Components

Authentication Components

import { AuthHeader, useAuth } from 'lightning-auth-and-payment';

function MyApp() {
  const { isAuthenticated, login, logout } = useAuth();
  
  return (
    <AuthHeader 
      onLogin={login}
      onLogout={logout}
      isAuthenticated={isAuthenticated}
    />
  );
}

Payment Components

import { BTCPayPaymentModal } from 'lightning-auth-and-payment';

function PaymentButton() {
  const [showPayment, setShowPayment] = useState(false);
  
  return (
    <BTCPayPaymentModal
      isOpen={showPayment}
      onClose={() => setShowPayment(false)}
      amount={1000}
      description="Purchase item"
      onPaymentSuccess={() => {
        // Handle successful payment
        setShowPayment(false);
      }}
      autoCloseDelay={3000}
      successMessage="Payment confirmed!"
    />
  );
}

Utility Components

import { 
  Button, 
  Card, 
  Badge, 
  Dialog 
} from 'lightning-auth-and-payment';

// Pre-styled components with Lightning Network theming
<Button variant="primary">Lightning Button</Button>
<Card>Lightning Card</Card>
<Badge variant="success">Success</Badge>

🔍 Hooks

Authentication Hooks

import { 
  useLightningAuth,
  useSession 
} from 'lightning-auth-and-payment';

// Lightning authentication with all features
const { isAuthenticated, login, logout, user, isLoading } = useLightningAuth();

// Session management
const { session, refreshSession } = useSession();

Payment Hooks

import { 
  useBTCPayPayment,
  useLightningPayment 
} from 'lightning-auth-and-payment';

// BTCPay Server payments
const { 
  paymentState, 
  createInvoice, 
  copyBolt11 
} = useBTCPayPayment();

// Basic Lightning payments
const { 
  createPayment, 
  paymentStatus, 
  resetPayment 
} = useLightningPayment();

Utility Hooks

import { 
  useCopyToClipboard,
  useCountdown,
  useDebounce,
  useLocalStorage 
} from 'lightning-auth-and-payment';

// Copy to clipboard
const { copied, copy } = useCopyToClipboard();

// Countdown timer
const { timeLeft, isExpired } = useCountdown(targetDate);

// Debounced values
const debouncedValue = useDebounce(value, 500);

// Local storage
const [storedValue, setStoredValue] = useLocalStorage('key', defaultValue);

🏪 E-Commerce Features

import { 
  ECommerceManager,
  OrderManager,
  ProductManager 
} from 'lightning-auth-and-payment';

// E-commerce management
const ecommerce = new ECommerceManager();
const orders = new OrderManager();
const products = new ProductManager();

🧪 Testing

import { 
  createTestAuth,
  createTestStore,
  mockUser,
  mockInvoice 
} from 'lightning-auth-and-payment/testing';

// Test utilities
const testAuth = createTestAuth();
const testStore = createTestStore();
const user = mockUser();
const invoice = mockInvoice();

📚 Examples

Check out the examples directory for complete implementations:

• Next.js App Router - Modern Next.js 13+ with App Router
• Express.js - Traditional Express.js server
• E-commerce - Complete shopping cart implementation

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🆘 Support

• Documentation: AI Setup Guide
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🎯 Roadmap

• WebLN integration for browser wallets
• Lightning Address support
• Multi-currency support
• Advanced payment flows
• Mobile app templates

Built with ⚡ for the Lightning Network