web-app/docs/02-modules/chat-module/integration.md

Nostr Chat Integration for Web-App

This document describes the Nostr chat integration that allows LNBits users to chat with each other using Nostr relays.

Overview

The chat system integrates with the LNBits user system and Nostr relays to provide encrypted messaging between users. Each user has a Nostr keypair (stored in pubkey and prvkey fields) that enables secure communication.

Navigation Integration

The chat feature is accessible through the main navigation menu:

• Desktop: Chat link appears in the top navigation bar with a message icon
• Mobile: Chat link appears in the mobile menu with a message icon
• Route: /chat - Accessible to authenticated users only

Components

1. ChatComponent.vue

Location: src/components/nostr/ChatComponent.vue

A Vue component that provides the chat interface with:

• Peer list populated from LNBits users
• Real-time messaging using Nostr relays
• Encrypted message exchange
• Connection status indicators

2. ChatService

Location: src/modules/chat/services/chat-service.ts

A service-based architecture that handles:

• Nostr relay connections via dependency injection
• Message encryption/decryption
• User authentication through AuthService
• Real-time message subscription
• Integration with modular service architecture

3. ChatPage.vue

Location: src/pages/ChatPage.vue

A page that integrates the chat component into the web-app.

4. Navigation Integration

Location: src/components/layout/Navbar.vue

The chat link has been added to the main navigation with:

• Message icon for visual identification
• Internationalization support (English, Spanish, French)
• Responsive design for desktop and mobile

API Endpoints

Get Current User

GET /users/api/v1/user/me
Authorization: Bearer <admin_token>

Response:
{
  "id": "user_id",
  "username": "username",
  "email": "email@example.com",
  "pubkey": "nostr_public_key",
  "prvkey": "nostr_private_key_hex",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Get All User Public Keys

GET /users/api/v1/nostr/pubkeys
Authorization: Bearer <admin_token>

Response:
[
  {
    "user_id": "user_id",
    "username": "username",
    "pubkey": "nostr_public_key"
  }
]

Features

1. User Integration

• Automatically loads peers from LNBits user database via dependency injection
• Uses existing pubkey and prvkey fields from AuthService
• Authentication managed through centralized AuthService
• No dual authentication issues - single source of truth

2. Nostr Relay Integration

• Connects to multiple Nostr relays for redundancy
• Real-time message delivery
• Encrypted end-to-end messaging

3. UI Features

• Peer list with user avatars and names
• Real-time message display
• Connection status indicators
• Message timestamps
• Auto-scroll to latest messages

4. Mobile-Responsive Design

• Mobile-first approach: Optimized for touch interactions
• Peer list view: Shows only peers list on mobile until a peer is selected
• Full-width chat view: When a peer is selected, switches to full-width chat
• Back button: Easy navigation back to peers list
• Touch-friendly: Larger touch targets and proper touch feedback
• Responsive avatars: Larger avatars on mobile for better visibility
• Message bubbles: Optimized width (75% max) for mobile readability
• Keyboard-friendly: Input stays visible when keyboard appears

5. Navigation Features

• Integrated into main navigation menu
• Message icon for easy identification
• Multi-language support
• Responsive design for all devices

Security

1. Encryption: All messages are encrypted using NIP-04 (Nostr encrypted direct messages)
2. Private Key Access: Only admin users can access private keys for messaging
3. Relay Security: Messages are distributed across multiple relays for redundancy
4. User Authentication: Requires LNBits authentication to access chat

Setup Requirements

1. NostrTools: The web-app needs NostrTools loaded globally
2. Admin Access: Users need admin privileges to access private keys
3. Relay Configuration: Default relays are configured in the composable
4. LNBits Integration: Requires the updated LNBits API endpoints

Usage

1. Navigate to /chat in the web-app (or click "Chat" in the navigation)
2. The system will automatically load peers from LNBits
3. Select a peer to start chatting
4. Messages are encrypted and sent via Nostr relays

Configuration

Default Relays

The system connects to these relays by default:

• wss://nostr.atitlan.io
• wss://relay.damus.io
• wss://nos.lol

Relay Configuration

You can modify the relays in useNostrChat.ts:

const DEFAULT_RELAYS: NostrRelayConfig[] = [
  { url: 'wss://your-relay.com', read: true, write: true }
]

Future Enhancements

1. Message Persistence: Store messages locally for offline access
2. File Sharing: Support for encrypted file sharing
3. Group Chats: Multi-user encrypted conversations
4. Message Search: Search through conversation history
5. Push Notifications: Real-time notifications for new messages
6. Profile Integration: Display user profiles and avatars
7. Message Reactions: Support for message reactions and replies

Troubleshooting

Common Issues

1. Connection Failed: Check relay availability and network connectivity
2. Messages Not Sending: Verify user has admin privileges and private key access
3. Peers Not Loading: Check LNBits API endpoint and authentication
4. Encryption Errors: Ensure NostrTools is properly loaded

Debug Information

The chat component logs detailed information to the console:

• Connection status
• Message encryption/decryption
• Relay connection attempts
• API call results

Dependencies

• NostrTools: For Nostr protocol implementation
• Vue 3: For reactive UI components
• LNBits API: For user management and authentication
• Nostr Relays: For message distribution