HiperChat Sovereign API

HiperChat is a zero-external-dependency, high-performance real-time messaging gateway and sovereign command center. It provides simultaneous access across standard IRC TCP, WebSocket message streaming, and REST automation endpoints.

Sovereign Design Principles:

Zero External CDNs: 100% self-contained single binary with bundled SQLite and memory bus.
Strict Authentication: Web access requires Google OAuth 2.0. Autonomous agents and CI pipelines use Bearer API tokens.
Dual Plane: Simultaneous RFC-compliant IRC engine and JSON REST endpoints backed by daily disk transcripts.

Authentication Model

HiperChat uses a dual-layer cryptographic authentication architecture:

Client Type	Mechanism	Header / Protocol Token
Human Web Users	Google OAuth 2.0 (OpenID Connect)	HMAC-SHA256 Signed Session Token (`PASS <token>` or `Authorization: Bearer <token>`)
Autonomous Bots & Agents	Static Bearer API Token	`Authorization: Bearer <api_token>` (Configured in `hiperchat.toml`)
IRC Clients (HexChat, WeeChat)	IRC `PASS` handshake	`PASS <session_token_or_api_token>`

Security Policy Note:

Legacy username/password authentication is permanently disabled for web users to prevent credential stuffing and brute-force vulnerabilities. Human users must authenticate through Google OAuth.

Publish Message API

Allows automated agents, alert managers, and webhooks to broadcast messages into channels or send direct alerts.

POST /api/v1/publish

Bearer Auth Required

Request Headers:

HTTP Headers

Authorization: Bearer sovereign-agent-token
Content-Type: application/json

JSON Body Parameters:

Field	Type	Status	Description
channel	string	Required	Target channel name (e.g. `#alerts`, `#engineering`) or DM nick (`@alice`).
sender	string	Required	Sender identifier. Must match token's allowed senders or name.
message	string	Required	Message content to broadcast (Markdown supported).
msg_type	string	Optional	`PRIVMSG` (default) or `NOTICE`.

Example Request (cURL):

cURL

curl -X POST http://localhost:8080/api/v1/publish \
  -H "Authorization: Bearer sovereign-agent-token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "#alerts",
    "sender": "ci-pipeline",
    "message": "Deployment to production successful (Commit: e7a7c12)"
  }'

Response (200 OK):

JSON Response

{
  "success": true,
  "data": {
    "status": "published",
    "channel": "#alerts",
    "sender": "ci-pipeline"
  }
}

File Upload API

Upload binary attachments, PDF architecture diagrams, screenshots, or logs securely.

POST /api/v1/upload?filename=diagram.pdf

Bearer Auth Required

Direct binary streaming upload. The file content is hashed with SHA-256 to generate an immutable, collision-resistant 64-character identifier.

Example Request (cURL):

cURL

curl -X POST "http://localhost:8080/api/v1/upload?filename=architecture.pdf" \
  -H "Authorization: Bearer sovereign-agent-token" \
  -H "Content-Type: application/pdf" \
  --data-binary @architecture.pdf

Response (200 OK):

JSON Response

{
  "success": true,
  "data": {
    "id": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "filename": "architecture.pdf",
    "size_bytes": 1048576,
    "url": "/api/v1/files/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "mime_type": "application/pdf"
  }
}

Secure File Download

Fetches previously uploaded attachments with strict Content Security Policy (CSP) sandboxing and attachment headers.

GET /api/v1/files/:file_id

Public Token Gated

Security Headers Enforced:

Content-Disposition: attachment; filename="..." (Prevents browser inline execution)
Content-Security-Policy: default-src 'none'; sandbox (Disables script execution)
X-Content-Type-Options: nosniff (Blocks MIME sniffing)

Channel History API

Retrieves recent messages from channels or direct message threads.

GET /api/v1/history?channel=%23alerts&limit=50

Bearer Auth Required

Query Parameters:

Parameter	Type	Description
channel	string	URL-encoded target (e.g. `%23alerts` or `@dm:alice:bob`).
limit	integer	Number of messages to retrieve (1 to 1000, default 50).

Transcript Export API

Exports complete daily conversation transcripts formatted as Markdown or JSON.

GET /api/v1/export?channel=%23general&format=markdown

Bearer Auth Required

Example cURL:

cURL

curl -s -H "Authorization: Bearer sovereign-agent-token" \
  "http://localhost:8080/api/v1/export?channel=%23general&format=markdown" -o general_transcript.md

Real-Time WebSocket IRC Gateway

Connect autonomous bots or custom UI clients to the live IRC event bus over WebSockets.

WSS /ws

PASS Handshake Required

Connection Handshake Sequence:

IRC Wire Protocol

PASS <session_token_or_api_token>
NICK my_bot
USER my_bot 0 * :Autonomous Firstmate Bot
JOIN #alerts
PRIVMSG #alerts :Agent online and listening

Python Agent Integration Example

Complete script using Python 3 to send alerts and stream WebSocket messages:

Python 3 (bot.py)

import urllib.request
import json

SERVER_URL = "http://localhost:8080"
API_TOKEN = "sovereign-local-admin-token"

def send_alert(channel: str, message: str):
    payload = json.dumps({
        "channel": channel,
        "sender": "python-agent",
        "message": message
    }).encode("utf-8")

    req = urllib.request.Request(
        f"{SERVER_URL}/api/v1/publish",
        data=payload,
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        method="POST"
    )

    with urllib.request.urlopen(req) as resp:
        print(f"Status: {resp.status}, Response: {resp.read().decode()}")

if __name__ == "__main__":
    send_alert("#alerts", "🚀 Python Autonomous Agent initialized successfully.")

Node.js Integration Example

JavaScript / Node.js (agent.js)

const SERVER_URL = 'http://localhost:8080';
const API_TOKEN = 'sovereign-local-admin-token';

async function publishMessage(channel, message) {
  const res = await fetch(`${SERVER_URL}/api/v1/publish`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      channel,
      sender: 'node-bot',
      message
    })
  });

  const data = await res.json();
  console.log('Result:', data);
}

publishMessage('#general', 'Hello from Sovereign Node.js Agent!');