LumaOps-Public/docs/SOURCE_AUDIT.md

# LumaOps source audit

Status: completed on 2026-07-14 against the imported OpenRGB 1.0rc3 source tree.

## Scope and method

The supplied archive was imported unchanged as commit `a15d499` and tagged
`upstream-openrgb-1.0rc3` before LumaOps work started. The audit covered the
build definition, command-line startup, SDK client/server implementation,
protocol structures, settings and profile persistence, plugin loading, Linux
hardware access, and the network-lighting controllers named in the project
brief.

The imported tree contains 2,237 tracked files, including 1,045 C++ sources,
943 headers, 37 Qt UI definitions, 189 controller directories, and 201 detector
implementations. OpenRGB vendors or embeds several dependencies, including
hidapi, libusb, mbedTLS, httplib, hueplusplus, libe131, mdns, and nlohmann JSON.

Files reviewed in detail include:

- `README.md`, `CONTRIBUTING.md`, `LICENSE`, and `OpenRGB.pro`
- all required documents under `Documentation/`
- `NetworkServer.*`, `NetworkClient.*`, and `NetworkProtocol.*`
- `PluginManager.*`, `SettingsManager.*`, and `ProfileManager.*`
- `cli.*`, `ResourceManager.*`, and platform startup sources
- the controller and detector sources for the network protocols listed below

## Confirmed versions

| Component | Version | Source of truth |
| --- | --- | --- |
| OpenRGB | 1.0rc3 | `OpenRGB.pro` sets `SUFFIX = 1.0rc3` |
| SDK protocol | 5 | `NetworkProtocol.h` sets `OPENRGB_SDK_PROTOCOL_VERSION 5` |
| Plugin API | 4 | `OpenRGBPluginInterface.h` sets `OPENRGB_PLUGIN_API_VERSION 4` |

The LumaOps adapter must negotiate protocol 5. A peer that returns a different
version is reported as incompatible instead of silently interpreting a newer or
older packet layout.

## Licensing and contribution constraints

OpenRGB is distributed under GPL-2.0. The source files commonly use the
`GPL-2.0-or-later` SPDX identifier. All upstream license files, copyright
notices, and SPDX headers remain intact. LumaOps is part of the combined work
and is therefore also published under GPL-2.0-or-later in this repository.

`CONTRIBUTING.md` makes the human contributor responsible for submitted code
and disallows AI authorship or co-authorship metadata. Commits use the existing
repository identity and do not add AI attribution trailers.

Anyone distributing a LumaOps image must make the corresponding source,
including the exact OpenRGB modifications and build instructions, available
under the GPL. Merely running the software privately does not trigger source
distribution obligations.

## Build and headless operation

### Upstream Linux build

`Documentation/Compiling.md` describes a qmake/Qt 5 build. The significant
Debian/Ubuntu build dependencies are Qt 5 development tools, a C++ toolchain,
pkg-config, libusb, hidapi, and mbedTLS. The upstream sequence is equivalent to:

```sh
mkdir build
cd build
qmake ../OpenRGB.pro
make -j"$(nproc)"
```

OpenRGB is still linked with Qt libraries in a headless build, but it creates a
`QApplication` only when the GUI flag is selected. It therefore runs without an
X11/Wayland display when started in server mode.

### Verified headless command

The CLI parser and platform startup code confirm this production command:

```sh
openrgb \
  --server \
  --server-host 127.0.0.1 \
  --server-port 6742 \
  --config /config/openrgb \
  --noautoconnect
```

The directory passed to `--config` must exist before startup. `--server-host`
must always be explicit because OpenRGB otherwise defaults to `0.0.0.0`.
`--nodetect` must not be supplied: it would defeat the required local hardware
inventory. Starting with no server/CLI action would select the graphical UI.

The Linux startup path initializes `ResourceManager`, starts the internal
server, waits for device detection, and then remains in
`WaitWhileServerOnline()`. There is one upstream gap relevant to containers:
SIGINT/SIGTERM handlers are registered only in the GUI startup branch. LumaOps
therefore carries a small isolated patch that installs the same shutdown handler
for headless server mode. This lets the supervisor stop OpenRGB cleanly instead
of relying on the operating system's abrupt default termination.

