docs: add installation and maintenance guide

.gitea/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+"on":
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38
+        with:
+          python-version: "3.12"
+          cache: pip
+      - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32
+        with:
+          go-version: "1.27.1"
+      - name: Install test dependencies
+        run: python -m pip install --requirement requirements-dev.txt
+      - name: Validate metadata, patches, and process manager
+        run: pytest -q
+      - name: Build amd64 image
+        run: docker build --build-arg BUILD_ARCH=amd64 --tag homeassistant-stelloauth-addon:test stelloauth
+      - name: Exercise runtime
+        run: SKIP_BUILD=1 tests/test_runtime.sh

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dennis / Radix ApS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,59 @@
+# Stelloauth for Home Assistant
+
+Et Home Assistant custom add-on, som kører Stelloauth og CloakBrowser lokalt til
+OAuth-opsætning af integrationen Stellantis Vehicles. Repositoryet understøtter
+`amd64` og `aarch64`.
+
+```text
+Home Assistant Core
+        |
+        | POST http://0031621f-stelloauth:8080/worker
+        v
++--------------------------------------------------+
+| Ét add-on / én container                         |
+|                                                  |
+|  Stelloauth 0.0.0.0:8080                        |
+|          |                                       |
+|          | CDP http://127.0.0.1:9222             |
+|          v                                       |
+|  CloakBrowser 127.0.0.1:9222                    |
++--------------------------------------------------+
+```
+
+Én add-on giver de to processer samme Supervisor-livscyklus og holder
+CloakBrowsers CDP-port på containerens loopback-interface. Add-onen bygges
+lokalt fra kilde, fordi CloakBrowser Binary License ikke tillader, at dette
+repository genudgiver en afledt image med den proprietære CloakBrowser-binær.
+Der publiceres derfor ingen prebuilt images.
+
+## Installation
+
+1. Tilføj
+   `https://git.radixadm.dk/dennis/homeassistant-stelloauth-addon.git` som
+   repository i Home Assistants Tilføjelsesbutik.
+2. Installér **Stelloauth**, aktivér **Start ved opstart** og **Watchdog**, og
+   start add-onen.
+3. Følg den fulde vejledning i [stelloauth/DOCS.md](stelloauth/DOCS.md).
+
+HAOS-installation er ikke gennemført eller påstået som valideret. Målmaskinen
+havde ved inspektionen approximately 4 GB free, mens det lokalt byggede image
+fyldte 2.571 GB; frigør om nødvendigt mere diskplads før installation.
+
+## Fastlåste upstream-kilder
+
+| Komponent | Version | Commit / OCI index digest |
+| --- | --- | --- |
+| Stelloauth | `v0.6.0` | `367d4f8c02a3b072c59142c49dffc129edc8548b` |
+| Stelloauth image contract | `v0.6.0` | `sha256:51b2194ec9b80cc484d11c016ec5436a12161277a493afdab7078959966d5aa9` |
+| CloakBrowser | `0.5.10` | `f04c23da285b3b3d3cf10c8f9d282e7adc1d52ce` / `sha256:2ed5b2d047cbdde22cde7ef1a796526c716aadaa5bccbe1db5ade49282b64a76` |
+| Go-builder | `1.27.1-bookworm` | `sha256:69a7b9788769bec032d238959b61854e9ae87f57be9029ec04e9885fabf99195` |
+| Stellantis Vehicles | `2026.9.4` | `9e0ef96f8fe478af291da4c38c923ada78d0ebf6` |
+
+Dockerfile og patches er build-opskriften. Supervisor henter det officielle
+CloakBrowser-image og bygger alene et lokalt image til intern brug.
+
+## Licens
+
+Repositoryets eget arbejde er MIT-licenseret; se [LICENSE](LICENSE). Dette
+omfatter ikke CloakBrowsers proprietære binær. Den er fortsat omfattet af den
+separate **CloakBrowser Binary License** og redistribueres ikke af repositoryet.

