sovereign-chat/README.md

# Sovereign Chat

A secure, enterprise-grade, OpenWebUI-compatible chat interface designed for the **Sovereign** AI appliance by Theta42.

## Features

- **Sovereign Chat Interface** - Fully branded premium dark slate theme with fluid transitions and Outfit typography.
- **LDAP Single Sign-On (SSO)** - Enterprise user authentication and group-based role checking (admins vs. standard users).
- **Administration Panel** - Dedicated administrative dashboard containing:
  - **Model Management**: Downloader for Theta42 pre-approved models (e.g. `SmolLM2-135M` & `SmolLM2-360M`), custom GGUF model upload drag-and-drop, and dynamic active model reload.
  - **Quotas & Scheduling**: Daily token quota configuration per user and operational hours (scheduling access window).
  - **Live Auditing & Compliance**: Real-time user session activity logs, plus a compliance download manager for cryptographically signed audit archives (`.tar.gz` and `.sig` signatures) aggregated by `cryptographic-audit-logger` on `/tank/audit`.
  - **Network Configuration**: View and configure the appliance exposed bridge interfaces (e.g. `vmbr0`) and static IP parameters.
- **RAG & Document Management** - Multi-file upload parsing and retrieval-augmented generation.
- **Strict Compliance Log Aggregator** - Chat completion requests log SOX-compliant query metadata to `/tank/audit/chat-audit.log` while strictly redacting the prompt text to protect privacy.
- **Streaming Responses** - Real-time token streaming.

## Quick Start

```bash
# Clone
git clone https://git.theta42.com/theta42/sovereign-chat.git
cd sovereign-chat

# Install
npm install

# Development (hot reload)
npm run dev

# Production build
npm run build

# Production server
NODE_ENV=production npm start
```

## Configuration

Uses JSON config files in `conf/` directory:

```
conf/
├── base.json           # Base config (all environments)
├── development.json    # Dev overrides (auth disabled)
├── production.json     # Production overrides
├── secrets.json        # Secrets (gitignored!)
└── secrets.example.json # Template
```

### Load Order

Files merge in order: `base.json` → `[environment].json` → `secrets.json`

### Example Configs

**conf/base.json:**
```json
{
  "server": { "port": 8089 },
  "gateway": { "url": "http://192.168.100.201:8000" },
  "auth": {
    "disabled": false,
    "ldap": {
      "enabled": true,
      "url": "ldap://ldap.internal.theta42.com:389",
      "baseDN": "dc=theta42,dc=com",
      "searchFilter": "(uid={{username}})"
    }
  }
}
```

**conf/secrets.json:**
```json
{
  "gateway": { "token": "your-openclaw-token" },
  "session": { "secret": "random-session-secret" },
  "auth": {
    "ldap": {
      "bindDN": "cn=ldapclient service,ou=People,dc=theta42,dc=com",
      "bindPassword": "1lovebyte"
    }
  }
}
```

### Environment Variables

Can override config at runtime:

- `PORT` - Server port
- `OPENCLAW_GATEWAY` - Gateway URL (points to AI-Core runtime)
- `OPENCLAW_TOKEN` - Gateway auth token
- `SESSION_SECRET` - Session signing secret
- `LDAP_ENABLED` - Enable LDAP auth

## LDAP Authentication

Supports standard LDAP servers (OpenLDAP, Active Directory):

1. Service binds with `bindDN` + `bindPassword`
2. Searches for user with `searchFilter`
3. Binds as user to verify password

**Search Filter:**
Use `{{username}}` as placeholder:
```
(&(memberof=cn=app_sovereign_admin,ou=groups,dc=theta42,dc=com)(uid={{username}}))
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Sovereign Chat                       │
├─────────────────────────────────────────────────────────┤
│  Frontend (Vanilla JS + Vite)                           │
│  ├── Chat Interface (SSO / LDAP login)                  │
│  ├── File Upload (content included)                      │
│  ├── Code Canvas                                         │
│  └── Administration Dashboard (Models, Quotas, Logs)     │
├─────────────────────────────────────────────────────────┤
│  Backend (Express.js)                                    │
│  ├── LDAP SSO Authentication & Group-based RBAC          │
│  ├── Session Management                                  │
│  ├── Chat History Persistence                            │
│  ├── Append-only HIPAA/SOX Metadata Logger               │
│  └── Admin APIs (/api/admin/*)                           │
├─────────────────────────────────────────────────────────┤
│  AI-Core Engine (port 8000)                             │
│  └── vLLM Server + Dynamic Model provisioner reload      │
└─────────────────────────────────────────────────────────┘
```

## API Endpoints

### Authentication
- `GET /api/auth/status` - Check auth status
- `POST /api/auth/login` - Login
- `POST /api/auth/logout` - Logout

### Conversations
- `GET /api/conversations` - List conversations
- `POST /api/conversations` - Create conversation
- `PUT /api/conversations/:id` - Update conversation
- `DELETE /api/conversations/:id` - Delete conversation
- `GET /api/conversations/:id/messages` - Get messages

### OpenAI-Compatible
- `POST /v1/chat/completions` - Chat completion requests (audited for token quotas and scheduling window)
- `GET /v1/models` - List models

### Admin Management Panel
- `GET /api/admin/status` - Fetch exposed network interfaces, active model, and stats
- `POST /api/admin/network` - Update static IP configuration (writes to `/etc/theta42/network.json`)
- `GET /api/admin/audit-logs` - Fetch cryptographically signed compliance log archives from `/tank/audit`
- `GET /api/admin/preapproved` - Fetch preapproved model list from manifest
- `POST /api/admin/models/download` - Trigger background download of a model to `/tank/staging`
- `POST /api/admin/models/upload` - Upload a custom model file to `/tank/staging`
- `POST /api/admin/settings` - Update daily token quotas and active operating hours schedule
- `POST /api/admin/models/active` - Update active model and trigger dynamic engine reload
- `GET /api/admin/monitoring` - View real-time active user query metadata statistics

## Production Deployment

**Systemd Service:**
```bash
# Create service file
cp sovereign-chat.service /etc/systemd/system/

# Enable and start
systemctl enable sovereign-chat
systemctl start sovereign-chat

# View logs
journalctl -u sovereign-chat -f
```

## Development

```bash
npm run dev
# Frontend: http://localhost:5173 (Vite HMR)
# Backend: http://localhost:3000 (auto-restart)
```

## License

MIT