54 lines
2.1 KiB
Markdown
54 lines
2.1 KiB
Markdown
# Desktop Local API
|
|
|
|
> **Status:** Active
|
|
> **Last updated:** 2026-07-05
|
|
|
|
## Overview
|
|
|
|
Electron hosts an optional **localhost HTTP API** that exposes read-only access to the local SQLite database, proxies login to allowed signaling servers, and serves bundled Docusaurus documentation offline.
|
|
|
|
## Responsibilities
|
|
|
|
| Layer | Owns |
|
|
|-------|------|
|
|
| Electron `api/router.ts` | HTTP routes, bearer token store, CQRS query dispatch |
|
|
| Desktop settings | Enable/disable Local API, port, allowed signal servers |
|
|
| `docs-site` build | Static bundle mounted at `/docusaurus/*` |
|
|
|
|
## Trust boundary
|
|
|
|
Separate **in-memory bearer tokens** from signaling-server session tokens. Login via Local API issues a local token; read routes require `Authorization: Bearer`. See [authentication.md](authentication.md).
|
|
|
|
## Routes (summary)
|
|
|
|
| Method | Path | Auth | Purpose |
|
|
|--------|------|------|---------|
|
|
| GET | `/api/health` | No | Local API liveness |
|
|
| GET | `/api/openapi.json`, `/docs`, `/scalar/api-reference.js` | No | API docs (Scalar) |
|
|
| GET | `/docusaurus/*` | No | In-app documentation site |
|
|
| POST | `/api/auth/login` | No | Proxy to configured signaling server; returns local bearer |
|
|
| POST | `/api/auth/logout` | Bearer | Revoke local token |
|
|
| GET | `/api/profile` | Bearer | Current user profile |
|
|
| GET | `/api/rooms`, `/api/rooms/{roomId}`, `.../users`, `.../messages`, `.../bans` | Bearer | Read-only room data |
|
|
| GET | `/api/messages/{messageId}`, `.../reactions`, `.../attachments` | Bearer | Message graph |
|
|
| GET | `/api/users/{userId}`, `/api/attachments`, `/api/plugin-data` | Bearer | User + plugin data reads |
|
|
| GET | `/api/meta/{key}` | Bearer | Meta key lookup |
|
|
|
|
Database routes return **503** when SQLite is not initialised.
|
|
|
|
## IPC
|
|
|
|
- `get-local-api-status`, `open-local-api-docs`, `open-docusaurus-docs`
|
|
|
|
## Related
|
|
|
|
- [authentication.md](authentication.md) — trust table
|
|
- `electron/CONTEXT.md` — Local API vocabulary
|
|
- `docs-site/CONTEXT.md` — documentation bundle
|
|
|
|
## Changelog
|
|
|
|
| Date | Change |
|
|
|------|--------|
|
|
| 2026-07-05 | Initial Local API route catalog |
|