The production container must verify at runtime that port 6742 is listening on
loopback and must never publish or expose it through Docker.

## SDK protocol audit

The SDK is an unauthenticated binary TCP protocol. It is appropriate only as an
internal process boundary in the same container; it is not an internet or LAN
security boundary.

Packets start with a 16-byte header:

1. magic bytes `ORGB`;
2. 32-bit device index;
3. 32-bit packet ID;
4. 32-bit payload length.

The implementation serializes the protocol's integers and packed structures in
the native little-endian layout used by the x86_64 target. Notable request IDs
are controller count (`0`), controller data (`1`), protocol negotiation (`40`),
client name (`50`), device-list-changed (`100`), rescan (`140`), profile list and
operations (`150`-`153`), and plugin operations (`200`-`201`). Update requests
cover mode, device/zone/LED colours, custom mode, resizing zones, and segment
changes.

Protocol 5 adds zone flags, controller flags, effects-only zones, alternative
LED names, and segment-clear/add operations. The controller-data response is a
nested variable-length structure containing strings, modes, zones, segments,
LEDs, and colours. This makes strict bounds checking mandatory.

The internal adapter will enforce:

- exact-length reads and the `ORGB` magic value;
- protocol-5 negotiation before normal traffic;
- a configurable hard maximum packet size (default 16 MiB);
- bounded collection counts and bounded, NUL-terminated strings;
- controller, zone, LED, mode, speed, brightness, and colour validation;
- controller identity checks instead of trusting a stale device index;
- one serialized write queue plus per-device locks;
- connection and command timeouts, bounded reconnect backoff, and cancellation;
- no write side effects during inventory;
- safe handling of device-list change notifications and OpenRGB restarts.

The server source also checks controller indexes and validates declared payload
sizes for update packets. LumaOps performs the same checks before transmitting,
so malformed application input never reaches OpenRGB.

### Existing Python client evaluation

The current `openrgb-python` package was inspected at upstream commit
`dbbe58336268e273e2604f6f10b9e2f2003d6d84`. It still declares protocol version
4, does not implement the protocol-5 surface required by this release, does not
provide the required rescan request, and contains receive paths that use a
single unbounded socket read for a declared packet length. Its repository also
does not provide the parser/serialization test coverage required here.

Decision: LumaOps uses a small first-party SDK protocol-5 adapter behind a
connector interface. No other application layer imports packet structures.
This keeps the binary protocol auditable and lets tests replay captured and
synthetic packets without replacing the real production adapter.

## Settings, profiles, and plugins

On Linux, OpenRGB normally stores data under `$XDG_CONFIG_HOME/OpenRGB` or
`$HOME/.config/OpenRGB`. With the verified command above, all OpenRGB-owned
state is instead rooted at `/config/openrgb`:

| Data | Location |
| --- | --- |
| Main settings | `/config/openrgb/OpenRGB.json` |
| Normal profiles | `/config/openrgb/*.orp` |
| Controller size profile | `/config/openrgb/sizes.ors` |
| User plugins | `/config/openrgb/plugins/` |
| System plugins | build-time platform directory, normally `/usr/lib/openrgb/plugins` |

Profiles match controller identity fields rather than relying only on discovery
order. Profile deletion removes the corresponding profile file. Settings are
written directly as JSON and OpenRGB itself does not make an atomic backup, so
LumaOps backs up the OpenRGB directory together with its own data before
restores, migrations, or destructive maintenance.

Plugin enablement is stored in the `Plugins` section of `OpenRGB.json`. A plugin
must match Plugin API 4 exactly. User-supplied plugins execute native code in the
OpenRGB process and are therefore treated as trusted administrator extensions,
not as sandboxed add-ons.

Some network-controller configuration is also stored in `OpenRGB.json`. It can
include credentials such as a Philips Hue username/client key or Espurna API
key. `/config/openrgb` must therefore receive the same restrictive filesystem
permissions, backup handling, and diagnostic redaction as LumaOps secrets.

LumaOps state is deliberately separate under `/config/lumaops` and `/data` so
OpenRGB upstream files and application migrations have independent lifecycles.

## Existing OpenRGB network support

The audit distinguishes automatic discovery from controllers that are created
from manually saved settings even when their source class is named a detector.

