plugins: READMEs

Author: lws-team

plugins/protocol_lws_cert_dist_client/README.md

@@ -0,0 +1,22 @@
+# lws-cert-dist-client
+
+This is the client-side protocol plugin for the certificate distribution system. It allows unprivileged client processes to securely request and update their TLS certificates (fullchain and private key) from a central `lws-cert-dist-server`.
+
+## Features
+
+- Securely fetches and updates TLS certificates for specified subdomains.
+- Spawns a privileged stub process (`--lws-stub=distribution-client`) when running as root to manage local file system writes and UDS communication.
+- Implements a UDS (Unix Domain Socket) IPC mechanism (`lws-cert-dist-stub`) for secure communication between the unprivileged process and the privileged stub.
+- Atomic symlink updates when new certificates are received.
+
+## Configuration PVOs (Per-VHost Options)
+
+| Name | Meaning | Default |
+|---|---|---|
+| `base-dir` | The base directory where certificates will be stored. | `/etc/lwsws-pki` |
+| `server-url` | The WebSocket URL of the central distribution server. | `wss://distribution-server.local` |
+| `subdomains` | A list of subdomains to request certificates for. | N/A |
+
+## Usage
+
+When enabled, the plugin checks if it is running as root and if subdomains are configured. If so, it spawns a privileged stub process to handle file system operations and sets up a UDS server. Unprivileged clients connect to this UDS server, which forwards JSON payloads containing the `subdomain`, `fullchain`, and `privkey` received from the central distribution server.

plugins/protocol_lws_cert_dist_server/README.md

@@ -0,0 +1,20 @@
+# lws-cert-dist-server
+
+This is the server-side protocol plugin for the certificate distribution system. It securely distributes TLS certificates (fullchain and private key) to authorized clients based on Mutual TLS (mTLS) authentication.
+
+## Features
+
+- Distributes certificates directly to verified clients over a secure WebSocket connection.
+- Relies on Mutual TLS (mTLS) to authenticate clients. The Common Name (CN) of the client certificate is used to identify the subdomain.
+- Actively watches the local Public Key Infrastructure (PKI) directory (if `LWS_WITH_DIR` is enabled) and automatically pushes updated certificates to connected clients when changes occur on disk.
+
+## Configuration PVOs (Per-VHost Options)
+
+| Name | Meaning | Default |
+|---|---|---|
+| `pki-root` | The root directory where domain certificates are stored. | `/var/dnssec/domains/` |
+
+## Usage
+
+When a client connects, the plugin extracts the Common Name (CN) from the client's TLS certificate to identify the requesting subdomain. It then validates that a distribution client certificate exists on the server for that subdomain at `pki-root/<domain>/dist-client/distribution-client-<subdomain>.crt`.
+If authorized, it reads the `fullchain.pem` and `privkey.pem` for the domain, encodes them in a JSON payload, and sends them to the client. If file system watching is enabled (`LWS_WITH_DIR`), the server automatically triggers updates to connected clients whenever the respective `fullchain.pem` or `privkey.pem` files are modified.

plugins/protocol_lws_oauth_preauth/README.md

@@ -0,0 +1,24 @@
+# lws-oauth-preauth
+
+This plugin provides a WebSocket-based waiting room for devices that have not yet been paired/authorized via RFC 8628 (OAuth 2.0 Device Authorization Grant). It acts as an intermediary signaling channel where pre-authenticated admin clients can securely identify and interact with unauthenticated devices before full pairing.
+
+## Features
+
+- Maintains a list of connected unauthenticated "devices" and authorized "listeners" (admins).
+- Validates authorized admin listeners via JWT (JSON Web Tokens) provided via an HTTP cookie.
+- Allows admins to discover unauthenticated devices currently waiting for pairing.
+- Facilitates sending "identify" commands to specific devices, often used to trigger a physical indication (like a blinking LED) so the admin can verify physical possession of the device before authorizing it.
+
+## Configuration PVOs (Per-VHost Options)
+
+| Name | Meaning | Default |
+|---|---|---|
+| `cookie-name` | The name of the HTTP cookie that carries the JWT for admin validation. | `auth_session` |
+| `jwt-jwk` | The JSON Web Key (JWK) string used to verify the JWT signature. Can be the literal JSON or a path to a file depending on LWS configuration. | N/A |
+
+## Operation
+
+- **Devices**: Devices connect to this protocol over WebSocket and send JSON payloads containing their identifying information (`name`, `serial`, `user_code`). 
+- **Listeners (Admins)**: Admins connect to the same protocol, providing their JWT cookie. If validation succeeds, they are registered as a listener. 
+- **Broadcast**: When a device connects or disconnects, the plugin broadcasts its state to all connected listeners.
+- **Identification**: A listener can send `{"cmd": "identify", "serial": "<device-serial>"}`. The plugin will route this `identify` command down to the target device, allowing it to perform a physical identification action (e.g., blink an LED).

