PD-172 — Plan d'implémentation¶

0. Préambule — Cadrage et décisions structurantes¶

Stack cible (réf. spec §10.1) : TypeScript / NestJS / ioredis@5.x. Le backend dispose déjà :

• d'un GlobalRateLimitMiddleware (PD-19, IP-only, fail-open silencieux) — src/common/middleware/global-rate-limit.middleware.ts
• d'un RateLimitService couplé au module auth (PD-23/24/32) — src/modules/auth/services/rate-limit.service.ts
• d'un rate-limit.config.ts mono-clé (global.max=100) — src/config/rate-limit.config.ts

PD-172 remplace ces trois éléments par un module dédié RateLimitModule global, multi-dimensions, multi-fenêtres, atomique, observable et conforme RGPD. La migration des appelants existants (PD-19/23/24/32) est in scope (re-routage, suppression du middleware obsolète, conservation de la compat header Retry-After).

Décisions tranchées dans la spec V2 (corrige tous les bloquants V1) :

1. Découpage en composants¶

Hiérarchie de dossiers cible :

src/modules/rate-limit/
├─ config/
│   ├─ rate-limit.config.ts
│   └─ rate-limit.config.schema.ts
├─ profiles/
│   ├─ route-profile.resolver.ts
│   ├─ route-profile.table.ts
│   └─ route-profile.types.ts
├─ normalizer/
│   └─ identifier-normalizer.ts
├─ redis/
│   ├─ lua/rate_limit_v1.lua
│   ├─ lua-script-manager.ts
│   └─ redis-atomic-evaluator.ts
├─ health/
│   ├─ circuit-breaker.ts
│   ├─ health-probe.scheduler.ts
│   └─ system-state.ts
├─ services/
│   ├─ rate-limit.service.ts
│   └─ rate-limit.types.ts
├─ guards/
│   └─ rate-limit.guard.ts
├─ observability/
│   ├─ rate-limit.logger.ts
│   └─ rate-limit.metrics.ts
├─ rate-limit.module.ts
└─ __tests__/
    ├─ unit/
    └─ integration/

2. Flux techniques¶

2.1 Flux nominal (decision pipeline)¶

1. RateLimitGuard.canActivate(ExecutionContext) est invoqué par NestJS avant tout handler (registre APP_GUARD global).
2. Extraction du contexte : route_template = request.route.path (ex. /api/v1/users/:id), ip = request.ip (Express trust proxy), user_sub = request.user?.sub ?? 'anonymous', tenant = request.user?.tenant ?? 'public'.
3. Validation route contre regex ^/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{1,255}$. Si KO → 400 ERR-172-03 + log decision_state=REJECTED_INVALID_CONTEXT.
4. RouteProfileResolver.resolve(route_template) → { route_profile, route_family, burst, sustained, dimensions }.
5. IdentifierNormalizer.normalize(...) calcule pour chaque dimension identifier_raw → identifier_hmac et route_key. Construit la liste de 9 clés Redis (4 dim × 2 fenêtres + 1 tenant global).
6. Vérif CircuitBreaker.state :
7. CLOSED → appel RedisAtomicEvaluator.evaluate(keys, args) (timeout 50 ms).
8. OPEN → appliquer la matrice fail-open/fail-closed sans appel Redis.
9. RedisAtomicEvaluator appelle redisClient.evalsha(SHA, 9, ...keys, ...args). Si NOSCRIPT → LuaScriptManager.reload() puis retry une fois.
10. Lua retourne [decision, remaining_min, retry_after, limiting_window_kind] :
11. decision=0 → ALLOWED : ajouter headers X-RateLimit-Limit/Remaining, next().
12. decision=1 → THROTTLED : 429 + headers + Retry-After ; pas d'appel handler (INV-172-02).
13. Si timeout / conn error / system_state=DEGRADED :
14. route_family=read → BYPASS_DEGRADED : next() métier exécuté + métrique decisions_total{decision="bypass_degraded"}. Compteur in-process local (token bucket par instance, plafond burst.max × 2 sur 60s) pour limiter le réplay-mode-dégradé (mitige R-08, H-05).
15. route_family ∈ {auth, costly} → DENIED_DEGRADED : 503 + Retry-After=retry_after_fail_closed_seconds (1s).
16. RateLimitObservability.record(decision, context) est appelé dans un finally async (INV-172-03 garanti même si exception aval).

