PD-236 — Recherche backend par tokens déterministes (consommation PD-42)¶

1. Objectif¶

La présente spécification définit, de manière canonique, contractuelle et testable, le comportement attendu du backend en tant que consommateur de la primitive cryptographique définie dans PD-42.

Cette User Story couvre l’indexation, la persistance et la recherche server-side par égalité stricte sur des tokens de recherche déterministes (T_kw), sans jamais re-définir ni altérer les règles cryptographiques, de canonicalisation ou de dérivation de clés.

Le backend agit comme un système opaque vis-à-vis du sens des keywords et se limite à manipuler des tokens et métadonnées conformes à PD-42.

Aucune implémentation logicielle n’est décrite dans ce document.

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

2.1 Inclus¶

• Réception de tokens T_kw et métadonnées conformes à PD-42.
• Persistance backend des couples (T_kw, resource_id, métadonnées).
• Recherche server-side par égalité stricte de T_kw.
• Validation de conformité des métadonnées (algorithm_id, canonicalization_id, k_search_scope).
• Gestion des erreurs contractuelles backend.
• Observabilité et auditabilité des opérations.

2.2 Hors périmètre¶

• Génération, canonicalisation ou tokenisation des keywords (réservé à PD-42).
• Accès, stockage ou interprétation de keywords en clair.
• Recherche plein texte, floue, partielle, sémantique ou par similarité.
• Scoring, ranking ou pondération des résultats.
• Protection contre les attaques par analyse de fréquence ou dictionnaire.

Ce risque est explicitement accepté : l’exposition potentielle aux attaques par analyse de fréquence/dictionnaire ne constitue pas une non-conformité contractuelle au titre de PD-236.

Les éléments hors périmètre sont explicitement non testables dans le cadre de la présente spécification.

3. Définitions¶

• T_kw : token de recherche déterministe produit conformément à PD-42, au format défini par l’algorithm_id déclaré (cf. PD-42 §4.3 ; pour DET-HMAC-SHA256-B64T22-V1 : Base64 RFC 4648 URL-safe sans padding, longueur 22).
• Métadonnées PD-42 : ensemble {algorithm_id, canonicalization_id, k_search_scope}.
• index_id : identifiant logique de l’index backend.
• M_I : métadonnées PD-42 de référence d’un index I, fixées à l’initialisation.
• Index backend : structure logique associant des T_kw à des resource_id pour un index_id donné, conforme à M_I.
• Recherche backend : opération de sélection de resource_id par égalité stricte sur T_kw.
• Keyword en clair : valeur textuelle non tokenisée fournie au backend via un champ explicitement qualifié de keyword dans le contrat d’API.
• Client conforme PD-42 : composant amont respectant intégralement PD-42.

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.0 Index et métadonnées de référence¶

• Chaque index backend est identifié par un index_id.
• Les métadonnées de référence M_I sont fixées à la création de l’index ou lors de la première indexation acceptée.
• M_I est immuable pour la durée de vie de l’index ; tout changement relève d’une migration hors périmètre.
• Toute requête d’indexation ou de recherche doit fournir des métadonnées M_req strictement identiques à M_I (égalité champ-à-champ), sinon ERR-BE-04.

5.1 Indexation backend¶

• Le backend reçoit un ensemble de couples (T_kw, resource_id) accompagnés des métadonnées PD-42.
• Le backend vérifie la présence des métadonnées et leur conformité à M_I.
• Le backend vérifie la conformité du format de T_kw selon PD-42 et l’algorithm_id déclaré.
• Le backend persiste uniquement T_kw, resource_id et métadonnées.
• Aucune transformation de T_kw n’est effectuée.

5.2 Recherche backend¶

• Le backend reçoit une requête contenant un T_kw et ses métadonnées.
• Le backend valide la cohérence des métadonnées avec M_I.
• Le backend vérifie la conformité du format de T_kw selon PD-42 et l’algorithm_id déclaré.
• Le backend effectue une recherche par égalité stricte sur T_kw.
• Le backend retourne l’ensemble (non ordonné) des resource_id associés.

5bis. Diagrammes¶