stelloauth/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Fastlåser Stelloauth `v0.6.0` og CloakBrowser `0.5.10` til verificerede
+  commits og OCI-digests.
+- Tilføjer fælles procesovervågning, readiness, watchdog og begrænset shutdown.
+- Dokumenterer intern Login service URL:
+  `http://0031621f-stelloauth:8080/worker`.
+- Begrænser CDP til loopback og hardener URL-validering, request-størrelse,
+  rate limiting og logredigering.

stelloauth/DOCS.md

@@ -0,0 +1,88 @@
+# Installation og drift
+
+1. Gå til **Indstillinger → Tilføjelser → Tilføjelsesbutik → ⋮ →
+   Repositorier**, og tilføj præcis
+   `https://git.radixadm.dk/dennis/homeassistant-stelloauth-addon.git`.
+
+2. Installér **Stelloauth**, aktivér **Start ved opstart** og **Watchdog**, og
+   start derefter add-onen. Installationen bygger et lokalt image fra kilde til
+   den valgte `amd64`- eller `aarch64`-arkitektur. Repositoryet publicerer ikke
+   et prebuilt image.
+
+3. Vent, til loggen i denne rækkefølge viser de fem faste readiness-beskeder:
+
+   ```text
+   Cleaning CloakBrowser profiles
+   Starting CloakBrowser
+   CloakBrowser ready
+   Starting Stelloauth
+   Stelloauth listening on 0.0.0.0:8080
+   ```
+
+4. Behold host-porten deaktiveret i normal drift. Ved kortvarig fejlfinding kan
+   `8080/tcp` tilknyttes host-port `8080`. Kontrollér derefter
+   `http://192.168.1.20:8080/` eller worker-endpointet
+   `http://192.168.1.20:8080/worker`, og **deaktivér porttilknytningen igen**,
+   når kontrollen er færdig. Worker-endpointet modtager MyOpel-oplysninger og
+   har ingen egen autentificering.
+
+5. Åbn konfigurationen af **Stellantis Vehicles**. Angiv præcis
+   `http://0031621f-stelloauth:8080/worker` som **Login service URL**.
+   Integrationen tilføjer ikke `/worker`; hele stien skal derfor stå i feltet.
+
+6. Vælg **Brand: Opel** og **Country: DK**, og gennemfør derefter integrationens
+   OAuth-opsætning med dine MyOpel-oplysninger.
+
+7. Add-onens tre muligheder er:
+
+   - `queue_timeout`: hvor længe et loginforsøg må vente på den ene session.
+   - `rate_limit_count`: højeste antal loginforsøg i hver periode.
+   - `rate_limit_duration`: længden af rate limit-perioden.
+
+   `CLOAK_MAX_SESSIONS` er fastlåst til én session, fordi CloakBrowsers gratis
+   niveau tillader ét samtidigt login. Samtidige forsøg bliver derfor køet.
+
+8. Hvert OAuth-forsøg får en midlertidig profil under `/tmp/cloakserve`.
+   CloakBrowser rydder inaktive browserprocesser efter 30 sekunder, og
+   process manageren rydder gamle profiler ved opstart. Credentials, cookies,
+   tokens og OAuth-koder gemmes ikke i `/data`. CDP lytter kun på loopback
+   `127.0.0.1:9222`, og logs bruger faste, redigerede hændelser uden email,
+   passwords, URLs, koder eller tokens.
+
+9. De målte resultater fra den reelle `linux/amd64`-kørsel under Rosetta var:
+
+   - Image: 2,571,693,650 bytes (2.571 GB decimal / 2452.56 MiB).
+   - Seneste idle RAM: 121.5 MiB.
+   - Stop: cirka 9.3 sekunder.
+   - `amd64` runtime bestod under Rosetta; `aarch64` build bestod.
+   - Mål-HAOS havde ved inspektionen approximately 4 GB free. Den knappe
+     plads sammenholdt med image- og build-lag kan forhindre installationen;
+     frigør plads først. Der er ikke verificeret en vellykket HAOS-installation.
+
+   Login-flow RAM: not measured without real MyOpel credentials.
+
+10. Fejlfinding og fjernelse:
+
+    - Mangler en readiness-besked, så se efter timeout: CloakBrowser har 60
+      sekunder og Stelloauth 30 sekunder. Ret årsagen og genstart add-onen.
+    - Et ugyldigt eller ikke-tilladt authorize-URL giver HTTP `400`.
+    - For mange loginforsøg giver HTTP `429`; vent den konfigurerede periode.
+    - Hvis repository-URL eller hostname ændres, ændres Supervisor-repository-ID
+      og dermed `0031621f-stelloauth`. Beregn og brug den nye interne URL.
+    - Ved disk pressure: kontrollér fri plads og fjern unødvendige images eller
+      backups via de normale Supervisor-funktioner før et nyt build.
+    - Hvis den interne URL ikke kan nås, brug kun den midlertidige portkontrol
+      fra trin 4 og deaktivér porttilknytningen bagefter.
+    - Fjernelse sker i **Indstillinger → Tilføjelser → Stelloauth → Afinstallér**.
+      Supervisor stopper containeren og fjerner add-onens lokale data; fjern
+      også repositoryet fra Tilføjelsesbutikken, hvis det ikke længere bruges.
+
+## Kilder og licenser
+
+Add-on-version `0.1.0` bygger Stelloauth `v0.6.0` fra commit
+`367d4f8c02a3b072c59142c49dffc129edc8548b` og bruger det officielle
+CloakBrowser `0.5.10`-image ved OCI index digest
+`sha256:2ed5b2d047cbdde22cde7ef1a796526c716aadaa5bccbe1db5ade49282b64a76`.
+Repositoryets egne filer og patches er MIT-licenserede. CloakBrowsers
+proprietære binær er fortsat under den separate **CloakBrowser Binary License**;
+den er ikke MIT-licenseret eller redistribueret af dette repository.