2.2 Flux de boot¶

1. RateLimitModule.onModuleInit() :
2. Charge config via Zod → ERR-172-05 au démarrage si KO.
3. Charge HMAC secret depuis ConfigService.get('rateLimit.hmacSecret') (Vault kv/app/rate-limit-hmac-secret). Pas de fallback.
4. RouteProfileResolver valide qu'aucune route NestJS exposée n'est sans profil (introspection via Reflector + DiscoveryModule). Si une route est trouvée sans profil → ERR-172-05 au boot (mitige H-172-02 / R-03).
5. LuaScriptManager.load() → SCRIPT LOAD + cache du SHA.
6. HealthProbeScheduler.start() (intervalle 10s).
7. Vérif Redis CONFIG GET maxmemory ≥ redis_memory_budget_mb_db2 × 1024 × 1024 (ou warn si la DB n'est pas isolée par Redis ACL).

2.3 Flux dégradation / récupération (état système)¶

1. HealthProbeScheduler exécute PING + INFO memory toutes les 10s.
2. Si KO → system_state passe à DEGRADED ; CircuitBreaker.open(). Notification métriques system_state_changes_total{from,to}.
3. Première sonde OK → RECOVERING.
4. degraded_clearing_cycles=3 sondes consécutives OK → HEALTHY ; CircuitBreaker.close().
5. Échec en RECOVERING → retour DEGRADED, compteur de cycles réinitialisé.

2bis. Diagramme de dépendances agents (step 6b)¶

graph LR
    %% Wave 1 — fondation, parallélisable
    subgraph "Wave 1 — Fondation"
        A[agent-A: Config + RouteProfileResolver]
        B[agent-B: IdentifierNormalizer + LuaScriptManager]
    end

    %% Wave 2 — infra Redis et santé
    subgraph "Wave 2 — Infra Redis + Health"
        C[agent-C: RedisAtomicEvaluator + CircuitBreaker + HealthProbe]
    end

    %% Wave 3 — service orchestrateur
    subgraph "Wave 3 — Orchestrateur"
        D[agent-D: RateLimitService]
    end

    %% Wave 4 — intégration HTTP et observabilité
    subgraph "Wave 4 — Intégration + Observabilité"
        E[agent-E: RateLimitGuard + Observability]
    end

    %% Wave 5 — wiring + migration legacy
    subgraph "Wave 5 — Module + Migration"
        F[agent-F: RateLimitModule + Migration PD-19/23/24/32]
    end

    %% Wave 6 — tests
    subgraph "Wave 6 — Tests"
        G[agent-G: Tests integration + perf + sécurité]
    end

    A --> C
    B --> C
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    A --> F
    F --> G

Ordonnancement : 6 vagues d'exécution. Vague 1 parallélisable (A et B indépendants). Vague 6 (tests) après le merge complet pour valider la chaîne de bout en bout.

2.4 Couverture de la machine d'états (§5.4)¶

Aucune transition non listée n'est implémentée (INV-172-06). Les états sont des terminaux retournés par RateLimitService ; aucune méthode n'autorise un changement d'état post-décision.

3. Mapping invariants → mécanismes¶

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

Anti-énumération (R-05) : tous les 400 retournent un body identique {"error":"invalid_context"}. Le détail (route_invalid vs ip_unresolved vs dimension_invalid) reste exclusivement dans les logs internes et les métriques (label cause), jamais dans la réponse client.

Anti-catch-absorb (learnings universal §Anti-catch-absorb 2026-03-08) : RateLimitObservability.record() est appelé dans un finally synchronisé, jamais dans un .catch(...) qui absorberait l'échec d'observabilité. Si l'émission métrique throw, l'erreur est propagée — INV-172-03 = fail-closed sur l'observabilité.

7. Impacts sécurité¶

7.1 Risques identifiés (réf. review §6) et mitigations plan¶

7.2 Conformité¶

7.3 Secret HMAC¶

• Source unique : Vault kv/app/rate-limit-hmac-secret
• Format : 32 bytes random hex (256 bits)
• Rotation : possible mais nécessite redémarrage coordonné — invalide tous les compteurs (acceptable, fenêtres ≤ 60s). Documenté en runbook ops.
• Aucune valeur par défaut — boot refusé si absent.

7.4 Logs sensibles (INV-172-12)¶

• Canal application (Loki retention 30j) : pas de client_ip_raw
• Canal security-audit (Loki retention 7j, accès SOC/SRE uniquement) : client_ip_raw présent uniquement sur événements decision_state ∈ {THROTTLED, DENIED_DEGRADED}
• Configuration retention au niveau infra (Loki rules) — hors code, documenté comme dépendance

8. Hypothèses techniques¶

9. Points de vigilance (risques, dette, pièges)¶

1. Migration legacy non triviale : la suppression du GlobalRateLimitMiddleware PD-19 (clé IP-only) doit être coordonnée — pendant un déploiement rolling, les deux peuvent coexister brièvement, et le nouveau Guard peut compter ce que l'ancien middleware a déjà compté (double-throttle transitoire). Mitigation : feature flag RATE_LIMIT_V2_ENABLED=true géré par ConfigService, désactivation du middleware legacy quand le flag est ON. Le flag est temporaire (à supprimer après 2 semaines de stabilité — voir offre /schedule à la fin).

2. Réplay-mode-dégradé R-08 : le token bucket local en BYPASS_DEGRADED est une mitigation, pas une garantie. Un attaquant qui a accès à plusieurs IP peut multiplier les buckets. Documenté comme dette acceptable V1.

3. Crash post-décision pré-observabilité (R-04) : non éliminable en absolu sans WAL transactionnel. Buffer mémoire 1s = dette acceptable, documentée. Une amélioration V2 serait Kafka audit avec ack synchrone (hors périmètre).

4. Hot-reload config (INV-172-08) : NestJS ConfigModule propose un reload() — il est explicitement non câblé sur RateLimitModule. Une PR future pourrait l'introduire par erreur ; protégé par forbidden dans code-contracts.

5. Cardinalité métriques (CA-172-07, C-06 review) : le label route brut est interdit (cardinalité non bornée → explosion Prometheus). Seuls route_profile, route_family, decision_state, cause, instance_id sont labels. Documenté comme garde-fou.

6. Ordre Guard vs Middleware : si un middleware Express modifie req.user (ex: JWT decoder), il doit s'exécuter avant le Guard. Vérifié par H-PLAN-08 + tests d'intégration.

7. Lua maintenance : le script rate_limit_v1.lua est versionné (suffix _v1) et immuable. Toute modification nécessite un _v2 + migration progressive (les deux SHA coexistent transitoirement). Documenté en runbook.

8. Tenant global (route_key="__global__") : la clé spéciale est calculée dans le même Lua. Attention : tenant=public (utilisateurs anonymes mutualisés) peut exhaust le quota global rapidement. Documenté ; pas de mitigation V1 (V2 pourrait splitter public par IP).

9. Tests perf en CI partagé : la cible P99 ≤ 5ms est tenue sur env de prod-like uniquement. CI partagé = relaxation à 10ms (documenté en package.json script test:perf). Critère contractuel vérifié en pré-prod.

10. HMAC secret rotation = invalidation totale : pendant la rotation, tous les compteurs repartent à zéro (changement de clé → nouvelles clés Redis). Acceptable car fenêtres ≤ 60s ; à documenter dans le runbook ops.

10. Hors périmètre¶

10.1 Hors périmètre code (rappel spec §2)¶

• Anti-DDoS réseau / CDN / WAF (couche infra OVH/Cloudflare).
• CAPTCHA (story dédiée).
• Device fingerprinting (V2).
• Quotas billing/pricing (story PD-XX hors backend-core).
• Rate-limit BullMQ/jobs (couvert par redis-health.service, scope distinct).
• API key en dimension V1 (prévu V2 — pas de support header X-API-Key).
• Reload dynamique config (V2).
• Whitelist/bypass ops (interdit par INV-172-07).

10.2 Hors périmètre code mais dépendances infra¶

11. Périmètre de test¶

Couverture minimale attendue : 85% lignes / 80% branches sur src/modules/rate-limit/**. Aucun stub inter-PD : tout est implémentable dans cette story.

Test perimeter — exclusions justifiées contractuellement :

• Bench prod-like exhaustif : nécessite env isolé non disponible en CI ; ticket SRE séparé à ouvrir post-Gate 8.
• Pentest externe : couvert par audit annuel ProbatioVault, pas par story.
• Tests de chaos engineering (kill-9 instance pendant THROTTLED) : V2.

12. Mécanismes cross-module¶

PD-172 ajoute un Guard global (APP_GUARD = RateLimitGuard) enregistré dans RateLimitModule (importé dans app.module.ts). Ce Guard s'applique à toutes les routes de tous les modules (auth, documents, exports, proof, profile, etc.).

Point d'attention migration : les services PD-23/24/32 utilisaient RateLimitService.checkLoginLimit(email) etc. → API à conserver via méthodes wrapper sur le nouveau service ou re-câblage explicite. Décision : ré-écriture des appelants plutôt que wrapper (préserve la signature normative evaluate(context) et évite l'éparpillement). Liste des fichiers à modifier : auth.controller.ts, mfa.controller.ts, account-purge.service.ts. Tests existants ré-exécutés en non-régression.

13. Code contracts similaires (réutilisation décisions)¶

Les décisions architecturales ré-utilisées des stories antérieures :

• PD-19 (rate-limit IP global) : pattern req.ip via Express trust proxy, hash SHA256 de l'IP. PD-172 conserve la résolution via Express mais remplace SHA256 par HMAC-SHA256 pour empêcher la corrélation cross-environment.
• PD-23 (rate-limit auth) : structure {allowed, retryAfter, count} retournée par le service. PD-172 étend en RateLimitDecision = { state, remaining, retry_after, system_state, cause? }.
• PD-24 (anti-bruteforce login) : cible email (user_id-equivalent). PD-172 généralise en dimension user_id.
• PD-251 (stubs inter-PD) : aucun stub dans PD-172 (tout est implémentable).
• PD-298 (Zod allowlist stricte metadata telemetry) : appliqué au schéma RateLimitConfigSchema — z.strictObject partout, pas de Record<string, unknown>.
• Anti-catch-absorb (learnings universal 2026-03-08) : appliqué dans RateLimitObservability — record() dans finally, pas .catch().
• Anti-enumeration messages 404/400 (learnings universal 2026-03-08) : body unique {"error":"invalid_context"} pour tous les 400.
• Refined types pour UUID semantiques (learnings universal 2026-03-04) : appliqué pour IdentifierHmac, RouteKey, RedisKey (branded types TS).

14. Critères de DONE pour le step 6 (implémentation)¶

• Tous les composants C1..C13 implémentés et testés unitairement
• tsc --noEmit PASS sur ProbatioVault-backend après chaque agent step 6b
• Tests d'intégration TC-NOM-* + TC-ERR-* + TC-NEG-* + TC-NR-* PASS
• Coverage ≥ 85% lignes / 80% branches sur src/modules/rate-limit/**
• Migration legacy : GlobalRateLimitMiddleware supprimé, callers PD-23/24/32 migrés
• Bench k6 P99 ≤ 10ms en CI (≤ 5ms en pré-prod)
• formal-check.sh --story PD-172 --step 6 --scope code retourne GO ou SKIP documenté
• Sonar QG = PASS (Gate 5 ne valide pas Sonar mais préparation step 7)
• Documentation runbook ops : rotation HMAC, escalade Redis-down, alertes

Fin du plan d'implémentation PD-172.