5bis.1 Diagramme de séquence — Indexation backend (§5.1)¶

sequenceDiagram
    participant C as Client conforme PD-42
    participant B as Backend PD-236
    participant DB as Persistence

    C->>B: POST /index {T_kw[], resource_id, metadata PD-42}
    activate B

    B->>B: Vérifier présence T_kw (sinon ERR-BE-01)
    B->>B: Vérifier format T_kw vs algorithm_id (sinon ERR-BE-02)
    B->>B: Vérifier présence métadonnées (sinon ERR-BE-03)

    alt Index existant (M_I défini)
        B->>B: Comparer M_req vs M_I champ-à-champ
        Note right of B: INV-03 — métadonnées identiques<br/>pour toutes les entrées
        B-->>C: ERR-BE-04 si mismatch
    else Première indexation (M_I non défini)
        B->>DB: Fixer M_I = M_req (immuable)
        Note right of DB: M_I figé pour la durée<br/>de vie de l’index
    end

    B->>B: Vérifier absence keyword clair (sinon ERR-BE-05 + audit)
    Note right of B: INV-01 — jamais de keyword en clair

    B->>DB: Persister (T_kw, resource_id, métadonnées)
    Note right of DB: Aucune transformation de T_kw<br/>INV-02 — égalité stricte préservée
    DB-->>B: OK

    B-->>C: 200 OK
    deactivate B

5bis.2 Diagramme de séquence — Recherche backend (§5.2)¶

sequenceDiagram
    participant C as Client conforme PD-42
    participant B as Backend PD-236
    participant DB as Persistence

    C->>B: GET /search {T_kw, metadata PD-42}
    activate B

    B->>B: Vérifier présence T_kw (sinon ERR-BE-01)
    B->>B: Vérifier format T_kw vs algorithm_id (sinon ERR-BE-02)
    B->>B: Vérifier présence métadonnées (sinon ERR-BE-03)
    B->>B: Comparer M_req vs M_I champ-à-champ (sinon ERR-BE-04)
    Note right of B: INV-03 — cohérence métadonnées<br/>INV-04 — rejet explicite si mismatch

    B->>DB: SELECT resource_id WHERE T_kw = ? (égalité stricte)
    Note right of DB: INV-02 — recherche par<br/>égalité stricte uniquement
    DB-->>B: {resource_id[]}

    B-->>C: 200 {resource_id[]} (ensemble non ordonné)
    deactivate B

5bis.3 Diagramme d’états — Cycle de vie d’un index backend (§5.0)¶

stateDiagram-v2
    [*] --> CREATED : Création index_id

    CREATED --> INITIALIZED : Première indexation acceptée<br/>(M_I fixé, immuable)
    Note right of INITIALIZED : INV-03 — M_I identique<br/>pour toutes les entrées

    INITIALIZED --> INITIALIZED : Indexation conforme (M_req == M_I)
    INITIALIZED --> INITIALIZED : Recherche conforme (M_req == M_I)

    INITIALIZED --> REJECTED : Mismatch M_req ≠ M_I
    Note right of REJECTED : INV-04 — rejet explicite<br/>ERR-BE-04

    REJECTED --> INITIALIZED : Nouvelle requête conforme

    INITIALIZED --> [*] : Migration/purge (hors périmètre §10)

6. Cas d’erreur¶

Tout rejet explicite : - inclut un code d’erreur ERR-BE-xx et une raison contractuelle, - n’entraîne aucun effet de bord (aucune persistance/modification d’état), - pour ERR-BE-05, déclenche un événement d’audit.

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

Les scénarios de test sont définis dans PD-236-tests.md et couvrent l’ensemble des invariants et critères d’acceptation testables ; INV-05 est un principe non testable a priori.

9. Hypothèses explicites¶

10. Points à clarifier¶

• Politique de migration des index en cas d’évolution de PD-42.
• Mapping protocolaire des codes ERR-BE-xx (HTTP/GRPC, format de réponse).
• Stratégie de purge ou de reconstruction d’index.

Références¶

• Epic : PD-186 BACKEND CORE
• Dépendance normative : PD-42 — Recherche déterministe chiffrée
• Repos concernés : backend