IRC-kosmi-relay/docs/setup/BROWSER_AUTH_GUIDE.md

Browser-Based Authentication Guide

Overview

The Kosmi bridge supports email/password authentication using headless Chrome (chromedp). This is only needed if you want to connect with a specific Kosmi account instead of anonymous access. The JWT obtained via browser login is cached on disk, so the browser is only launched when needed.

Quick Start

1. Configure Email/Password

Edit matterbridge.toml:

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

2. Run the Bot

./matterbridge -conf matterbridge.toml

The bot will:

1. Check for a cached token in the data directory
2. If no valid cache exists, launch headless Chrome
3. Navigate to Kosmi and log in with your credentials
4. Extract the JWT from localStorage
5. Cache the token for future use
6. Connect to Kosmi with the authenticated token

Authentication Modes

Option 1: Email/Password (Recommended for Authenticated Access)

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

• Fully automated with token caching
• Browser only launches when cache is missing or expired
• Token refreshes automatically before expiry (7-day buffer)
• Requires Chrome/Chromium installed

Option 2: Anonymous (Default)

# Leave both empty or omit entirely
Email=""
Password=""

• No setup needed, no browser required
• Connects with an anonymous Kosmi identity
• Cannot access private rooms

Token Caching

Authenticated tokens are cached to avoid launching Chrome on every startup:

• Docker: ./data/kosmi_token_cache.json (via MATTERBRIDGE_DATA_DIR=/app/data)
• Local: ~/.matterbridge/kosmi_token_cache.json

On startup, the bridge:

1. Loads the cached token
2. If valid (and not expiring within 7 days), uses it directly -- no browser
3. If expired or expiring soon, performs browser authentication
4. Saves the new token to cache

Kosmi JWT tokens are valid for approximately 1 year.

See TOKEN_PERSISTENCE.md for full details on caching.

Requirements

Chrome/Chromium

Must be installed and in PATH:

# macOS
brew install --cask chromium

# Ubuntu/Debian
sudo apt install chromium-browser

# Verify
which chromium chromium-browser google-chrome

In Docker, Chromium is pre-installed in the image.

Troubleshooting

"Browser automation failed" or "authentication failed"

1. Check Chrome/Chromium is installed and accessible
2. Verify credentials by logging in manually at app.kosmi.io
3. Delete the cached token to force fresh auth: rm data/kosmi_token_cache.json
4. Enable debug logging for detailed browser automation output

Token cache not persisting (Docker)

• Verify the ./data volume mount exists in docker-compose.yml
• Check directory permissions: ls -la ./data/
• Confirm MATTERBRIDGE_DATA_DIR is set to /app/data

Force token refresh

# Local
rm ~/.matterbridge/kosmi_token_cache.json
./matterbridge -conf matterbridge.toml

# Docker
rm ./data/kosmi_token_cache.json
docker-compose restart

Security Considerations

• Credentials are stored in plain text in matterbridge.toml -- restrict permissions:

  chmod 600 matterbridge.toml
  

• Do not commit config files with real credentials to version control
• The cached token file has restricted permissions (0600)
• Headless Chrome runs briefly and closes after token extraction
• Tokens can be revoked by logging out in a browser

Logs to Expect

First run (no cache)

INFO No cached token found, performing authentication...
INFO Authenticating with email/password...
INFO ✅ Authentication successful
INFO 💾 Token cached (expires in 8760h)
INFO Successfully connected to Kosmi

Subsequent runs (cached token)

INFO ✅ Using cached token (expires in 8736h)
INFO Successfully connected to Kosmi

Token refresh (near expiry)

INFO Cached token expires soon, will refresh
INFO Authenticating with email/password...
INFO ✅ Authentication successful
INFO 💾 Token cached (expires in 8760h)