Waggle

Persoonlijk command-centrum voor bewaarde Mattermost-berichten.

EXPERIMENTEEL — NIET PRODUCTIEKLAAR

Waggle is een individueel experiment van een Rijksoverheid-medewerker, opengesteld als open source voor leer-, deel- en discussie-doeleinden.

Het is bekend dat dit project (nog) niet voldoet aan de vereisten en standaarden die de Rijksoverheid stelt aan productie-software, waaronder maar niet beperkt tot:

• Informatiebeveiliging: geen BIO/ISO 27001-toetsing, geen pentest, geen formele threat-model-review.
• Privacy: geen DPIA uitgevoerd; niet beoordeeld op AVG-geschiktheid. Niet geschikt voor verwerking van bijzondere of gevoelige persoonsgegevens.
• Toegankelijkheid: niet getoetst op WCAG 2.2 / EN 301 549.
• Standaarden: niet getoetst aan de NeRDS-richtlijnen of "pas-toe-of-leg-uit"-standaarden van Forum Standaardisatie.
• Beheer: geen formeel beheer, geen SLA, geen supportkanaal, geen garantie op continuïteit. Kan zonder aankondiging stoppen of breken.
• Architectuur: single-user, SQLite, lokale deploy. Geen schaalbaarheid, geen hoogbeschikbaarheid, geen audit-logging, geen rolgebaseerde toegang.

Gebruik uitsluitend op eigen risico en voor verkennende doeleinden. Bijdragen, feedback en issues zijn zeer welkom — dit is een leeromgeving.

Wat doet Waggle?

• Importeert jouw gevlaggede (saved/flagged) Mattermost-posts in een Focus-view met zes secties (Doe nu / Wacht op verzending / Nieuw / Backlog / Bubble up in de toekomst / Voltooid) plus een aparte leeslijst.
• Bij voltooien van een kaart wordt het bericht automatisch in Mattermost ge-unsaved (met retry/backoff).
• Bij externe unsave in Mattermost wordt de kaart automatisch voltooid — één mentaal model, één bron van waarheid.
• Rich preview per kaart: markdown-body, bijlagen (afbeeldingen in lightbox, bestanden als chips), author-avatar, thread-context, notities.
• Bubble-up: stel een kaart uit tot een moment in de toekomst.
• Blocked-flag: markeer dat je op iemand anders wacht.
• "Nieuw"-badge op nog-niet-bekeken kaarten, donker/licht thema, volledige toetsenbord-navigatie.

Architectuur

• Backend: Python 3.13 + FastAPI + SQLAlchemy async + Postgres (prod) / SQLite (dev default). Tokens versleuteld at rest met Fernet (HKDF-domain-separated key). Auth via signed session-cookie. Rate-limit + Origin-check als CSRF-bescherming.
• Frontend: Vue 3.5 (Composition API + <script setup>) + Vite + TypeScript + TanStack Vue Query + Vue Router. NLDD-design-system (Lit web-components + design tokens, OKLCH, dark/light).
• Sync: asyncio-loop binnen de FastAPI lifespan, concurrency-guard via asyncio.Lock. Default interval 5 min (instelbaar 1-60 min).

Dev-quickstart

# Backend
cd backend
uv sync
uv run waggle generate-secrets      # → WAGGLE_SECRET_KEY=...
# Zet de waarde in een lokaal .env-bestand naast pyproject.toml.
# Login gaat via OIDC (start Keycloak via compose.dev.yaml) of via de
# dev-only synthetic-auth fallback (WAGGLE_DEV_SYNTHETIC_AUTH=1).
uv run uvicorn waggle.main:app --reload --port 8000

# Frontend (aparte terminal)
cd frontend
npm install
npm run dev     # → http://localhost:5173

Of alles in één commando via het justfile:

just dev-backend     # backend met reload op :8000
just dev-frontend    # vite dev-server op :5173
just preview         # bouwt frontend + start backend die static serveert op :8090
just urls

Lokale dev-stack: Keycloak + Postgres

compose.dev.yaml start twee services voor lokale ontwikkeling:

• Keycloak (port 8082) - OIDC-provider met het waggle-dev-realm pre-geladen. Vervangt het externe ZAD-Keycloak voor offline-werken.
• Postgres 16 (port 5432) - dezelfde engine die op ZAD draait. De default voor lokale tests blijft SQLite; gebruik Postgres als je productie-paritair wilt testen of WAGGLE_DATABASE_URL instelt.

We werken met podman compose (zelfde compose-spec als docker, geen daemon-vereiste). docker compose werkt overigens ook.

