PD-180 — Plan d'implementation¶

1. Decoupe en composants¶

C1 — Entites & Migration DDL¶

Responsabilite : schema de donnees PostgreSQL pour webhooks, intentions de livraison et tentatives.

Migration TypeORM reversible (up/down).

C2 — DTOs & Validation¶

Responsabilite : validation d'entree (Pipes NestJS), serialisation de sortie.

C3 — Service CRUD Webhooks¶

Responsabilite : logique metier CRUD, quota, machine d'etats webhook, rotation secret.

Methodes : - create(tenantId, dto) — creation + generation secret CSPRNG + stockage hash - findAll(tenantId, pagination) — liste paginee avec secret masque - findOne(tenantId, webhookId) — lecture unitaire - update(tenantId, webhookId, dto) — mise a jour attributs modifiables + revalidation - delete(tenantId, webhookId) — transition vers DELETED - rotateSecret(tenantId, webhookId) — generation nouveau secret, invalidation immediate - ping(tenantId, webhookId, userId) — creation intention de livraison webhook.ping

C4 — Service Signature HMAC¶

Responsabilite : construction payload canonique, calcul signature HMAC-SHA256.

Methodes : - buildCanonicalPayload(eventType, data) — construction objet dans l'ordre contractuel selon variante A/B/C - sign(secretSha256, timestamp, payload) — HMAC-SHA256(secretSha256, t + "." + JSON.stringify(payload)) - buildSignatureHeader(timestamp, signature) — t=<unix>,v1=<hex64>

C5 — Service SSRF¶

Responsabilite : validation URL + resolution DNS + blocage IP privees + mitigation DNS rebinding.

Methodes : - validateUrl(url) — schema https uniquement, longueur <= 2048, RFC 3986 - resolveAndValidate(url) — resolution DNS A/AAAA, validation IP contre ranges interdits - isPrivateIp(ip) — blocage 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, ::1, 169.254.0.0/16, fe80::/10, 169.254.169.254

C6 — Service de livraison¶

Responsabilite : creation intentions, envoi HTTP, gestion retry, journalisation append-only.

Methodes : - createDeliveryIntentions(eventType, eventData, sourceEventId) — trouve webhooks ACTIVE abonnes, cree intentions PENDING - executeDelivery(deliveryId) — relit secret_sha256 en DB, signe, envoie HTTP (timeout 5s, no-follow redirects), journalise tentative - scheduleRetry(deliveryId, attemptNumber) — planifie retry selon sequence contractuelle - replay(tenantId, eventId, userId) — verifie eligibilite, cree nouvelle intention avec original_event_id

C7 — Rate Limiter¶

Responsabilite : sliding window 100 intentions/min/org via Redis.

Methodes : - checkAndIncrementN(tenantId, count) — reserve N unites de quota (1 par intention), retourne { allowed: number, delayed: number }. Les intentions au-dela de la limite sont marquees pour enqueue avec delay progressif (pas de rejet, pas de perte). - getUsage(tenantId) — consultation quota courant

Implementation : Redis ZSET avec score = timestamp Unix ms, ZRANGEBYSCORE pour fenetre glissante 60s, ZCARD pour comptage. Le check est fait APRES le calcul du nombre d'intentions (N webhooks abonnes) et AVANT l'enqueue BullMQ. Les intentions excedentaires sont enqueuees avec un delay calcule pour respecter le debit (pas de 429).

C8 — Worker BullMQ¶

Responsabilite : traitement asynchrone des livraisons.

C9 — Controller REST¶

Responsabilite : endpoints API, guards, validation d'entree.

C10 — Module NestJS¶

Responsabilite : assemblage DI, registration BullMQ queue, imports.

2. Flux techniques¶

Flux A — Creation webhook¶

Client → Controller.create()
  → Guard: JWT validation + tenant extraction
  → Pipe: CreateWebhookDto validation
  → WebhooksService.create(tenantId, dto)
    → SsrfService.validateUrl(dto.target_url)
    → Verifie quota (COUNT WHERE org_id = tenantId AND status != DELETED) < 5
    → crypto.randomBytes(32) → secret brut
    → secret_sha256 = SHA-256(secret_brut)
    → INSERT webhook (status = ACTIVE)
    → Retourne secret brut UNE SEULE FOIS
  → Response 201 avec secret en clair

Flux D — Emission evenement metier¶

