@spectrumsense/spectrum-chat-dev/docs/README.md

Embeddable AI Widget - Add trusted, evidence-based answers directly to your website. Simple installation, enterprise-grade security.

# Spectrum Chat Security Documentation

Welcome to the Spectrum Chat security documentation. This folder contains comprehensive guides for implementing and migrating to the security-enhanced version of Spectrum Chat.

---

## 📚 Documentation Index

### 1. [Integration Guide](./INTEGRATION_GUIDE.md) ⭐ **START HERE**
**Quick start guide - Add chat to your website in 5 minutes**

Simple, step-by-step guide to integrate the Spectrum Chat widget on any website.

**Topics covered:**
- Quick start (2 steps)
- Basic configuration
- Customization options
- CMS integration (WordPress, Shopify, etc.)
- Troubleshooting
- Best practices

**Start here if you're:** Adding the chat widget to your website for the first time.

---

### 2. [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md)
**Complete security implementation documentation**

Learn about the security model, configuration options, usage examples, and best practices.

**Topics covered:**
- Security architecture overview
- Site-key + Origin validation with JWT tokens
- Configuration guide
- Error handling
- Best practices
- Troubleshooting

**Start here if you're:** Implementing security for the first time or want to understand how the security model works.

---

### 3. [API Reference](./API_REFERENCE.md)
**Complete API documentation**

Comprehensive reference for all configuration options, methods, events, and TypeScript definitions.

**Topics covered:**
- Widget configuration options
- Custom element API
- Global mode API
- Security functions
- Event system
- Storage keys
- Error types
- TypeScript definitions

**Start here if you're:** Looking for specific API details or TypeScript definitions.

---

### 4. [Migration Guide](./MIGRATION_GUIDE.md)
**Step-by-step migration from legacy version**

Detailed instructions for migrating from the legacy Spectrum Chat to the security-enhanced version.

**Topics covered:**
- Migration checklist
- Testing procedures
- Rollback plan
- FAQ

**Start here if you're:** Upgrading from an existing Spectrum Chat implementation.

---

## 🚀 Quick Start

### Method 1: Global Script (Recommended)

Add this before closing `</body>` tag:

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',  // Your site key
    title: 'Help Center',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### Method 2: Custom Element

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>

<spectrum-chat 
  api-url="https://your-api-domain.com/api/v1/conversations"
  site-key="pub_customer_xyz123"
  title="AI Assistant"
  citations="true">
</spectrum-chat>
```

**Note:** JWT authentication is enabled by default for enhanced security. No additional configuration needed!

---

## 🔒 Security Overview

### Secure by Default

The widget uses a secure, multi-layer authentication system:

✅ **Site-Key Authentication** - Public identifier tied to your domain  
✅ **Origin Validation** - API automatically verifies requests come from whitelisted domains  
✅ **JWT Session Tokens** - Secure, time-limited tokens (enabled by default)  
✅ **Auto-Refresh** - Tokens refresh automatically before expiration  
✅ **Conversation Protection** - Conversations bound to origin domain  
✅ **HTTPS Enforcement** - Production requires secure connections

**All security is automatic** - no configuration needed!

---

## 📋 Documentation by Use Case

### I want to...

#### Implement security for the first time
→ Read [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md)  
→ Focus on Phase 0 section  
→ Test with examples provided

#### Migrate from legacy version
→ Read [Migration Guide](./MIGRATION_GUIDE.md)  
→ Follow the checklist  
→ Test on staging first

#### Understand the API
→ Read [API Reference](./API_REFERENCE.md)  
→ Check specific methods/options  
→ Review TypeScript definitions

#### Enable JWT tokens
→ Read [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md) - Phase 1 section  
→ Update configuration with `use-jwt="true"`  
→ Test token lifecycle

#### Handle errors properly
→ Read [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md) - Error Handling section  
→ Review error codes in [API Reference](./API_REFERENCE.md)  
→ Implement custom error handling

#### Troubleshoot issues
→ Read [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md) - Troubleshooting section  
→ Enable debug mode: `debug="true"`  
→ Check browser console for errors

---

## 🔑 Key Concepts

### Site Key
A **public** identifier that associates your widget with your organization. Format: `pub_customer_a1b2c3d4`

**Not secret!** Security comes from origin validation, not site key secrecy.

### Origin Validation
The API automatically validates the `Origin` header sent by the browser against your allowed origins list.

**Automatic!** No configuration needed on client side.

### JWT Session Tokens
Optional time-limited tokens that provide enhanced security and audit trails.

**Auto-managed!** Widget handles creation, refresh, and expiration.

### Conversation Binding
Each conversation is bound to the origin that created it. Cross-origin continuation is blocked.

**Automatic!** Prevents conversation hijacking.

---

## 🛠️ Configuration Examples

### Minimal Configuration (Phase 0)

```html
<spectrum-chat 
  api-url="https://api.example.com/api/v1/conversations"
  site-key="pub_customer_a1b2c3d4">
