From 94274656d5d7366b24e37ccc9f77cff251c99676 Mon Sep 17 00:00:00 2001 From: Dennis Juhler Aagaard Date: Fri, 25 Sep 2026 10:58:15 +0200 Subject: [PATCH 1/3] docs: switch app UI and user docs to English --- README.md | 48 ++++++------ stelloauth/CHANGELOG.md | 13 ++-- stelloauth/DOCS.md | 129 ++++++++++++++++---------------- stelloauth/README.md | 12 +-- stelloauth/translations/da.yaml | 12 +-- stelloauth/translations/en.yaml | 2 +- tests/test_addon_metadata.py | 36 ++++----- 7 files changed, 129 insertions(+), 123 deletions(-) diff --git a/README.md b/README.md index 897a360..5a6c764 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Stelloauth for Home Assistant -En Home Assistant-app (tidligere kaldet add-on), som kører Stelloauth og -CloakBrowser lokalt til OAuth-opsætning af integrationen Stellantis Vehicles. -Repositoryet understøtter `amd64` og `aarch64`. +A Home Assistant app (formerly known as an add-on) that runs Stelloauth and +CloakBrowser locally for OAuth setup of the Stellantis Vehicles integration. +The repository supports `amd64` and `aarch64`. ```text Home Assistant Core @@ -10,45 +10,45 @@ Home Assistant Core | POST http://0031621f-stelloauth:8080/worker v +--------------------------------------------------+ -| Én app / én container | +| One app / one container | | | -| Stelloauth 0.0.0.0:8080 | +| Stelloauth 0.0.0.0:8080 | | | | | | CDP http://127.0.0.1:9222 | | v | -| CloakBrowser 127.0.0.1:9222 | +| CloakBrowser 127.0.0.1:9222 | +--------------------------------------------------+ ``` -Én app giver de to processer samme Supervisor-livscyklus og holder -CloakBrowsers CDP-port på containerens loopback-interface. Appen 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. +Running both processes in one app gives them the same Supervisor lifecycle and +keeps CloakBrowser's CDP port on the container's loopback interface. The app +builds locally from source because the CloakBrowser Binary License does not +allow this repository to redistribute a derived image containing the +proprietary CloakBrowser binary. No prebuilt images are published. ## Installation -1. Gå til **Indstillinger → Apps → Installér app → ⋮ → Repositorier**, og tilføj +1. Go to **Settings → Apps → Install app → ⋮ → Repositories** and add `https://git.radixadm.dk/dennis/homeassistant-stelloauth-addon.git`. -2. Installér **Stelloauth**, aktivér **Start ved opstart** og **Watchdog**, og - start appen. -3. Følg den fulde vejledning i [stelloauth/DOCS.md](stelloauth/DOCS.md). +2. Install **Stelloauth**, enable **Start on boot** and **Watchdog**, then start + the app. +3. Follow the complete guide in [stelloauth/DOCS.md](stelloauth/DOCS.md). -## Fastlåste upstream-kilder +## Pinned upstream sources -| Komponent | Version | Commit / OCI index digest | +| Component | 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` | +| 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. +The Dockerfile and patches define the build. Supervisor downloads the official +CloakBrowser image and builds a local image for internal use only. -## Licens +## License -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. +The repository's original work is licensed under the MIT License; see +[LICENSE](LICENSE). The proprietary CloakBrowser binary is not included. It +remains subject to the separate **CloakBrowser Binary License**. diff --git a/stelloauth/CHANGELOG.md b/stelloauth/CHANGELOG.md index 68a5c95..37614ad 100644 --- a/stelloauth/CHANGELOG.md +++ b/stelloauth/CHANGELOG.md @@ -2,10 +2,11 @@ ## 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: +- Pin Stelloauth `v0.6.0` and CloakBrowser `0.5.10` to verified commits and + OCI digests. +- Add shared process supervision, readiness checks, watchdog support, and a + bounded shutdown. +- Document the internal Login service URL: `http://0031621f-stelloauth:8080/worker`. -- Begrænser CDP til loopback og hardener URL-validering, request-størrelse, - rate limiting og logredigering. +- Restrict CDP to loopback and harden URL validation, request size limits, + rate limiting, and log redaction. diff --git a/stelloauth/DOCS.md b/stelloauth/DOCS.md index 3b7a427..69e1e6d 100644 --- a/stelloauth/DOCS.md +++ b/stelloauth/DOCS.md @@ -1,15 +1,15 @@ -# Installation og drift +# Installation and operation -1. Gå til **Indstillinger → Apps → Installér app → ⋮ → Repositorier**, og tilføj - præcis +1. Go to **Settings → Apps → Install app → ⋮ → Repositories** and add this + exact URL: `https://git.radixadm.dk/dennis/homeassistant-stelloauth-addon.git`. -2. Installér **Stelloauth**, aktivér **Start ved opstart** og **Watchdog**, og - start derefter appen. Installationen bygger et lokalt image fra kilde til - den valgte `amd64`- eller `aarch64`-arkitektur. Repositoryet publicerer ikke - et prebuilt image. +2. Install **Stelloauth**, enable **Start on boot** and **Watchdog**, then start + the app. Home Assistant builds a local image from source for the selected + `amd64` or `aarch64` architecture. This repository does not publish a + prebuilt image. -3. Vent, til loggen i denne rækkefølge viser de fem faste readiness-beskeder: +3. Wait for the app log to show these five readiness messages in order: ```text Cleaning CloakBrowser profiles @@ -19,72 +19,75 @@ 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. +4. Keep the host port disabled during normal operation. For brief + troubleshooting, map `8080/tcp` to host port `8080`. Then check + `http://192.168.1.20:8080/` or the worker endpoint at + `http://192.168.1.20:8080/worker`. **Disable the port mapping again** when + you finish. The worker endpoint receives MyOpel details and has no separate + authentication. -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. +5. Open the **Stellantis Vehicles** integration's configuration and set + **Login service URL** to exactly + `http://0031621f-stelloauth:8080/worker`. The integration does not append + `/worker`, so include the full path. -6. Vælg **Brand: Opel** og **Country: DK**, og gennemfør derefter integrationens - OAuth-opsætning med dine MyOpel-oplysninger. +6. Select **Brand: Opel** and **Country: DK**, then complete the integration's + OAuth setup with your MyOpel details. -7. Appens tre muligheder er: +7. The app provides three options: - - `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. + - `queue_timeout`: how long a login attempt may wait for the single session. + - `rate_limit_count`: the maximum number of login attempts allowed in each + period. + - `rate_limit_duration`: the length of the login rate-limit period. - `CLOAK_MAX_SESSIONS` er fastlåst til én session, fordi CloakBrowsers gratis - niveau tillader ét samtidigt login. Samtidige forsøg bliver derfor køet. + `CLOAK_MAX_SESSIONS` is fixed at one because CloakBrowser's free tier allows + one concurrent login. Additional attempts wait in the queue. -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. +8. Each OAuth attempt gets a temporary profile under `/tmp/cloakserve`. + CloakBrowser removes inactive browser processes after 30 seconds, and the + process manager removes old profiles at startup. Credentials, cookies, + tokens, and OAuth codes are not stored in `/data`. CDP listens only on the + loopback address `127.0.0.1:9222`. Logs use fixed, redacted messages and do + not include email addresses, passwords, URLs, codes, or tokens. -9. De målte resultater fra den reelle `linux/amd64`-kørsel under Rosetta var: +9. Measurements from a real `linux/amd64` run under Rosetta: - - Image: 2,571,693,650 bytes (2.571 GB decimal / 2452.56 MiB). - - Dokumenteret Task 4-måling: 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. + - Image: 2,571,693,650 bytes (2.571 GB decimal / 2,452.56 MiB). + - Documented Task 4 measurement: 121.5 MiB. + - Stop time: about 9.3 seconds. + - The `amd64` runtime passed under Rosetta; the `aarch64` build passed. - Der er ikke gennemført et live MyOpel-login. - Login-flow RAM: not measured without real MyOpel credentials. + A successful live MyOpel login has not been verified. Login-flow memory + usage was not measured without real MyOpel credentials. -10. Fejlfinding og fjernelse: +10. Troubleshooting and removal: - - Mangler en readiness-besked, så se efter timeout: CloakBrowser har 60 - sekunder og Stelloauth 30 sekunder. Ret årsagen og genstart appen. - - 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 → Apps → Stelloauth → Afinstallér**. - Supervisor stopper containeren og fjerner appens lokale data. Fjern også - repositoryet via **Indstillinger → Apps → Installér app → ⋮ → - Repositorier**, hvis det ikke længere bruges. + - If a readiness message is missing, check for a timeout. CloakBrowser has + 60 seconds and Stelloauth has 30 seconds. Fix the cause, then restart the + app. + - An invalid or disallowed authorize URL returns HTTP `400`. + - Too many login attempts return HTTP `429`; wait for the configured + rate-limit period. + - If the repository URL or hostname changes, the Supervisor repository ID + and `0031621f-stelloauth` hostname also change. Calculate and use the new + internal URL. + - If disk space is low, check available space and remove unneeded images or + backups through Supervisor before building again. + - If the internal URL cannot be reached, use the temporary port check from + step 4, then disable the port mapping again. + - To remove the app, go to **Settings → Apps → Stelloauth → Uninstall**. + Supervisor stops the container and removes the app's local data. If you + no longer need the repository, remove it from **Settings → Apps → Install + app → ⋮ → Repositories** as well. -## Kilder og licenser +## Sources and licenses -App-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 +App version `0.1.0` builds Stelloauth `v0.6.0` from commit +`367d4f8c02a3b072c59142c49dffc129edc8548b` and uses the official CloakBrowser +`0.5.10` image at 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. +The repository's original files and patches are licensed under the MIT License. +The proprietary CloakBrowser binary remains subject to the separate +**CloakBrowser Binary License**. It is not licensed under MIT or redistributed +by this repository. diff --git a/stelloauth/README.md b/stelloauth/README.md index d51a0c6..ef711a7 100644 --- a/stelloauth/README.md +++ b/stelloauth/README.md @@ -1,10 +1,10 @@ # Stelloauth -Lokal OAuth-worker til integrationen Stellantis Vehicles. Appen bygger -Stelloauth `v0.6.0` og CloakBrowser `0.5.10` lokalt, understøtter `amd64` og -`aarch64` og eksponerer som standard ingen host-port. +A local OAuth worker for the Stellantis Vehicles integration. This app builds +Stelloauth `v0.6.0` and CloakBrowser `0.5.10` locally, supports `amd64` and +`aarch64`, and exposes no host port by default. -Se [den fulde installations- og fejlfindingsvejledning](DOCS.md). +See the [installation and troubleshooting guide](DOCS.md). -CloakBrowsers binær er under den separate CloakBrowser Binary License og er -ikke omfattet af repositoryets MIT-licens. +The CloakBrowser binary is covered by the separate CloakBrowser Binary License, +not by this repository's MIT License. diff --git a/stelloauth/translations/da.yaml b/stelloauth/translations/da.yaml index 894559e..c8f8060 100644 --- a/stelloauth/translations/da.yaml +++ b/stelloauth/translations/da.yaml @@ -1,10 +1,10 @@ configuration: queue_timeout: - name: Køventetid - description: Angiver hvor længe et loginforsøg må vente i køen. + name: Queue timeout + description: Sets how long a login attempt may wait in the queue. rate_limit_count: - name: Loginforsøg - description: Angiver det maksimale antal loginforsøg i hver periode. + name: Login attempts + description: Sets the maximum number of login attempts in each period. rate_limit_duration: - name: Rate limit-periode - description: Angiver periodens længde for begrænsning af loginforsøg. + name: Rate limit period + description: Sets the length of the login attempt rate-limit period. diff --git a/stelloauth/translations/en.yaml b/stelloauth/translations/en.yaml index 337eb73..c8f8060 100644 --- a/stelloauth/translations/en.yaml +++ b/stelloauth/translations/en.yaml @@ -7,4 +7,4 @@ configuration: description: Sets the maximum number of login attempts in each period. rate_limit_duration: name: Rate limit period - description: Sets the length of the login attempt rate limit period. + description: Sets the length of the login attempt rate-limit period. diff --git a/tests/test_addon_metadata.py b/tests/test_addon_metadata.py index 323e131..201ac7b 100644 --- a/tests/test_addon_metadata.py +++ b/tests/test_addon_metadata.py @@ -55,51 +55,53 @@ def test_user_guide_documentation_contract() -> None: documentation = (ROOT / "stelloauth/DOCS.md").read_text(encoding="utf-8") for required_text in ( REPOSITORY_URL, - "Indstillinger → Apps → Installér app → ⋮ →", - "Installér **Stelloauth**", - "aktivér **Start ved opstart** og **Watchdog**", + "Settings → Apps → Install app → ⋮ → Repositories", + "Install **Stelloauth**", + "enable **Start on boot** and **Watchdog**", "http://0031621f-stelloauth:8080/worker", "http://192.168.1.20:8080/worker", "Brand: Opel", "Country: DK", - "Image: 2,571,693,650 bytes (2.571 GB decimal / 2452.56 MiB).", - "Dokumenteret Task 4-måling: 121,5 MiB.", - "Stop: cirka 9.3 sekunder.", - "approximately 4 GB free", - "Der er ikke gennemført et live MyOpel-login.", - "Login-flow RAM: not measured without real MyOpel credentials.", - "Fjernelse sker i **Indstillinger → Apps → Stelloauth → Afinstallér**.", + "Image: 2,571,693,650 bytes (2.571 GB decimal / 2,452.56 MiB).", + "Documented Task 4 measurement: 121.5 MiB.", + "Stop time: about 9.3 seconds.", + "A successful live MyOpel login has not been verified.", + "Login-flow memory usage was not measured without real MyOpel credentials.", + "**Settings → Apps → Stelloauth → Uninstall**", ): assert required_text in documentation - assert "deaktivér porttilknytningen igen" in documentation - assert "Seneste idle RAM" not in documentation - assert "Tilføjelser" not in documentation - assert "Tilføjelsesbutik" not in documentation + assert "Disable the port mapping again" in documentation + assert "approximately 4 GB free" not in documentation + assert "successful HAOS installation has not been verified" not in documentation def test_root_readme_repository_source_and_license_facts() -> None: readme = (ROOT / "README.md").read_text(encoding="utf-8") for required_text in ( REPOSITORY_URL, - "Indstillinger → Apps → Installér app → ⋮ → Repositorier", + "Settings → Apps → Install app → ⋮ → Repositories", "v0.6.0", "367d4f8c02a3b072c59142c49dffc129edc8548b", "0.5.10", "f04c23da285b3b3d3cf10c8f9d282e7adc1d52ce", "CloakBrowser Binary License", - "MIT-licenseret", + "licensed under the MIT License", ): assert required_text in readme - assert "Tilføjelsesbutik" not in readme + assert "Indstillinger" not in readme + assert "Installér" not in readme def test_translations_cover_every_option() -> None: keys = set(load_yaml("stelloauth/config.yaml")["options"]) + translations = {} for language in ("da", "en"): translation = load_yaml(f"stelloauth/translations/{language}.yaml") assert set(translation["configuration"]) == keys + translations[language] = translation["configuration"] for entry in translation["configuration"].values(): assert set(entry) == {"name", "description"} assert all(isinstance(value, str) and value.strip() for value in entry.values()) + assert translations["da"] == translations["en"] def test_dockerfile_uses_approved_pins_and_builds_patched_stelloauth() -> None: From 602cbe93406152d6974cc7c69d4bad6d8d4d377a Mon Sep 17 00:00:00 2001 From: Dennis Juhler Aagaard Date: Fri, 25 Sep 2026 12:27:55 +0200 Subject: [PATCH 2/3] docs: clarify the MyOpel security PIN --- README.md | 4 ++++ stelloauth/DOCS.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/README.md b/README.md index 5a6c764..f892538 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,10 @@ proprietary CloakBrowser binary. No prebuilt images are published. the app. 3. Follow the complete guide in [stelloauth/DOCS.md](stelloauth/DOCS.md). +When the integration asks for a security PIN, enter the four-digit PIN you +chose when activating Remote Control in the MyOpel app. MyOpel does not send +you a new PIN; the SMS verification code is separate. + ## Pinned upstream sources | Component | Version | Commit / OCI index digest | diff --git a/stelloauth/DOCS.md b/stelloauth/DOCS.md index 69e1e6d..d0a04a8 100644 --- a/stelloauth/DOCS.md +++ b/stelloauth/DOCS.md @@ -34,6 +34,10 @@ 6. Select **Brand: Opel** and **Country: DK**, then complete the integration's OAuth setup with your MyOpel details. + When asked for a security PIN, enter the four-digit PIN you chose when + activating Remote Control in the MyOpel app. Do not wait for MyOpel to send + you a new PIN; the SMS verification code is separate. + 7. The app provides three options: - `queue_timeout`: how long a login attempt may wait for the single session. From 5844fab1660a3f6eb4f2544f12b31a24300cd5c2 Mon Sep 17 00:00:00 2001 From: Dennis Juhler Aagaard Date: Fri, 25 Sep 2026 12:31:31 +0200 Subject: [PATCH 3/3] docs: remove outdated live login disclaimer --- stelloauth/DOCS.md | 3 --- tests/test_addon_metadata.py | 2 -- 2 files changed, 5 deletions(-) diff --git a/stelloauth/DOCS.md b/stelloauth/DOCS.md index d0a04a8..f79e275 100644 --- a/stelloauth/DOCS.md +++ b/stelloauth/DOCS.md @@ -62,9 +62,6 @@ - Stop time: about 9.3 seconds. - The `amd64` runtime passed under Rosetta; the `aarch64` build passed. - A successful live MyOpel login has not been verified. Login-flow memory - usage was not measured without real MyOpel credentials. - 10. Troubleshooting and removal: - If a readiness message is missing, check for a timeout. CloakBrowser has diff --git a/tests/test_addon_metadata.py b/tests/test_addon_metadata.py index 201ac7b..4f6d229 100644 --- a/tests/test_addon_metadata.py +++ b/tests/test_addon_metadata.py @@ -65,8 +65,6 @@ def test_user_guide_documentation_contract() -> None: "Image: 2,571,693,650 bytes (2.571 GB decimal / 2,452.56 MiB).", "Documented Task 4 measurement: 121.5 MiB.", "Stop time: about 9.3 seconds.", - "A successful live MyOpel login has not been verified.", - "Login-flow memory usage was not measured without real MyOpel credentials.", "**Settings → Apps → Stelloauth → Uninstall**", ): assert required_text in documentation