IRC-kosmi-relay/BROWSER_AUTH_GUIDE.md

Browser-Based Authentication Guide

Overview

The Kosmi bridge now supports fully automated email/password authentication using headless Chrome via chromedp. No manual token extraction needed!

Quick Start

1. Configure Email/Password

Edit matterbridge.toml:

[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
Email="your-email@example.com"
Password="your-password"

2. Run the Bot

./irc-kosmi-relay -conf matterbridge.toml

That's it! The bot will:

1. Launch headless Chrome
2. Navigate to Kosmi
3. Log in with your credentials
4. Extract the JWT token from localStorage
5. Use the token for authenticated connections
6. Automatically refresh the token daily (checks for expiry 7 days in advance)

How It Works

Initial Login

When you start the bot with Email/Password configured:

1. Browser Launch: Headless Chrome starts (no visible window)
2. Navigation: Goes to https://app.kosmi.io
3. Login Flow:
   • Clicks "Login" button
   • Clicks "Login with Email"
   • Fills in email and password
   • Submits the form
4. Token Extraction: Reads localStorage.getItem('token')
5. Token Parsing: Extracts expiry time from JWT
6. Connection: Uses token for WebSocket authentication

Automatic Token Refresh

• Daily Check: Every 24 hours, the bot checks if the token is still valid
• Expiry Buffer: Refreshes 7 days before expiration
• Seamless: Happens in the background without disconnecting
• Logging: You'll see "Checking token expiry..." in debug logs

Requirements

System Requirements

• Chrome/Chromium: Must be installed on your system
  • macOS: Usually pre-installed or via Homebrew: brew install chromium
  • Linux: sudo apt install chromium-browser or sudo yum install chromium
  • Windows: Download from https://www.chromium.org/getting-involved/download-chromium/

Go Dependencies

• github.com/chromedp/chromedp - Automatically installed with go get

Configuration Options

Option 1: Email/Password (Recommended)

Email="your-email@example.com"
Password="your-password"

• ✅ Fully automated
• ✅ Auto-refresh
• ✅ No manual intervention
• ⚠️ Requires Chrome/Chromium
• ⚠️ Stores credentials in config file

Option 2: Manual Token

Token="eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."

• ✅ No browser required
• ✅ No credentials in config
• ❌ Manual extraction needed
• ❌ Must update when expired (~1 year)

Option 3: Anonymous

# Leave both empty
Email=""
Password=""
Token=""

• ✅ No setup needed
• ❌ Limited permissions
• ❌ Can't access private rooms

Troubleshooting

"Browser automation failed"

Possible causes:

1. Chrome/Chromium not installed
2. Chrome/Chromium not in PATH
3. Network issues
4. Kosmi website changed

Solutions:

# Check if Chrome is installed
which chromium || which google-chrome || which chrome

# Install Chrome (macOS)
brew install chromium

# Install Chrome (Ubuntu/Debian)
sudo apt install chromium-browser

# Install Chrome (CentOS/RHEL)
sudo yum install chromium

"No token found in localStorage after login"

Possible causes:

1. Login failed (wrong credentials)
2. Kosmi's login flow changed
3. Page didn't fully load

Solutions:

• Verify credentials are correct
• Check bot logs for detailed error messages
• Try manual token extraction as fallback

"Token expired or expiring soon"

This is normal! The bot will automatically refresh the token. If refresh fails:

• Check Chrome is still installed
• Check network connectivity
• Restart the bot to force a fresh login

Headless Chrome Issues

If you see Chrome-related errors:

# Set environment variable for debugging
export CHROMEDP_DISABLE_GPU=1

# Or run with visible browser (for debugging)
export CHROMEDP_NO_HEADLESS=1

Security Considerations

Credential Storage

• Credentials are stored in plain text in matterbridge.toml
• Ensure config file has restrictive permissions:

  chmod 600 matterbridge.toml
  

• Do not commit config with real credentials to version control
• Consider using environment variables:

  export KOSMI_EMAIL="your-email@example.com"
  export KOSMI_PASSWORD="your-password"
  

Browser Automation

• Headless Chrome runs with minimal privileges
• No data is stored or cached
• Browser closes immediately after token extraction
• Token is kept in memory only

Token Security

• Tokens are JWT (JSON Web Tokens) signed by Kosmi
• Valid for ~1 year
• Can be revoked by logging out in browser
• Treat tokens like passwords

Advanced Configuration

Custom Chrome Path

If Chrome is installed in a non-standard location:

// In browser_auth.go, modify NewContext call:
opts := append(chromedp.DefaultExecAllocatorOptions[:],
    chromedp.ExecPath("/path/to/chrome"),
)
ctx, cancel := chromedp.NewExecAllocator(context.Background(), opts...)

Timeout Adjustment

If login takes longer than 60 seconds:

// In browser_auth.go, modify timeout:
ctx, cancel = context.WithTimeout(ctx, 120*time.Second)

Refresh Interval

To check token more/less frequently:

// In kosmi.go, modify ticker:
ticker := time.NewTicker(12 * time.Hour) // Check twice daily

Comparison with Manual Token

Feature	Browser Auth	Manual Token
Setup Complexity	Easy	Medium
Automation	Full	None
Token Refresh	Automatic	Manual
Dependencies	Chrome	None
Security	Credentials in config	Token in config
Maintenance	Low	Medium

Logs to Expect

Successful Login

INFO Using browser automation for email/password authentication
INFO Obtaining authentication token via browser automation...
INFO ✅ Successfully obtained token via browser automation
INFO Token expires in: 365d
INFO ✅ Browser authentication successful
INFO Successfully connected to Kosmi

Daily Token Check

DEBUG Checking token expiry...
DEBUG Token check complete

Token Refresh (when expiring)

INFO Token expired or expiring soon, will refresh
INFO Obtaining authentication token via browser automation...
INFO ✅ Successfully obtained token via browser automation
INFO Token expires in: 365d

Migration from Manual Token

If you're currently using manual token:

1. Add credentials to config:

   Email="your-email@example.com"
   Password="your-password"
   

2. Remove or comment out Token:

   #Token="..."
   

3. Restart the bot

The bot will automatically switch to browser-based auth!

Performance Impact

• Initial Login: ~5-10 seconds (one-time per start)
• Token Refresh: ~5-10 seconds (once per year, or when expiring)
• Daily Check: <1ms (just checks expiry time)
• Memory: +50-100MB during browser operation (released after)
• CPU: Minimal (browser runs briefly)

Conclusion

Browser-based authentication provides the best balance of:

• ✅ Full automation
• ✅ Reliable token refresh
• ✅ Simple configuration
• ✅ Low maintenance

For production use, this is the recommended authentication method.