Skip to content

Latest commit

 

History

History
1700 lines (1203 loc) · 25.1 KB

API.md

File metadata and controls

1700 lines (1203 loc) · 25.1 KB

Origin-X — Full API Reference

Lumira Core Daemon v0.3.0 · http://localhost:8899

All endpoints require a JWT Bearer token via Authorization: Bearer <token> header unless marked Public.

Locked screen returns 423 Locked for all protected endpoints.


Table of Contents

  1. Health & Auth
  2. Users
  3. System & Platform
  4. Security Engine
  5. Cyber Recon
  6. Terminal (Hyper-Term)
  7. OpenAPI / PostSwagger
  8. Journal
  9. Services
  10. Packages
  11. Network
  12. Updater / OTA
  13. Sandbox
  14. Memory / RAG
  15. Hardware Bus
  16. Voice
  17. Screen
  18. Self-Coding
  19. Ghost Mode
  20. File System
  21. Apps Store
  22. Settings
  23. WebSocket
  24. Static Files

1. Health & Auth

GET /api/health

Auth: Public

Returns service status.

Response:

{ "status": "ok", "service": "lumira-core", "version": "0.3.0" }

GET /api/auth/status

Auth: Public

Check if screen is locked.

Response:

{ "locked": false, "service": "lumira-core" }

POST /api/auth/login

Auth: Public

Authenticate user, receive JWT.

Request:

{ "username": "admin", "password": "secret" }

Response (200):

{
  "token": "eyJ...",
  "user": { "username": "admin", "role": "admin" },
  "expires_in": 86400
}

Response (401):

{ "detail": "Неверный логин или пароль." }

POST /api/auth/unlock

Auth: Public

Unlock the screen.

Request:

{ "password": "secret" }

Response:

{ "ok": true, "locked": false }

POST /api/auth/logout

Auth: Any user

Invalidate current session.

Response:

{ "ok": true }

GET /api/auth/me

Auth: Any user

Return current session info.

Response:

{ "session": { "username": "admin", "role": "admin", "token": "..." } }

POST /api/auth/lock

Auth: Any user

Lock the screen.

Response:

{ "ok": true, "locked": true }

2. Users

GET /api/users

Auth: Any user

List all users.

Response:

{ "users": [{ "username": "admin", "role": "admin" }] }

POST /api/users/create

Auth: Admin

Create a new user.

Request:

{ "username": "tom", "password": "pass", "role": "user" }

Response:

{ "ok": true, "user": { "username": "tom", "role": "user" } }

POST /api/users/delete

Auth: Admin

Delete a user.

Request:

{ "username": "tom" }

Response:

{ "ok": true }

3. System & Platform

GET /api/system

Auth: Any user

Full system info (CPU, RAM, disk, uptime, load).

Response:

{
  "platform": "Linux",
  "release": "7.1.8",
  "machine": "x86_64",
  "hostname": "origin-x",
  "cpu": "Intel Core i7",
  "ram_total_mb": 16384,
  "ram_used_mb": 4096,
  "ram_percent": 25,
  "disk_total_gb": 256,
  "disk_free_gb": 180,
  "loadavg": ["1.0", "0.5", "0.3"],
  "uptime_seconds": 86400
}

GET /api/platform

Auth: Any user

Detect OS platform.

Response:

{
  "os": "Windows",
  "is_wsl": false,
  "is_linux": false,
  "python": "3.12.0",
  "qemu_path": "C:\\Program Files\\qemu\\qemu-system-x86_64.exe"
}

4. Security Engine

GET /api/ports

Auth: Any user

List currently open/listening ports.

Response:

{
  "ports": [
    { "local_address": "0.0.0.0", "local_port": 8899, "pid": 1234, "name": "python" }
  ],
  "warnings": []
}

POST /api/scan

Auth: Any user

TCP port scan.

Request:

{ "host": "127.0.0.1", "port_range": "1-1024" }

Response:

{ "host": "127.0.0.1", "open_ports": [22, 80], "scanned": 1024, "duration_ms": 1234 }

GET /api/processes

Auth: Any user

List running processes.

Response:

