rushchatbot 1.6.7 → 1.6.9

package/README.md

@@ -0,0 +1,717 @@
+# RushChatbot
+
+**Version:** 1.6.9
+
+Embeddable hybrid chatbot plugin that combines a click-based FAQ tree with a free-text query engine backed by n8n. Ships as an npm package with a Node.js/Express server and widgets for React, Vue 3, and Vanilla JS.
+
+**Features:**
+- Click-based FAQ question tree with subquestions
+- Fuzzy + keyword matching against your config
+- n8n webhook fallback for unmatched queries
+- Markdown rendering (bold, lists, headings)
+- Multi-bubble paragraph responses
+- Draggable floating chat button
+- Tagalog (TL) language support
+- Input validation and profanity guardrails
+- Session-based analytics
+
+---
+
+## Table of Contents
+
+1. [Requirements](#1-requirements)
+2. [Installation](#2-installation)
+3. [Scaffold Config Files](#3-scaffold-config-files)
+4. [Configure the Chatbot](#4-configure-the-chatbot)
+5. [Build the FAQ Tree](#5-build-the-faq-tree)
+6. [Start the Server](#6-start-the-server)
+7. [Embed the Widget](#7-embed-the-widget)
+8. [Floating Button Behavior](#8-floating-button-behavior)
+9. [n8n Webhook Setup](#9-n8n-webhook-setup)
+10. [n8n Response Formats](#10-n8n-response-formats)
+11. [Environment Variables](#11-environment-variables)
+12. [API Reference](#12-api-reference)
+13. [Analytics](#13-analytics)
+14. [Troubleshooting](#14-troubleshooting)
+
+---
+
+## 1. Requirements
+
+| Requirement | Version |
+|---|---|
+| Node.js | >= 18.0.0 |
+| npm | >= 9.0.0 |
+| React (for React widget) | >= 18.0.0 |
+| Vue (for Vue 3 widget) | >= 3.0.0 |
+| Vue (for Vue 2 widget) | >= 2.5.17 |
+| n8n instance | Any hosted or self-hosted |
+
+---
+
+## 2. Installation
+
+```bash
+npm install rushchatbot
+```
+
+---
+
+## 3. Scaffold Config Files
+
+Run the init command to generate the required config and questions files in a directory of your choice:
+
+```bash
+npx rushchatbot init ./chatbot
+```
+
+This creates three files:
+
+```
+chatbot/
+├── chatbot.config.json     ← branding, n8n, chat settings
+├── questions.json          ← English FAQ tree
+└── questions.tl.json       ← Tagalog FAQ tree (optional)
+```
+
+---
+
+## 4. Configure the Chatbot
+
+Edit `chatbot.config.json` with your settings:
+
+```json
+{
+  "branding": {
+    "title": "My Support Bot",
+    "subtitle": "How can we help you today?",
+    "theme": {
+      "primaryColor": "#4F46E5",
+      "backgroundColor": "#FFFFFF",
+      "userBubbleColor": "#4F46E5",
+      "botBubbleColor": "#F3F4F6",
+      "textColor": "#111827",
+      "fontFamily": "Inter, sans-serif"
+    }
+  },
+  "n8n": {
+    "webhookUrl": "https://your-n8n.com/webhook/your-webhook-id",
+    "timeoutMs": 55000
+  },
+  "chat": {
+    "welcomeMessage": "Hi! Choose a question below or type your own.",
+    "fallbackMessage": "Let me look that up for you...",
+    "matchThreshold": 0.4,
+    "showPreQuestionsOnStart": true,
+    "language": "en"
+  }
+}
+```
+
+### Config field reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `branding.title` | string | — | Chat header title |
+| `branding.subtitle` | string | — | Chat header subtitle |
+| `branding.theme.primaryColor` | string | `#4F46E5` | Header, buttons, user bubble color |
+| `branding.theme.backgroundColor` | string | `#FFFFFF` | Chat window background |
+| `branding.theme.userBubbleColor` | string | `#4F46E5` | User message bubble color |
+| `branding.theme.botBubbleColor` | string | `#F3F4F6` | Bot message bubble color |
+| `branding.theme.textColor` | string | `#111827` | Main text color |
+| `branding.theme.fontFamily` | string | `Inter, sans-serif` | Font stack |
+| `n8n.webhookUrl` | string | — | Your n8n POST webhook URL |
+| `n8n.timeoutMs` | number | `55000` | n8n request timeout in milliseconds |
+| `chat.welcomeMessage` | string | — | First message shown when chat opens |
+| `chat.fallbackMessage` | string | — | Shown when an error occurs |
+| `chat.matchThreshold` | number | `0.4` | Fuzzy match sensitivity (0–1). Lower = stricter |
+| `chat.showPreQuestionsOnStart` | boolean | `true` | Show FAQ buttons when chat opens |
+| `chat.language` | `"en"` \| `"tl"` | `"en"` | Language for displaying FAQ questions |
+
+---
+
+## 6. Build the FAQ Tree
+
+Edit `questions.json` to define your FAQ categories and answers. The structure supports two levels: main questions and subquestions.
+
+```json
+[
+  {
+    "id": "q1",
+    "question": "About Our Company",
+    "answer": "We are a company that...",
+    "subquestions": [
+      {
+        "id": "q1a",
+        "question": "When was the company founded?",
+        "answer": "We were founded in 2010.",
+        "subquestions": []
+      },
+      {
+        "id": "q1b",
+        "question": "What is your mission?",
+        "answer": "Our mission is to...",
+        "subquestions": []
+      }
+    ]
+  },
+  {
+    "id": "q2",
+    "question": "Contact Information",
+    "answer": "You can reach us at support@example.com.",
+    "subquestions": []
+  }
+]
+```
+
+### Rules
+
+- Every question must have a unique `id`
+- `subquestions` must be an array (use `[]` if none)
+- `answer` is shown when the question is clicked directly or matched via text search
+- For Tagalog support, mirror the same structure in `questions.tl.json` with translated text — keep the same `id` values
+
+---
+
+## 6. Start the Server
+
+Create a server entry file (e.g. `server.js` or `server.ts`):
+
+```ts
+import { createServer } from 'rushchatbot/server'
+import path from 'path'
+
+createServer({
+  configPath: path.resolve('./chatbot/chatbot.config.json'),
+  questionsPath: path.resolve('./chatbot/questions.json'),
+  questionsTagalogPath: path.resolve('./chatbot/questions.tl.json'), // optional
+  port: 3001,
+  corsOrigin: 'https://your-frontend-domain.com', // or '*' for development
+}).listen()
+```
+
+### Server options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `configPath` | string | — | **Required.** Absolute path to `chatbot.config.json` |
+| `questionsPath` | string | — | **Required.** Absolute path to `questions.json` |
+| `questionsTagalogPath` | string | — | Optional. Absolute path to `questions.tl.json` |
+| `port` | number | `3001` | Port to listen on |
+| `corsOrigin` | string \| string[] | `*` | Allowed CORS origin(s) |
+
+Start the server:
+
+```bash
+node server.js
+```
+
+On successful startup you will see:
+
+```
+[RushChatbot] Server running on http://localhost:3001
+```
+
+---
+
+## 7. Embed the Widget
+
+RushChatbot ships three separate widget builds. Use the one that matches your frontend stack.
+
+---
+
+### React
+
+Install peer dependencies if not already present:
+
+```bash
+npm install react react-dom marked
+```
+
+Import and render the widget:
+
+```tsx
+import { ChatWidget } from 'rushchatbot/client'
+
+export default function App() {
+  return (
+    <div>
+      <ChatWidget apiBase="http://localhost:3001/api/chat" />
+    </div>
+  )
+}
+```
+
+The widget renders as a **floating draggable button** fixed to the bottom-right of the screen. Clicking it opens the chat box above the button.
+
+#### React widget props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiBase` | string | `http://localhost:3001/api/chat` | Base URL of the RushChatbot server |
+| `width` | number | `380` | Chat box width in pixels |
+| `height` | number | `580` | Chat box height in pixels |
+
+---
+
+### Vue 2
+
+Install peer dependency if not already present:
+
+```bash
+npm install vue@2
+```
+
+Register and use the component:
+
+```vue
+<script>
+import ChatWidget from 'rushchatbot/vue2'
+
+export default {
+  components: { ChatWidget }
+}
+</script>
+
+<template>
+  <ChatWidget api-base="http://localhost:3001/api/chat" />
+</template>
+```
+
+Or register it globally in `main.js`:
+
+```js
+import Vue from 'vue'
+import App from './App.vue'
+import ChatWidget from 'rushchatbot/vue2'
+
+Vue.component('RushChatbot', ChatWidget)
+new Vue({ render: h => h(App) }).$mount('#app')
+```
+
+Then use it anywhere:
+
+```vue
+<template>
+  <RushChatbot api-base="http://localhost:3001/api/chat" />
+</template>
+```
+
+#### Vue 2 widget props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `api-base` | string | `http://localhost:3001/api/chat` | Base URL of the RushChatbot server |
+| `width` | number | — | Chat box width in pixels (omit for fluid) |
+| `height` | number | — | Chat box height in pixels (omit for fluid) |
+| `primary-color` | string | from config | Override primary/accent color |
+| `bg-color` | string | from config | Override background color |
+| `border-radius` | number | `16` | Container corner radius in pixels |
+| `show-shadow` | boolean | `true` | Show/hide box shadow |
+| `placeholder` | string | `Type a message...` | Input placeholder text |
+| `send-label` | string | `Send` | Send button label |
+| `hide-input` | boolean | `false` | Hide the text input bar |
+| `hide-end-chat` | boolean | `false` | Hide the "I'm done" end chat button |
+
+---
+
+### Vue 3
+
+Install peer dependency if not already present:
+
+```bash
+npm install vue
+```
+
+Register and use the component:
+
+```vue
+<script setup>
+import ChatWidget from 'rushchatbot/vue'
+</script>
+
+<template>
+  <ChatWidget api-base="http://localhost:3001/api/chat" />
+</template>
+```
+
+Or register it globally in `main.ts`:
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import ChatWidget from 'rushchatbot/vue'
+
+const app = createApp(App)
+app.component('RushChatbot', ChatWidget)
+app.mount('#app')
+```
+
+Then use it anywhere:
+
+```vue
+<template>
+  <RushChatbot api-base="http://localhost:3001/api/chat" />
+</template>
+```
+
+#### Vue widget props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `api-base` | string | `http://localhost:3001/api/chat` | Base URL of the RushChatbot server |
+| `width` | number | — | Chat box width in pixels (omit for fluid) |
+| `height` | number | — | Chat box height in pixels (omit for fluid) |
+| `primary-color` | string | from config | Override primary/accent color |
+| `bg-color` | string | from config | Override background color |
+| `border-radius` | number | `16` | Container corner radius in pixels |
+| `show-shadow` | boolean | `true` | Show/hide box shadow |
+| `placeholder` | string | `Type a message...` | Input placeholder text |
+| `send-label` | string | `Send` | Send button label |
+| `hide-input` | boolean | `false` | Hide the text input bar |
+| `hide-end-chat` | boolean | `false` | Hide the "I'm done" end chat button |
+
+---
+
+### Vanilla JS (Web Component)
+
+No framework required. The Vanilla build registers a `<rush-chatbot>` custom element using the Web Components API with Shadow DOM.
+
+#### Via npm
+
+```ts
+import 'rushchatbot/vanilla'
+```
+
+Then add the element anywhere in your HTML:
+
+```html
+<rush-chatbot api-base="http://localhost:3001/api/chat"></rush-chatbot>
+```
+
+#### Via CDN / script tag
+
+```html
+<script type="module" src="/path/to/rushchatbot/dist/vanilla.es.js"></script>
+<!-- or IIFE build for non-module environments -->
+<script src="/path/to/rushchatbot/dist/vanilla.iife.js"></script>
+
+<rush-chatbot api-base="http://localhost:3001/api/chat"></rush-chatbot>
+```
+
+#### Web Component attributes
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `api-base` | string | `http://localhost:3001/api/chat` | Base URL of the RushChatbot server |
+| `width` | number | — | Chat box width in pixels (omit for fluid) |
+| `height` | number | — | Chat box height in pixels (omit for fluid) |
+| `primary-color` | string | from config | Override primary/accent color |
+| `bg-color` | string | from config | Override background color |
+| `border-radius` | number | `16` | Container corner radius in pixels |
+| `show-shadow` | boolean | `true` | Show/hide box shadow |
+| `placeholder` | string | `Type a message...` | Input placeholder text |
+| `send-label` | string | `Send` | Send button label |
+| `hide-input` | boolean | `false` | Hide the text input bar |
+| `hide-end-chat` | boolean | `false` | Hide the "I'm done" end chat button |
+| `auto-open` | boolean | `false` | Auto-open chat on load |
+| `position` | `bottom-right\|bottom-left` | `bottom-right` | Floating button position |
+
+Attributes can be updated at runtime and the widget will reflect the changes:
+
+```js
+document.querySelector('rush-chatbot').setAttribute('api-base', 'https://my-server.com/api/chat')
+```
+
+---
+
+## 8. Floating Button Behavior
+
+The chat button is draggable across the entire screen:
+
+- **Drag** — click and hold, then move to reposition the button anywhere on screen
+- **Click** (no drag) — toggles the chat box open or closed
+- **Chat box position** — always appears directly above the button, clamped to the viewport so it never goes off-screen
+- **Close** — click the ✕ button inside the chat header, or click the floating button again
+- Works on both desktop (mouse) and mobile (touch)
+
+---
+
+## 9. n8n Webhook Setup
+
+When a user types a query that doesn't match any FAQ answer, RushChatbot forwards it to your n8n webhook.
+
+### What RushChatbot sends to n8n
+
+```json
+{
+  "query": "the user's message",
+  "sessionId": "sess_abc123"
+}
+```
+
+Headers sent:
+
+```
+Content-Type: application/json
+x-session-id: sess_abc123
+```
+
+### Setting up the webhook in n8n
+
+1. Create a new workflow in n8n
+2. Add a **Webhook** trigger node — set method to `POST`
+3. Copy the webhook URL into `chatbot.config.json` under `n8n.webhookUrl`
+4. Add your AI/logic nodes after the webhook trigger
+5. End with a **Respond to Webhook** node returning one of the supported response formats (see section 11)
+6. Activate the workflow
+
+### Session continuity
+
+The `sessionId` is generated per browser tab (`sess_` + timestamp + random suffix). Pass it through your n8n workflow to maintain conversation context with your AI agent.
+
+---
+
+## 10. n8n Response Formats
+
+RushChatbot automatically parses all of the following response shapes from n8n:
+
+### Single answer
+
+```json
+[{ "output": "Your answer text here" }]
+```
+
+```json
+[{ "answer": "Your answer text here" }]
+```
+
+```json
+[{ "text": "Your answer text here" }]
+```
+
+### Multiple bubbles (paragraphs)
+
+Return a `paragraphs` array to render each item as a **separate chat bubble** with a short delay between them:
+
+```json
+[{
+  "paragraphs": [
+    "First part of the response.",
+    "Second part with **bold** and lists.",
+    "Third bubble with a follow-up question."
+  ]
+}]
+```
+
+### Markdown support
+
+All responses are rendered as Markdown. Supported formatting:
+
+| Syntax | Renders as |
+|---|---|
+| `**bold**` | **bold** |
+| `# Heading` | Large heading |
+| `- item` | Bullet list |
+| `1. item` | Numbered list |
+| `[link](url)` | Hyperlink |
+| `\n` (newline) | Line break |
+
+---
+
+## 11. Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `PORT` | No | Override the server port (default: `3001`) |
+
+### Setting the port
+
+```bash
+PORT=4000 node server.js
+```
+
+---
+
+## 12. API Reference
+
+All endpoints are mounted under `/api/chat`.
+
+### `GET /api/chat/config`
+
+Returns branding and chat settings. Safe to call from the frontend — never exposes n8n credentials or license key.
+
+**Response:**
+```json
+{
+  "branding": { "title": "...", "subtitle": "...", "theme": { } },
+  "chat": { "welcomeMessage": "...", "language": "en" }
+}
+```
+
+---
+
+### `GET /api/chat/questions`
+
+Returns the FAQ question tree in the configured language.
+
+**Response:**
+```json
+[
+  {
+    "id": "q1",
+    "question": "About Our Company",
+    "answer": "...",
+    "subquestions": []
+  }
+]
+```
+
+---
+
+### `GET /api/chat/query?query=your+question&sessionId=sess_abc`
+
+Forwards the query **directly to n8n**, bypassing FAQ matching. Useful for testing your n8n workflow from the browser.
+
+**Query params:**
+
+| Param | Required | Description |
+|---|---|---|
+| `query` | Yes | The user's question |
+| `sessionId` | No | Session identifier |
+
+**Response:**
+```json
+{ "answer": "...", "source": "n8n" }
+```
+or
+```json
+{ "paragraphs": ["...", "..."], "source": "n8n" }
+```
+
+---
+
+### `POST /api/chat/query`
+
+Main query endpoint. Runs the full pipeline: input validation → guardrails → FAQ matching → n8n fallback.
+
+**Request body:**
+```json
+{
+  "query": "How do I apply for membership?",
+  "sessionId": "sess_abc123"
+}
+```
+
+**Response (FAQ match):**
+```json
+{
+  "answer": "You can apply by...",
+  "source": "config",
+  "matchedQuestion": "How do I apply for membership?",
+  "matchedKeywords": ["apply", "membership"],
+  "score": 87
+}
+```
+
+**Response (n8n fallback):**
+```json
+{ "answer": "...", "source": "n8n" }
+```
+
+**Response (validation/guardrail blocked):**
+```json
+{ "answer": "Please rephrase your question...", "source": "validation" }
+```
+
+---
+
+### `POST /api/chat/click`
+
+Tracks when a user clicks a pre-built FAQ question.
+
+**Request body:**
+```json
+{
+  "questionId": "q1a",
+  "sessionId": "sess_abc123"
+}
+```
+
+**Response:**
+```json
+{ "ok": true }
+```
+
+---
+
+### `GET /api/chat/analytics`
+
+Returns the full analytics log.
+
+**Response:**
+```json
+[
+  {
+    "sessionId": "sess_abc123",
+    "questionId": "q1a",
+    "timestamp": "2025-01-01T10:00:00.000Z",
+    "type": "click"
+  }
+]
+```
+
+**Analytics types:**
+
+| Type | Description |
+|---|---|
+| `click` | User clicked a pre-built FAQ question |
+| `match` | User query matched a FAQ answer |
+| `n8n` | Query was forwarded to n8n |
+| `error` | Validation, guardrail, or server error |
+
+---
+
+## 13. Analytics
+
+Analytics are written to `analytics.json` in the same directory as your `chatbot.config.json`. Each entry records:
+
+- `sessionId` — browser session (resets on new tab)
+- `questionId` — the matched question ID, or `n8n` / `error` / `guardrail`
+- `timestamp` — ISO 8601 UTC
+- `type` — `click`, `match`, `n8n`, or `error`
+
+You can query the log at any time via `GET /api/chat/analytics` or read the file directly.
+
+---
+
+## 14. Troubleshooting
+
+### `[RushChatbot] configPath not found`
+
+- Use `path.resolve()` to ensure the path is absolute
+- Verify the file exists at the specified location
+
+### Chat widget shows nothing / blank
+
+- Check the browser console for CORS errors
+- Ensure `corsOrigin` in `createServer()` includes your frontend's origin
+- Confirm the server is running and reachable at the `apiBase` URL
+
+### n8n not responding / timeout
+
+- Increase `n8n.timeoutMs` in `chatbot.config.json` (default is 55000ms)
+- Test the webhook directly: `GET http://localhost:3001/api/chat/query?query=hello`
+- Check your n8n workflow is activated (not just saved)
+
+### Port already in use
+
+```bash
+kill $(lsof -ti :3001)
+```
+
+### Queries always fall through to n8n (no FAQ matches)
+
+- Lower `chat.matchThreshold` in config (e.g. `0.3`)
+- Ensure your `questions.json` answers contain keywords that appear in user queries
+- Check that question `id` values are unique across the entire tree

package/package/INTEGRATION.md

@@ -1,6 +1,6 @@
 # RushChatbot
 
-**Version:** 1.6.7
+**Version:** 1.6.9
 
 Embeddable hybrid chatbot plugin that combines a click-based FAQ tree with a free-text query engine backed by n8n. Ships as an npm package with a Node.js/Express server and widgets for React, Vue 3, and Vanilla JS.
 

package/package/README.md

@@ -1,6 +1,6 @@
 # RushChatbot
 
-**Version:** 1.6.7
+**Version:** 1.6.9
 
 Embeddable hybrid chatbot plugin that combines a click-based FAQ tree with a free-text query engine backed by n8n. Ships as an npm package with a Node.js/Express server and widgets for React, Vue 3, and Vanilla JS.
 

package/package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rushchatbot",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "description": "Embeddable hybrid chatbot with n8n fallback, license key protection, and configurable FAQ tree",
   "keywords": [
     "chatbot",

package/package/src/cli/index.ts

@@ -2,6 +2,19 @@
 import fs from 'fs'
 import path from 'path'
 
+function sanitizeLog(value: string): string {
+  return value.replace(/[\r\n\t]/g, ' ').slice(0, 500)
+}
+
+function safeResolvePath(inputArg: string): string {
+  const resolved = path.resolve(inputArg)
+  // Reject paths containing traversal sequences
+  if (inputArg.includes('..') || inputArg.includes('\0')) {
+    throw new Error(`Path traversal detected: ${sanitizeLog(inputArg)}`)
+  }
+  return resolved
+}
+
 const args = process.argv.slice(2)
 const command = args[0]
 
@@ -48,18 +61,24 @@ const DEFAULT_QUESTIONS = [
 
 function writeIfNotExists(filePath: string, content: unknown) {
   if (fs.existsSync(filePath)) {
-    console.log(`  [skip] ${filePath} already exists`)
+    console.log(`  [skip] ${sanitizeLog(filePath)} already exists`)
     return
   }
   fs.writeFileSync(filePath, JSON.stringify(content, null, 2))
-  console.log(`  [created] ${filePath}`)
+  console.log(`  [created] ${sanitizeLog(filePath)}`)
 }
 
 if (command === 'init') {
-  const targetDir = args[1] ? path.resolve(args[1]) : process.cwd()
+  let targetDir: string
+  try {
+    targetDir = args[1] ? safeResolvePath(args[1]) : process.cwd()
+  } catch (e) {
+    console.error(sanitizeLog((e as Error).message))
+    process.exit(1)
+  }
   fs.mkdirSync(targetDir, { recursive: true })
 
-  console.log(`\nInitializing RushChatbot config in: ${targetDir}\n`)
+  console.log(`\nInitializing RushChatbot config in: ${sanitizeLog(targetDir)}\n`)
   writeIfNotExists(path.join(targetDir, 'chatbot.config.json'), DEFAULT_CONFIG)
   writeIfNotExists(path.join(targetDir, 'questions.json'), DEFAULT_QUESTIONS)
   writeIfNotExists(path.join(targetDir, 'questions.tl.json'), DEFAULT_QUESTIONS)

package/package/src/server/index.ts

@@ -3,10 +3,50 @@ import cors from 'cors'
 import axios from 'axios'
 import fs from 'fs'
 import path from 'path'
+import crypto from 'crypto'
 import { findMatch, MatchResult, Question } from './matcher'
 import { checkGuardrails, validateInput } from './guardrails'
 import type { ChatbotConfig } from '../shared/types'
 
+function sanitizeLog(value: string): string {
+  return value.replace(/[\r\n\t]/g, ' ').slice(0, 500)
+}
+
+function validatePath(inputPath: string, allowedBase: string): string {
+  const resolved = path.resolve(inputPath)
+  if (!resolved.startsWith(path.resolve(allowedBase) + path.sep) && resolved !== path.resolve(allowedBase)) {
+    throw new Error(`[RushChatbot] Path outside allowed directory: ${resolved}`)
+  }
+  return resolved
+}
+
+const csrfTokens = new Map<string, number>()
+
+function generateCsrfToken(): string {
+  const token = crypto.randomBytes(32).toString('hex')
+  csrfTokens.set(token, Date.now())
+  return token
+}
+
+function validateCsrfToken(token: string | undefined): boolean {
+  if (!token || !csrfTokens.has(token)) return false
+  const age = Date.now() - (csrfTokens.get(token) ?? 0)
+  if (age > 3600000) { csrfTokens.delete(token); return false }
+  return true
+}
+
+function csrfMiddleware(req: express.Request, res: express.Response, next: express.NextFunction) {
+  const origin = req.headers.origin
+  const referer = req.headers.referer
+  // Allow requests with no origin (server-to-server, curl, mobile apps)
+  if (!origin && !referer) return next()
+  const token = req.headers['x-csrf-token'] as string | undefined
+  if (!validateCsrfToken(token)) {
+    return res.status(403).json({ error: 'Invalid or missing CSRF token' })
+  }
+  next()
+}
+
 export interface RushChatbotServerOptions {
   /** Absolute path to your chatbot.config.json */
   configPath: string
@@ -63,30 +103,31 @@ export function createServer(options: RushChatbotServerOptions) {
   if (!fs.existsSync(configPath)) throw new Error(`[RushChatbot] configPath not found: ${configPath}`)
   if (!fs.existsSync(questionsPath)) throw new Error(`[RushChatbot] questionsPath not found: ${questionsPath}`)
 
-  const analyticsPath = path.join(path.dirname(configPath), 'analytics.json')
+  const allowedBase = path.dirname(path.resolve(configPath))
+  const analyticsPath = path.join(allowedBase, 'analytics.json')
 
   function getConfig(): ChatbotConfig {
-    return JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+    return JSON.parse(fs.readFileSync(validatePath(configPath, allowedBase), 'utf-8'))
   }
 
   function getQuestions(lang: 'en' | 'tl'): Question[] {
     if (lang === 'tl') {
       if (!questionsTagalogPath || !fs.existsSync(questionsTagalogPath)) return []
-      return JSON.parse(fs.readFileSync(questionsTagalogPath, 'utf-8'))
+      return JSON.parse(fs.readFileSync(validatePath(questionsTagalogPath, allowedBase), 'utf-8'))
     }
-    return JSON.parse(fs.readFileSync(questionsPath, 'utf-8'))
+    return JSON.parse(fs.readFileSync(validatePath(questionsPath, allowedBase), 'utf-8'))
   }
 
   function getAnalytics(): AnalyticsEntry[] {
     if (!fs.existsSync(analyticsPath)) return []
-    return JSON.parse(fs.readFileSync(analyticsPath, 'utf-8'))
+    return JSON.parse(fs.readFileSync(validatePath(analyticsPath, allowedBase), 'utf-8'))
   }
 
   function saveAnalytics(entry: AnalyticsEntry) {
     try {
       const analytics = getAnalytics()
       analytics.push(entry)
-      fs.writeFileSync(analyticsPath, JSON.stringify(analytics, null, 2))
+      fs.writeFileSync(validatePath(analyticsPath, allowedBase), JSON.stringify(analytics, null, 2))
     } catch (e) {
       console.error('[RushChatbot analytics error]', e)
     }
@@ -99,10 +140,21 @@ export function createServer(options: RushChatbotServerOptions) {
   const app = express()
   app.use(cors({ origin: corsOrigin }))
   app.use(express.json())
+  // Apply CSRF protection globally to all state-changing methods
+  app.use((req, res, next) => {
+    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+      return csrfMiddleware(req, res, next)
+    }
+    next()
+  })
 
   const router = express.Router()
 
-  router.post('/click', (req, res) => {
+  router.get('/csrf-token', (_req, res) => {
+    res.json({ csrfToken: generateCsrfToken() })
+  })
+
+  router.post('/click', csrfMiddleware, (req, res) => {
     const { questionId } = req.body
     const sid = getSid(req)
     if (!questionId || typeof questionId !== 'string')
@@ -126,12 +178,12 @@ export function createServer(options: RushChatbotServerOptions) {
       return res.json({ ...parseN8nResponse(data), source: 'n8n' })
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : String(err)
-      console.error('[RushChatbot query GET error]', message)
-      return res.status(500).json({ error: message })
+      console.error('[RushChatbot query GET error]', sanitizeLog(message))
+      return res.status(500).json({ error: 'Internal server error' })
     }
   })
 
-  router.post('/query', async (req, res) => {
+  router.post('/query', csrfMiddleware, async (req, res) => {
     const sid = getSid(req)
     const cfg = getConfig()
     try {
@@ -181,7 +233,7 @@ export function createServer(options: RushChatbotServerOptions) {
 
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : String(err)
-      console.error('[RushChatbot query error]', message)
+      console.error('[RushChatbot query error]', sanitizeLog(message))
       saveAnalytics({ sessionId: sid, questionId: 'error', timestamp: new Date().toISOString(), type: 'error' })
       return res.status(500).json({ answer: cfg.chat.fallbackMessage, source: 'error' })
     }

package/package/src/vanilla/index.ts

@@ -2,6 +2,15 @@ import { RushChatbot, parseMarkdown } from '../core/RushChatbot'
 import type { RushChatbotState, WidgetSettings } from '../core/RushChatbot'
 import type { Question, Message } from '../shared/types'
 
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
 const STYLES = `
   @keyframes rushchatbot-bounce {
     0%, 80%, 100% { transform: translateY(0); opacity: 0.4; }
@@ -137,42 +146,100 @@ class RushChatbotElement extends HTMLElement {
     const msgsEl = this.shadow.querySelector('.messages') as HTMLElement | null
     const wasAtBottom = msgsEl ? msgsEl.scrollHeight - msgsEl.scrollTop - msgsEl.clientHeight < 60 : true
 
-    this.shadow.innerHTML = `
+    // Build static shell with no user data in innerHTML
+    const shellHtml = `
       <style>${STYLES}</style>
-      <div class="container" style="background:${theme.backgroundColor};color:${theme.textColor};width:${this.w};height:${this.h};font-family:${theme.fontFamily};border-radius:${borderRadius}px;box-shadow:${shadow}">
-        <div class="header" style="background:${theme.primaryColor}">
-          <div class="header-title">${state.config!.branding.title}</div>
-          <div class="header-subtitle">${state.config!.branding.subtitle}</div>
+      <div class="container" id="container">
+        <div class="header" id="header">
+          <div class="header-title" id="header-title"></div>
+          <div class="header-subtitle" id="header-subtitle"></div>
         </div>
         <div class="messages-wrap">
-          ${this.showScrollBtn ? `
-            <button class="scroll-btn" id="scrollBtn" style="background:${theme.primaryColor}" aria-label="Scroll to latest">
-              <svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M8 3v10M3 9l5 5 5-5" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
-            </button>` : ''}
           <div class="messages" id="msgs">
-            ${state.messages.map((msg, idx) => this.renderMsg(msg, idx)).join('')}
-            ${state.loading ? `<div class="thinking" style="background:${theme.botBubbleColor}">
-              ${[0,1,2].map(i => `<span class="dot" style="background:${theme.primaryColor};animation:rushchatbot-bounce 1.2s ease-in-out ${i*0.2}s infinite"></span>`).join('')}
-            </div>` : ''}
-            ${state.showMain && state.questions.length > 0 ? `
-              <div class="main-list">
-                ${state.questions.map(q => `
-                  <button class="main-btn" data-action="main" data-id="${q.id}"
-                    style="border:1px solid ${theme.primaryColor};color:${theme.primaryColor}">
-                    ${q.question}
-                  </button>`).join('')}
-                ${settings.hideEndChat ? '' : `<button class="end-btn" data-action="endchat">👋 I'm done, thanks!</button>`}
-              </div>` : ''}
+            <div id="msgs-content"></div>
             <div id="bottom"></div>
           </div>
         </div>
         ${settings.hideInput ? '' : `
         <form class="input-row" id="form">
-          <input id="input" placeholder="${placeholder}" value="${state.input}" ${state.loading ? 'disabled' : ''} />
-          <button type="submit" style="background:${theme.primaryColor}" ${state.loading ? 'disabled' : ''}>${sendLabel}</button>
+          <input id="input" />
+          <button type="submit" id="send-btn"></button>
         </form>`}
       </div>
     `
+    this.shadow.innerHTML = shellHtml
+
+    // Populate dynamic values via DOM (safe from XSS)
+    const container = this.shadow.getElementById('container') as HTMLElement
+    container.style.cssText = `background:${escapeHtml(theme.backgroundColor)};color:${escapeHtml(theme.textColor)};width:${this.w};height:${this.h};font-family:${escapeHtml(theme.fontFamily)};border-radius:${borderRadius}px;box-shadow:${shadow}`
+
+    const header = this.shadow.getElementById('header') as HTMLElement
+    header.style.background = escapeHtml(theme.primaryColor)
+    ;(this.shadow.getElementById('header-title') as HTMLElement).textContent = state.config!.branding.title
+    ;(this.shadow.getElementById('header-subtitle') as HTMLElement).textContent = state.config!.branding.subtitle
+
+    const msgsContent = this.shadow.getElementById('msgs-content') as HTMLElement
+    msgsContent.textContent = ''
+
+    state.messages.forEach((msg, idx) => {
+      msgsContent.appendChild(this.renderMsg(msg, idx))
+    })
+
+    if (state.loading) {
+      const thinking = document.createElement('div')
+      thinking.className = 'thinking'
+      thinking.style.background = escapeHtml(theme.botBubbleColor)
+      ;[0,1,2].forEach(i => {
+        const dot = document.createElement('span')
+        dot.className = 'dot'
+        dot.style.cssText = `background:${escapeHtml(theme.primaryColor)};animation:rushchatbot-bounce 1.2s ease-in-out ${i*0.2}s infinite`
+        thinking.appendChild(dot)
+      })
+      msgsContent.appendChild(thinking)
+    }
+
+    if (state.showMain && state.questions.length > 0) {
+      const mainList = document.createElement('div')
+      mainList.className = 'main-list'
+      state.questions.forEach(q => {
+        const btn = document.createElement('button')
+        btn.className = 'main-btn'
+        btn.dataset.action = 'main'
+        btn.dataset.id = q.id
+        btn.style.cssText = `border:1px solid ${escapeHtml(theme.primaryColor)};color:${escapeHtml(theme.primaryColor)}`
+        btn.textContent = q.question
+        mainList.appendChild(btn)
+      })
+      if (!settings.hideEndChat) {
+        const endBtn = document.createElement('button')
+        endBtn.className = 'end-btn'
+        endBtn.dataset.action = 'endchat'
+        endBtn.textContent = "\uD83D\uDC4B I'm done, thanks!"
+        mainList.appendChild(endBtn)
+      }
+      msgsContent.appendChild(mainList)
+    }
+
+    if (this.showScrollBtn) {
+      const scrollBtn = document.createElement('button')
+      scrollBtn.className = 'scroll-btn'
+      scrollBtn.id = 'scrollBtn'
+      scrollBtn.style.background = escapeHtml(theme.primaryColor)
+      scrollBtn.setAttribute('aria-label', 'Scroll to latest')
+      scrollBtn.innerHTML = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M8 3v10M3 9l5 5 5-5" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`
+      this.shadow.querySelector('.messages-wrap')!.prepend(scrollBtn)
+    }
+
+    if (!settings.hideInput) {
+      const inputEl = this.shadow.getElementById('input') as HTMLInputElement
+      inputEl.placeholder = placeholder
+      inputEl.value = state.input
+      if (state.loading) inputEl.disabled = true
+      const sendBtn = this.shadow.getElementById('send-btn') as HTMLButtonElement
+      sendBtn.textContent = sendLabel
+      sendBtn.style.background = escapeHtml(theme.primaryColor)
+      if (state.loading) sendBtn.disabled = true
+    }
 
     const newMsgsEl = this.shadow.getElementById('msgs') as HTMLElement
     if (wasAtBottom) {
@@ -257,41 +324,66 @@ class RushChatbotElement extends HTMLElement {
     })
   }
 
-  private renderMsg(msg: Message, idx: number): string {
+  private renderMsg(msg: Message, idx: number): HTMLElement {
     const { theme } = this
     const isUser = msg.role === 'user'
     const bgColor = isUser ? theme.userBubbleColor : theme.botBubbleColor
     const color = isUser ? '#fff' : theme.textColor
-    const firstStyle = idx === 0 ? 'margin-top:48px;' : ''
+
+    const row = document.createElement('div')
+    row.className = `msg-row ${isUser ? 'user' : 'bot'}`
+    if (idx === 0) row.style.marginTop = '48px'
+
+    const bubble = document.createElement('div')
+    bubble.className = 'bubble'
+    bubble.style.cssText = `background:${escapeHtml(bgColor)};color:${escapeHtml(color)}`
 
     if (msg.subquestions && msg.subquestions.length > 0) {
       const siblingIds = msg.subquestions.map((s: Question) => s.id).join(',')
-      return `
-        <div class="msg-row bot" style="${firstStyle}">
-          <div class="bubble" style="background:${bgColor};color:${color}">
-            <div class="rushchatbot-md" style="margin-bottom:8px">${parseMarkdown(msg.text)}</div>
-            <div class="sub-list">
-              ${msg.subquestions.map((sub: Question) => `
-                <button class="btn" data-action="sub" data-id="${sub.id}" data-siblings="${siblingIds}"
-                  style="border:1px solid ${theme.primaryColor};color:${theme.primaryColor}">
-                  ${sub.question}
-                </button>`).join('')}
-              <button class="btn" data-action="back" style="border:1px solid #6B7280;color:#6B7280">← Back to main menu</button>
-            </div>
-          </div>
-        </div>`
+      const mdDiv = document.createElement('div')
+      mdDiv.className = 'rushchatbot-md'
+      mdDiv.style.marginBottom = '8px'
+      mdDiv.innerHTML = parseMarkdown(msg.text)
+      bubble.appendChild(mdDiv)
+
+      const subList = document.createElement('div')
+      subList.className = 'sub-list'
+      msg.subquestions.forEach((sub: Question) => {
+        const btn = document.createElement('button')
+        btn.className = 'btn'
+        btn.dataset.action = 'sub'
+        btn.dataset.id = sub.id
+        btn.dataset.siblings = siblingIds
+        btn.style.cssText = `border:1px solid ${escapeHtml(theme.primaryColor)};color:${escapeHtml(theme.primaryColor)}`
+        btn.textContent = sub.question
+        subList.appendChild(btn)
+      })
+      const backBtn = document.createElement('button')
+      backBtn.className = 'btn'
+      backBtn.dataset.action = 'back'
+      backBtn.style.cssText = 'border:1px solid #6B7280;color:#6B7280'
+      backBtn.textContent = '\u2190 Back to main menu'
+      subList.appendChild(backBtn)
+      bubble.appendChild(subList)
+    } else if (isUser) {
+      bubble.textContent = msg.text
+    } else {
+      const mdDiv = document.createElement('div')
+      mdDiv.className = 'rushchatbot-md'
+      mdDiv.innerHTML = parseMarkdown(msg.text)
+      bubble.appendChild(mdDiv)
+      if (msg.isEndChat) {
+        const newChatBtn = document.createElement('button')
+        newChatBtn.className = 'new-chat-btn'
+        newChatBtn.dataset.action = 'newchat'
+        newChatBtn.style.background = escapeHtml(theme.primaryColor)
+        newChatBtn.textContent = '\uD83D\uDD04 Start a new chat'
+        bubble.appendChild(newChatBtn)
+      }
     }
 
-    return `
-      <div class="msg-row ${isUser ? 'user' : 'bot'}" style="${firstStyle}">
-        <div class="bubble" style="background:${bgColor};color:${color}">
-          ${isUser
-            ? msg.text
-            : `<div class="rushchatbot-md">${parseMarkdown(msg.text)}</div>
-               ${msg.isEndChat ? `<button class="new-chat-btn" data-action="newchat" style="background:${theme.primaryColor}">🔄 Start a new chat</button>` : ''}`
-          }
-        </div>
-      </div>`
+    row.appendChild(bubble)
+    return row
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rushchatbot",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "scripts": {
     "dev": "concurrently \"npm run dev:server\" \"npm run dev:client\"",
     "dev:client": "vite",

package/server/data/analytics.json

@@ -791,5 +791,11 @@
     "questionId": "q4d",
     "timestamp": "2026-09-24T05:33:53.688Z",
     "type": "click"
+  },
+  {
+    "sessionId": "sess_mugkfhe5_nsw8z9",
+    "questionId": "q1",
+    "timestamp": "2026-09-25T06:14:13.722Z",
+    "type": "click"
   }
 ]