plugins/protocol_lws_smtp_client/README.md

@@ -0,0 +1,30 @@
+# lws-smtp-client
+
+This is a protocol plugin providing a simple SMTP client API. It allows other components and plugins to asynchronously queue and send emails via a local or remote SMTP server.
+
+## Features
+
+- Non-blocking, event-loop integrated SMTP client.
+- Provides a C API (`lws_smtp_client_ops_t`) exposed via the protocol's user pointer, allowing other plugins/C code to trigger emails dynamically.
+- Implements a basic SMTP state machine (Connecting, Greeting, Helo, Mail From, Rcpt To, Data, Body, Quit).
+
+## Usage via C API
+
+You can lookup the protocol and access its operations to send emails from within libwebsockets:
+
+```c
+const struct lws_protocols *pp = lws_vhost_name_to_protocol(vh, "lws-smtp-client");
+if (pp) {
+	lws_smtp_client_ops_t *ops = (lws_smtp_client_ops_t *)pp->user;
+	
+	lws_smtp_email_t email;
+	email.from = "sender@example.com";
+	email.to = "receiver@example.com";
+	email.subject = "Test Email";
+	email.body = "This is a test email sent via lws-smtp-client.";
+
+	ops->send_email(cx, vh, &email);
+}
+```
+
+The plugin internally queues the email and asynchronously negotiates the SMTP transaction. By default, it connects to an SMTP server at `127.0.0.1:25`.

plugins/protocol_lws_webrtc/README.md

@@ -0,0 +1,24 @@
+# lws-webrtc
+
+This plugin implements a shared WebRTC signaling and media transport layer within libwebsockets. It handles the WebSocket signaling, DTLS (Datagram Transport Layer Security) negotiation, SRTP (Secure Real-time Transport Protocol) keying, and RTP packetization for both audio and video streams.
+
+## Features
+
+- **Signaling**: Parses and generates SDP (Session Description Protocol) offer/answer exchanges over a secure WebSocket connection.
+- **ICE Handling**: Processes STUN (Session Traversal Utilities for NAT) binding requests to establish connectivity without full ICE-agent complexity (acts as an ICE-lite server).
+- **Security**: Sets up DTLS handshakes and extracts SRTP keys to encrypt outgoing RTP media flows.
+- **Media Delivery**: Provides a C API (`lws_webrtc_send_video`, `lws_webrtc_send_audio`) to inject raw H.264/AV1 NAL units and Opus frames into the WebRTC session.
+- **Packetization**: Automatically fragments H.264/AV1 bitstreams and wraps them in RTP packets suitable for browsers.
+- **Feedback**: Receives and processes RTCP (RTP Control Protocol) feedback, particularly NACKs and PLIs (Picture Loss Indications), to maintain stream health.
+
+## Usage
+
+This protocol is usually utilized as an underlying infrastructure plugin for higher-level media handlers (like `protocol_lws_rtc_camera` or `protocol_lws_webrtc_mixer`), which feed the raw media frames into `lws_webrtc`.
+
+It provides operations via `lws_vhost_name_to_protocol(vh, "lws-webrtc")->user`, exposing functions like:
+- `lws_webrtc_send_video()`
+- `lws_webrtc_send_audio()`
+- `lws_webrtc_send_text()`
+- Session iteration and telemetry functions.
+
+When a client connects to the `lws-webrtc` WebSocket endpoint, the server responds with an SDP offer containing the supported codecs (H.264, AV1, Opus) and negotiates the WebRTC UDP data path transparently.