sync

QUICK_START_AUTH.md

@@ -0,0 +1,94 @@
+# Quick Start: Testing Authentication
+
+## Step 1: Create Bot Account
+
+1. Go to https://app.kosmi.io
+2. Sign up with a dedicated email (e.g., `your-bot@example.com`)
+3. Choose a display name (e.g., "HSO Relay Bot")
+4. Save the credentials securely
+
+## Step 2: Test with Monitor Script
+
+```bash
+cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
+
+# Run monitor in login mode
+./bin/monitor-auth -login
+
+# In the browser that opens:
+# 1. Log in with your bot credentials
+# 2. Navigate to a room
+# 3. Press Ctrl+C to stop
+
+# Review the captured data
+cat auth-monitor.log | grep -A 5 "login"
+```
+
+## Step 3: Configure Matterbridge
+
+Edit `matterbridge.toml`:
+
+```toml
+[kosmi.hyperspaceout]
+RoomURL="https://app.kosmi.io/room/@hyperspaceout"
+Email="your-bot@example.com"
+Password="your-secure-password"
+```
+
+## Step 4: Test Connection
+
+```bash
+# Build the bridge
+go build
+
+# Run with your config
+./matterbridge -conf matterbridge.toml
+
+# Watch the logs for:
+# - "Using authenticated connection"
+# - "Logged in as: HSO Relay Bot"
+# - "Successfully connected to Kosmi"
+```
+
+## Verification Checklist
+
+- [ ] Bot account created manually
+- [ ] Credentials documented securely
+- [ ] Monitor script captured login flow
+- [ ] Config file updated with credentials
+- [ ] Bridge logs show authenticated connection
+- [ ] Bot display name appears correctly in chat
+- [ ] Messages relay successfully
+
+## Troubleshooting
+
+### Wrong account logged in
+
+Check the log for "Logged in as: {name}". If it doesn't match your bot:
+- Verify email/password in config
+- Check for typos
+- Ensure you're using the correct credentials
+
+### Anonymous connection despite credentials
+
+Check that both Email AND Password are set:
+```bash
+grep -A 2 "Email=" matterbridge.toml
+```
+
+### Token expired
+
+The bridge should auto-refresh. If not:
+- Check logs for "Token refresh failed"
+- Verify credentials are still valid
+- Try manual login at app.kosmi.io
+
+## Next Steps
+
+Once authenticated connection works:
+- Test reconnection (simulate network failure)
+- Monitor for token refresh (wait 24 hours)
+- Test with multiple rooms
+- Set up as systemd service
+
+See the monitoring script output and logs for detailed information about Kosmi's authentication behavior.