winzik/docs/platform-account.md
David Nurdin 2e57cbfab2 Moteur : JumPHP\Platform\AppAccount, le client des comptes jumphp.net pour toute application (connexion, clé-valeur, objets versionnés)
- signUp / signIn / recover / signOut / me / devices / revokeDevice / hello / changePassword / deleteAccount ; jeton dans var/
  (jumphp-account.json), oublié sur un 401 (onSignedOut).
- Clé-valeur : get / value / set (If-Match) / setText / delete / search (préfixe, motif, curseur, valeurs) / getMany ; un conflit
  412 échoue avec AppAccountError::isConflict() et data['current'].
- Objets : put / getObject (?version, SHA-256 vérifié) / versions / objects / deleteObject ; store() sérialise un objet PHP,
  load() le relit avec allowed_classes obligatoire (une classe hors liste, même au fond, est refusée), AppAccount::unserialize().
- Jamais bloquant (Tasks par $engine->http()), bureau, navigateur et Android ; AppAccount::for($engine) (platform_url,
  JUMPHP_PLATFORM_URL).
- Tests engine/tests/Platform/AppAccountTest.php (faux serveur), docs/platform-account.md, AGENTS.md §1 et §9.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01JkYTqrBXzYFUXiSrqYBdP3
2026-11-20 14:29:28 +01:00

136 lines
8.6 KiB
Markdown