Module source emet EventEmitter2 event (avec tenantId dans le payload)
  → WebhookEventListener.onEvent(eventType, data, tenantId)
    → DeliveryService.createDeliveryIntentions(eventType, data, tenantId)
      → SELECT webhooks WHERE org_id = tenantId AND status = ACTIVE AND eventType IN event_types
      → N = nombre de webhooks matches
      → RateLimiterService.checkAndIncrementN(tenantId, N)
        → Retourne { allowed: M, delayed: N-M } (M <= 100 restants dans la fenetre)
      → BEGIN TRANSACTION (DB uniquement, pas BullMQ)
        → Pour chaque webhook : INSERT webhook_delivery (status = PENDING)
      → COMMIT
      → Pour chaque delivery (post-commit, pattern outbox) :
        → Si dans les M premiers : Enqueue BullMQ job "deliver" (deliveryId, delay=0)
        → Si excedentaire : Enqueue BullMQ job "deliver" (deliveryId, delay=calcule)
    → Worker recoit job "deliver"
      → DeliveryService.executeDelivery(deliveryId)
        → SELECT webhook.secret_sha256 FROM DB (relecture obligatoire)
        → SsrfService.resolveAndValidate(target_url) — DNS A/AAAA + IP check
        → SignatureService.buildCanonicalPayload(eventType, data)
        → SignatureService.sign(secret_sha256, now(), payload)
        → HTTP POST target_url (timeout 5s, maxRedirects: 0)
        → INSERT webhook_delivery_attempt (status, code, duration)
        → Si 2xx → UPDATE delivery status = DELIVERED
        → Si non-2xx/timeout/erreur → scheduleRetry(deliveryId, attemptNum)
          → Si attemptNum >= 10 → UPDATE delivery status = FAILED
          → Sinon → enqueue BullMQ "retry" avec delay selon sequence

Flux G — Rotation secret¶

Client → Controller.rotateSecret(webhookId)
  → WebhooksService.rotateSecret(tenantId, webhookId)
    → SELECT webhook WHERE id = webhookId AND org_id = tenantId
    → crypto.randomBytes(32) → nouveau secret brut
    → new_sha256 = SHA-256(nouveau_secret)
    → UPDATE webhook SET secret_sha256 = new_sha256, updated_at = NOW()
    → Les tentatives futures relisent secret_sha256 en DB → nouveau secret automatiquement
    → Retourne nouveau secret brut UNE SEULE FOIS

Flux F — Replay¶

Client → Controller.replay(eventId)  // pas de webhookId — broadcast
  → DeliveryService.replay(tenantId, eventId)
    → SELECT delivery WHERE event_id = eventId
    → Verifie : meme org, status IN (DELIVERED, FAILED), age < 30j
    → Si PENDING/IN_PROGRESS/RETRY_SCHEDULED → 409 Conflict
    → Si autre org → 403
    → Si introuvable/purge → 404
    → Cree nouvelle intention avec :
      → Nouveau event_id (crypto.randomUUID())
      → Nouveau timestamp
      → original_event_id = eventId (trace interne)
    → Emission vers webhooks ACTIVE abonnes AU MOMENT DU REPLAY

2b. Diagrammes Mermaid¶

Graphe de dependances des composants¶

graph TD
    C9[C9 — Controller REST] --> C3[C3 — Service CRUD]
    C9 --> C2[C2 — DTOs & Validation]
    C3 --> C1[C1 — Entites & Migration DDL]
    C3 --> C5[C5 — Service SSRF]
    C3 --> C4[C4 — Service Signature HMAC]
    C6[C6 — Service de livraison] --> C4
    C6 --> C5
    C6 --> C1
    C7[C7 — Rate Limiter] -.->|Redis ZSET| C6
    C8[C8 — Worker BullMQ] --> C6
    C10[C10 — Module NestJS] --> C9
    C10 --> C3
    C10 --> C6
    C10 --> C7
    C10 --> C8

    style C9 fill:#4a90d9,color:#fff
    style C3 fill:#4a90d9,color:#fff
    style C6 fill:#d94a4a,color:#fff
    style C8 fill:#d94a4a,color:#fff
    style C5 fill:#d9a54a,color:#fff
    style C4 fill:#d9a54a,color:#fff
    style C7 fill:#d9a54a,color:#fff
    style C1 fill:#5cb85c,color:#fff
    style C2 fill:#5cb85c,color:#fff
    style C10 fill:#888,color:#fff

Legende : bleu = API, rouge = traitement asynchrone, orange = services transversaux, vert = donnees, gris = assemblage.

Sequence — Emission evenement metier (Flux D)¶