{ "processes": [{ "pid": 1, "name": "systemd", "cpu": 0.1, "mem": 0.5 }] }

POST /api/kill

Auth: Admin

Kill a process by name or PID.

Request:

{ "target": "chrome" }

Response:

{ "ok": true, "message": "Process 'chrome' terminated." }

GET /api/docker

Auth: Any user

List Docker containers.

Response:

{
  "status": "ok",
  "containers": [
    { "names": "my-app", "image": "nginx:latest", "status": "Up 2 days" }
  ]
}

POST /api/firewall

Auth: Admin

Add a firewall rule.

Request:

{ "action": "allow", "port": 8080, "protocol": "tcp" }

Response:

{ "ok": true, "message": "Rule applied.", "elevation_required": false }

5. Cyber Recon

POST /api/cyber/scan

Auth: Any user

TCP port scan (extended).

Request:

{ "host": "192.168.1.1", "port_range": "1-1024", "timeout": 2.0, "max_threads": 100 }

Response:

{ "host": "192.168.1.1", "open_ports": [22, 80, 443], "scanned": 1024, "duration_ms": 3400 }

POST /api/cyber/dns

Auth: Any user

DNS record lookup.

Request:

{ "host": "example.com", "record_types": ["A", "AAAA", "MX"] }

Response:

{ "host": "example.com", "records": { "A": ["93.184.216.34"], "MX": ["..."] } }

POST /api/cyber/brute

Auth: Any user

DNS subdomain brute-force.

Request:

{ "host": "example.com", "extra": ["dev", "staging"] }

Response:

{ "host": "example.com", "found": ["www.example.com", "mail.example.com"] }

POST /api/cyber/traceroute

Auth: Any user

Network traceroute.

Request:

{ "host": "8.8.8.8", "max_hops": 30 }

Response:

{ "host": "8.8.8.8", "hops": [{ "ttl": 1, "ip": "192.168.1.1", "rtt_ms": 1.2 }] }

POST /api/cyber/http

Auth: Any user

Fetch HTTP headers.

Request:

{ "url": "https://example.com" }

Response:

{ "url": "https://example.com", "headers": { "Server": "nginx", "Content-Type": "text/html" } }

POST /api/cyber/full

Auth: Any user

Full scan (ports + DNS + subdomains + traceroute in parallel).

Request:

{ "host": "example.com", "port_range": "1-1024" }

Response:

{
  "scan": { "open_ports": [...] },
  "dns": { "records": {...} },
  "subdomains": { "found": [...] },
  "traceroute": { "hops": [...] }
}

6. Terminal (Hyper-Term)

POST /api/terminal

Auth: Any user

Execute a shell command.

Request:

{ "command": "ls -la", "confirm": false }

Response:

{
  "stdout": "total 64\ndrwxr-xr-x ...",
  "stderr": "",
  "returncode": 0,
  "duration_ms": 120,
  "requires_confirmation": false,
  "explanation": "",
  "fix": null,
  "error": null
}

Dangerous commands return requires_confirmation: true with an explanation and proposed fix.


7. OpenAPI / PostSwagger

GET /api/openapi/discover

Auth: Any user

Auto-discover openapi.json in a workspace.

Query params: workspace (default .)

Response:

{ "path": "/path/to/openapi.json" }

POST /api/openapi/load

Auth: Any user

Load and parse an OpenAPI specification.

Request:

{ "path": "/path/to/openapi.json", "workspace": "." }

Response:

{
  "ok": true,
  "title": "My API",
  "version": "1.0.0",
  "endpoints": [{ "method": "GET", "path": "/users", "summary": "List users", "operation_id": "listUsers" }]
}

POST /api/openapi/test

Auth: Any user

Send a test request to a loaded endpoint.

Request:

{
  "index": 0,
  "base_url": "https://api.example.com",
  "overrides": { "header Authorization": "Bearer xxx" },
  "params": {},
  "path_values": {}
}

Response:

{
  "request": { "method": "GET", "url": "https://api.example.com/users", "headers": {...} },
  "response": { "status": 200, "body": "..." }
}

8. Journal