# Comptes et données des utilisateurs : `JumPHP\Platform\AppAccount`
Une application JumPHP publiée sur [jumphp.net](https://jumphp.net) peut donner à ses utilisateurs **un compte** (pseudo + mot de passe,
pas d'e-mail) et **garder leurs données sur le serveur** pour les retrouver sur le PC, le téléphone et le navigateur, sans écrire de
serveur à soi. `JumPHP\Platform\AppAccount` est le client PHP de cette « API plateforme » :
- **connexion** : `signUp()`, `signIn()`, `recover()` (code de secours), `signOut()`, `me()`, `devices()`, `revokeDevice()`,
`hello()` (présence), `changePassword()`, `deleteAccount()` ;
- **clé-valeur** : `get()`, `value()`, `set()`, `setText()`, `delete()`, `search()` (préfixe, motif `*` `?`, curseur), `getMany()` ;
- **objets entiers versionnés** : `put()`, `getObject()`, `versions()`, `objects()`, `deleteObject()`, et `store()` / `load()` qui
sérialisent un objet PHP et le relisent **sans danger** (seulement les classes que vous nommez).
Les mêmes appels marchent sur le bureau, dans le navigateur et sur Android. Ils **ne bloquent jamais** : chacun rend une
`JumPHP\Async\Task` réglée à une image suivante (par `$engine->http()`). Le serveur, ses limites et ses codes d'erreur :
[Comptes d'application](https://jumphp.net/docs/comptes-applications) et
[Données des comptes d'application](https://jumphp.net/docs/donnees-applications).
## Démarrer
```php
use JumPHP\Platform\AppAccount;
use JumPHP\Platform\AppAccountError;
$this->account = AppAccount::for($this->engine); // l'application (project.yaml `id`) sur https://jumphp.net
// AppAccount::for($this->engine, 'mon-app') // un autre nom sur la plateforme
```
- L'adresse : `https://jumphp.net/api/apps/<slug>/account`. `project.yaml` `platform_url` ou `JUMPHP_PLATFORM_URL` (environnement ou
page) en donnent une autre (un playground local) ; `''` = pas de serveur (tests) : chaque appel échoue avec le code `disabled`.
- L'application doit être **publiée** sur jumphp.net (sinon 404).
- Le jeton de l'appareil est gardé dans `var/jumphp-account.json` (IndexedDB dans le navigateur, fichier 0600 sur le bureau) et envoyé
en `Authorization: Bearer`. Jamais le mot de passe, jamais le code de secours.
- Le type d'appareil (`desktop`, `phone`, `web`) est deviné ; le nom affiché dans la liste des appareils est « Computer », « Phone »
ou « Browser » tant que l'utilisateur n'en donne pas un (dernier argument de `signIn()` / `signUp()`).
## Se connecter
```php
$this->account->signUp($pseudo, $motDePasse, 'PC salon')->then(
fn (array $r) => $this->showRecoveryCode($r['recovery']), // à montrer UNE fois : le seul moyen de revenir sans mot de passe
fn (AppAccountError $e) => $this->error = $e->getMessage()); // $e->errorCode : login_taken, bad_login, bad_password, rate_limited...
$this->account->signIn($pseudo, $motDePasse)->then(fn () => $this->scenes()->switchTo(HomeScene::class));
$this->account->recover($pseudo, $code, $nouveauMotDePasse)->then(fn (array $r) => $this->showRecoveryCode($r['recovery']));
$this->account->signedIn(); // un jeton est là (au démarrage suivant aussi)
$this->account->signOut(); // oublié ici tout de suite, même hors ligne
$this->account->onSignedOut = fn () => $this->scenes()->switchTo(LoginScene::class); // jeton révoqué ailleurs (401)
```
Présence et appareils : `hello()` toutes les 60 s (`{online: [...], ...}`), `me()`, `devices()`, `revokeDevice($id)`.
## Clé-valeur
Une clé : 1 à 128 caractères `A-Z a-z 0-9 . _ : / -`. Une valeur : n'importe quoi que `json_encode()` écrit (64 Ko), ou du texte.
```php
$this->account->set('settings', ['volume' => 0.8, 'theme' => 'dark']);
$this->account->value('settings', [])->then(fn (array $s) => $this->apply($s));
$this->account->get('settings')->then(fn (?array $item) => $this->version = $item['version'] ?? 0); // null : pas de clé
$this->account->setText('notes/courses', "pain\nlait");
$this->account->delete('settings'); // true, false si elle n'existait pas
// chercher : préfixe, motif sur toute la clé (* = n'importe quoi, ? = un caractère), page par page
$this->account->search(prefix: 'score:', match: '*-12', limit: 50, values: true)
->then(fn (array $page) => [$this->rows, $this->next] = [$page['items'], $page['next']]);
$this->account->search(prefix: 'score:', cursor: $this->next); // la page suivante (next null : c'était la dernière)
$this->account->getMany(['settings', 'save/slot1'])->then(fn (array $r) => ...); // {items, missing}
```
**Deux appareils, une clé** : écrivez avec la version lue (`$ifMatch`). Si un autre appareil a écrit entre-temps, la tâche échoue avec
`AppAccountError::isConflict()` et `$e->data['current']` (la valeur actuelle et sa version) : fusionnez et réécrivez.
```php
$this->account->set('progress', $merged, $this->version)->then(
fn (array $r) => $this->version = $r['version'],
function (AppAccountError $e) use ($merged): void {
if ($e->isConflict()) {
$current = $e->data['current'];
$this->account->set('progress', $this->merge($current['value'] ?? [], $merged), $current['version']);
}
});
```
`$ifMatch = 0` : seulement si la clé n'existe pas encore ; `null` (par défaut) : la dernière écriture gagne.
## Objets PHP entiers, versionnés
```php
$this->account->store('save', $this->game, keep: 10)->then(fn (array $v) => $this->savedVersion = $v['version']);
$this->account->load('save', [Game::class, Player::class, Inventory::class])
->then(fn (?Game $game) => $this->game = $game ?? new Game(), // null : rien d'enregistré
fn (AppAccountError $e) => $this->error = $e->getMessage()); // unserialize : une classe hors de la liste...
$this->account->versions('save')->then(fn (array $h) => $this->history = $h['versions']); // [{version, size, sha256, createdAt, device}]
$this->account->load('save', [Game::class, Player::class, Inventory::class], 3); // revenir à la version 3 : la relire, puis store()
```
- `store()` fait `serialize()` et envoie les octets (format `php-serialize`) ; le serveur ne les lit jamais. 2 Mo par version ; les
`keep` dernières versions sont gardées (10 par défaut, 1 à 50).
- `load()` **exige la liste des classes permises** : `unserialize($octets, ['allowed_classes' => $liste])`, jamais sans. Une classe
absente de la liste, même tout au fond de l'objet, fait échouer la tâche (`errorCode` `unserialize`, `data['class']`) au lieu de
rendre un objet à moitié fait. `[]` : des tableaux et des valeurs simples seulement. Les octets abîmés en route (SHA-256) sont
refusés aussi. `AppAccount::unserialize($octets, $classes)` fait la même vérification pour vos propres octets.
- Ne stockez que des données : pas de fermeture (`Closure`), de ressource, de texture SDL ni de scène ; un modèle à vous (`Game`,
`Player`) avec des propriétés simples. Pour du JSON, un format à vous ou des octets : `put($nom, $octets, 'json')` / `getObject()`.
## Les erreurs
Toute tâche échoue avec un `AppAccountError` : `getMessage()` (le message du serveur, en anglais : traduisez à partir du code),
`errorCode`, `status` (HTTP, 0 sans réponse), `data` (le reste de la réponse). Codes : ceux du serveur (`bad_credentials`, `login_taken`,
`bad_login`, `bad_password`, `revoked`, `unauthorized`, `not_found`, `version_not_found`, `version_conflict`, `quota`, `too_big`,
`rate_limited` avec `data['retryAfter']`, `bad_key`, `bad_request`, `unsupported_type`), et ceux du client : `network` (pas de réponse),
`disabled` (pas de serveur), `signed_out` (pas de jeton : rien n'est envoyé), `unserialize`, `damaged`.
Un 401 autre que `bad_credentials` (appareil déconnecté ailleurs, compte supprimé) oublie le jeton et appelle `onSignedOut`.
## Tester sans réseau
Le constructeur prend la fonction qui fait les requêtes : un faux serveur suffit.
```php
$account = new AppAccount(function (string $method, string $url, ?string $body, array $headers, float $timeout): Task {
$task = new Task();
$task->settle(new HttpResponse(200, '{"login":"ada","token":"wzd_test","device":{"id":"a1b2c3d4e5f6"}}'));
return $task;
}, 'https://jumphp.test/api/apps/mon-app/account', new Storage($dossierTemporaire));
```
Exemples : `engine/tests/Platform/AppAccountTest.php`.
## Pour le propriétaire
Le serveur MCP du playground donne au propriétaire de l'application (à lui seul) les outils `app_accounts_stats`, `list_app_accounts`,
`get_app_account_data` et `delete_app_account` : combien de comptes, leurs pseudos, ce que pèsent leurs données, le contenu d'un compte
pour déboguer, la suppression d'un compte. Jamais un mot de passe ni un jeton.