sequenceDiagram
    participant Src as Module source
    participant EE as EventEmitter2
    participant Lst as WebhookEventListener
    participant DS as C6 DeliveryService
    participant RL as C7 RateLimiter
    participant DB as PostgreSQL
    participant BM as BullMQ
    participant Wk as C8 Worker
    participant SS as C5 SsrfService
    participant Sig as C4 SignatureService
    participant Ext as Endpoint partenaire

    Src->>EE: emit(eventType, data, tenantId)
    EE->>Lst: onEvent(eventType, data, tenantId)
    Lst->>DS: createDeliveryIntentions(eventType, data, tenantId)
    DS->>DB: SELECT webhooks WHERE org_id=tenantId AND ACTIVE AND event_type match
    DB-->>DS: N webhooks
    DS->>RL: checkAndIncrementN(tenantId, N)
    RL-->>DS: {allowed: M, delayed: N-M}
    DS->>DB: BEGIN TX — INSERT N webhook_deliveries (PENDING)
    DS->>DB: COMMIT
    loop Pour chaque delivery
        DS->>BM: enqueue "deliver" (delay=0 si allowed, delay=calcule si excedentaire)
    end
    BM->>Wk: job "deliver" (deliveryId)
    Wk->>DS: executeDelivery(deliveryId)
    DS->>DB: SELECT webhook.secret_sha256
    DS->>SS: resolveAndValidate(target_url)
    SS-->>DS: IP validee
    DS->>Sig: buildCanonicalPayload(eventType, data)
    Sig-->>DS: payload canonique
    DS->>Sig: sign(secret_sha256, timestamp, payload)
    Sig-->>DS: signature HMAC
    DS->>Ext: POST target_url (timeout 5s, maxRedirects:0)
    alt 2xx
        Ext-->>DS: 200 OK
        DS->>DB: INSERT attempt (SUCCESS) + UPDATE delivery DELIVERED
    else non-2xx / timeout
        Ext-->>DS: erreur
        DS->>DB: INSERT attempt (FAILED)
        alt attemptNum < 10
            DS->>BM: enqueue "retry" (delay selon sequence)
        else attemptNum >= 10
            DS->>DB: UPDATE delivery FAILED
        end
    end

Sequence — Creation webhook (Flux A)¶

sequenceDiagram
    participant Client
    participant C9 as C9 Controller
    participant C2 as C2 DTO Pipe
    participant C3 as C3 WebhooksService
    participant C5 as C5 SsrfService
    participant DB as PostgreSQL

    Client->>C9: POST /webhooks (JWT)
    C9->>C9: Guard JWT — extract tenantId
    C9->>C2: validate CreateWebhookDto
    C2-->>C9: dto valide
    C9->>C3: create(tenantId, dto)
    C3->>C5: validateUrl(dto.target_url)
    C5-->>C3: URL valide (HTTPS)
    C3->>DB: COUNT webhooks WHERE org_id=tenantId AND status!=DELETED
    DB-->>C3: count < 5
    C3->>C3: crypto.randomBytes(32) → secret brut
    C3->>C3: SHA-256(secret_brut) → secret_sha256
    C3->>DB: INSERT webhook (ACTIVE, secret_sha256)
    C3-->>C9: webhook + secret brut (UNE SEULE FOIS)
    C9-->>Client: 201 Created (secret en clair)

3. Mapping invariants → mecanismes¶

4. Mapping criteres d'acceptation → mecanismes¶

5. Mapping tests (TC-*) → mecanismes + observables¶

6. Gestion des erreurs¶

Erreurs internes (non-API)¶

7. Impacts securite¶

7.1 Surface d'attaque¶

7.2 Journalisation securite¶

• Toute tentative de livraison : URL, code HTTP, duree, resultat SSRF
• Rotation secret : timestamp, webhook_id, tenant_id (jamais la valeur)
• Blocage SSRF : IP resolue, motif, URL cible
• Acces cross-tenant : JWT sub, tenant, ressource ciblee

7.3 Dependances¶

8. Hypotheses techniques¶

9. Points de vigilance (risques, dette, pieges)¶

9.1 Race conditions¶

• Quota webhook : Deux creations concurrentes pourraient depasser le quota de 5. Mitigation : SELECT ... FOR UPDATE ou UNIQUE INDEX partiel + gestion conflit.
• Rotation secret pendant livraison : Le worker relit secret_sha256 en DB a chaque tentative. Pas de race condition car chaque tentative est atomique.

9.2 BullMQ¶