stelloauth/README.md

@@ -0,0 +1,10 @@
+# Stelloauth
+
+Lokal OAuth-worker til integrationen Stellantis Vehicles. Add-onen bygger
+Stelloauth `v0.6.0` og CloakBrowser `0.5.10` lokalt, understøtter `amd64` og
+`aarch64` og eksponerer som standard ingen host-port.
+
+Se [den fulde installations- og fejlfindingsvejledning](DOCS.md).
+
+CloakBrowsers binær er under den separate CloakBrowser Binary License og er
+ikke omfattet af repositoryets MIT-licens.

tests/test_addon_metadata.py

@@ -50,6 +50,27 @@ def test_repository_hostname_derivation() -> None:
     assert repository_id == "0031621f"
     assert f"{repository_id}-stelloauth" == "0031621f-stelloauth"
 
+
+def test_documentation_contract() -> None:
+    documentation = "\n".join(
+        (ROOT / path).read_text(encoding="utf-8")
+        for path in ("README.md", "stelloauth/README.md", "stelloauth/DOCS.md")
+    )
+    for required_text in (
+        REPOSITORY_URL,
+        "http://0031621f-stelloauth:8080/worker",
+        "http://192.168.1.20:8080/worker",
+        "Brand: Opel",
+        "Country: DK",
+        "v0.6.0",
+        "0.5.10",
+        "CloakBrowser Binary License",
+        "approximately 4 GB free",
+        "Login-flow RAM: not measured without real MyOpel credentials.",
+    ):
+        assert required_text in documentation
+    assert "deaktivér porttilknytningen igen" in documentation
+
 def test_translations_cover_every_option() -> None:
     keys = set(load_yaml("stelloauth/config.yaml")["options"])
     for language in ("da", "en"):