# 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](/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](/docs/donnees-applications).

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](/docs/donnees-applications) |

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) :

```json
{
  "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](/docs/fichiers-partages)).

### 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`) :

```json
{"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](/docs/donnees-applications), 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](/docs/donnees-applications#depuis-php-jumphp)) :

```php
$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.

```php
$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);
```
