diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..b817806 --- /dev/null +++ b/.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 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..feafe7a --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..5dccc56 --- /dev/null +++ b/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. diff --git a/stelloauth/CHANGELOG.md b/stelloauth/CHANGELOG.md new file mode 100644 index 0000000..68a5c95 --- /dev/null +++ b/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. diff --git a/stelloauth/DOCS.md b/stelloauth/DOCS.md new file mode 100644 index 0000000..6646779 --- /dev/null +++ b/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. diff --git a/stelloauth/README.md b/stelloauth/README.md new file mode 100644 index 0000000..8186dd1 --- /dev/null +++ b/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. diff --git a/tests/test_addon_metadata.py b/tests/test_addon_metadata.py index d38aa47..6d7b7ed 100644 --- a/tests/test_addon_metadata.py +++ b/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"):