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:

```env
# 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:

```typescript
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:

```typescript
// 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.