136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
Nostr_Login_Lite
|
|
===========
|
|
|
|
## API
|
|
|
|
Complete configuration showing all available options:
|
|
|
|
```javascript
|
|
await window.NOSTR_LOGIN_LITE.init({
|
|
// Theme configuration
|
|
theme: 'default', // 'default' | 'dark' | custom theme name
|
|
|
|
// 🔐 Authentication persistence configuration
|
|
persistence: true, // Enable persistent authentication (default: true)
|
|
isolateSession: false, // Use sessionStorage for per-tab isolation (default: false = localStorage)
|
|
|
|
// Relay configuration
|
|
relays: ['wss://relay.damus.io', 'wss://nos.lol'],
|
|
|
|
// Authentication methods
|
|
methods: {
|
|
extension: true, // Browser extensions (Alby, nos2x, etc.)
|
|
local: true, // Manual key entry & generation
|
|
readonly: true, // Read-only mode (no signing)
|
|
connect: true, // NIP-46 remote signers
|
|
otp: false // OTP/DM authentication (not implemented yet)
|
|
},
|
|
|
|
// Floating tab configuration
|
|
floatingTab: {
|
|
enabled: true, // Show/hide floating login tab
|
|
hPosition: 0.95, // 0.0 = left edge, 1.0 = right edge
|
|
vPosition: 0.1, // 0.0 = top edge, 1.0 = bottom edge
|
|
offset: { x: 0, y: 0 }, // Fine-tune positioning (pixels)
|
|
|
|
appearance: {
|
|
style: 'pill', // 'pill' | 'square' | 'circle'
|
|
theme: 'auto', // 'auto' | 'light' | 'dark'
|
|
icon: '[LOGIN]', // Text-based icon
|
|
text: 'Sign In', // Button text
|
|
iconOnly: false // Show icon only (no text)
|
|
},
|
|
|
|
behavior: {
|
|
hideWhenAuthenticated: false, // Keep visible after login
|
|
showUserInfo: true, // Show user info when authenticated
|
|
autoSlide: true, // Slide animation on hover
|
|
persistent: false // Persist across page reloads
|
|
}
|
|
}
|
|
});
|
|
|
|
// Control Methods
|
|
NOSTR_LOGIN_LITE.launch(); // Open login modal
|
|
NOSTR_LOGIN_LITE.logout(); // Clear authentication state
|
|
NOSTR_LOGIN_LITE.switchTheme('dark'); // Change theme
|
|
NOSTR_LOGIN_LITE.showFloatingTab(); // Show floating tab
|
|
NOSTR_LOGIN_LITE.hideFloatingTab(); // Hide floating tab
|
|
NOSTR_LOGIN_LITE.updateFloatingTab(options); // Update floating tab options
|
|
NOSTR_LOGIN_LITE.toggleFloatingTab(); // Toggle floating tab visibility
|
|
|
|
// Get Authentication State (Single Source of Truth)
|
|
const authState = NOSTR_LOGIN_LITE.getAuthState();
|
|
const isAuthenticated = !!authState;
|
|
const userInfo = authState; // Contains { method, pubkey, etc. }
|
|
```
|
|
|
|
**Authentication Persistence:**
|
|
|
|
Two-tier configuration system:
|
|
|
|
1. **`persistence: boolean`** - Master switch for authentication persistence
|
|
- `true` (default): Save authentication state for automatic restore
|
|
- `false`: No persistence - user must login fresh every time
|
|
|
|
2. **`isolateSession: boolean`** - Storage location when persistence is enabled
|
|
- `false` (default): Use localStorage - shared across tabs/windows
|
|
- `true`: Use sessionStorage - isolated per tab/window
|
|
|
|
**Use Cases for Session Isolation (`isolateSession: true`):**
|
|
- Multi-tenant applications where different tabs need different users
|
|
- Testing environments requiring separate authentication per tab
|
|
- Privacy-focused applications that shouldn't share login state across tabs
|
|
|
|
## Embedded Modal API
|
|
|
|
Embed login interface directly into page element:
|
|
|
|
```javascript
|
|
// Initialize library first
|
|
await NOSTR_LOGIN_LITE.init({
|
|
methods: {
|
|
extension: true,
|
|
local: true,
|
|
readonly: true
|
|
}
|
|
});
|
|
|
|
// Embed into container
|
|
const modal = NOSTR_LOGIN_LITE.embed('#login-container', {
|
|
title: 'Login',
|
|
showHeader: true,
|
|
seamless: false // true = no borders/shadows, blends into page
|
|
});
|
|
```
|
|
|
|
Container can be CSS selector or DOM element. Modal renders inline without backdrop overlay.
|
|
|
|
## Logout API
|
|
|
|
To log out users and clear authentication state:
|
|
|
|
```javascript
|
|
// Unified logout method - works for all authentication methods
|
|
window.NOSTR_LOGIN_LITE.logout();
|
|
```
|
|
|
|
This will:
|
|
- Clear persistent authentication data from localStorage
|
|
- Dispatch `nlLogout` event for custom cleanup
|
|
- Reset the authentication state across all components
|
|
|
|
### Event Handling
|
|
|
|
Listen for logout events in your application:
|
|
|
|
```javascript
|
|
window.addEventListener('nlLogout', () => {
|
|
console.log('User logged out');
|
|
// Clear your application's UI state
|
|
// Redirect to login page, etc.
|
|
});
|
|
```
|
|
|
|
The logout system works consistently across all authentication methods (extension, local keys, NIP-46, etc.) and all UI components (floating tab, modal, embedded).
|