| Family | Existing OpenRGB path | Transport and discovery notes |
| --- | --- | --- |
| DDP | DDP network controller | Manual target stored in settings; UDP, default port 4048 |
| E1.31/sACN | E1.31 controller | Manual unicast/multicast configuration; standard E1.31 UDP transport |
| Philips Hue | Hue controller via hueplusplus | Bridge discovery plus manual bridge data; REST/entertainment setup; username and client key are persistent secrets |
| Philips WiZ | WiZ controller | UDP port 38899 |
| Nanoleaf | Nanoleaf controller | HTTP API for setup/state and external-control UDP streaming; external port may be negotiated, with 60222 used by supported paths |
| LIFX | LIFX controller | LAN protocol over UDP port 56700 |
| Govee | Govee controller | LAN discovery multicast `239.255.255.250:4001`, local discovery port 4002, control UDP port 4003 |
| TP-Link Kasa | Kasa controller | Local TCP protocol on port 9999 |
| Yeelight | Yeelight controller | LAN discovery/manual target; TCP port 55443 |
| Espurna | Espurna controller | Manual IP/port/API key; HTTP-style API over TCP |
| Elgato lighting | Key Light and Light Strip controllers | Local HTTP/TCP API on port 9123 |

Host networking may be needed for broadcast, multicast, or mDNS discovery on an
Unraid host. Bridge networking remains the default. A host-network deployment
still binds the SDK to `127.0.0.1`; only the LumaOps web port is intended for LAN
access.

Native WLED and Home Assistant connectors remain outside OpenRGB and use the
same LumaOps capability model. Duplicate ownership is prevented by assigning
one management owner per physical device.

## Hardware access on Linux and Unraid

### USB

OpenRGB needs access to hidraw/libusb devices. A normal Linux installation can
install generated udev rules at `/usr/lib/udev/rules.d/60-openrgb.rules`. In a
container, the host kernel still owns udev and permissions. The supported
deployment passes `/dev/bus/usb` explicitly and, where needed, selected hidraw
devices. Running the whole container as privileged or mounting all of `/dev` is
not the production default.

### SMBus/I2C

The host loads `i2c-dev` plus its chipset driver, commonly `i2c-i801` on Intel
or `i2c-piix4` on AMD. Only discovered `/dev/i2c-*` nodes that are actually
needed are passed through. Some boards require vendor-specific modules; some
kernel/ACPI workarounds can be unsafe and are documented as diagnostics rather
than enabled automatically. SPD-related controllers can conflict with kernel
memory sensor drivers, so LumaOps does not unload modules or write to SMBus as
part of inventory.

### Serial devices

Optional serial controllers use individually mapped `/dev/ttyUSB*` or
`/dev/ttyACM*` devices. Their group/permission requirements remain host-specific.

The first-run inventory is read-only. Actual validation starts with one selected
device, a static low-intensity colour, and a low command frequency.

## Architectural conclusions

1. Preserve the upstream source layout and keep LumaOps under `lumaops/`,
   `docker/`, `docs/`, and `tests/`.
2. Carry only the documented headless signal patch and unambiguous HID-interface
   fallback in OpenRGB Core; keep all other policy, persistence, connectors, and UI
   work outside the core.
3. Build OpenRGB from the imported source in the production multi-stage image.
4. Run OpenRGB and FastAPI under a real init/supervisor; serve the built React
   application from FastAPI so only one web port is public.
5. Use an internal protocol-5 adapter for production and a clearly marked mock
   adapter only for tests and intentional development mode.
6. Store stable LumaOps UUIDs from a fingerprint of durable identity fields plus
   persisted identity aliases; never expose discovery order as identity.
7. Keep OpenRGB at `127.0.0.1:6742`, including under host networking, and reject
   non-loopback production configuration unless an administrator explicitly
   opts into the documented remote-endpoint risk.
8. Treat both `/config/openrgb` and `/config/lumaops` as sensitive persistent
   state and redact them from diagnostics.
9. Model connector capabilities generically so WLED, Home Assistant, MQTT,
   remote agents, and future protocols do not require brand-specific UI paths.

This audit clears the project to proceed with the LumaOps architecture and MVP
implementation while retaining OpenRGB 1.0rc3 as the actual hardware engine.