c88b75f30d
Rewrite README.md and all setup guides to reflect the current native GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket interception descriptions). Add new docs/IRC.md with complete IRC command reference, vote syntax, and ticker symbol table. Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move historical development notes from docs/ root into docs/archive/. Co-authored-by: Cursor <cursoragent@cursor.com>
161 lines
4.0 KiB
Markdown
161 lines
4.0 KiB
Markdown
# 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`:
|
|
|
|
```toml
|
|
[kosmi.hyperspaceout]
|
|
RoomURL="https://app.kosmi.io/room/@yourroom"
|
|
Email="your-email@example.com"
|
|
Password="your-password"
|
|
```
|
|
|
|
### 2. Run the Bot
|
|
|
|
```bash
|
|
./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)
|
|
|
|
```toml
|
|
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)
|
|
|
|
```toml
|
|
# 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](TOKEN_PERSISTENCE.md) for full details on caching.
|
|
|
|
## Requirements
|
|
|
|
### Chrome/Chromium
|
|
|
|
Must be installed and in PATH:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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)
|
|
```
|