web-app/docs/03-core-services/authentication.md

Authentication System

This web application now uses LNBits username/password authentication instead of Nostr keypairs.

Overview

The authentication system has been completely replaced with a traditional username/password system that integrates with LNBits. Users can now:

• Register new accounts with username and password
• Login with username/email and password
• Manage their profile information
• Logout securely

Configuration

Environment Variables

Create a .env file in the web-app directory with the following variables:

# LNBits Base URL Configuration
# Set this to your LNBits instance base URL
# Example: http://localhost:5000 or https://your-lnbits-instance.com
VITE_LNBITS_BASE_URL=http://localhost:5000

# Enable debug logging for LNBits API calls
VITE_LNBITS_DEBUG=false

# App Configuration
VITE_APP_TITLE=Ario
VITE_APP_DESCRIPTION=Your secure platform for events and community management

LNBits Setup

1. Ensure your LNBits instance is running and accessible
2. Make sure the username/password authentication method is enabled in LNBits
3. Configure CORS if your LNBits instance is on a different domain

API Endpoints

The application uses the following LNBits API endpoints:

• POST /api/v1/auth - Login
• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/logout - Logout
• GET /api/v1/auth - Get current user
• PUT /api/v1/auth/password - Update password
• PUT /api/v1/auth/update - Update profile

Components

New Components

• LoginDialog.vue - Modal dialog for login/register
• UserProfile.vue - Display user information and logout
• Login.vue - Full-page login/register form

Updated Components

• App.vue - Now uses new authentication system
• Navbar.vue - Shows user status and logout option
• Home.vue - Displays welcome message and user profile

Authentication Flow

1. App Initialization: The app checks for existing authentication token on startup
2. Route Protection: Routes with requiresAuth: true redirect to login if not authenticated
3. Login/Register: Users can create accounts or login with existing credentials
4. Token Management: Access tokens are stored in localStorage and automatically included in API requests
5. Logout: Clears tokens and redirects to login page

Security Features

• JWT tokens for session management
• Secure password handling (handled by LNBits)
• Automatic token refresh
• Route protection for authenticated pages
• Secure logout with token cleanup

Architecture

The authentication system uses a dependency injection pattern for clean modular architecture:

Core Components

1. AuthService (src/modules/base/auth/auth-service.ts)

   • Singleton service that manages authentication state
   • Handles API calls to LNBits
   • Provides reactive state management

2. useAuthService (src/composables/useAuthService.ts)

   • Wrapper composable that provides unified access to AuthService
   • Uses dependency injection to access the service
   • Provides consistent API for all components

3. Dependency Injection Container (src/core/di-container.ts)

   • Manages service registration and injection
   • Ensures single source of truth across modules

Usage Pattern

Components access authentication through the useAuth() composable:

import { useAuth } from '@/composables/useAuthService'

export default defineComponent({
  setup() {
    const auth = useAuth()
    
    // Access authentication state
    const isAuthenticated = auth.isAuthenticated
    const currentUser = auth.currentUser
    
    // Call authentication methods
    const login = (credentials) => auth.login(credentials)
    const logout = () => auth.logout()
    
    return {
      isAuthenticated,
      currentUser,
      login,
      logout
    }
  }
})

Service Registration

The AuthService is registered in the base module and made available through dependency injection:

// In base module
container.provide(SERVICE_TOKENS.AUTH_SERVICE, authService)

// In components 
const authService = injectService(SERVICE_TOKENS.AUTH_SERVICE)

Migration from Legacy Architecture

The following components have been updated:

• Legacy: Global useAuth.ts composable → Current: useAuthService.ts with dependency injection
• Legacy: Direct service imports → Current: Dependency injection pattern
• Legacy: Dual authentication detection → Current: Single source of truth via AuthService
• IdentityDialog.vue → LoginDialog.vue
• PasswordDialog.vue → Integrated into LoginDialog.vue
• Nostr connection status → User authentication status

Development

To run the application with the new authentication system:

1. Set up your LNBits instance
2. Configure the environment variables
3. Run the development server: npm run dev
4. Access the application and test login/register functionality

Troubleshooting

Common Issues

1. CORS Errors: Ensure your LNBits instance allows requests from your frontend domain
2. Authentication Failures: Check that username/password auth is enabled in LNBits
3. API Connection: Verify the VITE_LNBITS_BASE_URL is correct and points to your LNBits instance (without /api/v1)

Debug Mode

Enable debug logging by setting VITE_LNBITS_DEBUG=true to see detailed API request/response information in the browser console.