KO

Comptes d'application : un espace commun entre le PC, le téléphone et le navigateur

Une application publiée sur jumphp.net peut donner à ses utilisateurs un compte pour retrouver leurs données sur tous leurs appareils : un pseudo et un mot de passe, rien d'autre. Pas d'e-mail, pas de vérification, aucune donnée personnelle. Le compte garde une playlist cloud (un document JSON versionné), des fichiers de paroles (.lyr), sait quels appareils sont en ligne, et donne à ses appareils une salle du relais et une clé pour s'envoyer des fichiers entre eux. WinZik s'en sert pour envoyer les MP3 du PC vers le téléphone.

Le serveur ne garde jamais les morceaux : aucune route n'accepte un fichier audio. Les MP3 passent d'un appareil à l'autre, en direct sur le réseau local ou chiffrés à travers le relais, qui ne stocke rien.

N'importe quelle application peut aussi garder ses propres données dans le compte : un magasin clé-valeur (avec recherche de clés) et des objets entiers sérialisés (PHP serialize(), JSON…) avec leurs versions : voir Données des comptes d'application.

Chaque application a ses propres comptes : ada sur WinZik et ada sur une autre application sont deux comptes différents, et le jeton d'un appareil ne vaut que pour son application.

L'API

Base : https://jumphp.net/api/apps/<slug>/account (sur le site, pas sur l'origine des jeux). JSON en entrée et en sortie, CORS ouvert (les pages des applications et les programmes installés l'appellent), aucun cookie. Une fois connecté, chaque requête porte le jeton de l'appareil : Authorization: Bearer wzd_…. Les réponses ne sont jamais mises en cache (Cache-Control: no-store).

Requête Ce qu'elle fait
POST /signup crée le compte : {login, password, device: {name, kind}} → 201 {login, device, token, recovery}
POST /login connecte un appareil : {login, password, device: {name, kind}} → {login, device, token}
POST /recover sans le mot de passe : {login, recovery, newPassword, device?} → {login, recovery, device?, token?}
GET /me le compte : {login, createdAt, device, devices: [...], usage, limits, storage: {usage, limits}}
POST /hello présence (toutes les 60 s) → {now, device, online: [...], playlist: {version, entries}, lyrics: {count, bytes}, next}
POST /logout déconnecte cet appareil (son jeton ne vaut plus rien)
DELETE /devices/<id> déconnecte un autre appareil du compte
PUT /password {password, newPassword} : change le mot de passe et déconnecte les autres appareils
DELETE /me {password} : supprime le compte, ses appareils, sa playlist, ses paroles, ses clés et ses objets
GET /cloud/playlist {version, entries, updatedAt} + ETag: "<version>"
PUT /cloud/playlist {entries: [...]} avec If-Match: "<version lue>" → {version, entries} + ETag
GET /cloud/lyrics/<entrée> le .lyr de l'entrée (text/plain; charset=utf-8, ETag, If-None-Match → 304)
PUT /cloud/lyrics/<entrée> le corps est le texte du .lyr (UTF-8, 64 Ko au plus) → {entry, bytes, usage}
DELETE /cloud/lyrics/<entrée> supprime ce .lyr
GET /cloud/link {relay, room, key, alg, week, exp, expiresIn} : la salle et la clé du compte pour la semaine
GET /storage, /kv…, /objects… les données de l'application dans le compte : clés et objets

Un appareil : {id, name, kind, online, lastSeen, current}. kind vaut desktop, phone ou web ; name est ce que l'utilisateur voit dans la liste de ses appareils (« PC salon », 40 caractères au plus). online : vu il y a moins de 150 s.

