📄 SPÉCIFICATION CANONIQUE CONTRACTUELLE¶

PD-23 — Inscription utilisateur Zero-Knowledge (SRP-6a) avec validation email

📌 EPIC ➡️ PD-182 — AUTH

📌 Artefact produit ➡️ PD-23-spec.md

1. Objectif¶

Définir de manière formelle, exhaustive et testable les exigences relatives à l'inscription d'un nouvel utilisateur via un endpoint exposé par le système, incluant :

• la validation des données d'entrée ;
• la mise en place d'un mécanisme d'authentification zero-knowledge basé sur SRP-6a, sans transmission du mot de passe ;
• la création d'un compte utilisateur dans un état initial maîtrisé (validation email) ;
• la prévention anti-spam et anti-automatisation ;
• la traçabilité minimale conforme RGPD.

Cette spécification constitue une référence contractuelle. Toute implémentation doit s'y conformer strictement.

2. Périmètre / Hors périmètre¶

2.1 Périmètre¶

La présente spécification couvre exclusivement :

• l'exposition d'un endpoint d'inscription utilisateur POST /auth/register ;
• la validation syntaxique et sémantique des champs fournis ;
• la génération et la persistance des artefacts nécessaires à SRP-6a sans réception du mot de passe ;
• la création atomique d'un utilisateur dans le système ;
• la gestion des erreurs liées à l'inscription ;
• la génération d'un lien de validation email à durée de vie limitée ;
• la traçabilité minimale de l'opération d'inscription.

2.2 Hors périmètre¶

• authentification (login) et émission de session/token ;
• authentification multi-facteur (MFA) ;
• récupération ou réinitialisation de mot de passe ;
• intégration à des fournisseurs d'identité tiers ;
• politiques long-terme de rotation ou gestion des clés utilisateur (hors création) ;
• tout mécanisme impliquant la connaissance serveur du mot de passe.

3. Définitions¶

4. Invariants (non négociables)¶

1. Le mot de passe ne doit jamais être transmis au serveur, même sur TLS, sous quelque forme que ce soit.
2. Le serveur ne doit jamais être capable de restituer le mot de passe original.
3. L'inscription ne doit persister côté serveur que les artefacts strictement nécessaires à SRP-6a (salt, verifier, paramètres SRP) et des métadonnées de compte.
4. Chaque utilisateur est identifié par un email unique.
5. Les données reçues doivent être validées avant tout traitement persistant.
6. La création d'un utilisateur est atomique (succès complet ou aucun effet).
7. Toute tentative d'inscription est traçable via des événements minimisés, sans PII en clair.
8. Le comportement du système ne doit pas permettre l'énumération fiable des emails existants.
9. À l'issue de l'inscription, le compte est créé en état PENDING_VALIDATION. L'activation du compte dépend d'un flux de validation email défini dans une spécification dédiée (US Validation email, à créer). Cette spécification définit notamment l'usage d'un jeton à usage unique d'une durée de validité de 1 heure.
10. Sans validation à expiration, le compte est supprimé automatiquement avec trace minimale de purge.
11. Un mécanisme d'anti-automatisation est appliqué à l'inscription utilisateur. Ce mécanisme est défini contractuellement dans une spécification dédiée (US Anti-abus, à créer), incluant notamment :
    • des règles de rate limiting (seuils et fenêtres),
    • les conditions d'activation d'un challenge (CAPTCHA ou équivalent),
    • les codes de réponse HTTP associés,
    • la journalisation et la détection des abus.
12. Conformité RGPD : aucune PII en clair dans les logs, purge des comptes non validés et minimisation des traces.

5. Contrat d'API¶

5.1 Endpoint¶

POST /auth/register

5.2 Payload d'entrée (contractuel)¶

Le payload NE DOIT PAS contenir le mot de passe.

Champs attendus :

• email : string
• srp_salt : string (hex/base64)
• srp_verifier : string (hex/base64)
• srp_params : identifiant ou objet décrivant les paramètres SRP
• client_metadata : optionnel, sans PII

Si un champ password (ou équivalent) est présent, la requête doit être rejetée.

5.3 Réponse de succès¶

• HTTP 200
• Body générique : { "status": "OK" }

La réponse doit être indiscernable quel que soit l'état réel de l'email (anti-énumération).

6. Flux nominaux¶

6.1 Inscription nominale¶

1. Le client appelle POST /auth/register avec email + artefacts SRP.
2. Le système valide la conformité des champs.
3. Le système crée atomiquement :
4. un utilisateur en état PENDING_VALIDATION ;
5. les artefacts SRP persistés ;
6. un jeton de validation à usage unique (TTL 1h).
7. L'envoi de l'email de validation est déclenché.
8. Une réponse générique de succès est retournée.

6bis. Diagrammes¶

6bis.1 Diagramme d'états du compte utilisateur¶

