Python/FastAPI strežnik za lastno Chrome razširitev: sprejema obiske, jih trajno shrani v SQLite in jih lahko opcijsko pošlje v zaseben Discord kanal prek webhooka.

URL-ji so lahko občutljivi. Uporabi samo na napravah, ki jih upravljaš, z jasnim obvestilom uporabnikom. Strežnika ne izpostavljaj neposredno internetu brez HTTPS in dodatne zaščite.

Zagon

cp .env.example .env
# V .env nastavi dolg, naključen API_TOKEN.
docker compose up -d --build
docker compose logs -f
curl http://127.0.0.1:8080/healthz

Privzeto posluša samo na 127.0.0.1:8080. Za dostop iz drugih naprav uporabi VPN (Tailscale/WireGuard) ali HTTPS reverse proxy. Ne odpiraj porta neposredno v internet.

API

POST /v1/visits, z glavo Authorization: Bearer TVOJ_API_TOKEN:

{
  "device_id": "otrok-prenosnik",
  "visits": [{
    "url": "https://example.com/clanek",
    "title": "Primer",
    "visit_time": "2026-10-06T18:50:00Z",
    "transition": "observed"
  }]
}

Odgovor 202 Accepted pomeni, da je paket zapisan v ./data/history.sqlite3. Podvojeni obiski se ne podvojijo.

Spletni pregledovalnik

Odpri http://127.0.0.1:8080/ in se prijavi z VIEWER_USERNAME ter VIEWER_PASSWORD iz .env. Pregledovalnik omogoča:

filter od/do (čas je UTC),
filter po napravi,
iskanje po domeni, naslovu ali URL-ju,
seznam do 500 zadnjih obiskov,
pregled unikatnih domen s številom obiskov in zadnjim obiskom.

Discord (neobvezno)

V .env nastavi DISCORD_WEBHOOK_URL. Najprej se zapis shrani v SQLite, nato se poskusi poslati Discordu. Neuspeh Discorda ne izbriše podatkov.

Nastavitev razširitve

Javni extension/config.js vsebuje javni privzeti collectorUrl, prazen apiToken in prazen deviceId. Za lokalno uporabo lahko nastaviš kopijo; za upravljane naprave uporabi Chrome managed policy spodaj. Razširitev arhivira in pošilja tudi URL-je prenosov, nikoli pa vsebine prenesenih datotek. Token naj ne konča v repozitoriju. manifest.json vsebuje široko dovoljenje za HTTP/HTTPS gostitelje zato, da lahko izbereš lasten API naslov; če želiš strožje dovoljenje, zamenjaj host_permissions samo s svojim HTTPS naslovom.

Objavljanje podpisane razširitve

Repozitorij in release asseti morajo biti javni ter anonimno dosegljivi prek HTTPS, sicer Chrome ne more preverjati posodobitev. V Gitei omogoči Actions runner z labelom ubuntu-latest. Workflow potrebuje najmanj contents: write; če Gitea tega ne preslika samodejno, mora imeti vgrajeni GITEA_TOKEN v nastavitvah repozitorija pravico za ustvarjanje releaseov in taga updates.

Gitea mora .crx servirati z Content-Type: application/x-chrome-extension; v konfiguracijo dodaj [repository.mimetype_mapping] z mapiranjem .crx = application/x-chrome-extension, ali enak header nastavi v reverse proxyju. Objavljalni skript pred objavo updates.xml anonimno preveri HTTP 200, CRX3 glavo in ta MIME tip.

Ustvari en RSA zasebni ključ v PEM obliki zunaj repozitorija, ga varno shrani in kot CRX_PRIVATE_KEY dodaj v repo Actions secrets (na primer tmpdir=$(mktemp -d) && openssl genrsa -out "$tmpdir/history-collector.pem" 2048 && chmod 600 "$tmpdir/history-collector.pem"). Ključa nikoli ne rotiraj: s tem bi se spremenil ID razširitve. Ob tagu vX.Y.Z ali vX.Y.Z.N, ki se mora ujemati z version v extension/manifest.json, workflow zgradi in preveri CRX3, ZIP, checksums, extension-id.txt in updates.xml. V verzionirani release objavi CRX/ZIP/checksums/ID, updates.xml pa v poseben prerelease/tag updates. ID dobiš iz extension-id.txt ali iz chrome://extensions pri podpisanem paketu.

Za bump spremeni manifest, commitaj in ustvari ustrezen tag, na primer git tag v1.0.1 && git push origin v1.0.1. V Windows Chromeu običajen off-store CRX potrebuje enterprise policy; brez podpisa auto-update ne deluje. Force-install policy uporabi:

ExtensionInstallForcelist = <EXTENSION_ID>;https://git.komelt.dev/komelt/history-collector/releases/download/updates/updates.xml

V ExtensionSettings lahko za isti ID nastaviš installation_mode: force_installed in isti update_url. Managed storage politika je na Windowsu pod HKLM\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\<EXTENSION_ID>\policy; nastavi vrednosti collectorUrl (na primer https://chrome.komelt.dev/v1/visits), apiToken in deviceId. Te vrednosti preglasijo javne privzetke in ostanejo prek posodobitev. V podpisanem paketu je brez managed policy oddaljeno pošiljanje na API neaktivno; lokalni Native Messaging arhiv pa še vedno deluje.

Token, ki je bil prej commitan v extension/config.js, je še vedno v Git zgodovini: nemudoma ga prekliči in zamenjaj. Nikoli ne objavljaj API skrivnosti v javnem CRX.

Windows native arhiv (neobvezno)

Repozitorij vključuje tudi Chrome razširitev in Windows Native Messaging host za lokalni, append-only arhiv obiskov v SQLite.

V Chromu odpri chrome://extensions, vklopi Developer mode, klikni Load unpacked in izberi mapo extension.
Kopiraj 32-znakovni ID razširitve.

V PowerShellu iz korena repozitorija zaženi:

powershell -ExecutionPolicy Bypass -File .\install-native-host.ps1 -ExtensionId TUKAJ_PRILEPI_ID

Lokalni arhiv se privzeto shrani v %USERPROFILE%\ChromeHistoryArchive\history.sqlite3. Za pošiljanje obiskov tudi na API uredi lokalni extension/config.js; vanj ne zapisuj tokena v commitu.