Pseudo, mot de passe, code de secours

  • Pseudo : 3 à 32 lettres, chiffres, ., - ou _, commençant par une lettre ou un chiffre. Une adresse e-mail ou un numéro de téléphone est refusé (pas de donnée personnelle). Les majuscules ne comptent pas (Ada et ada sont le même compte).
  • Mot de passe : 8 à 200 caractères, aucune autre règle. Il est haché (Argon2id ou bcrypt), jamais gardé en clair.
  • Code de secours : donné une seule fois, à la création (recovery, par exemple 7K3M-Q9TD-…, 20 caractères). C'est le seul moyen de revenir sans le mot de passe, puisqu'il n'y a pas d'e-mail : l'application doit dire à l'utilisateur de le noter. POST /recover le prend (majuscules, tirets et espaces au choix), pose le nouveau mot de passe, déconnecte tous les appareils et donne un nouveau code (l'ancien ne marche plus).

La playlist cloud et If-Match

Le document a une version qui monte à chaque écriture. Un appareil écrit en disant la version qu'il a lue : si un autre appareil a écrit entre-temps, l'écriture est refusée et rien n'est perdu.

  1. GET /cloud/playlist → {version: 4, entries: [...]} et ETag: "4" (version 0 : pas encore de playlist).
  2. PUT /cloud/playlist avec If-Match: "4" → 200 {version: 5, entries}.
  3. Sans If-Match : 428 {code: "precondition_required", version}. Avec une version dépassée : 412 {code: "version_conflict", version, entries} (la version actuelle) : l'appareil rejoue ses changements sur ces entrées (par id) et renvoie avec la nouvelle version. If-Match: "0" crée la playlist (412 si elle existe déjà).

Une entrée (les autres champs sont ignorés, en particulier tout contenu de fichier ou chemin local) :

{
  "id": "3f0c9a52-7d1e-4b8e-9a0f-0c1d2e3f4a5b",
  "title": "Titre", "artist": "Artiste", "duration": 201.5,
  "size": 4812345, "sha256": "64 chiffres hexadécimaux",
  "addedBy": "id de l'appareil",
  "source": {"type": "pc", "device": "id de l'appareil qui a le fichier"},
  "lyrics": true,
  "at": "2026-11-20T10:00:00Z"
}

id : 8 à 64 lettres, chiffres, - ou _ (un UUID), unique dans la liste. source vaut {"type": "pc", "device"} (le PC envoie le fichier) ou {"type": "youtube", "videoId", "query"} (l'appareil le récupère lui-même). size : 300 Mo au plus. addedBy et source.device valent l'appareil qui écrit s'ils manquent.

Les paroles

PUT /cloud/lyrics/<id de l'entrée> avec le texte du .lyr comme corps (Content-Type: text/plain). Du texte UTF-8 seulement : un fichier binaire est refusé (415). Les paroles d'un compte sont privées : seuls ses appareils les lisent (pour les partager avec tout le monde, voir les fichiers partagés).

Le lien entre les appareils

GET /cloud/link donne la même réponse à tous les appareils du compte pendant toute la semaine (ISO, lundi 00:00 UTC → exp) :

{"relay": "wss://jumphp.net/ide-relay/ws", "room": "43 caractères base64url", "key": "32 octets en base64url",
 "alg": "AES-256-GCM", "week": "2026-W47", "exp": "2026-11-23T00:00:00+00:00", "expiresIn": 270000}

Les appareils entrent dans la salle room du relais (le relais de php-wasm-network : {"t":"create","room":"<room>","max":4}, le premier la crée, les suivants la rejoignent de la même façon) et chiffrent chaque message avec key (AES-256-GCM, un nonce de 12 octets neuf par message). Le relais ne voit que du chiffré et ne garde rien. La salle et la clé sont dérivées (HMAC-SHA256) du secret du serveur, de l'application, du compte et de la semaine : elles changent chaque lundi, l'appareil redemande /cloud/link après exp. Limite honnête : la clé vient du serveur, qui pourrait donc déchiffrer ; il ne voit jamais passer les octets.

Une salle relaie 2 Go par jour au plus (UTC) ; au-delà ses messages sont jetés et l'envoyeur reçoit une fois {"t":"error","code":"quota"}. Une page web doit être servie par jumphp.net ou un de ses sous-domaines pour ouvrir le relais (un programme installé n'envoie pas d'origine et passe toujours).

Limites et erreurs

Appareils par compte 10 (une connexion de plus déconnecte celui qui n'a pas été vu depuis le plus longtemps)
Playlist 5 000 entrées, 2 Mo de JSON
Paroles 64 Ko par fichier, 5 000 fichiers, 10 Mo par compte
Connexions ratées 5 par quart d'heure pour un pseudo depuis une adresse, 50 par heure pour un pseudo
Créations de compte 5 par jour et par adresse
Requêtes d'un appareil 300 par minute
Compte inutilisé supprimé après 18 mois sans aucune requête

Les erreurs sont en JSON {error, code} : 400 bad_request / bad_login / bad_password, 401 bad_credentials (pseudo ou mot de passe faux : la réponse ne dit jamais lequel), 401 unauthorized (pas de jeton valable) ou revoked (appareil déconnecté : il faut se reconnecter), 403 (mot de passe de confirmation faux), 404 (application non publiée, appareil ou paroles inconnus), 409 login_taken, 412 version_conflict, 413 quota / too_big, 415 (paroles qui ne sont pas du texte), 428 precondition_required, 429 rate_limited (avec Retry-After et retryAfter en secondes).

Ce que le serveur garde

Le pseudo, les empreintes du mot de passe et du code de secours, pour chaque appareil son nom, son type, l'empreinte SHA-256 de son jeton et ses dates (création, dernière requête, déconnexion), la playlist (titres, artistes, durées, tailles, empreintes), les fichiers de paroles, et ce que l'application elle-même range dans le compte (clés et objets, avec leurs versions). Aucune adresse e-mail, aucune adresse IP enregistrée avec le compte, aucun fichier audio. Un appareil déconnecté est oublié au bout d'un mois, un compte inutilisé au bout de 18 mois (bin/console app:accounts:purge, une fois par jour), et DELETE /me efface tout de suite.

Depuis PHP (JumPHP)

Le plus simple : JumPHP\Platform\AppAccount (dans le moteur) fait la connexion, la déconnexion, les appareils, la présence, les clés et les objets, sans jamais bloquer, et garde le jeton dans var/ (exemples) :

$account = \JumPHP\Platform\AppAccount::for($this->engine, 'mon-app');
$account->signUp($pseudo, $motDePasse)->then(fn (array $r) => $this->recovery = $r['recovery']);   // à montrer une fois
$account->hello()->then(fn (array $h) => $this->online = $h['online']);                              // toutes les 60 s

À la main, avec JumPHP\Http : jamais bloquant, la réponse arrive à une image suivante.

$base = 'https://jumphp.net/api/apps/mon-app/account';
$this->engine->http()->post("$base/login", ['login' => $pseudo, 'password' => $motDePasse,
    'device' => ['name' => 'PC salon', 'kind' => 'desktop']])
    ->then(function (HttpResponse $r) {
        $this->token = $r->ok() ? $r->json()['token'] : null;      // à garder dans les réglages de l'application
    });

// toutes les 60 s
$this->engine->http()->post("$base/hello", [], ['Authorization' => "Bearer $this->token"])
    ->then(fn (HttpResponse $r) => $r->ok() && $r->json()['playlist']['version'] !== $this->version ? $this->reload() : null);