Appairage par code d'appareil depuis l'écran de connexion (2.16.0) — APP-4 #4

Merged
bruno merged 1 commits from appairage-android into main 2026-11-10 07:53:46 -05:00
Owner

Périmètre

APP-4 (carte fusion #157) — ShaarIt Android 2.16.0 (versionCode 47) : appairage par code d'appareil depuis l'écran de connexion, selon la conception DRACODEV-APPAIRAGE-ANDROID-v1.md (§2 flux, §3.2 côté app, §5.3, §6 phase 4). Décisions actées : D1 code d'appareil, D2 secret d'appareil réutilisant le JWT HS512, D5 pas d'expiration.

  • Écran de connexion (traduit en français au passage) : champ URL déjà présent, puis bouton principal « Se connecter avec mon compte Dracodev » → écran d'appairage (PairingScreen.kt) : demande du code au serveur choisi, user_code en grand, verification_uri, bouton « Ouvrir le navigateur » (verification_uri_complete), compte à rebours, annulation. Interrogation de /api/pairing/token dans LoginViewModel en respectant interval et slow_down (+5 s à chaque 429), abandon après 3 échecs techniques consécutifs, états d'échec propres et en français (access_denied, expired_token, expiration locale à 10 min).
  • Réception du secret shd_… : stockage via le TokenManager existant (EncryptedSharedPreferences / Keystore) avec drapeau d'origine (SecretOrigin : PAIRED / MANUAL) et nom du compte approuvant. saveApiSecret() (saisies manuelles) pose l'origine MANUAL ; clearApiSecret() efface aussi le drapeau. JwtGenerator et AuthInterceptor inchangés (diff vide sur ces deux fichiers).
  • Vérification immédiate par appel réel GET /api/v1/info (AuthRepository.completePairing) : échec → secret effacé, retour à l'écran de connexion avec message.
  • Le champ « secret manuel » reste exactement comme avant (bouton secondaire « Se connecter avec le secret API ») : l'app demeure un client Shaarli générique pour les instances tierces.
  • Désappairage dans les Paramètres : la carte compte affiche « Connecté par appairage » + le compte ; bouton « Désappairer cet appareil » = effacement local et message clair — le serveur n'expose à l'app aucun endpoint de révocation de son propre secret (vérifié dans APP-2 : seule la route web /settings/devices/{id}/revoke, session navigateur), donc aucun endpoint inventé ; la boîte de dialogue et le message de confirmation disent que la révocation se fait depuis les Réglages web (section « Appareils appairés », effet immédiat).
  • 401 persistant en vie courante : patron existant conservé (AuthInterceptor : retry unique après resynchronisation d'horloge, puis SessionManager.onUnauthorized()) ; SessionManager dépose en plus un message explicite (« Cet appareil a été désappairé ou le secret a été révoqué côté serveur… ») que l'écran de connexion affiche à l'arrivée, au lieu d'un retour muet.
  • Étiquette d'appareil envoyée à la demande : modèle + version de l'app (ex. « Pixel 8 · ShaarIt Android 2.16.0 »), aucune empreinte matérielle.
  • Version : version.properties 2.15.1 → 2.16.0, code 46 → 47 (rituel du dépôt) ; README : puce « Appairage » dans la section Authentification.

Contrat consommé (APP-2, ShaarIt 0.8.0, PR Projets/shaarit#20 — non fusionnée)

Hors /api/v1, à la racine du serveur choisi, corps et réponses relus dans src/appairage.rs de la branche appairage-shaarit-serveur :

  • POST /api/pairing/device {app: "shaarit-android", device_label} → 200 {device_code, user_code, verification_uri, verification_uri_complete, expires_in: 600, interval: 5} ; 404 traité comme « ce serveur ne propose pas l'appairage » (repli indiqué vers le secret manuel), 429 quota.
  • POST /api/pairing/token {device_code} → 428 authorization_pending (continuer), 429 slow_down (intervalle +5 s), 400 access_denied / expired_token (écrans d'échec), 200 {api_secret: "shd_…", account_name} une seule fois.

DTO Moshi dédiés (PairingDtos.kt), API Retrofit en Response<> pour lire les statuts du flux normal sans exceptions (PairingApi.kt, PairingRepositoryImpl.kt).

Preuves

  • Rejeu boîte noire du contrat, contre le serveur ShaarIt 0.8.0 compilé depuis la branche appairage-shaarit-serveur (binaire release local, base vierge, lien draco fabriqué comme dans les tests d'intégration du serveur) : un client scripté mime exactement les appels de l'app (mêmes routes, mêmes corps, JWT HS512 iat seul signé comme JwtGenerator). 32/32 vérifications réussies : forme complète de la réponse device, 428 en attente, 429 en rafale, 400 expired_token sur code inconnu, page d'approbation (app, appareil, code, compte affichés), approbation, délivrance unique du shd_… avec account_name, seconde interrogation → expired_token, GET /api/v1/info → 200 avec le secret d'appareil et avec le secret d'instance (validation duale), 401 sur mauvais secret, révocation web → secret d'appareil refusé immédiatement (401) pendant que le secret d'instance continue de passer. Script séparé pour le refus : approbation refusée → 400 access_denied. Scripts conservés hors dépôt (workspace/appairage-travail/rejeu/).
  • Relecture statique du diff complet : équilibrage accolades/parenthèses vérifié par script sur les 15 fichiers Kotlin touchés, API Compose limitées à celles du BOM 2023.08 / Material3 1.1 (pas de HorizontalDivider, absent de cette version), injections Hilt résolues (PairingApi, PairingRepository, Moshi, SessionManager tous fournis/liés).

Limites — énoncées franchement

  • Aucune compilation de l'app dans la VM de travail : ni JDK (java introuvable), ni SDK Android, ni Gradle/Kotlin. ./gradlew assembleDebug n'a donc pas tourné et aucun APK n'est prétendu construit. La preuve côté app est la relecture + le rejeu du contrat ci-dessus.
  • Reste à valider après les fusions de Bruno : APP-2 fusionnée et déployée (serveur 0.8.0), cette app installée sur un appareil réel — appairage de bout en bout sur la dev avec le compte testeur, synchronisation complète au secret d'appareil, révocation web → retour à l'écran de connexion au 401 persistant, secret d'instance toujours accepté en parallèle (matrice de la phase 4, §6 de la conception).
  • Aide du Hub : la PR Hub #5 (APP-2, branche appairage-shaarit-aide, non fusionnée) a déjà mis à jour aide/shaarit/android.md avec la voie d'appairage (bouton, code, approbation, révocation, désappairage local) — contenu relu et juste ; aucune PR Hub doublon n'est créée ici. Seule nuance : la page cite « version 2.15.1 au moment de ce guide », formulation datée mais pas fausse ; à rafraîchir lors d'une prochaine passe si souhaité.

Aucune fusion — branche et PR seulement, comme demandé.

## Périmètre APP-4 (carte fusion #157) — ShaarIt Android **2.16.0** (versionCode 47) : appairage par code d'appareil depuis l'écran de connexion, selon la conception `DRACODEV-APPAIRAGE-ANDROID-v1.md` (§2 flux, §3.2 côté app, §5.3, §6 phase 4). Décisions actées : D1 code d'appareil, D2 secret d'appareil réutilisant le JWT HS512, D5 pas d'expiration. - **Écran de connexion** (traduit en français au passage) : champ URL déjà présent, puis bouton principal **« Se connecter avec mon compte Dracodev »** → écran d'appairage (`PairingScreen.kt`) : demande du code au serveur choisi, `user_code` en grand, `verification_uri`, bouton « Ouvrir le navigateur » (`verification_uri_complete`), compte à rebours, annulation. Interrogation de `/api/pairing/token` dans `LoginViewModel` en respectant `interval` et `slow_down` (+5 s à chaque 429), abandon après 3 échecs techniques consécutifs, états d'échec propres et en français (`access_denied`, `expired_token`, expiration locale à 10 min). - **Réception du secret `shd_…`** : stockage via le `TokenManager` existant (EncryptedSharedPreferences / Keystore) **avec drapeau d'origine** (`SecretOrigin` : `PAIRED` / `MANUAL`) et nom du compte approuvant. `saveApiSecret()` (saisies manuelles) pose l'origine `MANUAL` ; `clearApiSecret()` efface aussi le drapeau. **`JwtGenerator` et `AuthInterceptor` inchangés** (diff vide sur ces deux fichiers). - **Vérification immédiate** par appel réel `GET /api/v1/info` (`AuthRepository.completePairing`) : échec → secret effacé, retour à l'écran de connexion avec message. - **Le champ « secret manuel » reste** exactement comme avant (bouton secondaire « Se connecter avec le secret API ») : l'app demeure un client Shaarli générique pour les instances tierces. - **Désappairage dans les Paramètres** : la carte compte affiche « Connecté par appairage » + le compte ; bouton « Désappairer cet appareil » = effacement local **et message clair** — le serveur n'expose à l'app aucun endpoint de révocation de son propre secret (vérifié dans APP-2 : seule la route web `/settings/devices/{id}/revoke`, session navigateur), donc **aucun endpoint inventé** ; la boîte de dialogue et le message de confirmation disent que la révocation se fait depuis les Réglages web (section « Appareils appairés », effet immédiat). - **401 persistant en vie courante** : patron existant conservé (`AuthInterceptor` : retry unique après resynchronisation d'horloge, puis `SessionManager.onUnauthorized()`) ; `SessionManager` dépose en plus un **message explicite** (« Cet appareil a été désappairé ou le secret a été révoqué côté serveur… ») que l'écran de connexion affiche à l'arrivée, au lieu d'un retour muet. - **Étiquette d'appareil** envoyée à la demande : modèle + version de l'app (ex. « Pixel 8 · ShaarIt Android 2.16.0 »), aucune empreinte matérielle. - Version : `version.properties` 2.15.1 → **2.16.0**, code 46 → **47** (rituel du dépôt) ; README : puce « Appairage » dans la section Authentification. ## Contrat consommé (APP-2, ShaarIt 0.8.0, PR Projets/shaarit#20 — non fusionnée) Hors `/api/v1`, à la racine du serveur choisi, corps et réponses relus dans `src/appairage.rs` de la branche `appairage-shaarit-serveur` : - `POST /api/pairing/device` `{app: "shaarit-android", device_label}` → 200 `{device_code, user_code, verification_uri, verification_uri_complete, expires_in: 600, interval: 5}` ; 404 traité comme « ce serveur ne propose pas l'appairage » (repli indiqué vers le secret manuel), 429 quota. - `POST /api/pairing/token` `{device_code}` → 428 `authorization_pending` (continuer), 429 `slow_down` (intervalle +5 s), 400 `access_denied` / `expired_token` (écrans d'échec), 200 `{api_secret: "shd_…", account_name}` une seule fois. DTO Moshi dédiés (`PairingDtos.kt`), API Retrofit en `Response<>` pour lire les statuts du flux normal sans exceptions (`PairingApi.kt`, `PairingRepositoryImpl.kt`). ## Preuves - **Rejeu boîte noire du contrat, contre le serveur ShaarIt 0.8.0 compilé depuis la branche `appairage-shaarit-serveur`** (binaire release local, base vierge, lien draco fabriqué comme dans les tests d'intégration du serveur) : un client scripté mime exactement les appels de l'app (mêmes routes, mêmes corps, JWT HS512 `iat` seul signé comme `JwtGenerator`). **32/32 vérifications réussies** : forme complète de la réponse `device`, 428 en attente, 429 en rafale, 400 `expired_token` sur code inconnu, page d'approbation (app, appareil, code, compte affichés), approbation, délivrance unique du `shd_…` avec `account_name`, seconde interrogation → `expired_token`, `GET /api/v1/info` → 200 avec le secret d'appareil **et** avec le secret d'instance (validation duale), 401 sur mauvais secret, révocation web → secret d'appareil refusé immédiatement (401) pendant que le secret d'instance continue de passer. Script séparé pour le refus : approbation refusée → `400 access_denied`. Scripts conservés hors dépôt (`workspace/appairage-travail/rejeu/`). - **Relecture statique** du diff complet : équilibrage accolades/parenthèses vérifié par script sur les 15 fichiers Kotlin touchés, API Compose limitées à celles du BOM 2023.08 / Material3 1.1 (pas de `HorizontalDivider`, absent de cette version), injections Hilt résolues (`PairingApi`, `PairingRepository`, `Moshi`, `SessionManager` tous fournis/liés). ## Limites — énoncées franchement - **Aucune compilation de l'app dans la VM de travail** : ni JDK (`java` introuvable), ni SDK Android, ni Gradle/Kotlin. `./gradlew assembleDebug` n'a donc **pas** tourné et **aucun APK n'est prétendu construit**. La preuve côté app est la relecture + le rejeu du contrat ci-dessus. - Reste à valider après les fusions de Bruno : APP-2 fusionnée et déployée (serveur 0.8.0), cette app installée sur un appareil réel — appairage de bout en bout sur la dev avec le compte testeur, synchronisation complète au secret d'appareil, révocation web → retour à l'écran de connexion au 401 persistant, secret d'instance toujours accepté en parallèle (matrice de la phase 4, §6 de la conception). - **Aide du Hub** : la PR Hub #5 (APP-2, branche `appairage-shaarit-aide`, non fusionnée) a déjà mis à jour `aide/shaarit/android.md` avec la voie d'appairage (bouton, code, approbation, révocation, désappairage local) — contenu relu et juste ; **aucune PR Hub doublon n'est créée** ici. Seule nuance : la page cite « version 2.15.1 au moment de ce guide », formulation datée mais pas fausse ; à rafraîchir lors d'une prochaine passe si souhaité. Aucune fusion — branche et PR seulement, comme demandé.
bruno added 1 commit 2026-11-09 11:33:51 -05:00
- Bouton « Se connecter avec mon compte Dracodev » à l'écran de connexion
  (voie principale pour une instance Dracodev) : demande de code à
  POST /api/pairing/device, écran d'attente (code en grand,
  verification_uri, bouton navigateur, compte à rebours, annulation),
  interrogation de POST /api/pairing/token en respectant interval et
  slow_down (+5 s), états d'échec propres (access_denied, expired_token).
- Secret d'appareil shd_… stocké via TokenManager (EncryptedSharedPreferences)
  avec drapeau d'origine appairé/manuel et nom du compte ; JwtGenerator et
  AuthInterceptor inchangés. Vérification immédiate par GET /api/v1/info,
  secret effacé en cas d'échec.
- Le champ « secret manuel » reste (client Shaarli générique).
- Désappairage dans les Paramètres : effacement local + message clair
  (aucun endpoint de révocation self-service côté serveur ; la révocation
  se fait depuis les Réglages web, section Appareils appairés).
- 401 persistant : SessionManager dépose un message explicite que
  l'écran de connexion affiche au retour.
- Étiquette d'appareil : modèle + version de l'app, aucune empreinte.
- Écran de connexion traduit en français ; version 2.16.0 (code 47).

Contrat consommé : celui d'APP-2 (ShaarIt 0.8.0, PR shaarit#20).
Rejeu boîte noire contre le serveur 0.8.0 compilé depuis la branche
appairage-shaarit-serveur : 32/32 + chemin du refus (voir la PR).
bruno merged commit 94b8d62cd0 into main 2026-11-10 07:53:46 -05:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Projets/Sharrit#4