kent/announcer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
announcer/AGENTS.md
Kent d6eb811ee5 Pluggbar autentisering: PIN, JWT og OIDC 
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>
2026-10-08 15:43:35 +02:00

8.9 KiB
Raw Blame History

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.