Repository Public
1<!--2VQuant iOS3File: docs/IOS_AUTHENTICATION.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Authentification — clés d'accès, Face ID / Touch ID, sessions d'appareil910> 2.0 (2026-11-20) : **protocole inchangé**. Seuls changent l'en-tête client (`vquant-ios/2.0.0 (2)`) et ce qui est11> effacé en fin de session : s'y ajoute la réplique de synchronisation (objets du compte, file d'écritures, conflits),12> scellée avec la même clé que le cache. Les tests d'authentification de 1.0 passent sans modification.1314## Principe1516Le serveur ne fait confiance qu'à une **clé d'accès WebAuthn**. Face ID / Touch ID n'authentifient jamais auprès du17serveur : ils autorisent l'appareil à utiliser la clé privée (Secure Enclave / Trousseau iCloud) et, séparément,18déverrouillent l'app en local. Il n'y a ni mot de passe, ni seconde base de comptes.1920| Couche | Mécanisme | Vérifié par |21|---|---|---|22| Identité | Clé d'accès, `AuthenticationServices` (`ASAuthorizationPlatformPublicKeyCredentialProvider`, clé de sécurité acceptée aussi) | Serveur (`@simplewebauthn/server`, vérification de l'utilisateur exigée) |23| Session | Jeton d'appareil opaque `vqn_…` (`Authorization: Bearer`), Trousseau | Serveur (empreinte SHA-256, révocable, 90 jours d'inactivité) |24| Opérations sensibles | Nouvelle assertion de clé d'accès (`/api/native/reauth/*`), valable 5 minutes | Serveur |25| Verrou de l'app | `LocalAuthentication` (`deviceOwnerAuthentication` : biométrie, puis code de l'appareil) | Appareil seulement |2627## Compatibilité avec les comptes existants2829- Partie de confiance : `vquant.spboucher.ai` (la même que le site). L'app déclare30 `webcredentials:vquant.spboucher.ai` (Associated Domains) et le serveur publie31 `/.well-known/apple-app-site-association` avec `3YM54G49SN.ai.spboucher.vquant`.32- Une clé d'accès créée sur le site et synchronisée par le Trousseau iCloud est proposée telle quelle par iOS.33- Un appareil sans clé s'enrôle avec un **lien d'invitation** à usage unique (`npm run access:invite invite <personne>`34 sur le serveur) : l'app accepte le lien collé (`/setup/<jeton>`) ou le jeton seul, crée la clé d'accès et ouvre la35 session. Le fichier d'association ne déclare pas `applinks` : un lien d'invitation touché dans Safari ouvre le site,36 pas l'app ; il faut le coller.37- Personnes : celles de `ACCESS_USERS` sur le serveur. Historique, mémoire, portefeuille et veilles sont cloisonnés38 par personne, côté serveur.3940## Cérémonies (`VQuant/Auth/PasskeyService.swift`)4142| Action | Appels | Résultat |43|---|---|---|44| Connexion | `POST /api/native/login/options` → feuille système → `POST /api/native/login/verify {response, device:{name}}` | `{token, user, device, idleDays}` |45| Enrôlement | `POST /api/native/register/options {token}` → création → `POST /api/native/register/verify {token, response, device}` | idem ; 410 si le lien a expiré ou déjà servi |46| Vérification fraîche | `POST /api/native/reauth/options` → assertion → `POST /api/native/reauth/verify {response}` | `{ok, freshForMs: 300000}` |47| Déconnexion | `POST /api/native/logout` | session révoquée côté serveur |4849Chaque requête porte `X-VQ-Client: vquant-ios/<version> (<build>)` et aucun en-tête `Origin` (le pont natif refuse50les navigateurs). Le libellé de l'appareil est construit par le serveur.5152## Stockage local5354- **Jeton de session** : Trousseau, `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`, non synchronisé, non55 restauré sur un autre appareil. « Après le premier déverrouillage » permet l'actualisation en arrière-plan.56- **Clé du cache** : 256 bits aléatoires dans le Trousseau, mêmes attributs. Le cache est en AES-256-GCM (l'heure57 d'enregistrement est authentifiée), fichiers sous Data Protection, exclus des sauvegardes.58- Aucune clé d'API, aucun secret dans le binaire. Aucun jeton dans les journaux (l'app n'en écrit pas).59- Les widgets n'ont aucun identifiant : ils lisent un instantané déposé par l'app.6061## Fin de session6263| Événement | Comportement |64|---|---|65| Déconnexion volontaire | Révocation serveur, puis effacement : jeton, clé du cache, cache, **réplique de synchronisation**, préférence de verrou, instantané des widgets, index Spotlight. L'app tente d'abord d'envoyer la file d'écritures ; ce qui n'a pas pu partir (hors ligne) est perdu. |66| 401 avec `x-vq-locked: 1` (session révoquée depuis un autre appareil, 90 jours d'inactivité, rotation de `ACCESS_KEY`) | Même effacement, retour à l'écran de connexion avec l'explication. |67| 401 sans cet en-tête (assertion refusée) | La session reste valide ; l'erreur est affichée. |68| Hors ligne au lancement | La session est conservée, non vérifiée ; l'app ouvre ses copies locales. La première requête aboutie la confirme ou la ferme. |6970## Appareils autorisés (Réglages › Clés d'accès et appareils autorisés)7172`GET /api/native/devices` : sessions d'appareil natives et clés d'accès du compte (identifiées par un `ref` opaque).73Révoquer une autre session (`DELETE /api/native/devices/:id`) ou supprimer une clé74(`DELETE /api/native/passkeys/:ref`) répond 403 `reauth_required` sans vérification récente : l'app déclenche alors75la cérémonie de vérification puis rejoue l'opération. La dernière clé ne peut pas être supprimée (409). Les sessions76du site web n'apparaissent pas : le serveur signe un témoin par personne, pas par appareil.7778## Verrou biométrique7980Activé par défaut après la première connexion (si l'appareil a au moins un code), réglable : immédiatement, 1, 5 ou8115 minutes. L'activer comme le désactiver exige de réussir la vérification. Le contenu est masqué dans le sélecteur82d'apps. Sans code configuré, le verrou est indisponible et l'app le dit.8384## Ce qui reste à valider sur un appareil physique8586Le simulateur ne permet ni cérémonie de clé d'accès réelle (domaine associé) ni Face ID matériel. Sont vérifiés par87les tests : la forme exacte des messages WebAuthn, le pont natif avec un jeton de test, le refus d'un jeton inconnu,88l'exigence de vérification fraîche, la logique du verrou. À faire sur un iPhone : connexion par clé d'accès89synchronisée, enrôlement par invitation, vérification fraîche avant révocation, verrou Face ID. Le fichier90d'association est mis en cache par le CDN d'Apple : la première connexion peut échouer quelques minutes après91l'installation (message explicite dans l'app).92