GET /api/journal

Auth: Any user

Read recent journal entries.

Query params: tail (1-1000, default 100), level, source

Response:

{ "entries": [{ "time": "2025-01-01T12:00:00", "level": "info", "source": "auth", "message": "Login success" }] }

DELETE /api/journal

Auth: Admin

Clear the journal.

Response:

{ "ok": true }

9. Services

GET /api/services

Auth: Any user

List system services.

Response:

{ "services": [{ "name": "origin-x", "display": "Lumira Core", "status": "running" }] }

POST /api/services/act

Auth: Admin

Start / stop / restart a service.

Request:

{ "name": "origin-x", "action": "restart" }

Response:

{ "ok": true, "status": "running" }

10. Packages

GET /api/packages

Auth: Any user

List installed Python packages.

Response:

{ "packages": [{ "name": "fastapi", "version": "0.115.0" }] }

POST /api/packages/install

Auth: Admin

Install a Python package.

Request:

{ "package": "requests" }

Response:

{ "ok": true, "message": "requests installed successfully." }

POST /api/packages/remove

Auth: Admin

Remove a Python package.

Request:

{ "package": "requests" }

Response:

{ "ok": true, "message": "requests removed." }

11. Network

GET /api/network

Auth: Any user

Get network info (interfaces, external IP, hostname).

Response:

{
  "hostname": "origin-x",
  "external_ip": "203.0.113.50",
  "interfaces": [
    { "name": "eth0", "state": "up", "ipv4": ["192.168.1.100"] }
  ]
}

POST /api/network/ping

Auth: Any user

Ping a host.

Request:

{ "host": "8.8.8.8" }

Response:

{ "host": "8.8.8.8", "reachable": true, "rtt_ms": 12.5 }

12. Updater / OTA

GET /api/updater/check

Auth: Any user

Check for updates.

Response:

{ "ok": true, "message": "System is up to date.", "latest_version": "0.3.0" }

POST /api/updater/update

Auth: Admin

Pull and apply updates.

Response:

{ "ok": true, "message": "Updated to v0.3.1", "modules_reloaded": 5 }

GET /api/updater/config

Auth: Admin

Get OTA config.

Response:

{ "repo_url": "https://github.com/user/origin-x", "branch": "main", "auto_check": true }

POST /api/updater/config

Auth: Admin

Update OTA config.

Request:

{ "repo_url": "https://github.com/user/origin-x", "branch": "main", "auto_check": true }

Response:

{ "ok": true, "config": {...} }

GET /api/updater/status

Auth: Any user

Check current update status.

Response:

{ "version": "0.3.0", "last_check": "2025-01-01T12:00:00", "auto_check": true }

POST /api/updater/reload

Auth: Admin

Hot-reload Python modules without restarting daemon.

Response:

{ "ok": true, "reloaded": ["core.cyber", "core.sandbox"], "failed": [] }

13. Sandbox

GET /api/sandbox/available

Auth: Any user

Check if Docker sandbox is available.

Response:

{ "docker": true, "fallback": false }

GET /api/sandbox/images

Auth: Any user

List available Docker images.

Response:

{ "images": ["alpine:3.20", "python:3.12-slim"] }

POST /api/sandbox/run

Auth: Any user

Execute code or command in a sandboxed container.

Request (code):

{
  "code": "print('hello')",
  "lang": "python",
  "image": "alpine:3.20",
  "timeout": 30,
  "network": false,
  "memory": "256m",
  "cpus": 1
}

Request (command):

{
  "command": "ls -la /",
  "image": "alpine:3.20",
  "timeout": 10
}

Response:

{
  "ok": true,
  "stdout": "hello",
  "stderr": "",
  "returncode": 0,
  "engine": "docker",
  "duration_ms": 450
}

GET /api/sandbox/history

Auth: Any user

Recent sandbox executions.

Response:

{ "history": [{ "command": "print(1)", "ok": true, "duration_ms": 200 }] }

14. Memory / RAG

GET /api/memory

Auth: Any user

List memory entries.

Query params: source, limit (default 100)

Response:

