@spectrumsense/spectrum-chat-dev

# Security Testing Guide **Test Date:** October 6, 2025 **Configuration:** - API URL: `http://localhost:8000` - Site Key: `pub_bright_spectrum_htlzbncn` - Organization: BrightSpectrum (default demo) --- ## 🚀 Quick Start ### 1. Prerequisites ✅ **API Server Running** ```bash # Make sure your API is running on http://localhost:8000 # The API should have the following configured: # - Organization: BrightSpectrum # - Site Key: pub_bright_spectrum_htlzbncn # - Allowed Origins: http://localhost:3000 ``` ✅ **Widget Server Running** ```bash # The widget server is already running on http://localhost:3000 ``` ### 2. Open Test Page Open your browser and navigate to: ``` http://localhost:3000/test-security.html ``` --- ## 🧪 Test Scenarios ### Test 1: Phase 0 - Site-Key Only (Basic Security) This tests the basic security model without JWT tokens. **Steps:** 1. **Ensure Phase 0 is selected** (should be default) - Button should show "Phase 0: Site-Key Only" as active - JWT Status should show "No (Phase 0)" 2. **Test Start Conversation** - Click "Test Start Conversation" button - Watch the log panel for activity - **Expected Request:** ```http POST http://localhost:8000/api/v1/conversations Origin: http://localhost:3000 Content-Type: application/json { "message": "Test message...: What is your return policy?", "siteKey": "pub_bright_spectrum_htlzbncn", "citations": true } ``` - **Expected Response:** ```json { "text": "AI response text...", "role": "assistant", "conversation_id": "c_abc123...", "sources": [...], "error": null } ``` - **Success Indicators:** - ✅ Log shows "Conversation started successfully" - ✅ Response text is displayed - ✅ Conversation ID is saved and displayed - ✅ "Test Continue Conversation" button becomes enabled 3. **Test Continue Conversation** - Click "Test Continue Conversation" button - **Expected Request:** ```http POST http://localhost:8000/api/v1/conversations/{conversation_id} Origin: http://localhost:3000 Content-Type: application/json { "message": "Follow-up...: How long do I have to return items?", "citations": true } ``` - **Expected Response:** ```json { "text": "Follow-up AI response...", "role": "assistant", "conversation_id": "c_abc123...", "sources": [...], "error": null } ``` - **Success Indicators:** - ✅ Log shows "Conversation continued successfully" - ✅ Response maintains context from first message - ✅ Same conversation ID is used 4. **Test Widget Integration** - Click "Open Widget" button - Type a message in the widget chat - Send the message - **Expected:** - ✅ Widget opens successfully - ✅ Message is sent via the API - ✅ Response is displayed in chat - ✅ Conversation ID is maintained 5. **Test Clear Session** - Click "Clear Session" button - Verify conversation ID is cleared - Click "Test Start Conversation" again - **Expected:** - ✅ New conversation ID is created - ✅ Previous conversation is not continued --- ### Test 2: Phase 1 - Site-Key + JWT (Enhanced Security) This tests the enhanced security model with JWT session tokens. **Steps:** 1. **Switch to Phase 1** - Click "Phase 1: Site-Key + JWT" button - JWT Status should show "Yes (Phase 1)" - Session ID should initially show "None" - Token Valid should show "❌ Invalid/Expired" 2. **Test Session Creation** - Click "Test Session Creation" button - Watch the log panel for activity - **Expected Request:** ```http POST http://localhost:8000/api/v1/sessions Origin: http://localhost:3000 Content-Type: application/json { "siteKey": "pub_bright_spectrum_htlzbncn", "pageUrlHash": "sha256_hash_of_url", "nonce": "uuid" } ``` - **Expected Response:** ```json { "token": "eyJhbGciOiJI...", "session_id": "550e8400-e29b...", "expires_in": 3600, "expires_at": "2025-10-06T13:00:00Z" } ``` - **Success Indicators:** - ✅ Log shows "Session created successfully" - ✅ Session ID is displayed - ✅ Token Valid shows "✅ Valid" - ✅ Expires at timestamp is logged 3. **Test Start Conversation with JWT** - Click "Test Start Conversation" button - **Expected Request:** ```http POST http://localhost:8000/api/v1/conversations Origin: http://localhost:3000 Authorization: Bearer eyJhbGciOiJI... Content-Type: application/json { "message": "Test message...: What is your return policy?", "siteKey": "pub_bright_spectrum_htlzbncn", "citations": true } ``` - **Success Indicators:** - ✅ Log shows "Added Authorization header" - ✅ Conversation starts successfully - ✅ Conversation ID is saved 4. **Test Continue Conversation with JWT** - Click "Test Continue Conversation" button - **Expected Request:** ```http POST http://localhost:8000/api/v1/conversations/{conversation_id} Origin: http://localhost:3000 Authorization: Bearer eyJhbGciOiJI... Content-Type: application/json { "message": "Follow-up...: How long do I have to return items?", "citations": true } ``` - **Success Indicators:** - ✅ Log shows "Added Authorization header" - ✅ Conversation continues successfully - ✅ Same conversation ID and session ID maintained 5. **Test Token Validation** - Check the "Token Valid" field in Session Information - Should show "✅ Valid" if token is not expired - Token will auto-refresh 5 minutes before expiration 6. **Test Widget with JWT** - Click "Open Widget" button - Send messages through the widget - **Expected:** - ✅ Widget uses JWT token in requests - ✅ Session ID is maintained - ✅ Token is used for all API calls --- ## 🔍 What to Monitor ### Browser DevTools Console Open Chrome DevTools (F12) and check the Console tab for: 1. **Widget Initialization** ``` Spectrum Chat Unified script loaded! Deep Chat loaded internally by Spectrum Chat Initializing Spectrum Chat Global... Spectrum Chat Global initialized successfully ``` 2. **Phase 0 Requests** ``` Sending message: Test message... API URL: http://localhost:8000/api/v1/conversations Request body: {message: "...", siteKey: "...", citations: true} Response data: {text: "...", conversation_id: "...", ...} New conversation started: c_abc123... ``` 3. **Phase 1 Session Creation** ``` Creating session with API URL: http://localhost:8000/api/v1/sessions Session created: {session_id: "...", expires_at: "..."} Saved token data: {session_id: "...", expires_at: "..."} ``` 4. **Phase 1 Requests** ``` Using existing valid token Sending message: Test message... Authorization header: Bearer eyJhbGciOiJI... ``` ### Browser DevTools Network Tab Check the Network tab to verify actual HTTP requests: 1. **Check Request Headers** - `Origin: http://localhost:3000` (automatic) - `Content-Type: application/json` - `Authorization: Bearer ...` (Phase 1 only) 2. **Check Request Payload** - Phase 0: `{message, siteKey, citations}` - Phase 1: `{message, siteKey, citations}` + Authorization header 3. **Check Response** - Status: 200 OK - Response body includes `conversation_id`, `text`, `sources` ### Browser DevTools Application Tab Check sessionStorage: 1. **Phase 0:** - `spectrum-chat-conversation-id`: Conversation ID string - `spectrum-chat-messages`: Message history array 2. **Phase 1:** - `spectrum-chat-conversation-id`: Conversation ID string - `spectrum-chat-token`: JWT token data object - `spectrum-chat-messages`: Message history array --- ## ✅ Success Criteria ### Phase 0 Tests - [ ] Start conversation request includes `siteKey` - [ ] Origin header is automatically sent - [ ] Conversation ID is returned and saved - [ ] Continue conversation uses correct URL format - [ ] Widget integration works end-to-end - [ ] Session clear removes conversation ID ### Phase 1 Tests - [ ] Session creation request includes `siteKey`, `pageUrlHash`, `nonce` - [ ] JWT token is returned and saved to sessionStorage - [ ] Start conversation includes Authorization header - [ ] Continue conversation includes Authorization header - [ ] Token validation works correctly - [ ] Widget integration uses JWT token ### Common Tests - [ ] No JavaScript errors in console - [ ] All API requests return 200 OK - [ ] Conversation context is maintained - [ ] Error messages are user-friendly - [ ] Debug logs show correct flow - [ ] Storage keys are properly managed --- ## 🐛 Troubleshooting ### Issue: "Origin not allowed for this site" **Cause:** Your domain is not in the API's allowed origins list **Solution:** 1. Check API configuration for organization `BrightSpectrum` 2. Ensure `http://localhost:3000` is in allowed origins list 3. Restart API server after configuration change ### Issue: "Invalid or disabled site key" **Cause:** Site key doesn't match or is disabled **Solution:** 1. Verify site key is `pub_bright_spectrum_htlzbncn` 2. Check organization status is active 3. Verify site key is correctly configured ### Issue: "Token expired" (Phase 1) **Cause:** JWT token has expired **Solution:** 1. Click "Clear Session" and retry 2. Widget should auto-refresh tokens before expiration 3. Check token expiration time in session info ### Issue: Widget not loading **Cause:** Script loading error **Solution:** 1. Check browser console for errors 2. Verify server is running on port 3000 3. Check `dist/spectrum-chat.js` exists 4. Clear browser cache and reload ### Issue: CORS errors **Cause:** API not allowing cross-origin requests **Solution:** 1. Ensure API has CORS enabled 2. Check API allows `http://localhost:3000` 3. Verify Origin header is being sent --- ## 📊 Test Results Template Use this template to record your test results: ```markdown ## Test Results - [Date/Time] ### Environment - API URL: http://localhost:8000 - Widget URL: http://localhost:3000 - Site Key: pub_bright_spectrum_htlzbncn - Browser: [Chrome/Firefox/Safari/Edge] ### Phase 0 Tests - [ ] Start Conversation: PASS/FAIL - Request: PASS/FAIL - Response: PASS/FAIL - Conversation ID saved: PASS/FAIL - [ ] Continue Conversation: PASS/FAIL - Request: PASS/FAIL - Response: PASS/FAIL - Context maintained: PASS/FAIL - [ ] Widget Integration: PASS/FAIL - [ ] Session Clear: PASS/FAIL ### Phase 1 Tests - [ ] Session Creation: PASS/FAIL - Request: PASS/FAIL - Token received: PASS/FAIL - Token saved: PASS/FAIL - [ ] Start Conversation with JWT: PASS/FAIL - Auth header present: PASS/FAIL - Conversation created: PASS/FAIL - [ ] Continue Conversation with JWT: PASS/FAIL - Auth header present: PASS/FAIL - Conversation continued: PASS/FAIL - [ ] Token Validation: PASS/FAIL - [ ] Widget Integration with JWT: PASS/FAIL ### Issues Found [List any issues or errors encountered] ### Notes [Additional observations or comments] ``` --- ## 🎯 Next Steps After Testing 1. **Review test results** - Document any failures - Capture error messages - Take screenshots if needed 2. **Verify production readiness** - All Phase 0 tests pass - All Phase 1 tests pass - No console errors - User-friendly error messages 3. **Update configuration for production** - Change API URL to production - Update allowed origins - Disable debug mode - Test on production environment 4. **Deploy and monitor** - Deploy to staging first - Test on staging - Deploy to production - Monitor error logs --- ## 📞 Support If you encounter issues during testing: 1. Check browser console for errors 2. Check browser network tab for failed requests 3. Review the log panel in test page 4. Check API server logs 5. Refer to troubleshooting section above --- **Happy Testing! 🚀**