Nostr_Login_Lite

API

Complete configuration showing all available options:

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:

// 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:

// 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:

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).