Feature 17: API Deployment and Identity (#217)

Co-authored-by: dev_agent <17+dev_agent@code.cubecraftcreations.com>
Co-committed-by: dev_agent <17+dev_agent@code.cubecraftcreations.com>

api/README.md

@@ -0,0 +1,83 @@
+# NestQuest API
+
+Standalone FastAPI service owning the NestQuest database (Feature 16).
+Served with ``uvicorn --factory api.app:create_app``; configuration is
+environment-supplied (``api/config.py``) and every variable is required.
+
+## Runtime dependencies
+
+``api/requirements.txt`` is the API deployable's OWN dependency
+manifest (fastapi, uvicorn, pyjwt[crypto], httpx) — deliberately kept
+out of the integration's ``pyproject.toml`` dev group, which exists only
+so the monorepo test venv can run the API tests.
+
+## Container deployment (scaffold)
+
+The image is built from the repository ROOT context (the API loads the
+bundled domain core from ``custom_components/nestquest/core/`` by file
+location, so both trees must be in the build context):
+
+    docker build -t nestquest-api:latest .
+
+Run it with compose — the SQLite file lives on the named volume
+``nestquest-db`` so recreating the container keeps household data:
+
+    cp deploy/.env.example deploy/.env   # then fill in real values
+    docker compose -f deploy/compose.yaml up -d --build
+
+``deploy/.env`` is git-ignored and supplies the secrets (panel service
+token, Authentik OIDC settings); ``NESTQUEST_DB_PATH`` is fixed to
+``/var/lib/nestquest/nestquest.db`` by compose.
+
+The published port binds ``NESTQUEST_BIND_ADDRESS`` from
+``deploy/.env`` and defaults to ``127.0.0.1`` (localhost only). In
+production TLS is terminated by the shared Traefik reverse proxy,
+which serves ``https://nestquest.cubecraftlabs.com`` (Let's Encrypt,
+auto-renewed, HTTP redirected to HTTPS) and forwards to the API box
+on port 8080 — so on that box set ``NESTQUEST_BIND_ADDRESS`` to its
+LAN address (``10.60.1.14``). Traefik only allows
+``/api/v1/panel`` from the Home Assistant host. The full deployment,
+restore and verification procedure is in ``deploy/RUNBOOK.md``.
+
+## Continuous backup (Litestream)
+
+Compose also runs a ``litestream`` sidecar
+(``litestream/litestream:0.5.17``, config ``deploy/litestream.yml``).
+It mounts the same ``nestquest-db`` volume and continuously replicates
+``/var/lib/nestquest/nestquest.db`` over SFTP to the Synology NAS
+``CubeCraft-SRVR1`` (``joshua@10.60.1.50``), directory
+``/volume1/homes/Joshua/nestquest-backups`` (``/homes/Joshua/...`` in
+the NAS's chrooted SFTP view) — so the backup is outside the Docker
+host and its volume. A snapshot is taken daily and a week of
+snapshots plus incremental changes is retained; the NAS host key is
+pinned in the config.
+
+The SFTP login uses a dedicated keypair that lives only on the API
+box and is git-ignored. Create it once, before ``up``:
+
+    ssh-keygen -t ed25519 -N "" -C nestquest-litestream -f deploy/litestream_key
+
+then append ``restrict `` + the contents of ``deploy/litestream_key.pub``
+to ``joshua@10.60.1.50:~/.ssh/authorized_keys``. Compose mounts the
+private key read-only at ``/etc/litestream/sftp_key``. The sidecar runs
+as uid/gid 999 (the API's ``nestquest`` user), so give it the key:
+
+    sudo chown 999:999 deploy/litestream_key && chmod 600 deploy/litestream_key
+
+The sidecar needs WRITE access to the database volume: Litestream adds
+its own ``_litestream_seq``/``_litestream_lock`` tables to the database,
+writes the ``-wal``/``-shm`` files and checkpoints the WAL, and fails
+with "unable to open database file" on a read-only mount. That access
+is contained rather than removed — the sidecar runs as the non-root
+volume owner with a read-only root filesystem, ``no-new-privileges``
+and all Linux capabilities dropped.
+
+Check replication with
+``docker compose -f deploy/compose.yaml logs litestream`` or
+``docker compose -f deploy/compose.yaml exec litestream litestream ltx /var/lib/nestquest/nestquest.db``.
+To restore (high level): stop the ``api`` service, run
+``litestream restore -config /etc/litestream.yml -o <new path>
+/var/lib/nestquest/nestquest.db`` from a litestream container with the
+same mounts, verify the restored file, move it into place on the
+volume (removing any stale ``-wal``/``-shm`` files), and start ``api``
+again.

api/requirements.txt

@@ -0,0 +1,38 @@
+# Runtime dependency manifest for the NestQuest API deployable.
+#
+# The monorepo's pyproject.toml carries fastapi/uvicorn/pyjwt/httpx in
+# the INTEGRATION's dev group only (so the test venv can exercise the
+# API); they are deliberately NOT integration runtime dependencies.
+# Per that manifest's own comment, the API deployable declares its own
+# runtime dependencies HERE — this file is what the container image
+# installs (see the Dockerfile at the repository root).
+#
+# EXACT pins: the versions installed in the deployed image
+# (nestquest-api:latest on the API box, read with importlib.metadata),
+# so a rebuild resolves the same packages.  The four direct
+# dependencies come first; the rest is their resolved transitive
+# closure, pinned too so nothing floats.  The dev group's floors in
+# pyproject.toml are unchanged.  Bump deliberately, together with the
+# Dockerfile's digest-pinned base image.
+fastapi==0.141.1
+uvicorn==0.53.0
+pyjwt[crypto]==2.15.0
+httpx==0.28.1
+
+# Transitive dependencies of the above.
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.15.1
+certifi==2026.7.22
+cffi==2.1.1
+click==8.5.0
+cryptography==50.0.1
+h11==0.16.0
+httpcore==1.0.9
+idna==3.20
+pycparser==3.0
+pydantic==2.13.5
+pydantic_core==2.46.5
+starlette==1.7.0
+typing-inspection==0.4.4
+typing_extensions==4.16.0