SPB Git

Repository Public

IOS_AUTHENTICATION.md 6.4 KB

# 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éclare webcredentials:vquant.spboucher.ai (Associated Domains) et le serveur publie /.well-known/apple-app-site-association avec 3YM54G49SN.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 pas applinks : un lien d'invitation touché dans Safari ouvre le site, pas l'app ; il faut le coller.
  • Personnes : celles de ACCESS_USERS sur 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).

Files main
Menu

Theme