HTTP API

The BBS has an HTTP API for programs and web front ends: REST for accounts, message areas, mail and files; server-sent events; and WebSockets for chat, in JSON or protobuf. A web client is a node like any other: it shows in Who's online, chats with terminal callers, gets node messages and can page the sysop.

It is on when bbs.conf has an [http] section:

[http]
address = :8443
cert_file = /etc/bbs/tls/cert.pem
key_file = /etc/bbs/tls/key.pem
;cors = https://www.example.org
;metrics = 127.0.0.1:9100

The OpenAPI 3.1 description is at /api/v1/openapi.json.

Behind a proxy¶

The server can sit behind a reverse proxy (nginx, Caddy, HAProxy, a load balancer) that handles TLS. Every request then comes from the proxy's address, so list the proxy in trusted_proxies, and the server will trust it to say which caller each request is from:

[http]
address = 127.0.0.1:8080
tls = no
trusted_proxies = 127.0.0.1, ::1
secure_cookies = yes

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_http_version 1.1;                  # the WebSockets: streams
    proxy_set_header Upgrade $http_upgrade;  # and the web terminal
    proxy_set_header Connection "upgrade";
    client_max_body_size 8m;                 # the image boards' images
}

The caller's address is the last address in X-Forwarded-For (or else Forwarded's for=, or else X-Real-IP) that is not a trusted proxy. Any addresses before it are whatever the caller sent, and are not trusted. That address is then used for the request everywhere: rate limits, logins and the logs, the forum, the web terminal's throttling, the image boards' flood control and bans, and the [security] deny lists and bans (a refused caller gets 403). Connections from a trusted proxy are not held to max_per_ip, because they carry many callers. Requests from anywhere else are taken as they come, and their forwarding headers are ignored.

Tokens and scopes¶

Every request but /login, /openapi.json and (when anonymous = yes) /system and /who needs a token: Authorization: Bearer bbs_....

• A session: POST /api/v1/login with {"name": ..., "password": ...} (and "scopes", to have fewer) returns {"token": ..., "expires": ...}. POST /api/v1/logout ends it.
• An API key, for a program: bbs token add alice -scope read,post -expires 90 -name "my bot" prints it once. bbs token list [USER] and bbs token revoke ID manage them, and users see and revoke their own at /api/v1/me/tokens.

Only a hash of a token is kept. A locked user's tokens stop working.

REST¶

Every endpoint is under /api/v1 and takes and returns JSON (except uploads and downloads). Errors are {"error": "...", "code": "..."}.

