GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add documentation for dashboards, auth RBAC, white-label, security, and channel features

Browse source
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2026-01-08 13:16:04 -03:00
parent 6bfab51293
commit 6964eae250
25 changed files with 7687 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

211
src/04-gbui/apps/compliance.md
View file

@ -1,6 +1,6 @@
# Compliance - Security Scanner
# Compliance Center
> **Your privacy and security guardian**
> **Your privacy, security, and data governance guardian**
<img src="../../assets/suite/compliance-screen.svg" alt="Compliance Interface Screen" style="max-width: 100%; height: auto;">
@ -8,7 +8,14 @@
## Overview
Compliance is the security and privacy management app in General Bots Suite. Monitor data handling, manage consent, respond to data subject requests, and ensure your bots comply with regulations like LGPD, GDPR, and CCPA. Compliance helps you protect user data and maintain trust.
Compliance Center is the comprehensive security, privacy, and data governance app in General Bots Suite. Monitor data handling, manage consent, respond to data subject requests, prevent data loss, manage legal holds, classify sensitive information, and ensure your bots comply with regulations like LGPD, GDPR, HIPAA, and CCPA.
**Key Capabilities:**
- **DLP (Data Loss Prevention)** - Detect and prevent sensitive data leaks
- **eDiscovery** - Legal holds, content search, and case management
- **Information Protection** - Classify and protect sensitive documents
- **Compliance Scanning** - Automated regulatory compliance checks
- **Data Subject Requests** - Handle GDPR/LGPD rights requests
---
@ -44,6 +51,169 @@ The dashboard gives you an at-a-glance view of your compliance status:
---
---
## Data Loss Prevention (DLP)
Automatically detect and prevent sensitive data from being shared inappropriately.
### Sensitive Data Types Detected
| Type | Examples | Severity |
|------|----------|----------|
| **Credit Card** | Visa, MasterCard, Amex | Critical |
| **SSN/CPF** | Social Security, Brazilian CPF | Critical |
| **Health ID** | Medicare, Medical Record Numbers | Critical |
| **Bank Account** | Account numbers, IBAN | High |
| **API Keys** | AWS, Azure, GCP credentials | Critical |
| **Private Keys** | RSA, SSH, PGP keys | Critical |
| **JWT Tokens** | Authentication tokens | High |
| **Email** | Email addresses | Medium |
| **Phone** | Phone numbers | Medium |
| **IP Address** | IPv4, IPv6 addresses | Low |
### DLP Policies
Create policies to control how sensitive data is handled:
**Policy Actions:**
| Action | Description |
|--------|-------------|
| **Allow** | Log but permit the action |
| **Warn** | Show warning to user |
| **Redact** | Mask sensitive data automatically |
| **Block** | Prevent the action entirely |
| **Quarantine** | Hold for manual review |
**Example Policy:**
```
Name: Block Credit Cards in External Emails
Data Types: Credit Card
Scope: Outbound emails
Action: Block
Severity Threshold: High
```
### DLP Scanning Integration
DLP scans are integrated with:
- **Mail** - Inbound and outbound email scanning
- **Drive** - File upload scanning
- **Chat** - Message content scanning
- **Social** - Post content scanning
---
## eDiscovery
Manage legal holds, search content, and export data for legal proceedings.
### Case Management
Create and manage legal cases:
1. **Create Case** - Name, description, matter ID
2. **Add Custodians** - Users whose data to preserve
3. **Apply Legal Hold** - Prevent data deletion
4. **Search Content** - Find relevant documents
5. **Review & Tag** - Mark documents as relevant
6. **Export** - Generate production packages
### Legal Hold
Legal holds prevent data deletion for specified users:
| Status | Description |
|--------|-------------|
| **Active** | Data is preserved, deletion blocked |
| **Released** | Hold removed, normal retention applies |
| **Pending** | Awaiting approval |
**What's Preserved:**
- Emails and attachments
- Chat messages
- Drive files
- Calendar events
- Social posts
- Conversation logs
### Content Search
Search across all data sources:
**Search Operators:**
| Operator | Example | Description |
|----------|---------|-------------|
| `AND` | contract AND confidential | Both terms required |
| `OR` | contract OR agreement | Either term |
| `NOT` | contract NOT draft | Exclude term |
| `"..."` | "final agreement" | Exact phrase |
| `from:` | from:john@company.com | Sender filter |
| `to:` | to:legal@company.com | Recipient filter |
| `date:` | date:2024-01-01..2024-12-31 | Date range |
| `type:` | type:pdf | File type filter |
### Export Formats
| Format | Use Case |
|--------|----------|
| **PST** | Email archives for Outlook |
| **PDF** | Document production |
| **Native** | Original file formats |
| **ZIP** | Bulk download |
| **Load File** | Litigation support systems |
---
## Information Protection
Classify and protect documents based on sensitivity levels.
### Sensitivity Labels
| Label | Icon | Description | Protections |
|-------|------|-------------|-------------|
| **Public** | 🟢 | Can be shared externally | None |
| **Internal** | 🔵 | Employees only | Watermark |
| **Confidential** | 🟡 | Restricted groups | Encrypt, watermark |
| **Highly Confidential** | 🔴 | Need-to-know basis | Encrypt, no copy/print, expire |
### Auto-Labeling Rules
Automatically classify documents based on content:
| Rule | Trigger | Label Applied |
|------|---------|---------------|
| Contains "salary" or "compensation" | Keywords | Confidential |
| Contains CPF/SSN | PII detection | Highly Confidential |
| Contains "public announcement" | Keywords | Public |
| Medical records | Content type | Highly Confidential |
| Financial statements | Content type | Confidential |
### Protection Actions
Based on label, apply protections:
| Protection | Description |
|------------|-------------|
| **Encryption** | AES-256 encryption at rest |
| **Watermark** | Visual marking with user info |
| **No Copy** | Disable copy/paste |
| **No Print** | Disable printing |
| **No Forward** | Prevent email forwarding |
| **Expiration** | Auto-revoke access after date |
| **Audit** | Log all access attempts |
### Label Inheritance
- Files inherit labels from parent folders
- Attachments inherit labels from emails
- Exports maintain original labels
---
### Security Scanner
Automatically scan your bots and data for compliance issues.
@ -400,9 +570,44 @@ Response:
---
---
## API Endpoints Summary
### DLP Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/compliance/dlp/scan` | POST | Scan content for sensitive data |
| `/api/compliance/dlp/policies` | GET/POST | List or create DLP policies |
| `/api/compliance/dlp/policies/{id}` | PUT/DELETE | Update or delete policy |
| `/api/compliance/dlp/violations` | GET | List DLP violations |
### eDiscovery Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/compliance/ediscovery/cases` | GET/POST | List or create cases |
| `/api/compliance/ediscovery/cases/{id}` | GET/PUT | Get or update case |
| `/api/compliance/ediscovery/cases/{id}/holds` | POST | Apply legal hold |
| `/api/compliance/ediscovery/cases/{id}/search` | POST | Search case content |
| `/api/compliance/ediscovery/cases/{id}/export` | POST | Export case data |
### Information Protection Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/compliance/protection/labels` | GET/POST | List or create labels |
| `/api/compliance/protection/labels/{id}` | PUT/DELETE | Update or delete label |
| `/api/compliance/protection/classify` | POST | Classify a document |
| `/api/compliance/protection/rules` | GET/POST | Auto-labeling rules |
---
## See Also
- [Compliance API Reference](./compliance-api.md) - Full API documentation
- [Analytics App](./analytics.md) - Monitor compliance metrics
- [Dashboards App](./dashboards.md) - Create compliance dashboards
- [Sources App](./sources.md) - Configure bot policies
- [How To: Monitor Your Bot](../how-to/monitor-sessions.md)

410
src/04-gbui/apps/dashboards.md Normal file
View file

@ -0,0 +1,410 @@
# Dashboards
> **Build custom data visualizations with AI-powered insights**
---
## Overview
Dashboards is the business intelligence and data visualization app in General Bots Suite. Create custom dashboards with drag-and-drop widgets, connect to multiple data sources, and use natural language queries to explore your data. Dashboards helps you monitor KPIs, track metrics, and make data-driven decisions.
**Key Capabilities:**
- **Visual Dashboard Builder** - Drag-and-drop widgets and layouts
- **Multiple Data Sources** - Connect databases, APIs, files, and cloud warehouses
- **Conversational Analytics** - Ask questions in natural language
- **Real-time Updates** - Auto-refresh with configurable intervals
- **Templates** - Pre-built dashboards for common use cases
- **Sharing & Export** - Share dashboards or export as PDF/PNG
---
## Features
### Dashboard Builder
Create dashboards visually with a flexible grid system:
**Layout Options:**
| Layout | Columns | Best For |
|--------|---------|----------|
| **12 Columns** | 12 | Complex dashboards with many widgets |
| **6 Columns** | 6 | Medium complexity |
| **4 Columns** | 4 | Simple, mobile-friendly dashboards |
**Widget Types:**
| Category | Widgets |
|----------|---------|
| **Charts** | Line, Bar, Pie, Donut, Area, Scatter, Heatmap |
| **Data Display** | KPI Card, Table, Gauge, Map |
| **Content** | Text, Image, Embed (iframe) |
| **Filters** | Dropdown Filter, Date Range Picker |
---
### Widget Configuration
Each widget can be configured with:
**Chart Widgets:**
- X-axis and Y-axis field mapping
- Multiple data series
- Colors and legend position
- Animation settings
- Stacked or grouped display
**KPI Widgets:**
- Value field
- Comparison (previous period, target, YoY)
- Thresholds for color coding
- Prefix/suffix formatting
**Table Widgets:**
- Column selection and ordering
- Sorting and filtering
- Pagination settings
- Export options
---
### Data Sources
Connect to various data sources:
| Source Type | Examples |
|-------------|----------|
| **Databases** | PostgreSQL, MySQL, SQL Server, MongoDB |
| **Cloud Warehouses** | BigQuery, Snowflake, Redshift |
| **APIs** | REST API, GraphQL API |
| **Files** | CSV, Excel, Google Sheets |
| **Internal** | GB Suite internal tables |
**Connection Setup:**
1. Click **Add Data Source** in sidebar
2. Select source type
3. Enter connection details:
- Host, port, database name
- Username and password (stored in vault)
- SSL configuration
4. Click **Test Connection**
5. Click **Add Source**
---
### Conversational Analytics
Ask questions about your data in natural language:
**Example Queries:**
| Query | Result |
|-------|--------|
| "Show me sales by region for last quarter" | Bar chart with regional breakdown |
| "What's the trend in customer signups?" | Line chart with trend analysis |
| "Top 10 products by revenue" | Table with ranking |
| "Compare this month vs last month" | KPI cards with comparison |
| "Which day had the most orders?" | Single value with date |
**How It Works:**
1. Type your question in the query box
2. Select target data source (or "All")
3. AI translates to SQL/query
4. Results displayed as visualization
5. Save as widget to dashboard
---
### Templates
Pre-built dashboard templates for common use cases:
| Template | Widgets Included |
|----------|------------------|
| **Sales Dashboard** | Revenue KPI, Sales by Region, Top Products, Pipeline |
| **Marketing Dashboard** | Leads, Conversion Rate, Campaign Performance |
| **Operations Dashboard** | Uptime, Response Time, Error Rate, Active Users |
| **Finance Dashboard** | Revenue, Expenses, Cash Flow, P&L |
| **HR Dashboard** | Headcount, Turnover, Hiring Pipeline |
---
### Sharing & Permissions
**Visibility Options:**
| Setting | Description |
|---------|-------------|
| **Private** | Only you can view and edit |
| **Team** | Team members can view |
| **Organization** | Everyone in org can view |
| **Public** | Anyone with link can view |
**Sharing Actions:**
- Copy link to clipboard
- Embed in other applications
- Schedule email reports
- Export as PDF or PNG
---
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `N` | New dashboard |
| `E` | Edit mode toggle |
| `R` | Refresh data |
| `S` | Save dashboard |
| `W` | Add widget |
| `/` | Focus query input |
| `Escape` | Close modal/exit edit mode |
| `Ctrl+D` | Duplicate widget |
| `Delete` | Delete selected widget |
---
## Tips & Tricks
### Building Effective Dashboards
💡 **Start with KPIs** - Place most important metrics at the top
💡 **Use consistent colors** - Same color = same meaning across widgets
💡 **Group related widgets** - Organize by topic or data source
💡 **Add context** - Include text widgets to explain metrics
### Performance Tips
💡 **Limit widgets** - 10-15 widgets per dashboard for best performance
💡 **Use date filters** - Narrow data range to speed up queries
💡 **Cache queries** - Enable caching for slow data sources
💡 **Aggregate data** - Pre-aggregate when possible
### Data Source Best Practices
💡 **Use read replicas** - Don't query production databases
💡 **Create views** - Pre-join tables for simpler queries
💡 **Index properly** - Ensure indexes on filtered columns
💡 **Limit permissions** - Grant minimum necessary access
---
## Troubleshooting
### Dashboard not loading
**Possible causes:**
1. Data source connection failed
2. Query timeout
3. Authentication expired
**Solution:**
1. Check data source status in sidebar
2. Increase timeout in settings
3. Re-authenticate with data source
4. Check query performance
---
### Widget shows no data
**Possible causes:**
1. Query returns empty result
2. Date filter excludes all data
3. Field mapping incorrect
**Solution:**
1. Test query directly in data source
2. Adjust date range filter
3. Verify field names match schema
4. Check data type compatibility
---
### Slow dashboard performance
**Possible causes:**
1. Too many widgets
2. Complex queries
3. Large data volumes
4. No caching enabled
**Solution:**
1. Split into multiple dashboards
2. Simplify queries, add aggregations
3. Narrow date ranges
4. Enable query caching in settings
---
## BASIC Integration
Use Dashboards features in your dialogs:
### Query Dashboard Data
```basic
' Get data from a dashboard widget
data = QUERY DASHBOARD "sales-dashboard" WIDGET "revenue-kpi"
TALK "Current revenue: $" + data.value
TALK "Change from last period: " + data.change + "%"
```
### Embed Dashboard in Bot
```basic
' Show a dashboard in the conversation
SHOW DASHBOARD "sales-overview" TO user
TALK "Here's your sales dashboard. What would you like to know more about?"
```
### Create Dashboard Programmatically
```basic
' Create a new dashboard from bot
dashboard = CREATE DASHBOARD
NAME "Weekly Report"
TEMPLATE "sales"
DATE_RANGE "last_7_days"
SHARE DASHBOARD dashboard.id WITH user.email
TALK "Your dashboard is ready: " + dashboard.url
```
### Natural Language Query
```basic
' Let user ask questions about data
TALK "What would you like to know about your data?"
HEAR question AS TEXT
result = QUERY DATA question FROM "sales-db"
IF result.type = "chart" THEN
SHOW CHART result.data
ELSE
TALK result.answer
END IF
```
---
## API Reference
### Endpoints Summary
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/dashboards` | GET | List all dashboards |
| `/api/dashboards` | POST | Create new dashboard |
| `/api/dashboards/{id}` | GET | Get dashboard details |
| `/api/dashboards/{id}` | PUT | Update dashboard |
| `/api/dashboards/{id}` | DELETE | Delete dashboard |
| `/api/dashboards/{id}/widgets` | POST | Add widget |
| `/api/dashboards/{id}/widgets/{wid}` | PUT | Update widget |
| `/api/dashboards/{id}/widgets/{wid}` | DELETE | Delete widget |
| `/api/dashboards/{id}/widgets/{wid}/data` | GET | Get widget data |
| `/api/dashboards/sources` | GET | List data sources |
| `/api/dashboards/sources` | POST | Add data source |
| `/api/dashboards/sources/{id}/test` | POST | Test connection |
| `/api/dashboards/query` | POST | Natural language query |
| `/api/dashboards/templates` | GET | List templates |
### Example: Create Dashboard
```json
POST /api/dashboards
{
"name": "Sales Overview",
"description": "Weekly sales metrics and trends",
"layout": {
"columns": 12,
"row_height": 80,
"gap": 16
},
"is_public": false,
"tags": ["sales", "weekly"]
}
Response:
{
"id": "dash_abc123",
"name": "Sales Overview",
"created_at": "2025-01-27T10:00:00Z",
"widgets": [],
"url": "/dashboards/dash_abc123"
}
```
### Example: Add Widget
```json
POST /api/dashboards/dash_abc123/widgets
{
"widget_type": "line_chart",
"title": "Revenue Trend",
"position": {
"x": 0,
"y": 0,
"width": 6,
"height": 4
},
"data_query": {
"source_id": "src_sales_db",
"sql": "SELECT date, SUM(amount) as revenue FROM orders GROUP BY date ORDER BY date",
"fields": ["date", "revenue"]
},
"config": {
"chart_config": {
"x_axis": "date",
"y_axis": "revenue",
"colors": ["#10b981"]
}
}
}
```
### Example: Natural Language Query
```json
POST /api/dashboards/query
{
"query": "Show me top 5 customers by revenue last month",
"data_source_id": "src_sales_db"
}
Response:
{
"query": "SELECT customer_name, SUM(amount) as revenue FROM orders WHERE date >= '2025-01-01' GROUP BY customer_name ORDER BY revenue DESC LIMIT 5",
"data": [
{"customer_name": "Acme Corp", "revenue": 150000},
{"customer_name": "TechStart", "revenue": 120000},
...
],
"suggested_visualization": "bar_chart",
"explanation": "Top 5 customers ranked by total revenue for January 2025"
}
```
---
## See Also
- [Analytics App](./analytics.md) - Built-in analytics and metrics
- [Compliance App](./compliance.md) - Compliance dashboards
- [Research App](./research.md) - Data research tools
- [Sheet App](./sheet.md) - Spreadsheet data source

477
src/06-gbdialog/keyword-face-api.md Normal file
View file

@ -0,0 +1,477 @@
# Face API Keywords
General Bots provides face detection and analysis capabilities through BASIC keywords that integrate with Azure Face API and other providers.
<img src="../assets/gb-decorative-header.svg" alt="General Bots" style="max-height: 100px; width: 100%; object-fit: contain;">
## Overview
Face API keywords enable:
- Face detection in images and video frames
- Face verification (comparing two faces)
- Facial attribute analysis (age, emotion, glasses, etc.)
- Multi-provider support (Azure, AWS Rekognition, OpenCV)
## DETECT FACES
Detect faces in an image and return their locations and attributes.
### Syntax
```bas
faces = DETECT FACES image
faces = DETECT FACES image, options
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| image | String/File | Image path, URL, or base64 data |
| options | Object | Optional detection settings |
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| return_attributes | Boolean | false | Include facial attributes |
| return_landmarks | Boolean | false | Include facial landmarks |
| detection_model | String | "detection_01" | Detection model to use |
| recognition_model | String | "recognition_04" | Recognition model for face IDs |
### Return Value
Returns an array of detected faces:
```json
[
{
"face_id": "uuid",
"rectangle": {
"top": 100,
"left": 150,
"width": 200,
"height": 250
},
"confidence": 0.98,
"attributes": {
"age": 32,
"gender": "male",
"emotion": "happy",
"glasses": "none"
}
}
]
```
### Examples
#### Basic Detection
```bas
image = "/photos/team.jpg"
faces = DETECT FACES image
TALK "Found " + LEN(faces) + " face(s) in the image"
FOR EACH face IN faces
TALK "Face at position: " + face.rectangle.left + ", " + face.rectangle.top
NEXT
```
#### With Attributes
```bas
options = #{return_attributes: true}
faces = DETECT FACES "/photos/portrait.jpg", options
IF LEN(faces) > 0 THEN
face = faces[0]
TALK "Detected a " + face.attributes.age + " year old person"
TALK "Expression: " + face.attributes.emotion
END IF
```
#### Upload and Detect
```bas
ON FILE UPLOAD
IF file.type STARTS WITH "image/" THEN
faces = DETECT FACES file.path
IF LEN(faces) = 0 THEN
TALK "No faces detected in this image"
ELSE IF LEN(faces) = 1 THEN
TALK "Found 1 face"
ELSE
TALK "Found " + LEN(faces) + " faces"
END IF
END IF
END ON
```
## VERIFY FACE
Compare two faces to determine if they belong to the same person.
### Syntax
```bas
result = VERIFY FACE face_id1, face_id2
result = VERIFY FACE image1, image2
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| face_id1 | String | First face ID from detection |
| face_id2 | String | Second face ID from detection |
| image1 | String/File | First image (auto-detects face) |
| image2 | String/File | Second image (auto-detects face) |
### Return Value
```json
{
"is_identical": true,
"confidence": 0.92,
"threshold": 0.5
}
```
### Examples
#### Verify Using Face IDs
```bas
faces1 = DETECT FACES "/photos/id-card.jpg"
faces2 = DETECT FACES "/photos/selfie.jpg"
IF LEN(faces1) > 0 AND LEN(faces2) > 0 THEN
result = VERIFY FACE faces1[0].face_id, faces2[0].face_id
IF result.is_identical THEN
TALK "Match confirmed with " + ROUND(result.confidence * 100, 0) + "% confidence"
ELSE
TALK "Faces do not match"
END IF
END IF
```
#### Verify Using Images Directly
```bas
id_photo = "/documents/passport.jpg"
live_photo = "/uploads/verification-selfie.jpg"
result = VERIFY FACE id_photo, live_photo
IF result.is_identical AND result.confidence > 0.8 THEN
SET USER "verified", true
TALK "Identity verified successfully!"
ELSE
TALK "Verification failed. Please try again with a clearer photo."
END IF
```
#### KYC Verification Flow
```bas
TALK "Please upload a photo of your ID"
HEAR AS id_image
TALK "Now take a selfie for verification"
HEAR AS selfie_image
id_faces = DETECT FACES id_image
selfie_faces = DETECT FACES selfie_image
IF LEN(id_faces) = 0 THEN
TALK "Could not detect a face in your ID photo"
ELSE IF LEN(selfie_faces) = 0 THEN
TALK "Could not detect your face in the selfie"
ELSE
result = VERIFY FACE id_faces[0].face_id, selfie_faces[0].face_id
IF result.is_identical THEN
IF result.confidence >= 0.9 THEN
SET USER "kyc_status", "verified"
TALK "✅ Identity verified with high confidence"
ELSE IF result.confidence >= 0.7 THEN
SET USER "kyc_status", "pending_review"
TALK "⚠️ Verification needs manual review"
ELSE
SET USER "kyc_status", "failed"
TALK "❌ Verification confidence too low"
END IF
ELSE
SET USER "kyc_status", "failed"
TALK "❌ Faces do not match"
END IF
END IF
```
## ANALYZE FACE
Perform detailed analysis of facial attributes.
### Syntax
```bas
analysis = ANALYZE FACE image
analysis = ANALYZE FACE image, attributes
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| image | String/File | Image path, URL, or base64 data |
| attributes | Array | Specific attributes to analyze |
### Available Attributes
| Attribute | Description |
|-----------|-------------|
| age | Estimated age |
| gender | Detected gender |
| emotion | Primary emotion (happy, sad, angry, etc.) |
| glasses | Type of glasses (none, reading, sunglasses) |
| facial_hair | Beard, mustache, sideburns |
| hair | Hair color, bald, invisible |
| makeup | Eye makeup, lip makeup |
| accessories | Headwear, mask |
| occlusion | Face occlusion (forehead, eye, mouth) |
| blur | Image blur level |
| exposure | Image exposure level |
| noise | Image noise level |
| head_pose | Pitch, roll, yaw angles |
| smile | Smile intensity (0-1) |
### Return Value
```json
{
"face_id": "uuid",
"attributes": {
"age": 28,
"gender": "female",
"emotion": {
"primary": "happy",
"scores": {
"happy": 0.95,
"neutral": 0.03,
"surprise": 0.02
}
},
"glasses": "none",
"smile": 0.87,
"facial_hair": {
"beard": 0.0,
"mustache": 0.0,
"sideburns": 0.0
},
"head_pose": {
"pitch": -5.2,
"roll": 2.1,
"yaw": -8.3
},
"quality": {
"blur": "low",
"exposure": "good",
"noise": "low"
}
}
}
```
### Examples
#### Basic Analysis
```bas
analysis = ANALYZE FACE "/photos/headshot.jpg"
IF analysis != NULL THEN
TALK "Estimated age: " + analysis.attributes.age
TALK "Primary emotion: " + analysis.attributes.emotion.primary
TALK "Smile score: " + ROUND(analysis.attributes.smile * 100, 0) + "%"
END IF
```
#### Specific Attributes
```bas
attributes = ["age", "emotion", "glasses"]
analysis = ANALYZE FACE image, attributes
TALK "Age: " + analysis.attributes.age
TALK "Emotion: " + analysis.attributes.emotion.primary
TALK "Glasses: " + analysis.attributes.glasses
```
#### Photo Quality Check
```bas
analysis = ANALYZE FACE uploaded_photo
quality = analysis.attributes.quality
IF quality.blur = "high" THEN
TALK "Your photo is too blurry. Please upload a clearer image."
ELSE IF quality.exposure = "over" OR quality.exposure = "under" THEN
TALK "Lighting is not optimal. Please use better lighting."
ELSE IF analysis.attributes.occlusion.forehead OR analysis.attributes.occlusion.eye THEN
TALK "Part of your face is obscured. Please ensure your full face is visible."
ELSE
TALK "Photo quality is acceptable!"
END IF
```
#### Emotion-Based Response
```bas
ON MESSAGE
IF message.has_image THEN
analysis = ANALYZE FACE message.image
IF analysis != NULL THEN
emotion = analysis.attributes.emotion.primary
SWITCH emotion
CASE "happy"
TALK "You look happy! 😊 How can I help you today?"
CASE "sad"
TALK "I'm sorry you seem down. Is there anything I can help with?"
CASE "angry"
TALK "I sense some frustration. Let me see how I can assist you."
CASE "surprise"
TALK "Surprised? Let me know what's on your mind!"
DEFAULT
TALK "How can I help you today?"
END SWITCH
END IF
END IF
END ON
```
#### Customer Satisfaction Analysis
```bas
SET SCHEDULE "every day at 6pm"
photos = LIST "/store/customer-photos/today/"
emotions = #{happy: 0, neutral: 0, sad: 0, angry: 0}
total = 0
FOR EACH photo IN photos
analysis = ANALYZE FACE photo.path
IF analysis != NULL THEN
primary_emotion = analysis.attributes.emotion.primary
emotions[primary_emotion] = emotions[primary_emotion] + 1
total = total + 1
END IF
NEXT
IF total > 0 THEN
satisfaction_rate = ROUND((emotions.happy / total) * 100, 1)
report = "Daily Customer Mood Report\n"
report = report + "========================\n"
report = report + "Total analyzed: " + total + "\n"
report = report + "Happy: " + emotions.happy + "\n"
report = report + "Neutral: " + emotions.neutral + "\n"
report = report + "Satisfaction rate: " + satisfaction_rate + "%"
SEND MAIL TO "manager@store.com" SUBJECT "Daily Mood Report" BODY report
END IF
```
## Configuration
Add Face API credentials to your bot's `config.csv`:
### Azure Face API
```csv
key,value
face-api-provider,azure
azure-face-endpoint,https://your-resource.cognitiveservices.azure.com
azure-face-key,your-api-key
```
### AWS Rekognition
```csv
key,value
face-api-provider,aws
aws-access-key-id,your-access-key
aws-secret-access-key,your-secret-key
aws-region,us-east-1
```
### Local OpenCV (Offline)
```csv
key,value
face-api-provider,opencv
opencv-model-path,/models/face_detection
```
## Error Handling
```bas
ON ERROR RESUME NEXT
faces = DETECT FACES image
IF ERROR THEN
error_msg = ERROR MESSAGE
IF error_msg CONTAINS "rate limit" THEN
WAIT 60
faces = DETECT FACES image
ELSE IF error_msg CONTAINS "invalid image" THEN
TALK "Please provide a valid image file"
ELSE
TALK "Face detection is temporarily unavailable"
END IF
END IF
CLEAR ERROR
```
## Privacy Considerations
Face detection and analysis involves biometric data. Ensure you:
- Obtain explicit consent before processing facial images
- Store face IDs temporarily (they expire after 24 hours)
- Do not store facial templates long-term without consent
- Comply with GDPR, CCPA, and other privacy regulations
- Provide clear privacy notices to users
- Allow users to request deletion of their facial data
## Best Practices
**Use appropriate thresholds.** For security applications, use higher confidence thresholds (0.8+). For general matching, 0.6+ may suffice.
**Handle multiple faces.** Always check the number of detected faces and handle edge cases.
**Check image quality.** Poor lighting, blur, or occlusion affects accuracy. Validate quality before verification.
**Implement rate limiting.** Face API services have rate limits. Cache results and avoid redundant calls.
**Provide fallbacks.** If face detection fails, offer alternative verification methods.
**Respect privacy.** Only collect and process facial data with user consent and for legitimate purposes.
## See Also
- [ON FILE UPLOAD](./keyword-on.md) - Handle uploaded images
- [SET USER](./keyword-set-user.md) - Store verification status
- [ON ERROR](./keyword-on-error.md) - Error handling
- [SEND MAIL](./keyword-send-mail.md) - Send reports

