Add TLS to WebAPI (again)

.gitignore

@@ -13,3 +13,4 @@ package/
 **/build/
 TODO.txt
 DESIGN.txt
+.vscode/

.vscode/settings.json

@@ -3,10 +3,19 @@
         "libsysinspect",
         "Sysinspect"
     ],
+    "python.defaultInterpreterPath": "/usr/bin/python3",
     "files.associations": {
         "*.cfg": "yaml"
     },
     "makefile.configureOnOpen": false,
+    "esbonio.sphinx.confDir": "${workspaceFolder}/docs",
+    "esbonio.sphinx.srcDir": "${workspaceFolder}/docs",
     "python-envs.defaultEnvManager": "ms-python.python:system",
-    "python-envs.pythonProjects": []
-}
+    "python-envs.pythonProjects": [],
+    "esbonio.sphinx.pythonCommand": {
+        "command": [
+            "/usr/bin/python3"
+        ],
+        "cwd": "${workspaceFolder}"
+    }
+}

Makefile

@@ -4,7 +4,7 @@ include Makefile.in
 
 .PHONY: build devel all all-devel modules modules-dev modules-dist-devel modules-refresh-devel clean check fix setup \
 	musl-aarch64-dev musl-aarch64 musl-x86_64-dev musl-x86_64 \
-	stats man test test-core test-modules test-sensors test-integration tar
+	stats man test test-core test-modules test-sensors test-integration tar dev-tls
 
 setup:
 	$(call deps)
@@ -90,20 +90,22 @@ stats:
 man:
 	pandoc --standalone --to man docs/manpages/sysinspect.8.md -o docs/manpages/sysinspect.8
 
-test: setup
-	CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run --workspace $(PLATFORM_WORKSPACE_EXCLUDES) --test-threads $(TEST_RUN_THREADS)
+dev-tls:
+	./scripts/dev-tls.sh
 
+test: setup
+	@CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run --workspace $(PLATFORM_WORKSPACE_EXCLUDES) --test-threads $(TEST_RUN_THREADS)
 test-core: setup
-	CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(foreach pkg,$(CORE_PACKAGE_SPECS),-p $(pkg)) --lib --bins --test-threads $(TEST_RUN_THREADS)
+	@CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(foreach pkg,$(CORE_PACKAGE_SPECS),-p $(pkg)) --lib --bins --test-threads $(TEST_RUN_THREADS)
 
 test-modules: setup
-	CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(foreach pkg,$(MODULE_PACKAGE_SPECS),-p $(pkg)) --bins --test-threads $(TEST_RUN_THREADS)
+	@CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(foreach pkg,$(MODULE_PACKAGE_SPECS),-p $(pkg)) --bins --test-threads $(TEST_RUN_THREADS)
 
 test-sensors: setup
-	CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(foreach pkg,$(SENSOR_PACKAGE_SPECS),-p $(pkg)) --lib --bins --test-threads $(TEST_RUN_THREADS)
+	@CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(foreach pkg,$(SENSOR_PACKAGE_SPECS),-p $(pkg)) --lib --bins --test-threads $(TEST_RUN_THREADS)
 
 test-integration: setup
-	CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(INTEGRATION_TEST_TARGETS) --test-threads $(TEST_RUN_THREADS)
+	@CARGO_BUILD_JOBS=$(TEST_BUILD_JOBS) cargo nextest run $(INTEGRATION_TEST_TARGETS) --test-threads $(TEST_RUN_THREADS)
 
 tar:
 	# Cleanup

docs/apidoc/overview.rst

@@ -1,18 +1,65 @@
 Web API
 =======
 
-This section provides an overview of the Web API for SysInspect, including its structure, endpoints, and usage.
+This section provides an overview of the Web API for SysInspect, including its
+HTTPS/TLS access pattern, endpoints, and request flow.
 
 Accessing the Documentation
 ---------------------------
 
-The Web API is automatically documented using Swagger, which provides a user-friendly interface to explore the available endpoints
-and their parameters. You can access the Swagger UI at the following URL:
+The Web API is automatically documented using Swagger, which provides a
+user-friendly interface to explore the available endpoints and their
+parameters. You can access the Swagger UI at:
 
-```
-http://<your-server-address>:4202/doc/
-```
+``https://<your-server-address>:4202/doc/``
 
-This interface, running on default port **4202**, allows you to interact with the API, view the available endpoints,
-and test them directly from your browser. You can change the port and API version in the general ``sysinspect.conf``
-configuration file.
+This interface runs on default port **4202**.
+
+The embedded Web API only starts when TLS is configured correctly under
+``api.tls.*`` in ``sysinspect.conf``.
+
+Authentication And Requests
+---------------------------
+
+The Web API uses:
+
+- HTTPS/TLS for transport protection
+- bearer tokens for authentication
+- plain JSON request and response bodies
+
+Typical flow:
+
+1. ``POST /api/v1/authenticate`` with JSON credentials
+2. receive ``access_token``
+3. call later endpoints with ``Authorization: Bearer <token>``
+
+Example authentication request body:
+
+.. code-block:: json
+
+   {
+     "username": "operator",
+     "password": "secret"
+   }
+
+Example query request body:
+
+.. code-block:: json
+
+   {
+     "model": "cm/file-ops",
+     "query": "*",
+     "traits": "",
+     "mid": "",
+     "context": {
+       "reason": "manual-run"
+     }
+   }
+
+Related Material
+----------------
+
+- :doc:`../global_config`
+- :doc:`../genusage/operator_security`
+- ``examples/transport-fixtures/webapi_auth_request.json``
+- ``examples/transport-fixtures/webapi_query_request.json``

docs/conf.py

@@ -1,3 +1,9 @@
+"""Sphinx configuration for the Sysinspect documentation."""
+
+from __future__ import annotations
+
+# pylint: disable=invalid-name,redefined-builtin
+
 project = "Sysinspect"
 copyright = "2026, Bo Maryniuk"
 author = "Bo Maryniuk"