Kent
d6eb811ee5
Dagens «auth» var én delt PIN i et X-Pin-header, sammenlignet med !=, og
den sa ingenting om hvem som sendte et utrop – køen viste bare IP-adressen.
Crew har et eget adminpanel som skal bli identitetsleverandør.
Modellen er én datatype og én funksjon: Principal (hvem + roller +
rettigheter) og require(action), som enten gir deg den eller stopper
forespørselen. Handlinger: view, preview, announce, stop, clear.
Tre leverandører, prøvd i rekkefølge, alle valgfrie:
- pin X-Pin som før, men med hmac.compare_digest istedenfor ==. Rolle
admin som standard, så eksisterende oppsett oppfører seg likt.
Beholdt bevisst: den virker uten nett, og det er nettopp da man
trenger å rope ut noe.
- jwt Authorization: Bearer. HS256 med delt hemmelighet, eller
RS256/ES256 mot panelets JWKS. Krever exp – et token uten
utløpstid er en evig nøkkel. Roller fra et konfigurerbart claim,
som tåler liste, streng, kommaliste og punktsti.
- oidc Autorisasjonskode med PKCE. Discovery hentes først ved første
innlogging, så tjenesten starter selv om panelet er nede.
En leverandør er aktiv når den står i auth.providers *eller* når den er
ferdig konfigurert. Derfor slår ANNOUNCER_PIN=1234 alene fortsatt på PIN,
slik det har virket til nå. Er ingen aktiv, er alt åpent – som før.
/auth/token?t=<jwt> er broa mens panelet mangler OIDC: panelet lenker hit
med et kortlevd token, vi setter sesjonscookie. Ett klikk, ingen PIN.
Kontrakten panelet skal oppfylle står i docs/crew-integration.md.
401 betyr «vi vet ikke hvem du er, logg inn», 403 «vi vet hvem du er, men
rollen din får ikke dette». Et gyldig token uten roller gir 403, ikke 401 –
å logge inn på nytt ville ikke hjulpet.
Samtidig:
- /api/status er lukket bak «view». Den var åpen, og lekket både
meldingstekstene og IP-ene til alle som hadde sendt noe, til hvem som
helst som nådde porten. IP vises nå bare for den som har «clear»; alle
andre ser navnet.
- Køen og en revisjonslogg i logs/announcements.jsonl viser hvem som sendte
hva. Loggen feiler aldri forespørselen – en logg som ikke lar seg skrive
skal ikke hindre et utrop.
- Branding flyttet fra index.html til /api/config, så config.toml fra
forrige commit faktisk brukes.
- Sesjonsnøkkel i instance/secret_key, ellers logges alle ut ved hver
restart. SESSION_COOKIE_SECURE settes bare bak TLS: appen kjører på rå
HTTP over LAN og NetBird, og med Secure på ville ingen klart å logge inn.
57 tester, de fleste på auth, inkludert hele OIDC-runden mot en stubbet
leverandør. Det er delen man ikke kan se etter med øyet: at en PIN virker
ser du med en gang, at et utløpt token blir avvist ser du aldri før det
smeller.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
171 lines
8.9 KiB
Markdown
171 lines
8.9 KiB
Markdown
# announcer – utrop på høyttaleranlegget
|
||
|
||
Liten Flask-app: tekst inn i nettleseren → forhåndslytt → «Send ut på anlegget»
|
||
spiller lyden lokalt på **denne** maskinen med `pw-play`. TTS er edge-tts
|
||
(nevrale stemmer, krever nett) med Piper som lokal reserve.
|
||
|
||
Appen er generisk: tittel, undertittel, aksentfarge og hurtigfraser kommer fra
|
||
`config.toml`, ikke fra HTML-en. Den het `sg-announcer` og var skrevet for Sauda
|
||
Gathering fram til oktober 2026.
|
||
|
||
Dokumentasjon for Kent: Athena-notatet `30 Ressurser/Teknologi/Announcer.md`.
|
||
Oppdater det, ikke denne fila, når noe som er verdt å huske endres.
|
||
|
||
Filer:
|
||
|
||
| Fil | Hva |
|
||
|---|---|
|
||
| `announcer.py` | server, kø, TTS, jingler, ruter |
|
||
| `auth.py` | `Principal`, leverandørene, OIDC-rutene |
|
||
| `config.py` | `config.toml` + miljøvariabler, standardverdier |
|
||
| `index.html` | hele sida, inline CSS/JS, ingen byggesteg |
|
||
| `config.example.toml` | kommentert mal; kopier til `config.toml` |
|
||
| `docs/crew-integration.md` | kontrakten mot crew-panelet |
|
||
| `tests/test_auth.py` | `uv run pytest` |
|
||
|
||
## Kjøring
|
||
|
||
Tjenesten er en systemd-brukerenhet: `~/.config/systemd/user/announcer.service`
|
||
(enabled, port 8090). `systemctl --user restart announcer` etter endringer i
|
||
koden. Manuelt: `uv run announcer.py --port 8090`.
|
||
|
||
Ny maskin (Debian/Ubuntu/Mint): `git clone https://git.1x1.no/kent/announcer.git`
|
||
og `./install.sh` gjør alt (apt, uv, Python 3.13, stemmer, enhet, ufw). Finnes
|
||
NetBird (`wt0`) skrur det på ufw med deny incoming og åpner 22, 22022 og porten
|
||
kun på `wt0`. Kan kjøres på nytt, og rydder da bort en gammel
|
||
`sg-announcer.service` hvis den ligger der. Avspilling bruker `pw-play` når
|
||
PipeWire kjører, ellers `paplay` (`player_cmd()`), så Mint 21 med PulseAudio
|
||
virker også.
|
||
|
||
### Omdøpingen: ett punkt gjenstår
|
||
|
||
Mappa er flyttet til `~/Work/announcer`, enheten heter `announcer.service`, og
|
||
remote peker på `https://git.1x1.no/kent/announcer.git`. **Men repoet i Forgejo
|
||
heter `annuoncer`** – en skrivefeil. Rett navnet i Forgejo, så virker remote;
|
||
Forgejo legger selv inn en omdirigering fra det gamle navnet.
|
||
|
||
Flytter du mappa igjen: `.venv` har absolutte stier i `pyvenv.cfg` og i
|
||
shebangen til hvert konsollskript, så `uv sync` alene er ikke nok. Da må
|
||
`rm -rf .venv && uv sync` til, og tjenesten startes om.
|
||
|
||
|
||
## Konfigurasjon
|
||
|
||
Tre lag, siste vinner: `DEFAULTS` i `config.py` → `config.toml` →
|
||
`ANNOUNCER_*`-miljøvariabler. **Uten `config.toml` virker alt**, med de gamle
|
||
standardverdiene og uten innlogging; det er med vilje, og
|
||
`test_uten_konfig_er_alt_apent` passer på det.
|
||
|
||
`config.toml` er gitignorert. `config.example.toml` er malen, og den er
|
||
kommentert – les den framfor å gjette.
|
||
|
||
Hemmeligheter settes som miljøvariabler i enheten, ikke i `config.toml`:
|
||
`ANNOUNCER_PIN`, `ANNOUNCER_JWT_SECRET`, `ANNOUNCER_OIDC_CLIENT_SECRET`,
|
||
`ANNOUNCER_SECRET_KEY`. Hele tabellen over variabler står i `ENV` i `config.py`;
|
||
den er eneste sted en ny variabel legges til.
|
||
|
||
## Autentisering
|
||
|
||
Modellen er én datatype og én funksjon: `Principal` (hvem + roller +
|
||
rettigheter) og `require(action)` som enten gir deg den eller stopper
|
||
forespørselen. Handlingene er `view`, `preview`, `announce`, `stop`, `clear`.
|
||
|
||
Tre leverandører, prøvd i rekkefølge, alle valgfrie:
|
||
|
||
- **pin** – `X-Pin`-header, som før. `hmac.compare_digest`, ikke `==`.
|
||
Får rollen `admin` som standard, så gammelt oppsett oppfører seg som før.
|
||
Virker uten nett, derfor beholdt.
|
||
- **jwt** – `Authorization: Bearer <jwt>` fra crew-panelet. HS256 med delt
|
||
hemmelighet, eller RS256/ES256 mot panelets JWKS (PyJWT cacher nøklene).
|
||
Krever `exp`; roller leses av et konfigurerbart claim.
|
||
- **oidc** – autorisasjonskode med PKCE. `/auth/login` → panelet →
|
||
`/auth/callback`. Discovery hentes først ved første innlogging, så tjenesten
|
||
starter selv om panelet er nede.
|
||
|
||
**En leverandør er aktiv når den står i `auth.providers` *eller* når den er
|
||
ferdig konfigurert.** Derfor slår `ANNOUNCER_PIN=1234` alene fortsatt på PIN.
|
||
Er ingen aktiv, er alt åpent.
|
||
|
||
`/auth/token?t=<jwt>` er broa mens panelet mangler OIDC: panelet lenker hit med
|
||
et kortlevd token, announcer setter sesjonscookie. Se
|
||
`docs/crew-integration.md` – det er kontrakten panelet skal oppfylle.
|
||
|
||
Roller → handlinger står i `[roles]` i `config.toml`. `"*"` betyr alt.
|
||
Rettighetene slås opp på nytt per forespørsel, så en endring der slår inn uten
|
||
at noen må logge inn igjen; nye `[auth.*]`-verdier krever omstart.
|
||
|
||
401 betyr «vi vet ikke hvem du er, logg inn», 403 betyr «vi vet hvem du er, men
|
||
rollen din får ikke dette». Et gyldig token uten roller gir 403, ikke 401 – å
|
||
logge inn på nytt ville ikke hjulpet.
|
||
|
||
Sesjonsnøkkelen genereres én gang og lagres i `instance/secret_key` (0600).
|
||
Uten den logges alle ut ved hver `systemctl restart`. `SESSION_COOKIE_SECURE`
|
||
settes bare når `server.behind_tls` er sann – appen kjører på rå HTTP over LAN
|
||
og NetBird, og med Secure på ville cookien aldri blitt sendt.
|
||
|
||
## Hvordan det henger sammen
|
||
|
||
- `/api/config` er alt sida trenger for å tegne seg selv: branding, stemmer,
|
||
jingler og en `auth`-blokk med hvem du er og hva du får gjøre. Svarer alltid
|
||
200, også med feil PIN – klienten spør «hvem er jeg?», og «ikke innlogget» er
|
||
et svar, ikke en feil. Route-funksjonen heter `client_config()`; navnet
|
||
`config` er tatt av modulen.
|
||
- `/api/preview` syntetiserer og returnerer WAV til nettleseren. Ingen lyd på PC-en.
|
||
- `/api/announce` legger meldingen i én FIFO-kø; en bakgrunnstråd spiller én om
|
||
gangen med `pw-play`. `/api/stop` dreper gjeldende avspilling, `/api/clear`
|
||
tømmer køen.
|
||
- `/api/status` krever `view`. Den var åpen før, og lekket både meldingstekster
|
||
og IP-ene til dem som hadde sendt noe. IP vises nå bare for den som har
|
||
`clear`; alle andre ser navnet.
|
||
- `/` er åpen uansett, ellers kunne ingen komme til innloggingsknappen.
|
||
- Knappen «Send ut» er låst til nøyaktig den teksten/stemmen/hastigheten som
|
||
sist ble forhåndslyttet. Det er med vilje: ingen skal sende noe de ikke har hørt.
|
||
- Ferdige WAV-er bufres i `cache/` etter innholdshash. Trygt å slette.
|
||
- `audit()` skriver én JSON-linje per hendelse til `logs/announcements.jsonl`
|
||
(`announce`, `played`, `stop`, `clear`) med navn, subject, metode og IP.
|
||
Rullerer til `.jsonl.1` ved 5 MB. Den feiler aldri forespørselen – en logg
|
||
som ikke lar seg skrive skal ikke hindre et utrop.
|
||
- Jingler: de innebygde (`BUILTIN_CHIMES`) genereres i Python med `_tone`/
|
||
`_mix`/`_overlay`, ingen lydfiler. Egne filer i `chimes/` (wav/mp3/ogg/flac)
|
||
dukker opp i menyen som `file:<stem>`; ffmpeg kutter til 6 s, normaliserer
|
||
til -18 LUFS og fader ut. Mappa leses ved hver forespørsel, så nye filer
|
||
vises uten restart. Toppnivå på de innebygde ligger mellom -4 og -10 dBFS,
|
||
talen går til 0 dBFS, så jinglen skal aldri være høyere enn stemmen.
|
||
|
||
## Stemmer og motorer
|
||
|
||
`VOICES_LIST` i `announcer.py` er eneste sted en stemme legges til. To motorer:
|
||
|
||
- **edge** (`_edge`): Microsofts nevrale stemmer via `edge-tts`-pakken. Gratis,
|
||
ingen nøkkel, men krever internett og er en uoffisiell bruk av Edge sin
|
||
«les høyt»-tjeneste – kan slutte å virke uten varsel. Norsk: bare
|
||
`nb-NO-FinnNeural` og `nb-NO-PernilleNeural`. `*MultilingualNeural`-stemmene
|
||
kan lese norsk med engelsk aksent. Liste: `uv run edge-tts --list-voices`.
|
||
Leverer MP3 24 kHz; dekodes med ffmpeg til PCM i `edge_pcm()`.
|
||
- **piper** (`_piper`): lokalt, robotaktig, reserve når nettet er nede.
|
||
Modellen lastes ned ved oppstart til `voices/` (gitignored). Norsk finnes
|
||
bare som `talesyntese-medium` og `nvcc-medium` (ti talere, `speaker`-indeks).
|
||
Full liste: `https://huggingface.co/rhasspy/piper-voices/resolve/main/voices.json`.
|
||
|
||
Vil Kent ha enda bedre lyd: ElevenLabs (nøkkel, best norsk) eller OpenAI
|
||
`gpt-4o-mini-tts` er neste trinn; legg til som ny motor i `synthesize()`.
|
||
|
||
## Feller
|
||
|
||
- **ufw**: appen kjører nativt, så Docker-smutthullet gjelder ikke. Porten må
|
||
åpnes eksplisitt for LAN-et (`sudo ufw allow from 10.20.70.0/23 to any port 8090 proto tcp`).
|
||
- `pkill -f announcer.py` fra et skall som selv har `announcer.py` i
|
||
kommandolinja dreper skallet. Bruk `systemctl --user`.
|
||
- `player = Player()` står på modulnivå, så avspillingstråden starter ved
|
||
`import announcer` – også i `install.sh`, som importerer modulen for å laste
|
||
ned stemmer. Harmløst, men greit å vite.
|
||
- `tests/conftest.py` nuller ut alle `ANNOUNCER_*`-variabler før hver test.
|
||
Uten den arver testene maskinens miljø – systemd-enheten setter
|
||
`ANNOUNCER_PORT` – og man får røde tester med feilmeldinger som ikke peker
|
||
på noe galt.
|
||
- `pyproject.toml` har `[tool.uv] package = false`. Appen er løse `.py`-filer
|
||
som kjøres på plass, ikke en pakke; uten den vil `uv sync` bygge et wheel og
|
||
klage på at `announcer/__init__.py` mangler.
|
||
- Piper 1.8 bruker `SynthesisConfig(length_scale=…)`; lavere = raskere.
|
||
- Forhåndslytt svarer 502 med feilmelding hvis edge-tts feiler (ingen nett).
|
||
Køen markerer meldingen som `failed`. Bytt til en lokal reserve-stemme.
|