• Nommage queue : Utiliser webhook-delivery (pas de : — interdit BullMQ v5, cf. learning PD-3).
• Deprecated API : Utiliser getJobSchedulers() et removeJobScheduler() (pas getRepeatableJobs()/removeRepeatableByKey() — deprecated BullMQ v5).
• Idempotence worker : Le worker DOIT etre idempotent. Si un job est execute 2 fois (restart), la deuxieme execution ne doit pas creer de doublon de tentative.

9.3 DNS rebinding¶

• IP pinning : resoudre le DNS, valider l'IP, puis connecter directement a l'IP resolue (pas de re-resolution par Axios). Si Axios ne supporte pas IP pinning natif, utiliser http.Agent custom avec lookup override.

9.4 Performance¶

• Fanout : Un evenement declenche N intentions (1 par webhook abonne). Avec le rate limit 100/min/org, le fanout est borne a 5 webhooks × 20 evenements/min = 100 intentions/min maximum.
• Redis ZSET : La fenetre glissante ZSET necessite un ZREMRANGEBYSCORE regulier pour eviter la croissance memoire.

9.5 Observabilite (points de verification tests)¶

• Exposer les metriques : webhooks actifs par org, tentatives en cours, taux de succes/echec, latence moyenne de livraison.
• Log structure JSON pour integration avec le systeme d'audit existant (PD-31).
• Payload exact signe : la colonne signed_payload (ou log structure) sur webhook_delivery_attempts stocke le message exact <t>.<JSON.stringify(payload)> avant signature. Observable pour TC-NOM-05.
• Headers signes : la colonne signature_header stocke la valeur X-ProbatioVault-Signature envoyee. Observable pour TC-NOM-05.
• Preuve de relecture DB : chaque tentative log le timestamp de lecture secret_sha256 en DB (colonne secret_read_at ou log). Observable pour TC-SEC-02.
• SSRF validation : la colonne resolved_ip sur webhook_delivery_attempts stocke l'IP resolue. Observable pour TC-INV-15.
• Framework de test : Jest (conforme au projet backend existant ProbatioVault-backend).
• Compatibilite module : CommonJS (coherent avec le setup NestJS existant, tsconfig.json module=commonjs).

9.6 Client HTTP — configuration critique¶

• maxRedirects: 0 — indispensable (INV-05)
• timeout: 5000 — 5 secondes exactes
• validateStatus: () => true — ne pas throw sur non-2xx, gerer manuellement
• Pas de retry automatique cote Axios — le retry est gere par BullMQ

9.8 Contraintes techniques¶

• Transport tenantId : les evenements EventEmitter2 DOIVENT inclure tenantId (orgId du JWT) dans le payload. Format : { eventType, tenantId, data: { doc_id, hash, user_id, ... } }. Le listener webhook filtre par tenantId pour les requetes DB.
• Dependances inter-PD : PD-13 (NestJS init) DONE, PD-14 (TypeORM) DONE, PD-15 (schema users) DONE, PD-3 (Redis/BullMQ) DONE, PD-28 (session) DONE, PD-19 (CORS) DONE, PD-31 (audit log) DONE, PD-60 (document upload) DONE, PD-55 (worker ancrage) DONE, PD-41 (PRE) DONE.
• Variables CI : DATABASE_URL, REDIS_URL, NODE_ENV=test. Pas de variables specifiques additionnelles — les tests d'integration utilisent un PostgreSQL et Redis de test.
• Limite metadata : validation data.metadata <= 4096 bytes UTF-8 dans le DTO (class-validator @MaxLength sur JSON.stringify).

10. Hors perimetre¶

• Webhooks entrants (inbound) : pas de reception de webhooks externes.
• UI d'administration : gestion API uniquement, pas d'interface graphique.
• Filtrage avance par metadata : les abonnements filtrent par event_type uniquement.
• IP allowlist administrable : pas de restriction IP cote partenaire administrable en v1.
• DLQ visualisation UI : pas de dashboard pour les evenements en echec.
• Webhooks B2C individuels : uniquement organisationnels (B2B).
• Transformation de payload : payload envoye tel quel, pas de mapping custom.
• Evenements batch/bulk : chaque evenement est traite individuellement.
• Emission des evenements source : les modules existants (documents, preuves, etc.) sont supposes emettre les evenements via EventEmitter2. Si ce n'est pas le cas, l'ajout des emetteurs est un prerequis hors perimetre PD-180 (H-01 spec).

Aucune modification d'autres modules n'est requise pour le CRUD/livraison/retry/journalisation webhook. L'integration avec les modules sources se fait par EventEmitter2 (ecoute passive).

11. Perimetre de test¶

Tous les niveaux de test sont couverts, aucune exclusion.