docs: add installation and maintenance guide

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.