</spectrum-chat>
```

### Recommended Configuration (Phase 1)

```html
<spectrum-chat 
  api-url="https://api.example.com/api/v1/conversations"
  site-key="pub_customer_a1b2c3d4"
  use-jwt="true"
  title="Customer Support"
  citations="true"
  primary-color="#2563eb"
  debug="false">
</spectrum-chat>
```

### Global Mode Configuration

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://api.example.com/api/v1/conversations',
    siteKey: 'pub_customer_a1b2c3d4',
    useJWT: true,
    title: 'Customer Support',
    enableCitations: true,
    primaryColor: '#2563eb',
    debug: false
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

---

## 🧪 Testing

### Enable Debug Mode

```html
<spectrum-chat 
  api-url="..."
  site-key="..."
  debug="true">
</spectrum-chat>
```

### Check Status Programmatically

```javascript
const chat = window.SpectrumChatGlobal;

// Check configuration
console.log('Config:', chat.getConfig());

// Check session
console.log('Conversation ID:', chat.getConversationId());
console.log('Session ID:', chat.getSessionId());
console.log('Token valid:', chat.isTokenValid());

// Check widget state
console.log('Is open:', chat.isOpen());
```

### Clear Session

```javascript
// Clear conversation, token, and messages
window.SpectrumChatGlobal.clearSession();
```

---

## ⚠️ Common Issues

### "This domain is not authorized"
**Solution:** Contact API administrator to add your domain to allowed origins list.

### "This chat service requires HTTPS"
**Solution:** Use HTTPS in production. HTTP is only allowed for localhost development.

### "Session expired"
**Solution:** Token will auto-refresh. If it persists, clear session and retry.

### Widget not loading
**Solution:** Check browser console for errors. Verify script URL and CSP settings.

---

## 📊 Security Checklist

Before going to production:

- [ ] Site key obtained from API administrator
- [ ] Domain(s) added to allowed origins list
- [ ] HTTPS enabled on production website
- [ ] Widget tested on staging environment
- [ ] Error handling implemented
- [ ] Debug mode disabled for production
- [ ] JWT enabled (Phase 1 recommended)
- [ ] Monitoring/analytics set up
- [ ] Team documentation updated

---

## 🆘 Support

Need help?

1. **Read the docs** - Start with [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md)
2. **Check troubleshooting** - Common issues and solutions
3. **Enable debug mode** - Get detailed console logging
4. **Check browser console** - Look for error messages
5. **Contact support** - support@spectrumsense.com

---

## 📦 Version Information

**Current Version:** 1.0.0  
**Release Date:** October 6, 2025  
**Widget Package:** `@spectrumsense/spectrum-chat`

### Changelog

#### v1.0.0 (October 6, 2025)
- ✅ Implemented Phase 0: Site-key + Origin validation
- ✅ Implemented Phase 1: JWT session tokens
- ✅ Added automatic token refresh
- ✅ Added stale conversation handling
- ✅ Added comprehensive error handling
- ✅ Added user-friendly error messages
- ✅ Maintained backward compatibility with tenant_id
- ✅ Added debug mode
- ✅ Added comprehensive documentation

---

## 🔗 Related Resources

### Internal Documentation
- [Main README](../README.md) - Project overview
- [Build Guide](../BUILD_GUIDE.md) - Building the widget
- [Publishing Guide](../PUBLISHING_GUIDE.md) - Publishing to NPM
- [Global Integration](../GLOBAL_INTEGRATION.md) - Template integration guide
- [Technical Spec](../technical-spec.md) - Technical specifications

### External Resources
- [KnowledgeInjester API Specification](https://github.com/your-org/knowledgeinjester-api) - API documentation
- [Deep Chat Documentation](https://deepchat.dev/) - Underlying chat component
- [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) - For SHA256 hashing
- [CORS Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) - Origin header behavior

---

## 📝 Contributing

Found an issue or want to improve the documentation?

1. Check existing issues
2. Create detailed issue report
3. Submit pull request with fixes
4. Update documentation accordingly

---

**Last Updated:** October 6, 2025  
**Maintained by:** Spectrum Sense Team  
**Version:** 1.0.0