Move troubleshooting and implementation docs to docs/
Relocate 30 non-essential .md files (investigation notes, fix summaries, implementation details, status reports) from the project root into docs/ to reduce clutter. Core operational docs (README, quickstart guides, configuration references) remain in the root. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cottongin
195
docs/AUTHENTICATION_STATUS.md
Normal file
195
docs/AUTHENTICATION_STATUS.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user