{
  "entries": [{ "id": "m1", "text": "...", "source": "chat", "created_at": "..." }],
  "stats": { "total": 42, "by_source": { "chat": 20, "sandbox": 22 } }
}

POST /api/memory/search

Auth: Any user

Semantic search in memory.

Request:

{ "query": "firewall rules", "k": 5 }

Response:

{ "results": [{ "text": "...", "score": 0.85, "source": "chat" }] }

POST /api/memory/recall

Auth: Any user

Recall context from memory (returns summary).

Request:

{ "query": "firewall rules", "k": 5 }

Response:

{ "summary": "You discussed firewall rules for ports 80 and 443...", "results": [...] }

POST /api/memory/add

Auth: Any user

Add a memory entry.

Request:

{ "text": "Important note about networking", "source": "manual" }

Response:

{ "ok": true, "id": "m3" }

GET /api/memory/stats

Auth: Any user

Memory statistics.

Response:

{ "total": 42, "by_source": { "chat": 20, "sandbox": 22 } }

DELETE /api/memory

Auth: Admin

Clear all memory.

Response:

{ "ok": true }

15. Hardware Bus

GET /api/hardware/devices

Auth: Any user

List all hardware devices (BT, USB, GPIO).

Response:

{
  "bluetooth": [{ "mac": "00:11:22:33:44:55", "name": "Phone" }],
  "usb": [{ "vid": "1234", "pid": "5678", "name": "Keyboard" }],
  "gpio": []
}

GET /api/hardware/gpio/{pin}

Auth: Any user

Read a GPIO pin value.

Response:

{ "pin": 17, "value": 1 }

POST /api/hardware/gpio/{pin}

Auth: Any user

Write a GPIO pin value.

Request:

{ "value": 1 }

Response:

{ "ok": true, "pin": 17, "value": 1 }

GET /api/hardware/triggers

Auth: Any user

List hardware triggers.

Response:

{ "triggers": [{ "id": "t1", "name": "BT disconnect lock", "enabled": true, "condition": {"type": "bt_disconnected", "mac": "..."} }] }

POST /api/hardware/triggers

Auth: Admin

Add a hardware trigger.

Request:

{
  "name": "Lock on BT disconnect",
  "condition": { "type": "bt_disconnected", "mac": "00:11:22:33:44:55" },
  "action": { "type": "lock" }
}

Response:

{ "ok": true, "id": "t2", "name": "Lock on BT disconnect" }

DELETE /api/hardware/triggers/{trigger_id}

Auth: Admin

Remove a hardware trigger.

Response:

{ "ok": true }

POST /api/hardware/triggers/{trigger_id}/toggle

Auth: Admin

Enable / disable a trigger.

Response:

{ "ok": true, "enabled": true }

GET /api/hardware/status

Auth: Any user

Hardware bus status.

Response:

{ "bt_scanning": true, "usb_polling": true, "gpio_count": 0, "triggers_active": 1 }

16. Voice

GET /api/voice/status

Auth: Any user

Voice subsystem status.

Response:

{ "tts": "pyttsx3", "stt": "whisper", "available": true }

POST /api/voice/config

Auth: Any user

Update voice config.

Request:

{ "tts": "pyttsx3", "stt": "whisper", "whisper_model": "base", "lang": "ru" }

Response:

{ "ok": true, "config": {...} }

POST /api/voice/tts

Auth: Any user

Text-to-speech, returns base64 audio.

Request:

{ "text": "Hello world" }

Response:

{ "ok": true, "audio_base64": "UklGR...", "format": "wav", "engine": "pyttsx3" }

POST /api/voice/speak

Auth: Any user

Speak text and broadcast to WebSocket clients.

Request:

{ "text": "Alert: system breach detected" }

Response:

{ "ok": true, "spoken": true }

POST /api/voice/stt

Auth: Any user

Speech-to-text from uploaded audio file.

Request: multipart/form-data with file field (wav/mp3).

Response:

{ "ok": true, "text": "open the terminal", "engine": "whisper" }

POST /api/voice/listen

Auth: Any user

Record from microphone and transcribe.

Request:

{ "seconds": 5.0 }

