Pour les développeurs

Contrat d'appairage

Une application est compatible avec CastCat dès qu'elle propose ces trois points d'accès. CastCat affiche ensuite simplement la page que vous lui indiquez dans une WebView plein écran : le contenu, la mise en page et les réglages sont entièrement les vôtres.

1. Demander un code

POST {service}/ecran/appairage        (sans authentification)

201 { "code": "K7PM-2QXA",
      "pairingSecret": "48 caractères hexadécimaux, connus de la télé seule",
      "pairUrl": "https://service.exemple/…/appairer?code=K7PM2QXA",
      "expiresAt": "2026-11-08T21:43:49+00:00",
      "pollSeconds": 3 }
429 { "error": "…" }    trop de demandes

La télé affiche pairUrl en QR code et code en grand. pairUrl mène à une page de votre application, protégée par votre connexion habituelle, où l'utilisateur nomme l'écran et valide.

2. Attendre l'approbation

GET {service}/ecran/appairage/{pairingSecret}

200 { "status": "pending" }
200 { "status": "approved", "displayUrl": "https://service.exemple/ecran/ap/{jeton}", "screenName": "Salle" }
200 { "status": "expired" }

La télé interroge toutes les pollSeconds secondes. Le jeton n'est livré qu'une seule fois ; les appels suivants répondent expired. CastCat ne retient que le chemin de displayUrl et le recompose sur l'adresse du service, pour ne pas dépendre de ce que voit votre proxy.

3. Servir l'écran

GET {service}/ecran/ap/{jeton}

200  la page HTML à afficher
404  jeton inconnu          → CastCat repart sur l'appairage
410  écran révoqué          → CastCat repart sur l'appairage

La page se rafraîchit elle-même (CastCat ne recharge rien). En cas d'erreur réseau, CastCat affiche son propre écran « Pas de réseau » puis réessaie toutes les 10 secondes.

Recommandations de sécurité

Point	Pourquoi
Stocker uniquement l'empreinte (SHA-256) du jeton d'écran	Une fuite de base de données ne donne accès à aucun écran.
Un jeton par écran, révocable	Écran perdu ou déplacé : on coupe cet écran seul.
Code d'appairage court, sans 0/O/1/I/L, valable ~15 min	Lisible de loin, impossible à deviner.
Limiter les demandes de code par adresse IP	Évite le remplissage de la base par un robot.
Aperçu et réglages derrière votre connexion	Seul `/ecran/ap/{jeton}` est public.
`Cache-Control: no-store`, `Referrer-Policy: no-referrer`, `noindex`	Le jeton est dans l'adresse : elle ne doit ni être cachée ni transmise.
N'afficher que le nécessaire (prénoms, pas d'e-mails)	Un écran de salle est vu par tout le monde.

Référence

Le serveur de référence est Mon Club Facile (Symfony) : entités Screen et ScreenPairing, widgets configurables et page de réglages. La liste des services connus de l'application est dans services.json.