HyperSpaceOut/IRC-kosmi-relay
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive documentation overhaul

Browse Source 
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>
This commit is contained in:
cottongin
2026-05-12 22:01:25 -04:00
parent 4188ae29af
commit c88b75f30d
57 changed files with 4530 additions and 1994 deletions
Download Patch File Download Diff File Expand all files Collapse all files

315
docs/setup/BROWSER_AUTH_GUIDE.md
View File

@@ -1,277 +1,160 @@
# 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!
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/@hyperspaceout"
RoomURL="https://app.kosmi.io/room/@yourroom"
Email="your-email@example.com"
Password="your-password"
```
### 2. Run the Bot
```bash
./irc-kosmi-relay -conf matterbridge.toml
./matterbridge -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)
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
## How It Works
## Authentication Modes
### 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
### Option 1: Email/Password (Recommended for Authenticated Access)
### 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)
```toml
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
```toml
Token="eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
```
- ✅ No browser required
- ✅ No credentials in config
- ❌ Manual extraction needed
- ❌ Must update when expired (~1 year)
- 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)
### Option 3: Anonymous
```toml
# Leave both empty
# Leave both empty or omit entirely
Email=""
Password=""
Token=""
```
- ✅ No setup needed
- ❌ Limited permissions
- ❌ Can't access private rooms
- 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"
**Possible causes:**
1. Chrome/Chromium not installed
2. Chrome/Chromium not in PATH
3. Network issues
4. Kosmi website changed
### "Browser automation failed" or "authentication failed"
**Solutions:**
```bash
# Check if Chrome is installed
which chromium || which google-chrome || which chrome
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
# Install Chrome (macOS)
brew install chromium
### Token cache not persisting (Docker)
# Install Chrome (Ubuntu/Debian)
sudo apt install chromium-browser
- 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`
# 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:
### Force token refresh
```bash
# Set environment variable for debugging
export CHROMEDP_DISABLE_GPU=1
# Local
rm ~/.matterbridge/kosmi_token_cache.json
./matterbridge -conf matterbridge.toml
# Or run with visible browser (for debugging)
export CHROMEDP_NO_HEADLESS=1
# Docker
rm ./data/kosmi_token_cache.json
docker-compose restart
```
## Security Considerations
### Credential Storage
- Credentials are stored in **plain text** in `matterbridge.toml`
- Ensure config file has restrictive permissions:
- Credentials are stored in **plain text** in `matterbridge.toml` -- restrict permissions:
```bash
chmod 600 matterbridge.toml
```
- Do not commit config with real credentials to version control
- Consider using environment variables:
```bash
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:
```go
// 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:
```go
// In browser_auth.go, modify timeout:
ctx, cancel = context.WithTimeout(ctx, 120*time.Second)
```
### Refresh Interval
To check token more/less frequently:
```go
// 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 |
- 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
### Successful Login
### First run (no cache)
```
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 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
```
### Daily Token Check
### Subsequent runs (cached token)
```
DEBUG Checking token expiry...
DEBUG Token check complete
INFO ✅ Using cached token (expires in 8736h)
INFO Successfully connected to Kosmi
```
### Token Refresh (when expiring)
### Token refresh (near expiry)
```
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
INFO Cached token expires soon, will refresh
INFO Authenticating with email/password...
INFO ✅ Authentication successful
INFO 💾 Token cached (expires in 8760h)
```
## Migration from Manual Token
If you're currently using manual token:
1. **Add credentials** to config:
```toml
Email="your-email@example.com"
Password="your-password"
```
2. **Remove or comment out Token**:
```toml
#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**.