IRC-kosmi-relay/AUTHENTICATION_STATUS.md

# Kosmi Authentication Status

## Current Status: ✅ Fully Automated

Authentication for the Kosmi bridge is **fully automated** using browser-based email/password login with automatic token refresh.

## Quick Start

### Option 1: Email/Password (Recommended - Fully Automated)

1. **Configure credentials** in `matterbridge.toml`:
   ```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`

The bot will automatically:
- Launch headless Chrome
- Log in to Kosmi
- Extract and use the JWT token
- Refresh the token automatically (checked daily)

See `BROWSER_AUTH_GUIDE.md` for detailed instructions.

### Option 2: Manual Token (Alternative)

If you prefer not to provide credentials:

1. **Log in to Kosmi** in your browser
2. **Extract your token**:
   - Open DevTools (F12) → Console tab
   - Run: `localStorage.getItem('token')`
   - Copy the token (without quotes)
3. **Add to config**:
   ```toml
   [kosmi.hyperspaceout]
   RoomURL="https://app.kosmi.io/room/@hyperspaceout"
   Token="your-token-here"
   ```
4. **Run the bot**: `./irc-kosmi-relay -conf matterbridge.toml`

See `QUICK_START_TOKEN.md` for detailed instructions.

## Authentication Methods

### ✅ Email/Password (RECOMMENDED)
- **Status**: Working - Fully Automated
- **Setup**: Provide email and password in config
- **Pros**: Fully automated, auto-refresh, no manual intervention
- **Cons**: Requires Chrome/Chromium, credentials in config file
- **Use Case**: Production use
- **Details**: See `BROWSER_AUTH_GUIDE.md`

### ✅ Manual Token (Alternative)
- **Status**: Working
- **Setup**: Extract token from browser localStorage
- **Pros**: Simple, no browser required, no credentials in config
- **Cons**: Manual process, token expires after ~1 year
- **Use Case**: When Chrome is not available or preferred
- **Details**: See `QUICK_START_TOKEN.md`

### ✅ Anonymous Login
- **Status**: Working
- **Setup**: Leave both `Email` and `Token` fields empty
- **Pros**: No configuration needed
- **Cons**: Limited permissions, can't access private rooms
- **Use Case**: Testing, public rooms

## Technical Details

### How It Works
1. User provides JWT token in configuration
2. Bot uses token directly for WebSocket authentication
3. Token is sent in `connection_init` payload
4. Kosmi validates token and establishes authenticated session

### Token Format
- **Algorithm**: HS512
- **Expiry**: ~1 year from issue
- **Storage**: Browser localStorage with key `"token"`
- **Format**: Standard JWT (header.payload.signature)

### Token Payload Example
```json
{
  "aud": "kosmi",
  "exp": 1793465205,
  "iat": 1762015605,
  "iss": "kosmi",
  "jti": "1c7f9db8-9a65-4909-92c0-1c646103bdee",
  "nbf": 1762015604,
  "sub": "4ec0b428-712b-49d6-8551-224295 45d29b",
  "typ": "access"
}
```

## Troubleshooting

### Bot connects anonymously instead of using token
- Check token is correctly copied (no quotes, no extra spaces)
- Verify `Token=""` line is not commented out
- Check logs for "Using provided authentication token"

### Connection fails with token
- Token may be expired - extract a new one
- Verify you're logged in to correct Kosmi account
- Check token format is valid JWT

### How to check token expiry
```bash
# Decode token at https://jwt.io
# Or use command line:
echo "your-token" | cut -d'.' -f2 | base64 -d | jq .exp | xargs -I {} date -r {}
```

## Implementation Files

### Core Implementation
- `bridge/kosmi/graphql_ws_client.go` - WebSocket client with token support
- `bridge/kosmi/kosmi.go` - Bridge integration and config handling
- `bridge/kosmi/auth.go` - Auth manager (for future email/password support)

### Configuration
- `matterbridge.toml` - Main config with Token field
- `test-token-config.toml` - Example test configuration

### Documentation
- `QUICK_START_TOKEN.md` - User guide for manual token setup
- `AUTH_DISCOVERY.md` - Technical investigation details
- `chat-summaries/auth-discovery-2025-11-01-16-48.md` - Session summary

### Testing Tools
- `cmd/test-introspection/main.go` - GraphQL schema introspection
- `cmd/test-login/main.go` - Test login mutations
- `cmd/monitor-auth/main.go` - Browser automation for traffic capture

## Future Enhancements

### Possible Improvements
1. **Automatic Token Extraction**: Browser automation to extract token
2. **Token Refresh**: Implement if refresh mechanism is discovered
3. **Email/Password**: Deep reverse engineering of Kosmi's auth
4. **Token Expiry Warning**: Alert user when token is about to expire

### Priority
- **Low**: Current solution works well for most use cases
- **Revisit**: If Kosmi adds official bot API or auth documentation

## Security Considerations

### Token Storage
- Tokens are stored in plain text in `matterbridge.toml`
- Ensure config file has appropriate permissions (chmod 600)
- Do not commit config with real tokens to version control

### Token Sharing
- Each token is tied to a specific user account
- Do not share tokens between users
- Revoke token by logging out in browser if compromised

### Best Practices
1. Use dedicated bot account for token
2. Limit bot account permissions in Kosmi
3. Rotate tokens periodically (even though they last 1 year)
4. Monitor bot activity for unusual behavior

## Support

### Getting Help
1. Check `QUICK_START_TOKEN.md` for setup instructions
2. Review `AUTH_DISCOVERY.md` for technical details
3. Check logs for error messages
4. Verify token is valid and not expired

### Reporting Issues
If you encounter problems:
1. Check token expiry
2. Verify configuration format
3. Review bot logs for errors
4. Try extracting a fresh token

## Conclusion

Manual token provision provides a **reliable and simple** authentication method for the Kosmi bridge. While not as automated as email/password would be, it:
- Works immediately
- Requires minimal maintenance (tokens last ~1 year)
- Has no external dependencies
- Is easy to troubleshoot

For most users, this is the recommended authentication method.