Response:

{ "ok": true, "text": "what time is it", "engine": "whisper" }

17. Screen

GET /api/screen/status

Auth: Any user

Screen capture status.

Response:

{ "available": true, "capture_enabled": true, "interval_sec": 5.0 }

POST /api/screen/capture

Auth: Any user

Capture screenshot.

Query params: preview (bool)

Response:

{ "ok": true, "path": "/tmp/screen.png", "preview_base64": "..." }

POST /api/screen/analyze

Auth: Any user

Capture + LLM vision analysis.

Request:

{ "prompt": "What is on screen?" }

Response:

{ "ok": true, "text": "The screen shows a terminal with...", "engine": "gpt-4o" }

POST /api/screen/control

Auth: Any user

Mouse/keyboard control.

Request:

{ "action": "click", "x": 500, "y": 300, "text": "" }

Actions: move, click, right_click, double_click, type, scroll

Response:

{ "ok": true }

POST /api/screen/config

Auth: Any user

Update screen capture config.

Request:

{ "interval_sec": 5.0, "max_width": 1280, "quality": 80, "capture_enabled": true }

Response:

{ "ok": true, "config": {...} }

18. Self-Coding

GET /api/coding/status

Auth: Any user

Self-coding subsystem status.

Response:

{ "available": true, "llm_configured": true }

GET /api/coding/history

Auth: Any user

Recent self-coding tasks.

Response:

{ "history": [{ "task": "Add port scanner module", "ok": true, "files_created": 1 }] }

POST /api/coding/task

Auth: Admin

Run a self-coding pipeline task.

Request:

{ "task": "Create a module that checks disk usage", "confirm": false }

Response (applied):

{ "ok": true, "message": "Module created: core/disk_check.py" }

Response (needs confirmation):

{
  "ok": false,
  "requires_confirmation": true,
  "patch": { "files": [...], "summary": "...", "test": {"passed": true} },
  "message": "Patch ready for review."
}

POST /api/coding/apply

Auth: Admin

Apply a pending patch.

Request:

{ "confirm": true }

Response:

{ "ok": true, "message": "Patch applied." }

19. Ghost Mode

GET /api/ghost/status

Auth: Any user

Ghost Mode status.

Response:

{ "active": false, "breach_detected": false }

POST /api/ghost/config

Auth: Any user

Configure Ghost Mode.

Request:

{
  "firewall_block_inbound": true,
  "lock_on_breach": true,
  "wipe_logs_on_breach": true,
  "encrypt_on_breach": true,
  "ble_key": {"mac": "00:11:22:33:44:55"},
  "tunnel": {"type": "ssh", "host": "remote.server.com", "port": 22}
}

Response:

{ "ok": true, "config": {...} }

POST /api/ghost/enable

Auth: Admin

Enable Ghost Mode (BLE proximity watch).

Response:

{ "ok": true, "message": "Ghost Mode activated. Monitoring BLE key." }

POST /api/ghost/disable

Auth: Admin

Disable Ghost Mode.

Response:

{ "ok": true, "message": "Ghost Mode deactivated." }

POST /api/ghost/wipe-logs

Auth: Admin

Erase journal and temp logs.

Response:

{ "ok": true, "wiped": 142 }

POST /api/ghost/lock-disks

Auth: Admin

Encrypt / lock disks on breach.

Response:

{ "ok": true, "message": "Disk encryption activated." }

POST /api/ghost/tunnel/start

Auth: Admin

Start reverse SSH tunnel.

Response:

{ "ok": true, "message": "Tunnel established to remote.server.com:22" }

POST /api/ghost/tunnel/stop

Auth: Admin

Stop tunnel.

Response:

{ "ok": true, "message": "Tunnel stopped." }

20. File System

POST /api/fs

Auth: Any user

Browse a directory.

Request:

{ "path": "/home/originx" }

Response:

{
  "path": "/home/originx",
  "parent": "/home",
  "entries": [
    { "name": "Documents", "type": "dir", "size": 0, "mtime": 1704067200 },
    { "name": "file.txt", "type": "file", "size": 1024, "mtime": 1704067200 }
  ]
}

