Authentification — clés d'accès, Face ID / Touch ID, sessions d'appareil
2.0 (2026-11-20) : protocole inchangé. Seuls changent l'en-tête client (
vquant-ios/2.0.0 (2)) et ce qui est effacé en fin de session : s'y ajoute la réplique de synchronisation (objets du compte, file d'écritures, conflits), scellée avec la même clé que le cache. Les tests d'authentification de 1.0 passent sans modification.
Principe
Le serveur ne fait confiance qu'à une clé d'accès WebAuthn. Face ID / Touch ID n'authentifient jamais auprès du serveur : ils autorisent l'appareil à utiliser la clé privée (Secure Enclave / Trousseau iCloud) et, séparément, déverrouillent l'app en local. Il n'y a ni mot de passe, ni seconde base de comptes.
| Couche | Mécanisme | Vérifié par |
|---|---|---|
| Identité | Clé d'accès, AuthenticationServices (ASAuthorizationPlatformPublicKeyCredentialProvider, clé de sécurité acceptée aussi) |
Serveur (@simplewebauthn/server, vérification de l'utilisateur exigée) |
| Session | Jeton d'appareil opaque vqn_… (Authorization: Bearer), Trousseau |
Serveur (empreinte SHA-256, révocable, 90 jours d'inactivité) |
| Opérations sensibles | Nouvelle assertion de clé d'accès (/api/native/reauth/*), valable 5 minutes |
Serveur |
| Verrou de l'app | LocalAuthentication (deviceOwnerAuthentication : biométrie, puis code de l'appareil) |
Appareil seulement |
Compatibilité avec les comptes existants
- Partie de confiance :
vquant.spboucher.ai(la même que le site). L'app déclarewebcredentials:vquant.spboucher.ai(Associated Domains) et le serveur publie/.well-known/apple-app-site-associationavec3YM54G49SN.ai.spboucher.vquant. - Une clé d'accès créée sur le site et synchronisée par le Trousseau iCloud est proposée telle quelle par iOS.
- Un appareil sans clé s'enrôle avec un lien d'invitation à usage unique (
npm run access:invite invite <personne>sur le serveur) : l'app accepte le lien collé (/setup/<jeton>) ou le jeton seul, crée la clé d'accès et ouvre la session. Le fichier d'association ne déclare pasapplinks: un lien d'invitation touché dans Safari ouvre le site, pas l'app ; il faut le coller. - Personnes : celles de
ACCESS_USERSsur le serveur. Historique, mémoire, portefeuille et veilles sont cloisonnés par personne, côté serveur.
Cérémonies (VQuant/Auth/PasskeyService.swift)
| Action | Appels | Résultat |
|---|---|---|
| Connexion | POST /api/native/login/options → feuille système → POST /api/native/login/verify {response, device:{name}} |
{token, user, device, idleDays} |
| 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 |
| Vérification fraîche | POST /api/native/reauth/options → assertion → POST /api/native/reauth/verify {response} |
{ok, freshForMs: 300000} |
| Déconnexion | POST /api/native/logout |
session révoquée côté serveur |
Chaque requête porte X-VQ-Client: vquant-ios/<version> (<build>) et aucun en-tête Origin (le pont natif refuse
les navigateurs). Le libellé de l'appareil est construit par le serveur.
Stockage local
- Jeton de session : Trousseau,
kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, non synchronisé, non restauré sur un autre appareil. « Après le premier déverrouillage » permet l'actualisation en arrière-plan. - Clé du cache : 256 bits aléatoires dans le Trousseau, mêmes attributs. Le cache est en AES-256-GCM (l'heure d'enregistrement est authentifiée), fichiers sous Data Protection, exclus des sauvegardes.
- Aucune clé d'API, aucun secret dans le binaire. Aucun jeton dans les journaux (l'app n'en écrit pas).
- Les widgets n'ont aucun identifiant : ils lisent un instantané déposé par l'app.
Fin de session
| Événement | Comportement |
|---|---|
| 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. |
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. |
| 401 sans cet en-tête (assertion refusée) | La session reste valide ; l'erreur est affichée. |
| 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. |
Appareils autorisés (Réglages › Clés d'accès et appareils autorisés)
GET /api/native/devices : sessions d'appareil natives et clés d'accès du compte (identifiées par un ref opaque).
Révoquer une autre session (DELETE /api/native/devices/:id) ou supprimer une clé
(DELETE /api/native/passkeys/:ref) répond 403 reauth_required sans vérification récente : l'app déclenche alors
la cérémonie de vérification puis rejoue l'opération. La dernière clé ne peut pas être supprimée (409). Les sessions
du site web n'apparaissent pas : le serveur signe un témoin par personne, pas par appareil.
Verrou biométrique
Activé par défaut après la première connexion (si l'appareil a au moins un code), réglable : immédiatement, 1, 5 ou 15 minutes. L'activer comme le désactiver exige de réussir la vérification. Le contenu est masqué dans le sélecteur d'apps. Sans code configuré, le verrou est indisponible et l'app le dit.
Ce qui reste à valider sur un appareil physique
Le 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 par les tests : la forme exacte des messages WebAuthn, le pont natif avec un jeton de test, le refus d'un jeton inconnu, l'exigence de vérification fraîche, la logique du verrou. À faire sur un iPhone : connexion par clé d'accès synchronisée, enrôlement par invitation, vérification fraîche avant révocation, verrou Face ID. Le fichier d'association est mis en cache par le CDN d'Apple : la première connexion peut échouer quelques minutes après l'installation (message explicite dans l'app).