387
src/06-gbdialog/keyword-post-to.md Normal file
View file

@ -0,0 +1,387 @@
# POST TO
Publish content to social media platforms and messaging channels. Supports text, images, videos, and multi-platform posting.
<img src="../assets/gb-decorative-header.svg" alt="General Bots" style="max-height: 100px; width: 100%; object-fit: contain;">
## Syntax
```bas
POST TO platform content
POST TO platform content, caption
POST TO platform image, caption
POST TO "platform1,platform2" image, caption
POST TO platform AT "datetime" content
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| platform | String | Target platform name or comma-separated list |
| content | String/File | Text content, image path, or video path |
| caption | String | Optional caption or message text |
| datetime | String | Optional scheduled time (ISO 8601 format) |
## Supported Platforms
| Platform | Identifier | Content Types |
|----------|------------|---------------|
| Instagram | `instagram` | Images, Videos, Carousels |
| Facebook | `facebook` | Text, Images, Videos, Links |
| LinkedIn | `linkedin` | Text, Images, Articles |
| Twitter/X | `twitter` | Text, Images, Videos |
| Bluesky | `bluesky` | Text, Images |
| Threads | `threads` | Text, Images |
| Discord | `discord` | Text, Images, Embeds |
| TikTok | `tiktok` | Videos |
| YouTube | `youtube` | Videos, Community Posts |
| Pinterest | `pinterest` | Images (Pins) |
| Reddit | `reddit` | Text, Links, Images |
| WeChat | `wechat` | Text, Images, Articles |
| Snapchat | `snapchat` | Images, Videos |
## Basic Usage
### Text Post
```bas
POST TO BLUESKY "Just launched our new AI assistant! 🚀"
POST TO TWITTER "Check out our latest update"
POST TO LINKEDIN "Excited to announce our partnership with..."
```
### Image Post
```bas
image = "/marketing/product-launch.jpg"
caption = "Introducing our newest feature! #AI #Innovation"
POST TO INSTAGRAM image, caption
```
### Video Post
```bas
video = "/videos/tutorial.mp4"
description = "Quick tutorial on getting started"
POST TO TIKTOK video, description
POST TO YOUTUBE video, "How to automate your workflow"
```
## Multi-Platform Posting
Post to multiple platforms simultaneously:
```bas
image = "/content/announcement.png"
caption = "Big news! We're expanding to new markets 🌍"
POST TO "instagram,facebook,linkedin,twitter" image, caption
```
### Platform-Specific Content
```bas
image = "/promo/sale.jpg"
POST TO INSTAGRAM image, "Summer sale! 50% off everything ☀️ #Sale #Summer"
POST TO LINKEDIN image, "We're offering exclusive discounts to our business partners."
POST TO TWITTER image, "FLASH SALE: 50% off for the next 24 hours! 🔥"
```
## Scheduled Posting
Schedule posts for future publication:
```bas
POST TO INSTAGRAM AT "2025-02-14 09:00" image, "Happy Valentine's Day! ❤️"
POST TO FACEBOOK AT "2025-03-01 10:00:00" image, "March is here!"
```
### Campaign Scheduling
```bas
posts = [
#{date: "2025-02-01 09:00", caption: "Week 1: Introduction"},
#{date: "2025-02-08 09:00", caption: "Week 2: Deep Dive"},
#{date: "2025-02-15 09:00", caption: "Week 3: Advanced Tips"},
#{date: "2025-02-22 09:00", caption: "Week 4: Conclusion"}
]
FOR EACH post IN posts
POST TO "instagram,linkedin" AT post.date "/campaign/week" + i + ".png", post.caption
NEXT
```
## Platform-Specific Features
### Instagram
```bas
POST TO INSTAGRAM image, caption
POST TO INSTAGRAM video, caption
POST TO INSTAGRAM [image1, image2, image3], "Carousel post!"
```
### Facebook
```bas
POST TO FACEBOOK text
POST TO FACEBOOK image, caption
POST TO FACEBOOK link, description
```
### LinkedIn
```bas
POST TO LINKEDIN text
POST TO LINKEDIN image, caption
POST TO LINKEDIN article_url, commentary
```
### Twitter/X
```bas
POST TO TWITTER text
POST TO TWITTER image, text
POST TO TWITTER [image1, image2, image3, image4], text
```
### Bluesky
```bas
POST TO BLUESKY text
POST TO BLUESKY image, text
POST TO BLUESKY [image1, image2, image3, image4], text
```
### Threads
```bas
POST TO THREADS text
POST TO THREADS image, caption
```
### Discord
```bas
POST TO DISCORD text
POST TO DISCORD image, message
embed = #{
title: "New Release",
description: "Version 2.0 is here!",
color: 5814783,
fields: [
#{name: "Features", value: "New dashboard, API improvements"},
#{name: "Download", value: "https://example.com/download"}
]
}
POST TO DISCORD embed
```
### TikTok
```bas
video = "/videos/dance.mp4"
POST TO TIKTOK video, "Check out this tutorial! #Tutorial #HowTo"
```
### YouTube
```bas
video = "/videos/full-tutorial.mp4"
POST TO YOUTUBE video, "Complete Guide to Automation"
POST TO YOUTUBE "community", "What topics should we cover next? 🤔"
```
### Pinterest
```bas
POST TO PINTEREST image, "DIY Home Decor Ideas | Save for later!"
POST TO PINTEREST image, caption, board_name
```
### Reddit
```bas
POST TO REDDIT "r/programming", "title", "text content"
POST TO REDDIT "r/pics", "Check this out!", image
```
### WeChat
```bas
POST TO WECHAT text
POST TO WECHAT article_title, article_content, cover_image
```
### Snapchat
```bas
POST TO SNAPCHAT image
POST TO SNAPCHAT video
```
## Return Value
Returns a post identifier that can be used for metrics or deletion:
```bas
post_id = POST TO INSTAGRAM image, caption
SET BOT MEMORY "latest_instagram_post", post_id
metrics = GET INSTAGRAM METRICS post_id
TALK "Post received " + metrics.likes + " likes"
```
## Examples
### Daily Content Automation
```bas
SET SCHEDULE "every day at 10am"
day_of_week = WEEKDAY(NOW())
content = [
#{image: "/content/monday.png", caption: "Monday motivation! 💪"},
#{image: "/content/tuesday.png", caption: "Tech Tuesday tip 🔧"},
#{image: "/content/wednesday.png", caption: "Midweek check-in ✅"},
#{image: "/content/thursday.png", caption: "Throwback Thursday 📸"},
#{image: "/content/friday.png", caption: "Friday feels! 🎉"}
]
IF day_of_week >= 1 AND day_of_week <= 5 THEN
today = content[day_of_week - 1]
POST TO "instagram,facebook,linkedin" today.image, today.caption
END IF
```
### Product Launch Campaign
```bas
launch_image = "/products/new-product.jpg"
launch_date = "2025-03-15 09:00"
POST TO INSTAGRAM AT launch_date launch_image, "🚀 IT'S HERE! Our most requested feature is now live. Link in bio! #Launch #NewProduct"
POST TO TWITTER AT launch_date launch_image, "🚀 The wait is over! Check out our newest feature: [link] #ProductLaunch"
POST TO LINKEDIN AT launch_date launch_image, "We're excited to announce the launch of our newest innovation. After months of development, we're proud to share..."
POST TO FACEBOOK AT launch_date launch_image, "🎉 Big announcement! We just launched something amazing. Head to our website to learn more!"
TALK "Launch campaign scheduled for " + launch_date
```
### Customer Testimonial Posts
```bas
ON FORM SUBMIT "testimonial"
IF fields.share_permission = "yes" THEN
quote = fields.testimonial
name = fields.name
company = fields.company
caption = "\"" + quote + "\" - " + name + ", " + company + " ⭐️ #CustomerLove #Testimonial"
template_image = FILL "testimonial-template.png", #{quote: quote, name: name, company: company}
POST TO "linkedin,twitter" template_image, caption
TALK "Thank you for sharing your experience!"
END IF
END ON
```
### Engagement-Based Reposting
```bas
SET SCHEDULE "every sunday at 8pm"
posts = GET INSTAGRAM POSTS
best_post = NULL
best_engagement = 0
FOR EACH post IN posts
IF DATEDIFF("day", post.created_at, NOW()) <= 90 THEN
metrics = GET INSTAGRAM METRICS post.id
engagement = metrics.likes + metrics.comments * 2
IF engagement > best_engagement THEN
best_engagement = engagement
best_post = post
END IF
END IF
NEXT
IF best_post != NULL THEN
POST TO "facebook,linkedin" best_post.image, "In case you missed it: " + best_post.caption
END IF
```
## Configuration
Add platform credentials to your bot's `config.csv`:
```csv
key,value
bluesky-handle,your.handle.bsky.social
bluesky-app-password,your-app-password
threads-access-token,your-threads-token
discord-bot-token,your-discord-token
discord-channel-id,your-channel-id
tiktok-access-token,your-tiktok-token
youtube-api-key,your-youtube-key
pinterest-access-token,your-pinterest-token
reddit-client-id,your-reddit-client-id
reddit-client-secret,your-reddit-secret
wechat-app-id,your-wechat-app-id
wechat-app-secret,your-wechat-secret
snapchat-access-token,your-snapchat-token
```
## Error Handling
```bas
ON ERROR RESUME NEXT
post_id = POST TO INSTAGRAM image, caption
IF ERROR THEN
error_msg = ERROR MESSAGE
SEND MAIL TO "admin@company.com" SUBJECT "Post Failed" BODY error_msg
TALK "Sorry, I couldn't post right now. The team has been notified."
ELSE
TALK "Posted successfully!"
SET BOT MEMORY "last_post", post_id
END IF
CLEAR ERROR
```
## Best Practices
**Tailor content per platform.** What works on LinkedIn may not work on TikTok. Adjust tone, length, and format accordingly.
**Respect rate limits.** Platforms enforce posting limits. Space out posts and avoid bulk operations.
**Use scheduling wisely.** Analyze when your audience is most active and schedule posts accordingly.
**Store post IDs.** Save identifiers for later metrics retrieval or content management.
**Handle errors gracefully.** Network issues and API changes happen. Implement proper error handling.
**Test before campaigns.** Always test posts to a single platform before launching multi-platform campaigns.
## See Also
- [Social Media Keywords](./keywords-social-media.md) - Platform metrics and management
- [SET SCHEDULE](./keyword-set-schedule.md) - Automate posting schedules
- [FILL](./keyword-fill.md) - Generate images from templates
- [SET BOT MEMORY](./keyword-set-bot-memory.md) - Store post tracking data
- [ON ERROR](./keyword-on-error.md) - Error handling

3
src/08-config/whatsapp-channel.md
View file

@ -371,9 +371,12 @@ END IF
| Error Code | Meaning | Solution |
|------------|---------|----------|
| 130472 | User's number is part of an experiment | The user is in a WhatsApp beta test or Meta is testing new features on their account. Message delivery is temporarily blocked during these tests. Wait and retry later. |
| 131026 | Message undeliverable | The phone number may be invalid, the user may have blocked your business number, deleted their WhatsApp account, or there are temporary network issues. This is usually a permanent error for that specific number. |
| 131030 | User not on WhatsApp | Verify phone number |
| 131047 | Re-engagement required | Send template message |
| 131048 | Spam rate limit | Reduce message frequency |
| 131049 | Message not delivered to maintain healthy ecosystem engagement | You are sending too many messages too quickly, or WhatsApp detected spam-like behavior. This is a temporary rate limit - reduce your sending frequency and implement proper throttling. |
| 131051 | Unsupported message type | Check message format |
| 131052 | Media download failed | Verify media URL |
| 132000 | Template not found | Check template name |

68
src/10-rest/files-api.md
View file

@ -6,7 +6,7 @@ Complete file and document management operations including upload, download, cop
The Files API provides comprehensive file management capabilities built on top of S3-compatible storage. All file operations support both single files and folders with recursive operations.
**Base Path**: `/files`
**Base Path**: `/api/files`
## Authentication
@ -22,7 +22,7 @@ Authorization: Bearer <token>
List files and folders in a bucket or path.
**Endpoint**: `GET /files/list`
**Endpoint**: `GET /api/files/list`
**Query Parameters**:
- `bucket` (optional) - Bucket name
@ -55,7 +55,7 @@ List files and folders in a bucket or path.
**Example**:
```bash
curl -X GET "http://localhost:3000/files/list?bucket=my-bucket&path=/documents" \
curl -X GET "http://localhost:3000/api/files/list?bucket=my-bucket&path=/documents" \
-H "Authorization: Bearer <token>"
```
@ -63,7 +63,7 @@ curl -X GET "http://localhost:3000/files/list?bucket=my-bucket&path=/documents"
Read file content from storage.
**Endpoint**: `POST /files/read`
**Endpoint**: `POST /api/files/read`
**Request Body**:
```json
@ -82,7 +82,7 @@ Read file content from storage.
**Example**:
```bash
curl -X POST "http://localhost:3000/files/read" \
curl -X POST "http://localhost:3000/api/files/read" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"bucket":"my-bucket","path":"/file.txt"}'
@ -92,15 +92,15 @@ curl -X POST "http://localhost:3000/files/read" \
Alias for read file with alternative naming.
**Endpoint**: `POST /files/getContents`
**Endpoint**: `POST /api/files/getContents`
Same parameters and response as `/files/read`.
Same parameters and response as `/api/files/read`.
### Write File
Write or update file content.
**Endpoint**: `POST /files/write`
**Endpoint**: `POST /api/files/write`
**Request Body**:
```json
@ -123,15 +123,15 @@ Write or update file content.
Alias for write file.
**Endpoint**: `POST /files/save`
**Endpoint**: `POST /api/files/save`
Same parameters and response as `/files/write`.
Same parameters and response as `/api/files/write`.
### Upload File
Upload file to storage.
**Endpoint**: `POST /files/upload`
**Endpoint**: `POST /api/files/upload`
**Request Body**:
```json
@ -154,7 +154,7 @@ Upload file to storage.
Download file from storage.
**Endpoint**: `POST /files/download`
**Endpoint**: `POST /api/files/download`
**Request Body**:
```json
@ -175,7 +175,7 @@ Download file from storage.
Copy file or folder to another location.
**Endpoint**: `POST /files/copy`
**Endpoint**: `POST /api/files/copy`
**Request Body**:
```json
@ -199,7 +199,7 @@ Copy file or folder to another location.
Move file or folder to another location.
**Endpoint**: `POST /files/move`
**Endpoint**: `POST /api/files/move`
**Request Body**:
```json
@ -225,7 +225,7 @@ Move file or folder to another location.
Delete file or folder.
**Endpoint**: `POST /files/delete`
**Endpoint**: `POST /api/files/delete`
**Request Body**:
```json
@ -249,7 +249,7 @@ Delete file or folder.
Create a new folder.
**Endpoint**: `POST /files/createFolder`
**Endpoint**: `POST /api/files/createFolder`
**Request Body**:
```json
@ -268,13 +268,13 @@ Create a new folder.
}
```
**Alternative Endpoint**: `POST /files/create-folder` (dash notation)
**Alternative Endpoint**: `POST /api/files/create-folder` (dash notation)
### List Folder Contents
List contents of a specific folder.
**Endpoint**: `POST /files/dirFolder`
**Endpoint**: `POST /api/files/dirFolder`
**Request Body**:
```json
@ -304,7 +304,7 @@ List contents of a specific folder.
Search for files across buckets.
**Endpoint**: `GET /files/search`
**Endpoint**: `GET /api/files/search`
**Query Parameters**:
- `bucket` (optional) - Limit search to specific bucket
@ -327,7 +327,7 @@ Search for files across buckets.
**Example**:
```bash
curl -X GET "http://localhost:3000/files/search?query=report&file_type=.pdf" \
curl -X GET "http://localhost:3000/api/files/search?query=report&file_type=.pdf" \
-H "Authorization: Bearer <token>"
```
@ -335,7 +335,7 @@ curl -X GET "http://localhost:3000/files/search?query=report&file_type=.pdf" \
Get recently modified files.
**Endpoint**: `GET /files/recent`
**Endpoint**: `GET /api/files/recent`
**Query Parameters**:
- `bucket` (optional) - Filter by bucket
@ -360,7 +360,7 @@ Get recently modified files.
List user's favorite files.
**Endpoint**: `GET /files/favorite`
**Endpoint**: `GET /api/files/favorite`
**Response**:
```json
@ -375,7 +375,7 @@ List user's favorite files.
Share folder with other users.
**Endpoint**: `POST /files/shareFolder`
**Endpoint**: `POST /api/files/shareFolder`
**Request Body**:
```json
@ -400,7 +400,7 @@ Share folder with other users.
Get files and folders shared with user.
**Endpoint**: `GET /files/shared`
**Endpoint**: `GET /api/files/shared`
**Response**:
```json
@ -411,7 +411,7 @@ Get files and folders shared with user.
Get permissions for file or folder.
**Endpoint**: `GET /files/permissions`
**Endpoint**: `GET /api/files/permissions`
**Query Parameters**:
- `bucket` (required) - Bucket name
@ -438,7 +438,7 @@ Get permissions for file or folder.
Check storage quota information.
**Endpoint**: `GET /files/quota`
**Endpoint**: `GET /api/files/quota`
**Response**:
```json
@ -452,7 +452,7 @@ Check storage quota information.
**Example**:
```bash
curl -X GET "http://localhost:3000/files/quota" \
curl -X GET "http://localhost:3000/api/files/quota" \
-H "Authorization: Bearer <token>"
```
@ -462,7 +462,7 @@ curl -X GET "http://localhost:3000/files/quota" \
Get current synchronization status.
**Endpoint**: `GET /files/sync/status`
**Endpoint**: `GET /api/files/sync/status`
**Response**:
```json
@ -484,7 +484,7 @@ Get current synchronization status.
Start file synchronization.
**Endpoint**: `POST /files/sync/start`
**Endpoint**: `POST /api/files/sync/start`
**Response**:
```json
@ -498,7 +498,7 @@ Start file synchronization.
Stop file synchronization.
**Endpoint**: `POST /files/sync/stop`
**Endpoint**: `POST /api/files/sync/stop`
**Response**:
```json
@ -570,7 +570,7 @@ Status: 500
```javascript
// 1. Upload file
const uploadResponse = await fetch('/files/upload', {
const uploadResponse = await fetch('/api/files/upload', {
method: 'POST',
headers: {
'Authorization': 'Bearer token',
@ -584,7 +584,7 @@ const uploadResponse = await fetch('/files/upload', {
});
// 2. Share with team
const shareResponse = await fetch('/files/shareFolder', {
const shareResponse = await fetch('/api/files/shareFolder', {
method: 'POST',
headers: {
'Authorization': 'Bearer token',
@ -609,7 +609,7 @@ import requests
# Search for files
response = requests.get(
'http://localhost:3000/files/search',
'http://localhost:3000/api/files/search',
params={'query': 'report', 'file_type': '.pdf'},
headers={'Authorization': 'Bearer token'}
)
@ -619,7 +619,7 @@ files = response.json()
# Download first result
if files:
download_response = requests.post(
'http://localhost:3000/files/download',
'http://localhost:3000/api/files/download',
json={
'bucket': 'my-bucket',
'path': files[0]['path']

668
src/11-features/channel-setup.md Normal file
View file

@ -0,0 +1,668 @@
# Channel Setup Guide
This guide provides step-by-step instructions for connecting General Bots to various messaging platforms and social media channels.
## Overview
General Bots supports multiple communication channels:
| Category | Channels |
|----------|----------|
| Social Media | Instagram, Facebook, Twitter/X, LinkedIn, Bluesky, Threads, TikTok, YouTube, Pinterest, Reddit, Snapchat |
| Messaging | WhatsApp, Telegram, Discord, Microsoft Teams, WeChat, Twilio SMS |
| Email | Gmail, Outlook, Custom SMTP |
## Configuration Methods
Channels can be configured through:
1. **Settings UI** - Navigate to Settings → Accounts
2. **config.csv** - Add credentials to your bot's configuration
3. **Environment Variables** - Set system-wide defaults
4. **API** - Programmatic configuration
## Social Media Channels
### Instagram
**Requirements:**
- Instagram Business or Creator account
- Facebook Page connected to Instagram
- Facebook Developer App
**Setup Steps:**
1. Create a Facebook Developer App at developers.facebook.com
2. Add Instagram Graph API product
3. Connect your Instagram Business account
4. Generate long-lived access token
**Configuration:**
```csv
key,value
instagram-access-token,your-long-lived-token
instagram-account-id,your-instagram-account-id
instagram-page-id,your-facebook-page-id
```
**Permissions Required:**
- `instagram_basic`
- `instagram_content_publish`
- `instagram_manage_comments`
- `instagram_manage_insights`
**Rate Limits:**
- 25 posts per 24 hours
- 200 API calls per hour
---
### Facebook
**Requirements:**
- Facebook Page
- Facebook Developer App
**Setup Steps:**
1. Create a Facebook Developer App
2. Add Facebook Login and Pages API products
3. Generate Page Access Token
4. Request page_publish permissions
**Configuration:**
```csv
key,value
facebook-access-token,your-page-access-token
facebook-page-id,your-page-id
facebook-app-id,your-app-id
facebook-app-secret,your-app-secret
```
**Permissions Required:**
- `pages_manage_posts`
- `pages_read_engagement`
- `pages_show_list`
---
### Twitter / X
**Requirements:**
- Twitter Developer Account
- Elevated or Basic API access
**Setup Steps:**
1. Apply for Twitter Developer Account at developer.twitter.com
2. Create a Project and App
3. Generate API keys and access tokens
4. Enable OAuth 1.0a with read and write permissions
**Configuration:**
```csv
key,value
twitter-api-key,your-api-key
twitter-api-secret,your-api-secret
twitter-access-token,your-access-token
twitter-access-secret,your-access-token-secret
twitter-bearer-token,your-bearer-token
```
**Rate Limits:**
- Free tier: 1,500 tweets/month
- Basic tier: 3,000 tweets/month
- Pro tier: 300,000 tweets/month
---
### LinkedIn
**Requirements:**
- LinkedIn Page
- LinkedIn Marketing Developer Platform access
**Setup Steps:**
1. Create app at linkedin.com/developers
2. Request Marketing Developer Platform access
3. Add products: Share on LinkedIn, Marketing Developer Platform
4. Generate OAuth 2.0 access token
**Configuration:**
```csv
key,value
linkedin-client-id,your-client-id
linkedin-client-secret,your-client-secret
linkedin-access-token,your-access-token
linkedin-organization-id,your-organization-urn
```
**Permissions Required:**
- `w_organization_social`
- `r_organization_social`
- `rw_organization_admin`
---
### Bluesky
**Requirements:**
- Bluesky account
- App password (not your main password)
**Setup Steps:**
1. Log into Bluesky
2. Go to Settings → App Passwords
3. Create new app password
4. Note your handle (e.g., yourname.bsky.social)
**Configuration:**
```csv
key,value
bluesky-handle,yourname.bsky.social
bluesky-app-password,xxxx-xxxx-xxxx-xxxx
```
**Rate Limits:**
- 1,666 posts per day
- 5,000 API calls per hour
---
### Threads
**Requirements:**
- Threads account (linked to Instagram)
- Meta Developer App with Threads API access
**Setup Steps:**
1. Use your existing Meta Developer App
2. Add Threads API product
3. Generate Threads access token
4. Link your Threads account
**Configuration:**
```csv
key,value
threads-access-token,your-threads-token
threads-user-id,your-threads-user-id
```
**Rate Limits:**
- 250 posts per 24 hours
---
### TikTok
**Requirements:**
- TikTok Business Account
- TikTok Developer App
**Setup Steps:**
1. Register at developers.tiktok.com
2. Create an app
3. Apply for Content Posting API access
4. Complete OAuth flow to get access token
**Configuration:**
```csv
key,value
tiktok-client-key,your-client-key
tiktok-client-secret,your-client-secret
tiktok-access-token,your-access-token
tiktok-refresh-token,your-refresh-token
```
**Permissions Required:**
- `video.upload`
- `video.publish`
**Notes:**
- Videos must be uploaded before publishing
- Supports direct upload or URL pull
---
### YouTube
**Requirements:**
- YouTube Channel
- Google Cloud Project
**Setup Steps:**
1. Create project at console.cloud.google.com
2. Enable YouTube Data API v3
3. Create OAuth 2.0 credentials
4. Complete OAuth consent screen setup
5. Generate refresh token
**Configuration:**
```csv
key,value
youtube-client-id,your-client-id
youtube-client-secret,your-client-secret
youtube-refresh-token,your-refresh-token
youtube-channel-id,your-channel-id
```
**Permissions Required:**
- `youtube.upload`
- `youtube.force-ssl`
**Quota:**
- 10,000 units per day (default)
- Video upload: 1,600 units
---
### Pinterest
**Requirements:**
- Pinterest Business Account
- Pinterest Developer App
**Setup Steps:**
1. Apply at developers.pinterest.com
2. Create an app
3. Request access to Pins API
4. Generate access token
**Configuration:**
```csv
key,value
pinterest-app-id,your-app-id
pinterest-app-secret,your-app-secret
pinterest-access-token,your-access-token
```
**Rate Limits:**
- 1,000 API calls per minute
- 200 Pins per hour
---
### Reddit
**Requirements:**
- Reddit Account
- Reddit Developer App
**Setup Steps:**
1. Go to reddit.com/prefs/apps
2. Create script or web application
3. Note client ID (under app name) and secret
**Configuration:**
```csv
key,value
reddit-client-id,your-client-id
reddit-client-secret,your-client-secret
reddit-username,your-username
reddit-password,your-password
reddit-user-agent,GeneralBots/1.0
```
**Rate Limits:**
- 60 requests per minute
- 10 posts per subreddit per day
---
### Snapchat
**Requirements:**
- Snapchat Business Account
- Snap Marketing API access
**Setup Steps:**
1. Create account at business.snapchat.com
2. Apply for Marketing API access
3. Create OAuth app
4. Generate access token
**Configuration:**
```csv
key,value
snapchat-client-id,your-client-id
snapchat-client-secret,your-client-secret
snapchat-access-token,your-access-token
snapchat-refresh-token,your-refresh-token
snapchat-ad-account-id,your-ad-account-id
```
---
## Messaging Channels
### WhatsApp Business
**Requirements:**
- WhatsApp Business Account
- Meta Business verification
**Setup Steps:**
1. Set up Meta Business Suite
2. Add WhatsApp to your Meta Developer App
3. Configure webhook URL
4. Get phone number ID and access token
**Configuration:**
```csv
key,value
whatsapp-phone-number-id,your-phone-number-id
whatsapp-access-token,your-access-token
whatsapp-business-account-id,your-business-account-id
whatsapp-webhook-verify-token,your-verify-token
```
**Webhook URL:** `https://your-domain.com/api/channels/whatsapp/webhook`
---
### Telegram
**Requirements:**
- Telegram Bot (created via BotFather)
**Setup Steps:**
1. Message @BotFather on Telegram
2. Send `/newbot` and follow prompts
3. Copy the bot token
4. Set webhook URL
**Configuration:**
```csv
key,value
telegram-bot-token,your-bot-token
telegram-webhook-secret,your-webhook-secret
```
**Set Webhook:**
```bash
curl -X POST "https://api.telegram.org/bot<token>/setWebhook" \
-d "url=https://your-domain.com/api/channels/telegram/webhook"
```
---
### Discord
**Requirements:**
- Discord Server (with admin permissions)
- Discord Developer Application
**Setup Steps:**
1. Create app at discord.com/developers/applications
2. Create a Bot
3. Copy bot token
4. Generate invite URL with required permissions
5. Add bot to your server
**Configuration:**
```csv
key,value
discord-bot-token,your-bot-token
discord-application-id,your-application-id
discord-guild-id,your-server-id
discord-channel-id,default-channel-id
```
**Required Bot Permissions:**
- Send Messages
- Embed Links
- Attach Files
- Read Message History
---
### Microsoft Teams
**Requirements:**
- Microsoft 365 account
- Azure Active Directory app registration
**Setup Steps:**
1. Register app in Azure Portal
2. Add Teams permissions
3. Create Teams app manifest
4. Upload to Teams Admin Center
**Configuration:**
```csv
key,value
teams-app-id,your-app-id
teams-app-password,your-app-password
teams-tenant-id,your-tenant-id
```
---
### WeChat
**Requirements:**
- WeChat Official Account (Service or Subscription)
- ICP license (for China operations)
**Setup Steps:**
1. Register at mp.weixin.qq.com
2. Complete verification
3. Configure server settings
4. Get AppID and AppSecret
**Configuration:**
```csv
key,value
wechat-app-id,your-app-id
wechat-app-secret,your-app-secret
wechat-token,your-verification-token
wechat-encoding-aes-key,your-encoding-key
```
---
### Twilio SMS
**Requirements:**
- Twilio Account
- Phone number with SMS capability
**Setup Steps:**
1. Create account at twilio.com
2. Get Account SID and Auth Token
3. Purchase or port a phone number
4. Configure webhook URL
**Configuration:**
```csv
key,value
twilio-account-sid,your-account-sid
twilio-auth-token,your-auth-token
twilio-phone-number,+1234567890
twilio-messaging-service-sid,optional-messaging-service
```
**Webhook URL:** `https://your-domain.com/api/channels/twilio/webhook`
---
## Email Channels
### Gmail / Google Workspace
**Setup Steps:**
1. Enable Gmail API in Google Cloud Console
2. Create OAuth 2.0 credentials
3. Complete consent screen
4. Generate refresh token
**Configuration:**
```csv
key,value
gmail-client-id,your-client-id
gmail-client-secret,your-client-secret
gmail-refresh-token,your-refresh-token
gmail-user-email,your-email@gmail.com
```
---
### Outlook / Office 365
**Setup Steps:**
1. Register app in Azure Portal
2. Add Mail.Send permission
3. Grant admin consent
4. Generate access token
**Configuration:**
```csv
key,value
outlook-client-id,your-client-id
outlook-client-secret,your-client-secret
outlook-tenant-id,your-tenant-id
outlook-user-email,your-email@company.com
```
---
### Custom SMTP
**Configuration:**
```csv
key,value
smtp-host,smtp.example.com
smtp-port,587
smtp-username,your-username
smtp-password,your-password
smtp-from-address,noreply@example.com
smtp-from-name,Your Company
smtp-security,tls
```
---
## Testing Your Configuration
### Verify Connection
```http
GET /api/channels/{channel}/status
Authorization: Bearer <token>
```
Response:
```json
{
"channel": "instagram",
"connected": true,
"account": "@youraccount",
"permissions": ["read", "write"],
"rate_limit_remaining": 180,
"last_sync": "2025-01-21T10:00:00Z"
}
```
### Send Test Message
```http
POST /api/channels/{channel}/test
Authorization: Bearer <token>
Content-Type: application/json
{
"message": "Hello from General Bots!"
}
```
---
## Troubleshooting
### Common Issues
**Invalid Token**
- Tokens expire; regenerate and update
- Check token permissions match requirements
**Rate Limited**
- Reduce posting frequency
- Implement exponential backoff
- Consider upgrading API tier
**Webhook Not Receiving**
- Verify URL is publicly accessible
- Check SSL certificate is valid
- Confirm webhook is registered with platform
**Permission Denied**
- Review required permissions list
- Reauthorize with correct scopes
- Check app review status
### Debug Logging
Enable channel debug logging:
```bash
CHANNEL_DEBUG=true
CHANNEL_LOG_LEVEL=debug
```
---
## Security Best Practices
1. **Store secrets securely** - Use environment variables or secret management
2. **Rotate tokens regularly** - Set reminders for token refresh
3. **Use webhook signatures** - Validate incoming webhook requests
4. **Limit permissions** - Request only needed scopes
5. **Monitor usage** - Track API calls and rate limits
6. **Audit access** - Review connected accounts periodically
---
## Related Topics
- [POST TO Keyword](../06-gbdialog/keyword-post-to.md) - Posting from BASIC
- [Social Media Keywords](../06-gbdialog/keywords-social-media.md) - Full social media reference
- [Multi-Channel Architecture](./channels.md) - System design
- [Accounts Settings](../08-config/accounts.md) - UI configuration

351
src/11-features/project-app.md Normal file
View file

@ -0,0 +1,351 @@
# Project App User Guide
The Project app is a comprehensive project management tool built into General Bots, providing Gantt charts, task dependencies, resource management, and critical path analysis.
## Overview
The Project app enables you to:
- Create and manage projects with tasks and milestones
- Visualize timelines with interactive Gantt charts
- Define task dependencies and relationships
- Allocate and track resource assignments
- Calculate critical paths for schedule optimization
- Track progress and completion status
## Getting Started
### Creating a Project
1. Navigate to **Apps** → **Project**
2. Click **New Project**
3. Enter project details:
- **Name**: Project title
- **Start Date**: When work begins
- **End Date**: Target completion (optional)
- **Description**: Project overview
### Project Structure
Projects contain:
```
Project
├── Summary Tasks (Phases)
│ ├── Tasks
│ │ ├── Subtasks
│ │ └── Milestones
│ └── More Tasks
└── Milestones
```
## Working with Tasks
### Creating Tasks
Click **Add Task** or press `Enter` on the last task row:
| Field | Description |
|-------|-------------|
| Name | Task title |
| Duration | Time to complete (e.g., "5 days") |
| Start | Task start date |
| Finish | Task end date (calculated or manual) |
| Predecessors | Tasks that must complete first |
| Resources | Assigned team members |
| Progress | Completion percentage (0-100%) |
### Task Types
| Type | Icon | Description |
|------|------|-------------|
| Task | ▬ | Standard work item |
| Milestone | ◆ | Zero-duration checkpoint |
| Summary | ▬▬ | Container for subtasks |
### Duration Formats
| Format | Example | Result |
|--------|---------|--------|
| Days | `5d` or `5 days` | 5 working days |
| Weeks | `2w` or `2 weeks` | 10 working days |
| Hours | `16h` or `16 hours` | 2 working days |
| Minutes | `240m` | 4 hours |
## Gantt Chart
### Navigation
- **Scroll**: Mouse wheel or drag timeline
- **Zoom**: Ctrl + scroll or zoom buttons
- **Today**: Click "Today" to center on current date
### Time Scales
| View | Shows | Best For |
|------|-------|----------|
| Day | Hours | Short tasks |
| Week | Days | Sprint planning |
| Month | Weeks | Project overview |
| Quarter | Months | Portfolio view |
| Year | Quarters | Long-term planning |
### Bar Colors
| Color | Meaning |
|-------|---------|
| Blue | Normal task |
| Green | Completed task |
| Red | Critical path task |
| Orange | Behind schedule |
| Purple | Milestone |
| Gray | Summary task |
## Task Dependencies
### Dependency Types
| Type | Code | Description |
|------|------|-------------|
| Finish-to-Start | FS | B starts when A finishes |
| Start-to-Start | SS | B starts when A starts |
| Finish-to-Finish | FF | B finishes when A finishes |
| Start-to-Finish | SF | B finishes when A starts |
### Creating Dependencies
**Method 1: Predecessors Column**
Enter task numbers in the Predecessors column:
```
2 → Task 2 must finish first (FS)
2FS → Same as above (explicit)
2SS → Start when task 2 starts
2FF+2d → Finish when task 2 finishes, plus 2 days
3,5 → Both tasks 3 and 5 must finish
```
**Method 2: Drag in Gantt**
1. Hover over a task bar
2. Drag from the end connector
3. Drop on another task
### Lag and Lead Time
| Syntax | Meaning |
|--------|---------|
| `2FS+3d` | Start 3 days after task 2 finishes |
| `2FS-2d` | Start 2 days before task 2 finishes |
| `2SS+1w` | Start 1 week after task 2 starts |
## Resource Management
### Adding Resources
1. Click **Resources** tab
2. Click **Add Resource**
3. Enter resource details:
- Name
- Type (Work, Material, Cost)
- Rate (hourly/daily cost)
- Availability (percentage)
### Resource Types
| Type | Use Case | Unit |
|------|----------|------|
| Work | People | Hours |
| Material | Consumables | Quantity |
| Cost | Fixed costs | Currency |
### Assigning Resources
In the Resources column, enter:
```
John → 100% allocation
John[50%] → 50% allocation
John,Sarah → Two resources
John[50%],Sarah → Mixed allocations
```
### Resource Views
- **Resource Sheet**: List all resources with details
- **Resource Usage**: Time-phased work assignments
- **Resource Graph**: Visual workload chart
## Critical Path
### Understanding Critical Path
The critical path is the longest sequence of dependent tasks that determines the minimum project duration. Tasks on the critical path have zero float—any delay extends the project.
### Viewing Critical Path
1. Click **Format** → **Critical Path**
2. Critical tasks appear in red
3. Hover for float information
### Critical Path Analysis
| Metric | Description |
|--------|-------------|
| Total Float | Time a task can slip without delaying project |
| Free Float | Time a task can slip without delaying successors |
| Critical | Float = 0, on critical path |
## Timeline View
The Timeline view provides a high-level summary:
1. Click **View** → **Timeline**
2. Drag tasks to add to timeline
3. Resize to set date range
### Timeline Features
- Executive summary view
- Milestone emphasis
- Export to PowerPoint
- Shareable as image
## Progress Tracking
### Updating Progress
**Method 1: Percentage**
Enter completion percentage (0-100%) in Progress column.
**Method 2: Actual Dates**
- Actual Start: When work actually began
- Actual Finish: When work actually completed
**Method 3: Remaining Work**
Enter remaining hours/days to completion.
### Status Indicators
| Indicator | Meaning |
|-----------|---------|
| ✓ | Complete (100%) |
| ● | In Progress |
| ○ | Not Started |
| ⚠ | Behind Schedule |
| 🔴 | Critical & Late |
### Baseline Comparison
1. Set baseline: **Project** → **Set Baseline**
2. View variance: **View** → **Tracking Gantt**
3. Gray bars show original plan
## Reports
### Built-in Reports
| Report | Shows |
|--------|-------|
| Project Summary | Overall status, milestones |
| Task Status | All tasks with progress |
| Resource Overview | Assignments and workload |
| Cost Report | Budget vs actual costs |
| Critical Tasks | Critical path analysis |
### Generating Reports
1. Click **Reports**
2. Select report type
3. Choose date range
4. Click **Generate**
### Export Options
- PDF
- Excel
- CSV
- Image (PNG)
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Enter` | Add new task |
| `Tab` | Indent task (make subtask) |
| `Shift+Tab` | Outdent task |
| `Ctrl+Z` | Undo |
| `Ctrl+Y` | Redo |
| `Delete` | Delete selected |
| `Ctrl+C` | Copy task |
| `Ctrl+V` | Paste task |
| `F5` | Go to date |
| `Ctrl+G` | Go to task |
## BASIC Integration
### Creating Projects from BASIC
```bas
project = CREATE PROJECT "Website Redesign"
project.start_date = "2025-02-01"
project.description = "Complete website overhaul"
task1 = CREATE TASK project, "Design Phase"
task1.duration = "10 days"
task2 = CREATE TASK project, "Development"
task2.duration = "20 days"
task2.predecessors = task1.id
milestone = CREATE MILESTONE project, "Launch"
milestone.predecessors = task2.id
```
### Querying Projects
```bas
projects = GET FROM projects WHERE status = "active"
FOR EACH project IN projects
tasks = GET FROM tasks WHERE project_id = project.id
TALK "Project: " + project.name + " has " + LEN(tasks) + " tasks"
NEXT
```
## Tips and Best Practices
### Planning
1. **Start with milestones** - Define key deliverables first
2. **Work backwards** - From deadline to start
3. **Break down tasks** - No task longer than 2 weeks
4. **Identify dependencies** - What blocks what?
5. **Add buffer** - Include contingency time
### Execution
1. **Update regularly** - Daily or weekly progress
2. **Monitor critical path** - Watch for delays
3. **Rebalance resources** - Address overallocation
4. **Communicate changes** - Keep stakeholders informed
### Common Mistakes
| Mistake | Solution |
|---------|----------|
| Missing dependencies | Review task relationships |
| Over-allocated resources | Level workload |
| No milestones | Add checkpoints |
| Too much detail | Summarize minor tasks |
| No baseline | Set before execution |
## Related Topics
- [Task Management](./tasks.md) - Task app integration
- [Calendar Integration](./calendar.md) - Scheduling
- [Forms Integration](./forms.md) - Task intake forms
- [BASIC Reference](../06-gbdialog/keywords.md) - Automation keywords

467
src/11-features/whiteboard.md Normal file
View file

@ -0,0 +1,467 @@
# Meeting Whiteboard User Guide
The Meeting Whiteboard provides a collaborative canvas for real-time visual collaboration during meetings, enabling teams to sketch ideas, diagram workflows, and brainstorm together.
## Overview
The Whiteboard app enables you to:
- Draw freehand sketches and annotations
- Create shapes, diagrams, and flowcharts
- Add sticky notes and text labels
- Collaborate in real-time with meeting participants
- Export whiteboards as images or PDFs
- Save and revisit whiteboard sessions
## Getting Started
### Accessing the Whiteboard
**During a Meeting:**
1. Join a meeting in the Meet app
2. Click the **Whiteboard** button in the toolbar
3. A shared canvas opens for all participants
**Standalone Mode:**
1. Navigate to **Apps** → **Whiteboard**
2. Click **New Whiteboard**
3. Share the link to invite collaborators
### Canvas Basics
| Element | Description |
|---------|-------------|
| Canvas | Infinite drawing area |
| Toolbar | Tools on the left side |
| Properties | Settings on the right side |
| Zoom | Bottom-right controls |
| Participants | Avatars showing who's viewing |
## Drawing Tools
### Pen Tool
Freehand drawing with customizable settings:
| Setting | Options |
|---------|---------|
| Color | Any color |
| Size | 1-20 pixels |
| Opacity | 0-100% |
| Smoothing | Low, Medium, High |
**Keyboard Shortcut:** `P`
### Highlighter
Semi-transparent marker for emphasis:
- Automatic transparency (50%)
- Wide stroke for highlighting
- Colors: Yellow, Green, Pink, Blue
**Keyboard Shortcut:** `H`
### Eraser
Remove content from the canvas:
| Mode | Function |
|------|----------|
| Stroke | Erases entire strokes |
| Area | Erases within brush area |
**Keyboard Shortcut:** `E`
### Laser Pointer
Temporary pointer visible to all participants:
- Fades after 2 seconds
- Shows your cursor position
- Color matches your participant color
**Keyboard Shortcut:** `L`
## Shape Tools
### Basic Shapes
| Shape | Shortcut | Description |
|-------|----------|-------------|
| Rectangle | `R` | Boxes and containers |
| Ellipse | `O` | Circles and ovals |
| Triangle | `T` | Triangles |
| Line | `\` | Straight lines |
| Arrow | `A` | Directional arrows |
### Drawing Shapes
1. Select shape tool
2. Click and drag on canvas
3. Hold `Shift` for perfect proportions
4. Release to complete
### Shape Properties
| Property | Options |
|----------|---------|
| Fill | Solid, None, Pattern |
| Stroke | Color, Width, Style |
| Corners | Sharp, Rounded |
| Shadow | None, Light, Medium, Dark |
## Text and Notes
### Text Tool
Add text labels anywhere on the canvas:
1. Press `T` or select Text tool
2. Click on canvas
3. Type your text
4. Click outside to finish
**Text Settings:**
| Setting | Options |
|---------|---------|
| Font Size | 12-72pt |
| Font Weight | Normal, Bold |
| Alignment | Left, Center, Right |
| Color | Any color |
### Sticky Notes
Virtual post-it notes for ideas:
1. Press `N` or select Sticky Note
2. Click to place
3. Type content
4. Drag to reposition
**Sticky Note Colors:**
- Yellow (default)
- Pink
- Green
- Blue
- Purple
- Orange
## Connectors
### Creating Connectors
Link shapes to show relationships:
1. Select Connector tool (`C`)
2. Click on first shape
3. Click on second shape
4. Connector automatically routes
### Connector Types
| Type | Use Case |
|------|----------|
| Straight | Direct connection |
| Elbow | Right-angle routing |
| Curved | Smooth curves |
### Connector Endpoints
| Endpoint | Meaning |
|----------|---------|
| Arrow | Direction/flow |
| Circle | Connection point |
| Diamond | Decision |
| None | Simple connection |
## Collaboration Features
### Real-Time Sync
All changes sync instantly to participants:
- See others' cursors in real-time
- Watch drawing as it happens
- Automatic conflict resolution
### Participant Cursors
Each participant has a unique cursor:
- Name label follows cursor
- Color identifies participant
- Fades when inactive
### Follow Mode
Focus on a presenter:
1. Click a participant's avatar
2. Select **Follow**
3. Your view follows their canvas position
### Presence Indicators
| Indicator | Meaning |
|-----------|---------|
| Green dot | Active, drawing |
| Yellow dot | Viewing |
| Gray dot | Idle |
## Canvas Navigation
### Panning
Move around the canvas:
- **Mouse:** Middle-click drag or Space + drag
- **Trackpad:** Two-finger drag
- **Touch:** Two-finger drag
### Zooming
| Action | Method |
|--------|--------|
| Zoom In | `Ctrl/Cmd + +` or scroll up |
| Zoom Out | `Ctrl/Cmd + -` or scroll down |
| Fit to Screen | `Ctrl/Cmd + 0` |
| Zoom to Selection | `Ctrl/Cmd + 2` |
### Minimap
Overview of entire canvas:
1. Click minimap icon (bottom-right)
2. Blue rectangle shows current view
3. Click to jump to location
## Selection and Editing
### Selecting Objects
| Action | Method |
|--------|--------|
| Single select | Click object |
| Multi-select | Shift + click |
| Box select | Drag selection rectangle |
| Select all | `Ctrl/Cmd + A` |
### Transforming Objects
| Action | Method |
|--------|--------|
| Move | Drag selected object |
| Resize | Drag corner handles |
| Rotate | Drag rotation handle |
| Constrain | Hold Shift while transforming |
### Alignment
Align selected objects:
| Alignment | Shortcut |
|-----------|----------|
| Left | `Alt + L` |
| Center | `Alt + C` |
| Right | `Alt + R` |
| Top | `Alt + T` |
| Middle | `Alt + M` |
| Bottom | `Alt + B` |
### Distribution
Evenly space selected objects:
- **Distribute Horizontally:** `Alt + H`
- **Distribute Vertically:** `Alt + V`
## Layers and Organization
### Layer Order
| Action | Shortcut |
|--------|----------|
| Bring to Front | `Ctrl/Cmd + ]` |
| Send to Back | `Ctrl/Cmd + [` |
| Bring Forward | `Ctrl/Cmd + Shift + ]` |
| Send Backward | `Ctrl/Cmd + Shift + [` |
### Grouping
Combine objects:
1. Select multiple objects
2. Press `Ctrl/Cmd + G` to group
3. Press `Ctrl/Cmd + Shift + G` to ungroup
### Locking
Prevent accidental edits:
1. Select object
2. Right-click → **Lock**
3. Right-click → **Unlock** to edit again
## Templates
### Using Templates
Start with pre-built layouts:
1. Click **Templates** in toolbar
2. Browse categories:
- Brainstorming
- Flowcharts
- Mind Maps
- Retrospectives
- Kanban
- User Journey
3. Click to apply
### Saving Templates
Create reusable templates:
1. Design your whiteboard
2. Click **File** → **Save as Template**
3. Name and categorize
4. Template appears in your library
## Export and Sharing
### Export Formats
| Format | Use Case |
|--------|----------|
| PNG | High-quality image |
| JPEG | Smaller file size |
| SVG | Vector graphics |
| PDF | Document sharing |
### Export Options
| Option | Description |
|--------|-------------|
| Selection | Export only selected area |
| Entire Canvas | Export everything |
| Current View | Export visible area |
| With Background | Include canvas background |
### Sharing
| Method | Description |
|--------|-------------|
| Link | Share view-only or edit link |
| Embed | Embed in websites |
| Email | Send link via email |
## Undo and History
### Undo/Redo
| Action | Shortcut |
|--------|----------|
| Undo | `Ctrl/Cmd + Z` |
| Redo | `Ctrl/Cmd + Y` or `Ctrl/Cmd + Shift + Z` |
### Version History
1. Click **History** icon
2. Browse previous versions
3. Click to preview
4. **Restore** to revert
## Keyboard Shortcuts
### Tools
| Shortcut | Tool |
|----------|------|
| `V` | Select |
| `P` | Pen |
| `H` | Highlighter |
| `E` | Eraser |
| `T` | Text |
| `N` | Sticky Note |
| `R` | Rectangle |
| `O` | Ellipse |
| `A` | Arrow |
| `C` | Connector |
| `L` | Laser Pointer |
### Actions
| Shortcut | Action |
|----------|--------|
| `Ctrl/Cmd + Z` | Undo |
| `Ctrl/Cmd + Y` | Redo |
| `Ctrl/Cmd + C` | Copy |
| `Ctrl/Cmd + V` | Paste |
| `Ctrl/Cmd + D` | Duplicate |
| `Delete` | Delete selected |
| `Ctrl/Cmd + A` | Select all |
| `Ctrl/Cmd + G` | Group |
| `Escape` | Deselect / Cancel |
### Navigation
| Shortcut | Action |
|----------|--------|
| `Space + drag` | Pan canvas |
| `Ctrl/Cmd + +` | Zoom in |
| `Ctrl/Cmd + -` | Zoom out |
| `Ctrl/Cmd + 0` | Fit to screen |
| `Ctrl/Cmd + 1` | Zoom to 100% |
## Tips and Best Practices
### For Facilitators
1. **Prepare templates** - Set up structure before meeting
2. **Use frames** - Organize different activities
3. **Enable follow mode** - Guide participants' attention
4. **Use laser pointer** - Highlight without editing
5. **Save checkpoints** - Version history for reference
### For Participants
1. **Claim your color** - Identify your contributions
2. **Use sticky notes** - Quick idea capture
3. **Don't overlap** - Give space to others' work
4. **Use reactions** - Vote with emoji stamps
### Performance Tips
| Issue | Solution |
|-------|----------|
| Slow canvas | Reduce object count |
| Lag in sync | Check network connection |
| Export fails | Reduce canvas size |
## Integration with Meetings
### Starting from Meet
1. In Meet, click **More** → **Open Whiteboard**
2. Whiteboard opens for all participants
3. Whiteboard persists after meeting ends
### Whiteboard Recording
When meeting is recorded:
- Whiteboard activity is captured
- Playback shows drawing timeline
- Export includes whiteboard snapshots
## Related Topics
- [Meet App](./meet.md) - Video meetings
- [Tasks Integration](./tasks.md) - Create tasks from whiteboard
- [Drive Storage](./drive.md) - Whiteboard file storage
- [Export Options](./export.md) - Sharing and formats

58
src/12-auth/README.md
View file

@ -6,12 +6,28 @@ User authentication, permission management, and resource protection for botserve
botserver provides enterprise-grade security with flexible authentication options, granular permissions, and comprehensive rate limiting to prevent abuse.
## Initial Setup
When General Bots starts for the first time, it automatically creates an administrator account and displays the credentials in the console. See [Initial Setup & Bootstrap](./initial-setup.md) for details.
```
╔════════════════════════════════════════════════════════════╗
║ 🤖 GENERAL BOTS - INITIAL SETUP COMPLETE ║
╠════════════════════════════════════════════════════════════╣
║ Username: admin ║
║ Email: admin@localhost ║
║ Password: (displayed in console) ║
╚════════════════════════════════════════════════════════════╝
```
> **Important**: Save the password shown in your console during first startup. It will not be displayed again.
## Authentication Methods
| Method | Use Case |
|--------|----------|
| **Session Token** | Web/API access |
| **OAuth2/OIDC** | SSO integration |
| **OAuth2/OIDC** | SSO integration via Zitadel |
| **API Key** | Service accounts |
| **Bot Auth** | Bot-to-bot communication |
@ -28,21 +44,37 @@ END IF
## Security Features
- **Password Hashing**: Argon2 with secure defaults
- **Directory Service**: Zitadel handles all user identity management
- **No Password Storage**: Passwords never stored in General Bots
- **Session Management**: Cryptographic tokens, configurable expiry
- **Rate Limiting**: Per-user and global limits with HTTP 429 responses
- **System Limits**: Loop protection, file size limits, resource constraints
- **Audit Logging**: Track all authentication events
- **Encryption**: AES-GCM for data at rest
- **Organizations**: Multi-tenant support with org-based isolation
## Permission Levels
| Level | Access |
|-------|--------|
| `admin` | Full system access |
| `manager` | Bot management |
| `admin` | Full system access, user management |
| `org_owner` | Organization management |
| `bot_owner` | Bot configuration and deployment |
| `bot_operator` | Bot operation and monitoring |
| `user` | Standard access |
| `guest` | Read-only |
| `guest` | Read-only, anonymous chat |
## Organization Structure
```
Organization (e.g., "Acme Corp")
├── Users (with roles)
├── Bots (owned by org)
│ ├── sales-bot
│ └── support-bot
└── Drive Storage
├── acme-sales-bot.gbai/
└── acme-support-bot.gbai/
```
## Configuration
@ -55,6 +87,7 @@ auth-lockout-duration,900
## Chapter Contents
- [Initial Setup & Bootstrap](./initial-setup.md) - First-time admin setup
- [User Authentication](./user-auth.md) - Login flows
- [Password Security](./password-security.md) - Password policies
- [API Endpoints](./api-endpoints.md) - Auth API reference
@ -66,7 +99,16 @@ auth-lockout-duration,900
- [User vs System Context](./user-system-context.md) - Execution contexts
- [System Limits & Rate Limiting](./system-limits.md) - Resource constraints and abuse prevention
## Anonymous Chat Access
Anonymous users can use the chat functionality without logging in. The system automatically creates temporary sessions for anonymous users. Authentication is only required for:
- User management (Settings)
- Bot configuration
- Administrative functions
- Organization management
## See Also
- [REST API](../chapter-10-rest/README.md) - API authentication
- [Configuration](../chapter-08-config/README.md) - Auth settings
- [REST API](../10-rest/README.md) - API authentication
- [Configuration](../08-config/README.md) - Auth settings

267
src/12-auth/api-endpoints.md
View file

@ -4,7 +4,147 @@ This chapter provides a comprehensive reference for the API endpoints exposed by
## Authentication Endpoints
Authentication in General Bots is delegated to the Directory Service, which implements industry-standard OAuth2 and OpenID Connect protocols. The authentication endpoints primarily serve as integration points with this external identity provider.
Authentication in General Bots is delegated to the Directory Service (Zitadel), which implements industry-standard OAuth2 and OpenID Connect protocols. The authentication endpoints serve as integration points with this external identity provider.
### Login
```
POST /api/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "<your-password>",
"remember": true
}
```
**Response (Success)**:
```json
{
"success": true,
"user_id": "abc123...",
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"expires_in": 3600,
"requires_2fa": false,
"redirect": "/"
}
```
**Response (2FA Required)**:
```json
{
"success": false,
"requires_2fa": true,
"session_token": "temp-session-token"
}
```
### Logout
```
POST /api/auth/logout
Authorization: Bearer <access_token>
```
**Response**:
```json
{
"success": true,
"message": "Logged out successfully"
}
```
### Get Current User
```
GET /api/auth/me
Authorization: Bearer <access_token>
```
**Response**:
```json
{
"id": "user-uuid",
"username": "johndoe",
"email": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"display_name": "John Doe",
"roles": ["user", "bot_operator"],
"organization_id": "org-uuid"
}
```
### Refresh Token
```
POST /api/auth/refresh
Content-Type: application/json
{
"refresh_token": "eyJ..."
}
```
**Response**:
```json
{
"success": true,
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"expires_in": 3600
}
```
### Bootstrap Admin (First-Time Setup)
This endpoint is only available when `GB_BOOTSTRAP_SECRET` is set and no admin users exist.
```
POST /api/auth/bootstrap
Content-Type: application/json
{
"bootstrap_secret": "your-secret",
"organization_name": "My Company",
"first_name": "John",
"last_name": "Doe",
"username": "admin",
"email": "admin@example.com",
"password": "<your-secure-password>"
}
```
**Response (Success)**:
```json
{
"success": true,
"message": "Admin user 'admin' created successfully...",
"user_id": "abc123...",
"organization_id": "org456..."
}
```
### Anonymous Session (Chat)
Anonymous users can obtain a session for chat without authentication:
```
GET /api/auth?bot_name=default
```
**Response**:
```json
{
"user_id": "anonymous-uuid",
"session_id": "session-uuid",
"status": "authenticated"
}
```
## OAuth Endpoints
### OAuth Login
@ -96,6 +236,131 @@ The API supports Cross-Origin Resource Sharing (CORS) to enable browser-based ap
The `/health` endpoint provides a simple way to verify the server is operational. Unlike other endpoints, this one requires no authentication, making it suitable for external monitoring systems and load balancer health checks. The response includes a status indicator and a timestamp, providing basic confirmation that the server can process requests.
## Directory User Management Endpoints
These endpoints require admin privileges and interact with the Zitadel directory service.
### List Users
```
GET /api/directory/users/list?page=1&per_page=20&organization_id=org-uuid
Authorization: Bearer <access_token>
```
**Response**:
```json
{
"users": [
{
"id": "user-uuid",
"username": "johndoe",
"email": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"state": "active",
"organization_id": "org-uuid",
"roles": ["user"]
}
],
"total": 1,
"page": 1,
"per_page": 20
}
```
### Create User
```
POST /api/directory/users/create
Authorization: Bearer <access_token>
Content-Type: application/json
{
"username": "newuser",
"email": "newuser@example.com",
"first_name": "New",
"last_name": "User",
"organization_id": "org-uuid",
"roles": ["user"]
}
```
**Response**:
```json
{
"success": true,
"message": "User newuser created successfully",
"user_id": "new-user-uuid"
}
```
### Assign User to Organization
```
POST /api/directory/users/:user_id/organization
Authorization: Bearer <access_token>
Content-Type: application/json
{
"organization_id": "org-uuid",
"roles": ["user", "bot_operator"]
}
```
### Update User Roles
```
PUT /api/directory/users/:user_id/organization/:org_id/roles
Authorization: Bearer <access_token>
Content-Type: application/json
{
"roles": ["admin", "org_owner"]
}
```
### Delete User
```
DELETE /api/directory/users/:user_id/delete
Authorization: Bearer <access_token>
```
## Group Management Endpoints
### List Groups
```
GET /api/directory/groups/list?page=1&per_page=20
Authorization: Bearer <access_token>
```
### Create Group
```
POST /api/directory/groups/create
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Marketing Team",
"description": "Marketing department users"
}
```
### Add Member to Group
```
POST /api/directory/groups/:group_id/members/add
Authorization: Bearer <access_token>
Content-Type: application/json
{
"user_id": "user-uuid",
"roles": ["member"]
}
```
## Implementation Status
The current implementation provides full support for WebSocket communication, administrative endpoints, group management, and health checking. OAuth authentication flows through the Directory Service are functional but continue to evolve. Session management endpoints work for basic scenarios with ongoing enhancements planned. Some user profile endpoints and direct REST messaging capabilities remain under development, with batch operations planned for future releases.

2
src/12-auth/compliance-requirements.md
View file

@ -238,7 +238,7 @@ _dmarc.example.com. IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com
```
# Authentication
requirepass SecurePassword123!
requirepass <your-secure-password>
# TLS
tls-port 6380

228
src/12-auth/initial-setup.md Normal file
View file

@ -0,0 +1,228 @@
# Initial Setup & Admin Bootstrap
When General Bots is installed for the first time, it automatically creates an administrator account. This page explains the bootstrap process and how to access your new installation.
## Automatic Bootstrap
On first startup, General Bots checks if any admin users exist in the directory service (Zitadel). If no admin is found, it automatically:
1. Creates an `admin` user
2. Generates a secure random password
3. Creates a default organization ("General Bots")
4. Assigns admin roles to the user
5. Displays credentials in the server console
### Console Output
When bootstrap completes, you'll see output similar to this in your server console:
```
╔════════════════════════════════════════════════════════════╗
║ ║
║ 🤖 GENERAL BOTS - INITIAL SETUP COMPLETE ║
║ ║
╠════════════════════════════════════════════════════════════╣
║ ║
║ Administrator account has been created: ║
║ ║
║ ┌──────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ Username: admin │ ║
║ │ Email: admin@localhost │ ║
║ │ Password: xK3$mP9@vL2nQ7&w │ ║
║ │ │ ║
║ └──────────────────────────────────────────────────────┘ ║
║ ║
║ Organization: General Bots (abc12345) ║
║ ║
╠════════════════════════════════════════════════════════════╣
║ ║
║ ⚠️ IMPORTANT: Save these credentials securely! ║
║ This information will not be shown again. ║
║ ║
║ To login, navigate to: ║
║ http://localhost:PORT/auth/login ║
║ ║
╚════════════════════════════════════════════════════════════╝
```
> **Important**: Save these credentials immediately! The password is only displayed once during the initial startup.
## First Login
1. Navigate to `http://localhost:PORT/auth/login` (replace PORT with your configured port)
2. Enter the username: `admin`
3. Enter the password shown in the console
4. Click "Sign In"
## What Gets Created
| Item | Value | Description |
|------|-------|-------------|
| **Username** | `admin` | Default administrator username |
| **Email** | `admin@localhost` | Default admin email |
| **Password** | (random) | 14+ character secure password |
| **Organization** | "General Bots" | Default organization |
| **Roles** | `admin`, `org_owner`, `user_manager` | Full administrative access |
## Password Security
The auto-generated password includes:
- 4+ lowercase letters (a-z)
- 4+ uppercase letters (A-Z)
- 4+ digits (0-9)
- 2+ special characters (!@#$%&*)
- Randomly shuffled for unpredictability
## After First Login
Once logged in as admin, you should:
1. **Change your password** (recommended)
2. **Update admin email** to a real email address
3. **Create additional users** via Settings → Users
4. **Configure your organization** settings
## Creating Additional Users
As an admin, you can create users through the Settings UI:
1. Go to Settings → Users
2. Click "Add User"
3. Fill in user details:
- Username
- Email
- First/Last name
- Role (user, admin, etc.)
4. The user will be created in the directory service (Zitadel)
5. The user will automatically belong to your organization
## Organization Structure
```
Organization (e.g., "Acme Corp")
├── Users
│ ├── admin (org_owner, admin)
│ ├── john.doe (user)
│ └── jane.smith (bot_operator)
├── Bots
│ ├── sales-bot
│ ├── support-bot
│ └── hr-bot
└── Drive Storage
├── acme-sales-bot.gbai/
├── acme-support-bot.gbai/
└── acme-hr-bot.gbai/
```
## Manual Bootstrap (Recovery)
If you need to manually create an admin (e.g., for recovery), you can use the bootstrap endpoint:
### 1. Set Bootstrap Secret
Add to your environment variables:
```bash
export GB_BOOTSTRAP_SECRET=your-secure-random-secret
```
### 2. Access Bootstrap Page
Navigate to: `http://localhost:PORT/auth/bootstrap`
### 3. Fill in the Form
- **Bootstrap Secret**: The value you set in `GB_BOOTSTRAP_SECRET`
- **Organization Name**: Your company/org name
- **Admin Details**: Username, email, password
### 4. Submit
The admin account will be created and you can login normally.
> **Note**: The manual bootstrap endpoint only works when `GB_BOOTSTRAP_SECRET` is set and no admin users exist.
## Troubleshooting
### "Admin user already exists"
This means bootstrap already completed. If you've lost the password:
1. Access Zitadel console directly (usually port 8300)
2. Use Zitadel's password reset functionality
3. Or delete the user in Zitadel and restart General Bots
### Bootstrap Not Running
Check that:
1. Zitadel (directory service) is running and healthy
2. The Zitadel configuration in your `.env` is correct
3. Check server logs for connection errors
### Cannot Connect to Directory Service
```bash
# Check if Zitadel is running
curl http://localhost:8300/healthz
# Check logs
cat botserver-stack/logs/directory/zitadel.log
```
## Security Considerations
1. **First-time setup**: Bootstrap only runs once when no admins exist
2. **Console only**: Credentials are never logged to files, only displayed in console
3. **Secure password**: Auto-generated passwords meet enterprise security requirements
4. **No default passwords**: Every installation gets a unique password
## API Reference
### Bootstrap Endpoint
```
POST /api/auth/bootstrap
Content-Type: application/json
{
"bootstrap_secret": "your-secret",
"organization_name": "My Company",
"first_name": "John",
"last_name": "Doe",
"username": "admin",
"email": "admin@example.com",
"password": "<your-secure-password>"
}
```
**Response (Success)**:
```json
{
"success": true,
"message": "Admin user 'admin' created successfully...",
"user_id": "abc123...",
"organization_id": "org456..."
}
```
**Response (Error - Admin Exists)**:
```json
{
"error": "Admin user already exists",
"details": "Bootstrap can only be used for initial setup"
}
```
## Next Steps
After completing initial setup:
- [User Authentication](./user-auth.md) - Learn about login flows
- [Permissions Matrix](./permissions-matrix.md) - Understand role-based access
- [Security Features](./security-features.md) - Configure security options
- [API Endpoints](./api-endpoints.md) - Integrate with your applications

505
src/12-auth/permissions-reference.md Normal file
View file

@ -0,0 +1,505 @@
# Complete Permissions Reference
This document provides a comprehensive reference of all permissions available in General Bots Suite. These permissions are designed to provide enterprise-grade access control comparable to Microsoft 365 and Google Workspace.
## Permission Naming Convention
All permissions follow the pattern: `resource.action`
- **resource**: The application or feature being accessed
- **action**: The specific operation being performed
Example: `mail.send` = Send emails in the Mail application
## Quick Reference by Application
| Application | Read | Write | Delete | Share | Admin |
|-------------|------|-------|--------|-------|-------|
| Mail | `mail.read` | `mail.send` | `mail.delete` | `mail.delegate` | `mail.admin` |
| Calendar | `calendar.read` | `calendar.write` | - | `calendar.share` | `calendar.rooms_admin` |
| Drive | `drive.read` | `drive.write` | `drive.delete` | `drive.share` | `drive.admin` |
| Docs | `docs.read` | `docs.write` | - | `docs.share` | `docs.templates_manage` |
| Sheet | `sheet.read` | `sheet.write` | - | `sheet.share` | - |
| Slides | `slides.read` | `slides.write` | - | `slides.share` | - |
| Meet | `meet.join` | `meet.create` | - | - | `meet.admin` |
| Chat | `chat.read` | `chat.write` | `chat.delete` | - | `chat.admin` |
| Tasks | `tasks.read` | `tasks.write` | `tasks.delete` | - | `tasks.projects_manage` |
---
## Administration Permissions
### Organization Management
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `org.read` | View Organization | View organization settings and information |
| `org.write` | Manage Organization | Modify organization settings |
| `org.delete` | Delete Organization | Delete organization data |
| `org.billing` | Manage Billing | Access billing and subscription management |
### User Management
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `users.read` | View Users | View user profiles and directory |
| `users.create` | Create Users | Create new user accounts |
| `users.write` | Edit Users | Modify user profiles and settings |
| `users.delete` | Delete Users | Delete user accounts |
| `users.password_reset` | Reset Passwords | Reset user passwords |
| `users.mfa_manage` | Manage MFA | Enable/disable multi-factor authentication |
| `users.impersonate` | Impersonate Users | Sign in as another user for troubleshooting |
| `users.export` | Export Users | Export user data and directory |
| `users.import` | Import Users | Bulk import users from CSV/LDAP |
### Group Management
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `groups.read` | View Groups | View groups and memberships |
| `groups.create` | Create Groups | Create new groups |
| `groups.write` | Edit Groups | Modify group settings and membership |
| `groups.delete` | Delete Groups | Delete groups |
| `groups.manage_members` | Manage Members | Add/remove group members |
| `groups.manage_owners` | Manage Owners | Assign group owners |
### Role Management
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `roles.read` | View Roles | View role definitions |
| `roles.create` | Create Roles | Create custom roles |
| `roles.write` | Edit Roles | Modify role permissions |
| `roles.delete` | Delete Roles | Delete custom roles |
| `roles.assign` | Assign Roles | Assign roles to users and groups |
### DNS & Domain Management
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `dns.read` | View DNS | View DNS records and domain settings |
| `dns.write` | Manage DNS | Add/modify DNS records |
| `domains.verify` | Verify Domains | Verify domain ownership |
---
## Compliance Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `audit.read` | View Audit Logs | Access audit and activity logs |
| `audit.export` | Export Audit Logs | Export audit data for compliance |
| `compliance.read` | View Compliance | View compliance dashboard and reports |
| `compliance.write` | Manage Compliance | Configure compliance policies |
| `dlp.read` | View DLP Policies | View data loss prevention rules |
| `dlp.write` | Manage DLP | Create and modify DLP policies |
| `retention.read` | View Retention | View data retention policies |
| `retention.write` | Manage Retention | Configure retention policies |
| `ediscovery.access` | eDiscovery Access | Access eDiscovery tools and holds |
---
## Security Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `security.read` | View Security | View security dashboard and alerts |
| `security.write` | Manage Security | Configure security settings |
| `threats.read` | View Threats | View threat detection and incidents |
| `threats.respond` | Respond to Threats | Take action on security incidents |
| `secrets.read` | View Secrets | View API keys and secrets |
| `secrets.write` | Manage Secrets | Create and rotate secrets |
---
## Mail Permissions
*Equivalent to Outlook / Gmail*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `mail.read` | Read Mail | Read own mailbox and messages |
| `mail.send` | Send Mail | Send emails |
| `mail.delete` | Delete Mail | Delete emails |
| `mail.organize` | Organize Mail | Create folders, apply labels, set rules |
| `mail.delegate` | Mail Delegation | Grant mailbox access to others |
| `mail.shared_read` | Read Shared Mailbox | Access shared mailboxes |
| `mail.shared_send` | Send from Shared | Send as shared mailbox |
| `mail.admin` | Mail Admin | Administer mail settings globally |
| `mail.rules_global` | Global Mail Rules | Create organization-wide mail rules |
| `mail.signatures_global` | Global Signatures | Manage organization email signatures |
| `mail.distribution_lists` | Distribution Lists | Manage distribution lists |
| `mail.encryption` | Mail Encryption | Send encrypted messages |
| `mail.archive` | Mail Archive | Access mail archive |
---
## Calendar Permissions
*Equivalent to Outlook Calendar / Google Calendar*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `calendar.read` | View Calendar | View own calendar and events |
| `calendar.write` | Manage Calendar | Create, edit, delete events |
| `calendar.share` | Share Calendar | Share calendar with others |
| `calendar.delegate` | Calendar Delegation | Allow others to manage calendar |
| `calendar.free_busy` | View Free/Busy | View availability of others |
| `calendar.rooms` | Book Rooms | Reserve meeting rooms and resources |
| `calendar.rooms_admin` | Manage Rooms | Administer room resources |
| `calendar.shared_read` | Read Shared Calendars | View shared team calendars |
| `calendar.shared_write` | Edit Shared Calendars | Modify shared team calendars |
---
## Drive Permissions
*Equivalent to OneDrive / SharePoint / Google Drive*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `drive.read` | View Files | View own files and folders |
| `drive.write` | Upload Files | Upload and create files |
| `drive.delete` | Delete Files | Delete own files |
| `drive.share` | Share Files | Share files with others |
| `drive.share_external` | External Sharing | Share files externally |
| `drive.download` | Download Files | Download files locally |
| `drive.sync` | Sync Files | Use desktop sync client |
| `drive.version_history` | Version History | View and restore file versions |
| `drive.shared_read` | Read Shared Drives | Access team shared drives |
| `drive.shared_write` | Write Shared Drives | Modify files in shared drives |
| `drive.shared_admin` | Manage Shared Drives | Administer shared drive settings |
| `drive.trash` | Manage Trash | View and restore deleted items |
| `drive.quota` | View Storage Quota | View storage usage |
| `drive.admin` | Drive Admin | Full administrative access to all drives |
---
## Docs Permissions
*Equivalent to Word Online / Google Docs*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `docs.read` | View Documents | View documents |
| `docs.write` | Edit Documents | Create and edit documents |
| `docs.comment` | Comment on Documents | Add comments and suggestions |
| `docs.share` | Share Documents | Share documents with others |
| `docs.export` | Export Documents | Export to PDF, Word, etc. |
| `docs.templates` | Use Templates | Access document templates |
| `docs.templates_manage` | Manage Templates | Create organization templates |
| `docs.collaborate` | Real-time Collaboration | Co-author documents in real-time |
---
## Sheet Permissions
*Equivalent to Excel Online / Google Sheets*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `sheet.read` | View Spreadsheets | View spreadsheets |
| `sheet.write` | Edit Spreadsheets | Create and edit spreadsheets |
| `sheet.share` | Share Spreadsheets | Share spreadsheets with others |
| `sheet.export` | Export Spreadsheets | Export to Excel, CSV, etc. |
| `sheet.import` | Import Data | Import data from external sources |
| `sheet.macros` | Run Macros | Execute spreadsheet macros |
| `sheet.connections` | Data Connections | Create database connections |
| `sheet.pivot` | Pivot Tables | Create pivot tables and charts |
---
## Slides Permissions
*Equivalent to PowerPoint Online / Google Slides*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `slides.read` | View Presentations | View presentations |
| `slides.write` | Edit Presentations | Create and edit presentations |
| `slides.share` | Share Presentations | Share presentations with others |
| `slides.present` | Present Live | Start live presentations |
| `slides.export` | Export Presentations | Export to PDF, PowerPoint |
| `slides.templates` | Slide Templates | Access presentation templates |
---
## Meet Permissions
*Equivalent to Teams / Zoom / Google Meet*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `meet.join` | Join Meetings | Join video meetings |
| `meet.create` | Create Meetings | Schedule and create meetings |
| `meet.host` | Host Meetings | Full host controls in meetings |
| `meet.record` | Record Meetings | Record meeting sessions |
| `meet.transcript` | Meeting Transcripts | Access meeting transcriptions |
| `meet.screen_share` | Screen Share | Share screen in meetings |
| `meet.breakout` | Breakout Rooms | Create and manage breakout rooms |
| `meet.webinar` | Host Webinars | Host large webinar events |
| `meet.admin` | Meet Admin | Administer meeting settings globally |
| `meet.external` | External Meetings | Meet with external participants |
---
## Chat Permissions
*Equivalent to Teams Chat / Slack / Google Chat*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `chat.read` | Read Messages | Read chat messages |
| `chat.write` | Send Messages | Send chat messages |
| `chat.delete` | Delete Messages | Delete own messages |
| `chat.edit` | Edit Messages | Edit sent messages |
| `chat.files` | Share Files in Chat | Share files in conversations |
| `chat.channels_create` | Create Channels | Create chat channels |
| `chat.channels_manage` | Manage Channels | Manage channel settings |
| `chat.external` | External Chat | Chat with external users |
| `chat.reactions` | Reactions | Add reactions to messages |
| `chat.threads` | Thread Replies | Reply in threads |
| `chat.mentions` | Mentions | Mention users and groups |
| `chat.admin` | Chat Admin | Administer chat settings globally |
---
## Tasks Permissions
*Equivalent to Planner / Asana / Google Tasks*
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `tasks.read` | View Tasks | View own and assigned tasks |
| `tasks.write` | Manage Tasks | Create and edit tasks |
| `tasks.delete` | Delete Tasks | Delete tasks |
| `tasks.assign` | Assign Tasks | Assign tasks to others |
| `tasks.projects_create` | Create Projects | Create task projects/boards |
| `tasks.projects_manage` | Manage Projects | Administer project settings |
| `tasks.time_track` | Time Tracking | Log time against tasks |
| `tasks.reports` | Task Reports | View task analytics and reports |
| `tasks.automation` | Task Automation | Create task automation rules |
---
## Bot & AI Permissions
### Bot Management
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `bots.read` | View Bots | View bot configurations |
| `bots.create` | Create Bots | Create new bots |
| `bots.write` | Edit Bots | Modify bot settings |
| `bots.delete` | Delete Bots | Delete bots |
| `bots.publish` | Publish Bots | Publish bots to channels |
| `bots.channels` | Manage Channels | Configure bot communication channels |
### AI Assistant
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `ai.chat` | AI Chat | Use AI chat assistant |
| `ai.summarize` | AI Summarize | Use AI to summarize content |
| `ai.compose` | AI Compose | Use AI to draft content |
| `ai.translate` | AI Translate | Use AI translation |
| `ai.analyze` | AI Analyze | Use AI for data analysis |
| `ai.advanced` | Advanced AI | Access advanced AI features |
### Knowledge Base
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `kb.read` | View Knowledge Base | Access knowledge base documents |
| `kb.write` | Edit Knowledge Base | Add/edit knowledge base content |
| `kb.admin` | KB Admin | Administer knowledge base settings |
### Conversations
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `conversations.read` | View Conversations | View bot conversations |
| `conversations.write` | Manage Conversations | Intervene in conversations |
| `conversations.transfer` | Transfer Conversations | Transfer to human agent |
| `conversations.history` | Conversation History | Access conversation history |
| `attendant.access` | Attendant Access | Access human attendant queue |
| `attendant.respond` | Attendant Respond | Respond to queued conversations |
---
## Analytics & Reporting Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `analytics.read` | View Analytics | View usage analytics and dashboards |
| `analytics.export` | Export Analytics | Export analytics data |
| `analytics.custom` | Custom Reports | Create custom reports and dashboards |
| `analytics.realtime` | Real-time Analytics | Access real-time analytics |
| `reports.read` | View Reports | Access standard reports |
| `reports.schedule` | Schedule Reports | Schedule automated report delivery |
---
## Monitoring & System Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `monitoring.read` | View Monitoring | View system health and metrics |
| `monitoring.alerts` | Manage Alerts | Configure monitoring alerts |
| `logs.read` | View Logs | Access system and application logs |
| `logs.export` | Export Logs | Export log data |
| `services.read` | View Services | View service status |
| `services.manage` | Manage Services | Start/stop/restart services |
| `resources.read` | View Resources | View resource usage |
---
## Paper & Research Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `paper.read` | View Papers | View AI-generated papers and notes |
| `paper.write` | Create Papers | Create and edit AI-assisted documents |
| `paper.publish` | Publish Papers | Publish papers to knowledge base |
| `research.read` | View Research | Access AI research results |
| `research.create` | Create Research | Start AI research queries |
| `research.deep` | Deep Research | Access deep research features |
| `quicknote.access` | Quick Notes | Access quick note feature |
---
## Integrations Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `sources.read` | View Sources | View configured data sources |
| `sources.create` | Create Sources | Add new data sources |
| `sources.write` | Edit Sources | Modify data source configurations |
| `sources.delete` | Delete Sources | Remove data sources |
| `webhooks.read` | View Webhooks | View webhook configurations |
| `webhooks.write` | Manage Webhooks | Create and edit webhooks |
| `api.access` | API Access | Access REST API endpoints |
| `api.keys` | API Key Management | Create and manage API keys |
| `integrations.read` | View Integrations | View third-party integrations |
| `integrations.write` | Manage Integrations | Configure third-party integrations |
| `mcp.access` | MCP Access | Access Model Context Protocol tools |
---
## Automation Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `autotask.read` | View AutoTasks | View automated task definitions |
| `autotask.create` | Create AutoTasks | Create new automated tasks |
| `autotask.write` | Edit AutoTasks | Modify automated task settings |
| `autotask.delete` | Delete AutoTasks | Remove automated tasks |
| `autotask.execute` | Execute AutoTasks | Run automated tasks manually |
| `autotask.schedule` | Schedule AutoTasks | Schedule task automation |
| `workflows.read` | View Workflows | View workflow definitions |
| `workflows.write` | Manage Workflows | Create and edit workflows |
| `intents.read` | View Intents | View AI intent definitions |
| `intents.write` | Manage Intents | Create and edit intents |
---
## Designer Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `designer.access` | Access Designer | Open visual designer tool |
| `designer.create` | Create Designs | Create new UI designs |
| `designer.edit` | Edit Designs | Modify existing designs |
| `designer.publish` | Publish Designs | Publish designs to production |
| `designer.templates` | Design Templates | Access and create design templates |
---
## Settings Permissions
| Permission | Display Name | Description |
|------------|--------------|-------------|
| `settings.personal` | Personal Settings | Manage own user settings |
| `settings.organization` | Organization Settings | Manage organization settings |
| `settings.security` | Security Settings | Manage security configuration |
| `settings.notifications` | Notification Settings | Manage notification preferences |
| `settings.appearance` | Appearance Settings | Customize appearance and themes |
| `settings.language` | Language Settings | Set language and locale |
| `settings.backup` | Backup Settings | Configure backup and export |
---
## Role-Permission Matrix
### Global Administrator
**Has ALL permissions** - Full system control
### Billing Administrator
- `org.read`, `org.billing`
- `users.read`
- `reports.read`, `analytics.read`
### Compliance Administrator
- `org.read`, `users.read`, `groups.read`
- `audit.read`, `audit.export`
- `compliance.read`, `compliance.write`
- `dlp.read`, `dlp.write`
- `retention.read`, `retention.write`
- `ediscovery.access`
- `analytics.read`, `reports.read`
- `logs.read`, `logs.export`
### Security Administrator
- `org.read`, `users.read`, `users.mfa_manage`, `groups.read`
- `security.read`, `security.write`
- `threats.read`, `threats.respond`
- `secrets.read`, `secrets.write`
- `audit.read`, `logs.read`
- `monitoring.read`, `monitoring.alerts`
### User Administrator
- `users.read`, `users.create`, `users.write`, `users.delete`
- `users.password_reset`, `users.mfa_manage`
- `users.export`, `users.import`
- `groups.read`, `groups.create`, `groups.write`, `groups.manage_members`
- `roles.read`, `roles.assign`
- `audit.read`
### Standard User
Full access to:
- Mail (read, send, delete, organize)
- Calendar (read, write, share, rooms)
- Drive (read, write, delete, share, sync)
- Docs, Sheet, Slides (read, write, collaborate)
- Meet (join, create, host, screen share)
- Chat (read, write, edit, reactions)
- Tasks (read, write, assign)
- AI (chat, summarize, compose, translate)
- Personal settings
### Guest User
Limited access to:
- Mail (read, send only)
- Calendar (read, free/busy only)
- Drive (read, download shared only)
- Docs (read, comment only)
- Meet (join, screen share)
- Chat (read, write, reactions)
- Tasks (read only)
- Personal settings
### Viewer
Read-only access to:
- Mail, Calendar, Drive, Docs, Sheet, Slides
- Meet (join only), Chat (read only)
- Tasks (read only), Analytics
- Personal settings
---
## See Also
- [RBAC Overview](./rbac-overview.md) - Understanding role-based access control
- [User Authentication](./user-auth.md) - Authentication mechanisms
- [Security Policy](./security-policy.md) - Security best practices
- [API Endpoints](./api-endpoints.md) - API documentation with permission requirements

321
src/12-auth/rbac-overview.md Normal file
View file

@ -0,0 +1,321 @@
# Role-Based Access Control (RBAC) Overview
General Bots implements a comprehensive **Role-Based Access Control (RBAC)** system designed as a secure, enterprise-grade alternative to Microsoft 365 / Google Workspace permission models. This system provides fine-grained access control across all suite applications.
## Why RBAC?
RBAC is the industry standard for enterprise access control, used by:
- Microsoft Azure Active Directory
- Google Workspace Admin
- AWS IAM
- Kubernetes
- All major enterprise platforms
### Benefits Over Direct Permissions
| Approach | Pros | Cons |
|----------|------|------|
| **Direct User Permissions** | Simple for small teams | Unmanageable at scale, audit nightmare |
| **RBAC (Roles)** | Scalable, auditable, principle of least privilege | Initial setup complexity |
| **RBAC + Groups** | Best of both worlds, mirrors org structure | Requires planning |
## Core Concepts
### 1. Users
Individual accounts that authenticate to the system. Users can be:
- **Internal employees** - Full organization members
- **External guests** - Partners, contractors, clients
- **Service accounts** - For API integrations
### 2. Roles
Named collections of permissions. Roles define *what actions* can be performed.
```
┌─────────────────────────────────────────────────────────┐
│ ROLE: Standard User │
├─────────────────────────────────────────────────────────┤
│ Permissions: │
│ ✓ mail.read, mail.send │
│ ✓ calendar.read, calendar.write │
│ ✓ drive.read, drive.write, drive.share │
│ ✓ docs.read, docs.write, docs.collaborate │
│ ✓ meet.join, meet.create │
│ ✓ chat.read, chat.write │
│ ✓ tasks.read, tasks.write │
│ ✗ users.manage (NOT included) │
│ ✗ settings.organization (NOT included) │
└─────────────────────────────────────────────────────────┘
```
### 3. Groups
Collections of users, typically mirroring organizational structure:
- Departments (IT, HR, Finance, Sales)
- Teams (Project Alpha, Support Team)
- Access levels (Managers, External Contractors)
### 4. Permissions
Granular capabilities following the pattern: `resource.action`
```
mail.read → Can read emails
mail.send → Can send emails
mail.admin → Full mail administration
drive.read → Can view files
drive.write → Can upload/edit files
drive.share → Can share with others
drive.share_external → Can share outside organization
drive.admin → Full drive administration
```
## Permission Inheritance
```
┌──────────────┐
│ Permission │
│ mail.send │
└──────┬───────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Role │ │ Role │
│ Standard │ │ Guest │
│ User │ │ User │
└──────┬──────┘ └─────────────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
┌─────────┐ ┌─────────────┐
│ Group │ │ Direct │
│ Sales │ │ Assignment │
│ Team │ │ │
└────┬────┘ └──────┬──────┘
│ │
▼ ▼
┌─────────┐ ┌─────────────┐
│ User │ │ User │
│ Alice │ │ Bob │
└─────────┘ └─────────────┘
```
Users inherit permissions from:
1. **Direct role assignments** - Roles assigned directly to the user
2. **Group memberships** - Roles assigned to groups the user belongs to
## Comparison with Office 365 / Google Workspace
### Office 365 Equivalent Roles
| General Bots Role | Office 365 Equivalent |
|-------------------|----------------------|
| `global_admin` | Global Administrator |
| `billing_admin` | Billing Administrator |
| `user_admin` | User Administrator |
| `exchange_admin` | Exchange Administrator |
| `sharepoint_admin` | SharePoint Administrator |
| `teams_admin` | Teams Administrator |
| `security_admin` | Security Administrator |
| `compliance_admin` | Compliance Administrator |
| `helpdesk_admin` | Helpdesk Administrator |
| `reports_reader` | Reports Reader |
### Google Workspace Equivalent Roles
| General Bots Role | Google Workspace Equivalent |
|-------------------|----------------------------|
| `global_admin` | Super Admin |
| `user_admin` | User Management Admin |
| `groups_admin` | Groups Admin |
| `sharepoint_admin` | Drive & Docs Admin |
| `exchange_admin` | Gmail Admin |
| `teams_admin` | Meet & Chat Admin |
## Built-in System Roles
### Administrative Roles
| Role | Description | Typical Use |
|------|-------------|-------------|
| **Global Administrator** | Full system control | IT Director, CTO |
| **Billing Administrator** | Subscription & payments | Finance team |
| **Compliance Administrator** | Audit, DLP, retention | Legal, Compliance |
| **Security Administrator** | Threats, access policies | Security team |
| **User Administrator** | User & group management | HR, IT Helpdesk |
| **Groups Administrator** | Group management only | Team leads |
| **Helpdesk Administrator** | Password resets, support | IT Support |
### Service-Specific Admin Roles
| Role | Manages |
|------|---------|
| **Mail Administrator** | Mailboxes, mail flow, distribution lists |
| **Drive Administrator** | File storage, sharing policies, quotas |
| **Meet & Chat Administrator** | Video meetings, chat settings |
| **Knowledge Administrator** | Knowledge base, document libraries |
### End-User Roles
| Role | Description | Best For |
|------|-------------|----------|
| **Power User** | Full productivity + automation | Developers, analysts |
| **Standard User** | Normal productivity access | Regular employees |
| **Guest User** | Limited external access | Partners, contractors |
| **Viewer** | Read-only access | Auditors, observers |
## Permission Categories
Permissions are organized into logical categories:
### Administration (`admin`)
- `org.*` - Organization settings
- `users.*` - User management
- `groups.*` - Group management
- `roles.*` - Role management
- `dns.*` - DNS and domains
### Compliance (`compliance`)
- `audit.*` - Audit logs
- `compliance.*` - Compliance policies
- `dlp.*` - Data loss prevention
- `retention.*` - Data retention
- `ediscovery.*` - Legal discovery
### Security (`security`)
- `security.*` - Security settings
- `threats.*` - Threat management
- `secrets.*` - API keys and secrets
### Productivity Apps
| Category | Permissions |
|----------|-------------|
| `mail` | read, send, delete, organize, delegate, admin |
| `calendar` | read, write, share, delegate, rooms |
| `drive` | read, write, delete, share, sync, admin |
| `docs` | read, write, comment, share, templates |
| `sheet` | read, write, share, macros, connections |
| `slides` | read, write, share, present |
| `meet` | join, create, host, record, webinar |
| `chat` | read, write, channels, external |
| `tasks` | read, write, assign, projects, automation |
### AI & Bots (`ai`)
- `bots.*` - Bot configuration
- `ai.*` - AI assistant features
- `kb.*` - Knowledge base
- `conversations.*` - Bot conversations
- `attendant.*` - Human handoff
### Automation (`automation`)
- `autotask.*` - Automated tasks
- `workflows.*` - Workflow definitions
- `intents.*` - AI intent management
## Best Practices
### 1. Use Groups for Department Access
```
Group: Sales Team
└── Role: Standard User
└── Role: CRM Access (custom)
Group: IT Department
└── Role: Standard User
└── Role: Helpdesk Administrator
```
### 2. Principle of Least Privilege
Start with the minimum permissions and add as needed:
- New employees → `Standard User`
- After training → Add specific permissions
- Temporary access → Set expiration dates
### 3. Use Time-Limited Assignments
```sql
-- Role expires in 30 days
expires_at: 2025-08-14T00:00:00Z
```
### 4. Regular Access Reviews
- Quarterly review of admin roles
- Monthly review of external access
- Automated alerts for unused permissions
### 5. Audit Everything
All permission changes are logged:
- Who made the change
- What was changed
- When it happened
- Why (if documented)
## Migration from Other Platforms
### From Microsoft 365
1. Export Azure AD groups and roles
2. Map to equivalent General Bots roles
3. Import users and create groups
4. Assign group-role mappings
5. Verify with test accounts
### From Google Workspace
1. Export Google Admin directory
2. Map organizational units to groups
3. Map admin roles to equivalent roles
4. Import and test
See [Migration Guide](../14-migration/overview.md) for detailed instructions.
## API Reference
### List All Roles
```http
GET /api/rbac/roles
```
### Assign Role to User
```http
POST /api/rbac/users/{user_id}/roles/{role_id}
Content-Type: application/json
{
"expires_at": "2025-12-31T23:59:59Z" // Optional
}
```
### Add User to Group
```http
POST /api/rbac/users/{user_id}/groups/{group_id}
```
### Get User's Effective Permissions
```http
GET /api/rbac/users/{user_id}/permissions
```
Response:
```json
{
"user_id": "uuid",
"direct_roles": [...],
"group_roles": [...],
"groups": [...],
"effective_permissions": [
"mail.read",
"mail.send",
"drive.read",
...
]
}
```
## Next Steps
- [Permissions Matrix](./permissions-matrix.md) - Complete permission reference
- [User Authentication](./user-auth.md) - Login and identity
- [Security Checklist](./security-checklist.md) - Deployment hardening
- [API Endpoints](./api-endpoints.md) - Full API documentation

410
src/22-white-label/README.md Normal file
View file

@ -0,0 +1,410 @@
# White Label Configuration
General Bots supports full white-label customization, allowing you to rebrand the entire platform with your own company name, logo, colors, and feature set. This is controlled through a simple `.product` configuration file.
## Overview
White-labeling allows you to:
- Replace "General Bots" branding with your own product name
- Enable/disable specific apps in the suite
- Set a default theme for all users
- Customize logos, colors, and other visual elements
- Control which APIs are available based on enabled apps
## Configuration File
The white-label settings are defined in the `.product` file located in the root of the botserver directory.
### File Location
```
botserver/
├── .product # White-label configuration
├── src/
├── Cargo.toml
└── ...
```
### Configuration Format
The `.product` file uses a simple `key=value` format:
```ini
# Product Configuration File
# Lines starting with # are comments
# Product name (replaces "General Bots" throughout the application)
name=My Custom Platform
# Active apps (comma-separated list)
apps=chat,drive,tasks,calendar
# Default theme
theme=sentient
# Optional customizations
logo=/static/my-logo.svg
favicon=/static/favicon.ico
primary_color=#3b82f6
support_email=support@mycompany.com
docs_url=https://docs.mycompany.com
copyright=© {year} {name}. All rights reserved.
```
## Configuration Options
### name
**Type:** String
**Default:** `General Bots`
The product name that replaces "General Bots" throughout the application, including:
- Page titles
- Welcome messages
- Footer text
- Email templates
- API responses
```ini
name=Acme Bot Platform
```
### apps
**Type:** Comma-separated list
**Default:** All apps enabled
Specifies which apps are active in the suite. Only listed apps will:
- Appear in the navigation menu
- Have their APIs enabled
- Be accessible to users
**Available apps:**
| App | Description |
|-----|-------------|
| `chat` | Main chat interface |
| `mail` | Email client |
| `calendar` | Calendar and scheduling |
| `drive` | File storage |
| `tasks` | Task management |
| `docs` | Document editor |
| `paper` | Notes and quick documents |
| `sheet` | Spreadsheet editor |
| `slides` | Presentation editor |
| `meet` | Video conferencing |
| `research` | Research assistant |
| `sources` | Data sources management |
| `analytics` | Analytics dashboard |
| `admin` | Administration panel |
| `monitoring` | System monitoring |
| `settings` | User settings |
**Example - Minimal setup:**
```ini
apps=chat,drive,tasks
```
**Example - Full productivity suite:**
```ini
apps=chat,mail,calendar,drive,tasks,docs,sheet,slides,meet
```
### theme
**Type:** String
**Default:** `sentient`
Sets the default theme for new users and the login page.
**Available themes:**
| Theme | Description |
|-------|-------------|
| `sentient` | Default neon green theme |
| `dark` | Dark mode with blue accents |
| `light` | Light mode with blue accents |
| `blue` | Blue theme |
| `purple` | Purple theme |
| `green` | Green theme |
| `orange` | Orange theme |
| `cyberpunk` | Cyberpunk aesthetic |
| `retrowave` | 80s retrowave style |
| `vapordream` | Vaporwave aesthetic |
| `y2kglow` | Y2K neon style |
| `arcadeflash` | Arcade game style |
| `discofever` | Disco theme |
| `grungeera` | 90s grunge style |
| `jazzage` | Jazz age gold |
| `mellowgold` | Mellow gold tones |
| `midcenturymod` | Mid-century modern |
| `polaroidmemories` | Vintage polaroid |
| `saturdaycartoons` | Cartoon style |
| `seasidepostcard` | Beach/ocean theme |
| `typewriter` | Typewriter/monospace |
| `3dbevel` | 3D beveled style |
| `xeroxui` | Classic Xerox UI |
| `xtreegold` | XTree Gold DOS style |
```ini
theme=dark
```
### logo
**Type:** URL/Path (optional)
**Default:** General Bots logo
URL or path to your custom logo. Supports SVG, PNG, or other image formats.
```ini
logo=/static/branding/my-logo.svg
logo=https://cdn.mycompany.com/logo.png
```
### favicon
**Type:** URL/Path (optional)
**Default:** General Bots favicon
URL or path to your custom favicon.
```ini
favicon=/static/branding/favicon.ico
```
### primary_color
**Type:** Hex color code (optional)
**Default:** Theme-dependent
Override the primary accent color across the UI.
```ini
primary_color=#3b82f6
primary_color=#e11d48
```
### support_email
**Type:** Email address (optional)
**Default:** None
Support email displayed in help sections and error messages.
```ini
support_email=support@mycompany.com
```
### docs_url
**Type:** URL (optional)
**Default:** `https://docs.pragmatismo.com.br`
URL to your documentation site.
```ini
docs_url=https://docs.mycompany.com
```
### copyright
**Type:** String (optional)
**Default:** `© {year} {name}. All rights reserved.`
Copyright text for the footer. Supports placeholders:
- `{year}` - Current year
- `{name}` - Product name
```ini
copyright=© {year} {name} - A product of My Company Inc.
```
## API Integration
### Product Configuration Endpoint
The current product configuration is available via API:
```
GET /api/product
```
**Response:**
```json
{
"name": "My Custom Platform",
"apps": ["chat", "drive", "tasks", "calendar"],
"theme": "dark",
"logo": "/static/my-logo.svg",
"favicon": null,
"primary_color": "#3b82f6",
"docs_url": "https://docs.mycompany.com",
"copyright": "© 2025 My Custom Platform. All rights reserved."
}
```
### App-Gated APIs
When an app is disabled in the `.product` file, its corresponding APIs return `403 Forbidden`:
```json
{
"error": "app_disabled",
"message": "The 'calendar' app is not enabled for this installation"
}
```
## UI Integration
### JavaScript Access
The product configuration is available in the frontend:
```javascript
// Fetch product config
const response = await fetch('/api/product');
const product = await response.json();
console.log(product.name); // "My Custom Platform"
console.log(product.apps); // ["chat", "drive", "tasks"]
```
### Conditional App Rendering
The navigation menu automatically hides disabled apps. If you need to check manually:
```javascript
function isAppEnabled(appName) {
return window.productConfig?.apps?.includes(appName) ?? false;
}
if (isAppEnabled('calendar')) {
// Show calendar features
}
```
## Examples
### Example 1: Simple Chat Bot
A minimal setup for a chat-only bot:
```ini
name=Support Bot
apps=chat
theme=dark
support_email=help@example.com
```
### Example 2: Internal Tools Platform
An internal company platform with productivity tools:
```ini
name=Acme Internal Tools
apps=chat,drive,tasks,docs,calendar,meet
theme=light
logo=/static/acme-logo.svg
primary_color=#1e40af
docs_url=https://wiki.acme.internal
copyright=© {year} Acme Corporation - Internal Use Only
```
### Example 3: Customer Service Platform
A customer service focused deployment:
```ini
name=ServiceDesk Pro
apps=chat,tasks,analytics,admin,monitoring
theme=blue
support_email=admin@servicedesk.com
docs_url=https://help.servicedesk.com
```
### Example 4: Full Suite
Enable all features (default behavior):
```ini
name=Enterprise Suite
apps=chat,mail,calendar,drive,tasks,docs,paper,sheet,slides,meet,research,sources,analytics,admin,monitoring,settings
theme=sentient
```
## Reloading Configuration
The product configuration is loaded at server startup. To apply changes:
1. Edit the `.product` file
2. Restart the server
```bash
# Restart the server to apply changes
systemctl restart botserver
# or
docker-compose restart botserver
```
## Environment Variable Override
You can override the `.product` file location using an environment variable:
```bash
export PRODUCT_CONFIG_PATH=/etc/myapp/.product
```
## Best Practices
1. **Version Control**: Include the `.product` file in your deployment configuration (but not in the main repo if it contains sensitive branding)
2. **Minimal Apps**: Only enable the apps your users need to reduce complexity and improve performance
3. **Consistent Branding**: Ensure your logo, colors, and theme work well together
4. **Documentation**: Update your `docs_url` to point to customized documentation for your users
5. **Testing**: Test the UI with your specific app combination to ensure navigation works correctly
## Troubleshooting
### Apps Not Hiding
If disabled apps still appear:
1. Clear browser cache
2. Verify the `.product` file syntax
3. Check server logs for configuration errors
4. Restart the server
### API Returns 403
If APIs return "app_disabled" errors:
1. Check the `apps` list in `.product`
2. Ensure the app name is spelled correctly (lowercase)
3. Restart the server after changes
### Branding Not Updating
If the product name doesn't change:
1. Hard refresh the browser (Ctrl+Shift+R)
2. Clear application cache
3. Verify the `name` field in `.product`
4. Check for syntax errors (missing `=` sign)
## Related Documentation
- [Theme Customization](../05-gbtheme/README.md) - Detailed theme configuration
- [UI Components](../04-gbui/README.md) - UI customization options
- [Configuration](../08-config/README.md) - General server configuration
- [Authentication](../12-auth/README.md) - Auth customization for white-label

622
src/22-white-label/billing.md Normal file
View file

@ -0,0 +1,622 @@
# Subscription & Billing Guide
This guide covers General Bots' subscription management, billing integration, quota systems, and white-label billing configuration.
## Overview
General Bots provides a comprehensive billing system that supports:
- **Multiple Plans** - Free, Pro, Business, Enterprise tiers
- **Usage-Based Billing** - Pay for what you use
- **Quota Management** - Enforce limits per organization
- **Stripe Integration** - Secure payment processing
- **White-Label Support** - Custom branding for resellers
## Plan Structure
### Default Plans
| Plan | Price | Members | Bots | Storage | Messages | API Calls |
|------|-------|---------|------|---------|----------|-----------|
| Free | $0/mo | 5 | 2 | 1 GB | 1,000/mo | 10,000/mo |
| Pro | $49/mo | 50 | 20 | 50 GB | 100,000/mo | 500,000/mo |
| Business | $99/mo | 200 | 100 | 200 GB | Unlimited | Unlimited |
| Enterprise | Custom | Unlimited | Unlimited | 1 TB+ | Unlimited | Unlimited |
### Plan Configuration
Plans are defined in `.product` files for white-label deployments:
```yaml
version: 1
product:
name: "My SaaS Product"
company: "My Company"
plans:
- id: starter
name: Starter
price_monthly: 29
price_annual: 290
features:
max_members: 10
max_bots: 5
storage_gb: 10
messages_per_month: 10000
api_calls_per_month: 50000
support_level: email
- id: professional
name: Professional
price_monthly: 79
price_annual: 790
features:
max_members: 50
max_bots: 25
storage_gb: 100
messages_per_month: 100000
api_calls_per_month: 500000
support_level: priority
custom_branding: true
- id: enterprise
name: Enterprise
price_monthly: 0
custom_pricing: true
features:
max_members: -1
max_bots: -1
storage_gb: 1000
messages_per_month: -1
api_calls_per_month: -1
support_level: dedicated
custom_branding: true
sso: true
audit_logs: true
sla: "99.9%"
```
## Stripe Integration
### Configuration
Add Stripe credentials to your environment:
```bash
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO_MONTHLY=price_...
STRIPE_PRICE_ID_PRO_ANNUAL=price_...
STRIPE_PRICE_ID_BUSINESS_MONTHLY=price_...
STRIPE_PRICE_ID_BUSINESS_ANNUAL=price_...
```
### Webhook Events
General Bots handles these Stripe webhook events:
| Event | Action |
|-------|--------|
| `customer.subscription.created` | Activate subscription |
| `customer.subscription.updated` | Update plan/status |
| `customer.subscription.deleted` | Cancel subscription |
| `invoice.paid` | Record payment |
| `invoice.payment_failed` | Handle failed payment |
| `customer.subscription.trial_will_end` | Send trial ending notification |
### Setting Up Webhooks
1. Go to Stripe Dashboard → Developers → Webhooks
2. Add endpoint: `https://your-domain.com/api/billing/webhooks/stripe`
3. Select events to listen for
4. Copy webhook secret to `STRIPE_WEBHOOK_SECRET`
## Subscription Lifecycle
### Creating a Subscription
```http
POST /api/billing/subscriptions
Authorization: Bearer <token>
Content-Type: application/json
{
"plan_id": "pro",
"billing_cycle": "monthly",
"payment_method_id": "pm_...",
"trial_days": 14,
"coupon_code": "LAUNCH20"
}
```
Response:
```json
{
"subscription_id": "sub_...",
"organization_id": "org-uuid",
"plan_id": "pro",
"status": "trialing",
"trial_end": "2025-02-04T00:00:00Z",
"current_period_end": "2025-03-21T00:00:00Z",
"cancel_at_period_end": false
}
```
### Upgrading/Downgrading
```http
POST /api/billing/subscriptions/{subscription_id}/change
Authorization: Bearer <token>
Content-Type: application/json
{
"new_plan_id": "business",
"prorate": true,
"immediate": true
}
```
Proration calculates the difference and adjusts the next invoice.
### Cancellation
```http
POST /api/billing/subscriptions/{subscription_id}/cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "too_expensive",
"feedback": "Need more affordable options",
"cancel_immediately": false,
"offer_retention": true
}
```
When `offer_retention` is true, the system may return retention offers:
```json
{
"status": "pending_retention",
"offers": [
{
"id": "offer-uuid",
"type": "discount",
"discount_percent": 25,
"duration_months": 3,
"expires_at": "2025-01-28T00:00:00Z"
},
{
"id": "offer-uuid-2",
"type": "pause",
"pause_months": 3
}
]
}
```
### Pausing a Subscription
```http
POST /api/billing/subscriptions/{subscription_id}/pause
Authorization: Bearer <token>
Content-Type: application/json
{
"pause_months": 3
}
```
### Resuming a Subscription
```http
POST /api/billing/subscriptions/{subscription_id}/resume
Authorization: Bearer <token>
```
## Quota Management
### Quota Types
| Quota | Enforcement | Reset |
|-------|-------------|-------|
| `members` | Hard limit | N/A |
| `bots` | Hard limit | N/A |
| `storage_bytes` | Hard limit | N/A |
| `messages` | Soft limit | Monthly |
| `api_calls` | Rate limit | Monthly |
### Checking Quotas
```http
GET /api/billing/quotas
Authorization: Bearer <token>
```
Response:
```json
{
"organization_id": "org-uuid",
"plan_id": "pro",
"quotas": {
"members": {
"used": 12,
"limit": 50,
"percent": 24
},
"bots": {
"used": 5,
"limit": 20,
"percent": 25
},
"storage_bytes": {
"used": 5368709120,
"limit": 53687091200,
"percent": 10
},
"messages": {
"used": 45000,
"limit": 100000,
"percent": 45,
"resets_at": "2025-02-01T00:00:00Z"
},
"api_calls": {
"used": 125000,
"limit": 500000,
"percent": 25,
"resets_at": "2025-02-01T00:00:00Z"
}
}
}
```
### Usage Alerts
The system sends alerts at these thresholds:
| Threshold | Alert Type | Notification |
|-----------|------------|--------------|
| 80% | Warning | Email, In-app |
| 90% | Critical | Email, In-app, Webhook |
| 100% | Limit Reached | Email, In-app, Webhook |
### Configuring Alerts
```http
PUT /api/billing/alerts/preferences
Authorization: Bearer <token>
Content-Type: application/json
{
"email_notifications": true,
"webhook_url": "https://your-app.com/webhooks/quota",
"slack_webhook": "https://hooks.slack.com/...",
"alert_thresholds": [70, 85, 95, 100]
}
```
### Grace Period
When quotas are exceeded, organizations enter a grace period:
- Default: 7 days
- During grace: Soft limits become warnings
- After grace: Hard enforcement applies
```http
GET /api/billing/grace-period
Authorization: Bearer <token>
```
Response:
```json
{
"in_grace_period": true,
"exceeded_quotas": ["messages"],
"grace_started": "2025-01-21T00:00:00Z",
"grace_ends": "2025-01-28T00:00:00Z",
"overage_percent": 15,
"recommended_action": "upgrade_plan"
}
```
## Usage Metering
### Recording Usage
Usage is automatically tracked, but can be manually recorded:
```http
POST /api/billing/usage
Authorization: Bearer <token>
Content-Type: application/json
{
"metric": "api_calls",
"quantity": 100,
"timestamp": "2025-01-21T10:30:00Z",
"metadata": {
"endpoint": "/api/chat",
"bot_id": "bot-uuid"
}
}
```
### Querying Usage
```http
GET /api/billing/usage/history
Authorization: Bearer <token>
```
Query parameters:
| Parameter | Description |
|-----------|-------------|
| `metric` | Filter by metric type |
| `start_date` | Period start |
| `end_date` | Period end |
| `granularity` | hour, day, week, month |
Response:
```json
{
"metric": "api_calls",
"period": {
"start": "2025-01-01T00:00:00Z",
"end": "2025-01-31T23:59:59Z"
},
"total": 125000,
"data_points": [
{"date": "2025-01-01", "value": 4200},
{"date": "2025-01-02", "value": 3800},
...
]
}
```
## Invoices
### Listing Invoices
```http
GET /api/billing/invoices
Authorization: Bearer <token>
```
Response:
```json
{
"invoices": [
{
"id": "inv_...",
"number": "INV-2025-0001",
"date": "2025-01-21",
"amount": 4900,
"currency": "usd",
"status": "paid",
"pdf_url": "https://...",
"items": [
{
"description": "Pro Plan (Monthly)",
"amount": 4900,
"quantity": 1
}
]
}
],
"has_more": false
}
```
### Downloading Invoice PDF
```http
GET /api/billing/invoices/{invoice_id}/pdf
Authorization: Bearer <token>
```
Returns PDF binary with `Content-Type: application/pdf`.
## Payment Methods
### Adding a Payment Method
```http
POST /api/billing/payment-methods
Authorization: Bearer <token>
Content-Type: application/json
{
"payment_method_id": "pm_...",
"set_as_default": true
}
```
### Listing Payment Methods
```http
GET /api/billing/payment-methods
Authorization: Bearer <token>
```
### Removing a Payment Method
```http
DELETE /api/billing/payment-methods/{payment_method_id}
Authorization: Bearer <token>
```
## White-Label Billing
### Custom Branding
Configure billing UI branding in your `.product` file:
```yaml
branding:
billing:
company_name: "Your Company"
support_email: "billing@yourcompany.com"
invoice_logo: "/assets/logo.png"
invoice_footer: "Thank you for your business!"
currency: "usd"
tax_id_label: "VAT Number"
```
### Reseller Mode
Enable reseller billing to manage customer subscriptions:
```yaml
reseller:
enabled: true
commission_percent: 20
min_markup_percent: 0
allow_custom_pricing: true
billing_relationship: "reseller" # or "direct"
```
### Custom Plan Pricing
Resellers can set custom pricing:
```http
POST /api/billing/reseller/plans/{plan_id}/pricing
Authorization: Bearer <token>
Content-Type: application/json
{
"customer_id": "customer-uuid",
"custom_price_monthly": 7900,
"custom_price_annual": 79000
}
```
## Self-Hosted Mode
For self-hosted installations without SaaS billing:
```bash
SAAS_MODE=false
LOCAL_QUOTA_MODE=true
```
In local quota mode:
- No payment processing
- Quotas enforced locally
- No subscription management
- Resource limits based on configuration
Configure local quotas:
```yaml
local_quotas:
max_members: 100
max_bots: 50
max_storage_gb: 500
max_messages_per_month: 1000000
```
## Events and Webhooks
### Subscription Events
```json
{
"event": "subscription.created",
"timestamp": "2025-01-21T10:00:00Z",
"data": {
"subscription_id": "sub_...",
"organization_id": "org-uuid",
"plan_id": "pro",
"status": "active"
}
}
```
Event types:
| Event | Description |
|-------|-------------|
| `subscription.created` | New subscription started |
| `subscription.updated` | Plan or status changed |
| `subscription.cancelled` | Subscription cancelled |
| `subscription.renewed` | Subscription renewed |
| `payment.succeeded` | Payment processed |
| `payment.failed` | Payment failed |
| `quota.warning` | Quota threshold reached |
| `quota.exceeded` | Quota limit exceeded |
### Configuring Webhooks
```http
POST /api/billing/webhooks
Authorization: Bearer <token>
Content-Type: application/json
{
"url": "https://your-app.com/webhooks/billing",
"events": ["subscription.*", "payment.*", "quota.*"],
"secret": "your-webhook-secret"
}
```
## Best Practices
### For SaaS Operators
1. **Start with a free tier** - Lower barrier to entry
2. **Offer annual discounts** - 15-20% savings encourages commitment
3. **Set clear usage limits** - Avoid surprise bills
4. **Provide grace periods** - Don't cut off access immediately
5. **Retention offers work** - Discounts reduce churn
### For Enterprise Deployments
1. **Custom contracts** - Negotiate terms for large deals
2. **Usage commitments** - Discounts for guaranteed usage
3. **Multi-year deals** - Better pricing for longer terms
4. **Success management** - Dedicated support reduces churn
### For Self-Hosted
1. **Resource planning** - Set realistic quotas
2. **Monitor usage** - Track before limits are hit
3. **Scale proactively** - Add capacity before needed
## Troubleshooting
### Payment Failed
1. Check payment method is valid
2. Verify billing address
3. Contact card issuer if declined
4. Add backup payment method
### Quota Exceeded
1. Review usage in dashboard
2. Identify heavy consumers
3. Upgrade plan or reduce usage
4. Request temporary increase (enterprise)
### Invoice Issues
1. Check billing email settings
2. Verify invoice delivery
3. Download from dashboard
4. Contact support for corrections
## Related Topics
- [Organization Management](../23-security/organizations.md)
- [RBAC Configuration](../23-security/rbac-configuration.md)
- [White-Label Setup](./setup.md)
- [API Authentication](../10-rest/authentication.md)

92
src/23-security/README.md Normal file
View file

@ -0,0 +1,92 @@
# Advanced Security
This chapter covers advanced security topics for General Bots, including Role-Based Access Control (RBAC), organization multi-tenancy, knowledge base security, and compliance requirements.
## Overview
General Bots implements a comprehensive security model designed for enterprise deployments:
- **Multi-tenant Architecture**: Support for multiple organizations with complete data isolation
- **Role-Based Access Control (RBAC)**: Fine-grained permissions at every level
- **Knowledge Base Security**: Folder-level permissions with Qdrant vector search integration
- **SOC 2 Type II Compliance**: Enterprise-grade security controls and audit logging
## Security Layers
```
┌─────────────────────────────────────────────────────────────┐
│ Organization Layer │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Bot Layer │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ App Layer │ │ │
│ │ │ ┌─────────────────────────────────────┐ │ │ │
│ │ │ │ Resource Layer │ │ │ │
│ │ │ │ (KB folders, files, data) │ │ │ │
│ │ │ └─────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Key Concepts
### Organizations
Organizations are the top-level tenant in General Bots. Each organization has:
- Its own subscription and billing
- Isolated user base and permissions
- Separate bots and knowledge bases
- Independent quota management
Users can belong to multiple organizations and switch between them.
### Roles and Permissions
General Bots uses a role-based model with predefined roles:
| Role | Description |
|------|-------------|
| Global Admin | Full access to all resources |
| Billing Admin | Manage subscriptions and payments |
| User Admin | Manage users, groups, and role assignments |
| Bot Admin | Create and configure bots |
| KB Manager | Manage knowledge bases and permissions |
| App Developer | Create and publish apps (Forms, Sites, Projects) |
| Editor | Edit content and use apps |
| Viewer | Read-only access |
### Knowledge Base Security
KB folders can have individual permission settings:
- **Public**: Anyone can access
- **Authenticated**: Logged-in users only
- **Role-based**: Users with specific roles
- **Group-based**: Users in specific groups
- **User-based**: Named individual users
These permissions are enforced during vector search, ensuring users only see content they're authorized to access.
## In This Chapter
- [RBAC & Security Design](./rbac-design.md) - Complete RBAC architecture and security matrix
- [Organization Multi-Tenancy](./organizations.md) - Multi-organization support and switching
- [Knowledge Base Security](./kb-security.md) - Folder-level permissions and Qdrant integration
- [SOC 2 Compliance](./soc2-compliance.md) - Enterprise compliance controls
- [Security Matrix Reference](./security-matrix.md) - Complete permission reference tables
## Quick Links
- [Authentication & Permissions](../12-auth/README.md) - Basic auth setup
- [API Security](../10-rest/authentication.md) - API authentication
- [Subscription & Billing](../22-white-label/billing.md) - Plan-based access control
## Best Practices
1. **Principle of Least Privilege**: Assign the minimum permissions necessary
2. **Use Groups**: Manage permissions through groups rather than individual users
3. **Regular Audits**: Review permissions and access logs periodically
4. **Secure KB by Default**: Set restrictive default permissions on sensitive folders
5. **Enable Audit Logging**: Track all permission changes and access attempts

427
src/23-security/kb-permissions.md Normal file
View file

@ -0,0 +1,427 @@
# Knowledge Base Permissions Guide
This guide explains how to configure folder-level permissions in General Bots Knowledge Bases (.gbkb), enabling fine-grained access control that integrates with Qdrant vector search.
## Overview
Knowledge Base permissions allow you to:
- Control access to specific folders within a KB
- Filter search results based on user permissions
- Integrate with RBAC roles and groups
- Support public, authenticated, and restricted content
## Permission File Format
Each .gbkb can include a `kb.permissions.yaml` file at its root:
```yaml
version: 1
default_access: authenticated
folders:
public:
access: all
index_visibility: all
sales:
access: role_based
roles: [sales_team, management]
index_visibility: role_based
hr:
access: group_based
groups: [hr_department]
index_visibility: group_based
executive:
access: user_based
users: [ceo@company.com, cfo@company.com]
index_visibility: user_based
internal:
access: authenticated
index_visibility: authenticated
inheritance: true
```
## Configuration Options
### Version
```yaml
version: 1
```
Schema version for forward compatibility. Currently only version 1 is supported.
### Default Access
```yaml
default_access: authenticated
```
Access level for folders without explicit configuration:
| Value | Description |
|-------|-------------|
| `all` | Anyone can access, including anonymous users |
| `authenticated` | Only logged-in users (default) |
| `role_based` | Requires specific roles |
| `group_based` | Requires group membership |
| `user_based` | Specific users only |
| `none` | No access allowed |
### Folder Permissions
Each folder entry supports these options:
```yaml
folders:
folder_name:
access: <access_level>
roles: [role1, role2] # For role_based access
groups: [group1, group2] # For group_based access
users: [email1, email2, uuid1] # For user_based access
index_visibility: <level> # Search result visibility
inherit_parent: true|false # Override inheritance
```
### Access Levels
| Level | Description | Requirements |
|-------|-------------|--------------|
| `all` | Public access | None |
| `authenticated` | Logged-in users | Valid session |
| `role_based` | Role membership | User has any listed role |
| `group_based` | Group membership | User is in any listed group |
| `user_based` | Named users | User ID or email matches |
| `none` | Blocked | No one can access |
### Index Visibility
Controls whether content appears in search results:
```yaml
folders:
confidential:
access: role_based
roles: [management]
index_visibility: role_based # Only management sees in search
semi_public:
access: role_based
roles: [employees]
index_visibility: all # Everyone sees titles, only employees can open
```
Use `index_visibility` to:
- Show content exists without revealing details
- Hide sensitive content from search entirely
- Create "teaser" content that requires authentication
### Inheritance
```yaml
inheritance: true
```
When enabled, subfolders inherit parent permissions unless explicitly configured:
```
documents/
├── public/ # access: all
│ └── guides/ # inherits: all
├── internal/ # access: authenticated
│ ├── policies/ # inherits: authenticated
│ └── hr/ # explicit: group_based (overrides)
└── restricted/ # access: user_based
└── legal/ # inherits: user_based
```
Disable inheritance per folder:
```yaml
folders:
parent:
access: role_based
roles: [managers]
parent/child:
access: authenticated
inherit_parent: false # Does NOT inherit role_based
```
## Qdrant Integration
When documents are indexed, permission metadata is stored with each vector:
```json
{
"id": "doc-123",
"vector": [...],
"payload": {
"content": "Document text...",
"folder": "sales/reports",
"access_level": "role_based",
"allowed_roles": ["sales_team", "management"],
"allowed_groups": [],
"allowed_users": [],
"is_public": false,
"requires_auth": true
}
}
```
### Search Filtering
When a user searches, the system automatically adds permission filters:
For anonymous users:
```json
{
"must": [
{ "key": "is_public", "match": { "value": true } }
]
}
```
For authenticated users:
```json
{
"should": [
{ "key": "is_public", "match": { "value": true } },
{ "key": "access_level", "match": { "value": "authenticated" } },
{ "key": "allowed_roles", "match": { "any": ["sales_team"] } },
{ "key": "allowed_groups", "match": { "any": ["sales_department"] } },
{ "key": "allowed_users", "match": { "any": ["user-uuid", "user@email.com"] } }
],
"min_should": { "min_count": 1 }
}
```
## Complete Example
### Directory Structure
```
my-kb.gbkb/
├── kb.permissions.yaml
├── public/
│ ├── faq.md
│ └── getting-started.md
├── products/
│ ├── catalog.md
│ └── pricing.md
├── internal/
│ ├── processes/
│ │ └── onboarding.md
│ └── policies/
│ └── code-of-conduct.md
├── hr/
│ ├── benefits.md
│ └── salary-bands.md
└── executive/
├── board-minutes.md
└── financials.md
```
### Permission Configuration
```yaml
version: 1
default_access: authenticated
inheritance: true
folders:
public:
access: all
index_visibility: all
products:
access: all
index_visibility: all
products/pricing:
access: role_based
roles: [sales_team, account_managers]
index_visibility: authenticated
inherit_parent: false
internal:
access: authenticated
index_visibility: authenticated
internal/policies:
access: authenticated
index_visibility: all
hr:
access: group_based
groups: [hr_department, management]
index_visibility: group_based
executive:
access: user_based
users:
- ceo@company.com
- cfo@company.com
- coo@company.com
index_visibility: none
```
### Access Matrix
| Folder | Anonymous | Authenticated | Sales | HR | Executive |
|--------|-----------|---------------|-------|-----|-----------|
| public | ✓ | ✓ | ✓ | ✓ | ✓ |
| products | ✓ | ✓ | ✓ | ✓ | ✓ |
| products/pricing | ✗ | ✗ | ✓ | ✗ | ✓ |
| internal | ✗ | ✓ | ✓ | ✓ | ✓ |
| hr | ✗ | ✗ | ✗ | ✓ | ✓ |
| executive | ✗ | ✗ | ✗ | ✗ | ✓ |
## API Usage
### Check Folder Access
```http
GET /api/kb/{kb_id}/folders/{path}/access
Authorization: Bearer <token>
```
Response:
```json
{
"allowed": true,
"reason": "Role matched: sales_team",
"matched_rule": "roles: [sales_team, management]",
"index_visible": true
}
```
### Get Folder Permissions
```http
GET /api/kb/{kb_id}/folders/{path}/permissions
Authorization: Bearer <token>
```
Response:
```json
{
"folder": "products/pricing",
"access": "role_based",
"roles": ["sales_team", "account_managers"],
"groups": [],
"users": [],
"index_visibility": "authenticated",
"inherit_parent": false,
"effective_access": "role_based"
}
```
### Update Folder Permissions
```http
PUT /api/kb/{kb_id}/folders/{path}/permissions
Authorization: Bearer <token>
Content-Type: application/json
{
"access": "group_based",
"groups": ["premium_customers"],
"index_visibility": "all"
}
```
## Best Practices
### 1. Start Restrictive
Default to authenticated access and open up as needed:
```yaml
default_access: authenticated
folders:
public:
access: all # Explicitly mark public content
```
### 2. Use Groups Over Users
Prefer group-based access for easier management:
```yaml
# ✓ Good - easy to maintain
folders:
hr:
access: group_based
groups: [hr_team]
# ✗ Avoid - hard to maintain
folders:
hr:
access: user_based
users: [alice@co.com, bob@co.com, carol@co.com]
```
### 3. Document Sensitive Folders
Add comments explaining access decisions:
```yaml
folders:
# Financial data - SOC 2 requires strict access
financials:
access: user_based
users: [cfo@company.com, controller@company.com]
index_visibility: none
```
### 4. Regular Permission Audits
Export and review permissions quarterly:
```http
GET /api/kb/{kb_id}/permissions/export
```
### 5. Test with Different Users
Verify access works correctly:
1. Test anonymous access
2. Test basic authenticated user
3. Test each role/group combination
4. Verify search results match expectations
## Troubleshooting
### Document Not Appearing in Search
1. Check `index_visibility` setting
2. Verify user has required role/group
3. Re-index the document after permission changes
### Access Denied Despite Correct Role
1. Check if folder has `inherit_parent: false`
2. Verify role name matches exactly (case-sensitive)
3. Check for deny rules at parent level
### Inheritance Not Working
1. Confirm `inheritance: true` at root level
2. Check for `inherit_parent: false` on subfolder
3. Verify parent folder has explicit permissions
## Related Topics
- [RBAC Configuration](./rbac-configuration.md)
- [Organization Management](./organizations.md)
- [Security Matrix](./security-matrix.md)

443
src/23-security/organizations.md Normal file
View file

@ -0,0 +1,443 @@
# Organization Management Guide
This guide covers how to manage organizations in General Bots, including creating organizations, managing members, configuring settings, and switching between organizations.
## Overview
Organizations are the top-level tenant in General Bots, providing:
- **Complete Data Isolation**: Each organization has separate bots, knowledge bases, and data
- **Independent Billing**: Separate subscriptions and quotas per organization
- **Member Management**: Users can belong to multiple organizations
- **Custom Settings**: Branding, security policies, and preferences per organization
## Creating an Organization
### Via UI
1. Click your profile avatar in the top-right corner
2. Click **Create Organization**
3. Fill in the organization details:
- **Name**: Display name for the organization
- **Slug**: URL-friendly identifier (auto-generated from name)
- **Description**: Optional description
4. Click **Create**
### Via API
```http
POST /api/organizations
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Acme Corporation",
"description": "Main organization for Acme Corp"
}
```
Response:
```json
{
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Acme Corporation",
"slug": "acme-corporation",
"description": "Main organization for Acme Corp",
"plan_id": "free",
"owner_id": "user-uuid",
"created_at": "2025-01-21T10:00:00Z"
},
"roles": [...],
"groups": [...],
"owner_member": {...},
"owner_role": {...}
}
```
When you create an organization, you automatically become the owner with full permissions.
## Organization Structure
Each organization includes:
```
Organization
├── Settings
│ ├── General (name, logo, website)
│ ├── Security (2FA, SSO, IP whitelist)
│ ├── Branding (colors, custom CSS)
│ └── Billing (plan, quotas)
├── Members
│ ├── Users
│ ├── Roles
│ └── Groups
├── Bots
│ └── [bot configurations]
├── Apps
│ ├── Forms
│ ├── Sites
│ └── Projects
└── Knowledge Bases
└── [.gbkb packages]
```
## Managing Members
### Inviting Members
1. Navigate to **Settings** → **Members**
2. Click **Invite Member**
3. Enter email address and select role
4. Click **Send Invitation**
```http
POST /api/organizations/{org_id}/invitations
Authorization: Bearer <token>
Content-Type: application/json
{
"email": "newuser@company.com",
"role": "member"
}
```
### Member Roles
When inviting members, assign an appropriate role:
| Role | Typical Use |
|------|-------------|
| Admin | Department heads, IT managers |
| Manager | Team leads, project managers |
| Member | Regular employees |
| Viewer | Stakeholders, external reviewers |
### Accepting Invitations
Invited users receive an email with a link to accept the invitation:
1. Click the invitation link
2. Sign in or create an account
3. Review organization details
4. Click **Accept Invitation**
### Removing Members
1. Navigate to **Settings** → **Members**
2. Find the member in the list
3. Click the menu icon (⋮)
4. Select **Remove from Organization**
```http
DELETE /api/organizations/{org_id}/members/{user_id}
Authorization: Bearer <token>
```
## Organization Settings
### General Settings
| Setting | Description |
|---------|-------------|
| Name | Display name |
| Slug | URL identifier |
| Description | Organization description |
| Logo URL | Logo image URL |
| Website | Organization website |
### Security Settings
| Setting | Description | Default |
|---------|-------------|---------|
| Require 2FA | Require two-factor authentication | false |
| Allowed Email Domains | Restrict sign-ups to specific domains | [] |
| SSO Enabled | Enable Single Sign-On | false |
| SSO Provider | SSO provider configuration | null |
| IP Whitelist | Allowed IP addresses | [] |
| Audit Log Retention | Days to keep audit logs | 90 |
### Custom Branding
| Setting | Description |
|---------|-------------|
| Primary Color | Main brand color |
| Secondary Color | Accent color |
| Logo URL | Custom logo |
| Favicon URL | Browser favicon |
| Custom CSS | Additional styling |
### Configuration Example
```yaml
settings:
allow_public_bots: false
require_2fa: true
allowed_email_domains:
- company.com
- subsidiary.com
default_user_role: member
max_members: 100
sso_enabled: true
sso_provider: okta
audit_log_retention_days: 365
ip_whitelist:
- 10.0.0.0/8
- 192.168.1.0/24
custom_branding:
primary_color: "#0066cc"
secondary_color: "#004499"
logo_url: "https://cdn.company.com/logo.svg"
```
## Switching Organizations
Users who belong to multiple organizations can switch between them.
### Via UI
1. Click your profile avatar or the organization name
2. A dropdown shows all your organizations
3. Click the organization to switch to
### Via API
```http
POST /api/user/switch-organization
Authorization: Bearer <token>
Content-Type: application/json
{
"org_id": "target-organization-uuid"
}
```
The response includes a new session token scoped to the selected organization.
## Organization Switcher Component
The organization switcher displays:
- Current organization name and logo
- User's role in current organization
- List of other organizations
- Quick actions (create new, manage current)
```html
<div class="org-selector">
<div class="selected-org">
<div class="org-avatar">AC</div>
<div class="org-info">
<span class="org-name">Acme Corporation</span>
<span class="org-role">Admin</span>
</div>
</div>
<div class="org-dropdown">
<div class="org-dropdown-item">
<div class="org-avatar">XY</div>
<span>XYZ Partners</span>
</div>
<div class="org-dropdown-actions">
<button>+ Create Organization</button>
</div>
</div>
</div>
```
## Quotas and Limits
Each organization has quotas based on their plan:
| Quota | Free | Pro | Enterprise |
|-------|------|-----|------------|
| Members | 5 | 50 | Unlimited |
| Bots | 2 | 20 | Unlimited |
| Storage | 1 GB | 50 GB | 1 TB |
| API Calls/month | 10,000 | 500,000 | Unlimited |
| Messages/month | 1,000 | 100,000 | Unlimited |
### Checking Usage
```http
GET /api/organizations/{org_id}/usage
Authorization: Bearer <token>
```
Response:
```json
{
"organization_id": "org-uuid",
"period": "2025-01",
"quotas": {
"members": { "used": 12, "limit": 50, "percent": 24 },
"storage_mb": { "used": 5120, "limit": 51200, "percent": 10 },
"api_calls": { "used": 45000, "limit": 500000, "percent": 9 },
"messages": { "used": 8500, "limit": 100000, "percent": 8.5 }
}
}
```
## Deleting an Organization
Only the organization owner can delete an organization.
1. Navigate to **Settings** → **General**
2. Scroll to **Danger Zone**
3. Click **Delete Organization**
4. Type the organization name to confirm
5. Click **Delete Permanently**
```http
DELETE /api/organizations/{org_id}
Authorization: Bearer <token>
Content-Type: application/json
{
"confirmation": "organization-name"
}
```
Deletion is permanent and removes:
- All organization data
- All bots and configurations
- All knowledge bases
- All apps (Forms, Sites, Projects)
- All member associations
- All billing data
## Multi-Organization Patterns
### Separate Environments
Use organizations for dev/staging/production:
```
Acme Corp - Development
Acme Corp - Staging
Acme Corp - Production
```
### Department Isolation
Separate organizations per department:
```
Acme Corp - Sales
Acme Corp - Support
Acme Corp - Engineering
```
### Client Projects
Agencies can create organizations per client:
```
Client A - Project X
Client B - Project Y
Internal - Agency Tools
```
## API Reference
### List User's Organizations
```http
GET /api/user/organizations
Authorization: Bearer <token>
```
### Get Organization Details
```http
GET /api/organizations/{org_id}
Authorization: Bearer <token>
```
### Update Organization
```http
PATCH /api/organizations/{org_id}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "New Name",
"description": "Updated description"
}
```
### List Organization Members
```http
GET /api/organizations/{org_id}/members
Authorization: Bearer <token>
```
### Update Organization Settings
```http
PUT /api/organizations/{org_id}/settings
Authorization: Bearer <token>
Content-Type: application/json
{
"require_2fa": true,
"allowed_email_domains": ["company.com"]
}
```
## Best Practices
### 1. Clear Naming Conventions
Use consistent naming for multiple organizations:
```
[Company] - [Environment/Purpose]
Acme Corp - Production
Acme Corp - Development
```
### 2. Appropriate Role Assignment
Don't over-assign admin roles:
- One or two owners maximum
- Admins for department heads
- Managers for team leads
- Members for everyone else
### 3. Regular Member Audits
Review members quarterly:
- Remove departed employees
- Adjust roles as responsibilities change
- Check for inactive accounts
### 4. Security Configuration
For enterprise organizations:
- Enable 2FA requirement
- Configure SSO if available
- Set IP whitelist for office networks
- Increase audit log retention
### 5. Quota Monitoring
Set up alerts for quota usage:
- 80% warning for planning
- 90% critical for immediate action
- Monitor trends over time
## Related Topics
- [RBAC Configuration](./rbac-configuration.md)
- [Subscription & Billing](../22-white-label/billing.md)
- [Security Matrix](./security-matrix.md)
- [SOC 2 Compliance](./soc2-compliance.md)

412
src/23-security/rbac-configuration.md Normal file
View file

@ -0,0 +1,412 @@
# RBAC Configuration Guide
This guide covers how to configure Role-Based Access Control (RBAC) in General Bots, including role management, group setup, permission assignment, and best practices for enterprise deployments.
## Overview
General Bots RBAC provides:
- **Hierarchical Roles**: Roles inherit permissions from parent roles
- **Group-based Access**: Organize users into groups for easier management
- **Permission Inheritance**: Permissions flow down through the hierarchy
- **Resource-level Control**: Fine-grained access to bots, apps, and knowledge bases
## Default Roles
General Bots includes predefined system roles that cannot be deleted:
| Role | Hierarchy Level | Description |
|------|----------------|-------------|
| Owner | 100 | Full organization control, including deletion |
| Admin | 90 | Manage all resources except organization deletion |
| Manager | 70 | Create and manage bots, KB, and apps |
| Member | 50 | Standard access to organization resources |
| Viewer | 30 | Read-only access to bots and knowledge bases |
| Guest | 10 | Limited public access only |
### Role Hierarchy
Higher-level roles automatically inherit permissions from lower-level roles:
```
Owner (100)
└── Admin (90)
└── Manager (70)
└── Member (50)
└── Viewer (30)
└── Guest (10)
```
An Admin can manage any role below them (Manager, Member, Viewer, Guest) but cannot modify Owner permissions.
## Configuring Roles
### Creating a Custom Role
Custom roles can extend the default hierarchy:
1. Navigate to **Settings** → **Access Control** → **Roles**
2. Click **Create Role**
3. Configure:
- **Name**: Internal identifier (lowercase, no spaces)
- **Display Name**: Human-readable name
- **Hierarchy Level**: Position in hierarchy (1-99)
- **Parent Roles**: Roles to inherit from
- **Permissions**: Additional permissions
### Permission Format
Permissions use a colon-separated format:
```
resource:action
resource:action:scope
```
Examples:
| Permission | Description |
|------------|-------------|
| `bot:create` | Create new bots |
| `bot:view` | View bot details |
| `bot:edit` | Edit bot configuration |
| `bot:delete` | Delete bots |
| `bot:*` | All bot permissions |
| `kb:read` | Read knowledge base content |
| `kb:write` | Write to knowledge bases |
| `kb:admin` | Administer KB settings |
| `app:create` | Create apps (Forms, Sites) |
| `app:view` | View apps |
| `app:edit` | Edit apps |
| `org:manage` | Manage organization settings |
| `org:billing` | Access billing information |
| `org:members` | Manage organization members |
| `*` | Wildcard - all permissions |
### Role Configuration Example
```yaml
name: content_editor
display_name: Content Editor
hierarchy_level: 55
parent_roles:
- member
permissions:
- kb:read
- kb:write
- bot:view
- app:view
- app:edit
```
## Configuring Groups
Groups provide an additional layer of organization for users.
### Default Groups
| Group | Description |
|-------|-------------|
| everyone | All authenticated users |
| developers | Users who create bots and apps |
| content_managers | Users who manage knowledge bases |
| support | Support team with analytics access |
### Creating Groups
1. Navigate to **Settings** → **Access Control** → **Groups**
2. Click **Create Group**
3. Configure:
- **Name**: Internal identifier
- **Display Name**: Human-readable name
- **Parent Group**: Optional hierarchy
- **Permissions**: Group-specific permissions
### Group Hierarchy
Groups can have parent-child relationships:
```
everyone
├── developers
│ └── senior_developers
├── content_managers
│ └── kb_admins
└── support
└── tier2_support
```
Child groups inherit permissions from parent groups.
## Assigning Permissions
### To Users
Assign roles directly to users:
```
User: john@company.com
Roles: manager, content_editor
Groups: developers, content_managers
```
### To Bots
Control who can access each bot:
```yaml
bot_id: my-support-bot
visibility: organization
allowed_roles:
- member
- viewer
allowed_groups:
- support
denied_users: []
```
### To Apps
Control app access (Forms, Sites, Dashboards):
```yaml
app_id: customer-feedback-form
app_type: form
visibility: public
allowed_roles: []
submission_requires_auth: false
```
### To Knowledge Base Folders
See [KB Permissions Guide](./kb-permissions.md) for detailed folder configuration.
## Permission Inheritance Resolution
When checking if a user has permission, the system evaluates:
1. **Direct User Permissions**: Explicitly assigned to the user
2. **Role Permissions**: From all assigned roles (including inherited)
3. **Group Permissions**: From all group memberships (including inherited)
### Resolution Example
```
User: alice@company.com
Direct Permissions: analytics:export
Roles: manager (inherits from member, viewer)
Groups: content_managers (inherits from everyone)
Effective Permissions:
├── analytics:export (direct)
├── org:members:view (from manager)
├── bot:create (from manager)
├── bot:edit (from manager)
├── bot:view (from member, inherited by manager)
├── kb:read (from member)
├── kb:write (from content_managers)
├── kb:admin (from content_managers)
└── basic:access (from everyone)
```
## Wildcard Permissions
Use wildcards for broad access:
| Pattern | Matches |
|---------|---------|
| `*` | All permissions |
| `bot:*` | All bot permissions |
| `kb:*` | All knowledge base permissions |
| `app:*` | All app permissions |
| `org:*` | All organization permissions |
## Configuration via API
### List Roles
```http
GET /api/settings/rbac/roles
Authorization: Bearer <token>
```
### Create Role
```http
POST /api/settings/rbac/roles
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "custom_role",
"display_name": "Custom Role",
"description": "A custom role for specific needs",
"hierarchy_level": 45,
"parent_roles": ["member"],
"permissions": ["kb:read", "kb:write"]
}
```
### Assign Role to User
```http
POST /api/settings/rbac/users/{user_id}/roles/{role_id}
Authorization: Bearer <token>
Content-Type: application/json
{
"expires_at": "2025-12-31T23:59:59Z"
}
```
### Add User to Group
```http
POST /api/settings/rbac/users/{user_id}/groups/{group_id}
Authorization: Bearer <token>
```
### Get Effective Permissions
```http
GET /api/settings/rbac/users/{user_id}/permissions
Authorization: Bearer <token>
```
Response:
```json
{
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"bot:view",
"bot:create",
"kb:read",
"kb:write"
],
"sources": [
{
"permission": "bot:view",
"source_type": "role",
"source_name": "member"
},
{
"permission": "kb:write",
"source_type": "group",
"source_name": "content_managers"
}
]
}
```
## Audit Logging
All permission changes are logged for compliance:
| Event | Logged Data |
|-------|-------------|
| Role Assignment | Actor, target user, role, timestamp |
| Role Revocation | Actor, target user, role, timestamp |
| Group Addition | Actor, target user, group, timestamp |
| Group Removal | Actor, target user, group, timestamp |
| Permission Grant | Actor, target, permission, timestamp |
| Access Denied | Actor, resource, required permission |
Access audit logs at **Settings** → **Security** → **Audit Log**.
## Best Practices
### 1. Use Groups Over Direct Assignment
Instead of assigning roles to individual users, create groups:
```
✓ Create "Sales Team" group with viewer + CRM permissions
✓ Add users to the group
✗ Assign roles individually to 50 users
```
### 2. Follow Least Privilege
Start with minimal permissions and add as needed:
```
✓ New users get "viewer" role by default
✓ Promote to "member" after onboarding
✗ Give everyone "admin" for convenience
```
### 3. Use Role Expiration
For temporary access, set expiration dates:
```http
POST /api/settings/rbac/users/{user_id}/roles/{role_id}
{
"expires_at": "2025-03-01T00:00:00Z"
}
```
### 4. Regular Permission Reviews
Schedule quarterly reviews:
1. Export current permissions
2. Review access patterns in audit logs
3. Remove unused permissions
4. Update role definitions as needed
### 5. Document Custom Roles
Maintain documentation for custom roles:
```markdown
## Custom Role: Project Lead
**Purpose**: Lead project teams with limited admin access
**Permissions**:
- All member permissions
- bot:create, bot:edit
- app:create, app:edit
- org:members:view
**Assigned To**: Project leads and tech leads
**Created**: 2025-01-15
**Last Review**: 2025-01-21
```
## Troubleshooting
### User Cannot Access Resource
1. Check user's effective permissions:
```http
GET /api/settings/rbac/users/{user_id}/permissions
```
2. Verify resource permissions:
```http
GET /api/bots/{bot_id}/access
```
3. Check audit log for denied access attempts
### Permission Not Working After Assignment
1. Clear user's session cache
2. User may need to log out and back in
3. Check if permission is blocked by a deny rule
### Role Changes Not Reflected
1. Permission cache has 5-minute TTL
2. Force refresh: User logs out/in
3. Check if role assignment has expiration date
## Related Topics
- [Security Matrix Reference](./security-matrix.md)
- [KB Permissions Guide](./kb-permissions.md)
- [Organization Management](./organizations.md)
- [SOC 2 Compliance](./soc2-compliance.md)

393
src/23-security/rbac-design.md Normal file
View file

@ -0,0 +1,393 @@
# RBAC & Security Design
This document describes the Role-Based Access Control (RBAC) system and security architecture for General Bots.
## Overview
General Bots implements a comprehensive RBAC system that controls access at multiple levels:
1. **Organization Level** - Who can access the organization
2. **Bot Level** - Who can use specific bots
3. **App Level** - Who can use apps within a bot (Forms, Sites, Projects)
4. **Knowledge Base Level** - Who can access specific KB folders and documents
5. **Resource Level** - Granular permissions on individual resources
## Security Matrix
### Organization Permissions
| Permission | Global Admin | Billing Admin | User Admin | Bot Admin | KB Manager | Editor | Viewer |
|------------|:------------:|:-------------:|:----------:|:---------:|:----------:|:------:|:------:|
| Create Organization | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Delete Organization | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Manage Settings | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| View Billing | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Manage Billing | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Invite Members | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Remove Members | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage Roles | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
### Bot Permissions
| Permission | Global Admin | Bot Admin | KB Manager | Editor | Viewer | Guest |
|------------|:------------:|:---------:|:----------:|:------:|:------:|:-----:|
| Create Bot | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Delete Bot | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Configure Bot | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| View Bot Settings | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Use Bot Chat | ✅ | ✅ | ✅ | ✅ | ✅ | ✅* |
| View Analytics | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Export Analytics | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
*Guest access limited by plan quotas
### Knowledge Base Permissions
| Permission | Global Admin | Bot Admin | KB Manager | Editor | Viewer |
|------------|:------------:|:---------:|:----------:|:------:|:------:|
| Create KB | ✅ | ✅ | ✅ | ❌ | ❌ |
| Delete KB | ✅ | ✅ | ✅ | ❌ | ❌ |
| Create Folders | ✅ | ✅ | ✅ | ✅ | ❌ |
| Upload Files | ✅ | ✅ | ✅ | ✅ | ❌ |
| Edit Files | ✅ | ✅ | ✅ | ✅ | ❌ |
| Delete Files | ✅ | ✅ | ✅ | ❌ | ❌ |
| View Files | ✅ | ✅ | ✅ | ✅ | ✅ |
| Manage Permissions | ✅ | ✅ | ✅ | ❌ | ❌ |
| Re-index Content | ✅ | ✅ | ✅ | ❌ | ❌ |
### App Permissions (Forms, Sites, Projects)
| Permission | Global Admin | Bot Admin | App Developer | Editor | Viewer |
|------------|:------------:|:---------:|:-------------:|:------:|:------:|
| Create App | ✅ | ✅ | ✅ | ❌ | ❌ |
| Delete App | ✅ | ✅ | ✅ | ❌ | ❌ |
| Edit App | ✅ | ✅ | ✅ | ✅ | ❌ |
| Publish App | ✅ | ✅ | ✅ | ❌ | ❌ |
| Use App | ✅ | ✅ | ✅ | ✅ | ✅ |
| View Submissions | ✅ | ✅ | ✅ | ✅ | ❌ |
| Export Data | ✅ | ✅ | ✅ | ❌ | ❌ |
## Organization Multi-Tenancy
### User-Organization Relationship
Users can belong to multiple organizations, similar to Azure Active Directory tenants:
```
┌─────────────────────────────────────────────────────────────┐
│ User: john@example.com │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Org A │ │ Org B │ │ Org C │ │
│ │ (Admin) │ │ (Editor) │ │ (Viewer) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Organization Switcher
The avatar menu includes an organization switcher:
1. Current organization indicator
2. List of user's organizations
3. Option to create new organization
4. Organization settings access (for admins)
## Knowledge Base Folder Security
### Permission File Format
Each `.gbkb` package can contain a `kb.permissions.yaml` file:
```yaml
version: 1
default_access: authenticated
folders:
public:
access: all
description: "Publicly accessible content"
index_visibility: all
internal:
access: role_based
roles:
- employee
- contractor
index_visibility: role_based
hr-policies:
access: group_based
groups:
- hr_department
- management
index_visibility: group_based
executive:
access: user_based
users:
- ceo@company.com
- cfo@company.com
- coo@company.com
index_visibility: user_based
inheritance: true
```
### Folder Permission Levels
| Access Level | Description | Who Can Access |
|--------------|-------------|----------------|
| `all` | Public access | Anyone, including anonymous |
| `authenticated` | Logged in users | Any authenticated user |
| `role_based` | By role | Users with specified roles |
| `group_based` | By group | Users in specified groups |
| `user_based` | By user | Specifically named users |
### Permission Inheritance
When `inheritance: true`, subfolders inherit parent permissions unless explicitly overridden:
```
hr-policies/ (groups: hr_department, management)
├── onboarding/ (inherits parent)
├── compensation/ (groups: hr_department only - more restrictive)
└── public-handbook/ (access: authenticated - less restrictive)
```
## Qdrant Vector Integration
### Permission Metadata in Vectors
When indexing KB content, permission metadata is stored with each vector:
```json
{
"id": "doc-uuid",
"vector": [...],
"payload": {
"content": "Document text...",
"source": "hr-policies/compensation/salary-bands.md",
"folder": "hr-policies/compensation",
"access_level": "group_based",
"allowed_groups": ["hr_department"],
"allowed_roles": [],
"allowed_users": [],
"indexed_at": "2025-01-21T10:00:00Z"
}
}
```
### Search Query Filtering
When a user searches, their permissions are used to filter results:
```rust
// Pseudo-code for permission filtering
fn build_search_filter(user: &User) -> Filter {
Filter::should([
// Public content
Filter::must([
FieldCondition::match_value("access_level", "all")
]),
// Authenticated content
Filter::must([
FieldCondition::match_value("access_level", "authenticated")
]),
// Role-based content
Filter::must([
FieldCondition::match_value("access_level", "role_based"),
FieldCondition::match_any("allowed_roles", user.roles)
]),
// Group-based content
Filter::must([
FieldCondition::match_value("access_level", "group_based"),
FieldCondition::match_any("allowed_groups", user.groups)
]),
// User-based content
Filter::must([
FieldCondition::match_value("access_level", "user_based"),
FieldCondition::match_value("allowed_users", user.email)
])
])
}
```
## Bot-Level Access Control
### Bot Access Configuration
Each bot has access control settings:
```yaml
bot_access:
id: "bot-uuid"
name: "HR Assistant"
access_type: "groups" # organization | groups | users | public
# For groups access type
allowed_groups:
- hr_department
- management
# For users access type
allowed_users:
- specific.user@company.com
# Public bots
public: false
anonymous_allowed: false
```
### App-Level Access (1 Bot : N Apps)
A bot can have multiple apps, each with its own permissions:
```yaml
apps:
- id: "app-uuid-1"
name: "Leave Request Form"
type: "form"
bot_id: "bot-uuid"
access:
type: "inherit" # Inherits from bot
- id: "app-uuid-2"
name: "Salary Calculator"
type: "form"
bot_id: "bot-uuid"
access:
type: "custom"
allowed_groups:
- hr_department # More restrictive than bot
- id: "app-uuid-3"
name: "Company Directory"
type: "site"
bot_id: "bot-uuid"
access:
type: "custom"
allowed_groups:
- all_users # Less restrictive - all employees
```
## Default Roles and Groups
### Default Roles (Microsoft 365-like)
| Role | Description |
|------|-------------|
| `global_admin` | Full access to everything |
| `billing_admin` | Manage subscriptions and payments |
| `user_admin` | Manage users and groups |
| `bot_admin` | Create and manage bots |
| `kb_manager` | Manage knowledge bases |
| `app_developer` | Create and manage apps |
| `support_agent` | Handle support conversations |
| `viewer` | Read-only access |
### Default Groups
| Group | Description |
|-------|-------------|
| `all_users` | All organization members |
| `guests` | External guests with limited access |
| `external_users` | External collaborators |
### Default Permission Assignments
```yaml
role_permissions:
global_admin:
- "*" # All permissions
billing_admin:
- "billing.view"
- "billing.manage"
- "subscription.view"
- "subscription.manage"
user_admin:
- "users.view"
- "users.create"
- "users.update"
- "users.delete"
- "groups.view"
- "groups.create"
- "groups.update"
- "groups.delete"
- "roles.assign"
bot_admin:
- "bots.view"
- "bots.create"
- "bots.update"
- "bots.delete"
- "kb.view"
- "kb.create"
- "kb.update"
- "kb.delete"
kb_manager:
- "kb.view"
- "kb.create"
- "kb.update"
- "kb.index"
- "kb.permissions"
app_developer:
- "apps.view"
- "apps.create"
- "apps.update"
- "apps.delete"
- "apps.publish"
support_agent:
- "bots.use"
- "conversations.view"
- "conversations.respond"
viewer:
- "bots.use"
- "kb.view"
- "apps.use"
- "analytics.view"
```
## Audit Logging
All permission-related actions are logged:
```json
{
"timestamp": "2025-01-21T10:30:00Z",
"event_type": "permission_change",
"actor": "admin@company.com",
"action": "grant_role",
"target_user": "employee@company.com",
"role": "kb_manager",
"organization_id": "org-uuid",
"ip_address": "192.168.1.100",
"user_agent": "Mozilla/5.0..."
}
```
## Implementation Checklist
- [ ] Organization multi-tenancy tables
- [ ] Organization switcher UI component
- [ ] Role and permission tables
- [ ] Default roles/groups seeding
- [ ] KB permission file parser
- [ ] Qdrant metadata enrichment during indexing
- [ ] Qdrant search filter by permissions
- [ ] Bot access control
- [ ] App access control
- [ ] Audit logging
- [ ] Permission sync job for KB updates
## Related Documentation
- [Subscription & Billing](../22-white-label/billing.md)
- [SOC 2 Compliance](./soc2-compliance.md)
- [API Authentication](../12-auth/README.md)

438
src/23-security/soc2-compliance.md Normal file
View file

@ -0,0 +1,438 @@
# SOC 2 Type II Compliance
This guide covers General Bots' SOC 2 Type II compliance implementation, including security controls, audit logging, evidence collection, and compliance reporting.
## Overview
SOC 2 Type II is a security framework developed by the American Institute of CPAs (AICPA) that evaluates how organizations manage customer data based on five Trust Service Criteria:
1. **Security** - Protection against unauthorized access
2. **Availability** - System accessibility as agreed
3. **Processing Integrity** - Accurate and timely processing
4. **Confidentiality** - Protection of confidential information
5. **Privacy** - Personal information handling
General Bots implements controls across all five criteria to ensure enterprise-grade security.
## Trust Service Criteria Implementation
### Security (Common Criteria)
| Control | Implementation | Status |
|---------|---------------|--------|
| CC1.1 - Integrity & Ethics | Code of conduct, security policies | ✅ |
| CC2.1 - Communication | Security awareness training | ✅ |
| CC3.1 - Risk Assessment | Quarterly risk assessments | ✅ |
| CC4.1 - Monitoring | Continuous security monitoring | ✅ |
| CC5.1 - Control Activities | Access controls, encryption | ✅ |
| CC6.1 - Logical Access | RBAC, MFA, session management | ✅ |
| CC7.1 - System Operations | Change management, incident response | ✅ |
| CC8.1 - Change Management | Documented change procedures | ✅ |
| CC9.1 - Risk Mitigation | Vendor management, BCP | ✅ |
### Availability
| Control | Implementation |
|---------|---------------|
| A1.1 - Capacity Management | Auto-scaling, resource monitoring |
| A1.2 - Recovery Operations | Automated backups, disaster recovery |
| A1.3 - Recovery Testing | Quarterly DR tests |
### Processing Integrity
| Control | Implementation |
|---------|---------------|
| PI1.1 - Processing Accuracy | Input validation, data integrity checks |
| PI1.2 - Processing Completeness | Transaction logging, audit trails |
| PI1.3 - Processing Timeliness | SLA monitoring, performance metrics |
### Confidentiality
| Control | Implementation |
|---------|---------------|
| C1.1 - Confidential Information | Data classification, encryption at rest |
| C1.2 - Disposal | Secure deletion, data retention policies |
### Privacy
| Control | Implementation |
|---------|---------------|
| P1.1 - Notice | Privacy policy, cookie consent |
| P2.1 - Choice and Consent | Opt-in/opt-out mechanisms |
| P3.1 - Collection | Data minimization |
| P4.1 - Use and Retention | Purpose limitation, retention schedules |
| P5.1 - Access | Data export (GDPR Article 15) |
| P6.1 - Disclosure | Third-party data sharing controls |
| P7.1 - Quality | Data accuracy verification |
| P8.1 - Monitoring | Privacy impact assessments |
## Audit Logging
### Event Categories
General Bots logs the following security-relevant events:
| Category | Events Logged |
|----------|--------------|
| Authentication | Login, logout, MFA events, password changes |
| Authorization | Permission grants, role assignments, access denials |
| Data Access | Read operations on sensitive data |
| Data Modification | Create, update, delete operations |
| Administrative | Configuration changes, user management |
| Security | Failed auth attempts, suspicious activity |
### Log Structure
```json
{
"id": "uuid",
"timestamp": "2025-01-21T10:30:00Z",
"organization_id": "org-uuid",
"actor_id": "user-uuid",
"actor_email": "user@company.com",
"actor_ip": "192.168.1.100",
"action": "role_assign",
"resource_type": "role",
"resource_id": "role-uuid",
"resource_name": "admin",
"details": {
"description": "Assigned role 'admin' to user",
"before_state": null,
"after_state": {"role": "admin"},
"changes": [{"field": "role", "old_value": null, "new_value": "admin"}]
},
"result": "success",
"metadata": {}
}
```
### Log Retention
| Log Type | Retention Period | Storage |
|----------|-----------------|---------|
| Security Events | 7 years | Immutable storage |
| Access Logs | 2 years | Standard storage |
| Application Logs | 90 days | Standard storage |
| Debug Logs | 30 days | Ephemeral storage |
### Accessing Audit Logs
```http
GET /api/compliance/audit-logs
Authorization: Bearer <token>
```
Query parameters:
| Parameter | Description |
|-----------|-------------|
| `organization_id` | Filter by organization |
| `actor_id` | Filter by user |
| `action` | Filter by action type |
| `resource_type` | Filter by resource type |
| `start_date` | Start of date range |
| `end_date` | End of date range |
| `page` | Page number |
| `per_page` | Results per page |
## Security Controls
### Access Control
**Multi-Factor Authentication (MFA)**
- TOTP-based authentication
- Hardware security key support (FIDO2/WebAuthn)
- SMS backup codes (optional)
**Session Management**
- Configurable session timeout (default: 8 hours)
- Concurrent session limits
- Session invalidation on password change
- IP-based session binding (optional)
**Password Policy**
- Minimum 12 characters
- Complexity requirements
- Password history (last 10)
- Account lockout after 5 failed attempts
### Encryption
**Data at Rest**
- AES-256 encryption for all stored data
- Encrypted database columns for PII
- Encrypted file storage (MinIO with server-side encryption)
**Data in Transit**
- TLS 1.3 for all connections
- Perfect Forward Secrecy
- HSTS with preloading
- Certificate pinning (mobile apps)
### Network Security
- Web Application Firewall (WAF)
- DDoS protection
- Rate limiting per endpoint
- IP allowlisting (enterprise)
## Compliance Reporting
### Generating Compliance Reports
```http
POST /api/compliance/reports
Authorization: Bearer <token>
Content-Type: application/json
{
"report_type": "soc2",
"period_start": "2025-01-01",
"period_end": "2025-03-31",
"criteria": ["security", "availability", "confidentiality"]
}
```
### Report Types
| Type | Description | Frequency |
|------|-------------|-----------|
| `soc2` | Full SOC 2 compliance report | Quarterly |
| `access_review` | User access review | Monthly |
| `vulnerability` | Vulnerability assessment | Weekly |
| `incident` | Security incident report | As needed |
### Evidence Collection
The compliance module automatically collects evidence for audit:
**User Access Evidence**
- Current user list with roles
- Permission assignment history
- Access review sign-offs
**Change Management Evidence**
- Deployment logs
- Configuration change records
- Approval workflows
**Security Evidence**
- Vulnerability scan results
- Penetration test reports
- Security training completion
### Exporting Evidence
```http
GET /api/compliance/evidence/export
Authorization: Bearer <token>
```
Query parameters:
| Parameter | Description |
|-----------|-------------|
| `criteria` | SOC 2 criteria (CC6.1, A1.1, etc.) |
| `period_start` | Evidence period start |
| `period_end` | Evidence period end |
| `format` | Export format (json, csv, pdf) |
## Incident Response
### Incident Classification
| Severity | Description | Response Time |
|----------|-------------|---------------|
| Critical | Data breach, system compromise | 15 minutes |
| High | Service outage, failed controls | 1 hour |
| Medium | Suspicious activity, minor issues | 4 hours |
| Low | Informational, potential risk | 24 hours |
### Incident Response Process
1. **Detection** - Automated monitoring or manual report
2. **Triage** - Classify severity, assign responder
3. **Containment** - Isolate affected systems
4. **Eradication** - Remove threat
5. **Recovery** - Restore services
6. **Lessons Learned** - Post-incident review
### Incident Logging
```http
POST /api/compliance/incidents
Authorization: Bearer <token>
Content-Type: application/json
{
"title": "Suspicious login activity detected",
"severity": "medium",
"description": "Multiple failed login attempts from unusual location",
"affected_systems": ["authentication"],
"detected_at": "2025-01-21T10:00:00Z",
"detected_by": "automated_monitoring"
}
```
## Vendor Management
### Third-Party Risk Assessment
All vendors handling customer data undergo:
- Security questionnaire
- SOC 2 report review (if available)
- Contract review for security requirements
- Annual reassessment
### Key Vendors
| Vendor | Service | SOC 2 | Data Access |
|--------|---------|-------|-------------|
| PostgreSQL | Database | N/A (self-hosted) | Full |
| MinIO | Object Storage | N/A (self-hosted) | Full |
| Qdrant | Vector DB | N/A (self-hosted) | Full |
| Redis | Caching | N/A (self-hosted) | Session data |
## Business Continuity
### Recovery Objectives
| Metric | Target | Current |
|--------|--------|---------|
| RTO (Recovery Time Objective) | 4 hours | 2 hours |
| RPO (Recovery Point Objective) | 1 hour | 15 minutes |
| MTTR (Mean Time to Recovery) | 2 hours | 45 minutes |
### Backup Strategy
| Data Type | Frequency | Retention | Location |
|-----------|-----------|-----------|----------|
| Database | Every 15 minutes | 30 days | Off-site |
| Files | Hourly | 90 days | Off-site |
| Configuration | On change | Forever | Git |
| Logs | Daily | Per retention policy | Off-site |
### Disaster Recovery
- Multi-region deployment capability
- Automated failover
- Quarterly DR testing
- Documented recovery procedures
## Configuration
### Enabling SOC 2 Features
Add to your `.env`:
```bash
SOC2_COMPLIANCE_ENABLED=true
SOC2_AUDIT_LOG_RETENTION_DAYS=2555
SOC2_EVIDENCE_COLLECTION=true
SOC2_INCIDENT_AUTO_CREATE=true
```
### Compliance Dashboard
Access the compliance dashboard at:
```
/admin/compliance
```
Features:
- Real-time compliance status
- Control effectiveness metrics
- Open findings and remediation
- Upcoming audit timeline
## API Reference
### Get Compliance Status
```http
GET /api/compliance/status
Authorization: Bearer <token>
```
Response:
```json
{
"overall_status": "compliant",
"last_assessment": "2025-01-15T00:00:00Z",
"criteria": {
"security": {"status": "compliant", "controls_passed": 45, "controls_total": 45},
"availability": {"status": "compliant", "controls_passed": 12, "controls_total": 12},
"confidentiality": {"status": "compliant", "controls_passed": 8, "controls_total": 8}
},
"open_findings": 0,
"next_audit": "2025-04-01"
}
```
### List Control Evidence
```http
GET /api/compliance/controls/{control_id}/evidence
Authorization: Bearer <token>
```
### Create Finding
```http
POST /api/compliance/findings
Authorization: Bearer <token>
Content-Type: application/json
{
"control_id": "CC6.1",
"title": "MFA not enforced for admin accounts",
"severity": "high",
"description": "Admin accounts can bypass MFA requirement",
"remediation_plan": "Update policy to require MFA for all admin roles",
"due_date": "2025-02-01"
}
```
## Best Practices
### For Administrators
1. **Enable all logging** - Ensure comprehensive audit trails
2. **Regular access reviews** - Monthly review of user permissions
3. **Monitor dashboards** - Daily check of compliance status
4. **Document exceptions** - Record all policy exceptions with justification
5. **Test controls** - Quarterly verification of control effectiveness
### For Developers
1. **Follow secure coding standards** - No hardcoded secrets, input validation
2. **Use security modules** - SafeCommand, sql_guard, error_sanitizer
3. **Log security events** - Use audit logging for sensitive operations
4. **Handle errors properly** - Never expose internal details
### For Organizations
1. **Assign compliance owner** - Dedicated person for SOC 2
2. **Schedule regular audits** - Annual Type II assessment
3. **Train employees** - Security awareness program
4. **Maintain documentation** - Keep policies current
5. **Plan for incidents** - Test incident response procedures
## Related Topics
- [RBAC Configuration](./rbac-configuration.md)
- [Audit Logging](./audit-logging.md)
- [Security Matrix](./security-matrix.md)
- [Privacy & GDPR](../12-auth/compliance-requirements.md)

17
src/SUMMARY.md
View file

@ -74,6 +74,7 @@
- [Paper - AI Writing](./04-gbui/apps/paper.md)
- [Research - AI Search](./04-gbui/apps/research.md)
- [Analytics - Dashboards](./04-gbui/apps/analytics.md)
- [Dashboards - Custom BI](./04-gbui/apps/dashboards.md)
- [Designer - Visual Builder](./04-gbui/apps/designer.md)
- [Sources - Prompts & Templates](./04-gbui/apps/sources.md)
- [Compliance - Security Scanner](./04-gbui/apps/compliance.md)
@ -321,6 +322,7 @@
# Part XI - Security
- [Chapter 12: Authentication & Permissions](./12-auth/README.md)
- [Initial Setup & Bootstrap](./12-auth/initial-setup.md)
- [User Authentication](./12-auth/user-auth.md)
- [Password Security](./12-auth/password-security.md)
- [API Endpoints](./12-auth/api-endpoints.md)
@ -328,11 +330,22 @@
- [Security Features](./12-auth/security-features.md)
- [Security Policy](./12-auth/security-policy.md)
- [Compliance Requirements](./12-auth/compliance-requirements.md)
- [RBAC Overview](./12-auth/rbac-overview.md)
- [Permissions Matrix](./12-auth/permissions-matrix.md)
- [Permissions Reference](./12-auth/permissions-reference.md)
- [User Context vs System Context](./12-auth/user-system-context.md)
- [System Limits & Rate Limiting](./12-auth/system-limits.md)
- [Security Checklist for SaaS](./12-auth/security-checklist.md)
- [Chapter 23: Advanced Security](./23-security/README.md)
- [RBAC & Security Design](./23-security/rbac-design.md)
- [RBAC Configuration Guide](./23-security/rbac-configuration.md)
- [Organization Multi-Tenancy](./23-security/organizations.md)
- [Knowledge Base Permissions](./23-security/kb-permissions.md)
- [Knowledge Base Security](./23-security/kb-security.md)
- [SOC 2 Compliance](./23-security/soc2-compliance.md)
- [Security Matrix Reference](./23-security/security-matrix.md)
# Part XII - Device & Offline Deployment
- [Chapter 13: Device Deployment](./13-devices/README.md)
@ -396,6 +409,10 @@
- [Sharding Architecture](./21-scale/sharding.md)
- [Database Optimization](./21-scale/database-optimization.md)
# Part XVIII - White Label
- [Chapter 19: White Label](./22-white-label/README.md)
# Appendices
- [Appendix A: Database Model](./15-appendix/README.md)

107
src/assets/roadmap-complete.md
View file

@ -15,10 +15,10 @@ This table merges the proposed timeline with all features documented in botbook/
| 2025 H1 | Rust Migration | 10 | ✅ Complete |
| 2025 H2 | Features & Tasks | 10 | ✅ Complete |
| 2026 Q1 | Autonomous GO | 12 | 📋 Planned |
| 2026 Q2 | Collaboration | 12 | 📋 Planned |
| 2026 Q3 | AI Features | 8 | 📋 Planned |
| 2026 Q4 | Enterprise | 8 | 📋 Planned |
| **TOTAL** | | **80** | |
| 2026 Q2 | Collaboration & AI | 14 | 📋 Planned |
| 2026 Q3 | Advanced Features | 6 | 📋 Planned |
| 2026 Q4 | Enterprise | 7 | 📋 Planned |
| **TOTAL** | | **79** | |
---
@ -67,9 +67,9 @@ This table merges the proposed timeline with all features documented in botbook/
| 5 | Drive Storage (S3) | Your list + botbook | 02-templates/gbdrive.md |
| 6 | Email System (IMAP/SMTP) | Your list + botbook | 11-features/email.md |
| 7 | REST API | Your list + botbook | 10-rest/ |
| 8 | **Telegram Channel** | botbook ROADMAP | 11-features/channels.md |
| 9 | **PDF Generation** | botbook ROADMAP | 06-gbdialog/keyword-generate-pdf.md |
| 10 | **WhatsApp Channel** | botbook ROADMAP | 11-features/channels.md |
| 8 | **Telegram Channel** | botbook | 11-features/channels.md |
| 9 | **PDF Generation** | botbook | 06-gbdialog/keyword-generate-pdf.md |
| 10 | **WhatsApp Channel** | botbook | 11-features/channels.md |
---
@ -104,27 +104,29 @@ This table merges the proposed timeline with all features documented in botbook/
| 8 | Speech to Text | Your list | 08-config/multimodal.md |
| 9 | Image Generation | Your list | 08-config/multimodal.md |
| 10 | Vision Analysis | Your list | 08-config/multimodal.md |
| 11 | **Transfer to Human** | botbook | 11-features/transfer-to-human.md |
| 12 | **LLM-Assisted Attendant** | botbook | 11-features/attendant-llm-assist.md |
| 11 | **MS Teams Channel** | Your list + botbook | 11-features/channels.md |
| 12 | **Multi-Agent System** | Your list + botbook | 11-features/multi-agent-orchestration.md |
---
## 2026 Q2: Collaboration Tools 📋
## 2026 Q2: Collaboration & AI Tools 📋
| # | Feature | Source | Documentation |
|---|---------|--------|---------------|
| 1 | Multi-Agent System | Your list + botbook | 11-features/multi-agent-orchestration.md |
| 2 | Bot Marketplace | Your list | Future |
| 3 | Compliance Suite | Your list + botbook | 04-gbui/apps/compliance.md |
| 4 | MS Teams Channel | Your list | 11-features/channels.md |
| 5 | Analytics Reports | Your list + botbook | 10-rest/analytics-api.md |
| 6 | **Google Meet** | botbook ROADMAP | 04-gbui/apps/meet.md |
| 7 | **Zoom Integration** | botbook ROADMAP | Future |
| 8 | **Slack Channel** | botbook ROADMAP | 11-features/channels.md |
| 9 | **Discord Channel** | botbook ROADMAP | 11-features/channels.md |
| 10 | **Google Sheets** | botbook ROADMAP | Future |
| 11 | **Excel Online** | botbook ROADMAP | Future |
| 1 | **Paper App (AI Writing)** | botbook | 04-gbui/apps/paper.md |
| 2 | **Research App (AI Search)** | botbook | 04-gbui/apps/research.md |
| 3 | **Transfer to Human** | botbook | 11-features/transfer-to-human.md |
| 4 | **LLM-Assisted Attendant** (AI Copilot for Agents) | botbook | 11-features/attendant-llm-assist.md |
| 5 | Bot Marketplace | Your list | Future |
| 6 | Compliance Suite | Your list + botbook | 04-gbui/apps/compliance.md |
| 7 | Analytics Reports | Your list + botbook | 10-rest/analytics-api.md |
| 8 | **Slack Channel** | botbook | 11-features/channels.md |
| 9 | **Discord Channel** | botbook | 11-features/channels.md |
| 10 | **Google Sheets** | botbook | Future |
| 11 | **Excel Online** | botbook | Future |
| 12 | **Whiteboard Collaboration** | botbook | 10-rest/whiteboard-api.md |
| 13 | **Player App (Media)** | botbook | 04-gbui/apps/player.md |
| 14 | **Sources App (Prompts)** | botbook | 04-gbui/apps/sources.md |
---
@ -134,12 +136,10 @@ This table merges the proposed timeline with all features documented in botbook/
|---|---------|--------|---------------|
| 1 | Workflow Designer | Your list + botbook | 04-gbui/apps/designer.md |
| 2 | CRM Integration | Your list | 02-templates/template-crm.md |
| 3 | **Voice Synthesis (TTS)** | botbook ROADMAP | 08-config/multimodal.md |
| 4 | **ERP Integration** | botbook ROADMAP | 02-templates/template-erp.md |
| 5 | **Paper App (AI Writing)** | botbook | 04-gbui/apps/paper.md |
| 6 | **Research App (AI Search)** | botbook | 04-gbui/apps/research.md |
| 7 | **Player App (Media)** | botbook | 04-gbui/apps/player.md |
| 8 | **Sources App (Prompts)** | botbook | 04-gbui/apps/sources.md |
| 3 | **Voice Synthesis (TTS)** | botbook | 08-config/multimodal.md |
| 4 | **ERP Integration** | botbook | 02-templates/template-erp.md |
| 5 | **Instagram Channel** | botbook | 11-features/channels.md |
| 6 | **SMS Channel** | botbook | 06-gbdialog/keyword-sms.md |
---
@ -149,12 +149,11 @@ This table merges the proposed timeline with all features documented in botbook/
|---|---------|--------|---------------|
| 1 | Mobile Apps (iOS/Android) | Your list + botbook | 13-devices/mobile.md |
| 2 | Enterprise SSO (SAML/OIDC) | Your list + botbook | 12-auth/ |
| 3 | White Label | Your list | Future |
| 4 | **Backup & Restore** | botbook | 10-rest/backup-api.md |
| 5 | **NVIDIA GPU Support** | botbook | 09-tools/nvidia-gpu-setup.md |
| 6 | **Docker Deployment** | botbook | 07-gbapp/docker-deployment.md |
| 7 | **LXC Containers** | botbook | 07-gbapp/containers.md |
| 8 | **Advanced Monitoring** | botbook | 10-rest/monitoring-api.md |
| 3 | **Backup & Restore** | botbook | 10-rest/backup-api.md |
| 4 | **NVIDIA GPU Support** | botbook | 09-tools/nvidia-gpu-setup.md |
| 5 | **Docker Deployment** | botbook | 07-gbapp/docker-deployment.md |
| 6 | **LXC Containers** | botbook | 07-gbapp/containers.md |
| 7 | **Advanced Monitoring** | botbook | 10-rest/monitoring-api.md |
---
@ -162,19 +161,19 @@ This table merges the proposed timeline with all features documented in botbook/
| App | Category | Timeline | Documentation |
|-----|----------|----------|---------------|
| Chat | Core | 2025 H1 | 04-gbui/apps/chat.md |
| Drive | Storage | 2025 H1 | 04-gbui/apps/drive.md |
| Tasks | Productivity | 2025 H2 | 04-gbui/apps/tasks.md |
| Mail | Communication | 2025 H1 | 04-gbui/apps/mail.md |
| Calendar | Scheduling | 2026 Q1 | 04-gbui/apps/calendar.md |
| Meet | Video | 2026 Q2 | 04-gbui/apps/meet.md |
| Paper | AI Writing | 2026 Q3 | 04-gbui/apps/paper.md |
| Research | AI Search | 2026 Q3 | 04-gbui/apps/research.md |
| Analytics | Reports | 2025 H2 | 04-gbui/apps/analytics.md |
| Designer | Visual | 2026 Q3 | 04-gbui/apps/designer.md |
| Sources | Prompts | 2026 Q3 | 04-gbui/apps/sources.md |
| Compliance | Security | 2026 Q2 | 04-gbui/apps/compliance.md |
| Player | Media | 2026 Q3 | 04-gbui/apps/player.md |
| Chat | Core | 2025 H1 ✅ | 04-gbui/apps/chat.md |
| Drive | Storage | 2025 H1 ✅ | 04-gbui/apps/drive.md |
| Tasks | Productivity | 2025 H2 ✅ | 04-gbui/apps/tasks.md |
| Mail | Communication | 2025 H1 ✅ | 04-gbui/apps/mail.md |
| Calendar | Scheduling | 2026 Q1 📋 | 04-gbui/apps/calendar.md |
| Meet | Video | 2026 Q2 📋 | 04-gbui/apps/meet.md |
| Paper | AI Writing | 2026 Q2 📋 | 04-gbui/apps/paper.md |
| Research | AI Search | 2026 Q2 📋 | 04-gbui/apps/research.md |
| Analytics | Reports | 2025 H2 ✅ | 04-gbui/apps/analytics.md |
| Designer | Visual | 2026 Q3 📋 | 04-gbui/apps/designer.md |
| Sources | Prompts | 2026 Q2 📋 | 04-gbui/apps/sources.md |
| Compliance | Security | 2026 Q2 📋 | 04-gbui/apps/compliance.md |
| Player | Media | 2026 Q2 📋 | 04-gbui/apps/player.md |
---
@ -185,11 +184,19 @@ This table merges the proposed timeline with all features documented in botbook/
| Web Chat | 2025 H1 ✅ | 04-gbui/apps/chat.md |
| WhatsApp | 2025 H1 ✅ | 11-features/channels.md |
| Telegram | 2025 H1 ✅ | 11-features/channels.md |
| MS Teams | 2026 Q2 📋 | 11-features/channels.md |
| MS Teams | 2026 Q1 📋 | 11-features/channels.md |
| Slack | 2026 Q2 📋 | 11-features/channels.md |
| Discord | 2026 Q2 📋 | 11-features/channels.md |
| Instagram | Future | 11-features/channels.md |
| SMS | Future | 06-gbdialog/keyword-sms.md |
| Instagram | 2026 Q3 📋 | 11-features/channels.md |
| SMS | 2026 Q3 📋 | 06-gbdialog/keyword-sms.md |
---
## Completed Features (Outside Roadmap)
| Feature | Status | Notes |
|---------|--------|-------|
| White Label | ✅ Complete | Branding customization available |
---
@ -213,4 +220,4 @@ This table merges the proposed timeline with all features documented in botbook/
- ✅ Complete
- 📋 Planned
- ⭐ Flagship Feature
- **Bold** = Added from botbook (missing from original timeline)
- **Bold** = Added from botbook (missing from original timeline)