PD-278 — Agent Developer Report: dip-exception-filter (C11)¶

Agent: agent-developer Module: dip-exception-filter Date: 2026-03-01 Story: PD-278 — NF Z42-013 DIP state

1. Fichiers modifies¶

2. Implementation¶

2.1 DisseminationAuditExceptionFilter¶

Fichier : src/modules/documents/filters/dissemination-audit-exception.filter.ts

Pattern de reference : DepositAuditExceptionFilter (PD-60), adapte pour persistance synchrone (spec §5.8).

Architecture :

Exception levee par guard/service
  -> @Catch() DisseminationAuditExceptionFilter
    -> shouldAudit(status, response) — filtre les codes auditables
    -> persistAuditDenied() — QueryRunner dedie, transaction legere
      -> AuditLogService.logAsync() — persistance HSM (sync attempt + queue fallback)
    -> response.status(status).json(body) — re-throw HTTP obligatoire

Codes HTTP audites (INV-278-04) : - 401 (E-401-AUTH) — acteur non authentifie - 403 (E-403-ROLE, E-403-RLS) — role non autorise ou RLS refuse - 429 (E-429-RATE-LIMIT) — depassement debit/quota - 409 uniquement si error_code === 'E-409-RETENTION-DUE' — blocage retention

Codes exclus (double audit evite) : - 400 (validation DTO — pas un refus securite) - 409-STATE, 409-CONFLICT, 409-TEMPORAL-ORDER (audites par le service) - 422 (validation metier — pas un refus securite) - 500 (echec atomique — rollback sans audit de succes)

2.2 Mecanisme de persistance synchrone¶

Le plan C11 specifie un "QueryRunner dedie" pour garantir la persistance AVANT le retour HTTP. L'implementation utilise :

1. DataSource.createQueryRunner() — transaction dediee isolee
2. AuditLogService.logAsync() — audit avec signature HSM (synchrone si HSM disponible, queue BullMQ si indisponible)
3. queryRunner.commitTransaction() / rollbackTransaction() — transaction legere
4. queryRunner.release() dans finally — liberation garantie

Garantie : La methode persistAuditDenied() est awaited avant l'envoi de la reponse HTTP. La trace d'audit est persistee ou loguee en erreur avant que le client ne recoive la reponse.

2.3 Extraction document_id¶

Le filter extrait le document_id selon le contexte de la requete : - F2 (retour DIP→SEALED) : request.params.id (route /documents/:id/dissemination-return) - F1 (communication SEALED→DIP) : request.body.documents[0] (premier document du package, contexte d'audit) - Fallback : null si non resolvable (ex: 401 pre-parsing du body)

2.4 Extraction error_code¶

Le filter extrait le code d'erreur structure depuis exception.getResponse().error_code si present. Sinon, fallback sur un code base sur le HTTP status (ex: E-401-AUTH, E-403-ROLE, E-429-RATE-LIMIT).

3. Respect des invariants¶

4. Respect des interdits (forbidden)¶

5. Couverture des tests contractuels¶

6. Integration dans le module¶

Le filter doit etre enregistre dans DocumentsModule.providers et applique au DisseminationController via @UseFilters() :

// documents.module.ts — providers array
DisseminationAuditExceptionFilter,

// dissemination.controller.ts — class decorator
@UseFilters(DisseminationAuditExceptionFilter)
@Controller('documents')
export class DisseminationController { ... }

Note : L'enregistrement dans le module et le controller sont hors perimetre de ce module (responsabilite de agent-controller et agent-module). Le filter est pret a etre branche.

7. Dependances¶

8. Decisions architecturales¶

architectural_decisions:
  - decision: "Utiliser AuditLogService.logAsync() (awaited) dans un QueryRunner dedie"
    rationale: "La spec §5.8 exige une persistance synchrone. AuditLogService.logAsync() est la facade standard qui gere HSM signing + queue fallback. Le QueryRunner dedie fournit le scope transactionnel isole requis."
    alternatives_considered:
      - "INSERT SQL direct dans audit_log — impossible car la table requiert entry_canonical, entry_hash, hsm_signature (NOT NULL) generes par AuditSignatureService"
      - "DepositAuditService pattern (fire-and-forget) — interdit par le code contract (forbidden: logAsync pour refus securite)"
    trade_offs:
      - "AuditLogService.logAsync() peut queue en BullMQ si HSM indisponible — compromis acceptable car la tentative de persistance synchrone est faite, et la queue garantit la non-perte"

  - decision: "Filtrage selectif des codes HTTP avec Set + check specifique 409"
    rationale: "Eviter le double audit des codes deja audites par le service layer (409-STATE, 409-CONFLICT, 422, 500). Seul 409-RETENTION-DUE est un refus securite relevant au niveau filter."
    alternatives_considered:
      - "Auditer tous les 409 — creerait du double audit avec le service"
      - "Ne pas auditer 409-RETENTION-DUE — violation INV-278-04"
    trade_offs:
      - "Le check `error_code === 'E-409-RETENTION-DUE'` couple le filter au format de reponse du service — acceptable car format contractuel (spec §6)"

9. Hypotheses¶

10. Points de vigilance¶

11. Verification qualite¶

12. Matrice de couverture test → fichier¶

TC-ERR-03  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts
TC-ERR-04  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts
TC-ERR-05  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts
TC-ERR-12  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts
TC-ERR-13  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts
TC-ERR-14  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts
TC-INV-04  → src/modules/documents/filters/dissemination-audit-exception.filter.spec.ts

Note : Les fichiers de test (.spec.ts) sont dans le perimetre du module dip-tests (agent-tests). La matrice ci-dessus indique ou les tests DOIVENT etre implementes.