TOKEN=$(curl -s https://bbs.example.org:8443/api/v1/login \
  -d '{"name":"alice","password":"..."}' | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" https://bbs.example.org:8443/api/v1/areas
curl -s -H "Authorization: Bearer $TOKEN" https://bbs.example.org:8443/api/v1/areas/1/messages \
  -d '{"subject":"Hello","body":"From curl."}'

Streams and nodes¶

The event stream and each WebSocket take a node, just as a caller does (Via is web). The node counts against max_nodes, shows in Who's online, and receives the node's events: lines said in its chat room, node messages, pages (for sysops), new mail and notices. The node ends when the connection does. POST /nodes/{n}/message, /page and answering a page are done from the token's open stream (409 without one). A page that reaches no sysop is 503 (unavailable), as the WebSocket's Page request answers it, and is not left waiting.

Server-sent events¶

GET /api/v1/events (with the Authorization header; a browser does this with fetch, as EventSource cannot send headers) starts with event: welcome (its node and user), then sends each event as event: said (emoted, joined, left, private, paged, notice, mail) with the event as JSON in data:, and a comment every 25 seconds to keep it open.

WebSockets¶

Two endpoints speak the same protocol, bbs.v1, defined in proto/bbs.proto:

The client sends ClientMessages with an id of its choosing; each is answered by ServerMessages with that id: ok (with room when the client's room changed), error (code and message), or what was asked for. Events and the welcome come with id 0.

A browser cannot set headers on a WebSocket, so unless the upgrade had an Authorization header the first message must be auth, within 10 seconds. The token needs the chat scope.

A session in JSON (> from the client):

> {"id":1,"auth":{"token":"bbs_..."}}
  {"welcome":{"bbs":"The BBS","user":"alice","node":3,"scopes":["read","post","mail","chat","files"]}}
> {"id":2,"join":{"room":"main"}}
  {"id":2,"lines":{"lines":["bob: hi all"]}}
  {"id":2,"ok":{"room":"main"}}
> {"id":3,"say":{"text":"hello from the web"}}
  {"id":3,"ok":{}}
  {"event":{"kind":"SAID","room":"main","from":"alice","node":3,"text":"hello from the web","time":"2026-10-11T12:00:00Z","line":"alice: hello from the web"}}
  {"event":{"kind":"SAID","room":"main","from":"bob","node":1,"text":"welcome!","time":"2026-10-11T12:00:04Z","line":"bob: welcome!"}}

Clients of the protobuf endpoint generate code from proto/bbs.proto (protoc --go_out=..., --python_out=... and so on). In JavaScript:

const ws = new WebSocket("wss://bbs.example.org:8443/api/v1/ws", "bbs.v1.json");
ws.onopen = () => ws.send(JSON.stringify({id: 1, auth: {token}}));
ws.onmessage = (m) => {
  const msg = JSON.parse(m.data);
  if (msg.welcome) ws.send(JSON.stringify({id: 2, join: {room: "main"}}));
  if (msg.event) console.log(msg.event.line);
};

The server pings every 30 seconds. Frames are at most 16 KB; a frame that does not read is answered by an error, and the same limits as on a terminal apply (200 characters a line, 8 lines in 10 seconds).

The web terminal¶

/terminal (and /, which goes there when the web forum is off) is the BBS in a browser: a page with xterm.js (5.5, MIT licensed, built into the bbs binary: nothing is loaded from elsewhere) whose terminal is joined to the text BBS by a WebSocket, /terminal/ws. The caller is a node like a telnet caller (Who's online says web terminal) and logs in at the BBS's own prompt, as on telnet: no token. They get ANSI colour and UTF-8 (ANSI art's CP437 shown as Unicode), menus, messages, mail, chat, paging and doors; not file transfers (download files by the API or FTP). Its xterm.js has the image addon, so the image boards' pictures (sixel) show in it.

The page allows scripts only from the BBS itself, cannot be framed, and accepts WebSockets only from its own host (and the cors origin). Connections count against max_per_ip and rate, and logins count against the throttle as a terminal's do. Behind a proxy on 127.0.0.1 without trusted_proxies, throttling is up to the proxy, because the BBS sees every caller as the proxy. terminal = no turns the page off.

Metrics¶

With metrics = 127.0.0.1:9100, /metrics there has, in Prometheus's text format: bbs_nodes, bbs_nodes_by_via{via}, bbs_max_nodes, bbs_users, bbs_messages, bbs_logins_total, bbs_login_failures_total, bbs_posts_total, bbs_mail_total, bbs_pages_total, bbs_chat_lines_total, bbs_pages_waiting and bbs_fido_outbound_files{link}.

Security¶

• TLS by default; tokens never go in URLs (only in the Authorization header or a WebSocket's first message).
• Tokens are 32 random bytes; only their SHA-256 is stored. A wrong token waits as a wrong password does, and failed logins are logged and counted like a terminal's.
• Rate limits per token (per address without one), connections per address, JSON bodies at most 64 KB with unknown fields refused, uploads limited as on the BBS.
• No CORS unless one origin is named; WebSockets from origins other than it and the API's own host are refused. Responses carry nosniff and no-store.
• What web clients say and post is cleaned as a terminal caller's is.

See also: Chat and paging, Security, Configuration