21. Apps Store

GET /api/apps/catalog

Auth: Any user

List app catalog.

Query params: category

Response:

{
  "apps": [{ "id": "term", "name": "Terminal", "category": "system", "installed": true }],
  "categories": ["system", "network", "utils"]
}

GET /api/apps/installed

Auth: Any user

Check if an app is installed.

Query params: app_id

Response:

{ "installed": true, "path": "/usr/local/bin/airo-term" }

POST /api/apps/install

Auth: Admin

Install an app.

Request:

{ "app_id": "term" }

Response:

{ "ok": true, "message": "Terminal installed." }

POST /api/apps/search

Auth: Any user

Search apps online.

Request:

{ "query": "text editor", "num": 8 }

Response:

{ "results": [{ "name": "Nano", "url": "...", "description": "..." }] }

POST /api/apps/open-url

Auth: Any user

Open a URL in default browser.

Request (query param): url=https://example.com

Response:

{ "ok": true }

POST /api/apps/download

Auth: Any user

Download a file.

Request:

{ "url": "https://example.com/file.tar.gz", "filename": "file.tar.gz", "subdir": "downloads" }

Response:

{ "ok": true, "path": "/home/originx/downloads/file.tar.gz", "size": 1048576 }

GET /api/apps/downloads

Auth: Any user

List downloaded files.

Query params: subdir

Response:

{ "files": [{ "name": "file.tar.gz", "size": 1048576, "mtime": 1704067200 }] }

GET /api/apps/download-status

Auth: Any user

Check download status.

Query params: download_id

Response:

{ "status": "complete", "progress": 100 }

POST /api/apps/open-file

Auth: Any user

Open a file with default application.

Request (query param): filepath=/home/originx/doc.pdf

Response:

{ "ok": true }

GET /api/apps/history

Auth: Any user

Download history.

Response:

{ "history": [{ "url": "...", "filename": "file.tar.gz", "ok": true }] }

22. Settings

GET /api/settings

Auth: Any user

Get all settings.

Response:

{
  "appearance": { "theme": "dark", "wallpaper": "..." },
  "network": { "proxy": "" },
  "updates": { "auto_check": true }
}

POST /api/settings

Auth: Admin

Update a settings section.

Request:

{ "section": "appearance", "updates": { "theme": "light" } }

Response:

{ "ok": true, "message": "Settings updated." }

23. WebSocket

WS /ws/chat?token=<jwt>

Real-time chat with Lumira. Authenticate via token query parameter.

Client sends:

{ "text": "show system info", "workspace": "." }

Or simply a string: "show system info"

Server responds:

{
  "type": "result",
  "intent": { "action": "system_info", "spoken_response": "..." },
  "content": "Статус системы:\n  • Платформа: Linux 7.1.8...",
  "data": { "platform": "Linux", ... }
}

Event broadcasts:

{ "type": "event", "event": "lock" }
{ "type": "event", "event": "unlock" }
{ "type": "event", "event": "ghost", "state": "on" }
{ "type": "event", "event": "voice", "action": "speak", "text": "..." }
{ "type": "event", "event": "notify", "content": "Hardware trigger activated" }

Confirmation flow:

// Server sends when dangerous action detected:
{ "type": "confirmation", "content": "Kill process chrome?", "confirm": true, "hint": "Reply 'yes' to confirm" }

// Client confirms:
{ "text": "yes" }

24. Static Files

The SPA client is served from the root / path:

GET /            → client/index.html
GET /app.js      → client/app.js
GET /styles.css  → client/styles.css
GET /manifest.json → client/manifest.json

Error Codes

Code Meaning
200 Success
400 Bad request / invalid parameters
401 Unauthorized (bad credentials or missing token)
403 Forbidden (requires admin role)
404 Not found
423 Screen locked — unlock first
500 Internal server error

Rate Limits

None enforced at application level. For production deployment, use a reverse proxy (nginx/traefik) with rate limiting.


Versioning

API version is embedded in the FastAPI OpenAPI spec at GET /openapi.json (auto-generated by FastAPI/Starlette).