Ce diagramme modélise le cycle de vie du compte depuis la requête d'inscription jusqu'à l'activation ou la purge automatique. Les transitions référencent les invariants correspondants.

stateDiagram-v2
    [*] --> PENDING_VALIDATION : POST /auth/register\n[INV-6 : création atomique]
    PENDING_VALIDATION --> ACTIVE : Validation email\n(jeton usage unique, TTL 1h)\n[INV-9]
    PENDING_VALIDATION --> PURGED : Expiration jeton (>1h)\n[INV-10 : suppression + trace minimale]
    PURGED --> [*]
    ACTIVE --> [*]

    note right of PENDING_VALIDATION
        INV-1 : mot de passe jamais transmis
        INV-3 : seuls artefacts SRP persistés
        INV-8 : anti-énumération
    end note

    note right of PURGED
        INV-12 : conformité RGPD
        Aucune PII en clair conservée
    end note

6bis.2 Diagramme de séquence — Inscription nominale¶

Ce diagramme détaille les interactions entre le client, l'API, la base de données et le service d'email lors d'une inscription réussie. Les artefacts SRP sont dérivés côté client (INV-1, INV-2) puis persistés côté serveur (INV-3) dans une transaction atomique (INV-6).

sequenceDiagram
    autonumber
    participant C as Client
    participant A as API /auth/register
    participant DB as PostgreSQL
    participant E as Email Service

    Note over C: Dérivation locale SRP-6a<br/>[INV-1 : mot de passe jamais transmis]<br/>[INV-2 : serveur ne peut restituer le mdp]
    C->>A: POST /auth/register<br/>{email, srp_salt, srp_verifier, srp_params}

    A->>A: Validation payload<br/>[INV-5 : validation avant persistance]<br/>Rejet si champ "password" présent [INV-1]

    A->>A: Anti-automatisation<br/>[INV-11 : rate limiting / CAPTCHA]

    rect rgb(230, 245, 255)
        Note over A,DB: Transaction atomique [INV-6]
        A->>DB: INSERT utilisateur (status = PENDING_VALIDATION)<br/>[INV-4 : email unique]<br/>[INV-9 : état initial PENDING_VALIDATION]
        A->>DB: INSERT artefacts SRP (salt, verifier, params)<br/>[INV-3 : seuls artefacts SRP]
        A->>DB: INSERT jeton validation (usage unique, TTL 1h)<br/>[INV-9]
    end

    A->>E: Envoi email validation (async)<br/>[INV-7 : traçabilité sans PII]

    A-->>C: HTTP 200 { "status": "OK" }<br/>[INV-8 : réponse indiscernable]

    Note over DB: Si TTL expiré → purge automatique<br/>[INV-10 : suppression + trace minimale]<br/>[INV-12 : conformité RGPD]

7. Cas d'erreur¶

7.1 Erreurs de validation¶

• email manquant ou invalide ;
• artefacts SRP manquants ou invalides ;
• présence d'un champ interdit (ex. password) ;
• dépassement des seuils de rate limiting.

Les réponses visibles côté client doivent rester compatibles avec la politique anti-énumération.

7.2 Erreurs internes¶

• échec de persistance ;
• échec de génération du jeton ;
• échec temporaire d'envoi d'email (retraitable).

8. Critères d'acceptation¶

• Le serveur ne reçoit jamais de mot de passe.
• Aucun hash de mot de passe classique n'est stocké.
• Une inscription valide crée exactement un compte PENDING_VALIDATION.
• Deux inscriptions avec le même email retournent une réponse indiscernable.
• Les comptes non validés sont automatiquement purgés après expiration.
• Les journaux ne contiennent aucune PII en clair.

9. Scénarios de test¶

Scénario 1 — Inscription valide¶

Given un email valide et des artefacts SRP valides When l'endpoint est appelé Then un compte PENDING_VALIDATION est créé

Scénario 2 — Présence d'un mot de passe¶

Given un payload contenant password When l'endpoint est appelé Then la requête est rejetée

Scénario 3 — Email déjà existant¶

Given un utilisateur existant When une nouvelle inscription est tentée Then la réponse est identique à une inscription nominale

Scénario 4 — Expiration validation¶

Given un compte non validé depuis plus d'1 heure When la tâche planifiée s'exécute Then le compte est supprimé et une trace minimale est conservée

10. Hypothèses explicites¶

• Le client sait produire les artefacts SRP-6a localement.
• Les échanges réseau sont protégés par TLS.
• Le système d'envoi d'email peut être asynchrone.

11. Points à clarifier¶

1. Format exact accepté pour l'email.
2. Politique de complexité du mot de passe côté client.
3. Paramètres SRP canoniques (groupes, hash).
4. Seuils exacts de rate limiting et CAPTCHA.
5. Politique de rétention et purge des traces.

Fin de la spécification canonique.