LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.
C cdebiandesktop-environmentebpffirewalllandlocklinuxlinux-distributionopen-sourceprivacyquickjsraspberry-pi-5reactsecuritywaylandwayland-compositor
/* broker.h — the "broker": the only channel between an isolated .lpk app (lord-server --app) and
* lord-server. The SDK inside the app process proxies the lord.* calls over this socket;
* lord-server checks the permission for each one (server/src/sec/perms.c) and, if needed, draws
* the system prompt. See appclient.c (app side), brokersrv.c (server side) and
* docs/PRIVACY.md.
*
* Protocol: SOCK_SEQPACKET messages. Each message = BrokerHdr + payload (text/JSON). Replies
* carry the same reqid. The file picker (powerbox) and the devices pass
* fds via SCM_RIGHTS. */
#ifndef LORD_SEC_BROKER_H
#define LORD_SEC_BROKER_H
#include <stddef.h>
#include <stdint.h>
#include <poll.h>
#define BROKER_FD_ENV "LORD_BROKER_FD"
#define BROKER_MAX_MSG (1024 * 1024)
enum BrokerOp {
BOP_FS_HOME = 1, /* → path of the app's data folder */
BOP_FS_READ, /* payload: path relative to the data folder → contents */
BOP_FS_WRITE, /* payload: "path\0contents" inside the data folder */
BOP_FS_LIST, /* payload: path → JSON [{name,dir}] */
BOP_CLIP_GET, /* (clipboard permission) → clipboard text */
BOP_CLIP_SET, /* payload: text → to the clipboard */
BOP_PERM, /* payload: permission name → "1"/"0" (asks if needed) */
BOP_DEVICE, /* payload: "camera on" | "microphone off" → sets the indicator */
BOP_PICK, /* (powerbox) opens the system dialog → fd of the chosen file */
BOP_THEME, /* → JSON of the theme tokens */
BOP_QUIT, /* the app is closing */
BOP_STATE, /* → JSON { theme, locale, keyboard }: the current state, at startup */
BOP_MENU, /* payload: JSON of the app's menus (for the system menu bar) */
BOP_MIC, /* payload "1"/"0": request/release the microphone. With permission, → read-only fd of the ring */
BOP_CAMERA, /* payload "list" | "open dev w h" | "ring sid" (→ read-only ring fd) | "ack sid id" |
* "size sid w h" | "photo sid mirror name" | "record sid mirror mic name" |
* "recstop sid" | "close sid". See brokercam.c */
BOP_VAULT_FIDO = 40,/* (Passwords only) open the FIDO2 key for lord-vault after the `usb` permission →
* "name"; the app never gets the device (docs/PASSWORDS.md) */
BOP_CLIP_SECRET, /* payload "seconds\0text": a secret to the clipboard, marked sensitive (out of
* the history, x-kde-passwordManagerHint) and cleared after `seconds` if unchanged */
BOP_KEYRING, /* payload "op\0service\0account\0label\0secret" (op: get | set | delete | list) → the
* app's own session-keyring items, owner = the verified app id (brokerkr.c,
* docs/PASSWORDS.md). Error replies carry an error code line (keyring.*) */
BOP_MAIL, /* (system Mail, Calendar, Contacts, Reminders only) lord-maild through lord-server:
* payload "verb\0rest", fds via SCM_RIGHTS for "req"/"reqm". Replies and events
* come back as "mail" events, in chunks. See brokermail.c, docs/PRIVACY.md */
BOP_SYS_OPEN, /* (those same system apps only) payload "app\0new\0json": open another of them
* with these args (Mail → Calendar for an invitation, Contacts → a new message) */
BOP_PROBE, /* (the system package `sysprobe` only, app/probe.c) payload: JSON of what its sandbox
* refused; lord-server adds the process's own status and keeps it for lord.sysinfo */
BOP_EVENT = 100, /* server → app, unrequested (reqid 0): payload "type\0json" */
};
enum BrokerStatus { BST_OK = 0, BST_DENIED = 1, BST_ERROR = 2, BST_PENDING = 3 };
typedef struct {
uint32_t reqid;
uint16_t op; /* BrokerOp (request) */
uint16_t status; /* BrokerStatus (reply); 0xffff in a request */
uint32_t len; /* payload bytes that follow */
} BrokerHdr;
#define BROKER_REQ 0xffff
/* ---- server side (lord-server, brokersrv.c) ---- */
/* Registers a new broker for app <id> (pid, for the cgroup/monitor). Returns -1 if there is no
* room. main.c polls the fd. */
int brokersrv_add(int fd, const char *id, int pid);
/* fds for poll(); returns how many it wrote and their indices. */
int brokersrv_pollfds(struct pollfd *pfd, int max);
void brokersrv_dispatch(struct pollfd *pfd, int n);
/* Delivers pending prompts and indicator changes to JS. */
typedef void (*BrokerEventFn)(const char *kind, const char *json);
void brokersrv_events(BrokerEventFn fn);
/* User's answer to a prompt (from JS: lord.broker.resolve). */
void brokersrv_resolve(uint32_t reqid, int allow);
int brokersrv_count(void);
/* The app on broker fd `fd` was spawned with a channel to lord-vault (system Passwords app): it may
* use BOP_VAULT_FIDO. */
void brokersrv_set_vault(int fd);
/* The app on broker fd `fd` is a system package (assets/sysapps, verified by app_package_dir): it
* keeps the keyring owner and lord-maild access it had in-process. */
void brokersrv_set_system(int fd);
/* Args for an isolated app (wm.open(id, { args }) in the session): sent now if it is running, or
* kept and sent when it starts. `json` is a JSON object (≤ 16 KiB). 0 if sent or kept. */
int brokersrv_open_args(const char *id, const char *json, size_t len, int new_window);
/* The app <id> is running: ask it for a new window. 0 if sent, -1 if it is not running. */
int brokersrv_new_window(const char *id);
/* Quit app <id> (❖Q, Dock → Quit): the app host closes all its windows, its close guards still
* apply, and the process ends when the last one closes. 0 if sent, -1 if it is not running. */
int brokersrv_quit(const char *id);
/* The id of the isolated app whose process is `pid` (a Wayland client's pid), or NULL. */
const char *brokersrv_app_of_pid(int pid);
/* The theme publishes its state (type "theme" or "locale", JSON) and it's forwarded live to every
* isolated app; it's also kept for the ones that start later (BOP_STATE). */
int brokersrv_publish(const char *kind, const char *json, size_t len);
/* On every loop iteration: forwards the keyboard layout if it changed and retries the sends
* that didn't fit (the server never blocks waiting on an app). */
void brokersrv_tick(void);
/* The user revoked a permission in Settings → Privacy: the app is notified (it releases the
* device) and its indicator is turned off. */
void brokersrv_revoke(const char *app, const char *perm);
/* The user picked a file in the system dialog (powerbox): lord-server opens it and passes
* the fd to the app. Empty or NULL path = cancelled. */
void brokersrv_pick_result(uint32_t reqid, const char *path);
/* The user picked an item from an app's menu (from the system menu bar): the app is notified
* through the broker. */
void brokersrv_menu_click(const char *app, const char *item);
/* JSON of the menus an app published (for the system menu bar); "[]" if none. */
const char *brokersrv_menus(const char *app);
/* System Information's last sandbox probe (BOP_PROBE): JSON { probe, proc, at } or NULL. */
const char *brokersrv_probe_result(void);
/* The microphone (and later the camera) runs in lord-server: its PipeWire socket has to be
* serviced in the main loop. */
int brokersrv_audio_pollfds(struct pollfd *pfd, int max);
void brokersrv_audio_dispatch(struct pollfd *pfd, int n);
#endif