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

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