# Start de hele stack (Keycloak + Postgres)
podman compose -f compose.dev.yaml up -d

# Of alleen Keycloak (Postgres niet nodig als je SQLite blijft gebruiken)
podman compose -f compose.dev.yaml up -d keycloak

# Default bindt Keycloak aan localhost:8082, Postgres aan localhost:5432.
# Andere host of poort? Zet KC_HOSTNAME, KC_PORT of PG_PORT als shell-env.
# De dev-realm gebruikt wildcard redirect-URIs dus extra hosts werken zonder
# realm-aanpassing; KC_HOSTNAME stuurt alleen de issuer-claim in tokens.
KC_PORT=8085 PG_PORT=15432 podman compose -f compose.dev.yaml up -d

Backend tegen Postgres draaien:

# In backend/.env
WAGGLE_DATABASE_URL=postgresql+asyncpg://waggle:waggle@localhost:5432/waggle

Alembic past het schema automatisch toe bij eerste startup (zie backend/alembic/).

Keycloak is beschikbaar zodra de healthcheck slaagt (~30-60 sec):

URL (default)	Beschrijving
http://localhost:8082/admin/master/console/	Realm-admin (admin / admin)
http://localhost:8082/realms/waggle-dev/.well-known/openid-configuration	OIDC discovery-endpoint

Testgebruikers (beide met wachtwoord welkom123):

• sam@example.com
• noor@example.com

Backend .env instellen (zie ook backend/.env.example):

WAGGLE_OIDC_ISSUER=http://localhost:8082/realms/waggle-dev
WAGGLE_OIDC_CLIENT_ID=waggle
WAGGLE_OIDC_CLIENT_SECRET=dev-not-secret
WAGGLE_PUBLIC_HOST=http://localhost:5173
WAGGLE_DEV_SYNTHETIC_AUTH=0

Verificatie nadat Keycloak opgestart is:

curl -sf http://localhost:8082/realms/waggle-dev/.well-known/openid-configuration \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['issuer']); print(d['token_endpoint'])"
# Verwacht:
# http://localhost:8082/realms/waggle-dev
# http://localhost:8082/realms/waggle-dev/protocol/openid-connect/token

Stoppen:

podman compose -f compose.dev.yaml down

Mattermost-token aansluiten

Waggle heeft een Mattermost-token nodig. Er zijn twee routes, afhankelijk van hoe jouw Mattermost-instantie is geconfigureerd.

Route A — Persoonlijke Access Token (voorkeur)

Werkt wanneer de Mattermost-beheerder persoonlijke tokens heeft ingeschakeld.

1. Log in op je Mattermost-omgeving in de browser.
2. Klik op je profielfoto linksboven en kies Profiel.
3. Open het tabblad Security (in oudere versies: Account Settings → Security).
4. Scroll naar Persoonlijke toegangstokens en klik Aanmaken.
5. Geef het token een naam (bv. Waggle) en klik Aanmaken.
6. Kopieer de getoonde Access Token (niet de Token-ID).
7. Plak het token in Waggle (Instellingen → Mattermost) en klik opslaan.

Route B — Browser-sessie-cookie

Werkt op instanties waar persoonlijke tokens uitgeschakeld zijn (o.a. de Digilab-instantie).

1. Log in op Mattermost in je browser.
2. Open de developer tools (F12 of Ctrl/⌘+Shift+I).
3. Ga naar Application (Chrome/Edge) of Storage (Firefox) → Cookies en selecteer je Mattermost-domein.
4. Zoek de cookie MMAUTHTOKEN en kopieer de waarde.
5. Plak die waarde in het Token-veld in Waggle.

De sessie-token verloopt wanneer je in Mattermost uitlogt of de sessie afloopt; je moet 'm dan opnieuw ophalen.

Tokens worden versleuteld opgeslagen (Fernet, HKDF-afgeleide key).

Tests

cd backend && uv run pytest -x -q     # backend pytest
cd frontend && npx tsc --noEmit       # frontend typecheck
cd frontend && npm run build          # frontend build

Via justfile:

just test       # backend pytest + frontend build

Preview bouwen

just preview     # bouwt frontend + start backend die static serveert op :8090

Vereist WAGGLE_SECRET_KEY in .env of environment.

Deploy

Voor ZAD-deployment (waggle.rijks.app op zad.rijksapp.nl): zie docs/deployment.md.

Licentie

Open source onder de EUPL-1.2. Zie publiccode.yml voor machine-leesbare metadata.

Ontwikkeld en onderhouden door Robbert Bos (robbert.bos@rijksoverheid.nl) — zie de disclaimer bovenaan dit bestand voor de context.